Enhancement request - generating scalable epub covers

[cjns1989]

When using pandoc to create an epub document, the user can specify a cover image via the "--epub-cover-image=" flag:

pandoc -o ../epub/book.epub title.txt ch*.md --epub-cover-image=../images/cover.png

Currently the generated html in "cover.xhtml" looks something like this:

<div id="cover-image">
<img src="../media/cover.png" alt="cover image" />
</div>

It would be better if pandoc wrapped the image in a tag to make the image scale automatically to the dimensions in pixels (aka. resolution) of the e-reader's display… something like this:

<div id="cover-image">
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="100%" height="100%" viewBox="0 0 900 1200" preserveAspectRatio="none">
<image width="900" height="1200" xlink:href="../media/cover.png"/>
</svg>
</div>

This appears to be strategy adopted by such epub-specific programs such as Sigil and Calibre when you add a cover image manually. My assumption here is that since their respective developers are bound to receive feedback from their users and this solution was implemented quite a few years ago… there is a pretty good change that it works for a majority of users and does not have any unfortunate side-effects.

In the above example my cover image is 900 pixels x 1200 pixels hight (4:3 ratio).

It may be necessary that pandoc call something like the imagemagick library or equivalent to determine the aspect ratio and dimensions of the image specified by the user (similar to the imagemagick "identify" command) in order to generate a valid

Lastly… it is necessary to add "properties=svg" to the content.opf manifest's description of the "cover.xhtml" item. Otherwise, the epubcheck validation tool will return an error.

<item id="cover_xhtml" href="text/cover.xhtml" media-type="application/xhtml+xml" properties="svg" />

[mb21]

This appears to be strategy adopted by such epub-specific programs such as Sigil and Calibre

Interesting... I wonder why they don't use some CSS, considering that not that many epub readers supports svgs... so they wouldn't render any image. But I agree with you that there was probably a reason for sigil/calibre to do it this way, would be good to figure that out.

btw. the relevant code is here.

[jgm]

We have code in pandoc to determine image dimensions.

Is this svg wrapper strategy portable to all ereaders? Does this require epub3?

[cjns1989]

not that many epub readers supports svgs

I suspect all depends on what "supports svgs" means. The <svg> tag or .svg images that need to be rasterized in order to be displayed?

there was probably a reason for sigil/calibre to do it this way

I see it from a different angle… which may be more relevant to this issue. The sigil/calibre developers have been using this technique for some time. Since they continue using it I would imagine it highly unlikely that it breaks anything that matters. They would have had users yelling at them and probably abandoned it (?).

The alternative would be to acquire every e-reader model, … past, present… and future and test…?

Since the <svg> tag (see above) is just plain html it should work regardless of your using an e-reader (or android app) + your html packaged as an epub… or a web browser once you've unzipped the container file.

As to .svg files, I did a 19th century song book a couple of years ago and I used lilypond to create the scores. Lilypond can create output either in pdf form or as svg's. I'd have to check but I'm pretty sure (almost certain) that when I tried to embed the svg files in my epub all I got on my antiquated Kobo glo' that I acquired maybe 5 years ago (but with up-to-date kobo software) all I ever got was was blank pages.

Is this svg wrapper strategy portable to all ereaders?

Probably. Please refer to my guesswork above.

Does this require epub3?

Same as the svg wrapper strategy. Since it's plain ole' html to begin with and not epub-related… I would imagine epub2 or epub3 support is irrelevant. The difference between the two being essentially in the precious little in epub2/3 that is not html+css.

Obviously, is you feel this might be detrimental to pandoc you may want to double-check with people who do know a thing or two about this rather than rely on Joe User's gut-feeling and experimenting… or ask the IDPF… who appear to have "ceased operations", effective January 30, 2017 IDPF… ;-)

Oh, if you decided to go ahead with the minor change that I suggest… you may want to amend the man page (*nix systems?) that currently specifies that,

It is recommended that the image be less than 1000px in width and height.

Thanks…

[jgm]

The svg tag is part of HTML5, but not HTML4. Since epub2 is based on XHTML4, I wondered whether it would require epub3. Does anyone have any experience in this?

Oh, if you decided to go ahead with the minor change that I suggest… you may want to amend the man page (*nix systems?) that currently specifies that,

It is recommended that the image be less than 1000px in width and height.

Agreed.

[mb21]

Yes, apparently that's an epub3-only solution: https://ebooks.stackexchange.com/a/8254/8342

@cjns1989 so does it show the svg cover image on your Kobo Glo?

[jgm]

I see no problem with implementing this (for epub3 output only).

[cjns1989]

@cjns1989 so does it show the svg cover image on your Kobo Glo?

? … glad to be of any assistance… but what am I supposed to upload to my e-reader?

Yes, apparently that's an epub3-only solution:

from a shell prompt run:

epubcheck -h

and take a look at "Modes and versions supported".

Perhaps the person you want to talk to about this is the author of this utility?

To clarify… I don't think it's a matter of epub2 vs. epub3. I have done mostly epub's version 2 (that is with the toc.ncx file and a few differences in the content.opf file) and they all use xhtml 2.0… hence html5.

They also all use the svg wrapper technique for the cover image and when I run epubcheck it automatically detects a version 2 epub and uses EPUB version 2.0.1 rules… and returns no errors.

With e-readers (or the software that they ship to be exact) it's not a matter what the IDPF said regarding epub2 or epub3 but rather a matter of what html/css individual features are supported (or unsupported) by the application that runs on the e-reader.

I'd say it's likely that some e-reader models that are still in use even though they stopped making them 5-10… years ago or more… running software that has not been updated in a decade will not support some features of html5 that some other more current e-reader software may support (or not support…) and that they may very well bork when the toc.ncx file is missing. (I've seen some annoying lockups of my e-reader when the software disapproves of one particular feature of a given epub).

I see no problem with implementing this (for epub3 output only).

Joe User here thinks it makes sense… not because of epub2 vs. epub3 etc… but rather because since all e-readers sold over the last few years support a minimal subset of epub3 (the internal structure of the zip archive basically and a sensible subset of html/css capabilities) … epub3 output is what everyone should go for in 2019… and then you could keep pandoc's epub2 generation capability as some sort of implicit escape hatch for legacy stuff?

This said… I'll go back to minding my own business… :-)

Thank you for all the good work… please let me know if you need anything else my end…

[jgm]

To clarify… I don't think it's a matter of epub2 vs. epub3. I have done mostly epub's version 2 (that is with the toc.ncx file and a few differences in the content.opf file) and they all use xhtml 2.0… hence html5.

Well, the EPUB v2 spec specifies XHTML 1.1.

I think the safest course is to adjust epub3 output but maybe keep epub2 output the same.

One thing we might be able to do is make this more easily configurable in the template, instead of generating content in the writer itself. (The writer could just pass in the cover image filename, and the template would do the rest.)

[jgm]

I implemented this in both epub3 and epub2, since epubcheck seemed to be okay with both.

Note that the hardcoded image code is gone. Now the template is fully configurable; you can even go back to the old behavior if you like it better.

[jgm]

Argh! Got the wrong issue number again in the commit message. Closed by 5f495eaace3ce4cf15a89b6b3cfb54df6d1658d8