What to do about the document outline? #33

Closed
stevefaulkner opened this Issue Jan 22, 2016 · 21 comments

Comments

Projects
None yet
7 participants
@stevefaulkner
Contributor

stevefaulkner commented Jan 22, 2016

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 whatwg/html#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

@stevefaulkner stevefaulkner changed the title from what to do about the document outline? to What to do about the document outline? Jan 22, 2016

@detlevhfischer

This comment has been minimized.

Show comment
Hide comment
@detlevhfischer

detlevhfischer Jan 22, 2016

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?

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Jan 22, 2016

Contributor

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>

Contributor

stevefaulkner commented Jan 22, 2016

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

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Jan 22, 2016

Collaborator

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.

Collaborator

chaals commented Jan 22, 2016

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

This comment has been minimized.

Show comment
Hide comment
@LJWatson

LJWatson Jan 28, 2016

Collaborator

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

Collaborator

LJWatson commented Jan 28, 2016

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

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Feb 1, 2016

Collaborator

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

Collaborator

chaals commented Feb 1, 2016

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

@stevefaulkner

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 1, 2016

Contributor

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
#33 (comment).

Contributor

stevefaulkner commented Feb 1, 2016

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
#33 (comment).

@chaals

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Feb 1, 2016

Collaborator

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…

Collaborator

chaals commented Feb 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@LJWatson

LJWatson Feb 1, 2016

Collaborator

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

Collaborator

LJWatson commented Feb 1, 2016

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

@stevefaulkner

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 1, 2016

Contributor

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/

Contributor

stevefaulkner commented Feb 1, 2016

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

This comment has been minimized.

Show comment
Hide comment
@AndySky21

AndySky21 Feb 1, 2016

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

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

This comment has been minimized.

Show comment
Hide comment
@unor

unor Feb 8, 2016

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

unor commented Feb 8, 2016

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

@stevefaulkner

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Feb 29, 2016

Contributor

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.
#110

Contributor

stevefaulkner commented Feb 29, 2016

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.
#110

@chaals

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals May 3, 2016

Collaborator

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?

Collaborator

chaals commented May 3, 2016

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner May 3, 2016

Contributor

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

Contributor

stevefaulkner commented May 3, 2016

@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

This comment has been minimized.

Show comment
Hide comment
Collaborator

chaals commented May 3, 2016

@jlbruno

This comment has been minimized.

Show comment
Hide comment
@jlbruno

jlbruno May 3, 2016

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

jlbruno commented May 3, 2016

@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 chaals added this to the After HTML 5.1 milestone May 10, 2016

@chaals

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals May 10, 2016

Collaborator

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.

Collaborator

chaals commented May 10, 2016

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

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Jun 1, 2016

Contributor

@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

Contributor

stevefaulkner commented Jun 1, 2016

@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

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Jun 1, 2016

Collaborator

Yeah, the comment was about implementations - is there any significant deployed legacy that somehow failed to implement the h1h6 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…

Collaborator

chaals commented Jun 1, 2016

Yeah, the comment was about implementations - is there any significant deployed legacy that somehow failed to implement the h1h6 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

This comment has been minimized.

Show comment
Hide comment
@chaals

chaals Nov 5, 2016

Collaborator

@stevefaulkner can we close this?

Collaborator

chaals commented Nov 5, 2016

@stevefaulkner can we close this?

@stevefaulkner

This comment has been minimized.

Show comment
Hide comment
@stevefaulkner

stevefaulkner Nov 5, 2016

Contributor

@chaals, yes

Contributor

stevefaulkner commented Nov 5, 2016

@chaals, yes

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