- From: Eliot Graff via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 21 Apr 2010 21:43:29 +0000
- To: public-html-commits@w3.org
Update of /sources/public/html5/html-xhtml-author-guide
In directory hutz:/tmp/cvs-serv26544
Modified Files:
html-xhtml-authoring-guide.html
Log Message:
Initial Draft incorporating content from origninal sources found on W3C and WHAT WG.
Index: html-xhtml-authoring-guide.html
===================================================================
RCS file: /sources/public/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- html-xhtml-authoring-guide.html 13 Apr 2010 19:54:15 -0000 1.1
+++ html-xhtml-authoring-guide.html 21 Apr 2010 21:43:27 -0000 1.2
@@ -29,7 +29,7 @@
// if there a publicly available Editor's Draft, this is the link
// TODO: Uncomment next line and add the link:
- //edDraftURI: "http://dev.w3.org/2009/dap/ReSpec.js/documentation.html",
+ edDraftURI: "http://dev.w3.org/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
@@ -77,17 +77,397 @@
</head>
<body>
<section id='abstract'>
- This appendix summarizes design guidelines for authors who wish their XHTML documents to render on existing HTML user agents.
- Note that this recommendation does not define how HTML conforming user agents should process HTML documents.
- Nor does it define the meaning of the Internet Media Type text/html. For these definitions, see [[HTML5]] and [[RFC2854]] respectively.
+ 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.
+ Note that this recommendation does not define how HTML5-conforming user agents should process HTML documents.
+ Nor does it define the meaning of the Internet Media Type text/html. For these definitions, see [[!HTML5]] and [[!RFC2854]] respectively.
</section>
<section>
<h2>Introduction</h2>
<p>
- TODO: Introductory comments here
+ It is often valuable to be able to serve HTML5 documents that are also valid XML documents.
+ An author may, for example, use XML tools to generate a document, and they and others may process the document using XML tools. These documents are served as text/html.
+ The language used to create documents that can be parsed by both HTML and XML parsers is called <dfn>polyglot</dfn>.
+ Polyglot is the overlap language of documents which are both HTML5 documents and XML documents.
+
+ <!-- <ul>
+ TODO: in this section:
+ <li>Offer "top-tier" summary of general guidelines to conform to polyglot language.</li>
+ <li>Link to more detailed analysis below.</li>
+ </ul> -->
+
+ </p>
+ </section>
+
+ <section>
+ <h2>Processing Instructions and the XML Declaration</h2>
+ <p>
+ You MUST NOT use processing instructions in a polyglot document. You SHOULD use the HTML <code>meta</code> tag to specify character and coding in the document.
+ If a polyglot document uses an encoding other than UTF8 or UTF16, you SHOULD include the XML declaration; however, in this case you SHOULD 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 MUST specify the same character and coding.
+ </p>
+ </section>
+
+ <section>
+ <h2>The DOCTYPE</h2>
+ <p>
+ For a polyglot document, you MUST use the <a href="http://dev.w3.org/html5/spec/syntax.html#the-doctype">HTML DOCTYPE</a>.
+ </p>
+ </section>
+
+ <section>
+ <h2>Namespaces</h2>
+ <p>
+ The following guidelines apply to namespaces used in polyglot documents.
+ </p>
+ <ul>
+ <li>
+ The <code><html></code> element MUST have the namespace declaration <code>xmlns="http://www.w3.org/1999/xhtml"</code>.
+ </li>
+ <li>
+ All <code><math></code> elements MUST have the namespace declaration <code>xmlns="http://www.w3.org/1998/Math/MathML"</code>.
+ </li>
+ <li>
+ All <code><svg></code> elements MUST have the namespace declaration <code>xmlns="http://www.w3.org/2000/svg"</code>.
+ </li>
+ <li>
+ The xlink prefix MUST be 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.
+ </li>
+ <li>
+ Once on each <code><svg></code> element that contains one or more elements with xlink:href attributes.
+ </li>
+ </ul>
+ </li>
+ <li>
+ No other elements should have namespace declarations.
+ </li>
+ </ul>
+ </section>
+
+ <section>
+ <h2>Elements</h2>
+ <section>
+ <h3>Required Elements</h3>
+ <p>
+ Each document MUST have a root <code>html</code> element. The root <code>html</code> element MUST contain both a <code>head</code> and a <code>body</code> element.
+ The <code>head</code> element MUST contain a <code>title</code> element.
+
+ </p>
+
+ <section>
+ <h3>Tables</h3>
+ <p>
+ For a polyglot document, a table MUST explicitly have a <code>tbody</code> element surrounding groups of <code>tr</code> elements.
+ HTML pasrsers insert the <code>tbody</code> element, but XML parsers do not, thus creating different DOMs.
+ </p>
+ <p>
+ Correct:
+ <pre class="example">
+<table>
+ <tbody>
+ <tr>...
+ </pre>
+ Incorrect:
+ <pre class="example">
+<table>
+ <tr>...
+ </pre>
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <h2>Case-Sensitivity</h2>
+ <p>
+ The following guidelines apply to markup, script, and CSS.
+ </p>
+
+ <section>
+ <h3>Element Names</h3>
+ <p>You MUST use the correct case for element names.</p>
+ <ul>
+ <li>
+ Element names MUST be lowercase for all HTML elements.
+ </li>
+ <li>
+ Element names MUST be lowercase for all MathML elements.
+ </li>
+ <li>
+ Element names MUST be lowercase for all SVG elements except the following, which MUST be in mixed case:
+ <ul>
+ <li><code>altGlyph</code></li>
+ <li><code>altGlyphDef</code></li>
+ <li><code>altGlyphItem</code></li>
+ <li><code>animateColor</code></li>
+ <li><code>animateMotion</code></li>
+ <li><code>animateTransform</code></li>
+ <li><code>clipPath</code></li>
+ <li><code>feBlend</code></li>
+ <li><code>feColorMatrix</code></li>
+ <li><code>feComponentTransfer</code></li>
+ <li><code>feComposite</code></li>
+ <li><code>feConvolveMatrix</code></li>
+ <li><code>feDiffuseLighting</code></li>
+ <li><code>feDisplacementMap</code></li>
+ <li><code>feDistantLight</code></li>
+ <li><code>feFlood</code></li>
+ <li><code>feFuncA</code></li>
+ <li><code>feFuncB</code></li>
+ <li><code>feFuncG</code></li>
+ <li><code>feFuncR</code></li>
+ <li><code>feGaussianBlur</code></li>
+ <li><code>feImage</code></li>
+ <li><code>feMerge</code></li>
+ <li><code>feMergeNode</code></li>
+ <li><code>feMorphology</code></li>
+ <li><code>feOffset</code></li>
+ <li><code>fePointLight</code></li>
+ <li><code>feSpecularLighting</code></li>
+ <li><code>feSpotLight</code></li>
+ <li><code>feTile</code></li>
+ <li><code>feTurbulence</code></li>
+ <li><code>foreignObject</code></li>
+ <li><code>glyphRef</code></li>
+ <li><code>linearGradient</code></li>
+ <li><code>radialGradient</code></li>
+ <li><code>textPath</code></li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Attribute Names</h3>
+ <p>
+ You MUST use the correct case for attribute names.
+ </p>
+ <ul>
+ <li>
+ Attribute names MUST be lowercase for all HTML elements.
+ </li>
+ <li>
+ Attribute names MUST be lowercase for all MathML elements except the following:
+ <p>The lowercase <code>definitionurl</code> MUST be changed to the mixed case <code>definitionURL</code>.</p>
+ </li>
+ <li>
+ Attribute names MUST be lowercase for all SVG elements except the following, which MUST be in mixed case:
+ <ul>
+ <li><code>attributeName</code></li>
+ <li><code>attributeType</code></li>
+ <li><code>baseFrequency</code></li>
+ <li><code>baseProfile</code></li>
+ <li><code>calcMode</code></li>
+ <li><code>clipPathUnits</code></li>
+ <li><code>contentScriptType</code></li>
+ <li><code>contentStyleType</code></li>
+ <li><code>diffuseConstant</code></li>
+ <li><code>edgeMode</code></li>
+ <li><code>externalResourcesRequired</code></li>
+ <li><code>filterRes</code></li>
+ <li><code>filterUnits</code></li>
+ <li><code>glyphRef</code></li>
+ <li><code>gradientTransform</code></li>
+ <li><code>gradientUnits</code></li>
+ <li><code>kernelMatrix</code></li>
+ <li><code>kernelUnitLength</code></li>
+ <li><code>keyPoints</code></li>
+ <li><code>keySplines</code></li>
+ <li><code>keyTimes</code></li>
+ <li><code>lengthAdjust</code></li>
+ <li><code>limitingConeAngle</code></li>
+ <li><code>markerHeight</code></li>
+ <li><code>markerUnits</code></li>
+ <li><code>markerWidth</code></li>
+ <li><code>maskContentUnits</code></li>
+ <li><code>maskUnits</code></li>
+ <li><code>numOctaves</code></li>
+ <li><code>pathLength</code></li>
+ <li><code>patternContentUnits</code></li>
+ <li><code>patternTransform</code></li>
+ <li><code>patternUnits</code></li>
+ <li><code>pointsAtX</code></li>
+ <li><code>pointsAtY</code></li>
+ <li><code>pointsAtZ</code></li>
+ <li><code>preserveAlpha</code></li>
+ <li><code>preserveAspectRatio</code></li>
+ <li><code>primitiveUnits</code></li>
+ <li><code>refX</code></li>
+ <li><code>refY</code></li>
+ <li><code>repeatCount</code></li>
+ <li><code>repeatDur</code></li>
+ <li><code>requiredExtensions</code></li>
+ <li><code>requiredFeatures</code></li>
+ <li><code>specularConstant</code></li>
+ <li><code>specularExponent</code></li>
+ <li><code>spreadMethod</code></li>
+ <li><code>startOffset</code></li>
+ <li><code>stdDeviation</code></li>
+ <li><code>stitchTiles</code></li>
+ <li><code>surfaceScale</code></li>
+ <li><code>systemLanguage</code></li>
+ <li><code>tableValues</code></li>
+ <li><code>targetX</code></li>
+ <li><code>targetY</code></li>
+ <li><code>textLength</code></li>
+ <li><code>viewBox</code></li>
+ <li><code>viewTarget</code></li>
+ <li><code>xChannelSelector</code></li>
+ <li><code>yChannelSelector</code></li>
+ <li><code>zoomAndPan</code></li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Attribute Values</h3>
+ <p>
+ You MUST specify attribute values as lowercase.
+ </p>
+ </section>
+ </section>
+
+
+ <section>
+ <h2>Empty Elements</h2>
+ <p>
+ You MAY use only the elements in the following table as empty elements.
+ </p>
+ <ul>
+ <li><code>area</code></li>
+ <li><code>base</code></li>
+ <li><code>br</code></li>
+ <li><code>col</code></li>
+ <li><code>command</code></li>
+ <li><code>embed</code></li>
+ <li><code>hr</code></li>
+ <li><code>img</code></li>
+ <li><code>input</code></li>
+ <li><code>keygen</code></li>
+ <li><code>link</code></li>
+ <li><code>meta</code></li>
+ <li><code>param</code></li>
+ <li><code>source</code></li>
+ </ul>
+ <p>
+ You SHOULD include a space before the trailing <code>/</code> and <code>></code> of empty elements, e.g. <code><br /></code>, <code><hr /></code> and <code><img src="karen.jpg" alt="Karen" /></code>.
+ Also, you SHOULD use 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>).
+ </p>
+ <p>
+ Note that MathML and SVG elements may be either self-closing or contain content.
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <h2>Attributes</h2>
+ <p>Avoid line breaks and multiple white space characters within attribute values. These are handled inconsistently by user agents.</p>
+ <p>See also <a href="#attribute-values">Attribute Values</a>.</p>
+
+ </section>
+
+ <section>
+ <h2>Named Entity References</h2>
+ <p>
+ You SHOULD use only the following named entity references:
+ </p>
+ <ul>
+ <li><code>amp</code></li>
+ <li><code>lt</code></li>
+ <li><code>gt</code></li>
+ <li><code>apos</code></li>
+ <li><code>quot</code></li>
+ </ul>
+ <p>
+ When you need entities beyond the previous list, use character references.
+ </p>
+ <p>
+ The named character reference <code>&apos;</code> (the apostrophe, U+0027) was introduced in XML 1.0 but does not appear in HTML.
+ Authors should therefore use <code>&#39;</code> instead of <code>&apos;</code> to work as expected in HTML user agents.
</p>
</section>
+
+
+ <section>
+ <h2>Script and Style</h2>
+ <p>
+ Script and style commands SHOULD be included by linking to external files rather than including them in-line.
+ </p>
+ <p>
+ Although you MAY use <code>document.write()</code> and <code>document.writeln()</code> in an HTML document, you MUST NOT use either function in XHTML and therefore 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.
+ </p>
+ <section>
+ <h3>External Script and Style</h3>
+ <p>
+ You MUST use external scripts if your script uses <code><</code> or <code>&</code> or <code>]]></code> or <code>--</code>.
+ You MUST 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>
+ </section>
+ <section>
+ <h3>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 SHOULD NOT use a <code>CDATA</code> section unless it is being used within foreign content.
+ <ul>
+ <li>Safe content is content that does not contain a <code><</code> or <code>&</code> character.
+ The following example is safe because it does not contain problematic characters within the <code><script></code> tag.
+ <pre class='example'>
+ <script>document.body.appendChild(document.createElement("div"));</script>
+ </pre>
+ </li>
+ <li>Wrap in-line script and style commands in a CDATA section</li>
+ <p>
+ Note that you cannot achieve same DOM in both XHTML and HTML by using in-line commands in a CDATA section.
+ However, this is not usally a problem unless the code has a dependency on the exact number of text nodes under a <code><script></code> or <code><style></code> element.
+ The following examples show in-line script and style commands wrapped in a <code>CDATA</code> section.
+ </p>
+ <pre class="example">
+<script>
+//<![CDATA[
+ (script goes here)
+//]]>
+</script>
+
+ </pre>
+ <pre class="example">
+<style>
+/*<![CDATA[*/
+ (styles go here)
+/*]]>*/
+</style>
+
+ </pre>
+ <p>
+ When using MathML or SVG, the parser follows the XML parsing rules.
+ You MUST 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>
+ </p>
+ </section>
+ </section>
+
+
+
+ <section>
+ <h2>Exceptions from the Foreign Content Parsing Rules</h2>
+ <p>
+ <!-- TODO: Need to call out exceptions from the foreign content parsing rules (e.g. <foreignContent> -->
+ </p>
+ </section>
+
<section class='appendix'>
<h2>Acknowledgements</h2>
Received on Wednesday, 21 April 2010 21:43:32 UTC