OPF & guide

[Nate the great]

Does anyone know if there is Epub reading software that uses the guide tags of the OPF file? I'd like to know if I can leave it undeveloped.

Thank you.

[JSWolf]

Here is from the most recent conversion using Calibre from MS Reader to ePub and the guide tags are used.

  <guide>
    <reference href="titlepage.xhtml" type="cover" title="Cover"/>
    <reference href="huntersthe_split_0.html#cop" type="copyright-page" title="Copyright link"/>
    <reference href="huntersthe_split_5.html#contents" type="toc" title="Table of Contents"/>
    <reference href="huntersthe_split_0.html#cop" type="title-page" title="About this title link"/>
  </guide>

[Nate the great]

Originally Posted by JSWolf

Here is from the most recent conversion using Calibre from MS Reader to ePub and the guide tags are used.

  <guide>
    <reference href="titlepage.xhtml" type="cover" title="Cover"/>
    <reference href="huntersthe_split_0.html#cop" type="copyright-page" title="Copyright link"/>
    <reference href="huntersthe_split_5.html#contents" type="toc" title="Table of Contents"/>
    <reference href="huntersthe_split_0.html#cop" type="title-page" title="About this title link"/>
  </guide>

I just checked, and I beleive that was copied over from the OPF inside the MSReader ebook. Just becuase it's there doesn't mean anything uses it.

[kovidgoyal]

calibre uses the type="cover" entry in <guide> in epub books to know if the first entry in the spine is a cover or not. So if the user specifies their own cover and then re-converts, the original cover is replaced instead of becmoing the second item in the spine

[Valloric]

Originally Posted by Nate the great

Does anyone know if there is Epub reading software that uses the guide tags of the OPF file? I'd like to know if I can leave it undeveloped.

The guide section is in OPF 2.0 for backwards compatibility reasons, I think. From the OPF spec:

Originally Posted by OPF 2.0

Reading Systems are not required to use the guide element in any way.

Because of this, few reading systems will support it. It also (poorly) duplicates the functionality of the NCX, that is, a presentable Table Of Contents. It's pretty much useless.

BTW Sigil doesn't create it and it will strip it from your input epub if it has one.

[kovidgoyal]

Originally Posted by Valloric

BTW Sigil doesn't create it and it will strip it from your input epub if it has one.

Could you change that to leave type="cover" alone, there's no other way to know if the first element in the spine is a cover or not.

[Valloric]

Originally Posted by kovidgoyal

Could you change that to leave type="cover" alone, there's no other way to know if the first element in the spine is a cover or not.

Create an issue for it and I'll see what I can do.

[Nate the great]

Originally Posted by kovidgoyal

calibre uses the type="cover" entry in <guide> in epub books to know if the first entry in the spine is a cover or not. So if the user specifies their own cover and then re-converts, the original cover is replaced instead of becmoing the second item in the spine

I don't like how you generate the cover, but since this is relatively easy to accommodate I will.

[JSWolf]

Originally Posted by Nate the great

I don't like how you generate the cover, but since this is relatively easy to accommodate I will.

How would you generate the cover?

[Nate the great]

Originally Posted by JSWolf

How would you generate the cover?

There are several possibilities:

autodetection,
have a check box in the spine creation step for "first item is a cover",
prompt the user to add it it by hand,
and I'm sure there are a couple other ways it could be done.

[Nate the great]

BTW, I wouldn't generate the cover; I'd simply create a reference to it if it existed.

[kovidgoyal]

Whether the cover is generated or not is immaterial, the point is that given an epub file, if the user wants software to automatically replace the existing cover the only way the software can know that the file has an existing cover is via the guide.

This is not an issue for an editing software like Sigil, since the user can just manually remove the cover, but it is for an automatic converter like calibre.

[Valloric]

Originally Posted by kovidgoyal

This is not an issue for an editing software like Sigil, since the user can just manually remove the cover, but it is for an automatic converter like calibre.

This leads me to my main problem with this idea: I can't force the user to place a chapter break after an image and then somehow semantically mark this chapter/XHTML file as one containing the cover only. How would such a UI option even look like? How would it be presented to the user in a simple and understandable way? And honestly, why should the user care? If I were creating an epub book and would have no intention of messing with it in calibre, I would not do this. It would have no tangible benefit to me.

I also wouldn't want to do this automatically on export, not in an editor. An editor (unlike a converter) should never change the structure of the document the user sees in the editor. WYSIWYG means something very specific.

I would welcome suggestions on how could this be handled, because I can't see how it can be.

[ahi]

Originally Posted by kovidgoyal

Whether the cover is generated or not is immaterial, the point is that given an epub file, if the user wants software to automatically replace the existing cover the only way the software can know that the file has an existing cover is via the guide.

This is not an issue for an editing software like Sigil, since the user can just manually remove the cover, but it is for an automatic converter like calibre.

Wouldn't a first page consisting solely of an image be a reasonably certain indication that it is a cover... regardless of whether the metadata also attests it to be?

- Ahi

[Valloric]

Originally Posted by ahi

Wouldn't a first page consisting solely of an image be a reasonably certain indication that it is a cover... regardless of whether the metadata also attests it to be?

Define "first page".

Also, what happens when the user loads in an epub comic book?