Author: Nikos Kouremenos
AsciiDoc comprises two programs: asciidoc for the most basic documents, and the more featureful a2x. Installation packages exist for many popular Linux distributions as well as for Microsoft Windows. Scripts are provided in the source package for those who prefer to install AsciiDoc from source; run ./install.sh (as root). You can uninstall the package (again as root) with the provided uninstall.sh script.
Running asciidoc is a simple. The program is a Python script that requires a specially formatted text file as input. Let’s examine an example file we’ll call demo.txt:
AsciiDoc showing very basic C++
================================
Nikos Kouremenos <someone@somewhere.com>
:Author Initials: NK
:numbered: Yes
:icons: Yes
Print something
----------------
.Printing (myApp.cpp)
[cpp]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#include <iostream>
using namespace std;
int main()
{
cout << "We few, we happy few, we band of brothers." << endl;
return 0;
}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Now do
----------------
$ g++ myApp.cpp
$ ./a.out
----------------
and you should see: +
We few, we happy few, we band of brothers.
NOTE: In Python, you just do *print "We few, we happy few, we band of brothers."*
To process this document, run the command asciidoc demo.txt. This will produce a demo.html file by default, which will look like this.
The syntax of an asciidoc file is simple, and easy to learn by using examples and the project’s user guide.
Asciidoc will automatically highlight source code syntax by using GNU source-highlight. To enable this functionality, specify the language used in square brackets immediately prior to the code block in the source document. In our example, the line [cpp] enables source highlighting for C++.
You can also include iconified alerts in the target document, as demonstrated in the above example using the NOTE: modifier. To enable this functionality, include the line :icons: Yes in the source document header. By default, asciidoc will look in ./images/icons/ for the appropriate images. Supported alerts include NOTE:, TIP:, IMPORTANT:, WARNING:, and CAUTION:.
The :numbered: Yes notation in the header of our example instructs asciidoc to enumerate the sections and subsections in our resulting document. The utility supports a list of several supported document attributes. Attributes that are included directly in the source document override any system-wide attributes that may be set in a global AsciiDoc configuration file.
Using a2x
The a2x program is much more complex than asciidoc, as it depends on a powerful chain of external utilities such as xsltproc, DocBook XSL Stylesheets, FOP (for PDF file generation), Lynx (for text file generation) and docbook2odf (for Open Document file generation) to perform its conversions. A2x can be used to convert an asciidoc source file to PDF, XHTML, HTML Help (CHM), ODF, and manpage formats.
After a significant amount of searching, I was unable to find an easy way to install the a2x utility and all of its dependencies. A tool or script that could perform such a task for the less technical user could prove invaluable. Until such a tool is produced, however, the installation and configuration of the chain can be quite time-consuming.
AsciiDoc is a great utility for producing visually pleasing HTML documents from simple plain text files. It’s trivial to use for simple tasks, but for more complex tasks it may require users to dig into the documentation. Indeed, when first learning to use the tool users may find themselves investing more time in document creation than they would have invested had they used a WYSIWYG editor. However, once learned, the advantages of writing documents in plain text with the ability to produce documents in a wide variety of formats from the same source become clear.
