search

oreillymedia / HTMLBook

Let's write books in HTML!
http://oreillymedia.github.io/HTMLBook
MIT License
650 stars 100 forks source link

TOOLSREQ-6840: Adding Title Attribute to <reference> Element in content.opf #235

Closed nadamsoreilly closed 3 years ago

nadamsoreilly commented 3 years ago

When testing whether Amazon will ingest our epubs, we've been receiving errors that state: "Guide title is empty. Item is ignored" and "This index is empty and has been skipped". I was able to locate the source of this error in the content.opf file, which is created by opf.xsl.

In content.opf, there is a <guide> element, which contains 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.

Looking at the logic within opf.xsl, this seems to be because the Title Page <reference> is set up to be flexible if there is no Title Page within the book, and so we didn't want to hardcode a title attribute. However, given that this is preventing ingestion to Amazon as well as the fact that every O'Reilly title built in Atlas has a title page, I believe it is worth it to hardcode this attribute.

Note that I'm planning on writing up an XSpec test for this, but given the relative urgency to begin testing, I wanted to get the PR up as soon as possible.

EDIT: I also wasn't sure if this would fit better under the ATLAS JIRA board better. I can move the ticket if need be.

nadamsoreilly commented 3 years ago

I agree that it makes sense to put off a test; maybe that can be written while this is staged? And out of curiosity, does xspec have the concept of "pending" tests like RSpec does? I've used that sometimes to remind me I need to write the test. But I don't think that should block this from QA.

That's a good point. My plan is to write the test next week while this is on Staging. This will need extensive QA testing of the Amazon ingestion pipeline while on staging anyway, so there should be time.

hackermatthew commented 3 years ago

If the assumption is that we'll always have a title page, I'm wondering if we should make a larger change as well and get rid of the fallback options in generate.guide for cover and first section. Also, "Title Page" as the hard-coded guide title makes sense if that's the case, but if we're keeping the fallbacks, should the guide title be more generic (e.g., "Start of Text")? My understanding is that's what the title page represents according to the comments.

Finally, getting rid of the guide element completely may be something we want to consider in the future, because it looks like it's been superseded by other metadata in EPUB 3: https://www.w3.org/publishing/epub3/epub-packages.html#sec-opf2-guide.