Automating Eclipse Help Generation

This article assumes that you are familiar with Eclipse Help. If you are not, you can refer to my earlier blog entry to learn more about it.

Some of the common formats used to author Eclipse Help are DocBook and DITA. Both of these formats use XML as source. The main benefits of using XML (instead of binary files) as source are, you can use your version control to maintain history (and see diffs) and can publish the source to multiple formats (PDF, HTML, EclipseHelp etc.,), using the same consistent formatting.

We used to use DocBook, but transitioned to use DITA since Adobe FrameMaker had good support for DITA and our technical writer was comfortable with using FrameMaker as well. Here is an article on how to author DITA topics using FrameMaker.

The next step is to transform DITA to EclipseHelp. You could use DITA open toolkit directly to produce help files. Better way is to use DITA maven plugin, which can be found here. If your Eclipse Help plugin does not have a POM, create one first. Then, all you need to do is to make sure that your POM follows this usage explained here. Look at the executions where Eclipse Help generation is bind to generate-sources phase.

output.dir specifies the directory where Eclipse Help will be generated.
args.input specifies the location of the ditamap. ditamap is where DITA topics are mapped. See here if you want to know what a ditamap is. ditamap supports both top-down and bottom-up composition. Make sure to use bottom-up composition and if you are not sure about the difference, you can see it from my earlier blog entry.
transtype specifies the output format and can be "pdf", "htmlhelp", "xhtml" or "eclipsehelp".

If you use style sheets to format your help, you could use args.css, args.csspath and args.copycss parameters to specify information about your css. Finally, make sure you have all the dependencies listed are in your maven repository.

That's it. Now, all you have to do is type "mvn generate-sources" (or any build lifecycle phase greater than generate-sources. For more info on maven lifecycles and it's phases, refer here) in command-line to generate Eclipse Help. You still need to maintain plugin.xml of your Help Plugin and make sure that toc and index files are referenced properly. But, this is easy and the hard work of creating html files and toc files are done by the maven plugin.