Re: Notes on the draft polyglot document Polyglot document

On 2010-06 -20, at 02:30, Leif Halvard Silli wrote:

> Eliot Graff, Thu, 17 Jun 2010 18:39:56 +0000:
> 
>>> 2. Suggested title:  XML/HTML "Polyglot" Documents
>> 
>> Awaiting verification from the WG. 
>> It looks like consensus points to "Polyglot Markup: HTML-compatible 
>> XHTML Documents." Will make that change once I verify consensus.
> 
> As the draft now stands, the title says "Polyglot Markup". And then, 
> the next time the word "polyglot" occurs (in the Abstract) – and 
> through out the document – the text says "polyglot document" over over. 
> A nice title which isn't reflected in the text, is suboptimal. 
> 
> At the bottom of the letter, I present a concrete amendment of TBL's 
> abstract where I try show what i mean by incorporation. (Also, so you 
> don't think that I try to sneak it in: I also make use of the term 
> 'HTML polyglot', because I think it is a useful term, even if it may be 
> to complicated in the title.)
> 
>>> 3. The abstract should be an abstract of the document not information about
>>> it.
>>> Suggested abstract:
>>> 
>>> Abstract:
>>> 
>>> A polyglot document is an HTML5 document which is at the same time an
>>> XML document and an HTML document, and meets a well defined set of
>>> constraints. Polyglot documents meeting these constraints are interpreted
>>> compatibly regardless of whether they are processed as HTML or as XHTML,
>>> per the HTML5 specification. Polyglot documents use a specific doctype,
>>> namespace declarations, and a specific case, normally lower case but
>>> occasionally camel case, for element and attribute names. They use lower
>>> case for certain attribute values. Further constraints include those 
>>> on empty
>>> elements, names entity references, and to the use of scripts and style.
> 
>> 3 & 4 done.
> 
> The abstract says that "Polyglot documents use a specific doctype". But 
> what is meant by this? Is it meant that polyglot documents have a 
> single DOCTYPE and that the docytp eis exactly <!DOCTYP html>? Not even 
> HTML5 itself is that strict: HTML5 allows the 'about:legacy' doctype as 
> well. And also, HTML5 mentions some obsolete doctypes that are only 
> obsoleted because "they are unnecessarily long". Two of those doctypes 
> are XHTML 1.0 Strict and XHTML 1.1. Any XHTML compatible DOCTYPE which 
> works in HTML5 should in principle also work in a polyglot spec, not? 
> (See the bug 9958 above for more on this.) 

The goal of an abstract is summarize the document so that someone
reading gets the gist of the document.  What it says should be true
of course but the reader can be expected to delve into the document for details.
It should help the reader decide whether she will read the document itself.

One should resolve the technical questions in the spec, and then make sure the abstract is correct
and a good summary, with an even balance of detail.
So maybe ""Polyglot documents use a specific doctype" will become
"Polyglot documents use specific doctypes"

(A good abstract should not be just introduction or just conclusion either!)


> My view: The polyglot spec needs to describe DOCTYPEs more generally, 
> as HTML5 itself does. Filed as bug 9958.[1]
> 
> Finally: Proposed amendment of the Abstract, as example of how to 
> incorporate the terminology - also filed as bug 9959: [2]
> 


> ]]
> This specification defines Polyglot Markup, an HTML-compatible XHTML 
> document format. Documents of this kind are also known as HTML 
> polyglots. An HTML polyglot is an HTML5 document which is at the same 
> time an XML document and an HTML document. HTML polyglots that meet 
> these constraints are, per the HTML5 specification, interpreted as 
> compatible, regardless of whether they are processed as HTML or as 
> XHTML. An HTML polyglot is obligated to have an XML- and 
> HTML5-compatible doctype, to use namespace declarations, and to use a 
> specific case—normally lower case but occasionally camel case—for 
> element and attribute names. HTML polyglots use lower case for certain 
> attribute values. Further constraints include those on empty elements, 
> named entity references, and the use of scripts and style.
> [[

As a matter of style, to reinforce the abstract as an abstract of the 
document, not a description of the document, it should not start
"This specification defines", but "Polyglot markup is.."

(What is an XML-compatible doctype? All doctypes are XML-compatible,
as DOCTYPE is a feature of XML, no?)


> 
> [1] http://www.w3.org/Bugs/Public/show_bug.cgi?id=9958
> [2] http://www.w3.org/Bugs/Public/show_bug.cgi?id=9959
> -- 
> leif halvard silli
>

Received on Sunday, 20 June 2010 13:47:18 UTC