From e96100f86c66294f7b87432910b6ee9ed5389e10 Mon Sep 17 00:00:00 2001 From: stevefaulkner Date: Mon, 18 Apr 2022 22:37:00 +0100 Subject: [PATCH] updated headings and sections used modified text of @annevk PR headings and sections section https://github.com/whatwg/html/pull/3499 --- source | 276 ++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 215 insertions(+), 61 deletions(-) diff --git a/source b/source index 109f5a7a1fa..fcf22fb8d37 100644 --- a/source +++ b/source @@ -17475,97 +17475,251 @@ interface HTMLHeadingElement : HTMLElement { -

Headings and sections

+

Headings and sections

-

The h1–h6 elements are headings.

+

Heading content elements have a heading level, which is + an unsigned integer. It is determined as follows for a given heading content element + heading:

-

The first element of heading content in an element of sectioning - content represents the heading for that section. Subsequent headings of equal - or higher rank start new (implied) sections, headings of lower rank - start implied subsections that are part of the previous one. In both cases, the element - represents the heading of the implied section.

+
    + +
  1. +

    Switch on heading:

    -

    Certain elements are said to be sectioning roots, including - blockquote and td 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.

    +
    +
    h2
    +
    Return 2.
    - -
      -
    • blockquote
      • -
    • body
      • -
    • details
      • -
    • dialog
      • -
    • fieldset
      • -
    • figure
      • -
    • td
      • -
    +
    h3
    +
    Return 3.
    + +
    h4
    +
    Return 4.
    + +
    h5
    +
    Return 5.
    + +
    h6
    +
    Return 6.
    +
    +
    2. + +
+ +

A heading content element represents a heading. + The lower a heading's heading level is, the more important + the heading is.

+ +

The document headings are all headings in a + document, in tree order.

+ +
- +

The document headings 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 heading.

+ +
+ +

If a document has a heading, at least a single heading within document headings must have a + heading level of 1.

+ +

Each heading following another heading lead in document headings must + have a heading level that is less, equal, or 1 greater than lead's + heading level.

+ +

Authors are encouraged to avoid having a sectioning content element + section without a heading descendant whose + nearest ancestor sectioning content element is not section. I.e., avoid + having a section without a heading.

+

The following example is non-conforming:

-

A document can contain multiple top-level headings:

+ 
<body>
+ <h4>Apples</h4>
+ <p>Apples are fruit.</p>
+ <section>
+  <h2>Taste</h2>
+  <p>They taste lovely.</p>
+ </section>
+</body>
- 
<!DOCTYPE HTML>
-<html lang=en>
-<title>Alphabetic Fruit</title>
-<h1>Apples</h1>
-<p>Pomaceous.</p>
-<h1>Bananas</h1>
-<p>Edible.</p>
-<h1>Carambola</h1>
-<p>Star.</p>
+

It could be written as follows and then it would be conforming:

-

This would form the following simple outline consisting of three top-level sections:

+ 
<body>
+ <h1>Apples</h1>
+ <p>Apples are fruit.</p>
+ <section>
+  <h2>Taste</h2>
+  <p>They taste lovely.</p>
+ </section>
+</body>
+ +
+ +
+

The following markup fragment:

+ + 
<body>
+  <hgroup id="document-title">
+    <h1>HTML</h1>
+    <p>Living Standard — Last Updated 12 August 2016</p>
+  </hgroup>
+  <p>Some intro to the document.</p>
+  <h2>Table of contents</h2>
+  <ol id=toc>...</ol>
+  <h2>First section</h2>
+  <p>Some intro to the first section.</p>
+</body>
+ +

...results in 3 document headings:

    -
  1. Apples -
  2. Bananas -
  3. Carambola +

  4. <hgroup id="document-title">...</hgroup> consisting of <h1>HTML</h1> and <p>Living Standard — Last Updated 12 August 2016</p>.

    5. + +

  5. <h2>Table of contents</h2>.

    6. + +

  6. <h2>First section</h2>.

-

Effectively, the body element is split into three.

+

A rendered view of the document headings might look like:

+

Top-level section with the + heading and associated text "HTML: Living Standard — Last Updated 12 August 2016" and two + subsections; "Table of contents" and "First section".

+
+

First, here is a document, which is a book with very short chapters and subsections:

-
Exposing outlines to users
+ 
<!DOCTYPE HTML>
+<html lang=en>
+<title>The Tax Book (all in one page)</title>
+<h1>The Tax Book</h1>
+<h2>Earning money</h2>
+<p>Earning money is good.</p>
+<h3>Getting a job</h3>
+<p>To earn money you typically need a job.</p>
+<h2>Spending money</h2>
+<p>Spending is what money is mainly used for.</p>
+<h3>Cheap things</h3>
+<p>Buying cheap things often not cost-effective.</p>
+<h3>Expensive things</h3>
+<p>The most expensive thing is often not the most cost-effective either.</p>
+<h2>Investing money</h2>
+<p>You can lend your money to other people.</p>
+<h2>Losing money</h2>
+<p>If you spend money or invest money, sooner or later you will lose money.
+<h3>Poor judgement</h3>
+<p>Usually if you lose money it's because you made a mistake.</p>
+ +

Its document headings could be presented as follows:

-

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.

+
    +
  1. The Tax Book +
      +
    1. Earning money +
        +
      1. Getting a job +
      +
    2. Spending money +
        +
      1. Cheap things +
      2. Expensive things +
      +
    3. Investing money +
    4. Losing money +
        +
      1. Poor judgement +
      +
    +
-

However, to mitigate the difficulties that arise from authors misusing sectioning - content, user agents are also encouraged to offer a mode that navigates the page using - heading content alone.

+

Notice that the title element is not a heading.

+
+

A document can contain multiple top-level headings:

-

For instance, a user agent could map the arrow keys as follows:

+ 
<!DOCTYPE HTML>
+<html lang=en>
+<title>Alphabetic Fruit</title>
+<h1>Apples</h1>
+<p>Pomaceous.</p>
+<h1>Bananas</h1>
+<p>Edible.</p>
+<h1>Carambola</h1>
+<p>Star.</p>
+
-
-
Shift + ← Left -
Go to previous section, including subsections of previous sections +
+

The following example is non-conforming as it has no heading whose heading level is 1:

-
Shift + → Right -
Go to next section, including subsections of the current section + 
<!DOCTYPE HTML>
+<html lang=en>
+<title>Alphabetic Fruit</title>
+<section>
+ <h2>Apples</h2>
+ <p>Pomaceous.</p>
+ <h2>Bananas</h2>
+ <p>Edible.</p>
+ <h2>Carambola</h2>
+ <p>Star.</p>
+</section>
+ -
Shift + ↑ Up -
Go to parent section of the current section +
+

The following example is non-conforming as the first heading's heading level is not 1:

-
Shift + ↓ Down -
Go to next section, skipping subsections of the current section -
+ 
<!DOCTYPE HTML>
+<html lang=en>
+<title>Feathers on The Site of Encyclopedic Knowledge</title>
+ <h2>A plea from our caretakers</h2>
+ <p>Please, we beg of you, send help! We're stuck in the server room!</p>
+<h1>Feathers</h1>
+<p>Epidermal growths.</p>
+ -

Plus in addition, the user agent could map the j and - k keys to navigating to the previous or next element of heading - content, regardless of the section's outline depth and ignoring sections with no - headings.

+
+

header elements do not influence the document headings of a + document:

-
+ 
<!DOCTYPE HTML>
+<html lang="en">
+<title>We're adopting a child! — Ray's blog</title>
+<h1>Ray's blog</h1>
+<article>
+ <header>
+  <nav>
+   <a href="?t=-1d">Yesterday</a>;
+   <a href="?t=-7d">Last week</a>;
+   <a href="?t=-1m">Last month</a>
+  </nav>
+  <h2>We're adopting a child!</h2>
+ </header>
+ <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.</p>
+</article>
+</html>
+

The document's document headings could be presented as follows:

+ +
    +
  1. Ray's blog +
      +
    1. We're adopting a child! +
    +
+

Usage summary