- From: Eliot Graff via cvs-syncmail <cvsmail@w3.org>
- Date: Thu, 17 Jun 2010 18:30:44 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/html-xhtml-author-guide
In directory hutz:/tmp/cvs-serv5522
Modified Files:
html-xhtml-authoring-guide.html
Log Message:
Moved prior abstract content to within "Status of This Document"; added new abstract; Changed most informative sections to be listed as normative sections; changed most references that were using RFC2116 language;
Index: html-xhtml-authoring-guide.html
===================================================================
RCS file: /sources/public/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -d -r1.14 -r1.15
--- html-xhtml-authoring-guide.html 27 May 2010 21:09:23 -0000 1.14
+++ html-xhtml-authoring-guide.html 17 Jun 2010 18:30:41 -0000 1.15
@@ -20,8 +20,8 @@
src="html-xhtml-authoring-guide_files/w3c_home.png" alt="W3C" width="72"
height="48"></a></p><h1 class="title" id="title">HTML/XHTML
Compatibility Authoring Guidelines</h1><h2
-id="w3c-editor-s-draft-27-may-2010"><acronym title="World Wide Web
-Consortium">W3C</acronym> Editor's Draft 27 May 2010</h2><dl><dt>This
+id="w3c-editor-s-draft-17-june-2010"><acronym title="World Wide Web
+Consortium">W3C</acronym> Editor's Draft 17 June 2010</h2><dl><dt>This
version:</dt><dd><a
href="http://dev.w3.org/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html">http://dev.w3.org/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html</a></dd><dt>Latest
published version:</dt><dd><a href="http://www.w3.org/TR/xxx-xxx/">http://www.w3.org/TR/xxx-xxx/</a></dd><dt>Latest
@@ -44,6 +44,28 @@
and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document
use</a> rules apply.</p><hr></div>
<div class="introductory section" id="abstract"><h2>Abstract</h2>
+ <p>
+ A polyglot document is an HTML5 document which is at the same time
+ an XML document and an HTML document, and which meets a well defined
+set of constraints.
+ Polyglot documents that meet these constraints as interpreted as
+compatible, 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.
+ Polyglot documents use lower case for certain attribute values.
+ Further constraints include those on empty elements, named entity
+references, and the use of scripts and style.
+ </p>
+ </div><div id="sotd" class="introductory section"><h2>Status of This
+ Document</h2><p><em>This section describes the status of this document
+at the time of its publication. Other documents may supersede this
+document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym>
+ publications and the latest revision of this technical report can be
+found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide
+Web Consortium">W3C</acronym> technical reports index</a> at
+http://www.w3.org/TR/.</em></p>
<p>This document summarizes design guidelines for authors who wish
their XHTML or HTML documents to validate on either HTML or XML
parsers, assuming the parsers to be HTML5-compliant.
@@ -57,14 +79,7 @@
href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a>] and [<a
href="#bib-RFC2854" rel="biblioentry" class="bibref">RFC2854</a>].
</p>
- </div><div id="sotd" class="introductory section"><h2>Status of This
- Document</h2><p><em>This section describes the status of this document
-at the time of its publication. Other documents may supersede this
-document. A list of current <acronym title="World Wide Web Consortium">W3C</acronym>
- publications and the latest revision of this technical report can be
-found in the <a href="http://www.w3.org/TR/"><acronym title="World Wide
-Web Consortium">W3C</acronym> technical reports index</a> at
-http://www.w3.org/TR/.</em></p><p>This document was published by the <a
+ <p>This document was published by the <a
href="http://www.w3.org/html/wg/"><acronym title="World Wide Web
Consortium">W3C</acronym> HTML</a> as an Editor's Draft. If you wish to
make comments regarding this document, please send them to <a
@@ -133,6 +148,8 @@
class="tocline"><a class="tocxref" href="#informative-references"><span
class="secno">B.2 </span>Informative references</a></li></ul></li></ul></div>
+
+
<div id="introduction" class="section informative">
<!--OddPage--><h2><span class="secno">1. </span>Introduction</h2><p><em>This
section is non-normative.</em></p>
@@ -149,12 +166,11 @@
</p>
</div>
- <div id="PI-and-xml" class="section informative">
+ <div id="PI-and-xml" class="section">
<!--OddPage--><h2><span class="secno">2. </span>Processing Instructions
- and the XML Declaration</h2><p><em>This section is non-normative.</em></p>
+ and the XML Declaration</h2>
<p>
- You <em title="must not" class="rfc2119">must not</em> use processing
- instructions in a polyglot document.
+ A polyglot document does not use processing instructions.
Note that the parsing rules for the XML declaration are not
processing instructions and are defined separately in <a
href="http://www.w3.org/TR/REC-xml/#NT-XMLDecl">Prolog and Document Type
@@ -162,20 +178,21 @@
<!-- TODO: Add Normative link once generated -->
</p>
</div>
- <div id="character-encoding" class="section informative">
- <!--OddPage--><h2><span class="secno">3. </span>Character Encoding</h2><p><em>This
- section is non-normative.</em></p>
+ <div id="character-encoding" class="section">
+ <!--OddPage--><h2><span class="secno">3. </span>Character Encoding</h2>
<p>
- You <em title="may" class="rfc2119">may</em> use either UTF-8 or
-UTF-16, although generally UTF-8 is preferred. If you use UTF-16, you <em
- title="should" class="rfc2119">should</em> include the BOM indicating
-UTF-16LE or UTF-16BE. In addition, you need not include the meta charset
- declaration, because the parser would have to read UTF-16 in order to
+ A polyglot document uses either UTF-8 or UTF-16, although generally
+UTF-8 is preferred.
+ If a polyglot document uses UTF-16, it <em title="should"
+class="rfc2119">should</em> include the BOM indicating UTF-16LE or
+UTF-16BE.
+ In addition, a polyglot document need not include the meta charset
+declaration, because the parser would have to read UTF-16 in order to
parse it by definition.
</p>
<p>
- In short, for correct character encoding for a polyglot document, you
- <em title="must" class="rfc2119">must</em> either:
+ In short, for correct character encoding, a polyglot document <em
+title="must" class="rfc2119">must</em> either:
</p><ul>
<li>Use UTF-8 or UTF-16 with the appropriate BOM.</li>
</ul>
@@ -188,23 +205,22 @@
<p>
If a polyglot document uses an encoding other than UTF-8 or UTF-16,
-you <em title="must" class="rfc2119">must</em> include the XML
-declaration; however, in this case you <em title="must" class="rfc2119">must</em>
- also include the HTML <code>meta</code> tag specifying the character
-set.
- When you use both the XML declaration and the HTML <code>meta</code>
-tag, they <em title="must" class="rfc2119">must</em> specify the same
+it <em title="must" class="rfc2119">must</em> include the XML
+declaration; however, in this case the document <em title="must"
+class="rfc2119">must</em> also include the HTML <code>meta</code> tag
+specifying the character set.
+ When a polyglot document uses both the XML declaration and the HTML <code>meta</code>
+ tag, these <em title="must" class="rfc2119">must</em> specify the same
character and coding.
</p>
</div>
- <div id="doctype" class="section informative">
- <!--OddPage--><h2><span class="secno">4. </span>The DOCTYPE</h2><p><em>This
- section is non-normative.</em></p>
+ <div id="doctype" class="section">
+ <!--OddPage--><h2><span class="secno">4. </span>The DOCTYPE</h2>
<p>
- For a polyglot document, you <em title="must" class="rfc2119">must</em>
- use the <code><!DOCTYPE html></code> doctype.
+ A polyglot document uses the <code><!DOCTYPE html></code>
+doctype.
Note that for a polyglot document the string, <code>html</code>, <em
title="must" class="rfc2119">must</em> be lower case.
For a pure HTML document, the string is defined as case-insensitive. [<a
@@ -212,30 +228,28 @@
</p>
</div>
- <div id="namespaces" class="section informative">
- <!--OddPage--><h2><span class="secno">5. </span>Namespaces</h2><p><em>This
- section is non-normative.</em></p>
+ <div id="namespaces" class="section">
+ <!--OddPage--><h2><span class="secno">5. </span>Namespaces</h2>
<p>
The following rules apply to namespaces used in polyglot
documents.
</p>
<ul>
<li>
- The <code><html></code> element <em title="must"
-class="rfc2119">must</em> have the namespace declaration <code>xmlns="http://www.w3.org/1999/xhtml"</code>.
+ The <code><html></code> element uses the namespace
+declaration <code>xmlns="http://www.w3.org/1999/xhtml"</code>.
</li>
<li>
- All <code><math></code> elements <em title="must"
-class="rfc2119">must</em> have the namespace declaration <code>xmlns="http://www.w3.org/1998/Math/MathML"</code>.
+ All <code><math></code> elements uses the namespace
+declaration <code>xmlns="http://www.w3.org/1998/Math/MathML"</code>.
</li>
<li>
- All <code><svg></code> elements <em title="must"
-class="rfc2119">must</em> have the namespace declaration <code>xmlns="http://www.w3.org/2000/svg"</code>.
+ All <code><svg></code> elements uses the namespace
+declaration <code>xmlns="http://www.w3.org/2000/svg"</code>.
</li>
<li>
- The xlink prefix <em title="must" class="rfc2119">must</em> be
-defined as <code>xmlns:xlink="http://www.w3.org/1999/xlink"</code>
-before using xlink:href. The prefix can be defined either:
+ The xlink prefix is defined as <code>xmlns:xlink="http://www.w3.org/1999/xlink"</code>
+ before using xlink:href. The prefix can be defined either:
<ul>
<li>
Once on the root <code><html></code> element.
@@ -252,27 +266,27 @@
</ul>
</div>
- <div id="elements" class="section informative">
- <!--OddPage--><h2><span class="secno">6. </span>Elements</h2><p><em>This
- section is non-normative.</em></p>
+ <div id="elements" class="section">
+ <!--OddPage--><h2><span class="secno">6. </span>Elements</h2>
<div class="section" id="required-elements">
<h3><span class="secno">6.1 </span>Required Elements</h3>
<p>
- Each document <em title="must" class="rfc2119">must</em> have a
-root <code>html</code> element. The root <code>html</code> element <em
-title="must" class="rfc2119">must</em> contain both a <code>head</code>
-and a <code>body</code> element.
+ Each polyglot document <em title="must" class="rfc2119">must</em>
+ have a root <code>html</code> element.
+ The root <code>html</code> element <em title="must"
+class="rfc2119">must</em> contain both a <code>head</code> and a <code>body</code>
+ element.
The <code>head</code> element <em title="must" class="rfc2119">must</em>
contain a <code>title</code> element.
</p>
- <div class="section" id="tables">
+ <div id="tables" class="section">
<h4><span class="secno">6.1.1 </span>Tables</h4>
<p>
- For a polyglot document, a table <em title="must" class="rfc2119">must</em>
- explicitly have a <code>tbody</code> element surrounding groups of <code>tr</code>
- elements.
+ Within a polyglot document, a table <em title="must"
+class="rfc2119">must</em> explicitly have a <code>tbody</code> element
+surrounding groups of <code>tr</code> elements.
HTML parsers insert the <code>tbody</code> element, but XML
parsers do not, thus creating different DOMs.
</p>
@@ -288,30 +302,30 @@
</div>
</div>
- <div class="section" id="case-sensitivity">
+ <div id="case-sensitivity" class="section">
<h3><span class="secno">6.2 </span>Case-Sensitivity</h3>
<p>
The following guidelines apply to any usage of element names,
attribute names, or attribute values in markup, script, or CSS.
</p>
- <div class="section" id="element-names">
+ <div id="element-names" class="section">
<h4><span class="secno">6.2.1 </span>Element Names</h4>
- <p>You <em title="must" class="rfc2119">must</em> use the
-correct case for element names.</p>
+ <p>A polyglot document uses the correct case for element
+names.</p>
<ul>
<li>
- Element names <em title="must" class="rfc2119">must</em> be
-lowercase for all HTML elements.
+ A polyglot document uses lowercase letters for all HTML element
+names.
</li>
<li>
- Element names <em title="must" class="rfc2119">must</em> be
-lowercase for all MathML elements.
+ A polyglot document uses lowercase letters for all MathML element
+names.
</li>
<li>
- Element names <em title="must" class="rfc2119">must</em> be
-lowercase for all SVG elements except the following, which <em
-title="must" class="rfc2119">must</em> be in mixed case:
+ A polyglot document uses lowercase letters for all SVG element
+names except the following, which <em title="must" class="rfc2119">must</em>
+ be in mixed case:
<ul>
<li><code>altGlyph</code></li>
<li><code>altGlyphDef</code></li>
@@ -354,31 +368,30 @@
</ul>
</div>
- <div class="section" id="attribute-names">
+ <div id="attribute-names" class="section">
<h4><span class="secno">6.2.2 </span>Attribute Names</h4>
<p>
- You <em title="must" class="rfc2119">must</em> use the correct case
- for attribute names.
- When required, you <em title="must" class="rfc2119">must</em> use
-lower case letters for all ASCII letters; however, case requirements do
-not apply to non-ASCII letters such as Greek, Cyrillic, or non-ASCII
-Latin letters.
+ A polyglot document uses the correct case for attribute names.
+ When required, a polyglot document <em title="must" class="rfc2119">must</em>
+ use lower case letters for all ASCII letters; however, case
+requirements do not apply to non-ASCII letters such as Greek, Cyrillic,
+or non-ASCII Latin letters.
</p>
<ul>
<li>
- Attribute names <em title="must" class="rfc2119">must</em>
- be lowercase for all HTML elements.
+ A polyglot document uses lowercase letters in attribute
+names for all HTML elements.
</li>
<li>
- Attribute names <em title="must" class="rfc2119">must</em>
- be lowercase for all MathML elements except the following:
+ A polyglot document uses lowercase letters in attribute
+names for all MathML elements except the following:
<p>The lowercase <code>definitionurl</code> <em
title="must" class="rfc2119">must</em> be changed to the mixed case <code>definitionURL</code>.</p>
</li>
<li>
- Attribute names <em title="must" class="rfc2119">must</em>
- be lowercase for all SVG elements except the following, which <em
-title="must" class="rfc2119">must</em> be in mixed case:
+ A polyglot document uses lowercase letters in attribute
+names for all SVG elements except the following, which <em title="must"
+class="rfc2119">must</em> be in mixed case:
<ul>
<li><code>attributeName</code></li>
<li><code>attributeType</code></li>
@@ -447,20 +460,21 @@
</ul>
</div>
- <div class="section" id="attribute-values">
+ <div id="attribute-values" class="section">
<h4><span class="secno">6.2.3 </span>Attribute Values</h4>
<p>
- The values for the attributes in the following list <em title="must"
- class="rfc2119">must</em> use lowercase letters when they exist on HTML
- elements.
- More specifically, where required, you <em title="must"
-class="rfc2119">must</em> use lower case letters for all ASCII letters
-in these attribute values; however, case requirements do not apply to
-non-ASCII letters such as Greek, Cyrillic, or non-ASCII Latin letters.
+ A polyglot document uses lowercase letters for the values of the
+attributes in the following list when they exist on HTML elements.
+ More specifically, where required, a polyglot document <em
+title="must" class="rfc2119">must</em> use lower case letters for all
+ASCII letters in these attribute values; however, case requirements do
+not apply to non-ASCII letters such as Greek, Cyrillic, or non-ASCII
+Latin letters.
Attributes for HTML elements other than those in the following list <em
title="may" class="rfc2119">may</em> have values made of mixed case
-letters. All attributes on non-HTML elements may have values made of
-mixed case letters.
+letters.
+ All attributes on non-HTML elements may have values made of mixed
+case letters.
</p>
<ul>
<li><code>accept</code></li>
@@ -514,11 +528,11 @@
</div>
- <div class="section" id="empty-elements">
+ <div id="empty-elements" class="section">
<h3><span class="secno">6.3 </span>Empty Elements</h3>
<p>
- You <em title="may" class="rfc2119">may</em> use only the
-elements in the following table as empty elements.
+ A polyglot document uses only the elements in the following
+list as empty elements.
</p>
<ul>
<li><code>area</code></li>
@@ -537,16 +551,16 @@
<li><code>source</code></li>
</ul>
<p>
- You <em title="must" class="rfc2119">must</em> use the minimized
- tag syntax for empty elements, e.g. <code><br/></code>.
+ A polyglot document uses the minimized tag syntax for empty
+elements, e.g. <code><br/></code>.
The alternative syntax <code><br></br></code>
allowed by XML gives uncertain results in many existing user agents.
</p>
<p>
Given an empty instance of an element whose content model is not
- EMPTY (for example, an empty title or paragraph) do not use the
-minimized form (e.g. use <code><p></p></code> and not <code><p
- /></code>).
+ EMPTY (for example, an empty title or paragraph) a polyglot document
+does not use the minimized form (e.g. the document uses <code><p></p></code>
+ and not <code><p /></code>).
</p>
<p>
Note that MathML and SVG elements may be either self-closing or
@@ -555,25 +569,25 @@
</div>
</div>
- <div id="attributes" class="section informative">
- <!--OddPage--><h2><span class="secno">7. </span>Attributes</h2><p><em>This
- section is non-normative.</em></p>
- <p>Avoid line breaks and multiple white space characters within
-attribute values. These are handled inconsistently by user agents.</p>
- <p>Attribute values <em title="must" class="rfc2119">must</em> be
-surrounded by quotation marks. Attribute values <em title="may"
-class="rfc2119">may</em> be surrounded either by single quotation marks
-or by double quotation marks.</p>
+ <div id="attributes" class="section">
+ <!--OddPage--><h2><span class="secno">7. </span>Attributes</h2>
+ <p>A polyglot document does not contain line breaks and multiple white
+ space characters within attribute values. These are handled
+inconsistently by user agents.</p>
+ <p>A polyglot document surrounds all attribute values with quotation
+marks. Attribute values <em title="may" class="rfc2119">may</em> be
+surrounded either by single quotation marks or by double quotation
+marks.</p>
<p>See also <a href="#attribute-values">Attribute Values</a>.</p>
</div>
- <div id="named-entity-references" class="section informative">
+ <div id="named-entity-references" class="section">
<!--OddPage--><h2><span class="secno">8. </span>Named Entity
-References</h2><p><em>This section is non-normative.</em></p>
+References</h2>
<p>
- You <em title="must" class="rfc2119">must</em> use only the
-following named entity references:
+ A polyglot document uses only the following named entity
+references:
</p>
<ul>
<li><code>amp</code></li>
@@ -583,65 +597,63 @@
<li><code>quot</code></li>
</ul>
<p>
- When you need entities beyond the previous list, use character
-references. For example, use <code>&#160;</code> instead of <code>&nbsp;</code>.
+ For entities beyond the previous list, a ployglot document uses
+character references. For example, a polyglot document uses <code>&#160;</code>
+ instead of <code>&nbsp;</code>.
</p>
</div>
- <div id="script-and-style" class="section informative">
- <!--OddPage--><h2><span class="secno">9. </span>Script and Style</h2><p><em>This
- section is non-normative.</em></p>
+ <div id="script-and-style" class="section">
+ <!--OddPage--><h2><span class="secno">9. </span>Script and Style</h2>
<p>
Script and style commands <em title="should" class="rfc2119">should</em>
be included by linking to external files rather than including them
in-line.
- However, you <em title="must not" class="rfc2119">must not</em>
-link to an external stylesheet by using the xml-stylesheet processing
-instruction, as described in <a href="#PI-and-xml">Processing
-Instructions and the XML Declaration</a>.
+ However, a polyglot document <em title="must not"
+class="rfc2119">must not</em> link to an external stylesheet by using
+the xml-stylesheet processing instruction.
+ See also <a href="#PI-and-xml">Processing Instructions and the
+XML Declaration</a>.
</p>
<p>The following examples show the proper way to include external
script and style, respectively:</p>
<pre class="example"><script src="external.js"></script></pre>
<pre class="example"><link rel="stylesheet" href="external.css"/> </pre>
<p>
- Although you <em title="may" class="rfc2119">may</em> use <code>document.write()</code>
- and <code>document.writeln()</code> in an HTML document, you <em
-title="must not" class="rfc2119">must not</em> use either function in
-XHTML and therefore in a polyglot document.
+ Although <code>document.write()</code> and <code>document.writeln()</code>
+ are valid in an HTML document, neither function may be used in XHTML.
+ Therefore, neither is used in a polyglot document.
Instead, use the <code>innerHTML</code> property for both HTML
and XHTML.
Note that the <code>innerHTML</code> property takes a string.
XML parsers parse the string as XML in XHTML.
HTML parsers parse the string as HTML in HTML.
- Therefore, if you send the parser content that does not follow
-the rules for a polyglot document the results will differ for a DOM
-create with an XML parser and one created with an HTML parser.
+ Because of the difference in parsing, if you send the parser
+content that does not follow the rules for a polyglot document the
+results will differ for a DOM create with an XML parser and one created
+with an HTML parser.
</p>
- <div class="section" id="external-script-and-style">
+ <div id="external-script-and-style" class="section">
<h3><span class="secno">9.1 </span>External Script and Style</h3>
<p>
- You <em title="must" class="rfc2119">must</em> use external
-scripts if your script uses <code><</code> or <code>&</code> or <code>]]></code>
+ A polyglot document uses external scripts if that document's
+script or style sheet uses <code><</code> or <code>&</code> or <code>]]></code>
or <code>--</code>.
- You <em title="must" class="rfc2119">must</em> use external
-style sheets if your style sheet uses <code><</code> or <code>&</code>
- or <code>]]></code> or <code>--</code>.
Note that XML parsers are permitted to silently remove the
contents of comments; therefore, the historical practice of hiding
scripts and style sheets within comments to make the documents backward
compatible is likely to not work as expected in XML-based user agents.
</p>
</div>
- <div class="section" id="in-line-script-and-style">
+ <div id="in-line-script-and-style" class="section">
<h3><span class="secno">9.2 </span>In-line Script and Style</h3>
<p>
- If you must use script or style commands within your source code,
- either use safe content or wrap the command in a CDATA section.
-However, you <em title="should not" class="rfc2119">should not</em> use a
- <code>CDATA</code> section unless it is being used within foreign
-content.
+ If a polyglot document must use script or style commands within
+its source code, either use safe content or wrap the command in a CDATA
+section.
+ However, a polyglot document does not use a <code>CDATA</code>
+section unless it is being used within foreign content.
</p><ul>
<li>Safe content is content that does not contain a <code><</code>
or <code>&</code> character.
@@ -672,9 +684,9 @@
<p>
When using MathML or SVG, the parser follows the XML parsing
rules.
- You <em title="must not" class="rfc2119">must not</em> rely on
-getting a CDATA instance from the DOM when using MathML or SVG, because
-the HTML parser does not create a CDATA instance in the DOM.
+ A polyglot document does not rely on getting a CDATA instance
+from the DOM when using MathML or SVG, because the HTML parser does not
+create a CDATA instance in the DOM.
</p>
</ul>
@@ -684,10 +696,9 @@
- <div id="foreign-content" class="section informative">
+ <div id="foreign-content" class="section">
<!--OddPage--><h2><span class="secno">10. </span>Exceptions from
-the Foreign Content Parsing Rules</h2><p><em>This section is
-non-normative.</em></p>
+the Foreign Content Parsing Rules</h2>
<p>
<!-- TODO: Need to call out exceptions from the foreign content parsing rules (e.g. <foreignContent> -->
</p>
@@ -698,7 +709,8 @@
<!--OddPage--><h2><span class="secno">A. </span>Acknowledgements</h2>
<p>
Many thanks to Daniel Glazman, Tony Ross, Sam Ruby, Jonas
-Sicking, Henri Sivonen, and Philip Taylor .
+Sicking, Henri Sivonen, and Philip Taylor. Special thanks to the <acronym
+ title="World Wide Web Consortium">W3C</acronym> TAG.
</p>
</div>
<div class="appendix section" id="references"><!--OddPage--><h2><span
Received on Thursday, 17 June 2010 18:30:46 UTC