For quite some time, lightweight documentation formats have been a big thing in the world of open source community documentation. While corporate environments are not very eager to move from their (often) ancient documentation platforms due to cost concerns, it is usually less of an issue for a typical open source documentation project out there to migrate to a new format.
I’ve recently started converting one of the open source documentation suites that I contribute to from a Publican-based DocBook XML source into AsciiDoc, which has been getting lots of attention especially from developer-centric communities.
The semantics of AsciiDoc is based on DocBook and AsciiDoc draws its roots from this industry-standard XML language. This allows for an easy AsciiDoc to DocBook conversion. Sadly, when you need to convert your DocBook content into AsciiDoc, you are left with a number of conversion tools which are either unmaintained or have incomplete support for DocBook syntax. This is an important aspect to consider when you are planning to migrate your documentation to the new format, especially if your documentation suite is rather complex and features a rich set of syntax and semantics.
Preparing your XML document for conversion
From the tools available for the conversion task (pandoc + docbook2asciidoc.sh, docbook2asciidoc, and others), docbookrx seems to have the most complete support for DocBook syntax. It can preserve tables, included files and images, procedures, and so on. Not all DocBook elements are supported, though. Here is an (incomplete) list of elements I had to replace with sed:
- productname
- menuchoice → menu:examplemenu[examplesubmenu > examplesubsubmenu]
- guimenu → [label]#example#
- guisubmenu → [label]#example#
- guimenuitem → [label]#example#
- userinput → [userinput]#example#
- option → `example`
- systemitem → `example`
- remark
- revhistory
It is always a good idea to use a version control system to track any replacements in your XML source files.
What is nice about docbookrx is that it prints a warning when it runs into an element that it can’t recognize. Some of the other converters just silently drop the unrecognised element, including the content inside it, which is something to bear in mind.
Using docbookrx.rb
- Clone the docbookrx repo:
git clone git@github.com:opendevise/docbookrx.git
- Copy the docbookrx.rb Ruby gem from the repo to the directory containing the XML files you want to convert.
- Load the gem, specifying a root file of your document as the input file:
ruby docbookrx.rb Admin_Guide.xml > Admin_Guide.adoc
The gem will follow included files referenced from the root file and convert the whole document.
- Run asciidoctor to generate an HTML preview:
asciidoctor Admin_Guide.adoc
Some additional clean-up of your document is usually needed afterwards but the document’s overall structure and syntax should be preserved.