Monday, June 10, 2013
With RichFaces 5 we have made a significant change to our documentation tool-chain with the introduction of AsciiDoc to simplify the task of authoring and editing the RichFaces documentation. Our documentation has for a long time been based on Docbook xml against which we have applied the Red Hat PressGang XSLT to create the HTML and PDF output of our docs.
Additionally the Docbook xml is fed downstream into Red Hat’s Web Framework Kit product (WFK), where it undergoes further transformations to fit well into Red Hat’s product documentation. Docbook xml is great for such manipulations, but it is by no means straight-forward to author. Anything more than simple edits quickly turns into a complex task.
Bring in the AsciiDoc!
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.
The one-time conversion to AsciiDoc
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:
Out-of-the-box the XSLT brought us closer to our target.
Our XSLT expertise allowed us to hack the docbook2asciidoc to suit our needs, wheres Pandoc is written in Haskell which presented too a steep learning curve for a one off migration.
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.
Changes with RichFaces 5
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.
Enable the community!
Conversely, we are hoping the more accessible format will enable more of you to jump in and fix errors and provide additions as you notice gaps in the documentation. So jump in! Give the new docs a read, and click that edit button in GitHub to initiate a pull request with any improvements you can suggest!
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.