Update outline algorithm #794

jonathantneal · 2017-02-12T15:33:21Z

As written, the outline algorithm may incorrectly take into account sectioning elements without headings as effecting the outline depth of headings nested more deeply.

How should this operate, and (how) should the specification be updated?

I'm also willing to create a ponyfill for this if Steve would provide an explicit expectation.

jakearchibald · 2017-02-13T14:33:05Z

The example given is:

<body>
<section>
<section>
<section>
<h4>Heading</h4>
</section>
</section>
</section>
</body>

Which produces:

Untitled Section
1. Untitled Section
  1. Untitled Section
    1. Heading

I'm not sure what to do about this, if anything. Flattening could be bad. Another case where we need some decent evidence.

stevefaulkner · 2017-02-13T14:45:42Z

I'm not sure what to do about this, if anything. Flattening could be bad. Another case where we need some decent evidence.

am unclear why flattening would be bad? In this case I would suggest ignore untitled sections in calculating the level of the heading.

stevefaulkner · 2017-02-13T14:51:06Z

Also in the case where there is no heading scoped to body I suggest that a heading like this should actually be a level 1 heading (rather than level 2) if empty sections are ignored.

<body>
<section>
<section>
<section>
<h4>Heading level 1</h4>
</section>
</section>
</section>
</body>

stevefaulkner · 2017-02-13T15:06:21Z

@jakearchibald

I am a heading with a level of 3

I think its a heading a level of 4

<body>
<h4>Heading level 1</h4>
<section>
<h4>Heading level 2</h4>
<section>
<h4>Heading level 3</h4>
<section>
<h4>Heading level 4</h4>
</section>
</section>
</section>
</body>

Marat-Tanalin · 2017-02-13T15:10:25Z

It probably makes sense to clarify here that flattening (effectively removing a redundant sectioning wrapper) should only take place if the wrapper does not contain anything except another sectioning element. So this:

<section>
    <section>
        <h4>Heading</h4>
    </section>
</section>

would be treated as:

<section>
        <h4>Heading</h4>
</section>

While this:

<section>
    Some text before

    <section>
        <h4>Heading</h4>
    </section>

    Or after
</section>

would not be flattened in any way.

Marat-Tanalin · 2017-02-13T15:14:11Z

Btw, AT (or an outline algorithm that AT rely on) could probably be smart enough to be able to expose headingless sections by using a starting part of its text content instead of a heading.

jakearchibald · 2017-02-13T16:23:48Z

@stevefaulkner

I think its a heading a level of 4

Ah, copy+paste error, sorry.

am unclear why flattening would be bad?

<h1>My article</h1>

<p>…</p>

<section>
  <h1>Comments</h1>
  <section class="comment">
    <h1>Rethinking the whole thing</h1>
    <p>Well actually…</p>
    <section>
      <h1>A specific problem:</h1>
      <p>…</p>
    </section>
  </section>

  <section class="comment">
    <p>I agree, but there's one thing I don't like…</p>
    <section>
      <h1>Concerns about the shed colour</h1>
      <p>…</p>
    </section>
  </section>
</section>

In this case, would flattening break the aggregation of the comments? Specifically, is <p>I agree, but there's one thing I don't like…</p> no longer part of a comment?

If so, I'm not sure if that's worse than presenting it as a section without a heading.

chaals · 2017-02-13T16:37:51Z

As noted, I think we need evidence from reality, but in principle section has always been a sectioning element, whereas if you wanted to group stuff you could pile on divs to your heart's content. So according to historical specs, we probably should not flatten section even if it is empty - but reality trumps fine ideas here.

I'd like to discover that people actually get this right an overwhelming majority of the time, because that would simplify what we need to do, and make me feel good about people.

Second preference is to find that close to nobody gets it right - while it might make me feel marginally less good about people, I would be even more confident that a change would have minimal legacy impact: most new stuff would be made by people doing what they always did, or by people who really work hard to follow the spec and are far more likely to continue to get it right, so we would only break a few things that shipped in the last few or next few years and are an historical anomaly.

We get a problem if we discover that there's maybe a 2:1 ratio or something, since whatever we do then is going to break lots of stuff :(

alrdytaken · 2017-02-16T23:44:10Z

I'm not quite sure why a Sectioning content with no content but another Sectioning content would exist. <section> and <article> for example both state:

A general rule is that the section (article) element is appropriate only if the element’s contents would be listed explicitly in the document’s outline.

And in case we have more content nested in the Sectioning content – for example a nested <section> has <p> as sibling, I'll find it hard to assume that the heading of the <section> is also the heading of the <p>, which it would be if flattened.

bkardell · 2017-02-18T20:42:33Z

Flattening seems to me a fundamentally broken idea - both devs and AT have 'other ways to view' sections in flat, document order. It is impossibly hard, as I described in my post, to reason about many structures today in outline form because we mix this 'flat' concept which actually relies heavily on notions derived from the visual. I'd like to see 'document outline' be about only a new contextual <h> for reasons I described. Even without speculative polyfills, today you can use role="heading" and aria-level to communicate this in any HTML. I cannot imagine that this makes any problem "worse" (including search engines and AT - they should largely 'already work') and by using speculative polyfills we can attempt to prove theory that given good incentives developers can write sensible code that clearly communicates the outline in any situation. I'm very pro "just ditch any idea of flattening WRT a future document outline".

AndySky21 · 2017-02-18T20:53:40Z

I'm against flattening too. It just makes no sense
Article and Section elements are not just "fancy div elements", nor they serve any stylistic purpose, either native or author-made. They are there for a reason. And the fact they have no heading is relevant. It could also be relevant as an error, or at least as a poor choice. Flattening them would make this choice even worse, by grouping together content that, may you want it or not, was given only one semantic significance:
"This is an atomic concept, somehow distinct from its upper level"

stevefaulkner · 2017-02-18T22:33:20Z

here is a 2014 bug that discusses the issue: outline depth calculation should not include empty sections as a result hixie made some ineffectual changes to the whatwg spec. They are ineffectual as they encourage AT to do things, when its the browsers that need to do these things as they produce the accessibility tree that AT use.

jonathantneal · 2017-02-21T12:09:36Z

As I stated last week, I'm willing and now interested in creating a speculative polyfill to expose the document outline as written, but I’m still unclear about sectioning roots:

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.

blockquote body details dialog fieldset figure td

How would I one communicate headings within these section roots? How do I expose an h2 inside blockquote as a heading that does not contribute to the outline of its ancestor? Would I be pushing this into a separate outline tree (like in some kind of array of outlines)? If I’m re-writing aria-level (to account for sectioning content and sectioning roots), should this element be aria-level=1, or should it be lower than any level belonging to its ancestor outline to prevent “contribution”, or something else? Despite body and blockquote both being sectioning roots, will I inevitably treat an h1 inside body differently than an h1 inside blockquote?

stevefaulkner · 2017-02-21T12:47:14Z

@jonathantneal I had a quick look at how this http://s.codepen.io/stevef/debug/jygGVP/vWkRwnbZmamM is outputted by H50 (outliner script) and the https://validator.w3.org/nu/ outline view. neither includes headings in the fieldset in the outline. Which doesn't make a lot of sense in terms of in page structure/navigation. It may make sense if an outline was being constructed for a table of contents maybe...

the sectioning root concept needs to be revisited me thinks.

stevefaulkner · 2017-02-22T10:13:47Z

related #806

carmacleod · 2017-02-24T05:23:51Z

In case it's helpful, here's what the ARIA 1.1 spec says about a section element (which has a default or implied aria role of "region") without a heading:

Authors must give each element with role region a brief label that describes the purpose of the content in the region. Authors should reference a visible label with aria-labelledby if a visible label is present. Authors should include the label inside of a heading whenever possible. The heading may be an instance of the standard host language heading element or an instance of an element with role heading.

The recommended Accessibility API mapping for region says:

Note: It is strongly recommended that user agents such as screen readers only convey the presence of, and provide navigation for section elements, when the section element has an accessible name.

So if AT are not including unlabelled sections, then perhaps the outline algorithm shouldn't either?

It should be noted that other aria landmark roles (other than the generic "region") do not require a name (label/heading) in order to be included in landmark navigation by AT (however, if they have one, then it can be used when listing landmarks).

chaals · 2018-02-13T11:44:56Z

see #806, #1001

chaals · 2018-03-11T04:06:19Z

There is a new proposal floating around, but we don't yet know if it will get uptake. I am going to postpone this to the next milestone, but I suspect we would do well to either switch to the new proposal, or just remove the old one and its proposed modifications for now, and note the various approaches as editorial.

chaals · 2018-04-01T18:05:26Z

To replace the existing algorithm there is a new speculative proposal.

There are several implementations floating around that implement what we have currently:

@dominykas' h50 - a base that is also used for extensions for Chrome, brackets, the Atom editor (from Github), a bookmarklet, and probably more.
html5outliner firefox addon
headings map firefox addon

I suggest we retain the current algorithm for HTML 5.3, with a warning that it may significantly change in the future and a request for feedback, and that we continue to track implementation / usage.

julkue · 2018-04-17T16:49:46Z

significantly change in the future

In which direction? Back to the roots (not always starting with <h1> in <section>) or something different?

chaals · 2018-04-17T17:10:57Z

@julmot It is hard to predict. There has been relatively low uptake of this algorithm, although not zero - @dominykas' implementation has been used in various projects, as well as the others mentioned above.

But it is somewhat complex, and the idea of using h1 as a level-free heading that would be automatically nested appropriately seems not to have got uptake - in particular, among the browser engineers who build the linkage to the Accessibility APIs that screen readers rely on.

The idea of heading whose level is determined "live" in context continues to be attractive. People do generate tables of contents all the time - it's a function of any Authoring Tool I have used in the last two decades.

So the question is what will get uptake. And that is hard to predict in advance.

jonathantneal mentioned this issue Feb 13, 2017

Add <h> element #774

Closed

chaals mentioned this issue Feb 19, 2017

headings and sections examples are inconsistent #802

Closed

chaals modified the milestones: When we can., When it's ready, Whenever we can. Mar 5, 2017

chaals self-assigned this Jan 30, 2018

chaals added match reality better needs implementations needs tests labels Jan 30, 2018

chaals modified the milestones: When it's ready, HTML5.3 WD2 Jan 30, 2018

chaals mentioned this issue Jan 30, 2018

Outline algorithm, removal of step 5 #1005

Closed

carmacleod mentioned this issue Feb 23, 2018

Draft guidance to help authors understand the difference between landmark regions and outline sections w3c/aria-practices#575

Open

chaals modified the milestones: HTML5.3 WD2, HTML5.3 WD3 Mar 11, 2018

chaals assigned scottaohara and unassigned chaals Apr 17, 2018

chaals closed this as completed in c35fc23 Apr 17, 2018

carmacleod mentioned this issue May 22, 2018

Labelling of Landmarks matatk/landmarks#1

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update outline algorithm #794

Update outline algorithm #794

jonathantneal commented Feb 12, 2017 •

edited

Loading

jakearchibald commented Feb 13, 2017 •

edited

Loading

stevefaulkner commented Feb 13, 2017 •

edited

Loading

stevefaulkner commented Feb 13, 2017

stevefaulkner commented Feb 13, 2017

Marat-Tanalin commented Feb 13, 2017 •

edited

Loading

Marat-Tanalin commented Feb 13, 2017

jakearchibald commented Feb 13, 2017 •

edited

Loading

chaals commented Feb 13, 2017

alrdytaken commented Feb 16, 2017 •

edited

Loading

bkardell commented Feb 18, 2017 •

edited

Loading

AndySky21 commented Feb 18, 2017

stevefaulkner commented Feb 18, 2017

jonathantneal commented Feb 21, 2017 •

edited

Loading

stevefaulkner commented Feb 21, 2017

stevefaulkner commented Feb 22, 2017

carmacleod commented Feb 24, 2017

chaals commented Feb 13, 2018

chaals commented Mar 11, 2018

chaals commented Apr 1, 2018

julkue commented Apr 17, 2018

chaals commented Apr 17, 2018

Update outline algorithm #794

Update outline algorithm #794

Comments

jonathantneal commented Feb 12, 2017 • edited Loading

jakearchibald commented Feb 13, 2017 • edited Loading

stevefaulkner commented Feb 13, 2017 • edited Loading

stevefaulkner commented Feb 13, 2017

stevefaulkner commented Feb 13, 2017

Marat-Tanalin commented Feb 13, 2017 • edited Loading

Marat-Tanalin commented Feb 13, 2017

jakearchibald commented Feb 13, 2017 • edited Loading

chaals commented Feb 13, 2017

alrdytaken commented Feb 16, 2017 • edited Loading

bkardell commented Feb 18, 2017 • edited Loading

AndySky21 commented Feb 18, 2017

stevefaulkner commented Feb 18, 2017

jonathantneal commented Feb 21, 2017 • edited Loading

stevefaulkner commented Feb 21, 2017

stevefaulkner commented Feb 22, 2017

carmacleod commented Feb 24, 2017

chaals commented Feb 13, 2018

chaals commented Mar 11, 2018

chaals commented Apr 1, 2018

julkue commented Apr 17, 2018

chaals commented Apr 17, 2018

jonathantneal commented Feb 12, 2017 •

edited

Loading

jakearchibald commented Feb 13, 2017 •

edited

Loading

stevefaulkner commented Feb 13, 2017 •

edited

Loading

Marat-Tanalin commented Feb 13, 2017 •

edited

Loading

jakearchibald commented Feb 13, 2017 •

edited

Loading

alrdytaken commented Feb 16, 2017 •

edited

Loading

bkardell commented Feb 18, 2017 •

edited

Loading

jonathantneal commented Feb 21, 2017 •

edited

Loading