jDocBook Plugin

DocBook is, in part, "an XML vocabulary that lets you create documents in a presentation-neutral form that captures the logical structure of your content". Another aspect of DocBook is the rendering of that content into various formats using DocBook-supplied (or custom) XSLT stylesheets. Basically, DocBook allows you to write and maintain a single source for documentation, and to then render that single source into multiple formats such as PDF or HTML.

The purpose of the jDocBook Plugin is to allow these DocBook transformations to occur as a natural part of the users Maven build. The main difficulty with this has always been the fact that DocBook transformations are usually very closely tied to the user's local environment. The design goal with writing this plugin was to utilize Maven's dependency mechanism to bring all the pieces together on demand. Those pieces are:

  1. the DocBook distribution;
  2. custom XSLT;
  3. custom fonts;
  4. custom images;
  5. custom css.

These are the ingredients that when mixed with the source file(s) and stirred with an XSLT transformer produce the desired output(s).

Currently, only SAXON is supported as the transformer factory. I have had issues getting XALAN to work properly.

Goals Overview

The jDocBook Plugin defines a dedicated project packaging ("jdocbook"). In part, this packaging is used to redefine a suitable set of lifecycle phases pertinent to performing DocBook transformations. Below are the defined lifecycle phases, with the goals attached to them:

process-resources
binds the jdocbook:resources goal which "stages" the resources need for the XSLT transformations such as fonts, images and css.
compile
binds the jdocbook:generate goal which performs the actual XSLT transformations.
package
binds the jdocbook:bundle goal which takes all the output formats, archives them as WARs and attaches the WARs to the project with the format name as the artifact classifier.
install
binds the standard install goal.
deploy
binds the standard deploy goal.

Usage

Detailed usage instructions for the jDocBook Plugin can be found here.

Examples

To provide you with better understanding of some usages of the jDocBook Plugin, you can take a look at the following examples: