Update outline algorithm #794

Closed
jonathantneal opened this Issue Feb 12, 2017 · 21 comments

Comments

@jonathantneal

jonathantneal commented Feb 12, 2017

Based upon @stevefaulkner in #774:

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

This comment has been minimized.

Show comment
Hide comment
@jakearchibald

jakearchibald Feb 13, 2017

The example given is:

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

Which produces:

  1. 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.

jakearchibald commented Feb 13, 2017

The example given is:

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

Which produces:

  1. 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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 13, 2017

Contributor

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.

Contributor

stevefaulkner commented Feb 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 13, 2017

Contributor

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>
Contributor

stevefaulkner commented Feb 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 13, 2017

Contributor

@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>
Contributor

stevefaulkner commented Feb 13, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@Marat-Tanalin

Marat-Tanalin Feb 13, 2017

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 commented Feb 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@Marat-Tanalin

Marat-Tanalin Feb 13, 2017

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.

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

This comment has been minimized.

Show comment
Hide comment
@jakearchibald

jakearchibald Feb 13, 2017

@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.

jakearchibald commented Feb 13, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Feb 13, 2017

Collaborator

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 :(

Collaborator

chaals commented Feb 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@alrdytaken

alrdytaken Feb 16, 2017

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.

alrdytaken commented Feb 16, 2017

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

This comment has been minimized.

Show comment
Hide comment
@bkardell

bkardell Feb 18, 2017

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".

bkardell commented Feb 18, 2017

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

This comment has been minimized.

Show comment
Hide comment
@AndySky21

AndySky21 Feb 18, 2017

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"

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 18, 2017

Contributor

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.

Contributor

stevefaulkner commented Feb 18, 2017

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

This comment has been minimized.

Show comment
Hide comment
@jonathantneal

jonathantneal Feb 21, 2017

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?

jonathantneal commented Feb 21, 2017

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 21, 2017

Contributor

@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.

Contributor

stevefaulkner commented Feb 21, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 22, 2017

Contributor

related #806

Contributor

stevefaulkner commented Feb 22, 2017

related #806

@carmacleod

This comment has been minimized.

Show comment
Hide comment
@carmacleod

carmacleod Feb 24, 2017

Contributor

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).

Contributor

carmacleod commented Feb 24, 2017

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

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Feb 13, 2018

Collaborator

see #806, #1001

Collaborator

chaals commented Feb 13, 2018

see #806, #1001

@chaals

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Mar 11, 2018

Collaborator

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.

Collaborator

chaals commented Mar 11, 2018

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 chaals modified the milestones: HTML5.3 WD2, HTML5.3 WD3 Mar 11, 2018

@chaals

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Apr 1, 2018

Collaborator

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

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

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.

Collaborator

chaals commented Apr 1, 2018

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

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

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.

@chaals chaals assigned scottaohara and unassigned chaals Apr 17, 2018

@chaals chaals closed this in c35fc23 Apr 17, 2018

@julmot

This comment has been minimized.

Show comment
Hide comment
@julmot

julmot Apr 17, 2018

significantly change in the future

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

julmot commented Apr 17, 2018

significantly change in the future

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

@chaals

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Apr 17, 2018

Collaborator

@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.

Collaborator

chaals commented Apr 17, 2018

@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.

@carmacleod carmacleod referenced this issue in matatk/landmarks May 22, 2018

Closed

Labelling of Landmarks #1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment