This Friday, on 11/11/11, the Austin Rackspace office is holding a Hackathon. The projects range from “fix the arcade game” to “install notification system to indicate availability of the men’s room” to my pet hack project, “create epub output for Rackspace and OpenStack manuals.”
Here’s a short introduction about making epubs from the FLOSS Manuals book, E-Book Enlightenment.
Of all the formats for e-books only EPUB combines small file sizes with the ability to do formatted text and illustrations. An EPUB is like a website contained in a Zip file, with a Table of Contents attached. It is also in one important way different from a website. A website is made with HTML (usually) but an EPUB is made with XHTML.
The difference is small but crucial. HTML is meant to be forgiving. If you make a web page you can leave out some tags, fail to close tags, or close tags in a different order than you opened them in. A web browser is supposed to forgive that, as much as possible. XHTML, on the other hand, is like HTML that is not forgiving. You can’t leave out a tag or put in a tag where the XHTML browser does not expect it. If an XHTML browser discovers an error in your page it can simply refuse to display it.
The end result is that an XHTML browser is easier to make than an HTML browser. A lot easier. It does put a burden on the e-book author to get his tags right, but in practice you’ll never create an XHTML file by hand.
With automation in mind, we’re going to use our existing toolchain to make the epub. Earlier this year, Robert Nagle, a tech writer in Houston, wrote up his findings about Docbook and epub. He writes for the Teleread website. What’s interesting to me is that he wrote up this blog post last year (11/7/10) about his findings while making epub from DocBook source and this past September said his next priority is moving his workflow to Oxygen + Ant + DocBook. David Cramer, our Doc Build Developer, has briefly tested the Maven-based toolchain by simply adding the goal generate-epub to a pom.xml file and building. That method did not copy over images. Then he tried building as part of the clouddocs plugin and received an error. We’ll start our debugging with the toolset, but we’ll also need debugging of our DocBook source as well.
Most of the “success” of the hack fest will be having fun and not sweating the small stuff. To me, we can call it done when we have epub examples for one OpenStack book and one Rackspace book that you can page through and read on a plane. Images should behave within reason, tables should be readable, and notes should be designated as such. Beyond those criteria, we’re exceeding expectations.
In case you’re curious about our tool chain for OpenStack docs, I have instructions on the OpenStack wiki. If you’re on a Mac or Linux machine, here are the quick steps for getting started with the tool chain for the openstack-manuals project:
1. First install the Apache Maven project.
With Macports already installed on a Mac, you can do this:
sudo port install maven2or on Ubuntu
sudo apt-get install maven2
2. Install Git by referring to Mac or Linux instructions.
3. Get (git it? Ha!) and then build the docs with these commands:
git clone https://github.com/openstack/compute-api.git
cd compute-api/openstack-compute-api-1.1
mvn clean generate-sources
You will see a /target directory containing HTML and PDF output. Perhaps after Friday, you’ll also see epub output, who knows? While Friday’s Hackathon is for Austin Rackers, I’m happy to share our experiences here. Here’s hoping the OpenStack community will benefit from our hacking.