I was looking for a maven plugin that produces documentation with syntax highlighting from docbook .
This article has been written in docbook , and generated via maven with the docbkx maven plugin .
You can check it out
You can download a ready-to-build maven project here http://www.springfuse.com/blog/docbook/docbook-1.0.0-src.zip . It is ready to be customized for your needs.
We write our documentation for Springfuse and Celerio using docbook .
We used to have an ant build to produce html, html-chunked and pdf out of it. We had an old XSL and had to do many xsl updates (and that was a reaaaaaaal pain)
We wanted to upgrade the xsl and use maven ... and we wanted to have syntax highlighting.
Here at what I looked at for highlighting via xsl :
I looked at these maven plugins :
I could not find something that was suitable.
As I could not find my way, I went to do something I do very frequently : look for what the best teams did. Look in spring code, in hibernate, in drools.
The Spring folks does it the ant way : https://src.springframework.org/svn/spring-build/trunk/project-build/docbook/
![[Note]](images/admons/note.png) | Argh |
|---|---|
No more ant for me :) |
The Jboss guys does it with maven using a specific plugin : http://www.jboss.org/maven-jdocbook-plugin/
None handled syntax highlighting.
Then I stumbled upon http://code.google.com/p/docbkx-tools/ . It looked like very much to what I needed.
I was up to speed very quickly with their documentation http://docbkx-tools.sourceforge.net/docbkx-maven-plugin/plugin-info.html and their examples here
... Until I tried to handle correctly PDF . I am not sure what I did wrong. But many stuff were missing.
By example when I imported my old xsl, and I had this kind of errors :
Embedded error: org.apache.fop.apps.FOPException: null:1:28951: Error(1/28951): No element mapping definition found for (Namespace URI:"http://xml.apache.org/fop/extensions", Local Name: "destination")
I tried many alternatives, tried different FOP version, looked at bugs reports, source code.
I was lost, the html was okay, but pdf would not produce correct results (or no result at all)
While looking for many kind of errors on google, I stumbled on a commit from http://cocoon.apache.org/ . I looked into their source at http://svn.apache.org/repos/asf/cocoon/cocoon3/trunk/ I downloaded it, built it (thank you maven)
Woah : everything I needed was working smoothly !