replace current outline algorithm with one based on heading levels #7829
Conversation
The CSS UA styles partial implementation has been left as is https://html.spec.whatwg.org/multipage/rendering.html#sections-and-headings Why partial? refer to https://codepen.io/stevef/pen/ZEvmNPg
|
+1. Within the BBC we have to specifically inform devs that the spec does not represent what is implemented or planned to be implemented. For us at least, this change would have positive real world impact. |
|
This deeply saddens me, but it's the right thing to do. |
|
100% support for this. Maybe removing the outline algorithm makes it possible to find solutions for its use cases that can and will actually be implemented. |
|
As discussed in the thread you link to, we cannot remove the outline algorithm, as documents still have outlines. It instead needs to be based on heading levels, without sectioning complications. |
|
It's hard to see why it's better to keep an outline algorithm that's totally wrong with respect to the outline that documents actually have, than to simply remove it. There's certainly a case for adding back in an algorithm that describes the true outline accurately, but I don't see why the lack of the latter precludes the former. |
used modified text of @annevk PR headings and sections section whatwg#3499
general clean up and closer alignment with @annevk PR whatwg#3499
|
Great! Let us know when the conflicts with the main branch are resolved and then we can work on review. |
|
@domenic conflicts resolved |
after feedback from @mtrootyy whatwg#7829 (review)
|
Thanks. Could you also make sure the build passes? |
@sideshowbarker said he would take a look at that |
Thanks to @sideshowbarker build now passes |
sideshowbarker
force-pushed
the
outline-reality-reset
branch
from
83bc19d
to
e230b44
Compare
This error seems to have been introduced in f5def65, whatwg#7475 — so it’s unclear why CI didn’t catch it there.
Changing the spec source markup to use a p element in hgroup will need to wait until after the spec change lands.
sideshowbarker
force-pushed
the
outline-reality-reset
branch
from
e230b44
to
d7a8d50
Compare
|
Hello, I have a question. What is the difference between a rank and a level in a heading?
In HTML5 and HTML LS, they are called "rank". This time, the term "heading level" has been restored in the Headings and sections but "rank" is still used for heading elements. |
|
Hey @SaekiTominaga , IIRC rank is a concept to determine the level of the heading in a corresponding section. They are not the same thing. Suppose there is a document with three headings: <h1>h1</h1>
<h2>h2</h2>
<h2>h2</h2>This would create the following outline:
Now, if you change the first h2 to h3, what would the outline be? <h1>h1</h1>
<h3>h3</h3>
<h2>h2</h2>It might be surprising but this would yield the same outline (except the text) per the current algorithm.
In this case, the rank in the heading of the first subsection is three, but the level of the heading is two. |
…(instead of heading element) Amends whatwg#7829.
This technique has been removed from the specs. whatwg/html#7829 https://html.spec.whatwg.org/multipage/sections.html#headings-and-outlines
|
Wow, congrats @stevefaulkner! Lovely to see #83 resolved. |
The current guidance on use of `<section>` tags is unclear because: - the approach it recommends (using `aria-labelledby` to use the heading as their accessible name) creates a region landmark but the examples seem to show content that shouldn't be split off into one - from looking through a lot of GDS repos, I couldn't find any code following this pattern - it seems to clash with the current HTML5 spec', which now says you should use `<section>` tags to wrap groupings of content marked by a heading without use of `aria-labelledby` to make the heading the `<section>`s accessible name See HTML5 spec on `<section>`: https://html.spec.whatwg.org/multipage/sections.html#the-section-element By 'region landmark', I mean an element with `role="region"`. The original opinion that this guidance is unclear was stated in this issue: #617 I think a major cause of this confusion comes from the current guidance having been written when the HTML5 spec' still said that `<section>`s should be used with `<h1>`s to create the document outline, something never implemented in any browser: https://www.tpgi.com/html5-document-outline/) This has since been changed: whatwg/html#7829 These changes intend to ensure guidance around use of `<section>` tags is clearer by only referencing them in the bit on region landmarks and making it clear that using them in other ways (without assigning an accessible name) removes any semantics they add. Worth noting that these changes gratefully borrow from https://www.scottohara.me/blog/2018/03/03/landmarks.html
An attempt to rewite the guidance on use of `<section>` tags to solve the problems in #617. I think the current guidance on use of `<section>` tags is unclear because: - the approach it recommends (using `aria-labelledby` to get their accessible name from the heading) creates a region landmark but the examples seem to show content that wouldn't benefit from being in one - from looking through a lot of GDS repos, I couldn't find any code following this pattern - it seems to clash with the current HTML5 spec', which includes similar content examples but doesn't use of `aria-labelledby` to set an accessible name The HTML5 spec' on `<section>`: https://html.spec.whatwg.org/multipage/sections.html#the-section-element). By 'region landmark', I mean an element with `role="region"`. I think a major cause of this confusion comes from the current guidance having been written when the HTML5 spec' still said that `<section>`s should be used with `<h1>`s to create the document outline, something never implemented in any browser: https://www.tpgi.com/html5-document-outline/) This has since been changed: whatwg/html#7829 The spec' now seems to advocate using `<section>`s to identify the scope of a heading. This arguably makes the HTML easier to read but doesn't add any new semantics so I'm wary of including guidance for it here. These changes instead intend to clear up the existing guidance on use of `<section>` tags by making it clear that this approach creates region landmarks and that using them in other ways (without assigning an accessible name) removes any semantics they add. Worth noting that these changes gratefully borrow from https://www.scottohara.me/blog/2018/03/03/landmarks.html Final note: I expect a bit of discussion on this pull request so intend to update the date of the page these changes are in if and when they are agreed to be the correct approach to the issue.
In the current version of the spec, the `body` element belongs to no content category. The sectioning root concept has been removed entirely from the HTML spec in this PR: whatwg/html#7829
This PR is an attempt to bring the HTML spec in line with the decade+ old reality of non-implementation of the outline algorithm in User Agents and the continued presence of misleading content in the HTML spec relating to the outline algorithm.
Notes:
hgroupdefinition to reflect what it actually does/isRelates to:
The CSS UA styles partial implementation has been left as is
https://html.spec.whatwg.org/multipage/rendering.html#sections-and-headings
Why partial? refer to https://codepen.io/stevef/pen/ZEvmNPg
/dom.html ( diff )
/form-elements.html ( diff )
/grouping-content.html ( diff )
/index.html ( diff )
/indices.html ( diff )
/infrastructure.html ( diff )
/interaction.html ( diff )
/interactive-elements.html ( diff )
/links.html ( diff )
/sections.html ( diff )
/tables.html ( diff )