Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <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>
        <version>1.69.1.7</version>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <xincludeSupport>true</xincludeSupport>
        </configuration>
      </plugin>
    </plugins>
  </build>
  • No labels