Writing DocBook documents always requires one to configure a suitable build system which generates the desired output formats. This post shows how to do that with Maven all from within Eclipse:

1. Download & Install Eclipse

If you have Eclipse not already up and running download it at http://eclipse.org/downloads/- it does not really matter which version you get or have as we are going to add missing plugins anyway.

2. Install m2eclipse Plugin

The m2eclipse plugin embedds a complete Maven 3 runtime inside Eclipse and thus lets us use all of Mavens features. Since we want to use Maven to generate our documents this plugin comes in handy because we won’t have to switch between Eclipse and a Maven shell all the time.

3. Download DocBook W3C XML-Schema files

To enable validation of your DocBook sources inside of Eclipse you’ll need the DocBook XSD files. Download all three (docbook.xsd, xlink.xsd and xml.xsd) and put them somewhere safe.

4. Install Eclipse XSL Tools (Optional)

When you plan on splitting your DocBook files into multiple parts you want to enable XSL support in Eclipse so that it won’t give you any validation errors. To do so install the Eclipse XSL Developer Tools from the main Eclipse repository for your release. I’m currently on the Helios (3.6) release and therefore it got the XSL tools from the Helios repository as shown in the following picture:

5. Install docbkx-archetype (Optional)

Maven allows one to use predefined archetype as a template for new projects. The docbkx-tools project defines one for DocBook publishing using Maven and their own plugin. Archetypes are not really needed as you can always write everything yourself but most of the time they offer a quickstart to whatever you are going to do. The following files are all derived from the docbkx archetype.

At this point we have all necessary tools and files for DocBook editing and publishing using Maven and Eclipse. To start writing you can now either create a new Maven project inside your Eclipse workspace using the docbkx archetype from step 5 or just a simple Maven project without the use of any archetype. Both ways will result in a pom.xml file which is the main configuration file for your project and the place to configure PDF output, etc. For this post I’ve started with the archetype project layout but modified it to better reflect the standard Maven layout. It looks as follows:

The pom.xml (link) looks like this:

As you can see, all DocBook sources are inside the src/main/docbkx folder and will get automatically picked-up by the docbkx-plugin. Also note that I’ve changed the file extension of all the DocBook files to .dbk which is the default file extension of DocBook files. The files under src/main/resources/xsd (these are the files from step 3) will now be used to validation your sources and provide you with content assist. For that open the Eclipse preferences via Window > Preferences and switch to the XML > XML Catalog category as shown in the following picture.

There add a new catalog entry by clicking on the Add button. The final result should look like in the pictures. If you want to use XIncludes as well you have to enable the “Process XML Inclusions” checkbox inside the XML > XML Files > Validation category as shown below.

At this point we are almost there but we still need to enable the actual validation. For this right-click on your project, select Properties and switch to the Validation category. There add a validation builder to your project and click on the XML validator settings as shown in the following picture.

Inside the XML validator settings click on the first include group (or create your own) and add a single rule to include files with a DocBook content-type. The DocBook content-type is already configured in the latest versions of Eclipse so no additional work needed. The result should look like the following:

At this point all validation of DocBook sources works and you have content assist inside those sources. To finally generate some output we are going to create a simple launch configuration with Eclipse which will call Maven to build your project. For that just right-click on your project, select Run As > Maven build… and set the goal to clean pre-site as shown in the following picture.

Now hit Run, wait for the process to finish and look into the target folder of your project for final outputs.

The nice thing about this setup is that it can be easily shared via SCM-systems. It only includes source files with the exception of those XSD files from step 3 and the FO stylesheet. But those could be easily moved into seperate projects, modules, plugins or just a network drive to make them accessible for all writers within a team.

(For the impatient I’ve created a sample project at github which includes all necessary files)