giude item "cover" displayed as "Title page"

[quinta@ebf.cz]

Menu "Go to..." of ebook viewer displays guide item of type "cover" as "Title page". Even though guide item declares its own name (using title attribute). Moreover displayed name "Title page" is not factually correct (because cover != title page).

Guide section in toc.opf:

<?xml version="1.0" encoding="utf-8"?>
<package {...}>
  <metadata {...}>{...}</metadata>
  <manifest>{...}</manifest>
  <spine toc="ncx">{...}</spine>
  <guide>
    <reference type="cover" title="Obálka" href="Text/cover.xhtml"/>
    <reference type="title-page" title="Titulní strana" href="Text/title-page.xhtml"/>
    <reference type="text" title="Text" href="Text/chapter1.xhtml"/>
    <reference type="colophon" title="Tiráž" href="Text/imprint.xhtml"/>
  </guide>
</package>

Go to... menu:


Guide items of type "title-page", "text" and "colophon" are displayed (as expected) under their names, as declared in corresponding title attributes ("Titulní strana", "Text", "Tiráž").
Guide item of type "cover" is displayed as "Title page" (expected name: "Obálka").
And, which probably is not intentional either, as last in list. (Expected order would be either order of items in guide section, or order of target positions in document reading order definition...)

Calibre 7.7 (just for info, behaviour is not specific for this Calibre version)
epub attached

[DNSB]

One item is how did you generate a toc.ncx with every src changed to scr for all the pagelist entries?

Then there are the two pairs of entries pointing to the same target. Again, this is not valid.

  <navPoint id="navPoint1" playOrder="1">
    <navLabel><text>Báj</text></navLabel>
    <content src="Text/cover.xhtml"/>
  
    <navPoint id="navPoint2" playOrder="2">
      <navLabel><text>obálka</text></navLabel>
      <content src="Text/cover.xhtml"/>
    </navPoint>

  <navPoint id="navPoint33" playOrder="33">
    <navLabel><text>Báj</text></navLabel>
    <content src="Text/afterword.xhtml"/>
  
    <navPoint id="navPoint34" playOrder="34">
      <navLabel><text>doslov (Jaroslav Putík)</text></navLabel>
      <content src="Text/afterword.xhtml"/>
    </navPoint>

I would suggesting correcting these errors and then testing the epub again.

[kovidgoyal]

In the EPUB2 guide there must be only one guide entry of type cover that points to the actual cover image and one entry of type titlepage that points to the actual HTML file that displays that cover. Any other setup gets forced into this form by calibre's EPUB2 input processing. The viewer (and indeed all of calibre) require this for various kinds of further processing they do.

[quinta@ebf.cz]

Originally Posted by DNSB

One item is how did you generate a toc.ncx with every src changed to scr for all the pagelist entries?

Excelent observation! Page list was generated just for testing purposes, and probably would be abandoned as "not working"... (Calibre editor "Check book" function does not anounce any errors...) Well, now page list testing can start from zero again... My feelings are mixed.
Anyway, removing pageList section from ncx did not affect guide "cover" issue.

Originally Posted by DNSB

Then there are the two pairs of entries pointing to the same target. Again, this is not valid.

Pairs of navPoints pointing to the same target are intentional. They are part of TOC solution...
Anyway, removing "duplicate src" navPoints from navMap did not affect guide "cover" issue.

Thank you very much for suggestions.

[quinta@ebf.cz]

Originally Posted by kovidgoyal

In the EPUB2 guide there must be only one guide entry of type cover that points to the actual cover image and one entry of type titlepage that points to the actual HTML file that displays that cover. Any other setup gets forced into this form by calibre's EPUB2 input processing. The viewer (and indeed all of calibre) require this for various kinds of further processing they do.

I think I have never seen guide item of type "titlepage". As far as I know, Calibre generates just one guide item (as can be seen e.g. in conversion from docx) . It is of type "cover", and is pointing to file (containing cover image):

  <guide>
    <reference type="cover" href="titlepage.xhtml" title="Cover"/>
  </guide>

(Also there is nothing as type "titlepage" in EPUB2 standard. There is mentioned type "title-page" there...): https://idpf.org/epub/20/spec/OPF_2....htm#Section2.6

In any case, Calibre _can_ successfuly process other types of guide items (other then of type "cover"): they are added as fully functional items into "Go to..." menu in Veiwer. As you can see in attached epub. Actually only guide item of type "cover" is processed in "wrong" way... Probably because of its special role in Calibre.

Just tested: When the type "cover" is simply replaced with "something else", menu is generated perfectly. Of course this is not a good solution; readers can expect type "cover", and probably even Calibre would miss type "cover" in some situations.

<guide>
  <reference type="cover-dummy" title="Obálka" href="Text/cover.xhtml"/>
  <reference type="title-page" title="Titulní strana" href="Text/title-page.xhtml"/>
  <reference type="text" title="Text" href="Text/chapter1.xhtml"/>
  <reference type="colophon" title="Tiráž" href="Text/imprint.xhtml"/>
</guide>

One more note: Phrase "title page" (in file name "titlepage.xhtml", or in menu item name "Title page") from my opinion is in Calibre used in wrong context. Phrase "title page" is in book terminology used for different book part than "cover". (Ok, cover can be in some cases identified as title page. But typically "title page" is page inside of book, it si a part of book front matter...). Of course, name of file "titlepage.xhtml" is many years old Calibre convention, and there would not be good idea to change it. Anyway should be taken into account that "titlepage.xhtml" actually is not "title page". Its "cover"...

[kovidgoyal]

*If* you use titlepage it must point to the cover HTML. If you use something else feel free to use whatever. And covers in the calibre viewer are always at the start so there is no use for a cover item in go to

[quinta@ebf.cz]

Originally Posted by kovidgoyal

*If* you use titlepage ...

What exactly is meant by the word "titlepage" here?

[kovidgoyal]

Originally Posted by quinta@ebf.cz

What exactly is meant by the word "titlepage" here?

An entry in the guide of type="titlepage". THese are used internally by calibre to point to the html file that hosts the cover image.

[quinta@ebf.cz]

Still confused. Wasn't the word "titlepage" typing error? Didn't you mean

entry in the guide of type="cover"

?

  <guide>
    <reference type="cover" href="titlepage.xhtml" title="Cover"/>
  </guide>

[kovidgoyal]

cover refers to the actual IMAGE. titlepage refers to the HTML file that displays the image.

[thiago.eec]

Originally Posted by kovidgoyal

In the EPUB2 guide there must be only one guide entry of type cover that points to the actual cover image and one entry of type titlepage that points to the actual HTML file that displays that cover. Any other setup gets forced into this form by calibre's EPUB2 input processing. The viewer (and indeed all of calibre) require this for various kinds of further processing they do.

Originally Posted by kovidgoyal

cover refers to the actual IMAGE. titlepage refers to the HTML file that displays the image.

Hi, Kovid.

According to EPUB2 specification, the Guide section says that:

Each reference must have an href attribute referring to an OPS Content Document included in the manifest, and which may include a fragment identifier

Now, it also defines:

OPS CONTENT DOCUMENT:
An XHTML, DTBook, or Out-Of-Line XML Island that conforms to this specification that may legally appear in an OPF Package Document spine element.

An entry pointing directly to the image file doesn't seem to be valid. Also, the cover image file is already marked in the Metadata section:

<meta name="cover" content="cover_image_file_id"/>

The specification also defines the types "cover" and "title-page":

cover: the book cover(s), jacket information, etc.
title-page: page with possibly title, author, publisher, and other metadata

The "title-page" type is very well defined, and does not refer to the cover page. Now, the "cover" type might be a little misleading, as it does not use the word 'page', but the that is implied by the other definitions (OPS Content Document).

The thing is calibre treats "title-page"/"titlepage" as equivalent to "cover". This happens not only in the Guide section, but also when adding a cover page using the Editor, Polish or Conversion.

[quinta@ebf.cz]

I am browsing available (Calibre related) epub files. And actually cannot find any guide item "titlepage"... But Calibre surely have to be related into it somehow: simply because guide item "titlepage" do not generate "Go to..." menu item (unlike any other guide item type).

On the other hand, what I can see everywhere is guide item "cover", but pointing on html (not image)...:

  <guide>
    <reference type="cover" href="titlepage.xhtml" title="Cover"/>
  </guide>

Such markup is generated e.g. during conversion from docx, or using (right click) menu item "Mark filename.xhtml as cover page" in editor...

I would sware I before met information that guide item "cover" can be used to identify cover image file (besides of second method via manifest/meta[@name="cover"] etc.)... But now, I can't find such info again. Just examples of cover item pointing to html file...:
https://epubsecrets.com/where-do-you...e-opf-file.php
https://wiki.mobileread.com/wiki/Ebook_Covers

[DNSB]

Unless you want to try placing the cover image file in the guide's loi item (list of illustrations), there is no way to point a guide item to the cover image. cover points to the xhtml file that displays the cover image which is normally cover.xhtml and can also point to a jacket file, etc. but again all xhtml files. The title-page item points to an xhtml file with possibly title, author, publisher, etc. other metadata.

Of course, the guide is deprecated in ePub3 where you use the landmark items in the xhtml navigation documents.

[thiago.eec]

Originally Posted by DNSB

Unless you want to try placing the cover image file in the guide's loi item (list of illustrations), there is no way to point a guide item to the cover image. cover points to the xhtml file that displays the cover image which is normally cover.xhtml and can also point to a jacket file, etc. but again all xhtml files. The title-page item points to an xhtml file with possibly title, author, publisher, etc. other metadata.

Of course, the guide is deprecated in ePub3 where you use the landmark items in the xhtml navigation documents.

Well, that was basically my point.

[quinta@ebf.cz]

Term "titlepage" in Calibre manual:

Originally Posted by Editing ebooks -> The file browser

Many files have special meaning, in the book. These will typically have an icon next to their names, indicating the special meaning. For example, in the picture to the left, you can see that the files cover_image.jpg and titlepage.xhtml have the icon of a cover next to them, this indicates they are the book cover image and titlepage.

https://manual.calibre-ebook.com/edi...e-file-browser

Originally Posted by Editing ebooks -> Marking the cover

EPUB files has the concept of a titlepage. A title page is a HTML file that acts as the title page/cover for the book

https://manual.calibre-ebook.com/edi...king-the-cover