updated headings and sections

used modified text of @annevk PR headings and sections section whatwg#3499

Author: stevefaulkner

Diff for: source

@@ -17475,97 +17475,251 @@ interface <dfn interface>HTMLHeadingElement</dfn> : <span>HTMLElement</span> {
 
 
 
-  <h4><dfn>Headings and sections</dfn></h4>
+ <h4><dfn>Headings and sections</dfn></h4>
 
-  <p>The <code>h1</code>&ndash;<code>h6</code> elements are headings.</p>
+  <p><span>Heading content</span> elements have a <dfn>heading level</dfn>, which is 
+  an unsigned integer. It is determined as follows for a given <span>heading content</span> element
+  <var>heading</var>:</p>
 
-  <p>The first element of <span>heading content</span> in an element of <span>sectioning
-  content</span> <span>represents</span> the heading for that section. Subsequent headings of equal
-  or higher <span>rank</span> start new (implied) sections, headings of lower <span>rank</span>
-  start implied subsections that are part of the previous one. In both cases, the element
-  <span>represents</span> the heading of the implied section.</p>
+  <ol>
+  
+   <li>
+    <p>Switch on <var>heading</var>:</p>
 
-  <p>Certain elements are said to be <dfn data-x="sectioning root">sectioning roots</dfn>, including
-  <code>blockquote</code> and <code>td</code> elements. These elements can have their own outlines,
-  but the sections and headings inside these elements do not contribute to the outlines of their
-  ancestors.</p>
+    <dl class="switch">
+     <dt><code>h2</code></dt>
+     <dd>Return 2.</dd>
 
-  <!-- when updating this also update the category index -->
-  <ul class="brief category-list">
-   <li><code>blockquote</code></li>
-   <li><code>body</code></li>
-   <li><code>details</code></li>
-   <li><code>dialog</code></li>
-   <li><code>fieldset</code></li>
-   <li><code>figure</code></li>
-   <li><code>td</code></li>
-  </ul>
+     <dt><code>h3</code></dt>
+     <dd>Return 3.</dd>
+
+     <dt><code>h4</code></dt>
+     <dd>Return 4.</dd>
+
+     <dt><code>h5</code></dt>
+     <dd>Return 5.</dd>
+
+     <dt><code>h6</code></dt>
+     <dd>Return 6.</dd>
+    </dl>
+   </li>
+   
+  </ol>
+
+  <p>A <span>heading content</span> element <span>represents</span> a <dfn data-x="concept-heading">heading</dfn>. 
+  The lower a <span data-x="concept-heading">heading</span>'s <span>heading level</span> is, the more important 
+  the <span data-x="concept-heading">heading</span> is.</p>
+
+  <p>The <dfn>document headings</dfn> are all <span data-x="concept-heading">headings</span> in a
+  document, in <span>tree order</span>.</p>
+
+  <div w-nodev>
 
-  <!-- a document element isn't a sectioning root. This means, for instance, that you don't get an
-  outline if you just have a random XML file with <html:h1> elements in it. Other vocabs need to
-  define what their sectioning root is. -->
+  <p>The <span>document headings</span> must be used for generating document outlines, for
+  example when generating tables of contents. When creating an interactive table of contents,
+  entries should jump the user to the relevant <span data-x="concept-heading">heading</span>.</p>
+
+  </div>
+
+  <p>If a document has a <span data-x="concept-heading">heading</span>, at least a single <span
+  data-x="concept-heading">heading</span> within <span>document headings</span> must have a
+  <span>heading level</span> of 1.</p>
+
+  <p>Each <span data-x="concept-heading">heading</span> following another <span
+  data-x="concept-heading">heading</span> <var>lead</var> in <span>document headings</span> must
+  have a <span>heading level</span> that is less, equal, or 1 greater than <var>lead</var>'s
+  <span>heading level</span>.</p>
+
+  <p class="note">Authors are encouraged to avoid having a <span>sectioning content</span> element
+  <var>section</var> without a <span data-x="concept-heading">heading</span> descendant whose
+  nearest ancestor <span>sectioning content</span> element is not <var>section</var>. I.e., avoid
+  having a section without a heading.</p>
 
   <div class="example">
+   <p>The following example is non-conforming:</p>
 
-   <p>A document can contain multiple top-level headings:</p>
+   <pre><code class="html" data-x="">&lt;body&gt;
+ &lt;h4&gt;Apples&lt;/h4&gt;
+ &lt;p&gt;Apples are fruit.&lt;/p&gt;
+ &lt;section&gt;
+  &lt;h2&gt;Taste&lt;/h2&gt;
+  &lt;p&gt;They taste lovely.&lt;/p&gt;
+ &lt;/section&gt;
+&lt;/body&gt;</code></pre>
 
-   <pre><code class="html">&lt;!DOCTYPE HTML>
-&lt;html lang=en>
-&lt;title>Alphabetic Fruit&lt;/title>
-&lt;h1>Apples&lt;/h1>
-&lt;p>Pomaceous.&lt;/p>
-&lt;h1>Bananas&lt;/h1>
-&lt;p>Edible.&lt;/p>
-&lt;h1>Carambola&lt;/h1>
-&lt;p>Star.&lt;/p></code></pre>
+   <p>It could be written as follows and then it would be conforming:</p>
 
-   <p>This would form the following simple outline consisting of three top-level sections:</p>
+   <pre><code class="html" data-x="">&lt;body&gt;
+ &lt;h1&gt;Apples&lt;/h1&gt;
+ &lt;p&gt;Apples are fruit.&lt;/p&gt;
+ &lt;section&gt;
+  &lt;h2&gt;Taste&lt;/h2&gt;
+  &lt;p&gt;They taste lovely.&lt;/p&gt;
+ &lt;/section&gt;
+&lt;/body&gt;</code></pre>
+
+  </div>
+
+  <div class="example">
+   <p>The following markup fragment:</p>
+
+   <pre><code class="html" data-x="">&lt;body>
+  &lt;hgroup id="document-title">
+    &lt;h1>HTML&lt;/h1>
+    &lt;p>Living Standard — Last Updated 12 August 2016&lt;/p>
+  &lt;/hgroup>
+  &lt;p>Some intro to the document.&lt;/p>
+  &lt;h2>Table of contents&lt;/h2>
+  &lt;ol id=toc>...&lt;/ol>
+  &lt;h2>First section&lt;/h2>
+  &lt;p>Some intro to the first section.&lt;/p>
+&lt;/body></code></pre>
+
+   <p>...results in 3 <span>document headings</span>:</p>
 
    <ol class="brief">
-    <li> Apples
-    <li> Bananas
-    <li> Carambola
+    <li><p><code data-x="">&lt;hgroup id="document-title">...&lt;/hgroup></code> consisting of <code
+    data-x="">&lt;h1>HTML&lt;/h1></code> and <code
+    data-x="">&lt;p>Living Standard — Last Updated 12 August 2016&lt;/p></code>.</p></li>
+
+    <li><p><code data-x="">&lt;h2>Table of contents&lt;/h2></code>.</p></li>
+
+    <li><p><code data-x="">&lt;h2>First section&lt;/h2></code>.</p></li>
    </ol>
 
-   <p>Effectively, the <code>body</code> element is split into three.</p>
+   <p>A rendered view of the <span>document headings</span> might look like:</p>
 
+   <p><img src="/images/outline.svg" width="465" height="120" alt="Top-level section with the
+   heading and associated text &quot;HTML: Living Standard — Last Updated 12 August 2016&quot; and two
+   subsections; &quot;Table of contents&quot; and &quot;First section&quot;."></p>
   </div>
 
+  <div class="example">
+   <p>First, here is a document, which is a book with very short chapters and subsections:</p>
 
-  <h5>Exposing outlines to users</h5>
+   <pre><code class="html" data-x="">&lt;!DOCTYPE HTML>
+&lt;html lang=en>
+&lt;title>The Tax Book (all in one page)&lt;/title>
+&lt;h1>The Tax Book&lt;/h1>
+&lt;h2>Earning money&lt;/h2>
+&lt;p>Earning money is good.&lt;/p>
+&lt;h3>Getting a job&lt;/h3>
+&lt;p>To earn money you typically need a job.&lt;/p>
+&lt;h2>Spending money&lt;/h2>
+&lt;p>Spending is what money is mainly used for.&lt;/p>
+&lt;h3>Cheap things&lt;/h3>
+&lt;p>Buying cheap things often not cost-effective.&lt;/p>
+&lt;h3>Expensive things&lt;/h3>
+&lt;p>The most expensive thing is often not the most cost-effective either.&lt;/p>
+&lt;h2>Investing money&lt;/h2>
+&lt;p>You can lend your money to other people.&lt;/p>
+&lt;h2>Losing money&lt;/h2>
+&lt;p>If you spend money or invest money, sooner or later you will lose money.
+&lt;h3>Poor judgement&lt;/h3>
+&lt;p>Usually if you lose money it's because you made a mistake.&lt;/p></code></pre>
+
+   <p>Its <span>document headings</span> could be presented as follows:</p>
 
-  <p>User agents are encouraged to expose page outlines to users to aid in navigation. This is
-  especially true for non-visual media, e.g. screen readers.</p>
+   <ol class="brief">
+    <li> The Tax Book
+     <ol class="brief">
+      <li> Earning money
+       <ol class="brief">
+        <li> Getting a job
+       </ol>
+      <li> Spending money
+       <ol class="brief">
+        <li> Cheap things
+        <li> Expensive things
+       </ol>
+      <li> Investing money
+      <li> Losing money
+       <ol class="brief">
+        <li> Poor judgement
+       </ol>
+     </ol>
+   </ol>
 
-  <p>However, to mitigate the difficulties that arise from authors misusing <span>sectioning
-  content</span>, user agents are also encouraged to offer a mode that navigates the page using
-  <span>heading content</span> alone.</p>
+   <p>Notice that the <code>title</code> element is not a <span
+   data-x="concept-heading">heading</span>.</p>
+  </div>
 
   <div class="example">
+   <p>A document can contain multiple top-level headings:</p>
 
-   <p>For instance, a user agent could map the arrow keys as follows:</p>
+   <pre><code class="html" data-x="">&lt;!DOCTYPE HTML>
+&lt;html lang=en>
+&lt;title>Alphabetic Fruit&lt;/title>
+&lt;h1>Apples&lt;/h1>
+&lt;p>Pomaceous.&lt;/p>
+&lt;h1>Bananas&lt;/h1>
+&lt;p>Edible.&lt;/p>
+&lt;h1>Carambola&lt;/h1>
+&lt;p>Star.&lt;/p></code></pre>
+  </div>
 
-   <dl>
-    <dt><kbd><kbd>Shift</kbd> + <kbd>&larr; Left</kbd></kbd>
-    <dd>Go to previous section, including subsections of previous sections
+  <div class="example">
+   <p>The following example is non-conforming as it has no <span
+   data-x="concept-heading">heading</span> whose <span>heading level</span> is 1:</p>
 
-    <dt><kbd><kbd>Shift</kbd> + <kbd>&rarr; Right</kbd></kbd>
-    <dd>Go to next section, including subsections of the current section
+   <pre><code class="html" data-x="">&lt;!DOCTYPE HTML>
+&lt;html lang=en>
+&lt;title>Alphabetic Fruit&lt;/title>
+&lt;section>
+ &lt;h2>Apples&lt;/h2>
+ &lt;p>Pomaceous.&lt;/p>
+ &lt;h2>Bananas&lt;/h2>
+ &lt;p>Edible.&lt;/p>
+ &lt;h2>Carambola&lt;/h2>
+ &lt;p>Star.&lt;/p>
+&lt;/section></code></pre>
+  </div>
 
-    <dt><kbd><kbd>Shift</kbd> + <kbd>&uarr; Up</kbd></kbd>
-    <dd>Go to parent section of the current section
+  <div class="example">
+   <p>The following example is non-conforming as the first <span
+   data-x="concept-heading">heading</span>'s <span>heading level</span> is not 1:</p>
 
-    <dt><kbd><kbd>Shift</kbd> + <kbd>&darr; Down</kbd></kbd>
-    <dd>Go to next section, skipping subsections of the current section
-   </dl>
+   <pre><code class="html" data-x="">&lt;!DOCTYPE HTML>
+&lt;html lang=en>
+&lt;title>Feathers on The Site of Encyclopedic Knowledge&lt;/title>
+ &lt;h2>A plea from our caretakers&lt;/h2>
+ &lt;p>Please, we beg of you, send help! We're stuck in the server room!&lt;/p>
+&lt;h1>Feathers&lt;/h1>
+&lt;p>Epidermal growths.&lt;/p></code></pre>
+  </div>
 
-   <p>Plus in addition, the user agent could map the <kbd><kbd>j</kbd></kbd> and
-   <kbd><kbd>k</kbd></kbd> keys to navigating to the previous or next element of <span>heading
-   content</span>, regardless of the section's outline depth and ignoring sections with no
-   headings.</p>
+  <div class="example">
+   <p><code>header</code> elements do not influence the <span>document headings</span> of a
+   document:</p>
 
-  </div>
+   <pre><code class="html" data-x="">&lt;!DOCTYPE HTML>
+&lt;html lang="en">
+&lt;title>We're adopting a child! &mdash; Ray's blog&lt;/title>
+&lt;h1>Ray's blog&lt;/h1>
+&lt;article>
+ &lt;header>
+  &lt;nav>
+   &lt;a href="?t=-1d">Yesterday&lt;/a>;
+   &lt;a href="?t=-7d">Last week&lt;/a>;
+   &lt;a href="?t=-1m">Last month&lt;/a>
+  &lt;/nav>
+  &lt;h2>We're adopting a child!&lt;/h2>
+ &lt;/header>
+ &lt;p>As of today, Janine and I have signed the papers to become
+ the proud parents of baby Diane! We've been looking forward to
+ this day for weeks.&lt;/p>
+&lt;/article>
+&lt;/html></code></pre>
 
+   <p>The document's <span>document headings</span> could be presented as follows:</p>
+
+   <ol class="brief">
+    <li> Ray's blog
+     <ol class="brief">
+      <li> We're adopting a child!
+     </ol>
+   </ol>
+  </div>
 
 
   <h4>Usage summary</h4>