Writing documentation with AsciiDoc

No readers like this yet.
Typewriter keys

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.

User profile image.
Steven Ovadia writes LinuxRig.com, which features The Linux Setup, interviews with desktop Linux users. He is an academic librarian who writes about how users interact with information in an online context for assorted Library Science journals. He is the author of Learn Linux in a Month of Lunches. You can see all of his publications at steven.ovadia.org

6 Comments

AsciiDoc is great, but there's a faster, better documented, and more standard-compliant fork in the form of Asciidoctor (which is also what's used in the Live Previews in both Brackets and Atom). Asciidoc was a better, smarter version of Markdown and I think it is fair to say that Asciidoctor has that same relationship with Asciidoc. Happy documenting!

AsciiDoc is a cool piece of software. Have you tried AsciiDocFX? It's a GUI for AsciiDoc that works great.

I haven't seen that! I'll check it out!

I've been hearing things about asciidoc and markup/down for a few years and have done a bit of dabbling in that area. But each time I do so, having learned a bit of TeX/LaTeX, it seems to me a waste of time and effort. I know well from experience how steep is the learning curve of TeX/LaTeX, but it also becomes apparent when I fiddle with asciidoc or markup/down that what they are doing is attempting to reinvent the wheel. If your formatting needs are fairly simple, maybe it makes sense to use ascidoc markup/down, since it requires less initial effort to learn. But if you will ever have more complex formatting needs, you will find out the limitations of these new systems and may end up needing to make feature requests or do your own hacking to get them to fulfill your needs. TeX/LaTeX does absolutely every formatting trick you could ever imagine and produces stunning results. And there are frontends for it (e.g., Lyx), just like there are for markup/down. I remain convinced that, if I am to learn some formatting language in order to write my documents in plain text, I will be better served by investing more time and effort learning TeX/LaTeX.

The beauty of options is that everyone can choose what's right for them. I do very simple writing, without formulas or formatting, so Asciidoc is perfect. But you're right -- for more complex documents, other syntax, like LaTeX makes more sense.

In reply to by JM (not verified)

Thanks Steven For This Information.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.