EPUB sucks
S. Gilles
2017-07-01
I have a large pile of epub files sitting around. After encountering
a few rendering glitches on my physical reader (as well as some
typos), I decided to recompile a few of them to perform some minor
edits, and maybe add some covers to the Project Gutenberg ones while
I was at it. I thought that since EPUB was built from well-known,
widely used technology like ZIP and XHTML, it would proabably be
usable.
As it turns out, EPUB is a terrible, terrible format. In no particular
order:
o Conceptually, EPUB is “just a bunch of (X)HTML files in a ZIP,
with some metadata”. But there are absurdly strict restrictions
on that ZIP. The “mimetype” file has to come first in the ordering,
it must not be compressed, and it must have no metadata. For the
rest of the file, directory entries must be supressed.
This is so that libmagic(5) style detection works easier, and
is how we get the magic
zip -X0 foo.epub mimetype
zip -Xur9D foo.epub *
sequence of commands. However, the structure of ZIP files already
provides a trivial solution: arbitrary archive comments can be
added at a predicatable location (the end) to a ZIP file. These
have been abused to create hosts of polyglot files already. It's
equally as easy to check for an uncompressed
mimetypeapplication/epub+zip
sequence as the beginning of the file as it is to ensure that
the file ends with the bytes
^@this_is_an_epub_file_okay?
so the EPUB spec could simply have mandated a particular comment
and stayed out of micromanaging ZIP arguments. The EPUB choice
sucks because it makes recreating the epub a nightmare: generic
tools like archivemount can't be trusted to faithfully preserve
an EPUB file while operating on it.
o Absurd redundancy of structure. The file I'm looking at now has:
- a META-INF/container.xml file, which contains a hierarchy of
files, but the hierarchy is trivial and just points to
content.opf.
- inside content.opf, there is a <manifest> object, containing
a list of all content-bearing files in the EPUB
- below that, there is a <spine toc="ncx"> object which is just
a list of ids previously established by the manifest.
- right below that is a <guide> object, which doesn't use the
ids from manifest.
- a toc.ncx file with exactly one entry,
- and that entry is a link to a table of contents created in
HTML as part of the book, bypassing the whole point of toc.ncx.
The <manifest> lists all objects in the file, which is rather
useless even in a streaming situation. The <spine> designates
an ordering of a subset of the <manifest>, and the <guide> applies
special types to elements of <manifest>. These could easily be
compressed into one object. That object could be the toc.ncx
file.
EPUB 3 makes this even worse, I hear.
o Poorly constructed website. Searching for epub specifications
brings up <
http://www.idpf.org/epub/20/spec/OPF_2.0_latest.htm>,
but since EPUB 3 exists, I tried changing that URL to
<
http://www.idpf.org/epub/30/spec/OPF_3.0_latest.htm>. But that
URL gives a 301, pointing to itself for an endless loop. I'm not
even sure how someone managed to do that. (The actual specification
for 3.0.1 is at
<
http://www.idpf.org/epub/301/spec/epub-publications.html>.)
o Investigating that specification yields the following example
for the title of LOTR. Instead of something like
<metadata
title-main="The Fellowship of the Ring"
collection="The Lord of the Rings"
title-expanded="THE LORD OF THE RINGS, Part One: The Fellowship of the Ring"
/>
The EPUB spec has opted for the following:
<metadata xmlns:dc="
http://purl.org/dc/elements/1.1/">
<dc:title id="t1">The Fellowship of the Ring</dc:title>
<meta refines="#t1" property="title-type">main</meta>
<dc:title id="t2">The Lord of the Rings</dc:title>
<meta refines="#t2" property="title-type">collection</meta>
<dc:title id="t3">THE LORD OF THE RINGS, Part One: The Fellowship of the Ring</dc:title>
<meta refines="#t3" property="title-type">expanded</meta>
…
</metadata>
Those jury-rigged id= and refines= tags are nothing short of
insane genius: it takes skill to start with XML and build a
specification in which it is possible to write a property that
modifies the wrong object, or no object at all.
o Specifying a cover for an music album, to a music player, is
pretty simple. You put a file called cover.jpg in the directory,
or perhaps folder.jpg if you belong to that camp.
For an EPUB document, the fastest way I can figure out is the
following: Put cover.jpg in the root, add it to the <manifest>
of content.opf, add something like
<meta name="cover" content="cover" />
to the <metadata> of content.opf, making sure that the content
tag is the same as the id from the manifest. When that doesn't
work, make a cover.xhtml file with appropriate css to reference
cover.jpg as an <img> element (make sure to see whether ‘width=100%’
or ‘height=100%’ is appropriate, since there's no way to easily
scale-to-fit preserving aspect-ratios in lowest-common-denominator
HTML+CSS), add THAT to the manifest, then add it to the <guide>
element of content.opf via something like
<reference href="cover.xhtml" type="cover" title="Cover" />
Just to save you some time, you can't put
<reference href="cover.jpg" type="cover" title="Cover" />
in the guide directly: each entry must be an “OPS Content
Document”, which is their name for “An XHTML document that
conforms to our DTD”.
This format was not meant for humans to work with, it was meant for
companies to charge other companies to churn out.
