This document provides an overview of the different features of the Maven Docbkx Plugin. With almost 200+ customizable properties per type of output format, it would be impossible list all of those in this document. For more detailed information on these customizable properties, please consult the online plugin documentation. Instead of being a reference guide, this document is intended to get you started, and at least to get some flavour of the scope of this plugin.

In this document, we will discuss every feature with an example, showing the relevant configuration code. You are encouraged to work through these examples in the given order.

Example Usage

This is by far the simplest example that you can possibly imagine. At a bare minimum, you need to specify a dependency on the jar file containing the DocBook DTD. That is, if your source documents are refering to a DocBook DTD at all. There are however good reasons to include a DTD reference, as you will find out in one of the following examples.

Using this configuration, you can build a document from the sources by invoking docbkx:generate-html. This will try to convert all files matching the *.xml file pattern in $basedir/src/docbkx to HTML pages.

Example 1. Minimal configuration

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

Normally you would of course want generation of the documents to happen automatically. In this sense, the Docbkx Maven Plugin is hardly any different than all of the other existing Maven 2 plugins. Simply add an execution element to specify the goal and the phase. The example below specifies that the documents in src/docbkx should be turned into HTML in the pre-site phase.

Example 2. Attached to a phase

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate-html</goal>
            </goals>
            <phase>pre-site</phase>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

Adding other output formats is easy. Simply specify it as additional goals. In the example below, we are not only rendering HTML but also PDF and UNIX man pages. (Note however that it does not make a lot of sense to render man pages from an appendix. You still need to add your own common sense to figure out which output formats make sense with your documents.

Example 3. Multiple output formats

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate-html</goal>
              <goal>generate-pdf</goal>
              <goal>generate-manpages</goal>
            </goals>
            <phase>generate-sources</phase>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

So now we are able to render different types of output. You might however not be impressed too much by the default output of the plugins. The good news is that there is a lot (!) to customize. Every goal (every output format) defines its own collection of customizable properties. The entire list would be far to big to list here, so we will just give a simple example. Let's just assume that you crafted your own CSS file containing the essential bling bling for your DocBook output file. In that case you can simply link this stylesheet to all HTML pages generated by addding the htmlStylesheet property, like shown below.

Example 4. Additional customization

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <htmlStylesheet>http://.....</htmlStylesheet>
        </configuration>
      </plugin>
    </plugins>
  </build>

The example given above highlights one of 200+ customizable properties that correspond to XSL parameters defined by the DocBook stylesheets. In addition, the plugin also defines a couple of properties of its own. You will probably find the includes property among the ones you will use most often. This property allows you to specify a comma separated list of file patterns to include in the transformation. The example given below specifies that any file matching $basedir/src/docbkx/-docbkx.xml should be included in the transformation.

*Example 5. Explicit source file selection

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <includes>*-docbkx.xml</includes>
        </configuration>
      </plugin>
    </plugins>
  </build>

One of the more advanced and interesting things of the Docbkx Maven Plugin is that it allows you to refer to POM properties from within your DocBook documents. Take some time to think that over... The plugin solves this by mapping entities to values defined in your POM. And in your POM you can define the values to be composed of other POM properties.

An example will help you to understand what this means. First of all, it is not uncommon for documents to refer to a version of the software. Maintaining the dependency by hand would be a lot of work, and there would be severe chance that it would go out whack in no-time. So, would it not be awesome if we could refer to the Maven version number from within our DocBook source document?

The good news is: you can. Look at the code snipped below to figure out how to do it. In all honesty, it is not that complicated at all. Within the entities section, you simply define an entity called version, and define it to be the value of the POM property version. The plugin will make sure that any reference to &version; will be translated to the version number defined in your POM.

Example 6. Entity substitution

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <entities>
            <entity>
              <name>version</name>
              <value>${{version}}</value>
            </entity>
          </entities>
        </configuration>
      </plugin>
    </plugins>
  </build>

Hopefully all of the above will make you consider using DocBook. DocBook does not need to be hard at all, and - if you want to - DocBook authoring can be almost like .... coding. The fact that it is plain old XML just makes it a very interesting candidate for completely automating your document generation. And with all of the XML based metadata available in your projects, it would actually be incredibly easy to accomplish.

The only problem that might get in the way if you are thinking about generating DocBook sources is the fact that Maven does not really provide a clear hook or phase for it. For that reason, the Maven Docbkx Plugin defines the preProcess and postProcess properties. When your project requires you to generate some content just in time, right before rendering PDF or HTML from DocBook, or if you need to do some post processing, then the plugin allows you to 'script' it in Ant vocabulary as part of the plugins configuration.

The example below does not really do anything interesting before rendering PDF output. It does however demonstrate how you could include your own scripts to be executed right before or right after the DocBook to output format transformation.

Example 7. Preprocessing DocBook sources

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <preProcess>
            <echo>Some script executing.</echo>
          </preProcess>
        </configuration>
      </plugin>
    </plugins>
  </build>

This example demonstrates how you can split up your HTML output document in multiple parts. Simply set the chunkedOutput property to true. That's all. The plugin will continue to use target file name, but reserve it for the first chunk of HTML. The remainder of the document will broken up into several pieces, depending on the policies you specified with customization properties.

Example 8. Chunked output

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <chunkedOutput>true</chunkedOutput>
        </configuration>
      </plugin>
    </plugins>
  </build>

In the past, the only way to compose a DocBook document from several parts required system entity include statements as part of your DTD declaration. XInclude provides an alternative and much more sophisticated way to pull in data from other sources. If you want XInclude support, then you should set the 'xincludeSupport' property to 'true'. Note that this feature is still fairly experimental.

Example 9. XInclude Support

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <xincludeSupported>true</xincludeSupported>
        </configuration>
      </plugin>
    </plugins>
  </build>

The easiest way to customize your DocBook output is probably by changing property values, as outlined above. However, there may be situations in which you need more flexbility. The plugin provides this flexibility by allowing you to pass a reference to your own stylesheet.

The mechanism is similar to what you would do normally when adding your own customization layer. You create a customization stylesheet that starts by importing the standard docbook.xsl stylesheet. The trick is how to locate the 'standard' docbook.xsl stylesheet. After all, the plugin would normally hide it from you entirely, right?

The trick is to use a 'symbolic' reference instead of a real location in your import. By using this import: <xsl:import href="urn:docbkx:stylesheet" />, you basically tell the plugin to import the standard stylesheet for your specific output format.

Once you have your own customization stylesheet (probably based on some of the tips in Bob Sagehills excellent book), you can simply tell the plugin to use that customization, by setting the foCustomization property (in case of PDF output) or/and the htmlCustomization property (for HTML output).

Example 10. Advanced Customization

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <foCustomization>src/test/resources/docbook-fo.xsl</foCustomization>
        </configuration>
      </plugin>
    </plugins>
  </build>