Issues - EPUB

This page discusses some of issues we have encountered in EPUB documents and sketches out how AxAp might address them.


Although EPUB 3 Best Practices covers a lot of issues in EPUB design, we've run into others in the Examples we've examined. So far, most of these have to do with importing the documents; we expect to run into other categories (e.g., accessibility) as we proceed.

Directory Structure

Most of the server-side web frameworks we've used (e.g., Phoenix, Ruby on Rails, Sinatra) have strong conventions about directory structure. Some frameworks (e.g., Rails) use this organization to support convention over configuration. In any case, having a logical and nicely-arranged file tree is a great benefit to anyone working with the code.

We expected to find similar conventions being used in EPUB file trees, so we were surprised (and rather disappointed) not to find them in our examples. Although some example documents have nicely-organized file trees, others put most of the files into a single folder. Some, indeed, have file trees that they use only sporadically. Tsk.

In the longer term, it may be possible to encourage EPUB creators to follow minimal structuring guidelines. However, EPUB Open Container Format (OCF) 3.0.1 does not address this issue. In any case, existing documents will still need to be handled.

Given that nobody will be deep linking into EPUB documents, it should be possible to rework an imported EPUB file tree (e.g., create sub-directories, relocate files, rewrite references). However, it's not clear that the benefits would outweigh the risk of breaking something in the document.

Document Structure

EPUB has the capability to encode detailed document structure. For example, in a technical reference, the table of contents might contain entries for Parts, Chapters, and Sections. This information could be extremely useful to an EPUB reader in creating navigation support.

However, none of the examples we've examined make much use of this. All of them encode chapters, but none of them encode sections. In some cases, the Part level is treated as a one-page Chapter, discarding its structural implications.

Given that EPUB's XML files are mechanically generated, it should be fairly easy to recognize and restore the Part level. Reclaiming information on Sections, however, could be tricky. There is no guarantee that books from a given publisher will use the same idioms for indicating sections. So, we'll see ...

This wiki page is maintained by Rich Morin, an independent consultant specializing in software design, development, and documentation. Please feel free to email comments, inquiries, suggestions, etc!

Topic revision: r2 - 29 Oct 2016, RichMorin
This site is powered by Foswiki Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
Foswiki version v2.1.6, Release Foswiki-2.1.6, Plugin API version 2.4
Ideas, requests, problems regarding CFCL Wiki? Send us email