ePUB toolshttp://norman.walsh.name/2010/06/09/epubxpl13222010-06-09T06:24:09-04:00NormanWalsh2010Norman WalshWant to convert your favorite specification to ePUB? Here are the tools
that I've been using. [Update: 10 June 2010] Much revised.Publishing W3C specifications
as ePUB files looks to be a popular essay.
Before I'm inundated with requests, I figure I
better publish my tools so you can do the conversions yourself. They work for me,
YMMV, of course.As things stand right now, if the input spec is W3C
pubrules
compliant, stored in a single file, and uses the classes “div1”,
“div2”, “div3”, etc. for the various section levels in the spec, I
think you'll get a nice, neat ePUB file. The more your input diverges from
that structure, the harder it will be to make things work.There are four parts:spec2epub.xplThis is the main
XProc
pipeline. Its job is to download the spec and shepherd
everything along. It fiddles a bit with class attributes to massage XProc and a few
other specs into the right general structure.
getfiles.plOne of the things that we need to do is download all
the ancillary documents (images, CSS stylesheets, etc.). The pipeline
can extract the URIs, but since some of them aren't XML, it can't
download them. This script does that part.(Well, actually, it can download them just fine,
what it can't do is write them to disk in their original, binary form.
I have an extension to p:store which does this, but I
didn't want to use any extensions in this pipeline.)
[Update: 10 June 2010] This script now parses CSS and massages
the CSS files to look for embedded url()’s.spec2epub.xslChunking the spec and creating the ePUB metadata
files is handled by an XSLT stylesheet.For W3C specifications, we can exactly and
accurately collect all the metadata (Thank you,
IanJacobs and pubrules!). For the
OASIS specs, I had to hand edit some of the metadata.[Update: 10 June 2010] I rewrote this stylesheet substantially. It works
a lot harder to preserve the relative structure of the spec so that it can
construct relative links to stylesheets, images, and the like. It also does
a whole bunch of (ad hoc!) markup cleanup.webkit2pngThe last thing I do is generate a cover image. I do
this with a platform-dependent, Mac-only script that converts an HTML
page into a PNG. You're on your own for this part, I can't help you.
(If someone knows of a portable way to do this, I'd love to hear about
it.)
Download the files and run the pipeline with your
favorite XProc processor. The pipeline has no inputs and no outputs,
only options:The URI of the spec you want to convert. For W3C
specs where the URI is often just a pathname, make sure you include
the trailing slash or internal URIs won't get resolved correctly.
The directory where you want the ePUB structure written.
By default, specs are physically chunked at
second-level sections. For some specs, this doesn't seem quite deep
enough. You can explicitly set the depth to 1, 2, or 3. If you want to
go deeper than 3, you'll have to edit f:chunk in
spec2epub.xsl.For example:$ calabash spec2epub.xpl base=/tmp/xproc/ href=http://www.w3.org/TR/xproc/ chunkdepth=3Good luck! If you make improvements, please share them!