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 you need to get it from Github directly. Also it was written for Python v2 although a fork has been done for Python v3. For Python v2, clone the directory using a Git client from Github (Python v2) or alternatively use the Download ZIP option from the Clone or download button and unpack the zip file. Once downloaded you can build the documentation for the AsciiDoc program with the following command:

python asciidoc.py doc\asciidoc.txt

For Python v3, either clone or download and unzip from the Python v3 Github site. The programs have all gained a 3 suffix to their name so the equivalent build command for the AsciiDoc documentation is:

python asciidoc3.py 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 from AsciiDoc to most other formats, the program converts the text 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 ftp://ftp.zlatkovic.com/libxml/. 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 a2x.py 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 a2x.py -L -f epub -v doc\asciidoc.txt

or for the v3 fork:

python a2x3.py -L -f epub -v doc\asciidoc.txt
Advertisements