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

html5/spec-author-view Overview.html,1.831,1.832 introduction.html,1.581,1.582 spec.html,1.839,1.840

From: Michael Smith via cvs-syncmail <cvsmail@w3.org>
Date: Sun, 04 Apr 2010 09:07:25 +0000
To: public-html-commits@w3.org
Message-Id: <E1NyLnh-0008Jx-B5@lionel-hutz.w3.org>
Update of /sources/public/html5/spec-author-view
In directory hutz:/tmp/cvs-serv31960

Modified Files:
	Overview.html introduction.html spec.html 
Log Message:
More information on the reasons for authoring conformance criteria. I can't wait to see other W3C and IETF specs, like SVG, Atom, or RDFa, include introduction sections explaining why _they_ all have authoring conformance criteria. (whatwg r4966)

[updated by splitter]


Index: Overview.html
===================================================================
RCS file: /sources/public/html5/spec-author-view/Overview.html,v
retrieving revision 1.831
retrieving revision 1.832
diff -u -d -r1.831 -r1.832
--- Overview.html	4 Apr 2010 07:47:35 -0000	1.831
+++ Overview.html	4 Apr 2010 09:07:21 -0000	1.832
@@ -307,7 +307,7 @@
    </dl><p>This specification is available in the following formats: 
     <a href="spec.html">single page HTML</a>,
     <a href="Overview.html">multipage HTML</a>.
-This is revision 1.3987.
+This is revision 1.3988.
    </p> 
    <p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
    &#169; 2010 <a href="http://www.w3.org/"><abbr title="World Wide

Index: spec.html
===================================================================
RCS file: /sources/public/html5/spec-author-view/spec.html,v
retrieving revision 1.839
retrieving revision 1.840
diff -u -d -r1.839 -r1.840
--- spec.html	4 Apr 2010 07:47:35 -0000	1.839
+++ spec.html	4 Apr 2010 09:07:22 -0000	1.840
@@ -305,7 +305,7 @@
    </dl><p>This specification is available in the following formats: 
     <a href=spec.html>single page HTML</a>,
     <a href=Overview.html>multipage HTML</a>.
-This is revision 1.3987.
+This is revision 1.3988.
    </p> 
    <p class=copyright><a href=http://www.w3.org/Consortium/Legal/ipr-notice#Copyright>Copyright</a>
    © 2010 <a href=http://www.w3.org/><abbr title="World Wide
@@ -1604,6 +1604,42 @@
 
     </div>
 
+    <p class=example>Another example is the restrictions on the
+    content models of the <code><a href=#the-ul-element>ul</a></code> element, which only allows
+    <code><a href=#the-li-element>li</a></code> element children. Lists by definition consist just
+    of zero or more list items, so if a <code><a href=#the-ul-element>ul</a></code> element
+    contains something other than an <code><a href=#the-li-element>li</a></code> element, it's not
+    clear what was meant.</p>
+
+   </dd>
+
+
+   <dt>Errors that catch cases where the default styles are likely to lead to confusion</dt>
+
+   <dd>
+
+    <p>Certain elements have default styles or behaviors that make
+    certain combinations likely to lead to confusion. Where these have
+    equivalent alternatives without this problem, the confusing
+    combinations are disallowed.</p>
+
+    <p class=example>For example, <code><a href=#the-div-element>div</a></code> elements are
+    rendered as block boxes, and <code><a href=#the-span-element>span</a></code> elements as inline
+    boxes. Putting a block box in an inline box is unnecessarily
+    confusing; since either nesting just <code><a href=#the-div-element>div</a></code> elements, or
+    nesting just <code><a href=#the-span-element>span</a></code> elements, or nesting
+    <code><a href=#the-span-element>span</a></code> elements inside <code><a href=#the-div-element>div</a></code> elements all
+    serve the same purpose as nesting a <code><a href=#the-div-element>div</a></code> element in a
+    <code><a href=#the-span-element>span</a></code> element, but only the latter involves a block
+    box in an inline box, the latter combination is disallowed.</p>
+
+    <p class=example>Another example would be the way
+    <a href=#interactive-content>interactive content</a> cannot be nested. For example, a
+    <code><a href=#the-button-element>button</a></code> element cannot contain a <code><a href=#the-textarea-element>textarea</a></code>
+    element. This is because the default behavior of such nesting
+    interactive elements would be highly confusing to users. Instead
+    of nesting these elements, they can be placed side by side.</p>
+
    </dd>
 
 
@@ -1642,6 +1678,34 @@
    </dd>
 
 
+   <dt>Errors that avoid peculiarities of the parser</dt>
+
+   <dd>
+
+    <p>Certain elements are parsed in someone eccentric ways
+    (typically for historical reasons), and their content model
+    restrictions are intended to avoid exposing the author to these
+    issues.</p>
+
+    <div class=example>
+
+     <p>For example, a <code><a href=#the-form-element>form</a></code> element isn't allowed inside
+     <a href=#phrasing-content>phrasing content</a>, because when parsed as HTML, a
+     <code><a href=#the-form-element>form</a></code> element's start tag will imply a <code><a href=#the-p-element>p</a></code>
+     element's end tag. Thus, the following markup results in two
+     <a href=#paragraph title=paragraph>paragraphs</a>, not one:</p>
+
+     <pre>&lt;p&gt;Welcome. &lt;form&gt;&lt;label&gt;Name:&lt;/label&gt; &lt;input&gt;&lt;/form&gt;</pre>
+
+     <p>It is parsed exactly like the following:</p>
+
+     <pre>&lt;p&gt;Welcome. &lt;/p&gt;&lt;form&gt;&lt;label&gt;Name:&lt;/label&gt; &lt;input&gt;&lt;/form&gt;</pre>
+
+    </div>
+
+   </dd>
+
+
    <dt>Errors that would likely result in scripts failing in hard-to-debug ways</dt>
 
    <dd>

Index: introduction.html
===================================================================
RCS file: /sources/public/html5/spec-author-view/introduction.html,v
retrieving revision 1.581
retrieving revision 1.582
diff -u -d -r1.581 -r1.582
--- introduction.html	2 Apr 2010 23:27:26 -0000	1.581
+++ introduction.html	4 Apr 2010 09:07:22 -0000	1.582
@@ -959,6 +959,42 @@
 
     </div>
 
+    <p class="example">Another example is the restrictions on the
+    content models of the <code><a href="grouping-content.html#the-ul-element">ul</a></code> element, which only allows
+    <code><a href="grouping-content.html#the-li-element">li</a></code> element children. Lists by definition consist just
+    of zero or more list items, so if a <code><a href="grouping-content.html#the-ul-element">ul</a></code> element
+    contains something other than an <code><a href="grouping-content.html#the-li-element">li</a></code> element, it's not
+    clear what was meant.</p>
+
+   </dd>
+
+
+   <dt>Errors that catch cases where the default styles are likely to lead to confusion</dt>
+
+   <dd>
+
+    <p>Certain elements have default styles or behaviors that make
+    certain combinations likely to lead to confusion. Where these have
+    equivalent alternatives without this problem, the confusing
+    combinations are disallowed.</p>
+
+    <p class="example">For example, <code><a href="grouping-content.html#the-div-element">div</a></code> elements are
+    rendered as block boxes, and <code><a href="text-level-semantics.html#the-span-element">span</a></code> elements as inline
+    boxes. Putting a block box in an inline box is unnecessarily
+    confusing; since either nesting just <code><a href="grouping-content.html#the-div-element">div</a></code> elements, or
+    nesting just <code><a href="text-level-semantics.html#the-span-element">span</a></code> elements, or nesting
+    <code><a href="text-level-semantics.html#the-span-element">span</a></code> elements inside <code><a href="grouping-content.html#the-div-element">div</a></code> elements all
+    serve the same purpose as nesting a <code><a href="grouping-content.html#the-div-element">div</a></code> element in a
+    <code><a href="text-level-semantics.html#the-span-element">span</a></code> element, but only the latter involves a block
+    box in an inline box, the latter combination is disallowed.</p>
+
+    <p class="example">Another example would be the way
+    <a href="content-models.html#interactive-content">interactive content</a> cannot be nested. For example, a
+    <code><a href="the-button-element.html#the-button-element">button</a></code> element cannot contain a <code><a href="the-button-element.html#the-textarea-element">textarea</a></code>
+    element. This is because the default behavior of such nesting
+    interactive elements would be highly confusing to users. Instead
+    of nesting these elements, they can be placed side by side.</p>
+
    </dd>
 
 
@@ -997,6 +1033,34 @@
    </dd>
 
 
+   <dt>Errors that avoid peculiarities of the parser</dt>
+
+   <dd>
+
+    <p>Certain elements are parsed in someone eccentric ways
+    (typically for historical reasons), and their content model
+    restrictions are intended to avoid exposing the author to these
+    issues.</p>
+
+    <div class="example">
+
+     <p>For example, a <code><a href="forms.html#the-form-element">form</a></code> element isn't allowed inside
+     <a href="content-models.html#phrasing-content">phrasing content</a>, because when parsed as HTML, a
+     <code><a href="forms.html#the-form-element">form</a></code> element's start tag will imply a <code><a href="grouping-content.html#the-p-element">p</a></code>
+     element's end tag. Thus, the following markup results in two
+     <a href="content-models.html#paragraph" title="paragraph">paragraphs</a>, not one:</p>
+
+     <pre>&lt;p&gt;Welcome. &lt;form&gt;&lt;label&gt;Name:&lt;/label&gt; &lt;input&gt;&lt;/form&gt;</pre>
+
+     <p>It is parsed exactly like the following:</p>
+
+     <pre>&lt;p&gt;Welcome. &lt;/p&gt;&lt;form&gt;&lt;label&gt;Name:&lt;/label&gt; &lt;input&gt;&lt;/form&gt;</pre>
+
+    </div>
+
+   </dd>
+
+
    <dt>Errors that would likely result in scripts failing in hard-to-debug ways</dt>
 
    <dd>
Received on Sunday, 4 April 2010 09:07:27 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Sunday, 4 April 2010 09:07:27 GMT