W3C home > Mailing lists > Public > public-html-diffs@w3.org > April 2010

eliot: Initial Draft incorporating content from origninal sources found on W3C and WHAT WG.

From: poot <cvsmail@w3.org>
Date: Thu, 22 Apr 2010 06:43:50 +0900 (JST)
To: public-html-diffs@w3.org
Message-Id: <20100421214350.BA0E12BC69@toro.w3.mag.keio.ac.jp>
eliot: Initial Draft incorporating content from origninal sources found
on W3C and WHAT WG.

http://dev.w3.org/cvsweb/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html?r1=1.1&r2=1.2&f=h

===================================================================
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>&lt;html&gt;</code> element MUST have the namespace declaration <code>xmlns="http://www.w3.org/1999/xhtml"</code>.
+      	</li>
+      	<li>
+      		All <code>&lt;math&gt;</code> elements MUST have the namespace declaration <code>xmlns="http://www.w3.org/1998/Math/MathML"</code>.
+      	</li>
+      	<li>
+      		All <code>&lt;svg&gt;</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>&lt;html&gt;</code> element.
+      				</li>
+      				<li>
+      					Once on each <code>&lt;svg&gt;</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">    	
+&lt;table&gt;
+  &lt;tbody&gt;
+    &lt;tr&gt;...
+      			</pre>	
+				Incorrect:
+				<pre class="example">				
+&lt;table&gt;
+  &lt;tr&gt;...
+				</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>&gt;</code> of empty elements, e.g. <code>&lt;br /&gt;</code>, <code>&lt;hr /&gt;</code> and <code>&lt;img src="karen.jpg" alt="Karen" /&gt;</code>. 
+	      	Also, you SHOULD use the minimized tag syntax for empty elements, e.g. <code>&lt;br /&gt;</code>. 
+	      	The alternative syntax <code>&lt;br&gt;&lt;/br&gt;</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>&lt;p&gt; &lt;/p&gt;</code> and not <code>&lt;p /&gt;</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>&amp;apos;</code> (the apostrophe, U+0027) was introduced in XML 1.0 but does not appear in HTML. 
+      	Authors should therefore use <code>&amp;#39;</code> instead of <code>&amp;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>&lt;</code> or <code>&amp;</code> or <code>]]&gt;</code> or <code>--</code>. 
+        You MUST use external style sheets if your style sheet uses <code>&lt;</code> or <code>&amp;</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>&lt;</code> or <code>&amp;</code> character. 
+      		The following example is safe because it does not contain problematic characters within the <code>&lt;script&gt;</code> tag.
+				<pre class='example'>
+		      		&lt;script&gt;document.body.appendChild(document.createElement("div"));&lt;/script&gt;
+		        </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>&lt;script&gt;</code> or <code>&lt;style&gt;</code> element.
+					The following examples show in-line script and style commands wrapped in a <code>CDATA</code> section.
+      			</p>
+      					<pre class="example">
+&lt;script&gt;
+//&lt;![CDATA[
+	(script goes here)
+//]]&gt;
+&lt;/script&gt;
+
+      					</pre>
+      					<pre class="example">
+&lt;style&gt;
+/*&lt;![CDATA[*/
+	(styles go here)
+/*]]>*/
+&lt;/style&gt;
+      					
+      					</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:44:48 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Saturday, 18 December 2010 06:14:19 GMT