Super Advanced Customization
Once you've done Advanced Customization a couple of times, you might start to get a little annoyed by the fact that you continuously have to copy your customization stylesheets in each of your project. That sucks. It would be so much better if you would be able to package it all as a single plugin, right?
Well, with a bit of work, you can actually do that. And before you learn how, there is something you need to know about the Maven Docbkx Plugin. You see, the Maven Docbkx Plugin is actually mostly auto generated by the stylesheets in a Docbook stylesheets distribution. The figure below illustrates the process:
The actual Mojo classes are generated directly from the Docbook XSL stylesheets. Once these Mojo classes are built, they are combined with your own sources and other resources (potentially) taken from the DocBook XSL distribution, and the result is then forged into a new Maven plugin. And all of this can (and is most ideally done) in a Maven project.
The Docbkx Tools project is shipping a Maven plugin assisting you with the first step: the Maven Docbkx Builder Plugin. (Mind the 'Builder' term; don't confuse this with the Maven Docbkx Plugin.) You configure the plugin with the version number of the Docbook XSL distribution, and a package name for the generated sources. In addition, you add some meta data for every type of output document you aim to generate using your plugin, and you're done.
Note that the plugin assumes you have a zip file including the DocBook stylesheets included in your distribution. It assumes the location of that zip file is lib/docbook-xsl-[version].zip, in which the version is the version of the zip file set as a plugin property, as outlined above.
Now, there are quite a few things you can configure on the Maven Docbkx Builder Plugin. You can for instance specify that you want to have your Mojo extend a class of your own, in case you want to add your own behaviour. If you wish to do so, make sure you subclass AbstractTransformerMojo, included in the docbkx-maven-base project.
Whenever the Maven Docbkx Builder Plugin is invoked to generate Mojos from a collection of stylesheets, it will gather all parameters supported by that stylesheet, and turn that into Mojo properties. However, you probably don't want to have all of those properties exported. And as it turns out, you can tell the Maven Docbkx Builder Plugin to ommit some properties. For the actual Maven Docbkx Plugin, it excludes properties like:
- VERSION
- PreviousReleaseRevision
- sf-relid
- VersionFileURL
- Revision
- Tag
- DistroName
- etc.
You can probably guess why these properties are omitted. It makes very little sense to allow users to override the values of these properties.
Now, having this, sky is the limit. You can basically build any type of plugin and have any type of pre- or postprocessing you want. This document is not going to give you all the options. That's up to your own creativity. If you want to know more, just carefully study the sources of the Maven Docbkx Plugin itself. It's a little messy, so it will probably take you some time, but it's doable.