Other navigation elements beyond ToC

[HadrienGardeur]

This is based on my gap analysis between EPUB 3.2 and WP: #176 (comment)

EPUB provides a number of additional lists that can all be expressed in the Navigation Document such as:

• page list
• landmarks
• list of audio files, list of tables, list of videos and list of images

Do we need any of these additional elements in WP?

[HadrienGardeur]

Page list seems to be very high on the list of requirements for education, it's probably worth considering in both WP and EPUB4.

[laudrain]

It's also a must have for a11y for all kind of books in general.

[danielweck]

Re. list of page breaks (aka page list): well, @laudrain "for all kind of books in general" that have an equivalent print representation (just to be clear that this is specifically about allowing content creators to encode references to "printed pages", nothing to do with "page numbers" generated in the context of dynamically-paginated reflowable documents, i.e. the reading system's own pagination capabilities).

[GarthConboy]

Seems, at least for page-list, this could be a manifest item pointing to an ARIA-tagged page-list <nav> element, much like the TOC.

[avneeshsingh]

Indeed, adding pagelist should be straight forward because we already have doc-pagelist in DPUB aria roles.
From accessibility point of view, I will also support pointing to other important pieces in the publications like landmarks, notes etc. Quick navigation to important chunk of information is very helpful for people with disabilities.

[css-meeting-bot]

The Working Group just discussed Issue 222.

The full IRC log of that discussion

<wolfgang> Topic: Issue 222
<garth> q+
<wolfgang> tzviya: gap analysis aims at being feature-compatible with epub 3
<ivan> q+
<wolfgang> ... not to duplicate epub 3
<tzviya> ack garth
<tzviya> ack ivan
<wolfgang> garth: in epub 3 hints for special stuff such as MathML. Is it useful and if we don't have it, what are the consequences? Not very important
<garth> q?
<wolfgang> ivan: slightly more general issue - minimal infoset in WP, but additional links can be added - don't think we should standardize everything in WP
<tzviya> q+
<tzviya> ack tzviya
<garth> q?
<wolfgang> ... note how useful epub pieces may be mapped to wp - separate contents of spec from contents of that note - looking for an owner of that note
<BenWaltersMS> q+
<tzviya> ack BenWaltersMS
<wolfgang> tzviya: are these properties relevant for system developer?
<timCole> q+
<dauwhe> q+
<tzviya> ack timCole
<wolfgang> ben: we do occasionally use them - ditching them is OK - you may extract info from contents
<garth> q?
<wolfgang> tim: using links and rel is more reliable than properties
<tzviya> ack dauwhe
<wolfgang> dave: hoping wp can function without these properties
<garth> dave: as the web manages to without same
<wolfgang> tzviya: approaching consensus that we may do without them, but keep a list/wiki of these properties for roundtripping purposes
<wolfgang> tzviya: create "roundtrip " label in github
<wolfgang> Topic : Issue 223
<tzviya> https://github.com//issues/223
<ivan> github topic: 223
<wolfgang> garth: additional capabilities of navigation methods, esp. page-list as most important, but also list of landmarks, list of tables, etc. pretty useful
<ivan> github topic: https://github.com//issues/223
<wolfgang> ... we have an ARIA mechanism that is usable and we may describe the function in the manifest.
<ivan> q+
<wolfgang> tzviya: how to create equivalent of page-list by using ARIA page-list - explain in the spec!
<George> q+
<tzviya> ack ivan
<wolfgang> garth: manifest may point where this info may be found
<Hadrien> q+
<wolfgang> ivan: "resource" and "links" are both an array of PublicationLinks, page-list may follow the same structures - should it be standardized
<tzviya> ack George
<garth> ack George
<wolfgang> garth: would be <nav> elements, pointed to from manifest
<wolfgang> george: would they live in the TOC? page-list - very important in education where print and digital version coexist
<garth> ack Hadrien
<tzviya> q+
<wolfgang> hadrien: I'm not suggesting anything myself - just a gap analysis
<wolfgang> ... in epub we have a way of pointing to the navigation doc, not the same as pointing to TOC in WP
<wolfgang> ... also no equivalent for identifying a specific nav element
<garth> q?
<garth> ack tzviya
<garth> q+
<wolfgang> tzviya: Hadrien is right - we need to define explicitly what to do with the page-list - we need to define criteria for UA conformance - in epub world this doesn't work in all RSs
<tzviya> ack garth
<wolfgang> ... we have the basic functionality in HTML already
<ivan> zakim, who is here?
<Zakim> Present: tzviya, dauwhe, dkaplan, wolfgang, ivan, Avneesh, JunGamo, rkwright, gpellegrino, romain, George, BenWaltersMS, Garth, laudrain, Bill_Kasdorf, MustlazMS, derekjackson,
<Zakim> ... Tim_Cole, caitlingebhard, BenSchroeter, duga, Hadrien, marisa, bigbluehat, Franco
<Zakim> On IRC I see Jean_K, Franco, clapierre, cmaden2, Hadrien, duga, BenSchroeter, marisa, caitlingebhard, MustlazMS, timCole, Bill_Kasdorf, laudrain, derekjackson, MURATA, garth,
<Zakim> ... BenWaltersMS, George, lsullam, rkwright, laurentlemeur, romain, JunGamo, jbuehler, Avneesh, dkaplan3, wolfgang, RRSAgent, Zakim, tzviya, ivan, dauwhe, plinss, github-bot,
<Zakim> ... astearns, bigbluehat, jyasskin
<wolfgang> garth: proposes to leave it up to UAs
<tzviya> q?
<garth> q?
<Avneesh> q+
<bigbluehat> q+
<tzviya> ack Avneesh
<tzviya> ack bigbluehat
<wolfgang> avneesh: if we put page-list in HTML, it would be very helpful
<garth> +1 Avneesh
<dkaplan3> avneesh++
<garth> q?
<wolfgang> benjamin: roundtripping = epub to wp and back?
<dkaplan3> q+
<garth> q+
<George> q+
<wolfgang> benjamin: going from epub 3 to epub 4 would make things easier while wp should be for the web
<tzviya> ack dkaplan
<wolfgang> dkaplan: is wp unpackaged epub 4? important to do a gap analysis wrt to epub3 -
<bigbluehat> q+ to suggest we're comparing gaps between the wrong things
<tzviya> ack garth
<wolfgang> garth: benjamin raised a good point. we do need page-list for wp, should be done in HTML (for non-WP-aware UA)
<tzviya> ack George
<wolfgang> ... we need them for wp and epub4
<garth> q?
<tzviya> ack bigbluehat
<Zakim> bigbluehat, you wanted to suggest we're comparing gaps between the wrong things
<wolfgang> george: not specifying UA behaviours - perhaps we need a note that helps implementors and users to understand what is meant
<garth> ack bigbluehat
<garth> q+
<wolfgang> benjamin: does this group agree that wp is on its own and not entangled in epub technology, but epub 4 would be in continuation of the epub tradition
<wolfgang> ... wp focused on browser
<tzviya> ack garth
<wolfgang> garth: wp is not only a waystation to epub 4, epub4 is inheriting from wp and epub3
<ivan> +1 to garth
<laudrain> +1
<bigbluehat> q+
<tzviya> ack bigbluehat
<wolfgang> tzviya: concerned that page-list is displayed as a list of numbers
<garth> q+
<laurentlemeur> q+
<wolfgang> benjamin: anything we don't put in entry page, UA has to hunt for. potentially unknown to the human reader in this case
<wolfgang> benjamin: needs to be an HTML - should be in a place where it would be quickly found
<tzviya> https://github.com//issues/223
<dkaplan3> tzviya: +1
<jbuehler> +1
<laurentlemeur> q-
<tzviya> q?
<wolfgang> tzviya: agree that it should be part of the spec, but not precisely how it should be done

[GarthConboy]

+1 to Anveesh above. The "page list" should be an ARIA tagged "doc-pagelist" tagged <nav> element. Such should be pointed to from the Manifest (and tagged as such). The <nav> element could well be in the Entry page, though not required.

Such an approach would work a desired in a non-WP aware UA/RS (assuming the browser encounter the so-labeled <nav> (in the Entry page or otherwise).

I'd tend to think a link to the page-list would also be in the TOC, but that's clearly not required.

[BigBlueHat]

If the page list is not included in the entry page, then how is the human reader to find it (since they can't consult the manifest)?

[deborahgu]

@BigBlueHat: It varies. In some current systems (eg. ibooks) a human reader can't access the page list unless they toggle a specific mode, which then displays it. Arguably, a page list should be primarily available to AT, which dpub-aria would afford, since it's less useful to human readers.

Disclaimer: "available to AT" doesn't mean "only available to screenreaders". There are non-screenreader and indeed non-accessibility use cases for needing navigation to or display of a print page number. There does need to be a way to use this without accessing the accessibility tree. But, as in ibooks, if this is considered a non-primary reading experience which needs to be enabled, then some other functionality can be responsible for accessing the manifest on demand.

[deborahgu]

Given my disclaimer above, I agree with @avneeshsingh that we should use the doc-pagelist, but I also think we need to remember that adding it to the accessibility tree doesn't inherently do anything useful in a reading system. In a native HTML, non-polyfilled reading experience, doc-pagelist will appear as a navigation block in the accessibility tree, without any specifying indicator of what kind of navigation -- and non screenreader users will have no access to the pagelist at all.

[GarthConboy]

Agree with Debora. And to Ben, it reasonable/likely/possible for the page-list Nav element to be listed within the TOC, so "following a link" would be an answer sometimes.

[iherman]

I believe there are (at least) two discussion threads here, and we may want to separate those.

1. How to represent some of these lists with nav elements (ie, how to use ARIA, etc) and how to use them.
2. How to find these nav elements via our manifest.

Let me concentrate on the second issue, which may be easier to handle. I think that, as a matter of consistency, we should follow the same pattern as for table of contents:

• If a resource in either the default reading order or resource-list is identified with a rel value of contents [iana-link-relations], use the url value of the specified resource as the link leading to the table of contents.
• If the primary entry page contains an HTML element with the role [html] value doc-toc [dpub-aria-1.0], use that element as the table of contents.

Of course, the ARIA value must be different, and the rel value should also be different (I would expect these rel values would be publication specific, not IANA values).

The only question which remain is how, editorially, these lists would appear in our spec. Are these necessary as new entries of the standard infoset, or are they the subject of a separate, best practices note?

Can we have a consensus on that second issue?

[avneeshsingh]

As I mentioned yesterday, for accessibility pagelist as as important as TOC, so using the same approach as TOC is good. So, +1 to Ivan.

Regarding use of DPUB aria role doc-pagelist. We made a decision in Toronto that we should use DPUB aria for publishing specific semantics until we have a separate arrangement for publishing specific semantics. So, it looks that we can reuse it, no matter that use of pagelist is broader than accessibility.

[llemeurfr]

@TzviyaSiegman warned during yesterday's call that a page-list being a raw list of page numbers + hyperlinks, there was a risk that the display of such a list in some UA would be dull. We must be aware that the choice of an HTML (nav) structure to handle such a list will have as a consequence that the display of such a list in ALL UA may be dull, depending what the author has coded. HTML (+ CSS) is targeted for display as-is. UA's won't create fancy layouts if the author has not done so in the HTML page.

Another fact must be clear to everybody. If I understood well, @BigBlueHat favors embedding all nav structures in the entry page. Embedding the ToC plus the page-list (plus the list of figures etc..) in the entry page will have as a direct consequence that most UA's will display the ToC + page-list + list of figures in the same screen, one after the other. The reason is the same as above: HTML (+ CSS) is targeted for display as-is.

Only a few reading systems, capable of filtering the HTML document and extract clean structures from the HTML tag soup (yes, we'll move from XHTML to HTML tag soup) will be able to present different panels for these different structures, and try to create a standardized fancy layout around page-lists.

[iherman]

@llemeurfr

Another fact must be clear to everybody. If I understood well, @BigBlueHat favors embedding all nav structures in the entry page. Embedding the ToC plus the page-list (plus the list of figures etc..) in the entry page will have as a direct consequence that most UA's will display the ToC + page-list + list of figures in the same screen, one after the other. The reason is the same as above: HTML (+ CSS) is targeted for display as-is.

I agree with that. Hence also my proposal in #223 (comment) to follow the same model as ToC (beyond consistency): the author has all the means to do what she wants, push everything into the entry page or organize it differently. I do not think we should impose one particular approach and the current ToC structure does just that.

[laudrain]

I agree with @iherman: we should not mix rendering with the question on finding these lists.
And rendering is an authoring question, not a UA's one: it belongs to the author on how to build "nice looking" nav content (Toc, page-list, ...).
BTW, the F2F already settled on this as Ivan said in #251 (comment)

I support Ivan's proposal on "How to find these nav elements via our manifest."

[TzviyaSiegman]

@avneeshsingh please propose how you would like this done in WPUB

[avneeshsingh]

Summarizing the discussions till now:
The pagelist may be added in the entry page. To identify the pagelist nav element with aria 1.1 DPUB role doc-pagelist should be used.
This is important for minimum viable WP that works in a non-WP aware user agent, #271.
The pagelist must have one or more hyperlinks pointing to target elements in the content, the target elements must be identified by aria 1.1 DPUB role pagebreak.
If pagelist is not in the entry page then manifest should point to the resource that contains the pagelist. url of the pagelist can be either in list of resources or default reading order.
If more than one pagelist is found, then reading system should make the choice based on its own algorithm.

[iherman]

This issue was discussed in a meeting.

• RESOLVED: add a pagelist into the draft, including the webidl, along the way toc is added

View the transcript

Navigation elements beyond the ToC
Ivan Herman: #223
Tzviya Siegman: navigational objects beyond the TOC
… Avneesh, are you on the call?
Avneesh Singh: I have summarized this
… reinforcing what Ivan has mentioned
… following model of toc for pagelist
… pagelist should also be in entry doc
Tzviya Siegman: #223 (comment)
Avneesh Singh: we ensure that a non-wp aware browser could present it
… would be identified by DPUB-ARIA 1.1 role
… the link to pagelist can also be provided in manifest
… can be in resources or can be in reading order
… so WP-aware UA can parse manifest to find this, and decide what to do
Tzviya Siegman: if no objections, we can ask matt to update the spec
Ivan Herman: since we discussed this issue
… we found a can of worms around the TOC
… so saying its the same as toc can be complicated
… there are a lot of pending issues around TOC
… how is it the same semantically as toc, and how is it different?
Avneesh Singh: the concept is similar, can be placed in entry doc and referred to by manifest
… other than this we don’t need to follow same rules
Tzviya Siegman: I agree with Avneesh. Other issues are separate.
Ivan Herman: that’s fine
… we introduce into the document another category we call pagelist, with these features?
Tzviya Siegman: yes
Ivan Herman: can we have that recorded as a resolution? it needs to appear in lots of places, such as the webIDL
Tzviya Siegman: let’s vote
Proposed resolution: add a pagelist into the draft, including the webidl, along the way toc is added (Ivan Herman)
Jeff Buehler: +1
Avneesh Singh: +1
Tzviya Siegman: +1
Marisa DeMeglio: +1
Bill Kasdorf: +1
George Kerscher: Avneesh, you mentioned two sets of pagelists?
… wouldn’t there normally be one?
Avneesh Singh: yes
Wolfgang Schindler: +1
Tzviya Siegman: I didn’t understand the question
Dave Cramer: there could certainly be multiple Page-lists
… or multiple pagelists because of varying publications of the same content
Ivan Herman: I put in a proposed resolution
… as an editor, I would like if someone, maybe Avneesh, would send me a paragraph that gives a short and compact description of what the page list is
… can one of you send it to me?
Avneesh Singh: yes
Ivan Herman: I can put it into the text sometime this week
Wolfgang Schindler: pagelist for me presupposes a print edition with pagenumbers
… or it would a paginated view of my html doc, which would require page ids and page numbers in my data
… is that right? a list that relates page numbers to fragment ids?
Avneesh Singh: yes, that’s correct
… the page list means identifying the exact position of the page breaks in print editions
Wolfgang Schindler: using fragment IDs?
Avneesh Singh: yes
Ivan Herman: I understand what Hadrien is saying, it’s not part of the webidl
Ivan Herman: there is another question
… we find pagelist with role=doc-pagelist
… but if we use the same structure for TOC we should have a link relation which we use
… for TOC there is an IANA link relation
… is there one for pagelist, or should we define our own?
Tzviya Siegman: would there be a problem using toc for this, too?
… it is a kind of TOC
Ivan Herman: I would be hesitant, but I don’t know
George Kerscher: to wolfgang’s question, there is also the notion of a virtual page, even if there’s no print equivalent, you can put in these links
Avneesh Singh: regarding IANA entry, I think using TOC may be misleading
… it’s a machine-readable thing
… it’s a different item
Ivan Herman: for the time being I can put in our own URL, like for the cover
Bill Kasdorf: I wanted to stress that a toc and pagelist is different
… one is structural.
Tzviya Siegman: I think we’re dTOC with this issue, we have details like the rel value to work out
Resolution #2: add a pagelist into the draft, including the webidl, along the way toc is added
Wolfgang Schindler: +1 to BillK’s description of the difference
Tzviya Siegman: we’ve agreed to ivan’s proposal above, now it’s editorial
… and Hadrien will open an issue about the webidl

[lrosenthol]

As discussed in #339 - just bringing over pagelist from EPUB may not the current solution to the use cases for which it exists. @danielweck and myself would like to see us back up and examine the use cases around it and then evaluate whether it is the correct mechanism or others (such as per-item attributes) are a better approach.

[danielweck]

@lrosenthol thank you for reporting here. However I must clarify my position, which is not quite correctly reported, and which I hope is well summarized here: #339 (comment)

[TzviyaSiegman]

@lrosenthol note that this is not the same solution as EPUB. Rather we are using roles from DPUB-ARIA.

The goal of pagelist is to reach pages, not more granular items. If you would like to discuss addressing more granular items, please open a separate issue.

[HadrienGardeur]

@lrosenthol I'm not entirely sure what you're proposing here.

I see some value in having the page information in the documents themselves instead of using a <nav> element that references fragment identifiers in various document, but this only works if there's a standard way for non WP-aware UAs to support such info as well.

As discussed in #339, data-* attributes are not a good fit for what I've just described.

[baldurbjarnason]

If I understand the conversation correctly, the proposal is that we have for how to represent a page list is:

• A <nav> element with a dpub-pagelist role that contains a list of links to page positions
• Those page positions may be based on a pre-paginated version of the publication (i.e. pdf or print) or may be entirely abstract navigation aids that are more granular than other navigation that is offered. (Better and more elegantly phrased in Added the pagelist entry #339 (comment) by @mattgarrish)
• Each link in the list points at an element in a publication document.
• Each of those targets has to have a dpub-pagebreak role

And considering that the example from the DPUB-ARIA spec includes the page number in a potentially machine-readable form (<span id="pg04" role="doc-pagebreak" title="4"/>) aren't most of the concerns that have been raised covered?

[avneeshsingh]

Matt's reformulation makes the text clear for even those who are at a distance from our technical community and may not be aware of terms like print equivalent.

[llemeurfr]

As we'll specify a page list section, the way we did with the ToC, I suggest we specify more precisely than in EPUB 3 the syntax of a page break (the target of the link). I don't mean requiring e.g. a span (), but rather make sure that page numbers are empty elements.

In the Daisy page on page lists, in the Q&A section, there is a question "Should I include the page numbers as content or empty elements?" the text states that "If you include the page numbers as text content within a span or div, ... mainstream user agents will not provide equivalent functionality to turn off unwanted content, forcing users to hear and view the page numbers." -> this seem bad practice. The alternative "Page numbers as empty elements are the more traditional mainstream approach, with anchor tags having served this function in the past. Using the aria-label attribute on an empty element, however, limits the users who will have access to the page number while reading." seems a better approach: it should be in our spec IMO, so that authors have a rule to follow and UAs don't mess with the content.

[iherman]

@llemeurfr

the way we did with the ToC

well, this is one of our open issues that will have to be decided, and possibly closed, at TPAC... maybe we should discuss it as part of that discussion.

[avneeshsingh]

@llemeurfr

Both of these are valid use cases. In some publications visible page numbers may be disruptive, while in some it may be essential. We should give example for both.