[ac] (0) Change the meaning of <dl> subtly; include some examples.

git-svn-id: http://svn.whatwg.org/webapps@1243 340c8d12-0b0e-0410-8428-c7bf67bfef74
whatwg · Feb 26, 2008 · 05cbd30 · 05cbd30
1 parent a33e649
commit 05cbd30
Show file tree

Hide file tree

Showing 2 changed files with 95 additions and 41 deletions.
diff --git a/index b/index
@@ -9878,18 +9878,38 @@ I first lived there):&lt;/p>
     href="#htmlelement">HTMLElement</a></code>.
   </dl>
 
-  <p>The <code><a href="#dl">dl</a></code> element introduces an unordered
-   association list consisting of zero or more name-value groups (a
-   description list). Each group must consist of one or more names (<code><a
+  <p>The <code><a href="#dl">dl</a></code> element introduces an association
+   list consisting of zero or more name-value groups (a description list).
+   Each group must consist of one or more names (<code><a
    href="#dt">dt</a></code> elements) followed by one or more values
    (<code><a href="#dd">dd</a></code> elements).
 
   <p>Name-value groups may be terms and definitions, metadata topics and
    values, or any other groups of name-value data.
 
-  <div class=example>
-   <p>The following are all conforming HTML fragments.</p>
+  <p>The order of the list of groups, and of the names and values within each
+   group, may be significant.
+
+  <p>If a <code><a href="#dl">dl</a></code> element is empty, it contains no
+   groups.
+
+  <p>If a <code><a href="#dl">dl</a></code> element contains non-<a
+   href="#inter-element" title="inter-element whitespace">whitespace</a> <a
+   href="#text-node" title="text node">text nodes</a>, or elements other than
+   <code><a href="#dt">dt</a></code> and <code><a href="#dd">dd</a></code>,
+   then those elements or <a href="#text-node" title="text node">text
+   nodes</a> do not form part of any groups in that <code><a
+   href="#dl">dl</a></code>, and the document is non-conforming.
 
+  <p>If a <code><a href="#dl">dl</a></code> element contains only <code><a
+   href="#dt">dt</a></code> elements, then it consists of one group with
+   names but no values, and the document is non-conforming.
+
+  <p>If a <code><a href="#dl">dl</a></code> element contains only <code><a
+   href="#dd">dd</a></code> elements, then it consists of one group with
+   values but no names, and the document is non-conforming.
+
+  <div class=example>
    <p>In the following example, one entry ("Authors") is linked to two values
     ("John" and "Luke").</p>
 
@@ -9900,7 +9920,9 @@ I first lived there):&lt;/p>
  &lt;dt&gt; Editor
  &lt;dd&gt; Frank
 &lt;/dl&gt;</pre>
+  </div>
 
+  <div class=example>
    <p>In the following example, one definition is linked to two terms.</p>
 
    <pre>&lt;dl&gt;
@@ -9910,7 +9932,9 @@ I first lived there):&lt;/p>
  the fine structure of the eye to distinguish three differently
  filtered analyses of a view. &lt;/dd&gt;
 &lt;/dl&gt;</pre>
+  </div>
 
+  <div class=example>
    <p>The following example illustrates the use of the <code><a
     href="#dl">dl</a></code> element to mark up metadata of sorts. At the end
     of the example, one group has two metadata labels ("Authors" and
@@ -9928,24 +9952,25 @@ I first lived there):&lt;/p>
 &lt;/dl&gt;</pre>
   </div>
 
-  <p>If a <code><a href="#dl">dl</a></code> element is empty, it contains no
-   groups.
-
-  <p>If a <code><a href="#dl">dl</a></code> element contains non-<a
-   href="#inter-element" title="inter-element whitespace">whitespace</a> <a
-   href="#text-node" title="text node">text nodes</a>, or elements other than
-   <code><a href="#dt">dt</a></code> and <code><a href="#dd">dd</a></code>,
-   then those elements or <a href="#text-node" title="text node">text
-   nodes</a> do not form part of any groups in that <code><a
-   href="#dl">dl</a></code>, and the document is non-conforming.
-
-  <p>If a <code><a href="#dl">dl</a></code> element contains only <code><a
-   href="#dt">dt</a></code> elements, then it consists of one group with
-   names but no values, and the document is non-conforming.
-
-  <p>If a <code><a href="#dl">dl</a></code> element contains only <code><a
-   href="#dd">dd</a></code> elements, then it consists of one group with
-   values but no names, and the document is non-conforming.
+  <div class=example>
+   <p>The following example shows the <code><a href="#dl">dl</a></code>
+    element used to give a set of instructions. The order of the instructions
+    here is important (in the other examples, the order of the blocks was not
+    important).</p>
+
+   <pre>&lt;p&gt;Determine the victory points as follows (use the
+first matching case):&lt;/p&gt;
+&lt;dl&gt;
+ &lt;dt&gt; If you have exactly five gold coins &lt;/dt&gt;
+ &lt;dd&gt; You get five victory points &lt;/dd&gt;
+ &lt;dt&gt; If you have one or more gold coins, and you have one or more silver coins &lt;/dt&gt;
+ &lt;dd&gt; You get two victory points &lt;/dd&gt;
+ &lt;dt&gt; If you have one or more silver coins &lt;/dt&gt;
+ &lt;dd&gt; You get one victory point &lt;/dd&gt;
+ &lt;dt&gt; Otherwise &lt;/dt&gt;
+ &lt;dd&gt; You get no victory points &lt;/dd&gt;
+&lt;/dl&gt;</pre>
+  </div>
 
   <p class=note>The <code><a href="#dl">dl</a></code> element is
    inappropriate for marking up dialogue, since dialogue is ordered (each

diff --git a/source b/source
@@ -8046,17 +8046,36 @@ I first lived there):&lt;/p>
    <dd>No difference from <code>HTMLElement</code>.</dd>
   </dl>
 
-  <p>The <code>dl</code> element introduces an unordered association
-  list consisting of zero or more name-value groups (a description
+  <p>The <code>dl</code> element introduces an association list
+  consisting of zero or more name-value groups (a description
   list). Each group must consist of one or more names (<code>dt</code>
   elements) followed by one or more values (<code>dd</code>
   elements).</p>
 
   <p>Name-value groups may be terms and definitions, metadata topics
   and values, or any other groups of name-value data.</p>
 
+  <p>The order of the list of groups, and of the names and values
+  within each group, may be significant.</p>
+
+  <p>If a <code>dl</code> element is empty, it contains no groups.</p>
+
+  <p>If a <code>dl</code> element contains non-<span
+  title="inter-element whitespace">whitespace</span> <span title="text
+  node">text nodes</span>, or elements other than <code>dt</code> and
+  <code>dd</code>, then those elements or <span title="text node">text
+  nodes</span> do not form part of any groups in that <code>dl</code>,
+  and the document is non-conforming.</p>
+
+  <p>If a <code>dl</code> element contains only <code>dt</code>
+  elements, then it consists of one group with names but no values,
+  and the document is non-conforming.</p>
+
+  <p>If a <code>dl</code> element contains only <code>dd</code>
+  elements, then it consists of one group with values but no names,
+  and the document is non-conforming.</p>
+
   <div class="example">
-   <p>The following are all conforming HTML fragments.</p>
    <p>In the following example, one entry ("Authors") is linked to two
    values ("John" and "Luke").</p>
    <pre>&lt;dl&gt;
@@ -8066,6 +8085,9 @@ I first lived there):&lt;/p>
  &lt;dt&gt; Editor
  &lt;dd&gt; Frank
 &lt;/dl&gt;</pre>
+  </div>
+
+  <div class="example">
    <p>In the following example, one definition is linked to two
    terms.</p>
    <pre>&lt;dl&gt;
@@ -8075,6 +8097,9 @@ I first lived there):&lt;/p>
  the fine structure of the eye to distinguish three differently
  filtered analyses of a view. &lt;/dd&gt;
 &lt;/dl&gt;</pre>
+  </div>
+
+  <div class="example">
    <p>The following example illustrates the use of the <code>dl</code>
    element to mark up metadata of sorts. At the end of the example,
    one group has two metadata labels ("Authors" and "Editors") and two
@@ -8091,22 +8116,26 @@ I first lived there):&lt;/p>
 &lt;/dl&gt;</pre>
   </div>
 
-  <p>If a <code>dl</code> element is empty, it contains no groups.</p>
-
-  <p>If a <code>dl</code> element contains non-<span
-  title="inter-element whitespace">whitespace</span> <span title="text
-  node">text nodes</span>, or elements other than <code>dt</code> and
-  <code>dd</code>, then those elements or <span title="text node">text
-  nodes</span> do not form part of any groups in that <code>dl</code>,
-  and the document is non-conforming.</p>
-
-  <p>If a <code>dl</code> element contains only <code>dt</code>
-  elements, then it consists of one group with names but no values,
-  and the document is non-conforming.</p>
+  <div class="example">
 
-  <p>If a <code>dl</code> element contains only <code>dd</code>
-  elements, then it consists of one group with values but no names,
-  and the document is non-conforming.</p>
+   <p>The following example shows the <code>dl</code> element used to
+   give a set of instructions. The order of the instructions here is
+   important (in the other examples, the order of the blocks was not
+   important).</p>
+
+   <pre>&lt;p&gt;Determine the victory points as follows (use the
+first matching case):&lt;/p&gt;
+&lt;dl&gt;
+ &lt;dt&gt; If you have exactly five gold coins &lt;/dt&gt;
+ &lt;dd&gt; You get five victory points &lt;/dd&gt;
+ &lt;dt&gt; If you have one or more gold coins, and you have one or more silver coins &lt;/dt&gt;
+ &lt;dd&gt; You get two victory points &lt;/dd&gt;
+ &lt;dt&gt; If you have one or more silver coins &lt;/dt&gt;
+ &lt;dd&gt; You get one victory point &lt;/dd&gt;
+ &lt;dt&gt; Otherwise &lt;/dt&gt;
+ &lt;dd&gt; You get no victory points &lt;/dd&gt;
+&lt;/dl&gt;</pre>
+  </div>
 
   <p class="note">The <code>dl</code> element is inappropriate for
   marking up dialogue, since dialogue is ordered (each speaker/line