Writing documentation with AsciiDoc

Image by:

April Killingsworth. Modified by Rikki Endsley. CC BY-SA 2.0.

I discovered AsciiDoc while writing Learn Linux in a Month of Lunches. AsciiDoc is a fantastically thorough markup language for writing books—think Markdown, but with more options, such as sidebars, notes, and tables. AsciiDoc lets you just type, with simple syntax controlling the formatting.

When I first started writing my book, I was using Word style sheets with LibreOffice. Manning, my publisher, offered .odt versions for OpenOffice, but I had trouble getting the styles to work. Ironically, I wound up using the Word .docx template, which worked best with LibreOffice. But the big problem was images, which wouldn't embed correctly. I was spending a decent chunk of time formatting when I needed to be writing.

Comments were also tough to parse. Jim Whitehurst actually got LibreOffice patched to handle comments when he was writing his book, The Open Organization. After a couple of chapters of fighting through our template, my editor suggested we switch to AsciiDoc and my life instantly became easier.

With LibreOffice, I had to insert an image, number it, caption it, style it, and then hope that everything held together, whereas with AsciiDoc, I write something like this:

.Mint's Software Manager has a similar look to the Ubuntu Software Center.

and AsciiDoc handles everything else for me, including numbering the images in the captions. This is how the above code renders:

^{AsciiDoc transformed into a PDF.}

A sidebar or note is as simple as something like this:

^{AsciiDoc syntax for a note.}

Which turns it into this:

^{AsciiDoc syntax for a note rendered into a PDF.}

AsciiDoc has formatting for heads and subheads and even automatically generates a table of contents based on them:

^{AsciiDoc generates a table of contents automatically.}

Because AsciiDoc is text, you can write in any text editor, but I like to preview the code to make sure everything looks OK. There's a Gedit plugin, but using it would require a little effort, and I was up against deadlines. I decided to use Atom, the GitHub-created text editor. Atom has a plugin that renders AsciiDoc, which I tried while working on a few chapters, but the preview was sometimes peculiar. Notes and sidebars would expand into the whole document. Also, I couldn't directly open AsciiDoc-formatted documents with it. Instead, I had to open Atom and then open a document via the Atom open menu.

Atom was fine, but annoying enough that I decided to try Brackets, the Adobe open source text editor. Brackets renders AsciiDoc much better, and although opening AsciiDoc files still isn't seamless, it's better than Atom. I wish Brackets had a running spellcheck instead of the ability to run a spellcheck when you're done, but it previews what I need to see and gives me a running word count, so I'm pretty happy.

^{The Brackets text editor.}

^{AsciiDoc rendered by Brackets.}

Brackets and Atom render in HTML, but the a2x command, which is part of the AsciiDoc package, makes converting the .adoc file to a PDF easy (although a bug causes the transformation to fail when image files have a period in the name). The output looks like a professionally formatted book chapter.

AsciiDoc has been a lifesaver for me, and I'm lucky to be working with a publisher who uses it. I think AsciiDoc has applications for anyone who needs nice-looking PDFs or who is interested in self-publishing. Also, AsciiDoc has tremendous implications for open education resources in that it allows someone to write a textbook without necessarily having to format it; they'll have a PDF ready easily, and can make the underlying AsciiDoc available to people who want to modify the original.

Markup languages like AsciiDoc are fantastic for people like me who don't want to deal with formatting. After we moved to AsciiDoc, we were able to use a private git repository to submit drafts back and forth. AsciiDoc also has the ability to comment-out text, which lets us share comments in the text. AsciiDoc saved me hours writing my book because it lets me focus on writing and not on styles and formatting. If you haven't tried AsciiDoc yet, give it a spin and let us know what you think in the comments.

Originally posted on MyLinuxRig.com. Reposted with permission.

Doc
Dish

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.