diff --git a/source b/source index 5f6f05ad1cf..240db24d17a 100644 --- a/source +++ b/source @@ -2367,15 +2367,13 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
Applications and tools that process HTML and XML documents for reasons other than to either render the documents or check them for conformance should act in accordance with the semantics of the documents that they process.
-A tool that generates document outlines but - increases the nesting level for each paragraph and does not increase the nesting level for each - section would not be conforming.
- +A tool that generates document outlines but increases the nesting level for + each paragraph and does not increase the nesting level for headings would not be conforming.
Sectioning content is content that defines the scope of headings and footers.
+ content">headings and footers, and determines the + heading level ofh1
and hgroup
elements.
section
Each sectioning content element potentially has a heading and an - outline. See the section on headings and sections for further - details.
- -There are also certain elements that are sectioning - roots. These are distinct from sectioning content, but they can also have an - outline.
+See the section on headings and sections for further details.
html
element.The section
element is not a generic
container element. When an element is needed only for styling purposes or as a convenience for
scripting, authors are encouraged to use the div
element instead. A general rule is
- that the section
element is appropriate only if the element's contents would be
- listed explicitly in the document's outline.
section
element is appropriate when used in conjunction with a heading.
HTMLHeadingElement
.These elements represent headings for their sections.
-The semantics and meaning of these elements are defined in the section on headings and sections.
-These elements have a rank given by the number in their name. The h1
- element is said to have the highest rank, the h6
element has the lowest rank, and two
- elements with the same name have equal rank.
As far as their respective document outlines (their heading and section structures) are - concerned, these two snippets are semantically equivalent:
+As far as their respective heading levels are concerned, + these two snippets are semantically equivalent:
<body>
<h1>Let's call it a draw(ing surface)</h1>
@@ -16263,7 +16250,7 @@ interface HTMLHeadingElement : HTMLElement {
The two styles can be combined, for compatibility with legacy tools while still
future-proofing for when that compatibility is no longer needed. This third snippet again has the
- same outline as the previous two:
+ same heading levels as the previous two:
<body>
<h1>Let's call it a draw(ing surface)</h1>
@@ -16283,12 +16270,10 @@ interface HTMLHeadingElement : HTMLElement {
<h2>Paths</h2>
</section>
</body>
-
hgroup
elementHTMLElement
.The hgroup
element represents the heading of a section, which
- consists of all the h1
–h6
element children of the
- hgroup
element. The element is used to group a set of
- h1
–h6
elements when the heading has multiple levels, such as
- subheadings, alternative titles, or taglines.
The hgroup
element can be used to group a set of
+ h1
–h6
elements for a heading that has multiple levels, such as subheadings, alternative
+ titles, or taglines.
The rank of an hgroup
element is the rank of the highest-ranked
- h1
–h6
element descendant of the hgroup
element, if
- there are any such elements, or otherwise the same as for an h1
element (the highest
- rank). Other h1
–h6
elements of heading content in the
- hgroup
element indicate subheadings or subtitles or (secondary) alternative
- titles.
The section on headings and sections defines how hgroup
elements are
- assigned to individual sections.
The remainder of the semantics and meaning of the hgroup
element, including what
+ it represents, are defined in the section on headings and sections.
Here are some examples of valid headings.
<hgroup>
@@ -16338,14 +16314,12 @@ interface HTMLHeadingElement : HTMLElement {
<h2>Or: How I Learned to Stop Worrying and Love the Bomb</h2>
</hgroup>
- The point of using hgroup
in these examples is to prevent the h2
- element (which acts as a secondary title) from creating a separate section of its own in any
- outline and to instead cause the contents of the h2
to be shown in
- rendered output from the outline algorithm in some way to indicate that it is not
- the title of a separate section but instead just a secondary title in a group of titles.
The point of using hgroup
in these examples is to create a single heading
+ consisting of two pieces (the primary title in the h1
element and the secondary
+ title in the h2
element).
How a user agent exposes such multi-level headings in user interfaces (e.g. in tables of +
How a user agent exposes such multi-level headings in user interfaces (e.g., in tables of contents or search results) is left open to implementers, as it is a user interface issue. The first example above could be rendered as:
@@ -16360,7 +16334,6 @@ interface HTMLHeadingElement : HTMLElement {The reality dysfunction Space is not the only void-
h1
gives
the (primary) title while the second gives the (secondary) alternative title. Even though both
the title and alternative title are marked up with h1
elements, in a rendered view
- of output from the outline algorithm, the second h1
in the
- hgroup
will be shown in some way that clearly indicates it is secondary; for
- example:
+ the second h1
in the hgroup
will likely be shown in some way that
+ clearly indicates it is secondary; for example:
In a US publication:
The Avengers (Avengers Assemble)
In a UK publication:
Avengers Assemble (The Avengers)-
In the following example, an hgroup
element is used to mark up a two-level
heading in a wizard-style dialog box:
The header
element is not sectioning content; it doesn't
- introduce a new section.
The header
element is not sectioning content.
In this example, the page has a page heading given by the h1
element, and two
- subsections whose headings are given by h2
elements. The content after the
- header
element is still part of the last subsection started in the
- header
element, because the header
element doesn't take part in the
- outline algorithm.
Another example header for a game:
<body>
<header>
@@ -16508,15 +16471,12 @@ Space is not the only void
<li><a href="/download">Download</a>
</ul>
</nav>
- <h2>Important News</h2> <!-- this starts a second subsection -->
- <!-- this is part of the subsection entitled "Important News" -->
+ <h2>Important News</h2>
<p>To play today's games you will need to update your client.</p>
- <h2>Games</h2> <!-- this starts a third subsection -->
+ <h2>Games</h2>
</header>
<p>You have three active games:</p>
- <!-- this is still part of the subsection entitled "Games" -->
...
-
The footer
element represents a footer for its nearest ancestor
- sectioning content or sectioning root element. A footer typically
- contains information about its section such as who wrote it, links to related documents, copyright
- data, and the like.
body
element. A footer typically contains
+ information about its section, such as who wrote it, links to related documents, copyright data,
+ and the like.
When the footer
element contains entire sections, they represent appendices, indexes, long colophons, verbose license
@@ -16558,11 +16518,10 @@ Space is not the only void
Footers don't necessarily have to appear at the end of a section, though they usually do.
-When the nearest ancestor sectioning content or sectioning root - element is the body element, then it applies to the whole page.
+When the nearest ancestor sectioning content or body
element is
+ the body element, then it applies to the whole page.
The footer
element is not sectioning content; it doesn't
- introduce a new section.
The footer
element is not sectioning content.
The h1
–h6
elements and the hgroup
element are
- headings.
Heading content elements have a heading level, which is either null or + 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.
+If heading has a parent hgroup
element, then return null.
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.
Switch on heading:
- -blockquote
body
details
dialog
fieldset
figure
td
h2
h3
Sectioning content elements are always considered subsections of their nearest - ancestor sectioning root or their nearest ancestor element of sectioning - content, whichever is nearest, regardless of what implied sections other headings may have - created.
+h4
h5
h6
Return the number of ancestor sectioning content elements + 1.
A heading content element whose heading level is non-null + represents a heading. The lower a heading's heading level is, the more important the + heading is.
+ +I.e., headings are heading
+ content elements whose parent is not an hgroup
element.
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.
-For the following fragment:
-<body>
- <h1>Foo</h1>
- <h2>Bar</h2>
- <blockquote>
- <h3>Bla</h3>
- </blockquote>
- <p>Baz</p>
- <h2>Quux</h2>
- <section>
- <h3>Thud</h3>
- </section>
- <p>Grunt</p>
-</body>
- ...the structure would be:
-body
section, containing the "Grunt" paragraph)
- section
section)
- Notice how the section
ends the earlier implicit section so that a later
- paragraph ("Grunt") is back at the top level.
Sections may contain headings of any rank, but authors are strongly encouraged to
- either use only h1
elements, or to use elements of the appropriate rank
- for the section's nesting level.
If a document has a heading, at least a single heading within document headings must have a + heading level of 1.
-Authors are also encouraged to explicitly wrap sections in elements of sectioning - content, instead of relying on the implicit sections generated by having multiple headings - in one element of sectioning content.
+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.
For example, the following is correct:
+The following example is non-conforming:
<body>
<h4>Apples</h4>
@@ -16874,14 +16819,10 @@ Space is not the only void
<section>
<h2>Taste</h2>
<p>They taste lovely.</p>
- <h6>Sweet</h6>
- <p>Red apples are sweeter than green ones.</p>
- <h1>Color</h1>
- <p>Apples come in various colors.</p>
</section>
</body>
- However, the same document would be more clearly expressed as:
+It could be written as follows and then it would be conforming:
<body>
<h1>Apples</h1>
@@ -16889,22 +16830,12 @@ Space is not the only void
<section>
<h2>Taste</h2>
<p>They taste lovely.</p>
- <section>
- <h3>Sweet</h3>
- <p>Red apples are sweeter than green ones.</p>
- </section>
- </section>
- <section>
- <h2>Color</h2>
- <p>Apples come in various colors.</p>
</section>
</body>
- Both of the documents above are semantically identical and would produce the same outline in - compliant user agents.
- -This third example is also semantically identical, and might be easier to maintain (e.g. if - sections are often moved around in editing):
+It could also be written as follows, and this might be preferable if the sections move around
+ a lot, as the heading level of h1
elements depends on the number of
+ ancestor sectioning content elements:
<body>
<h1>Apples</h1>
@@ -16912,51 +16843,12 @@ Space is not the only void
<section>
<h1>Taste</h1>
<p>They taste lovely.</p>
- <section>
- <h1>Sweet</h1>
- <p>Red apples are sweeter than green ones.</p>
- </section>
- </section>
- <section>
- <h1>Color</h1>
- <p>Apples come in various colors.</p>
</section>
</body>
- This final example would need explicit style rules to be rendered well in legacy browsers. - Legacy browsers without CSS support would render all the headings as top-level headings.
- -This section defines an algorithm for creating an outline for a sectioning content - element or a sectioning root element. It is defined in terms of a walk over the nodes - of a DOM tree, in tree order, with each node being visited when it is entered and when it - is exited during the walk.
-The outline for a sectioning content element or a sectioning - root element consists of a list of one or more potentially nested sections. The element for which an outline is created - is said to be the outline's owner.
- -A section is a container that corresponds to some nodes in
- the original DOM tree. Each section can have one heading associated with it, and can contain any
- number of further nested sections. The algorithm for the outline also
- associates each node in the DOM tree with a particular section and potentially a heading.
- (The sections in the outline aren't section
elements, though some may correspond to
- such elements — they are merely conceptual sections.)
The following markup fragment:
<body>
@@ -16971,418 +16863,27 @@ Space is not the only void
<p>Some intro to the first section.</p>
</body>
- ...results in the following outline being created for the body
node (and thus the
- entire document):
...results in 3 document headings:
Section created for body
node.
Associated with heading <hgroup
- id="document-title">...</hgroup>
consisting of primary heading <h1>HTML</h1>
and secondary heading <h2>Living
- Standard — Last Updated 12 August 2016</h2>
.
Also associated with the paragraph <p>Some intro to the
- document.</p>
(though it likely would not be shown in a rendered view of the
- outline).
Nested sections:
-Section implied for first h2
element.
Associated with heading <h2>Table of contents</h2>
.
Also associated with the ordered list <ol id=toc>...</ol>
- (though it likely would not be shown in a rendered view of the outline).
No nested sections.
-Section implied for second h2
element.
Associated with heading <h2>First section</h2>
.
Also associated with the paragraph <p>Some intro to the first
- section.</p>
(though it likely would not be shown in a rendered view of the
- outline).
No nested sections.
-<hgroup id="document-title">...</hgroup>
consisting of <h1>HTML</h1>
and <h2>Living Standard — Last Updated 12 August 2016</h2>
.
<h2>Table of contents</h2>
.
<h2>First section</h2>
.
The following image shows what a rendered view of the outline might look like.
+A rendered view of the document headings might look like:
The algorithm that must be followed during a walk of a DOM subtree rooted at a sectioning - content element or a sectioning root element to determine that element's - outline is as follows:
- -Let current outline target be null. (It holds the element whose - outline is being created.)
Let current section be null. (It holds a pointer to a section, so that elements in the DOM can all be associated with a - section.)
Create a stack to hold elements, which is used to handle nesting. Initialize this stack to - empty.
Walk over the DOM in tree order, starting with the sectioning - content element or sectioning root element at the root of the subtree for - which an outline is to be created, and trigger the first relevant step below for each element as - the walk enters and exits it.
- -The element being exited is a heading content element or an
- element with a hidden
attribute.
Pop that element from the stack.
- -hidden
attributeDo nothing.
hidden
attributePush the element being entered onto the stack. (This causes the algorithm to skip that - element and any descendants of the element.)
- -Run these steps:
- -If current outline target is not null, then:
- -If the current section has no heading, create an implied - heading and let that be the heading for the current section.
Push current outline target onto the stack.
Let current outline target be the element that is being - entered.
Let current section be a newly created section for the current outline target - element.
Associate current outline target with current - section.
Let there be a new outline for the new current outline - target, initialized with just the new current section as the only - section in the outline.
Run these steps:
- -If the current section has no heading, create an implied heading - and let that be the heading for the current section.
Pop the top element from the stack, and let the current outline - target be that element.
Let current section be the last section in the - outline of the current outline target element.
Append the outline of the sectioning content element being - exited to the current section. (This does not change which section is - the last section in the outline.)
Run these steps:
- -If current outline target is not null, push current outline target onto the stack.
Let current outline target be the element that is being - entered.
Let current outline target's parent section be current section.
Let current section be a newly created section for the current outline target - element.
Let there be a new outline for the new current outline - target, initialized with just the new current section as the only - section in the outline.
Run these steps:
- -If the current section has no heading, create an implied heading - and let that be the heading for the current section.
Let current section be current outline - target's parent section.
Pop the top element from the stack, and let the current outline - target be that element.
The current outline target is the element being exited, - and it is the sectioning content element or a sectioning root - element at the root of the subtree for which an outline is being generated.
- -If the current section has no heading, create an implied heading and - let that be the heading for the current section.
- -Skip to the next step in the overall set of steps. (The walk is over.)
- -If the current section has no heading, let the element being entered be - the heading for the current section.
- -If the element being entered is an hgroup
element, that
- hgroup
as a whole is a multi-level heading for the current
- section, with the highest-ranked
- h1
–h6
descendant of the hgroup
providing the
- primary heading for the current section, and with other
- h1
–h6
descendants of the hgroup
providing
- secondary headings for the current section.
Otherwise, if the element being entered has a rank equal to or higher than the - heading of the last section of the outline of the current outline - target, or if the heading of the last section of the outline of the current outline target is an implied heading, then create a new section and append it to the outline of the current outline target element, so that this new section is the new last - section of that outline. Let current section be that new section. Let the - element being entered be the new heading for the current section.
- -Otherwise, run these substeps:
- -Let candidate section be current - section.
Heading loop: If the element being entered has a rank lower than - the rank of the heading of the candidate section, then create a new - section, and append it to candidate - section. (This does not change which section is the last section in the outline.) Let - current section be this new section. Let the element being entered be the - new heading for the current section. Abort these substeps.
- -Let new candidate section be the section that contains candidate section in - the outline of current outline target.
Let candidate section be new candidate - section.
Return to the step labeled heading loop.
Push the element being entered onto the stack. (This causes the algorithm to skip any - descendants of the element.)
- -Recall that h1
has the highest rank, and h6
- has the lowest rank.
Do nothing.
In addition, whenever the walk exits a node, after doing the steps - above, if the node is not associated with a section yet, - associate the node with the section current - section.
- -Associate all non-element nodes that are in the subtree for which an outline is being - created with the section with which their parent element is - associated.
Associate all nodes in the subtree with the heading of the section with which they are associated, if any.
The tree of sections created by the algorithm above, or a proper subset thereof, must be used - when generating document outlines, for example when generating tables of contents.
- -The outline created for the body element of a Document
is the
- outline of the entire document.
When creating an interactive table of contents, entries should jump the user to the relevant - sectioning content element, if the section was - created for a real element in the original document, or to the relevant heading - content element, if the section in the tree was - generated for a heading in the above process.
- -Selecting the first section of the document
- therefore always takes the user to the top of the document, regardless of where the first heading
- in the body
is to be found.
The outline depth of a heading content element associated with a section section is the number of sections that are ancestors of section in the
- outermost outline that section finds itself in when the outlines of its Document
's elements are created, plus 1. The
- outline depth of a heading content element not associated with a section is 1.
User agents should provide default headings for sections that do not have explicit section - headings.
- -Consider the following snippet:
- -<body>
- <nav>
- <p><a href="/">Home</a></p>
- </nav>
- <p>Hello world.</p>
- <aside>
- <p>My cat is cute.</p>
- </aside>
-</body>
-
- Although it contains no headings, this snippet has three sections: a document (the
- body
) with two subsections (a nav
and an aside
). A user
- agent could present the outline as follows:
These default headings ("Untitled document", "Navigation", "Sidebar") are not specified by - this specification, and might vary with the user's language, the page's language, the user's - preferences, the user agent implementer's preferences, etc.
- -The following JavaScript function shows how the tree walk could be implemented. The root argument is the root of the tree to walk (either a sectioning - content element or a sectioning root element), and the enter and exit arguments are callbacks that are called with - the nodes as they are entered and exited.
- -function (root, enter, exit) {
- var node = root;
- start: while (node) {
- enter(node);
- if (node.firstChild) {
- node = node.firstChild;
- continue start;
- }
- while (node) {
- exit(node);
- if (node == root) {
- node = null;
- } else if (node.nextSibling) {
- node = node.nextSibling;
- continue start;
- } else {
- node = node.parentNode;
- }
- }
- }
-}
-
- The following document shows a straight-forward application of the outline - algorithm. First, here is the document, which is a book with very short chapters and - subsections:
+First, here is a document, which is a book with very short chapters and subsections:
<!DOCTYPE HTML>
<html lang=en>
@@ -17405,7 +16906,7 @@ Space is not the only void
<h3>Poor judgement</h3>
<p>Usually if you lose money it's because you made a mistake.</p>
- This book would form the following outline:
+Its document headings could be presented as follows:
Notice that the title
element does not participate in the outline.
Notice that the title
element is not a heading.
Here is a similar document, but this time using section
elements to get the same
- effect:
Here is a similar document, but this time using h1
and section
+ elements to get the same effect:
<!DOCTYPE HTML>
<html lang=en>
@@ -17473,7 +16973,7 @@ Space is not the only void
</section>
</section>
- This book would form the same outline:
+Its document headings could be presented identically:
A document can contain multiple top-level headings:
<!DOCTYPE HTML>
@@ -17510,26 +17008,11 @@ Space is not the only void
<p>Edible.</p>
<h1>Carambola</h1>
<p>Star.</p>
-
- This would form the following simple outline consisting of three top-level sections:
- -Effectively, the body
element is split into three.
Mixing both the h1
–h6
model and the
- section
/h1
model can lead to some unintuitive results.
Consider for example the following, which is just the previous example but with the contents
- of the (implied) body
wrapped in a section
:
The following example is non-conforming as it has no heading whose heading level is 1:
<!DOCTYPE HTML>
<html lang=en>
@@ -17542,32 +17025,11 @@ Space is not the only void
<h1>Carambola</h1>
<p>Star.</p>
</section>
-
- The resulting outline would be:
- -This result is described as unintuitive because it results in three subsections even
- though there's only one section
element. Effectively, the section
is
- split into three, just like the implied body
element in the previous example.
(In this example, "(untitled page)" is the implied heading for the body
- element, since it has no explicit heading.)
Headings never rise above other sections. Thus, in the following example, the first
- h1
does not actually describe the page header; it describes the header for the
- second half of the page:
The following example is non-conforming as the first heading's heading level is not 1:
<!DOCTYPE HTML>
<html lang=en>
@@ -17578,24 +17040,11 @@ Space is not the only void
</section>
<h1>Feathers</h1>
<p>Epidermal growths.</p>
-
- The resulting outline would be:
- -Thus, when an article
element starts with a nav
block and only later
- has its heading, the result is that the nav
block is not part of the same section as
- the rest of the article
in the outline. For instance, take this document:
header
elements do not influence the document headings of a
+ document:
<!DOCTYPE HTML>
<html lang="en">
@@ -17616,26 +17065,17 @@ Space is not the only void
</article>
</html>
- The resulting outline would be:
+The document's document headings could be presented as follows:
Also worthy of note in this example is that the header
element has no effect
- whatsoever on the document outline.
The hgroup
element can be used for subheadings. For example:
<!DOCTYPE HTML>
@@ -17651,12 +17091,14 @@ Space is not the only void
<h2> 12:00 to 18:00 </h2>
</hgroup>
<p>We study.</p>
-<hgroup>
- <h2>Additional Commentary</h2>
- <h3>Because not all this is necessarily true</h3>
- <h6>Ok it's almost certainly not true</h6>
-</hgroup>
-<p>Yeah we probably play, rather than study.</p>
+<section>
+ <hgroup>
+ <h2>Additional Commentary</h2>
+ <h3>Because not all this is necessarily true</h3>
+ <h6>Ok it's almost certainly not true</h6>
+ </hgroup>
+ <p>Yeah we probably play, rather than study.</p>
+</section>
<hgroup>
<h1> The evening </h1>
<h2> 18:00 to 00:00 </h2>
@@ -17669,13 +17111,14 @@ Space is not the only void
<p>We play some more.</p>
</html>
- The resulting outline would be:
+The document's document headings could be presented as follows:
But so would the following:
+And so would the following:
The following would also be valid, though maybe less practical in most contexts:
- -The morning -
06:00 to 12:00 -
The afternoon -
12:00 to 18:00 -
Additional Commentary -
Because not all this is necessarily true -
Ok it's almost certainly not true -
The evening -
18:00 to 00:00 -
The night -
00:00 to 06:00 -
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.
- -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.
- -For instance, a user agent could map the arrow keys as follows:
- -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.
-h1
–h6
- <h1>The Guide To Music On The Playa</h1>
<h2>The Main Stage</h2>
@@ -17849,7 +17237,7 @@ Space is not the only void
hgroup
- <hgroup>
<h1>Burning Music</h1>
@@ -18162,8 +17550,6 @@ of Gralmond's winters.</p>
- The hr
element does not affect the document's
- outline.
pre
elementtr
element.header
, footer
,
sectioning content, or heading content descendants.colspan
:heading
:heading()
The :heading
pseudo-class must match any
+ element that is a heading.
The :heading()
functional
+ pseudo-class accepts a level.
+ Level must be a positive
+ <integer>. The :heading()
+ functional pseudo-class must match any element that is a heading whose heading level is level.
:defined
video
(if the controls
attribute is present)
- blockquote
;
- body
;
- details
;
- dialog
;
- fieldset
;
- figure
;
- td
-