Build your EPUBs with Eclipse...and read them too

By Torkild Ulvøy ResheimSenior Software Engineer

Itema as, Trondheim, Norway

The stort story

• EPUB is a open and free format for electronic books.

• Most non-Kindle devices support it.

• Increasingly popular for technical literature and user guides.

Traditional user guides

• Users are able to add bookmarks and notes.

• Big (heavy) tomes.

• But still portable.

• There is a natural reading order.

DataFlex 2.2 User’s Manual453 pages (1986)

Contemporary user guides• User are often allowed to add

bookmarks.

• Not portable. Sometimes embedded in the application.

• Plain HTML with a few extras.

• Sometimes only online.

• Context help (good).

• No natural reading order.

Eclipse SDK 1.0 HelpQuite a few pages (2001)

Your next user guide?• eBooks are increasingly

popular!

• Add bookmarks and notes.

• Very portable, carry hundreds or thousands of books on one device.

• Synchronisation between reading systems.

• Feels natural – there is a beginning and an end.

Pro Git813 pages (2011)

Benefits of EPUB• Open and free, based on

existing standards – CSS, XHTML, SVG...

• Out-of-line content.

• Allows DRM if required.

• A large number of existing reading systems

• EPUB3 allows JavaScript, HTML5, CSS3, MathML, Video and more.

• Rich Content (video and audio).

How to build an EPUB• Export from Pages, Adobe

Digital Editions, Indesign etc.

• ePubtools, various command line tools (requires Python).

• Online tools, Feedbooks and BookGlutton.

• Sigil the WYSIWYG EPUB editor.

• GUI apps Stanza and Calibre can convert from other formats.

New tooling for Eclipse• API for defining, reading and

writing EPUBs. Model represented using EMF.

• Apache Ant task for defining and writing EPUBs.

• UI for generating EPUBs from wiki markup format.

• Supports EPUB 2.0.1 (3.0 was released in October).

• Part of the Mylyn Docs project.

• Will be released 24. February (Mylyn 3.7/Indigo SR2)

Tooling features• Supports most EPUB 2.0.1

features. (Not DRM).

• Table of contents can be generated automatically.

• Referenced resources (images, out-of-line content) can be added automatically.

• Cover page (compatible with most readers) easily created.

• Validation of EPUB content and structure.

• Allows multiple publications within one EPUB.

• Does not do any data conversion.

The API (provisional)

• The data model (OCF, OPF, NCX, Dublin Core) is built on EMF.

• Utility methods for retrieving content by identifier, type, reference etc.

• Supports reading and writing of EPUBs.

public void createEPUB() throws Exception { EPUB epub = new EPUB(); OPSPublication oebps = new OPS2Publication(); oebps.addTitle(null, null, "My title"); oebps.addLanguage(null, "en"); oebps.addSubject(null, null, "My subject"); oebps.addItem(new File("My XHTML file")); epub.add(oebps); epub.pack(new File("My new EPUB.epub")); }

Demo: UI CommandQuickly generate EPUB from wiki markup

The Ant task• Structure resembles the OPF

structure.

• Supports filesets for adding non-spine resources.

• Items are analysed for content so that correct MIME types are used.

• Makes some tasks, such as adding a cover page much easier.

• Can be combined with existing documentation generation schemes.

Markup HTML

HTML

EPUB EclipseHelp

Demo: Ant taskSame source for Eclipse help and EPUB

In the pipeline...

• EPUB reader and library manager inside Eclipse.

• Support for EPUB 3.

Summary

• EPUB is an excellent format for user guides!

• Can be built in various (hard) ways. But new tooling makes it easier.

• Coming to Eclipse in February.

• Currently at https://github.com/turesheim/org.eclipse.mylyn.docs

• See http://eclipse.org/mylyn/docs/

Apropos...

• Thanks to Steffen Pingel and David Green of the Mylyn team for helping out!

• Any questions?