Converting DocBook into AsciiDoc

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, 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

  1. Clone the docbookrx repo:
    git clone
  2. Copy the docbookrx.rb Ruby gem from the repo to the directory containing the XML files you want to convert.
  3. 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.

  4. 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.

Open Help Conference 2015 Hackfest Wrap Up Notes

Wrap up notes for the Open Help Conference 2015 GNOME Documentation Hackfest, Cincinnati, OH, September 28 – 30, 2015.

The hackfest was held at a lovely co-working place called Platform 53 in Covington, Kentucky, just across the river from downtown Cincinnati. During the three intensive days full of writing, the docs team managed to update tons of pages throughout GNOME Help.

  • Due to the timing of the 3.18.0 stable release, the updates, together with some updated translations, eventually landed in 3.18.1.
  • I mostly focused on updating user account, power, and printing help. These should be in a good shape now. There are exceptions, though, like documentation on enterprise login, which is pending some code-related updates.
  • Some of us struggled with getting a 3.18.0 up and running. We tried different build images from GNOME Continuous, Fedora, and openSUSE. While there seems to be a plenty of options at first glance, when it comes to being able to try out and preview the actual GNOME Desktop, I think there is still a long way to go.
  • Testing some of the cool features in 3.18 can get challenging, for example, automatic screen brightness that requires an integrated light sensor. I wish I had one!
  • I managed to get the Getting Started module in sync with most of the updates that landed in GNOME Help. Meanwhile, Jakub has been working on a different approach to Getting Started animations.
  • The team had a profound discussion about restructuring some of the most visible topics and topic groups in GNOME Help. We made good progress, although some of the issues, including content duplicity, remain unresolved. Material for the next hackfest?
  • Shaun organized a team building event for us, we watched a baseball game at Great American Ball Park. Cincinnati  Reds!

Big thanks to Shaun & Kat for organizing the hackfest, and the GNOME Foundation for sponsoring me!

View from Platform 53 towards Downtown Cincinnati.
View from Platform 53 towards Downtown Cincinnati.
The ball game in Cincinnati.
The baseball game in Cincinnati.