Fortunately we have been able to remedy this problem, without sacrificing any of the power and flexibility of our Docbook tool-chain, by converting all our Docbook source into AsciiDoc. The AsciiDoc source is in turn converted back into Docbook xml, and fed into our existing tool-chain. This toolchain is a set of Pressgang XSLT files that takes the Docbook xml and converts it into our published PDF and HTML docs.

The capabilities of AsciiDoc are well demonstrated by the fact that we were able to create identical HTML and PDF docs using the AsciiDoc generated Docbook xml, without making any changes to our Docbook tool-chain. AsciiDoc is indeed a highly expressive markup language. On the other hand, AsciiDoc is only as complex as you want it to be - in basic use cases it’s as simple to read as Markdown.

Converting the Docbook xml into AsciiDoc however was not a simple task. We had a significant step forward by starting with the docbook2asciidoc XSLT project from O’Reilly media that converts Docbook xml into AsciiDoc. Jason Porter had already forked the project, introducing some changes to handle Red Hat flavoured Docbook.

We forked that fork, and introduced a number of additional changes to the XSLT to properly convert the Docbook xml into AsciiDoc. This conversion took us 98% of the way there, the final leg of the conversion was finished with some regexps and manual fine-tuning.

We also looked at the Pandoc project - a multi-purpose document converter that is able to output Docbook xml. We stuck with the XSLT for two reasons:

Although had our initial format not been xml, Pandoc would probably have been a better choice. Hopefully the Asciidoctor project is able to fill this conversion-to-asciidoc void in a future release.

Checkout the results, here are links to the AsciiDoc files on GitHub. Notice how GitHub renders the files, you can click the "raw" buttons to see the AsciiDoc source.

A word on AsciiDoc implementations. AsciiDoc is by no means a new kid on the block - the original python implementation has been around since 2002. However in 2012 a second implementation of AsciiDoc was begun called Asciidoctor. Written in Ruby, Asciidoctor has recently caught up with the original AsciiDoc implementation, and in many ways surpassed it. Asciidoctor is amazingly fast, rendering documents an order of magnitude more quickly than the original python implementation.

Coupled with these general improvements, the Asciidoctor community has done a great job integrating the ruby-based Asciidoctor with java via the asciidoctor-java-integration project. This java integration is then used to create a full-featured asciidoctor-maven-plugin, making Asciidoctor a natural choice and a good fit into our existing tool-chain.

Following the AsciiDoc conversion, we put the new format to the test with a massive edit of the docs to reflect the changes we introduced to the framework in RichFaces 5. I’m happy to report that the transformation was a success - the doc changes were nearly trivial to implement. This is indeed a huge step forward for the project, and will enable us to provide you, our user community, with much better documentation.

While we will release RichFaces 5.0.0.Alpha1 with our new AsciiDoc based documentation, we are by no means down with our doc changes. Now that we have the new simpler AsciiDoc source in place, we will re-arrange the docs to provide something that is both more accessible and useful.