We are using DocBook for writing technical documentation for all our projects and in-house frameworks. We are actually quite happy with this approach, especially because we are able to automatically publish the docs in a number of formats, including HTML and PDF. To do so, we use the docbkx-maven-plugin in the project's nightly build.
So, all has been in best order... until I decided to upgrade this docbkx-maven-plugin from version 2.0.8 to current version 2.0.11 (due to some issues we had). After doing so, the document conversion issues an error which breaks the build:
[ERROR] Failed to execute goal com.agilejava.docbkx:docbkx-maven-plugin:2.0.11:generate-pdf (pdf) on project builddoc-ma
ven-plugin: Failed to transform to PDF: org.apache.fop.fo.ValidationException: null:30:723: Error(30/723): fo:table-body
is missing child elements.
[ERROR] Required Content Model: marker* (table-row+|table-cell+)
Well, this is somewhat unexpected because I didn't change anything but the plugin version, and I don't see any reason it could not work as before. In particular, we are still using the same docbook version in our POM. Here is the relevant snippet:
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.11</version>
<dependencies>
<!-- the DocBook XML DTD and catalog files (see http://www.oasis-open.org/docbook) -->
<dependency>
<groupId>org.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>4.4</version>
<scope>runtime</scope>
</dependency>
</dependencies>
<executions>
<execution>
<id>pdf</id>
<goals>
<goal>generate-pdf</goal>
</goals>
<phase>post-site</phase>
<configuration>
...
</configuration>
</execution>
...
</executions>
<configuration>
<htmlStylesheet>css/html.css</htmlStylesheet>
<htmlCustomization>${basedir}/src/doc/xsl/html_chunk_customization.xsl</htmlCustomization>
<foCustomization>${basedir}/src/doc/xsl/fopdf_customization.xsl</foCustomization>
...
</configuration>
</plugin>
It's important to understand that we are using the advanced customizing capabilities of DocBook, i.e. we customized the stylesheets used for rendering HTML and PDF. The created custom stylesheets contain an import to urn:docbkx:stylesheet, and in the Maven POM the htmlCustomization and foCustomization properties point to those custom stylesheets. This is how it's supposed to be, and this is how it worked all along.
I found out that the error message is correct when building with plugin version greater than 2.0.8, since the for-each element indeed does not return any element which results in an empty fo:table-body. In fact, none of the xsl:value-of in our customized stylesheet returned any value any more....
So here is why: since docbkx-maven-plugin version 2.0.9, the plugin is using namespaced stylesheets. That is, we must use a namespace in our custom stylesheet to be able to select any docbook element! See this or this post for related comments.
Thus, all I have to do is to add the docbook namespace declaration at the top and add the docbook namespace prefix to all references to element names in my customization layer. See highlighted lines in this XSL snippet:
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:db="http://docbook.org/ns/docbook"
exclude-result-prefixes="date"
version="1.0">
<xsl:template name="book.titlepage.separator">
<fo:block>
<fo:table table-layout="fixed" width="163mm">
...
<fo:table-body text-align="left">
<xsl:for-each select="/db:book/db:bookinfo/db:revhistory/db:revision">
...
</xsl:for-each>
</fo:table-body>
</fo:table>
</fo:block>
</xsl:template>
...
</xsl:stylesheet>
Well, that did the trick – after spending a couple of hours of investigation... I think that issue should be clearly noted with the docbkx-maven-plugin Maven plugin, because in the end it is an incompatability between versions 2.0.8 and 2.0.9. Alas, I did not find this information on the plugin's Changes Report page. At least, nothing that pointed me (not being a DocBook expert) into this direction... :-(
