W3C home > Mailing lists > Public > public-html-commits@w3.org > May 2010

html5/html-xhtml-author-guide html-xhtml-authoring-guide.html,1.5,1.6

From: Eliot Graff via cvs-syncmail <cvsmail@w3.org>
Date: Thu, 06 May 2010 01:18:26 +0000
To: public-html-commits@w3.org
Message-Id: <E1O9pjO-0003Dk-Oe@lionel-hutz.w3.org>
Update of /sources/public/html5/html-xhtml-author-guide
In directory hutz:/tmp/cvs-serv12366

Modified Files:
	html-xhtml-authoring-guide.html 
Log Message:
Changed abstract to emphasize that this specification is for web authors rather than UAs; updated Processing Instructions and the XML Declaration to more accurately account for requirements around using UTF-8 and UTF-16; updated doctype to speak to case sensitivity; added note excluding non-ASCII letters from lowercase requirement in attribute names; called out xml declaration as specifically not processing insstructions; changed named entity references from SHOULD to MUST; removed reference to "&apos;" as it exists in HTML5; changed should to MUST in minimized tag syntax for empty elements;

Index: html-xhtml-authoring-guide.html
===================================================================
RCS file: /sources/public/html5/html-xhtml-author-guide/html-xhtml-authoring-guide.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- html-xhtml-authoring-guide.html	4 May 2010 21:05:50 -0000	1.5
+++ html-xhtml-authoring-guide.html	6 May 2010 01:18:24 -0000	1.6
@@ -47,12 +47,15 @@
       <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. 
+      This specification is intended to be used by web authors. It is 
+not a specification for user agents and creates no obligations on user 
+agents.
       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 [<a href="#bib-HTML5" 
-rel="biblioentry" class="bibref">HTML5</a>] and [<a href="#bib-RFC2854" 
-rel="biblioentry" class="bibref">RFC2854</a>] respectively.
+text/html. For user agent guidance and for these definitions, see [<a 
+href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a>] and [<a 
+href="#bib-RFC2854" rel="biblioentry" class="bibref">RFC2854</a>].
       </p>
       <p><strong>Note:</strong>   If your browser does not render the 
 fully-formatted version of this document with images and color fonts, 
@@ -164,17 +167,46 @@
  and the XML Declaration</h2>
 		<p>
 			You <em title="must not" class="rfc2119">must not</em> use processing
- instructions in a polyglot document. You <em title="should" 
-class="rfc2119">should</em> 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
- <em title="should" class="rfc2119">should</em> include the XML 
+ instructions in a polyglot document. 
+			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
+ Declaration</a>. 
+			<!-- TODO: Add Normative link once generated --> 
+		</p>
+		<p>
+			You <em title="should" class="rfc2119">should</em> use the HTML <code>meta</code>
+ tag to specify character and coding in the document. 
+			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 
+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:
+			</p><ul>
+				<li>Use UTF-8 or UTF-16 with the appropriate BOM.</li>
+			</ul>
+			<strong>OR</strong>
+			<ul>
+				<li>Use both the XML Declaration and <code>meta</code> tag to 
+specify the appropriate character encoding.</li>
+			</ul>
+		
+		
+		<p>
+			If a polyglot document uses an encoding other than UTF-8 or UTF-16, 
+you <em title="should" class="rfc2119">should</em> include the XML 
 declaration; however, in this case you <em title="should" 
 class="rfc2119">should</em> also include the HTML <code>meta</code> tag 
-specifying the character set. 
+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 
 character and coding.
+ 
 		</p>
 	</div>
 
@@ -182,8 +214,11 @@
 	<!--OddPage--><h2><span class="secno">3. </span>The DOCTYPE</h2>
 	<p>
 		For a polyglot document, you <em title="must" class="rfc2119">must</em>
- use the <a href="http://dev.w3.org/html5/spec/syntax.html#the-doctype">HTML
- DOCTYPE</a>.
+ use the <code>&lt;!DOCTYPE html&gt;</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
+ href="#bib-HTML5" rel="biblioentry" class="bibref">HTML5</a>]
 	</p>
 	</div>    
     
@@ -264,7 +299,7 @@
 	    <div class="section" id="case-sensitivity">
 	      <h3><span class="secno">5.2 </span>Case-Sensitivity</h3>
 	      <p>
-	        The following guidelines apply to markup, script, and CSS.
+	        The following guidelines apply to markup, script, and CSS. 
 	      </p>
 	
 	        <div class="section" id="element-names">
@@ -330,7 +365,11 @@
 			<h4><span class="secno">5.2.2 </span>Attribute Names</h4>
 				<p>
 					You <em title="must" class="rfc2119">must</em> use the correct case
- for attribute names.
+ 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.
 				</p>
 	        			<ul>
 	        				<li>
@@ -420,6 +459,10 @@
 				<p>
 					You <em title="must" class="rfc2119">must</em> specify attribute 
 letters as lowercase.
+					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.
 				</p>
 			</div>
 	    </div>
@@ -448,8 +491,8 @@
 				<li><code>source</code></li>
 			</ul>
 	      <p>
-	      	You <em title="should" class="rfc2119">should</em> use the 
-minimized tag syntax for empty elements, e.g. <code>&lt;br/&gt;</code>. 
+	      	You <em title="must" class="rfc2119">must</em> 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>
@@ -478,7 +521,7 @@
       <!--OddPage--><h2><span class="secno">7. </span>Named Entity 
 References</h2>
       <p>
-        You <em title="should" class="rfc2119">should</em> use only the 
+        You <em title="must" class="rfc2119">must</em> use only the 
 following named entity references:
       </p>
       	<ul>
@@ -492,13 +535,6 @@
       	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>
     </div>
 
 
Received on Thursday, 6 May 2010 01:18:28 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 6 May 2010 01:18:29 GMT