Clarify guidance regarding aside headings and nav toc linking

[AndersEkl]

Originally written by @martinpub

Currently, the guidelines say:

Headings in text boxes is by default required to be marked up using <p epub:type="bridgehead">. These are structurally unimportant headings and will not be included in the navigation document. If, however, certain text boxes should be included in the navigation document, they must be marked up using a <h[x]> element of an appropriate level, following the level structure of the surrounding text. (3.4.8 Sidebars, Text Boxes etc.)

However, the following section states what could be seen as conflicting guidance:

All headings in the main body of text must be included in the <nav role="doc-toc"...> element and the heading levels must be implied through nesting. Headings of sidebars, text boxes or other secondary content should not be included, unless specific instructions are given by the Ordering Agency. (2.6.1.1 The Table Of Contents)

The validator currently complains if a h[x] heading is not referenced in the nav toc.

Shouldn't the guideline be that headings of asides etc. should always be included when h[x] headings are used?

Ping @AndersEkl.

Comment by @AndersEkl

I think that is the general idea, but it is not that clearly explained. We changed the rule here when we introduced bridgeheads and the paragraph about the navigation document was probably not changed. But what the rules say is that IF you want to include a text box in the navigation document, then you must use h[x]. Of course, that means that you should then include it in the navigation document. Otherwise, use bridgehead and do not include in the navigation document. I don't see any conflict here, but I do see the potential of explaining it much better. :)

[jonaslil]

epub:type="bridgehead" is deprecated in the EPUB 3 Structural Semantics Vocabulary, see 9. Titles and headings, so we might need to reconsider this markup.

For me, coming from the outside, the requirement that all h# headings always need to be in the toc seems a bit rigid. There is no formal accessibility requirement supporting this. I think it would be reasonable to let the ordering agency decide if they want to leave some less important headings out from the toc. But I understand that this would make validation of toc completeness less straightforward. A solution might be to add a class to non-toc h# headings.

There is some discussion of this in the EPUB Accessibility Techniques 1.1, 4.2.2.1 Note about the table of contents.

[oscarlcarlsson]

@jonaslil I'm not sure if we talked about this already or not, but: when you mention " all h# headings always need to be in the toc" are you referring to the nav.xhtml or the toc in the text content of the book?

[jonaslil]

I was referring to the toc in the navigation file (nav.xhtml).

[josteinaj]

If you open the HTML file in your browser, and use a screen reader, then I think the screen reader will include all the hX headings in the navigation hierarchy? My impression is that the navigation document has the same purpose. You can in principle always infer it based on the HTML files (in reading order according to the OPF). It is just there for better performance, so that the reading systems doesn't have to open all the HTML files all the time?

How would you mark up a bridgehead on a website?

(We allow our patrons to download our books as HTML in addition to EPUB, because that works better for them in various ways.) with

[oscarlcarlsson]

I tried adding a header to an aside just now, and it did not pass our validation due to validation issue [nordic_nav_references_1]. I might have done it the wrong way, though. Have you tried using headers in asides in any recent titles?

[jonaslil]

Have included aside headings in a recent book, but it has not been run through the nordic validator.

The Daisy KB recommends using h[x] headings in asides, and discusses the appropriate level here: http://kb.daisy.org/publishing/docs/html/asides.html#faq-002

The only case where using a h[x] heading for a text box would seem problematic, are cases where they appear at different levels in the main heading structure, so that assigning a consistent heading level to the boxes is not possible without messing up the hierarchy. Probably not very common. If we just want to be able to exclude text box headings from the toc, adding a class that signals that is a non-toc heading would solve the problem.

[oscarlcarlsson]

Do you want me to run it through our validator, Jonas? If you do. just send me the file.

[jonaslil]

Thanks Oscar, let's get back to that. The file was a bit messed up during MO production and my colleague is working on fixing it.

[oscarlcarlsson]

in regards to bridgeheads: i found this paragraph under Poetry and verse:

If the content written in verse has a title it may be handled as a normal heading, with <section> elements wrapping the content. However, if it does not make sense to use a proper heading, it may be marked up with <p epub:type="bridgehead"> and placed within the <div class="verse"> container. This option must not be used unless specific instructions are given by the Ordering Agency.

Should we just remove this section or do we want to replace it with something else?

[AndersEkl]

in regards to bridgeheads: i found this paragraph under Poetry and verse:

If the content written in verse has a title it may be handled as a normal heading, with <section> elements wrapping the content. However, if it does not make sense to use a proper heading, it may be marked up with <p epub:type="bridgehead"> and placed within the <div class="verse"> container. This option must not be used unless specific instructions are given by the Ordering Agency.

Should we just remove this section or do we want to replace it with something else?

Yes, this is mentioned in #66 . We need a solution for how to handle what would have been bridgeheads and then apply it throughout the document.

[oscarlcarlsson]

I noticed that after i posted it as well. I'll ponder it during the day.

[oscarlcarlsson]

@AndersEkl this one seems to be intertwined with #66. This could be closed at the same time as that one, right?

[AndersEkl]

@AndersEkl this one seems to be intertwined with #66. This could be closed at the same time as that one, right?

Yes, I think so to,

[AndersEkl]

Closing this, as it has been handled with #66 .