Wednesday, March 11, 2009

Documentation ported to Docbook

Gilberto C. Andrade recently ported Click's documentation to Docbook using Michael Fuchs HTML to Docbook converter.

This is really great news as we can now generate the documentation in both PDF and HTML formats.

Below is a screenshot of how the PDF looks like:



And here is how the HTML version looks like:



To generate the docs we use a modified version of the Velocity Docbook Framework. The modifications include upgrading to the latest versions of Apache FOP and Docbook XLS.

To achieve syntax highlighting for our source code we include the XSLTHL library.

The only issue I encountered was that XSLTHL doesn't work with the latest official Docbook XLS release. Luckily the latest snapshot of Docbook XLS resolved the issue.

We hope the new format will make it easier to read and learn Click.

The Click team.

6 comments:

Frederic Daoud said...

That's great news - keep up the good work!

Bob Schellink said...

Thanks Freddy, just hope the Docbook maintenance isn't too high ;-)

Anonymous said...

How complicated would be for other projects to use that modified version of (velocity)Docbook toolset for document generation? (e.g. if the project already is using ANT).

Bob Schellink said...

Hi,

Here are the steps I took to upgrade Velocity Docbook (DBF) were:

1. Replaced DBF/lib/fop.jar with fop-0.95.jar. Also added fop-0.95 dependencies namely xmlgraphics-commons.jar, batik-1.7.jar, commons-io.jar and commons-logging.jar to the DBF/lib folder

2. Also added xslthl.jar to DBF/lib/ for syntax highlighting

3. Replace DBF/src/zip/docbook-xsl-1.70.zip with the latest snapshop.zip and changed the property dbf.xsl.version in the file DBF/docbook.properties to refer to the snapshot

We've created a Google code project containing the modifications. You can grab a copy here: http://code.google.com/p/click-docbook/source/browse/#svn/trunk/build

And if you're interested here is Click's docbook: http://svn.apache.org/viewvc/incubator/click/trunk/click/documentation/xdocs/

Hope this helps.

kind regards

bob

Anonymous said...

> Here are the steps ...
Thank you very much!

I think your detailed description about how to use docbook deserves front page blog post (not just a comment - you can't vote them on dzone :) ).

hantsy said...

I also create a docbook build tool for converting Docbook to HTML, chunked html and PDF.
see http://code.google.com/p/hantsy-labs/ .