Self-Publishing Workflow Update
Next up on the Master Space and Time With JavaScript status report is the workflow that takes my words and turns them into a PDF. And an HTML file. And an ePub. And don’t forget Kindle.
As you can imagine, this is something of a minefield, although there are a lot more tools available than there were three years ago when I did this the last time — here’s an overview of the process I used then. That article talks about the process that I used on Rails Test Prescriptions for as long as it was self-published.
Things have gotten more complicated. Most obviously, there are more devices and formats to support. The Kindle’s mobi format and ePub are different, and every ePub device has its own quirks. On the plus side, there are a lot more tools and libraries available than there were, though figuring out what they all do is a challenge in itself. Plus, a lot of the existing tools produce documents that are, well, kind of dull-looking, especially noticeable in the PDF versions. (If you are a self-publishing author, I don’t mean you, your stuff looks great. Those other people, though… can you believe them?)
Over the last few years, I’ve gotten addicted to being able to sort of see what the text looks like all laid out fancy and the like. So it was important to me to get at least the semblance of a tool chain in place before I started rewriting in earnest, not least because I needed to figure out what format the text was going to be.
Here’s what I’ve got. It starts with Markdown, because Markdown is pretty simple, I’ve been using it for years, and there are like a jillion editors that support it. Because I’m using Markdown, I’m also experimenting with writing the book in a more writerly editor like Byword, rather than a programmer editor like Sublime. In theory, this will make the book less… I don’t know, less programmerish, or less sublime? Dunno, but right now, I’m enjoying the change of scenery.
Then it starts to get complicated. There are multiple implementations of Markdown or Markdown-like libraries, and they all are subtly different. Right now, I’m using Multi-Markdown, since it has footnotes and cross-references, though there’s some possibility I’d switch at some point in the future. (I love footnotes, and I’d add one here, but I don’t think this blog engine uses a version of Markdown with footnotes.)
Markdown’s weakness is that it’s hard to specify custom styles or HTML classes. I’m working around that by running my Markdown text through a pre-processor where I can put in some custom directives. I can, for example, write:
!!!sidebar
:title A Sidebar
The sidebar content goes here
The pre-processor catches that, and converts the code into some specially styled HTML. (Yes, I’ll be open-sourcing the tool at some point in the future.)
I’ve also added something that I’ve wanted for a long time, namely the ability to insert code from a file at an arbitrary branch in a git repository, meaning that I can show code from multiple successive versions of the same file just by having them in different git branches. Meaning I can distribute the sample code in a git repository and have it not look too awkward.
I also have the ability to post-process Markdown’s HTML, which I think I’m eventually going to need to reconcile the rest of the tools.
Once I have the converted HTML, I need to generate e-book files. For PDF, I’m going back to using PrinceXML. There’s a lot of things I like about this tool. For one, it has a lot of the features that you would normally associate with actual books, like section numbering, footnotes, cross references, and page headers and footers. I think it produces nice-looking files, and its controllable with CSS, a technology that I (mostly) understand, so it’s easy and fun to tinker with.
I didn’t have any existing tools for ePub or Mobi, so I looked at somebody who I thought was creating pretty nice files, specifically Avdi Grimm, who did a pretty great job with the Objects on Rails ebooks. Avdi created his own tool called OrgPress, and for ePub and Mobi, he uses the command line interface to Calibre. Even though OrgPress uses Emacs Org Mode, Make, and Awk — three tools that, to put it mildly, I feel no particular pull to tinker in — I was able to take advantage of Avdi’s hard-fought war with Calibre to get a set of command line flags that basically work, though I’m going to have to tweak them a bit before they are salable. I’m also looking at Rpub, since it’s in Ruby.
One nice side effect of all these tools is that it’s easy for me to have an almost all iPad workflow — I turn on watchr on the laptop, write using Byword on the iPad, and when Dropbox syncs the file, the ebooks are all updated, and I can view them on the iPad via Dropbox. Not bad.
I know this isn’t done yet. For one thing, I suspect that Multimarkdown and PrinceXML are going to disagree on the format for a footnote, and I’m probably going to have to referee. Later note: it’s worse then that… Multimarkdown’s footnote format actually crashes the Mac Adobe and Nook ePub readers, though that seems to be a bug on their end, and it does work in iBooks.
I’m eventually going to need custom styles for each format — the sidebar CSS that looks great in PDF looks awful in iBooks. And I’ll need a cover.
And, you know, content.