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]](http://www.springfuse.com/documentation/springfuse/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 !
Here is a java example with syntax highlighting
@Entity @Table(name = "ATTACHMENT") @Cache(usage=CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) public class Attachment implements Comparable<Attachment>, Serializable { static final private long serialVersionUID = 1L; static final private Log logger = LogFactory.getLog(Attachment.class); // Raw Properties private String key; private String contentType; private byte[] binary; ... }
This is a java example with syntax highlighting and callouts
@Entity@Table(name = "ATTACHMENT") @Cache(usage=CacheConcurrencyStrategy.NONSTRICT_READ_WRITE) public class Attachment implements Comparable<Attachment>, Serializable { static final private long serialVersionUID = 1L; static final private Log logger = LogFactory.getLog(Attachment.class); // Raw Properties private String key; private String contentType; private byte[] binary;
|
The
|
| This is the last line: binary field |
I added the most used docbook commands, check out these sites to learn some more:
You can specify commands like this :
<command>javac –version</command>
The output: javac –version
You can specify output like this :
<screen>screen output</screen>
The output:
c:\tutorial\springfuse-example>mvn initialize
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building springfuse-example
[INFO] task-segment: [initialize]
[INFO] ------------------------------------------------------------------------
[INFO] [sql:execute {execution: Create and initialize the database}]
[INFO] Executing file: c:\tutorial\springfuse-example\src\main\sql\h2\drop.sql
[INFO] Executing file: c:\tutorial\springfuse-example\src\main\sql\h2\create.sql
[INFO] Executing file: c:\tutorial\springfuse-example\src\main\sql\h2\comment.sql
[INFO] Executing file: c:\tutorial\springfuse-example\src\main\sql\h2\init.sql
[INFO] 45 of 45 SQL statements executed successfully
[INFO] [springfuse:extract {execution: Extract database Meta Data}]
[INFO] Ready to extract the database schema
[INFO] Connecting to database jdbcUrl=jdbc:h2:~/.h2/quickstartdb
[INFO] Connected OK
[INFO] database Product Name: H2
[INFO] database schema extracted
[INFO] File data-model.springfuse passed reverse conversion OK
[INFO] File data-model.springfuse created successfully
[INFO] You are now ready to upload data-model.springfuse to http://www.springfuse.com/
and generate your project!
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jan 27 16:10:07 CET 2009
[INFO] Final Memory: 4M/8M
[INFO] ------------------------------------------------------------------------
You can specify filenames like this :
<filename>src/main/generated-java/com/springfuse/example/model/Account.java</filename>
The output:
src/main/generated-java/com/springfuse/example/model/Account.java
You can specify classname like this :
<classname>GenericDaoService</classname>
The output:
GenericDaoService
You can specify literals like this :
<literal>jdbc.driver</literal>
The output:
jdbc.driver
You can set lists like this
<itemizedlist> <listitem><para>Spring Core</para></listitem> <listitem><para>Spring MVC</para></listitem> <listitem><para>Spring Security</para></listitem> <listitem><para>Spring Integration</para></listitem> <listitem><para>Spring Web Flow</para></listitem> </itemizedlist>
The output
Spring Core
Spring MVC
Spring Security
Spring Integration
Spring Web Flow
You can add images like this
<mediaobject> <imageobject> <imagedata fileref="images/how-springfuse-works.png" align="center" /> </imageobject> <caption>How springfuse works</caption> </mediaobject>
The output:
For some reason the latest version (
2.0.9
) of the plugin produces :
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 had to rely on version
2.0.8
this sole behavior stole hours from me.
I also could not add an image in the
fopdf.xsl
on the cover page.
<fo:block> <fo:external-graphic src="file:images/logo.png"/>
| Not working |
I had to use this notation instead:
<fo:block> <fo:external-graphic src="file:src/docbkx/resources/images/logo.png"/>
| Working |
Even if this kind of bug seems obvious, it was not that easy to find when mixed between version problems, dependency hell, syntaxic errors etc.
Anyway, hopefully this will help you to build great looking documentation.
Docbkx is the right tool for the job. When correctly setup, it works like a charm.
You can download this maven project and build it by yourself here: http://www.springfuse.com/blog/docbook/docbook-1.0.0-src.zip
To produce image in PDF I found the solution reading Open JPA : FOP needs the JAI jars, unfortunately they are not in the central maven repository.
You need to install manually the Java Advanced Imaging framework .
Download the release at http://download.java.net/media/jai/builds/release/1_1_3/jai-1_1_3-lib.zip
Unzip
Install both jar locally in your repository by executing
mvn install:install-file -Dfile=jai-1_1_3\lib\jai_core.jar -DgroupId=javax.media -DartifactId=jai-core -Dversion=1.1.3 -Dpackaging=jar
and
mvn install:install-file -Dfile=jai-1_1_3\lib\jai_codec.jar -DgroupId=javax.media -DartifactId=jai-codec -Dversion=1.1.3 -Dpackaging=jar
I created the
install
maven profile: it will download the file for you and unzip it in
target/
.
Just execute
mvn -Pinstall initialize
Then in
targetexecuteinstall.(bat|sh)
After that you have the jars in your local repository,you can re-execute the maven command:
mvn
to produce the documentation
You can download this article as a PDF at http://www.springfuse.com/blog/docbook/maven-docbook-syntax-highlighting.pdf
As you can see most of the tests fail. The following logical identity test is not satisfied as you can expect.
Almost all the tests pass now, except the one below:
All the tests pass now :-)