- From: CVS User egraff <cvsmail@w3.org>
- Date: Mon, 13 Jan 2014 00:06:01 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/html-polyglot
In directory roscoe:/tmp/cvs-serv20462
Modified Files:
html-polyglot.html
Log Message:
Editing pass through the end of the spec, also updated Section 2
--- /sources/public/html5/html-polyglot/html-polyglot.html 2014/01/09 01:16:49 1.22
+++ /sources/public/html5/html-polyglot/html-polyglot.html 2014/01/13 00:06:01 1.23
@@ -8,7 +8,7 @@
var respecConfig = {
specStatus: "ED",
shortName: "html-polyglot",
- publishDate: "2014-01-07",
+ publishDate: "2014-01-12",
previousPublishDate: "2010-10-19",
// previousDiffURI: "http://htmlwg.org/heartbeat/WD-html-polyglot-20131008/",
previousMaturity: "WD",
@@ -109,26 +109,32 @@
<h3>Robustness</h3>
<p> Polyglot markup is a means to an end – <dfn id="dfn-robustness">robustness</dfn>.
- <!-- We should have a more precise definition of robust -->
- It is not a goal in itself. However, authors do not need
- to understand these benefits in order to use and benefit from this syntax. But neither does anyone
- need to exaggerate its benefits. For instance, <a title="polyglot markup">polyglot markup</a> does not add semantics. Polyglot markup does,
- however, work to <em>preserve</em> semantics, including during the authoring process. Polyglot markup
- also doesn’t ensure accessibility - as it does not add any requirements
- that other relevant specs have not already added. But it can work to <em>preserve</em> accessibility.</p>
+ <a title="polyglot markup">Polyglot markup</a> embraces the principle of <a>robustness</a>
+ as it is defined in Web Content Accessibility Guidelines (WCAG) 2.0:
+ <em>Content must be robust enough that it can be interpreted reliably by a wide variety of user agents,
+ including assistive technologies.</em> [[!WCAG20]]
+ </p>
+ <p><a title="robustness">Robustness</a> is not a goal in itself, nor do authors need
+ to understand the benefits of <a>robustness</a> in order to use and benefit from the syntax of polyglot markup.
+ Nor does anyone need to exaggerate the benefits of polyglot markup.
+ For instance, <a title="polyglot markup">polyglot markup</a> does not add semantics.
+ Polyglot markup does, however, work to <em>preserve</em> semantics, including during the authoring process.
+ Polyglot markup does not ensure accessibility,as it does not add any accessibility requirements
+ that other relevant specifications have not already added.
+ But <a>polyglot markup</a> can work to <em>preserve</em> accessibility through adherence to required practices.</p>
- <p>The motivation behind, and reason for <a title="polyglot markup">polyglot markup</a> to exist as a specification, is its widely supported
- <a title="robustness">robustness</a>. With <a title="robustness">robust</a> (also known as conservative) markup, authors can
+ <p>The motivation behind, and reason for <a title="polyglot markup">polyglot markup</a> is support for <a title="robustness">robustness</a>.
+ With <a title="robustness">robust</a> (sometimes known as conservative) markup, authors can
<q cite="http://www.w3.org/TR/WCAG20/#robust">maximize compatibility with current and future user agents</q> and authoring tools. [[!WCAG20]]</p>
- <p>Polyglot markup seeks to define constraints on the serialization of a DOM tree in a <a title="robustness">robust</a> manner that
- is likely to retain semantics when said serialization is reparsed using a variety of parsers, be
+ <p>Polyglot markup approaches <a>robustness</a> by defining constraints on the serialization of a DOM tree in a manner that
+ is likely to retain semantics when that serialization is reparsed using a variety of parsers, be
they full featured and bug free HTML5 parsers, somewhat HTML-aware parsers, and even XML parsers.
</p>
<p> For the most part, <a title="polyglot markup">polyglot markup</a> is just a pure deduction of the validity constraints and syntax requirements that
- HTML and XHTML dictate, many of which took polyglotness into consideration when they were added to HTML5.
- However, for reasons of <a title="robustness">robustness</a>, the spec sometimes goes a little further than the principle of the lowest common
+ HTML and XHTML dictate, many of which took "polyglotness" into consideration when they were added to HTML5.
+ However, for reasons of <a title="robustness">robustness</a>, this specification sometimes goes a little further than the principle of the lowest common
denominator would have required.</p>
<p> For instance, included in the set of constraints on the serialization is the requirement to use the UTF-8 encoding.
@@ -136,9 +142,9 @@
that in turn have lead the HTML5 specification to recommend that all new documents use UTF-8,
but also because it is the sole encoding that <em>every</em> parser,
be it an HTML parser or an XML parser, is required to support.
- NB, the HTML-specific benefits are described in HTML5 [[!HTML5]].
+ Note that the HTML-specific benefits are described in HTML5 [[!HTML5]].
</p>
- <p> Also, UTF-8 might in some situations be the sole <em>HTML-conforming</em> option, since it is one of
+ <p> Also, UTF-8 might in some situations be the sole <em>HTML-conforming</em> option, since it is one of
only two encodings (the other being UTF-16, with its own, separate set of well-known issues) for which XML well-formed
rules doesn’t require the encoding to be explicitly declared.
This in turn has the benefit that any HTML-invalid XML
@@ -760,12 +766,12 @@
wrapping the contents in a <code>CDATA</code> section. The <code>CDATA</code> code is then seen as text
by the HTML parser (and can thus interfere with the scripting or styling language!), while the XML parser sees the
content as text without markup semantics.</li></ul>
- <p>Limiting the contents to <a>safe content</a> requires more planning and control over the code, but can be said to be
+ <p>Limiting the contents to <a>safe text content</a> requires more planning and control over the code, but can be said to be
more <a title="robustness">robust</a> than the <code>CDATA</code> option as it requires no extra, potentially
breakable code to make the scripting or styling language work. The <code>CDATA</code> option on the
other hand, gives more freedom and robustness against various errors that can happen because the author isn’t
- aware of the <a>safe content</a> limitations or because the code is inserted by a tool that is unable to
- guarantee that the content is <a title="safe content">safe</a>.</p>
+ aware of the <a>safe text content</a> limitations or because the code is inserted by a tool that is unable to
+ guarantee that the content is <a title="safe text content">safe</a>.</p>
<section id="safe-text-content">
<h5>Options for delivering safe text content</h5>
@@ -778,6 +784,7 @@
External files are parsed as the respective script or stylesheet and are thus not limited
by the same restrictions as safe text content.
<figure>
+ <figcaption>Examples of linking to external scripts or stylesheets</figcaption>
<pre class="example highlight"
><!-- Ways to link to external scripts or stylesheets --><br/><script src="external.js" ></script><br
/><link href="external.css" rel="stylesheet"/><br
@@ -794,6 +801,7 @@
so long as they are valid.
That is, for <a>polyglot markup</a>, there is no difference between <code>&amp;</code> and <code>&#x3C;</code>.
<figure>
+ <figcaption>Examples of content that is not safe text content</figcaption>
<pre class="example highlight"><!-- Unsafe content: < and & are not escaped<br
/> This code is not XML well-formed. --><br/><style>q::before{content:"<";}</style><br/><script>var a = "&";</script>
@@ -805,10 +813,11 @@
<p>For CSS, the inline <a>safe text content</a> option would work very well most of the time, as <code><</code> and
<code>&</code> are not key parts of CSS and not very often used. But when it comes to JavaScript,
the <code>&</code> and the <code><</code> are key verbs (operators) of the
- language, and thus one soon runs into trouble – it is better to use <em>external</em> <a>safe content</a>.</p>
+ language, and thus one soon runs into trouble – it is better to use <em>external</em> <a>safe text content</a>.</p>
</li>
</ul>
<figure>
+ <figcaption>Inline content containing no ambiguous strings</figcaption>
<pre class="example highlight"
><!-- The following example of inline script is <a>polyglot markup</a> because there are no ambiguous strings within the <code>script</code> element. --><br
/><script>document.body.appendChild(document.createElement("div"));</script></pre>
@@ -858,20 +867,33 @@
<ol>
<li><code><![CDATA[</code> - without commenting it out.
<pre class="example highlight"><script type="not-CSS-and-not-JS"><![CDATA[foo]]></script></pre>
- <ul>
- <li> Important: This is not conforming as 'text/css' or 'text/javascript' content when parsed as HTML.</li>
- <li> Advantage: This can be useful for type="text/html" and templating in general, as it saves bytes.</li>
- <li> Disadvantage: Scripting languages might need to be tuned to support it.</li></ul>
- </li>
- <li><code>//<![CDATA[</code> - pure scripting language level commenting out. Comment starts in the node before the CDATA section:
+ <p class="note">Using the <code><![CDATA[</code> block without commenting it out
+ is not conforming as <code>type="text/css"</code> or <code>type="text/javascript"</code> content when parsed as HTML.
+ </p>
+ <!--<p>
+ The advantage of Using the <code><![CDATA[</code> block without commenting it out is that
+ it can be useful for <code>type="text/html"</code> and templating in general, as it saves bytes.
+ The disadvantage, however, is that scriptiing languages may need to be tuned to support the construct.
+ </p>-->
+
+ <li><code>//<![CDATA[</code> - using scripting language comments for the entire block.
<pre class="example highlight"><script>//<![CDATA[ FOO; //]]></script></pre>
- <ul>
- <li> Advantage: Well known in JavaScript. Much used.</li>
- <li> Disadvantage: Less safe for templating since the comment could become treated as part of the template.</li>
- </ul>
+ <p>
+ Note that the comment starts in the node before the CDATA section.
+ <!-- The advantage of commenting out the entire block is that the practice is well-known and commonly used in JavaScript.
+ The disadvantage of this approach is in templating, where the comment could become treated as part of the template.-->
+ </p>
</li>
<li> <code><!--//--><![CDATA[</code> - Same as 2, but the scripting comment is hidden inside an XML comment.
<pre class="example highlight"><script><!--//--><![CDATA[ FOO; //]]></script></pre>
+ <p>
+ Note that the scripting language must accept <code><!--</code> as syntactically legal.
+ JavaScript does, but other scripting languages may not.
+ </p>
+ <p>
+ This approach is compatible with CSS; however, rule 2 above prevents validity.
+ </p>
+ <!--
<ul>
<li> Advantage: Versatile.
<ul>
@@ -884,7 +906,7 @@
<ul><li>The JavaScript linter might not like it.</li>
<li>The scripting language must accept <code><!--</code> as syntactically legal (which JavaScript does) </li></ul>
</li>
- </ul>
+ </ul>-->
</li>
</ol>
@@ -893,17 +915,26 @@
</section>
<section id="CDATA-comment-syntax-in-script">
<h6>Comment syntax in <code>script</code></h6>
- <p>Do not place strings in the shape of the <code><script></code> start tag inside comments inside the <code>script</code> element as this causes the HTML parser, for compatibility related reasons, to <strong>not</strong> close the element on the next <code></script></code> end tag unless a closing comment string (<code>--></code>) has occurred first. Alternatively, if the parser doesn’t see any comment end first, the element will be closed on the <em>second</em> <code></script></code> end tag. If neither comment end or a second element end tag is found, the rest of the document will be swallowed.</p>
- <p>This idiosyncratic behavior is not seen for the <code>style</code> element, however. To avoid the suprising difference between <code>style</code> and <code>script</code>, simply avoid comments in these elements.</p>
+ <p><a title="polyglot markup">Polyglot markup</a> does not place the opening <code><script></code> tag inside comments within a
+ <code>script</code> element.
+ When the HTML parser encounters an opening <code><script></code> tag inside comments within a <code>script</code> element,
+ it does <strong>not</strong> close the element on the next <code></script></code> end tag unless a closing comment string
+ (<code>--></code>) occurs first, for compatibility-related reasons.
+ Alternatively, if the parser doesn’t see any comment end first, the element will be closed on the <em>second</em> <code></script></code> end tag.
+ If neither a comment end nor a second <code><script</code> element end tag is found,
+ the rest of the document is commented out. Note that this behavior does not occur with the <code>style</code> element.</p>
+ <!--<p>This behavior does not occur for the <code>style</code> element, however.
+ To avoid the difference between <code>style</code> and <code>script</code>, simply avoid comments in these elements.</p>-->
</section>
</section>
</section>
<section id="escaped-raw-text-elements">
<h4>Escapable raw text elements</h4>
- <p>Escapable raw text elements are elements in which character references are permitted, but where the HTML parser treats elements as text rather than as markup. </p>
+ <p>Escapable raw text elements are elements in which character references are permitted
+ but where the HTML parser treats elements as text rather than as markup. For <a>polyglot markup</a>, escapable raw text elements are:</p>
<ul class="inline-list"><li><code>title</code></li><li><code>textarea</code></li></ul>
- <p>Escapable raw text elements are subject to the same rules of safe text content, with the exception that polyglot character entities are permittd.</p>
+ <p>Polyglot markup uses the same rules of safe text content for escapable raw text elements, except that character entities are permitted for escapable raw text elements.</p>
</section>
<section id="foreign-elements" class="section">
<h4>Foreign elements</h4>
@@ -912,8 +943,9 @@
</section>
<section id="normal-elements" class="section">
<h4>Normal elements</h4>
- <p>Normal elements have no special restrictions other than those that normally apply to polyglot markup. But note that some elements, such as the <code>iframe</code>
- element must be empty in the polyglot markup since this is is a requirement which the HTML specification sets on <code>iframe</code> in the XHTML syntax.</p>
+ <p>Normal elements have no special restrictions other than those that generally apply to polyglot markup.
+ Note that some elements (such as the <code>iframe</code> element) must be empty in polyglot markup,
+ because the HTML specification sets this requirement on <code>iframe</code> in the XHTML syntax.</p>
<!--End section: White Space in textarea and pre Elements-->
</section>
</section>
@@ -942,6 +974,8 @@
For example, within an attribute's value, <a>polyglot markup</a> uses <code>&#x9;</code> for a tab
rather than the literal character <code>'\t'</code>.
This is because of attribute-value normalization in XML [[!XML10]].
+ </p>
+ <p>
The following example uses numeric character references (escaped characters) for the line feed, tab, and less-than characters within a <code>srcdoc</code> attribute.
</p>
<pre class="example highlight">
@@ -968,7 +1002,7 @@
<section id="disallowed-attributes" class="section">
<h3>Disallowed attributes</h3>
<p>The following attributes are not allowed in <a>polyglot markup</a>.
- These attributes have effects in documents parsed as XML but do not have effects in documents parsed as text/html.
+ These attributes have effects in documents parsed as XML but do not have effects in documents parsed as <code>text/html</code>.
The HTML5 spec therefore defines them as invalid in text/html documents. [[!HTML5]]
</p>
<ul class="inline-list">
@@ -1143,7 +1177,7 @@
The example document is served as <code>'text/html'</code>.
Some legacy user agents do not support SVG in when served up as <code>'text/html'</code> as it is in this example.
The example page could also be served as <code>'application/xhtml+xml'</code> instead, with the file extension .html,
- maintaining adherence to Polyglot markup and enabling the rendering of the SVG.
+ maintaining adherence to polyglot markup and enabling the rendering of the SVG.
</p>
<pre class="example" id="SampleDoc"><!DOCTYPE html>
Received on Monday, 13 January 2014 00:06:03 UTC