For manuals and guides, Wikis are an excellent way of organizing content. Yet, they often don't work as well for larger articles or books because individual content is spread across many pages and the reader has to click around. Additionally, when you want to read online content while in a place where you cannot get an Internet connection (like, reading on the plane), another mode of content delivery is needed.
Recently, I was quite thrilled to see Opensource.com offer a thorough and skillful way of How to create an eBook the open source way. But, I am not a big fan of Wysiwig editors and prefer markup languages like LaTeX, Markdown, AsciiDoc, or even Wiki-Markup. So, here I give you an alternative: preparing content for an eBook editing AsciiDoc documents. [You can also do this on the go, in an email editor on your mobile phone or tablet.]
AsciiDoc is a markup language that has been around for quite some time. The content is created in plain text and is readable in its source form. For instance:
= Chapter 1
The quick brown fox jumps over the source `code`
image::myCat.png[A lolcat]
* First list item
* Second list item
* Third list item
= Chapter 2
Lorem ipsum...
include::example.adoc[]
Note: This is a simple example; AsciiDoc formatting can be much more powerful.
Processing AsciiDoc
A tool chain written in Python is available to transform documents in target formats like .html, .pdf, and also ePub. To convert a document written in AsciiDoc, run the command like this:
asciidoc -d book <input.adoc>
And the load the resulting .html document in your browser.
Using asciidoctor instead of AsciiDoc for processing
Asciidoctor is a drop-in replacement for the AsciiDoc command. There are some small differences, but typically they do not make a difference. Asciidoctor is writen in Ruby and is notably faster. Get it via gem install asciidoctor, then use it similar to the above:
asciidoctor -d book <input.adoc>
Use autoload extensions in the browser for live preview
Manually switching between text editor, command line and browser to get a preview is still a bit cumbersome, so Dan Allen has described a way to automatically trigger a recreation of the output document when the file has changed. On top of that, a browser plugin can then detect the changed .html file and automatically reload it. If you keep browser window and editor next to each other you basically have wysiwyg editing.
Turning the document into ePub
Now that the document is finished we can render it in ePub format. For this we will use AsciiDoc and its tool chain, especially the a2x command.
a2x -fepub -d book <input.adoc>
First, this internally converts the document to a docbook, and from there, into the final ePub. This process is mostly transparent to the user except in cases where the original document violates some of the rules of ePub and a2x returns a cryptic error message. The documentation has an extended guide on how to use a2x to create ebooks with AsciiDoc.
3 Comments