Skip to main content
September 23, 2010

How to succeed in ePub building with really trying

The ePub spec is long and very formal, but the format itself is fairly straightforward. And while building an ePub by hand is not complicated in itself, reworking content from other formats can be tricky. Beyond that, getting an ePub into Apple’s iBookstore presents its own hurdles, as iTunes Producer and the iBookstore are nothing if not vague as to what might be stalling your upload, even after validation. Having been through this process with our Technical Writing 101 ePub, I’ve got a few tips that should help save time and unnecessary headaches.

Tech Writing 101 in the iBookstore
Technical Writing 101 in the iBookstore

Basically, an ePub is a series of XHTML files in a ZIP container, with a mimetype, a reader instruction file, a TOC file, and a manifest. To create an ePub, you need to produce or process your content, build the container, and pull everything together. If you’re reworking content from FrameMaker or Word (or whatever), you’ll need to export it as (X)HTML and process it from there as plainly as possible.

When working up your content, bear in mind that there are some specifics you need to adhere to, namely:

  • Content files must be in valid XHTML.
  • Namespaces must be properly declared.
  • Dates must be properly formatted.
  • Content files must contain only UTF-8 or UTF-16 characters, with no HTML entities or spaces in the filenames.

Overall, a uniform style with a minimum of class declarations and unique formats works best, as no two ePub readers seem to render content in exactly the same way. Embedded fonts are fine, so long as the stylesheet knows where to look for them and the license information is included. I should say that you could use a program like Calibre, eCub, or Sigil (there are a zillion of them), but in lieu of that, I would recommend using a text editor or a decent HTML editor to do your brute work. Some of the tools will lace your files throughout with junk code and chop them up in ways that baffle the mind, ultimately adding hours to the process.

When building your container, simpler is again better. For our Technical Writing 101 ePub, the file structure is as follows:

  • /ePub (this is the ZIP container with the .epub extension)
    • mimetype (tells the reader software what’s in the package)
    • /META-INF
      • container.xml (tells the reader where to find the content within the ePub)
    • /OEBPS (holds the book’s contents)
      • toc.ncx (table of contents file, also specifies reading order)
      • content.opf (the manifest, listing every file in the ePub)
      • XHTML and CSS files (content and stylesheet)
      • /fonts
      • /images

(For a more comprehensive explanation of what these files look like and do, see Jedisaber’s excellent tutorial.)

To build the container, use a standard zip program (we used the zip utility built into Windows) to create a new folder. It’s important that you create the folder first, and then add your content. If you compress the mimetype, the ePub won’t work at all. After you’ve roped in your content, change the file extension from .zip to .epub, and your book is ready for validation.

There are several validation tools out there; the most popular is the ePubcheck command line utility (hosted on Google Code). It’s thorough, and it’s what Apple recommends (Apple being the strictest ePub vendor). You can also validate on the web at Threepress if you’d like, though both methods validate against the same schema.

As a forewarning, know that it’s entirely possible to create a valid ePub that fails to make it into the iBookstore. If this happens, review your upload package, checking for files not listed in the manifest, or anything else not in keeping with the requirements above. Apple rejected our first ePub upload, not for any of these reasons, but because we had included in our package a cover image that lacked the proper dimensions of 600 px on one side (that requirement isn’t as well documented as you might think). If you’re sure you’re in compliance, write to the folks at the iBookstore–they’ll respond.

ePubs are an excellent alternative to PDFs, as they handle graphics and text piecemeal by the file (like web pages), rendering more quickly on the screen, etc. I’m sure that as the ePub standard continues to gain market share someone will make an amazingly great ePub tool, but until then, creating by hand seems to be the shortest row to hoe.