Skip to content

Commit

Permalink
updated headings and sections
Browse files Browse the repository at this point in the history 
used modified text of @annevk PR headings and sections section whatwg#3499
  • Loading branch information
@stevefaulkner
stevefaulkner committed Apr 18, 2022
1 parent f86c397 commit e96100f
Showing 1 changed file with 215 additions and 61 deletions.
276 changes: 215 additions & 61 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down

0 comments on commit e96100f

Please sign in to comment.