AsciiDoc for open source documentation

I discovered AsciiDoc in writing Learn Linux in a month of breakfasts. AsciiDoc is an incredibly comprehensive markup language for writing books, think Markdown, but with more options, such as sidebars, notes, and tables. AsciiDoc allows you to simply type, with simple syntax controlling formatting.

When I started writing my book, I was using Word stylesheets with LibreOffice. Manning, my editor, offered .odt versions for OpenOffice, but I was having trouble getting the styles to work. Ironically, I ended up using the Word .docx template, which worked best with LibreOffice. But the big problem was the images, which did not integrate well. I spent a good deal of my time formatting when I needed to write.

The comments were also difficult to analyze. Jim Whitehurst actually fixed LibreOffice to handle comments when he was writing his book, The open organization. After a few chapters of fighting through our model, my editor suggested that we switch to AsciiDoc and my life instantly became easier.

With LibreOffice, I had to insert an image, number it, label it, style it, and then hope everything fits, while with AsciiDoc I write something like this:

The .Mint Software Manager looks similar to the Ubuntu Software Center.

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

AsciiDoc transformed into PDF.

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

AsciiDoc syntax for a note.

Which turns it into this:

AsciiDoc syntax for a note rendered in a PDF.

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

AsciiDoc automatically generates a table of contents.

As AsciiDoc is text, you can write in any text editor, but I like to preview the code to make sure everything looks OK. There is a Gedit plugin, but using it would take a little effort, and I was running into delays. i decided to use Atom, the text editor created by GitHub. Atom has a plugin that makes AsciiDoc, which I tried out while working on a few chapters, but the preview was sometimes peculiar. Notes and sidebars would extend throughout the document. Moreover, I could not directly open documents in AsciiDoc format with. Instead, I had to open Atom and then open a document through the Atom open menu.

Atom was good, but boring enough that I decided to give it a try Supports, Adobe’s open source text editor. Parentheses make AsciiDoc much better, and although opening AsciiDoc files is still not transparent, it is better than Atom. I would have liked Brackets to have a running spell check instead of the ability to run a spell check when you’re done, but that previews what I need to see and gives me a running word count, so I am quite happy.

The parentheses text editor.

AsciiDoc rendered by Brackets.

The brackets and Atom are rendered in HTML, but the a2x The command, which is part of the AsciiDoc package, makes it easy to convert the .adoc file to PDF (although a bug causes the transformation to fail when image files have a dot in the name). The output looks like a professional-formatted book chapter.

AsciiDoc saved my life and I have the good fortune to work with an editor who uses it. I think AsciiDoc has apps for anyone who needs beautiful PDFs or is interested in self-publishing. Additionally, AsciiDoc has huge implications for open educational resources in that it allows someone to write a textbook without necessarily having to format it; they will easily have a PDF ready and can make the underlying AsciiDoc available to people who wish to modify the original.

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

Originally posted on Republished with permission.


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.

Sam D. Gomez