Link to nav.xhtml in TOC

[cges30901]

Hello, I am using Sigil to create epub3.
In Sigil 0.9.18, I can go to Tools > Table Of Contents > Edit Table Of Contents... and add an entry with target as "Text/nav.xhtml". After I upgrade to Sigil 1.0.0, this doesn't work anymore. If I open epub created with Sigil 1.0.0 in epub reader (like Calibre) and click the link to nav.xhtml in TOC, it can not go to nav.xhtml.

Link created with Sigil 0.9.18 is like this:

      <li>
        <a href="../Text/nav.xhtml">TOC</a>
      </li>

Link created with Sigil 1.0.0 is like this:

      <li>
        <a href="">TOC</a>
      </li>

Sample epub created with Sigil 1.0.0: test.epub

Am I doing it the wrong way or this is a bug in Sigil 1.0.0?

[KevinH]

I am confused. When you edit the TOC in an epub3, you are editing the nav file. So you are trying to create a link to the nav toc section in the nav in that exact same nav toc section and call it the TOC?

Are you sure you you did not actually want to create a separate HTML Table Of Contents and create a link to the nav from it?

KevinH

[KevinH]

Okay, creating links to the top of the page in the nav from the top of the page in the nav via EditTOC was not a case we had considered. I have now pushed a fix for this to master.

FWIW, a better way to handle this would be to specify the target with a proper fragment from the list that is provided. Linking to the nav toc from the nav toc is not common.
Hand adding a new target that does not exist in the list of potential targets is also probably not the best idea.

If you do hand add a new target in this case, the nav.xhtml has id="toc" that it would make for a better target id than the top of page for the nav itself.

Thank you for your bug report.

[cges30901]

Thanks for your suggestion and fix! Actually I am creating epub by editing a template I found online, which links to nav from nav.

Here are possible solutions:

1. Link to # (using Sigil from master branch). This is not supported in some viewers.
2. Link to #nav. This is not supported in some viewers.
3. Create a separate HTML Table Of Contents. This is a good solution, but I have to look into css used by nav.xhtml to make separate HTML Table Of Contents looks pretty.
4. Remove link to TOC or nav. The link doesn't seem necessary to me.

My conclusion is that I will try solution 3 first, if this looks like too much work for me, I will use solution 4.

[cges30901]

I found if I create link to toc.xhtml in nav and create a separate HTML Table Of Contents, I will have link to toc in toc, which is only a little better that the original epub. So I decide to use solution 4: Remove link to TOC or nav.

[KevinH]

An internal href to # should always work to navigate to the top of that page from that page. Which e-readers have trouble with that basic approach?

This specific style of internal linking is part of the html5 spec:

Note: You can use href="#top" or the empty fragment (href="#") to link to the top of the current page, as defined in the HTML specification.

[cges30901]

I tested several viewers, all of them can navigate from nav.xhtml page, but some can not navigate from application's TOC menu (don't know how to call it).

viewers that can: duokan (Android), Calibre (Linux)
viewers that can not navigate from application's TOC menu: Reasily (Android), Lithium (Android)

Some viewers don't even support epub 3 nav, so I have to generate NCX. But those do work, like KOReader (Android) and Moon+ (Android).

[KevinH]

It sounds like some of the Android based e-readers are very broken.

Navigating an internal link using "#" from any html document to the top of that page has been a part of the html spec since before even html4. All e-readers should support a spec that old by now.

An e-reader can have many navigation menus generated.

For example on epub2:
1. a generated toc from the ncx (no internal linking from ncx to itself is allowed or needed) The ncx is machine parseable.

2. a navigation aid based on the opf guide to major sections of the book
(again no internal linking within the guide to itself is allowed or needed)

3. An separate html file created to act as a user viewable table of contents
(here internal linking is possible) typically added to the opf spine. Typically is not machine parseable easily.

Under epub3 you have the toc and landmarks sections both from the nav.xhtml used to replace the ncx and the opf guide. But because the nav.xhtml is html5 based, internal links from the nav to itself are possible under the spec. Although pure html5, the nav.xhtml must always be machine parseable. It need not be added to the spine or may be added as linear = no.


In older epub2 only e-readers, adding an ncx and opf guide section to an epub3 helps to make them more usable.

So in any and all html based table of contents, using a "#" to navigate internally to within itself to the top of page must work or your e-reader app is very broken as that has long been part of the html and html5 specification.

[DiapDealer]

I don't really worry much about minor players in the android-epub-reader-du-jour game. They come and go like the weather.

If there's quick and easy, non-intrusive, spec-compliant workarounds we can add to make more android readers happy, I'm all for it. But if they can't handle the very basics of how html is supposed to work, I'm not inclined to spend much energy helping their broken reading apps do what they should already know how to do.

[KevinH]

The only workaround is to move from an internal style link (implemented as a simple scrollTo in all browsers and Sigil) to an external style link, which would need to pass all network security and in Sigil's case (like most browsers) requires a complete reload of Preview and re-rendering of the page and reloading of the current tab and re syntax highlighting in CodeView. All just to scroll to the top of the page!

This style of internal linking has worked since the early html4 days and is in the spec. I do not want to change that because of really poorly written e-readers on Android.

[DiapDealer]

I agree. That's way too much work for something that should already "just work" in anyone's reading app.

[pazos]

Originally Posted by cges30901

I tested several viewers, all of them can navigate from nav.xhtml page, but some can not navigate from application's TOC menu (don't know how to call it).

viewers that can: duokan (Android), Calibre (Linux)
viewers that can not navigate from application's TOC menu: Reasily (Android), Lithium (Android)

Some viewers don't even support epub 3 nav, so I have to generate NCX. But those do work, like KOReader (Android) and Moon+ (Android).

Yeah, most (homemade) ebook readers don't support some epub3 specs. Probably IDPF folks are aware of this and thus include legacy NCX on most of their epub3 samples.

I use both KOReader and Moon+. Moon+ will generate a TOC based on toc.xhtml, if available. KO wont. The workaround most ko users will do is generating a new toc based on h1-h6 headers (by long pressing the toc entry in the menu).

Anyways, if you're looking for apps to test the epub3 you can use the charts in http://epubtest.org/results and sort the results looking for basic functionality. Some of the usual suspects are Apple books, Google books, ADE and gitden.

While Moon+ is not included in the charts it does support a subset of epub3, specially text-direction (for vertical text) and ruby tags.

I see no reason other that "nobody is using that feature" for Moon+ to be epub3 compliant, as it is based on webview. Sadly that's not the case of KOReader, where some parts of the specs, like media playing or css-writting-modes, won't be supported with current rendering backends (crengine and mupdf).

In short: you can safely exclude KO, FBReader, AlReader, Kybook3, Hyphen, TiReader, Coolreader, MuPDF viewer... and do your tests on:

- iOS: ADE/ Bluefire reader/ Play Books, Apple Books
- Android: ADE/ Bluefire reader/ Play Books / Moon+ / Gitden
- Linux: foliate
- Web: anything based on epub.js, like epubViewer