What to do about the document outline?

[stevefaulkner]

As many people have been lead to believe it actually effects the semantics of headings, when in practice it does not, currently HTML has a warning for web developers about the document outline algorithm as its semantics are not implemented in UA's and visual styling of headings based on their section nesting is only partially implemented.

In a related issue discussion, I started, based on the lack of developer advice in the whatwg spec https://github.com/whatwg/html/issues/83 there has been talk of removing/modifying the algorithm and how sectioning elements (in particular section and article elements) effect the semantics of headings.

We need to look more into the issues with the algorithm and decide the future of how document outlines are expressed in HTML and how the current semantics of sectioning elements could/should be changed.

related: https://www.w3.org/wiki/HTML/Usage/Headings/h1only

[detlevhfischer]

This may be nonsense but I give it a shot: Wouldn't it be possible for a script to query whether a (future) browser suports the outline algorithm? If it does, the script could parse headings of content being inserted and renumber them so heading levels start one below the (possibly generated) parent numbering level and shift levels accordingly. If it doesn't (the fallback for browsers that ignore the algorithm, or when scripts are turned off), the heading levels remain as specified in the source content. This means I could specify, for some content to be inserted, my headings on a range from h3 - h6 (because I may know that in most common placement contexts h1 and h2 will be used on a higher level). When the same content is used in some other context, say, with no preceding headings, my content would be dynamically renumbered to h1-h4. I ignore for now what happens to headings being transposed to levels below h6 (aria role=heading with aria-level > 6 might come in handy here). Any thoughts?

[stevefaulkner]

ouldn't it be possible for a script to query whether a (future) browser suports the outline algorithm? If it does, the script could parse headings of content being inserted and renumber them so heading levels start one below the (possibly generated) parent numbering level and shift levels accordingly.

sure,but that does not help with the question of what the spec should say about the outline and how it defines the effect of sectioning elements. FYI <HTML5-h>

[chaals]

More to the point, writing such a script seems like a lot of work, and highly prone to going wrong.

If browsers are not going to fix the longstanding bugs, maybe we should stop telling people to behave as though they will.

In the case of heading levels, there is a serious problem that the browsers effectively report one level of heading to the user, through a default styling, and a different level to accessibility APIs.

Likewise, the styling trick is pretty fragile - any author style seems to override it immediately.

I'm personally leaning toward the idea that we should just drop the sectioning thing, since it seems browsers are not really prepared to implement it.

[LJWatson]

Unless there is an implimentation of the outline algorithm that honours heading structuring, I think the advice in the HTML spec should recommend the use of ranked headings.

@stevefaulkner noted (elsewhere) that ePub3 uses the outline algorithm to produce a table of contents [1]. It doesn't seem to influence heading structure AFAIK though.

[1] http://www.idpf.org/epub/30/spec/epub30-overview.html

[chaals]

An apparent implementation as a Firefox extension - I haven't tested this yet

[stevefaulkner]

there are also bookmarklets and the nu markup checker implements

Regards

SteveF Current Standards Work @W3C http://www.paciellogroup.com/blog/2015/03/current-standards-work-at-w3c/

On 1 February 2016 at 16:54, chaals notifications@github.com wrote:

An apparent implementation as a Firefox extension https://addons.mozilla.org/es/firefox/addon/headingsmap/ - I haven't tested this yet

— Reply to this email directly or view it on GitHub https://github.com/w3c/html/issues/33#issuecomment-178065361.

[chaals]

So I wonder if any of those don't work with the old h1..h6 model, and if such things exist whether they are important to the real world…

[LJWatson]

@stevefaulkner @chaals would any of those tools break if we updated the spec to recommend explicitly ranked headings instead of <h1> only?

[stevefaulkner]

On 1 February 2016 at 17:23, Léonie Watson notifications@github.com wrote:

would any of those tools break

no

Regards

SteveF Current Standards Work @W3C http://www.paciellogroup.com/blog/2015/03/current-standards-work-at-w3c/

[AndySky21]

Here's another example, this time for Chrome (not thoroughly tested, but it works somehow) https://chrome.google.com/webstore/detail/html5-outliner/afoibpobokebhgfnknfndkgemglggomo

[unor]

A JavaScript implementation, also offering a bookmarklet (screenshot): https://github.com/hoyois/html5outliner

[stevefaulkner]

I have made an initial pass at rewriting the article element definition (as a discussion starter), this is part of the much larger task of recasting the outlining stuff. https://github.com/w3c/html/issues/110

[chaals]

Having removed the harmful advice to use nested h1 elements everywhere, is there more we should do about this issue? It seems there is implementation that is probably useful. Are there other harmful things somewhere?

[stevefaulkner]

@chaals I am going to review the changes and will bring up any thoughts I have next week at F2F as well as on issue.

[chaals]

@stevefaulkner cool.

Discussion on WG

[jlbruno]

@stevefaulkner ,

If I recall, one of the main benefits of the current spec is that it allows for easier syndication of parts of a document, correct? An article or section could be syndicated elsewhere with an h1 and it would stand alone, but put it into the context of a larger page and the technology should be able to tell that the nested h1 now becomes a heading of a different level.

Are there any other main use cases for using a top level heading inside sections that would be a reason for keeping the spec as written?

[chaals]

The bit that was actually breaking things was the section/h1/section/h1 nesting, which was removed, the rest doesn't work in browsers but doesn't break anything and is used elsewhere.

[stevefaulkner]

@chaals

So I wonder if any of those don't work with the old h1..h6 model

The outline algorithm is backward compatible, so works fine with just h1 to h6

[chaals]

Yeah, the comment was about implementations - is there any significant deployed legacy that somehow failed to implement the h1…h6 model.

I don't know of any, and haven't heard of any - although I know there is a real use case for being able to go beyond 6 levels, which was what made me wonder…

[chaals]

@stevefaulkner can we close this?

[stevefaulkner]

@chaals, yes