Most of the projects we embark on need documenting, either for writing a specification, or detailing data formats, etc. Some people like to use Open Office which is probably fine for the original developer, but when multiple developers need to work on the text the ODT format doesn’t play nice – we cannot easily diff the document to quickly see what patches achieve. Text XML formats are also horrible as they create terrible diff’s which are very hard to read. We need a format that can be put under version control and is simple to use (we don’t want to have to learn a complete new language to be able to generate documents!)
AsciiDoc also has an advantage over most systems in that it is able to output a massive amount of formats. It’s extensible and so can create even more formats with additional plugins.
The following describes using AsciiDoc for valvers project documentation.
Get the toolchain
Getting AsciiDoc on Windows means you’ll need python installed. So go and grab python and then go and grab AsciiDoc distribution zip and unzip to somewhere on your hard drive. Put the path into your PATH environment variable if you want to be able to run it from anywhere.
If you haven’t altered windows to make python files executable (which is normal, not many people make python files executable in Windows) then you can quickly make a batch file to enable easier instantiation of asciidoc, call it asciidoc.bat: You can grab a copy here.
python asciidoc.py %*
If you want to be able to parse included source code in documentation then you’ll also need to get hold of GNU Src highlite. You just need this to be in your PATH for AsciiDoc to be able to format source code. If it is not in your path you’ll receive warnings from AsciiDoc warning that there is no output from the source code filter.
NOTE FOR GNUWIN32 SOURCE-HIGHLIGHT – There is a bug which prevents it from running correctly as it cannot find any language filters. In order to fix this problem, unzip the application and make sure the /bin directory is in your PATH environment variable. Then, rename source-highlight.exe to source-highlight-exe.exe and save the following batch file into the bin folder:
source-highlight-exe –data-dir %~dp0\..\share\source-highlight %*[/code]
Don’t forget to save it as source-highlight.bat! You can grab a copy here.
Now from the command line (outside of that directory) you should be able to execute:
and get an output similar to:
[code]Supported languages (file extensions)
and associated language definition files
C = cpp.lang
H = cpp.lang
bison = bison.lang
c = cpp.lang
Just use your package manager to get asciidoc, usually something like:
[code]sudo apt-get install asciidoc[/code]
It depends on your package manager and your distribution
Test the toolchain
Testing is really simple, we’ll need an example asciidoc formatted document and the ability to run asciidoc. Download the example article template which is a direct copy of the asiidoc example. We can compile to a standalone html file using the following command:
[code]asciidoc -b html5 -a data-uri -a icons -a toc2 -a theme=flask article.txt[/code]
This should generate a standalone html file (where images are embedded in the source code instead of being required to be linked to – this generates really tidy html documentation pages.
NOTE: In order for data-uri to succeed it will follow the local relative links to data files (like images) in the directory you are currently working in. So to get the amonition paragraphs to work correctly you’ll need to copy the images folder from the ASCIIdoc installation to your local working directory. Or of-course, you can use your own icon files instead!
You’re going to get bored of typing that on the command line! So generate another batch file, similar to the following:
python %PATH_ASCII%\asciidoc.py -b html5 -a data-uri -a icons -a toc2 -a theme-flask %*[/code]
and save it as asciidoc-html5 or something shorter if you’d prefer, and then you can quickly generate great html5 documentation without having to remember ALL the options!
Basic AsciiDoc Formatting
The first thing we should note is that the official asciidoc user guide is very comprehensive!
Now that we can build an example, we can start learning the asciidoc formatting rules. They are very simple and infact for programmers it is extremely natural. AsciiDoc is what most of us write when we write in a standard text editor anyway so there is not that much to learn to get started. There are of course some more advanced features for linking sections with anchor points and such, but for now let’s just concentrate on getting the basics right.
Sections are easily created. The order of sections and sub sections is shown below:
Top Section (Level 1)
Sub-Section (Level 2)
Sub-Section (Level 3)
Sub-Section (Level 4)
If you need to go deeper than four levels – check your documentation – you probably don’t need to nest this much. However, check the user guide for all available levels.
Admonition paragraphs are highlighted with an icon to bring attention to a short paragraph. They are used to highlight important facts which may be skipped over during general reading of a document. They can be used to highlight ambiguous points or notes of interest. They are extremely easy and natural to use – just type the style of the callout (which determines the icon that will be placed to the left side of the paragraph, followed by a colon and then the paragraph. For example:
[code]IMPORTANT: Pay attention to this information it’s important![/code]
The available admonition paragraphs are:
TIP, NOTE, IMPORTANT, WARNING and CAUTION
You can include source code in the documentation too so that it stays correctly indented, etc. You’ll need to make sure GNU SRC Highlight is installed.
To include source code in the documentation, use a BB style bracketing and tell asciidoc what formatting to use (i.e. what the language of the source is):
int main(int argc, char* argv)
For more information on the standard source code hightlighting, see The Asciidoc source code highlighting filter documentation.
In order to quote, you simply create a block similar to the source code block, but add quoting attributes instead, like so:
[code][quote, Brian Sidebotham, ASCIIDoc for Project Documentation]
In order to quote, you simply create a block similar to the source code block,
but add quoting attributes instead, like so:
It is possible to add comments into the asciidoc document – these will never be output. A comment must start with two forward slashes on a new line with no spaces before the slashes. e.g.:
[code]// An Asciidoc comment – this line will never appear in the document output[/code]
A Very Quick Example:
Grab the very quick example here. Compile it using:
[code]asciidoc -b html5 -a icons -a toc2 -a theme=flask valvers.txt[/code]
and you should get an output similar to the following:
Pretty nice for an ASCII document! 😀