Electronic books are everywhere these days and new reading devices seem to be announced monthly. With a few exceptions (e.g. Amazon’s Kindle) - all of these can display books formatted as EPUB. There are also a few decent desktop applications capable of displaying EPUBs. With this abundance of reading systems it could be wise to take advantage of the situation and publish for instance user guides and manuals in this format. This way users can read them at home, at the desktop and everywhere in between. Most reading systems also supports annotating and bookmarking with synchronization between devices.

There are several ways of assembling EPUBs: You can write a document in Apple’s Pages and directly export to EPUB. You can for example write it in Microsoft’s Word and convert it to EPUB using EPUBGen, in DocBook and convert it using docbook2epub or even manually assembling the publication using various command line tools. The popular Calibre tool can also be used to create a number of formats. All these methods have their merits but few can be easily used to assemble publications during a continuous build and none can be used without adding a few extra dependencies such as Ruby or Python.

Hence the primary goal of the EPUB support in Mylyn Docs is to create a mechanism that allows consistent building of EPUB files adhering to all relevant standards, using ANT tasks, while introducing as few dependencies as possible (only Java and parts of Eclipse). The secondary goal is to create an API that can be used for manipulating EPUBs. For instance loading an existing publication and altering it’s contents or metadata.

The EPUB support in Eclipse is built around an EMF data model describing the publication along with various mechanisms to manipulate this structure and assemble a EPUB file. The model is expressed in Ecore, representing the Open Packaging Format (OPF), a subset of Dublin Core and the Navigation Control File (NCX). All required parts of a properly assembled EPUB file following the 2.0.1 revision of the standard.

The mechanisms mentioned is an API for handling the EPUB and a Ant task that can be used during building. The following code shows the minimum Ant script required to generate a publication.

<epub file="My Book.epub">
  <title>My Book</title>
  <subject>My Book's subject</subject>
  <item file="my_chapter.xhtml" />

Some of the fields required by will be automatically created and added to the publication when not specified in the Ant script. The table of contents will for instance be automatically created, the language set to en for “English” and an identifier (based on UUID) will be generated. Details can be found in the chapter describing the epub Ant task.

Learning more

If you would like to learn more about building EPUBs you may want to take a look at following resources: