Epub Notes

There are several Wiki pages relating to epubs. Some have not been updated for many years; some relate to creation of custom epubs; some have suggestions for ways to tackle specific issues. This page is intended to be a place to record handy things that you discover relating to epubs.

Since one issue regarding epub-related pages is whether the advice is still relevant, given how the handling of epubs has changed over the last 10 years, please keep the following points up-to-date, editing or deleting them if they become obsolete. Also, please edit the date below:

Notes for PPers

Here are things people have discovered that it might be handy to know if you are a regular PPer/PPVer. These are aimed at people whose books are converted to epub by ebookmaker, and give hints or tips as to things which work well or not so well.

<q> tags for smart quotes are not currently parsed by all readers

[reported May, 2020]

Another "may be a problem to some ereader out there" issue recently came up. The short version: I use <q> and </q> for quotations and build an HTML5 file and pass it to the Nu validator. The HTML looks great in my browser and the validator lets me feel comfortable that I have all the quotes right. In a recent fiction book just produced, there were 4,114 quotation marks, including 52 left single-quoted phrases.

Once I have it right as validated by the Nu (HTML5-only) validator, I regenerate the book as XHTML 1.0 Strict for PG. It looks great in my browser. It looks great in my computers ebook reader app. It looks great everywhere--almost. I grab my wife's Samsung tablet and download the epub to see how it looks. All of the quote marks disappear from the book. It's not that they revert to straight quotes. They simply disappear. Who knew? I didn't.

local testing and epub validation

[reported May, 2020]

There is an online ebookmaker, which should be used to verify the ePub you get is what you intended. There are lots of ways that might not happen. For some PPers, installing a local copy of ebookmaker and a local copy of the ePub validator is worthwhile. Then a single line command can generate the epub and another single line can validate it.

Ebookmaker install. There are instructions in the README.txt to install it locally. I do not use those instructions. Instead I do this:

 $ git clone https://github.com/gutenbergtools/ebookmaker
 $ cd ebookmaker
 $ python3 setup.py build
 $ sudo python3 setup.py install
 $ which ebookmaker
   /usr/local/bin/ebookmaker
 $ ebookmaker --version
 EbookMaker 0.8.10

usage: ebookmaker --make=epub.images -max-depth 0 --ebook 10001 --title "Little Miss Grouch" --author "Dudley Doright" grouch.html

Validator install.

 visit https://github.com/w3c/epubcheck/releases/tag/v4.2.2
 from Assets, download epubcheck-4.2.2.zip
 unpack to folder epubcheck-4.2.2
 move that folder to ~/bin/epubcheck

usage: java -jar ~/bin/epubcheck/epubcheck.jar 10001-images-epub.epub

Ways to confuse/break ebookmaker

[reported May, 2020]

1. Start with a div carrying the magic class of "section" or "chapter" 2. Have almost any <hx> before the first h1 of the user's text, with examples from posted books and workarounds.

Notes for others

Here are things people have discovered that it might be handy to know if you create tools or are interested in the limits of what can be done in epubs.

Directory names matter

[reported May, 2020]

I had a book project in a folder named "Virginias Adventure Club".

ebookmaker --make=epub.images --ebook 10001 --title "Virginia’s Adventure Club" --author "Grace May North" advclub.htm
java -jar ~/bin/epubcheck/epubcheck.jar 10001-images-epub.epub
Validating using EPUB version 2.0.1 rules.
WARNING(PKG-010): 10001-images-epub.epub/10001/@home@rfrank@books@IN_PP@Virginias Adventure Club@advclub-0.htm.html(-1,-1):
Filename contains spaces, therefore URI escaping is necessary. Consider removing spaces from filename.
 ... many more of these warnings ...
Check finished with warnings
Messages: 0 fatals / 0 errors / 43 warnings / 0 infos

Yeah, just a warning. But I really don't know if the unescaped path in the epub that ebookmaker generates might be a problem to some ereader out there. Seems like escaping that would be something EBM would do.

I'd like to have no warnings. It's easy to get that: simply do not have spaces in the enclosing folder's path name. But I didn't know that. Maybe it's in the DP documentation somewhere. Like I said, I'm guessing I'm finding out things more experienced PPers already know about epubs. Change the enclosing folder to "Virginias_Adventure_Club" and epubcheck is happy:

ebookmaker --make=epub.images --ebook 10001 --title "Virginia’s Adventure Club" --author "Grace May North" advclub.htm
java -jar ~/bin/epubcheck/epubcheck.jar 10001-images-epub.epub
Validating using EPUB version 2.0.1 rules.
No errors or warnings detected.
Messages: 0 fatals / 0 errors / 0 warnings / 0 infos