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.
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>${project.version}</version>
</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 and XHTML 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>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-html</goal>
<goal>generate-xhtml</goal>
<goal>generate-xhtml5</goal>
</goals>
<phase>pre-site</phase>
</execution>
</executions>
<configuration>
<includes>article.xml</includes>
</configuration>
</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, UNIX man pages and Eclipse help files. (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>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-html</goal>
<goal>generate-pdf</goal>
<goal>generate-eclipse</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>article.xml</includes>
</configuration>
</plugin>
</plugins>
</build>
This samples shows how to generate a manpage software documentation, a simple sample is provided in "manpages/first-command.xml" file.
Example 4. Manpages output
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-manpages</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>manpages/first-command.xml</includes>
</configuration>
</plugin>
</plugins>
</build>
This sample shows how to setup a dependency to docbook xml 4.4 in order to enable xml catalog resolution for Docbook 4.4 public identifier. It is especially needed if you want to work offline
Example 5. Docbook XML 4.4 DTD
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<dependencies>
<dependency>
<groupId>org.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.4</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<configuration>
<includes>4.4/article.xml</includes>
</configuration>
</plugin>
</plugins>
</build>
This sample shows how to setup a dependency to docbook xml 4.5 in order to enable xml catalog resolution for Docbook 4.5 public identifier. It is especially needed if you want to work offline. You will need to add a thirdparty sonatype repository in your pom configuration:
<repositories> <repository> <id>sonatype-public</id> <name>Sonatype Public</name> <url>http://repository.sonatype.org/content/groups/public</url> </repository> </repositories>
Example 6. Docbook XML 4.5 DTD
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<dependencies>
<dependency>
<groupId>docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.5</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<configuration>
<includes>4.5/article.xml</includes>
</configuration>
</plugin>
</plugins>
</build>
This sample is same nature of the previous one but this time it enables the xml catalog resolution for Docbook 5.0 public identifer.
Example 7. Docbook XML 5.0
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<configuration>
<includes>article.xml</includes>
</configuration>
<dependencies>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.0-all</version>
<classifier>resources</classifier>
<type>zip</type>
<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.
Note that - in case of boolean parameters - there are two ways you can pass values. The prefered way is to use 'true' and 'false', just like you're used to. However, in order to be compatible with previous versions, you *can* pass a numeric value as well. Zero is interpreted as false. Anything non-zero is interpreted as true. (This is the way the DocBook XSL stylesheets accept parameters.)
Example 8. Additional customization
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</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 9. Explicit source file selection
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</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.
As of version 2.0.5 of the plugin it got even better. Version 2.0.5 allows you to refer to properties *directly*, introducing the mapping to entities.
The procedure is simple. The plugin defines a dedicated processing instruction for inserting Maven properties. The processing instruction relies on the JSP Expression Language (probably familiar to many of you). So, you would for example be able to inject this <?eval ${project.version}?> to include the version number of your pom.xml file anywhere in your DocBook content.
Example 10. Entity substitution
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<dependencies>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.0-all</version>
<classifier>resources</classifier>
<type>zip</type>
<scope>runtime</scope>
</dependency>
</dependencies>
<configuration>
<entities>
<entity>
<name>version</name>
<value>${project.version}</value>
</entity>
</entities>
<includes>entities/article.xml</includes>
</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 11. Preprocessing DocBook sources
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</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 12. Chunked output
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-html</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<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.
As no goal is specified nor attached to a phase, you must specify it on the command line like 'docbkx:generate-pdf'
Example 13. XInclude Support
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<configuration>
<xincludeSupported>true</xincludeSupported>
</configuration>
</plugin>
</plugins>
</build>
The advanced XInclude mode is activated by specifying the additional 'generatedSourceDirectory' parameter. By doing this XOM xml parser will be used instead of Xerces, XOM being more powerful concerning XML Inclusions (xpointer ...)
As no goal is specified nor attached to a phase, you must specify it on the command line like 'docbkx:generate-pdf'
Example 14. Advanced XInclude Support
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<configuration>
<xincludeSupported>true</xincludeSupported>
<generatedSourceDirectory>${project.build.directory}/xinclude</generatedSourceDirectory>
<includes>xinclude/book.xml</includes>
</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 15. Advanced Customization
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<configuration>
<foCustomization>src/docbkx/docbook-fo.xsl</foCustomization>
</configuration>
</plugin>
</plugins>
</build>
The later versions of the DocBook stylesheets support syntax highlighting. In order to use it, add a language attribute to the DocBook element containing your sources, and set it to the language of the sources within that element. In your pom.xml configuration, set highlightSource to true and import highlight.xsl in your customization layer in order to enable highlighting support. (<xsl:import href="urn:docbkx:stylesheet/highlight.xsl"/>).
The highlightXslthlConfig attribute can be used to configure xslthl to add new highlighters, ... if you want to customize the highlighting properties you will have to do it in your xslt customization layer (you can start from highlight.xsl from the docbook distribution).
Example 16. Syntax Highlighting
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<dependencies>
<dependency>
<groupId>net.sf.xslthl</groupId>
<artifactId>xslthl</artifactId>
<version>2.0.1</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>net.sf.offo</groupId>
<artifactId>fop-hyph</artifactId>
<version>1.2</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<configuration>
<highlightSource>1</highlightSource>
<foCustomization>src/docbkx/docbook-fo.xsl</foCustomization>
<hyphenate>true</hyphenate>
<hyphenateVerbatim>true</hyphenateVerbatim>
</configuration>
</plugin>
</plugins>
</build>
PDF has built-in support for a number of fonts. It's not unlikely that you want to replace those fonts with something else. You can always refer to other fonts installed on your system, but then there is a chance that your audience does not have those fonts installed causing your document to be completely unreadable. So, it's probably safer to embed those fonts in the PDF files generated. This is supported as of version 2.0.8 of the Docbkx Maven Plugin.
The snippet included below shows how you include another font. The first thing that you should know is that PDF generation is based on Apache FOP. Apache FOP requires access to a 'metrics' file, containing some font metrics. Apache FOP ships a couple of tools for generating those font metrics, so you *could* generate those metrics file yourself, and include them in your sources. The Docbkx Tools project has a Maven plugin wrapping these tools, making it a little easier to generate those font files.
Once you have these metrics files, embedding the font in your PDF document is a breeze. The only thing that you need to do is add a font tag containing all relevant metadata. Simply include a reference to the .ttf file and the metrics file, and add some additional metadata. Once you have done that, you can refer to this font in the plugin parameters or in customization stylesheets you created yourself. In this case, we are overriding the default body font.
The configuration parameter <ansi>true</ansi> should be set to false if your document contains special characters.
If you need to get full access to the FOP configuration file properties, you can specify a custom configuration file using <externalFOPConfiguration /> parameter. The current <fonts /> parameter is deprecated since FOP 1.0 because the xml metric file is only used on specific cases (see FOP website).
Example 17. Alternative Fonts
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>generate-pdf</goal>
</goals>
</execution>
</executions>
<configuration>
<bodyFontFamily>Kaffeesatz</bodyFontFamily>
<fonts>
<font>
<name>Kaffeesatz</name>
<style>normal</style>
<weight>normal</weight>
<embedFile>${basedir}/src/fonts/YanoneKaffeesatz-Regular.ttf</embedFile>
<metricsFile>${basedir}/target/fonts/YanoneKaffeesatz-Regular-metrics.xml</metricsFile>
</font>
</fonts>
</configuration>
</plugin>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-fop-support</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<ansi>true</ansi>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
The JavaHelp format (combined with its java based framework) will allow you to create professional online help systems from your documentations.
Docbkx Maven Plugin will help you in generating the JavaHelp main content but will not create all the glue needed to have a JavaHelp up and running within your application.
Concerning the configuration properties of the goal 'generate-javahelp' they are the same as the 'generate-html' (chunked mode) ones except these additional ones: javahelp.encoding
Example 18. JavaHelp example
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-javahelp</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>article.xml</includes>
</configuration>
</plugin>
</plugins>
</build>
The Eclipse help format allows your documentation to be accessible into the Eclipse platform as a Plugin.
The only operation needed to enable it into Eclipse platform is to create a directory inside the 'plugins' directory of your Eclipse installation using the same name as the 'eclipsePluginId' The help will then be available inside the menu named 'Help contents'
Example 19. Eclipse help example
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-eclipse</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>article.xml</includes>
<eclipsePluginId>docbkx.sample</eclipsePluginId>
</configuration>
</plugin>
</plugins>
</build>
This samples shows you how to use profiling stylesheets (in this case the html one). In order to do this you will have to make an empty (at least) stylesheet customization layer and just point to the profiling stylesheet of the official docbook distribution.
This can be done using something like that:
<xsl:import href="urn:docbkx:stylesheet/profile-docbook.xsl" />
Example 20. Attached to a phase
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-html</goal>
</goals>
<phase>pre-site</phase>
</execution>
</executions>
<configuration>
<includes>profile/*.xml</includes>
<profileStatus>draft</profileStatus>
<htmlCustomization>src/docbkx/profile/profile-docbook-html.xsl</htmlCustomization>
</configuration>
<dependencies>
<dependency>
<groupId>org.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.4</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
This sample shows you how to generate EPub documents verion 2 and version 3(@see http://en.wikipedia.org/wiki/EPUB)
Example 21.
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-epub</goal>
<goal>generate-epub3</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>epubbook/book.001.xml</includes>
<htmlStylesheet>test.css</htmlStylesheet>
<epubEmbeddedFonts>fonts/LeagueScript.otf</epubEmbeddedFonts>
<chunkQuietly>true</chunkQuietly>
<showXslMessages>true</showXslMessages>
<preProcess>
<copy todir="${project.build.directory}/docbkx/epub/epubbook/book.001/covers">
<fileset dir="src/docbkx/epubbook/covers/"/> </copy>
<copy todir="${project.build.directory}/docbkx/epub/epubbook/book.001/fonts">
<fileset dir="src/docbkx/epubbook/fonts/">
<include name="*.otf"/> </fileset>
</copy>
<copy todir="${project.build.directory}/docbkx/epub/epubbook/book.001" file="src/docbkx/epubbook/test.css"></copy>
<copy todir="${project.build.directory}/docbkx/epub3/epubbook/book.001/covers">
<fileset dir="src/docbkx/epubbook/covers/"/> </copy>
<copy todir="${project.build.directory}/docbkx/epub3/epubbook/book.001/fonts">
<fileset dir="src/docbkx/epubbook/fonts/">
<include name="*.otf"/> </fileset>
</copy>
<copy todir="${project.build.directory}/docbkx/epub3/epubbook/book.001" file="src/docbkx/epubbook/test.css"></copy>
</preProcess>
</configuration>
</plugin>
</plugins>
</build>
This sample shows different outputs (here PDF and RTF) based on FO stylesheet
Example 22.
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>generate-rtf</goal>
<goal>generate-pdf</goal>
</goals>
</execution>
</executions>
<configuration>
<highlightSource>1</highlightSource>
<foCustomization>src/docbkx/docbook-fo.xsl</foCustomization>
</configuration>
</plugin>
</plugins>
</build>
This sample shows the webhelp output, a browser and platform independent output with a javascript search engine.
Example 23.
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>webhelpsite/readme.xml</includes>
<webhelpIndexerLanguage>fr</webhelpIndexerLanguage>
<webhelpIncludeSearchTab>1</webhelpIncludeSearchTab>
</configuration>
</plugin>
</plugins>
</build>
This sample shows how to generate titlepage stylesheet that may be needed to customize other outputs, it makes use of an xml input file.
Example 24.
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-template</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>titlepage/titlepage.templates.xml</includes>
</configuration>
</plugin>
</plugins>
</build>
This sample shows how to skip the plugin execution in an easy way. It will likely be used as a command line parameter instead as in the pom definition using '-Ddocbkx.skip=true'.
Example 25.
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<executions>
<execution>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<skip>true</skip>
</configuration>
</plugin>
</plugins>
</build>
This sample shows how to collect xref for cross references to other docbook documents
Example 26.
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>${project.version}</version>
<dependencies>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.0-all</version>
<classifier>resources</classifier>
<type>zip</type>
<scope>runtime</scope>
</dependency>
</dependencies>
<executions>
<execution>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<includes>article.xml</includes>
<collectXrefTargets>yes</collectXrefTargets>
</configuration>
</plugin>
</plugins>
</build>