search

w3c / epubcheck

The conformance checker for EPUB publications
https://www.w3.org/publishing/epubcheck/
BSD 3-Clause "New" or "Revised" License
1.66k stars 402 forks source link

"Non-linear content must be reachable," error for OEBPS/cover.xhtml in epubcheck 5.0.0: why? #1488

Open idiotprogrammer opened 1 year ago

idiotprogrammer commented 1 year ago

I created an epub file which validated in epubcheck 4.2.6 with no errors. Now I'm trying to validate it with the  command line tool of the latest epubcheck 5.0.0 for epub3.3 and I got this message: 

ERROR(OPF-096): hostage25.epub/OEBPS/package.opf(31,79): Non-linear content must be reachable, but found no hyperlink to "OEBPS/cover.xhtml".

I'm not familiar enough with 3.3 epub standard to know what's going on, but in package.opf, I have the lines: 

<manifest>.....     
 <item id="cover" href="cover.xhtml" media-type="application/xhtml+xml"/>
  <item id="cover-image" properties="cover-image" href="images-epub/hostage-hillyer-cover.jpg" media-type="image/jpeg"/>
...</manifest> 

I assume that the 5.0.0 validation error message does NOT mean that I should have a TOC entry in the navigation html document for the cover image. Surely that is not being required, right? 

(by the way, if you want to examine the epub file in question that I'm using ,  it's on a public facing website -- it's a public domain ebook  https://www.personvillepress.com/11378h/random/hillyer/robert-hillyer-my-heart-for-hostage10.epub )

Thanks. rjn

idiotprogrammer commented 1 year ago

With regard to the issue I posted a few minutes ago, I just wanted to note that the epub in the URL and the epub being validated have different file names, but they are identical files.

When I test on the epub in the URL, I get the identical error message: ERROR(OPF-096): robert-hillyer-my-heart-for-hostage10.epub/OEBPS/package.opf(31,79): Non-linear content must be reachable, but found no hyperlink to "OEBPS/cover.xhtml".

rdeltour commented 1 year ago

The EPUB spec requires that non-linear content (the documents referenced in an itemref element with a linear attribute set to "no") are reachable from linear content; typically, from a hyperlink in a content document or in the navigation document.

This requirement dates back to at least EPUB 3.1, but the check has only been recently added to EPUBCheck (in #1451).

I assume that the 5.0.0 validation error message does NOT mean that I should have a TOC entry in the navigation html document for the cover image. Surely that is not being required, right?

A toc entry is not specifically required, but some kind of link yes. The easiest workaround for now is to add a landmarks nav element to your navigation document, listing the cover page.

All that said, your case (a non-linear cover image) is one that @mattgarrish foresaw could lead to confusion. But this is not directly an issue with EPUBCheck, which correctly implements the specification here, but more of the specification itself. It could be discussed in a new issue on the EPUB specification.

I'll leave this issue open for a while, in case others have thoughts or the WG decides that the spec should be amended or EPUBCheck made less strict.

idiotprogrammer commented 1 year ago

rdeltour, Thanks for the insight. FYI, this epub was generated through docbook XSLT, and I need to look into how the xslt can output landmarks.

In the meantime, I found that hardcoding a conventional hyperlink to "OEBPS/cover.xhtml in one of the HTML output pages -- in my case the CREDITS AND ACKNOWLEDGEMENTS HTML page -- easily fixed the issue. (Because I'm just a stranger here, I won't close the issue; I'll leave it to you guys to handle. )

danielweck commented 1 year ago

Hello @idiotprogrammer , in your reflowable EPUB I don't see a strong justification for the "cover" HTML document to exist in the reading order, so alternatively (instead of adding a link just to pass EPUBCheck validation) you could remove <itemref idref="cover" linear="no"/> from your spine. Despite the EPUB specification being quite permissive (i.e. "do what you like" https://www.w3.org/TR/epub-33/#attrdef-itemref-linear ), I think that most reading systems ignore non-linear documents (i.e. skips them during the presentation of the reading order), but I know of one notable exception: when Apple "iBooks" (or Books.app on Mac) renders fixed-layout publications (aka FXL), the linear attribute itself is ignored, just as if it didn't exist (see https://help.apple.com/itc/booksassetguide/en.lproj/itc6120b3793.html ). In other words, linear="no" spine items behave as equivalent to linear="yes", which is the default fallback value when the attribute is absent. This causes major interoperability issues with reading systems that do support non-linear FXL documents, typically resulting in incorrect left/right synthetic spread order (totally broken user experience, mixed spread slots). In Thorium we decided to apply Apple's logic / to align with prior art, in order to correctly render existing FXL EPUBs that were incorrectly generated with linear="no" on the "cover" HTML / first spine item (just like your reflowable EPUB). I hope that makes sense. In summary: I think EPUBCheck correctly implements the specification (i.e. all non-linear documents must be "reachable"), but unfortunately the EPUB specification carries historical baggage that makes it impossible to fix the underspecified linear="no" conformance requirements, without introducing breaking changes. Back in the IDPF working group days, not everybody agreed on the interpretation of linear="no" and I don't think this has changed :)

jarupxx commented 1 year ago

I'm no expert either, but I think Apple "iBooks" is not EPUB 3 reader. It limited functions support doesn't even The page-spread-* properties of FXL. It renders in a spread, but that's it.

barnabynagy commented 9 months ago

This message drives me crazy! How do I fix it?

mattgarrish commented 9 months ago

See @rdeltour's comment above, specifically:

The easiest workaround for now is to add a landmarks nav element to your navigation document, listing the cover page.

barnabynagy commented 9 months ago

See @rdeltour's comment above, specifically:

The easiest workaround for now is to add a landmarks nav element to your navigation document, listing the cover page.

I don't know how, I'm not a tech user, I'm using Ulysses app and their export has this error.

mattgarrish commented 9 months ago

I'm using Ulysses app and their export has this error

You likely need to contact them, then, and see if they can fix their export.

There isn't a solution to the problem that doesn't involve manually editing your EPUB once it's been exported. A program like sigil would shield you from having to understand the nuances of an epub's zipping, but you'll still have to figure out how to add the landmarks nav with the correct entry.

barnabynagy commented 9 months ago

I'm using Ulysses app and their export has this error

You likely need to contact them, then, and see if they can fix their export.

There isn't a solution to the problem that doesn't involve manually editing your EPUB once it's been exported. A program like sigil would shield you from having to understand the nuances of an epub's zipping, but you'll still have to figure out how to add the landmarks nav with the correct entry.

I see, thanks for responding