View Full Version : OPF & guide


Nate the great
08-05-2009, 10:12 AM
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
08-05-2009, 10:17 AM
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
08-05-2009, 10:24 AM
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
08-05-2009, 11:36 AM
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
08-05-2009, 11:38 AM
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:


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
08-05-2009, 11:44 AM
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
08-05-2009, 11:49 AM
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
08-05-2009, 12:18 PM
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
08-05-2009, 12:20 PM
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
08-05-2009, 12:41 PM
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
08-05-2009, 12:42 PM
BTW, I wouldn't generate the cover; I'd simply create a reference to it if it existed.

kovidgoyal
08-05-2009, 02:17 PM
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
08-05-2009, 02:38 PM
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
08-05-2009, 02:39 PM
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
08-05-2009, 02:51 PM
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?

Nate the great
08-05-2009, 02:53 PM
Define "first page".


A separate file named cover.html.

kovidgoyal
08-05-2009, 02:55 PM
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.

A button that says "Click me to add cover"?

kovidgoyal
08-05-2009, 02:56 PM
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

No, it could for example be a copyright page with publishers logo.

ahi
08-05-2009, 03:05 PM
No, it could for example be a copyright page with publishers logo.

As the first thing in an eBook? Do you mean "title page"?

If a book has no cover, the "title page" is the next best thing... making treating it as a cover still the right choice.

As for what constitutes a page? Whatever would result in the image being rendered by itself on the device display.

Whether it is by virtue of it being in a separate cover.html file, or whatever other ways ePub gurus could accomplish much the same. Or is there no other way to do that?

- Ahi

kovidgoyal
08-05-2009, 03:12 PM
Suppose the user wants to set a new cover in an epub file. Now should calibre replace the first entry in the spine or not? That is the question.

The only way to unambiguously answer it is to have some pointer in the OPF file that tells calibre whether the first entry in the spine is a cover or not.

Try to guess if the first entry is a cover is not at all robust, just take my word for it, I lack the patience to enumerate all the cases where any guessing algorithm will fail.

ahi
08-05-2009, 03:19 PM
Suppose the user wants to set a new cover in an epub file. Now should calibre replace the first entry in the spine or not? That is the question.

The only way to unambiguously answer it is to have some pointer in the OPF file that tells calibre whether the first entry in the spine is a cover or not.

Try to guess if the first entry is a cover is not at all robust, just take my word for it, I lack the patience to enumerate all the cases where any guessing algorithm will fail.

What about presenting that first image to the user (in a window) at the beginning of the conversion process, and asking them to indicate (by a click) whether it is to be deleted or left in place after the addition of the new cover at the beginning of the eBook?

That seems dummy proof, no?

- Ahi

Valloric
08-05-2009, 03:56 PM
A separate file named cover.html.

You cannot seriously expect all epubs to have a file named "cover.html" in them, can you?

What about presenting that first image to the user (in a window) at the beginning of the conversion process, and asking them to indicate (by a click) whether it is to be deleted or left in place after the addition of the new cover at the beginning of the eBook?

That seems dummy proof, no?

I was just about to advise something similar. Calibre could start reading the file and presenting the images that appear in the book, from first to last. Arrow buttons for "next", "previous", "Select image" and "Cancel".

This should always work, guide element present or not.

Valloric
08-05-2009, 03:59 PM
A button that says "Click me to add cover"?

Sigil doesn't work that way. What if the user just imported an image and placed it at the beginning of the file? Not to mention that an "add cover image" button is redundant because of the above way of doing this, which most people want to use anyway.

There should be no difference between a cover image and any other image in an epub. Any such difference would be arbitrary and artificial. Reading systems are not required to use the guide element, and even if they were, ebook authors are not required to specify a cover page.

ahi
08-05-2009, 04:14 PM
Sigil doesn't work that way. What if the user just imported an image and placed it at the beginning of the file? Not to mention that an "add cover image" button is redundant because of the above way of doing this, which most people want to use anyway.

There should be no difference between a cover image and any other image in an epub. Any such difference would be arbitrary and artificial. Reading systems are not required to use the guide element, and even if they were, ebook authors are not required to specify a cover page.

Hmmm... I'm not sure your thinking is necessarily sound here.

A "cover" probably should be treated as metadata, if technology allows. Are there reasons to avoid doing so? (Other than "it's not as easy for Sigil's users"?)

- Ahi

kovidgoyal
08-05-2009, 04:15 PM
Sigil doesn't work that way. What if the user just imported an image and placed it at the beginning of the file? Not to mention that an "add cover image" button is redundant because of the above way of doing this, which most people want to use anyway.

There should be no difference between a cover image and any other image in an epub. Any such difference would be arbitrary and artificial. Reading systems are not required to use the guide element, and even if they were, ebook authors are not required to specify a cover page.

Yes but users like to change the covers of ebooks. To me, what users actually want is far more important than what the EPUB spec says they should want.

If the user just imports an image file at the beginning of the document and doesn't specify that it's a cover, that's the users problem. But Sigil should at least present the possibility for a user to do it the right way.

At the very least Sigil should not strip out existing guide elements, unless the file it points to is removed.

Nate the great
08-05-2009, 04:21 PM
You cannot seriously expect all epubs to have a file named "cover.html" in them, can you?


No, I don't. I'm still thinking about how to cooperate with this odd little thing that Kovid did.

TBH, I've moved it down my list of priorities. It's not in the spec so there's no reason for me to mess with it.

Valloric
08-05-2009, 04:28 PM
A "cover" probably should be treated as metadata, if technology allows. Are there reasons to avoid doing so? (Other than "it's not as easy for Sigil's users"?)

Oh I'd love it if the EPUB spec had some "cover image" metadata. That would be awesome. But it doesn't. What little it has that could be used to specify the cover image is not mandatory.

EDIT: And even that cannot be used to specify the cover image, only the cover page!

Yes but users like to change the covers of ebooks.

Open it in Sigil, delete the cover image, insert a new one. Done. No need for a guide element.

If the user just imports an image file at the beginning of the document and doesn't specify that it's a cover, that's the users problem. But Sigil should at least present the possibility for a user to do it the right way.

Fair point. But the "right way" is arbitrary now, it's what you say is "right". I say "right" means putting an image at the beginning of the document. Again, there is no way to semantically specify the cover image in an epub that all reading systems would have to respect.

Even ADE has its own proprietary extension for this I believe.


At the very least Sigil should not strip out existing guide elements, unless the file it points to is removed.

The file pointed to is not present after importing. Sigil disassembles the imported epub and creates the NCX, OPF etc on export. These files are not stored after they are imported.

kovidgoyal
08-05-2009, 04:37 PM
Oh I'd love it if the EPUB spec had some "cover image" metadata. That would be awesome. But it doesn't. What little it has that could be used to specify the cover image is not mandatory.


Yes but it exists, why not use it?



Open it in Sigil, delete the cover image, insert a new one. Done. No need for a guide element.


Yes, but the world is larger than Sigil.



Fair point. But the "right way" is arbitrary now, it's what you say is "right". I say "right" means putting an image at the beginning of the document. Again, there is no way to semantically specify the cover image in an epub that all reading systems would have to respect.


It's not arbitrary, it's in the spec. The fact that reading systems dont have to support it is immaterial, since the cover is also the first element in the spine.



The file pointed to is not present after importing. Sigil disassembles the imported epub and creates the NCX, OPF etc on export. These files are not stored after they are imported.

Doesn't mean you can't keep an internal pointer to the file and output it in the generated OPF.

Valloric
08-05-2009, 05:20 PM
Doesn't mean you can't keep an internal pointer to the file and output it in the generated OPF.

There is no "file". It's content is read, parsed and copied to an internal buffer along with the other OPS documents. Nothing of the original document remains.

But I did notice you completely ignored suggestions for a dialog that lets the user specify what is the cover image. The world is larger than calibre, too. A lot of epubs, if not the vast majority, will not have the guide element.

So let's make a deal: you make a dialog for specifying what is the cover image in the book in calibre, and I'll add WYSIWYG actions for specifying what is a cover page in Sigil (which will generate the guide element on export). Deal?

I think this works in the user's favor, no matter what the application.

kovidgoyal
08-05-2009, 05:26 PM
Sigh, whatever, I give up. I can see that getting Sigil to play well with calibre is not going to happen.

Probably faster for me to just make my own EPUB editor.

pdurrant
08-05-2009, 05:30 PM
Kovid, perhaps you missed the bit where Valloric said "Sigil [...] will generate the guide element on export"

I think it's a good point that not all ePubs will have this guide element, and it would be great if Calibre provided a work-around for this case.

Sigh, whatever, I give up. I can see that getting Sigil to play well with calibre is not going to happen.

Probably faster for me to just make my own EPUB editor.

Valloric
08-05-2009, 05:30 PM
Sigh, whatever, I give up. I can see that getting Sigil to play well with calibre is not going to happen.

Probably faster for me to just make my own EPUB editor.

This I think is a bit unnecessary Kovid. I'm willing to compromise and I'm certainly more than willing to do everything in my power to make Sigil play well with calibre. In the end, I'll just make the guide element if that will be what it takes to end what seems to have grown from a polite discussion to an argument. No need to do anything on your part...

I'm absolutely shocked you said something like this Kovid. I really am.

Valloric
08-05-2009, 05:34 PM
Kovid, perhaps you missed the bit where Valloric said "Sigil [...] will generate the guide element on export"

Yes, I thought I said that. I wanted Sigil to create whatever is necessary to work with calibre, but I also wanted calibre to work better with other epubs that might not come from an app that takes this into consideration.

But if he's going to get angry over this, then I'll just help out and he can sulk. I'm not going to go into a pissing contest over an XML element.

EDIT: I still don't see any need for anyone to get angry here. I mean WTH I still can't fathom the turn this thread took.

kovidgoyal
08-05-2009, 05:42 PM
Sorry about that, I'm having a rough day and this seems like such a trivial thing that I am amazed we ended up going 18 rounds over it. I just didn't expect to have to spend hours arguing over it.

As for getting Sigil and calibre to co-operate I'm all for it. In fact I have been planning to add a button to the calibre GUI to launch Sigil with the EPUB in the calibre database (making for a convenient workflow). With regards to that, I have some ideas about IPC I'd like to hash out with you, but perhaps over email. Just PM me your email address.

Valloric
08-05-2009, 05:51 PM
Sorry about that, I'm having a rough day and this seems like such a trivial thing that I am amazed we ended up going 18 rounds over it.

You're absolutely right here. The rough day I can understand and I'm willing to forget this whole rather retarded thread and move on.

I just didn't expect to have to spend hours arguing over it.

I honestly didn't see it as an argument. Honestly. I saw it as a polite discussion, like any number of others I've had the privilege of participating in here on MobileRead.


As for getting Sigil and calibre to co-operate I'm all for it. In fact I have been planning to add a button to the calibre GUI to launch Sigil with the EPUB in the calibre database (making for a convenient workflow). With regards to that, I have some ideas about IPC I'd like to hash out with you, but perhaps over email. Just PM me your email address.

I'll do that right now.

And just for the record so nothing is left lingering... I've never had anything but the utmost respect for you Kovid. You have single-handedly made the whole e-book market pleasant for the everyday user. I personally would have never bought an ebook reading device if it weren't for calibre and your efforts.

kovidgoyal
08-05-2009, 05:57 PM
Cool, this thread is closed. And I apologize once again for my rudeness. And calibre is much more than my single handed effort. All I can really take credit for is getting it going. It now has a life of its own, as evidenced by the declining percentage of code I commit to it :)

JSWolf
08-05-2009, 05:57 PM
Sigil can do what Book Designer did which was take the first page as a cover. And if the first page is blank ([age break with nothing in front of it), Sigil can then take that as there is no cover.

Jellby
08-06-2009, 06:25 AM
Sigil doesn't work that way. What if the user just imported an image and placed it at the beginning of the file?

Have an option to mark (and unmark) the first page (which may be an image or whatever) as "cover". It can be shown in some particular way on the screen, and on export will be marked as cover in the guide.

Reading systems are not required to use the guide element, and even if they were, ebook authors are not required to specify a cover page.

Reading systems are not required to properly display "text-variant: small-caps" or "display: oeb-page-header", and yet I'm sure you can generate that with Sigil.

Valloric
08-06-2009, 10:53 AM
Have an option to mark (and unmark) the first page (which may be an image or whatever) as "cover". It can be shown in some particular way on the screen, and on export will be marked as cover in the guide.

Jellby, Kovid and I are working through email on making this (and more) happen. Please don't poke this thread, leave it to die. :)

Jellby
08-06-2009, 12:13 PM
Sorry :)