When testing whether Amazon will ingest our epubs, we've been receiving errors that state:
"Guide title is empty. Item is ignored"
"This index is empty and has been skipped"
"Hyperlink not resolved: OEBPS/toc01.html"
"Some hyperlinks could not be resolved."
I was able to locate the source of these errors in the content.opf file, which is created by opf.xsl. All 4 errors relate to the <guide> element, which is created by the generate-guide template. The <guide> element contains <reference> elements as children. There is a <reference> for the Cover, TOC, and Title Page. The <reference>s for the Cover and TOC each have 3 attributes: href, type, and title, while the <reference> for the Title Page only has the first two. The <guide> element is an EPUB2 navigation standard that we include for backward-compatibility with older e-readers.
To fix the first two errors, I added a title="Start of Text". To fix the second two errors I removed the template that creates the <reference> link to the TOC.
I also updated opf.xspec to match the changes. Unfortunately, when we were previously reviewing the HTMLBook test suite, we were unable to get many of the XSPEC tests working, including the one that tests generate-guide. XSPEC is not commonly used and we weren't able to find much help online, so we decided to mark test that errored out as pending. However, I wanted to make sure that if in the future that changed that the generate-guide test was up-to-date. XSPEC is also relatively human-readble, so the pass/fail states should be clear even without being able to run the test.
When testing whether Amazon will ingest our epubs, we've been receiving errors that state:
I was able to locate the source of these errors in the content.opf file, which is created by opf.xsl. All 4 errors relate to the
<guide>element, which is created by thegenerate-guidetemplate. The<guide>element contains<reference>elements as children. There is a<reference>for the Cover, TOC, and Title Page. The<reference>s for the Cover and TOC each have 3 attributes: href, type, and title, while the<reference>for the Title Page only has the first two. The<guide>element is an EPUB2 navigation standard that we include for backward-compatibility with older e-readers.To fix the first two errors, I added a
title="Start of Text". To fix the second two errors I removed the template that creates the<reference>link to the TOC.I also updated opf.xspec to match the changes. Unfortunately, when we were previously reviewing the HTMLBook test suite, we were unable to get many of the XSPEC tests working, including the one that tests
generate-guide. XSPEC is not commonly used and we weren't able to find much help online, so we decided to mark test that errored out aspending. However, I wanted to make sure that if in the future that changed that thegenerate-guidetest was up-to-date. XSPEC is also relatively human-readble, so the pass/fail states should be clear even without being able to run the test.