[Plugin] ePub3-itizer - epub3 output plugin for Sigil

[AlanHK]

Originally Posted by KevinH

And afaict there is no valid reason to use nbsp in pre since you control the line breaks. So I am not sure the original xhtml code was valid to begin with. I will see if I can find a clearer spec.

It passed epubcheck.

I didn't insert nbsp in the pre sections deliberately, but I do a global conversion of ellipses to spaced periods, so that must have created it.

nbsp is not "preserved" in Sigil settings.



New version, works, thanks.

[philja]

After using ePub3-itizer to convert a 'no-fault-found' epub2 book to epub3, I've eliminated all the pink Validation Results (mostly involving image width being defined as %) except this one:

OEBPS/content.opf,127,9919,"Col: 92: ERROR(OPF-096): Non-linear content must be reachable, but found no hyperlink to "OEBPS/nav.xhtml"."

I've spent some time reading all 30 pages of this thread plus some others but don't understand how to fix the error. I take it that the reference to 'non-linear content' is down to the spine entry <itemref idref="navid" linear="no"/>.

I've seen KevinH's note in post #17 of this thread stating

" The created nav.xhtml is called is "nav.xhtml" not "toc.xhtml" and will be found right beside the content.opf file, not in the Text folder."

I realise that was getting on for ten years ago and things, including plugins, change. But the Text folder is exactly where the nav.xhtml file is.

I understand that nav.xhtml is required by the spec, but for reading purposes, none of the content files need to link to it—that sort of communication is satisfied for the human reader by the existing HTML table of contents file (chapter3.xhtml in the book), which has links back from chapter headings. I note, too, that for Kindles, I can simply remove nav.xhtml from the spine to avoid it being displayed as a duplicate of the HTML toc.

If I understand correctly, the reading device will use and display nav.xhtml if it operates at the epub3 level. Otherwise, epub2 devices will use the everpresent toc.ncx file.

So, do I understand that epub3-itizer has created the nav.xhtml file as an orphan? Which files should link to it? What is the best solution to avoid this error message?

[DiapDealer]

Originally Posted by philja

I take it that the reference to 'non-linear content' is down to the spine entry <itemref idref="navid" linear="no"/>.

Not sure. That might be the reference, but that spine entry itself won't produce an epubcheck error like that. An empty epub3 created by Sigil contains that same spine entry and does not trigger that particular EpubCheck error. It might be something else. What does the line number in the opf error correspond to?

[philja]

Originally Posted by DiapDealer

Not sure. That might be the reference, but that spine entry itself won't produce an epubcheck error like that. An empty epub3 created by Sigil contains that same spine entry and does not trigger that particular EpubCheck error. It might be something else. What does the line number in the opf error correspond to?

The line 127 in content.opf is

  <item id="navid" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>

This is the final entry in the manifest just before the </manifest> tag.

Edit: I've been trying a few things and if I change the last line in the spine from
<itemref idref="navid" linear="no"/> to
<itemref idref="navid" linear="yes"/>

and then run epubcheck again, there is the good news 'No problems found!'

This is repeatable when linear is no, there's the problem, yes gets rid of it. I've gone backwards and forwards several times.

Further: IIRC KevinH said somewhere that an empty entry is taken as 'yes' by default so I tried
<itemref idref="navid"/>
and again 'No problems found!'

[DNSB]

For what it's worth, I've attached a dummy epub which shows the error when linear="no" is used in the spine entry for the nav.xhtml file. Removing the linear="no" or changing to linear="yes" does not display the error. I also played with changing the ID and that did not help. Removing the line from the spine entries also worked.

I did find that adding the following to the nav.xhtml file cleared the error:

  <nav epub:type="landmarks"><h2>Guide</h2>

  <ol>
    <li><a epub:type="toc" href="nav.xhtml"> Table of Contents </a></li>
  </ol></nav>

Probably since it supplies the hyperlink for the nav.xhtml file.

[philja]

Originally Posted by DNSB

For what it's worth, I've attached a dummy epub which shows the error when linear="no" is used in the spine entry for the nav.xhtml file. Removing the linear="no" or changing to linear="yes" does not display the error. I also played with changing the ID and that did not help.

Yes - that's exactly what I'm getting. If that has not been reported before, there must have been some regression.

[DNSB]

I think that error message was added to the 5+ versions of epubcheck. See #1451 in the epubcheck issues for more information.

Previously while the ePub spec required that link, epubcheck did not check for that condition.

[philja]

Originally Posted by DNSB

I think that error message was added to the 5+ versions of epubcheck. See #1451 in the epubcheck issues for more information.

Previously while the ePub spec required that link, epubcheck did not check for that condition.

Interesting. That article quotes the spec as saying :

EPUB creators MUST provide a means of accessing all non-linear content (e.g., hyperlinks in the content or from the EPUB navigation document).

The error message produced by epubcheck only seems to be concerned with links to the nav document. The nav document itself has plenty of links the other way "from the EPUB navigation document".

This seems to have been a problem since around March 2023 with people complaining about the same error message about a cover page.

[DNSB]

Originally Posted by philja

Interesting. That article quotes the spec as saying :


The error message produced by epubcheck only seems to be concerned with links to the nav document. The nav document itself has plenty of links the other way "from the EPUB navigation document".

This seems to have been a problem since around March 2023 with people complaining about the same error message about a cover page.

Basically the same issue since many people do not supply a link to the cover page and so marking it as linear="no" is a no-no (sorry, couldn't resist). At one time, there was a piece of advice to include all text files in the nav document.

I did a test when I was playing with the test file by adding a cover file and image and marking the cover file as linear="no" and got the same error message except for the file name.

March, 2023 would make sense in terms of epubcheck 5.0 being commonly used.

[KevinH]

This is a bug in epubcheck as far as I can tell. I exchanged comments with them as well.
See my post here and their replies.

https://github.com/w3c/epub-specs/is...ent-1496140289

The issue is that epubcheck now wants *all* xhtml linear="no" in the spine to have a direct link to that file from some other resource in the spine. This was seemingly done to prevent unseeable spine content in all epub readers.

That requirement is fine for normal xhtml files but NOT the nav document itself. Any epub3 e-reader can always access the nav itself, so it should be exempt from this new requirement by epubcheck.

There are only 3 workarounds:

1. remove the nav completely from the spine, and edit the nav code to remove its own internal link to its toc in its landmarks section as only files listed in the spine can be linked to, due to epubcheck. But removing it from the spine means no easy drag and drop reordering in Sigil.

2. create the css necessary and link it to the nav so that the nav appears just like a desired xhtml toc in appearance and remove the linear="no" associated with the nav so that the nav itself functions like a directly linked user xhtml toc file (ie it plays 2 roles - both machinereadable nav and user toc). But not everyone wants a user xhtml toc.

3. leave it as is, but create a link to the nav.xhtml from some other file such as a user toc.xhtml. This is the solution I use until epubcheck gets fixed.

None of these workarounds are ideal. The bug that requires a link to the nav.xhtml from some other spine resource just because it has linear="no" in the spine should really be fixed in epubcheck.

Sigil and epub3-itizer use linear="no" on the nav entry in the spine as that used to be the documented best practice for epub3 during 3.0, 3.1, and 3.2 specs, and earlier epubcheck versions.

I am still hoping someone from epubcheck will come to their senses and exempt a properly specified nav from having to meet this new additional requirement.

[DiapDealer]

Sigil's blank ePub3 (with linear="no" in the spine) doesn't produce this error with the latest epubcheck. Does our default epub link directly to the nav somewhere?

[KevinH]

Not that I know of. But in our Sigil User Guide, I had to add a link from the xhtml user toc to the nav to get it to pass epubcheck.

[DNSB]

Originally Posted by DiapDealer

Sigil's blank ePub3 (with linear="no" in the spine) doesn't produce this error with the latest epubcheck. Does our default epub link directly to the nav somewhere?

Yes, the Landmarks section of nav.xhtml links to the toc ID of the nav.xhtml document.

That's where I lifted the bit of code I added to the sample file to fix the error.

[philja]

My little error has opened up visibility of a large existing can of worms, I see. All very interesting.

KevinH This is a bug in epubcheck as far as I can tell. I exchanged comments with them as well.
See my post here and their replies.
https://github.com/w3c/epub-specs/is...ent-1496140289

A very interesting exchange where I came upon a couple of notions that I am not familiar with : foreign resource, fallback. I take it that a foreign resource is one not contained within the epub. Is that correct? And fallback is a last resort when the reading device is unable to cope?

1. remove the nav completely from the spine, and edit the nav code to remove its own internal link to its toc in its landmarks section as only files listed in the spine can be linked to, due to epubcheck. But removing it from the spine means no easy drag and drop reordering in Sigil.

In my problem epub3 doc, the nav.xhtml file does not have an internal link to its toc in its landmarks section although I see that a new blank epub3 file generated by Sigil does. Instead, my nav.xhtml landmarks produced by the conversion plugin essentially just reproduces the guide section from the content.opf:

<guide>
    <reference type="title-page" title="Title page" href="Text/chapter.xhtml"/>
    <reference type="text" title="Text" href="Text/chapter2.xhtml"/>
    <reference type="toc" title="Table of Contents" href="Text/chapter3.xhtml"/>
    <reference type="cover" title="Cover" href="Text/titlepage.xhtml"/>
  </guide>

  <nav epub:type="landmarks" id="landmarks" hidden="">
      <h2>Guide</h2>
      <ol>
        <li>
          <a epub:type="titlepage" href="Text/chapter.xhtml">Title page</a>
        </li>
        <li>
          <a epub:type="bodymatter" href="Text/chapter2.xhtml">Text</a>
        </li>
        <li>
          <a epub:type="toc" href="Text/chapter3.xhtml">Table of Contents</a>
        </li>
        <li>
          <a epub:type="cover" href="Text/titlepage.xhtml">Cover</a>
        </li>
      </ol>
    </nav>

With the "toc" link going to my HTML toc.

2. create the css necessary and link it to the nav so that the nav appears just like a desired xhtml toc in appearance and remove the linear="no" associated with the nav so that the nav itself functions like a directly linked user xhtml toc file (ie it plays 2 roles - both machinereadable nav and user toc). But not everyone wants a user xhtml toc.

To do this, replacing the author HTML toc, would, in my case involve serious editing effort to add loads of anchors to the entries because all my chapters have links back to the HTML toc.

3. leave it as is, but create a link to the nav.xhtml from some other file such as a user toc.xhtml. This is the solution I use until epubcheck gets fixed.

I've seen this implemented at the end of the Sigil guide's HTML toc. It looks like a tidy solution but I'm in no hurry so I'll wait and see whether and how the subject evolves.

[KevinH]

To test DNSB's theory that even an internal link from a non-linear resource (the nav) back to itself is enough to fool the epubcheck test (why a link from a non-linear resource to itself would make any difference is beyond me).

I changed the Sigil User's Guide nav landmarks section to to add an internal back link (see the last li I added below):

  <nav epub:type="landmarks" id="landmarks" hidden="">
    <h1>Landmarks</h1>
    <ol>
      <li>
        <a epub:type="cover" href="Text/cover.xhtml">Cover</a>
      </li>
      <li>
        <a epub:type="bodymatter" href="Text/introduction.xhtml">Text</a>
      </li>
      <li>
        <a epub:type="toc" href="Text/toc.xhtml">Table of Contents</a>
      </li>
      <li>
        <a epub:type="toc" href="#toc">Nav Table Of Contents</a>
      </li>
    </ol>
  </nav>

And I removed the link from the xhtml toc to the nav I had added just to make it pass, and sure enough, it passes epubcheck!

So DNSB's theory is right! We can prevent the whole epubcheck bug from hitting by just adding an internal link from the nav landmarks back to the nav table of contents and that fools the code into thinking that all non-linear resources are reachable from some linear resource.