Repository navigation
Must navigation order match spine order? #1283
Description
There have been several discussions in the EPUBCheck repo about a new validation test, which checks that the order of links in the toc nav element matches the spine order. Existing EPUBs are failing validation because of this new check, although the spec has required this since EPUB 3.0.
The references in the
toc navelement MUST be ordered such that they reflect both:
- the order of the referenced EPUB Content Documents in the spine;
- the order of the targeted elements within their respective EPUB Content Documents.
The order of
lielements contained within thetoc navelement must match the order of the targeted elements within each targeted EPUB Content Document, and must also follow the order of Content Documents in the Rendition's spine.
In w3c/epubcheck#1036 there is a proposal to change this error to a warning. If we are to keep the spec aligned with EPUBCheck, that would mean changing our MUST to a SHOULD.
Should we change the EPUB spec? Is making this a SHOULD good enough?
Activity
GeorgeKerscher commentedon Jun 24, 2019
murata2makoto commentedon Jun 24, 2019
damiangza commentedon Jun 26, 2019
Hi
The intention of author/creators order of all the content is described and the
spine. On the other hand, ebook reading apps could, for whatever reason, provide the user with a features which might override author's toc, the author might purposefully want to display the chapters/sections/headings in a different order, or multiple toc to provide alternate navigation paths.Perhaps stipulating SHOULD for
toc navallows for flexibility for authors and reading apps.Doktorchen commentedon Jun 26, 2019
About the edge behaviour mentioned by George:
Does this edge (I do not have access to this program) not already fail at some large books without a chapter structure?
Some tools split the content due to file size, but mention only the first part of such a split in the toc at all.
For example I read already a book, created with such a tool.
It has 42 files in the spine, most of them with a file size of about 150 kiB.
But only cover, imprint and the first split document are mentioned in the toc.
If edge has already probiems with such simple books, it may have even much more problems with books with a more complex structure.
dauwhe commentedon Jul 1, 2019
Would it be acceptable to change this to a SHOULD in EPUB 3, and thus a warning in EPUBCheck?
dauwhe commentedon Jul 2, 2019
Question: if we adopt SHOULD instead of MUST, do we do it both for links to the same content document, and for different spine items? Is there actually a use case for the primary navigation links to the same content document not being in document order?
shiestyle commentedon Jul 2, 2019
In a reflowable content, it may be prepared that the NavDoc with chapters first and columns second for the spine item when a long XHTML has some chapters and columns.
For example, it will be the case of integrated books with some volumes.
avneeshsingh commentedon Jul 2, 2019
The correct implementation in EPUBCheck is the cause of this issue. The EPUBCheck 4.2 was released a month ago and the development will continue through 2019. So, it is OK to relax this rule in EPUBCheck for now i.e. give a warning instead of error and revisit this issue in later part of 2019.
For longer term solution we should work on specifications. Mokoto asked me in DPUB summit, if first spine item is last Nav Doc item how would you feel from accessibility perspective. My reply was that it can drive me crazy. If someone is doing it, I should at least get a warning from reading system that Nav items do not align to spine order. I understand that there may be use cases for this, may the book is in form of a decision tree where path through the book is chosen by the user and it cannot be aligned with spine. Makoto, romain and I talked about different ways to resolve this issue, one way was to have a new property to give warning to the users, and other was to evolve landmarks so that it can be used for the pointers that are not in-sync with spine order.
mattgarrish commentedon Jul 2, 2019
Not to harp on the distinction here, but this is an accessibility consideration not a technical one. We're making a content issue a normative requirement.
Or can someone explain why ordering is mentioned at all? What is it enabling in the specification?
That's why I feel this belongs in Ace not epubcheck.
bduga commentedon Jul 9, 2019
Ordering allows a RS to indicate position in the book. For instance the number of pages in the current chapter/section can be displayed. Additionally, the "current" chapter/section can be indicated in some special way (eg a different color for visually rendered ToCs). In this non-linear table of contents, what is "next"? What is the relationship between the items (before/after, above/below)? It seems like truly non-linear content wouldn't have an extensive ToC (eg a choose your own adventure may just have ["prologue", "start", "afterward"]). For the case mentioned, this doesn't seem to be non-linear, but is rather a legacy from print where dynamic ToCs don't exist. That is, I can't fold chapter 2 open or closed to show or hide the sub columns. But I am not really sure I understand that example - is it really the case where this non-linear toc is better? Can we get a real world example?
23 remaining items
llemeurfr commentedon Jul 25, 2019
On the Readium side, there is not problem with Backward Moby Dick on R2 Reader iOS, R2 Reader Android nor Thorium Reader (MacOS, Windows, Linux). The spine is processed for the reading order (next/previous) and the ToC links to the proper locations in the publication.
murata2makoto commentedon Jul 26, 2019
@llemeurfr @GeorgeKerscher Could you try my three examples?
GeorgeKerscher commentedon Jul 26, 2019
murata2makoto commentedon Jul 26, 2019
@GeorgeKerscher
Here you go.
danielweck commentedon Aug 1, 2019
@murata2makoto in two of the Readium desktop readers I am working on, this is how the TOC of
moonstone.epublooks like (is that what you would expect?):murata2makoto commentedon Aug 2, 2019
@danielweck Yes, this is the intended rendering.
Does your desktop application provide navigation within the TOC? For example, go to the next/previous subsection, go to the beginning of the parent section, etc. If it does, is my nav doc tractable?
danielweck commentedon Aug 2, 2019
Nothing sophisticated, just the standard (shift)keyboard-tabbing "up and down" the hierarchical list of headings, as per the linear document order of the source navigation document or NCX.
And each heading is basically a hyperlink into any arbitrary document location within the publication. At this point in time the TOC implementation does not guide the user with additional contextual heuristics / helpers. As you can see from the screenshots, the TOC is presented much like the HTML rendering (also shown in the screenshots), with a combination of inert headings (anchor with no
href=> not clickable, not linked to anything), and active interactive hyperlinks.VeryGoodErotica commentedon Aug 28, 2019
I'm brand new to ePub - previously I've done all my publishing via LaTeX where a considerable amount of freedom exists. However PDF is not easy to read on phones etc.
So I apologize if this concern has been brought up, but it is very important to me.
The order should NOT be required to match and there is historical publishing precedence where they do NOT match - such as in the pulp magazines and presumably others.
Very often stories will be listed together in the ToC, followed by things like essays/poems, followed by glamour photo shoots, etc.
Their actual location within the magazine itself is mixed - but having them grouped in the ToC makes it easier for someone looking for a specific type of content within the magazine to find it.
In LaTeX just use the
tocloftpackage and you can do the ToC any way you want. Why does ePub want to be more restrictive on creative typographical freedom?danielweck commentedon Aug 28, 2019
Welcome to GitHub @VeryGoodErotica, and thanks for chiming in! (here and in the other issue)
Would EPUB "landmarks" be useful in your use-case?
https://www.w3.org/publishing/epub/epub-packages.html#sec-nav-landmarks
Note that you can design any "table(s) of contents" (I use the term loosely here) and display it/them to your readers using HTML document(s) judiciously placed in the reading order (aka publication "spine"), or linked from landmarks but declared as "non-linear" (although I would personally refrain from using this latter technique, as it is not supported consistently across reading systems).
You would of course still need to design a machine-readable TOC (i.e.
navwithepub:type="toc") that would only provide a high-level and linear-order-matching view of your publication structure, lacking the detail of your rendered (HTML + CSS) table(s) of contents ... thus why I suggest defining machine-readable landmarks as well, so that reading systems can at least point to the more "fancy" TOCs available in the publication.I hope this makes sense! (it is getting late here ;)
carltongibson commentedon Mar 5, 2020
I think a SHOULD is fine.
Working on the EPUB for the docs for the Django Web Framework, we have done everything we can to produce a valid EPUB. This one rule is blocking us. Django Issue
We have a section index page with a TOC at the top, linking to various subpages, and to sections lower on the main page. Given the content, it makes no sense to reorder, and in the end we had to decide to ignore this warning. (Maybe with a big restructure we could satisfy it but that feels like putting the cart before the horse.)
Hopefully the example helps you to decide.
Thanks for all the effort!
wareid commentedon Oct 23, 2020
F2F Meeting October 22, the group has resolved to change the MUST to a SHOULD.
This will align the specification to the current state of EPUBCheck. We also recommend that Ace add a check for linear order as an accessibility requirement.