Skip to content

Commit

Permalink
Allow <div> around each <dt><dd> group in <dl> (whatwg#1945)
Browse files Browse the repository at this point in the history 
This only changes the content model and the rules for determining
what a dl element represents.

Fixes whatwg#1937.
  • Loading branch information
@zcorpan
zcorpan authored and Alice Boxhall committed Jan 7, 2019
1 parent f588184 commit a7e9222
Showing 1 changed file with 167 additions and 37 deletions.
204 changes: 167 additions & 37 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3138,6 +3138,7 @@ a.setAttribute('href', 'http://example.com/'); // change the content attribute d
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-child" data-x="concept-tree-child">child</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-root">root</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-root">shadow-including root</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-inclusive-ancestor">inclusive ancestor</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-shadow-including-descendant">shadow-including descendant</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-first-child">first child</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#concept-tree-next-sibling">next sibling</dfn> concepts</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#document-element">document element</dfn> concept</li>
<li>The <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document-tree">in a document tree</dfn>, <dfn data-x-href="https://dom.spec.whatwg.org/#in-a-document">in a document</dfn> (legacy), and <dfn data-x-href="https://dom.spec.whatwg.org/#connected">connected</dfn> concepts</li>
<li>The <dfn data-x="concept-slot" data-x-href="https://dom.spec.whatwg.org/#concept-slot">slot</dfn> concept, and its <dfn data-x="slot-name" data-x-href="https://dom.spec.whatwg.org/#slot-name">name</dfn> and <dfn data-x-href="https://dom.spec.whatwg.org/#slot-assigned-nodes">assigned nodes</dfn></li>
Expand Down Expand Up @@ -17814,7 +17815,8 @@ interface <dfn>HTMLLIElement</dfn> : <span>HTMLElement</span> {
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd>Zero or more groups each consisting of one or more <code>dt</code> elements followed by one or more <code>dd</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dd>Either: Zero or more groups each consisting of one or more <code>dt</code> elements followed by one or more <code>dd</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dd>Or: One or more <code>div</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt><!--TOPIC:DOM APIs-->
Expand All @@ -17826,9 +17828,12 @@ interface <dfn>HTMLDListElement</dfn> : <span>HTMLElement</span> {};</pre>

<p>The <code>dl</code> element <span>represents</span> an association list consisting of zero or
more name-value groups (a description list). A name-value group consists of one or more names
(<code>dt</code> elements) followed by one or more values (<code>dd</code> elements), ignoring any
nodes other than <code>dt</code> and <code>dd</code> elements. Within a single <code>dl</code>
element, there should not be more than one <code>dt</code> element for each name.</p>
(<code>dt</code> elements, possibly as children of a <code>div</code> element child) followed by
one or more values (<code>dd</code> elements, possibly as children of a <code>div</code> element
child), ignoring any nodes other than <code>dt</code> and <code>dd</code> element children, and
<code>dt</code> and <code>dd</code> elements that are children of <code>div</code> element
children. Within a single <code>dl</code> element, there should not be more than one
<code>dt</code> element for each name.</p>

<p>Name-value groups may be terms and definitions, metadata topics and values, questions and
answers, or any other groups of name-value data.</p>
Expand All @@ -17839,30 +17844,88 @@ interface <dfn>HTMLDListElement</dfn> : <span>HTMLElement</span> {};</pre>
<p>The order of the list of groups, and of the names and values within each group, may be
significant.</p>

<p>In order to annotate groups with <span>microdata</span> attributes, or other <span>global
attributes</span> that apply to whole groups, or just for styling purposes, each group in a
<code>dl</code> element can be wrapped in a <code>div</code> element. This does not change the
semantics of the <code>dl</code> element.</p>

<div w-nodev>

<p>If a <code>dl</code> element has no <code>dt</code> or <code>dd</code> element children, it
contains no groups.</p>
<p>The name-value groups of a <code>dl</code> element <var>dl</var> are determined using the
following algorithm. A name-value group has a name (a list of <code>dt</code> elements, initially
empty) and a value (a list of <code>dd</code> elements, initially empty).</p>

<ol>
<li><p>Let <var>groups</var> be an empty list of name-value groups.</p></li>

<li><p>Let <var>current</var> be a new name-value group.</p></li>

<li><p>Let <var>seenDd</var> be false.</p></li>

<li><p>Let <var>child</var> be <var>dl</var>'s <span>first child</span>.</p></li>

<li><p>Let <var>grandchild</var> be null.</p></li>

<li>
<p>While <var>child</var> is not null, follow these substeps:</p>

<ol>
<li>
<p>If <var>child</var> is a <code>div</code> element, then follow these subsubsteps:</p>

<ol>
<li><p>Let <var>grandchild</var> be <var>child</var>'s <span>first child</span>.</p></li>

<li>
<p>While <var>grandchild</var> is not null, follow these subsubsubsteps:</p>

<p>If a <code>dl</code> element has one or more non-<span data-x="inter-element
whitespace">whitespace</span> <code>Text</code> node children, or has child elements that are
neither <code>dt</code> nor <code>dd</code> elements, all such <code>Text</code> nodes and
elements, as well as their descendants (including any <code>dt</code> or <code>dd</code>
elements), do not form part of any groups in that <code>dl</code>.</p>
<ol>
<li><p><span>Process <code>dt</code> or <code>dd</code></span> for
<var>grandchild</var>.</p></li>

<p>If a <code>dl</code> element has one or more <code>dt</code> element children but no
<code>dd</code> element children, then it consists of one group with names but no values.</p>
<li><p>Set <var>grandchild</var> to <var>grandchild</var>'s <span>next
sibling</span>.</p></li>
</ol>
</li>
</ol>
</li>

<p>If a <code>dl</code> element has one or more <code>dd</code> element children but no
<code>dt</code> element children, then it consists of one group with values but no names.</p>
<li><p>Otherwise, <span>process <code>dt</code> or <code>dd</code></span> for
<var>child</var>.</p></li>

<p>If a <code>dl</code> element's first <code>dt</code> or <code>dd</code> element child is a
<code>dd</code> element, then the first group has no associated name.</p>
<li><p>Set <var>child</var> to <var>child</var>'s <span>next sibling</span>.</p></li>
</ol>
</li>

<p>If a <code>dl</code> element's last <code>dt</code> or <code>dd</code> element child is a
<code>dt</code> element, then the last group has no associated value.</p>
<li><p>If <var>current</var> is not empty, then append <var>current</var> to
<var>groups</var>.</p></li>

<p class="note">When a <code>dl</code> element doesn't match its content model, it is often due to
<li><p>Return <var>groups</var>.</p></li>
</ol>

<p>To <dfn>process <code>dt</code> or <code>dd</code></dfn> for a node <var>node</var> means to
follow these steps:</p>

<ol>
<li><p>Let <var>groups</var>, <var>current</var>, and <var>seenDd</var> be the same variables as
those of the same name in the algorithm that invoked these steps.</p></li>

<li>
<p>If <var>node</var> is a <code>dt</code> element, then follow these substeps:</p>

<ol>
<li><p>If <var>seenDd</var> is true, then append <var>current</var> to <var>groups</var>, set
<var>current</var> to a new name-value group, and set <var>seenDd</var> to false.</p></li>

<li><p>Append <var>node</var> to <var>current</var>'s name.</p></li>
</ol>
</li>

<li><p>Otherwise, if <var>node</var> is a <code>dd</code> element, then append <var>node</var> to
<var>current</var>'s value and set <var>seenDd</var> to true.</p></li>
</ol>

<p class="note">When a name-value group has an empty list as name or value, it is often due to
accidentally using <code>dd</code> elements in the place of <code>dt</code> elements and vice
versa. Conformance checkers can spot such mistakes and might be able to advise authors how to
correctly use the markup.</p>
Expand Down Expand Up @@ -17900,18 +17963,26 @@ interface <dfn>HTMLDListElement</dfn> : <span>HTMLElement</span> {};</pre>

<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 values ("Robert Rothman" and "Daniel Jackson").</p>
and two values ("Robert Rothman" and "Daniel Jackson"). This example also uses the
<code>div</code> element around the groups of <code>dt</code> and <code>dd</code> element, to aid
with styling.</p>

<pre>&lt;dl&gt;
&lt;dt&gt; Last modified time &lt;/dt&gt;
&lt;dd&gt; 2004-12-23T23:33Z &lt;/dd&gt;
&lt;dt&gt; Recommended update interval &lt;/dt&gt;
&lt;dd&gt; 60s &lt;/dd&gt;
&lt;dt&gt; Authors &lt;/dt&gt;
&lt;dt&gt; Editors &lt;/dt&gt;
&lt;dd&gt; Robert Rothman &lt;/dd&gt;
&lt;dd&gt; Daniel Jackson &lt;/dd&gt;
&lt;/dl&gt;</pre>
<pre>&lt;dl>
&lt;div>
&lt;dt> Last modified time &lt;/dt>
&lt;dd> 2004-12-23T23:33Z &lt;/dd>
&lt;/div>
&lt;div>
&lt;dt> Recommended update interval &lt;/dt>
&lt;dd> 60s &lt;/dd>
&lt;/div>
&lt;div>
&lt;dt> Authors &lt;/dt>
&lt;dt> Editors &lt;/dt>
&lt;dd> Robert Rothman &lt;/dd>
&lt;dd> Daniel Jackson &lt;/dd>
&lt;/div>
&lt;/dl></pre>
</div>

<div class="example">
Expand Down Expand Up @@ -17950,6 +18021,56 @@ first matching case):&lt;/p&gt;
&lt;/dl></pre>
</div>

<div class="example">

<p>This example uses <span>microdata</span> attributes in a <code>dl</code> element, together
with the <code>div</code> element, to annotate the ice cream desserts at a French restaurant.</p>
<!-- https://commons.wikimedia.org/wiki/File:Carte_des_desserts_2012_des_cafétérias_Toquenelle_(1).jpg -->

<pre lang="fr">&lt;dl>
&lt;div itemscope itemtype="http://schema.org/Product">
&lt;dt itemprop="name">Café ou Chocolat Liégeois
&lt;dd itemprop="offers" itemscope itemtype="http://schema.org/Offer">
&lt;span itemprop="price">3.50&lt;/span>
&lt;data itemprop="priceCurrency" value="EUR">€&lt;/data>
&lt;dd itemprop="description">
2 boules Café ou Chocolat, 1 boule Vanille, sause café ou chocolat, chantilly
&lt;/div>

&lt;div itemscope itemtype="http://schema.org/Product">
&lt;dt itemprop="name">Américaine
&lt;dd itemprop="offers" itemscope itemtype="http://schema.org/Offer">
&lt;span itemprop="price">3.50&lt;/span>
&lt;data itemprop="priceCurrency" value="EUR">€&lt;/data>
&lt;dd itemprop="description">
1 boule Crème brûlée, 1 boule Vanille, 1 boule Caramel, chantilly
&lt;/div>
&lt;/dl></pre>

<p>Without the <code>div</code> element the markup would need to use the <code
data-x="attr-itemref">itemref</code> attribute to link the data in the <code>dd</code> elements
with the item, as follows.</p>

<pre lang="fr">&lt;dl>
&lt;dt itemscope itemtype="http://schema.org/Product" itemref="1-offer 1-description">
&lt;span itemprop="name">Café ou Chocolat Liégeois&lt;/span>
&lt;dd id="1-offer" itemprop="offers" itemscope itemtype="http://schema.org/Offer">
&lt;span itemprop="price">3.50&lt;/span>
&lt;data itemprop="priceCurrency" value="EUR">€&lt;/data>
&lt;dd id="1-description" itemprop="description">
2 boules Café ou Chocolat, 1 boule Vanille, sause café ou chocolat, chantilly

&lt;dt itemscope itemtype="http://schema.org/Product" itemref="2-offer 2-description">
&lt;span itemprop="name">Américaine&lt;/span>
&lt;dd id="2-offer" itemprop="offers" itemscope itemtype="http://schema.org/Offer">
&lt;span itemprop="price">3.50&lt;/span>
&lt;data itemprop="priceCurrency" value="EUR">€&lt;/data>
&lt;dd id="2-description" itemprop="description">
1 boule Crème brûlée, 1 boule Vanille, 1 boule Caramel, chantilly
&lt;/dl></pre>

</div>

<p class="note">The <code>dl</code> element is inappropriate for marking up dialogue. <a
href="#conversations">Examples of how to mark up dialogue</a> are shown below.</p>

Expand All @@ -17962,6 +18083,7 @@ first matching case):&lt;/p&gt;
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Before <code>dd</code> or <code>dt</code> elements inside <code>dl</code> elements.</dd>
<dd>Before <code>dd</code> or <code>dt</code> elements inside <code>div</code> elements that are children of a <code>dl</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>header</code>, <code>footer</code>, <span>sectioning content</span>, or <span>heading content</span> descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
Expand Down Expand Up @@ -18005,6 +18127,7 @@ first matching case):&lt;/p&gt;
<dd>None.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>After <code>dt</code> or <code>dd</code> elements inside <code>dl</code> elements.</dd>
<dd>After <code>dt</code> or <code>dd</code> elements inside <code>div</code> elements that are children of a <code>dl</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
Expand Down Expand Up @@ -18345,8 +18468,10 @@ included with Exhibit B.
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dd>As a child of a <code>dl</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd>If the element is a child of a <code>dl</code> element: one or more <code>dt</code> elements followed by one or more <code>dd</code> elements, optionally intermixed with <span>script-supporting elements</span>.</dd>
<dd>If the element is not a child of a <code>dl</code> element: <span>Flow content</span>.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt><!--TOPIC:DOM APIs-->
Expand All @@ -18359,7 +18484,8 @@ interface <dfn>HTMLDivElement</dfn> : <span>HTMLElement</span> {};</pre>
<p>The <code>div</code> element has no special meaning at all. It <span>represents</span> its
children. It can be used with the <code data-x="attr-class">class</code>, <code
data-x="attr-lang">lang</code>, and <code data-x="attr-title">title</code> attributes to mark up
semantics common to a group of consecutive elements.</p>
semantics common to a group of consecutive elements. It can also be used in a <code>dl</code>
element, wrapping groups of <code>dt</code> and <code>dd</code> elements.</p>

<p class="note">Authors are strongly encouraged to view the <code>div</code> element as an element
of last resort, for when no other element is suitable. Use of more appropriate elements instead of
Expand Down Expand Up @@ -114131,7 +114257,8 @@ interface <dfn>External</dfn> {
<th><code>dd</code></th>
<td>Content for corresponding <code>dt</code> element(s)</td>
<td>none</td>
<td><code>dl</code></td>
<td><code>dl</code>;
<code>div</code>*</td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
Expand Down Expand Up @@ -114191,10 +114318,11 @@ interface <dfn>External</dfn> {

<tr>
<th><code>div</code></th>
<td>Generic flow container</td>
<td>Generic flow container, or container for name-value groups in <code>dl</code> elements</td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span>;
<code>dl</code></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLDivElement</code></td>
Expand All @@ -114208,6 +114336,7 @@ interface <dfn>External</dfn> {
<td><span data-x="Flow content">flow</span></td>
<td><code>dt</code>*;
<code>dd</code>*;
<code>div</code>*;
<span>script-supporting elements</span></td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLDListElement</code></td>
Expand All @@ -114217,7 +114346,8 @@ interface <dfn>External</dfn> {
<th><code>dt</code></th>
<td>Legend for corresponding <code>dd</code> element(s)</td>
<td>none</td>
<td><code>dl</code></td>
<td><code>dl</code>;
<code>div</code>*</td>
<td><span data-x="Flow content">flow</span>*</td>
<td><span data-x="global attributes">globals</span></td>
<td><code>HTMLElement</code></td>
Expand Down

0 comments on commit a7e9222

Please sign in to comment.