h1. Introduction

p. 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.

p. 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":http://code.google.com/p/epub-tools/, in DocBook and convert it using "docbook2epub":http://code.google.com/p/epub-tools/ or even manually assembling the publication using various command line tools. The popular "Calibre":http://calibre-ebook.com/ 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. 

p. 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. 

p. 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":http://wiki.eclipse.org/Ecore, representing the "Open Packaging Format (OPF)":http://idpf.org/epub/20/spec/OPF_2.0.1_draft.htm, 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.

p. 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.

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

p. 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":epub-ant-task.html Ant task.

h2. Features

* General support for the EPUB 2.0.1 specification.
* Wizard for converting a single markup file to an EPUB.
* Ant task for assembling an EPUB.
* API for creating, reading, writing and manipulating an EPUB.
* Content validation.

h3. Unsupported EPUB features

* Digital Rights Management (DRM). Including signing, encryption and font obfuscation.
* **Tours** element in the OPF. Was deprecated in version 2.0.1 and removed in version 3.0 of the EPUB specification.
* **Out-of-line XML islands** in the OPF. Was removed in version 3.0 of the specification.

h2. Learning more

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

* Elizabeth Castro: EPUB Straight to the Point - ISBN: 9780132366984
* International Digital Publishing Forum: "EPUB":http://idpf.org/epub
* Liza Daly: "Build a digital book with EPUB":http://www.ibm.com/developerworks/xml/tutorials/x-epubtut/index.html
* Harrison Ainsworth: "Epub Format Construction Guide":http://www.hxa.name/articles/content/epub-guide_hxa7241_2007.html

