Generating Eclipse Help from Docbook

A while ago Chris Aniszczyk and Lawrence Mandel wrote an article for eclipse corner titled "Authoring With Eclipse". This is a very good article that uses several freely available plugins to allow creating and authoring of PDF, HTML and other formats from Docbook. I recently discovered the joys of Docbook as I was working on converting some guidelines for work into multiple formats. Being able to separate content from the presentation is a great benefit when you have to support multiple output formats.



Docbook includes a stylesheet for generating eclipse help system files. This is described in detail by Jirka Koreska in "DocBook for Eclipse". The screen shot shown is the XSL Launch configuration for generating the appropriate files, using the XSL Tooling project. There is one issue, and that is by default, it will output the plugin.xml, and toc.xml to whatever the working directory is, and not the base.dir.

There are several ways to address this:

1. Create a Customization layer for the eclipse.xsl file, so that the plugin.xml and toc.xml are placed in the plugin project directly. Either through a new variable or modifying the templates directly.

2. The other option is to add support in the XSL Launch Configuration to specify the working directory. Bug 221042 suggests just this very thing.

3. Create a build.xml file that generates the file. This allows for inclusion of XIncludes and additional post processing beyond what the XSL Launch configuration allows.

Option 2 is needed anyways, when dealing with the exslt:document function, which allows outputing multiple documents during one transformation process. Otherwise they end up in whatever is the current working directory, and this usually isn't a project directory in your workspace.

The Docbook eclipse stylesheet does need a few updates, but it works very well as is (once you move the files to the correct directories). There are some open request for both DITA and Docbook support within the XSL Tooling project. We've already had our first code contribution from Lars Vogel to allow us to support XInclude, and also have an ANT Task. Look for this to be hopefully added in 0.5M6.

Updated 03/02/08 to correct the spelling of Chris's last name.