Creating A Personal E-Book
Ever since I bought my first electronic book reader I've wanted to create my own e-book1. Not because I want to self-publish a book, because I want move the notes and cheat-sheets I have on paper to something I can reference on my e-book reader.
My first experiment was with PDFs. They're easy to create but the results are underwhelming. While there are exceptions, PDFs generally don't display well on e-book readers, especially technical documents. It was clear that I needed to produce an ePub document.
I've noodled around with different options. Last week I decided to give it a concerted effort.
My criteria was:
- Ability to have source chapters or sections in individual files
- Ability to have the files readable on a website as well in ePub format
- Easy to update the ePub document (i.e., as simple a workflow as possible)
- Have the source formatting as straight forward as possible
The formatting issue meant that working in a word processor such as Open Office or MS Word was not an option. EPub is very structured document. Word processors are excellent at achieving a good visual look but create the crappiest structured document I have ever seen. If you don't believe me, see how much space the Smash Words Style Guide devotes to telling authors how to make MS Word behave. I didn't want to deal with cleaning up the output.
Knowing that many people had written books using text files and Github, I started researching options in that direction. There are a lot of examples out there!
My research wasn't exhaustive or systematic. I basically stopped at the first option that appeared to meet my criteria: the technique used by Addy Osmani for his book Developing Backbone.js Applications. It's a very software developer approach involving command line tools.
The build process:
- The Make utility is used build the different documents from source files written in markdown2
- Make uses the awk command to concatenates individual text files into a master document
- A utility named pandoc3 converts the master document into a number of different formats, including ePub and HTML.
This technique meets all of the criteria. Having seen the technical layouts in Osmani's book I have some assurance this technique can handle technical formatting requirements. It has the added advantage of being hostable on Github, which displays the markdown files visually formatted, not as plain text. And although I hadn't considered writing in the open and allowing collaboration, I have a some technical writing project ideas that might be fun to do this way.
I've only just started converting my notes, so no experiences to talk about so far.
In the spirit of open source I've uploaded the template to Github as ss-edoc-template: Single Source Document Publishing Example Template. It is entirely derived from Osmani's example and I encourage you to take a look at Developing Backbone.js Applications to see the breadth of formatting options.
If you have any experiences or comments you'd like to share, please leave a comment!
[1] The shortened form of electronic book is variously e-book, ebook, or eBook. E-book seems to be the preferred spelling from the official usage bodies. Given the evolution of e-mail to email, I expect the same trajectory with e-book. For now, though, I'll go with the official usage.
[2] Markdown is a plain-text formatting convention designed to both human readable and easy to convert to a formatted document, usually HTML. There are a number of different standards. For more information: http://en.wikipedia.org/wiki/Markdown
[3] Pandoc is a utility program the converts between different document formats. For more information: http://johnmacfarlane.net/pandoc/
