Month: August 2017

AsciiDoc and DocBook

I’ve covered Markdown (.md) in other posts but another text format gaining popularity is AsciiDoc which is a plain text interpretation of DocBook XML. These files generally use a verbose .asciidoc file extension but you can sometimes see them using the text file (.txt) extension.

The main AsciiDoc program is written in Python, but there is no pip install method. Instead clone the directory using the Mercurial hg command or if you have not got a Mercurial client visit the Google Code website to download and unpack the zip file.

Once downloaded you can build the documentation for the AsciiDoc program with the following command:

python doc\asciidoc.txt

This also acts as a way to test the basic setup. If all goes well you should see no error messages and it should create a doc\asciidoc.html file which you can open with any web browser.

To get most other formats, AsciiDoc converts the file to the DocBook XML format and then acts as a wrapper around DocBook to create the necessary file. DocBook is not aimed at Windows users so getting it installed is not straight forward. Thankfully combining this blog post and this SO post gives us the installation steps below.

First go to DocBooks SourceForge site and download the zip file. Unpack this to the C: drive (or wherever you want it) and optionally rename the directory to docbook-xsl, that is remove the version number from the folder. Add this folder to your path environment variable.

Now you need libxml2, libxslt, libxmlsec , zlib and iconv. A Windows build of all these can be obtained from Download the latest version of the zip file for each library and extract the contents of the bin directory of each zip file into the docbook-xsl directory created above.

So avoid calling several programs to create the other files, there is also provided. This is a wrapper around the various software programs that need to be called. To create an epub ebook of the instructions above the command becomes:

python -L -f epub -v doc\asciidoc.txt