Maven and docbook

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.

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 !

I created this blog entry, so do you not loose 2 or 3 days of your life having to deal with xsl, lib, fop version, weird errors, and frustration !

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 @javax.persistence.Table annotation is JPA blabla
	This is the last line: binary field

This is XML with syntax highlighting

<security:anonymous />
<security:http-basic />
<security:logout
	logout-url="/logout.action"
	logout-success-url="/index.action"/>
<security:remember-me user-service-ref="accountDetailsServiceImpl"/>
		

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

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:

How springfuse works

You can use the properties from your pom

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"/>                                       
</fo:block>

Not working

I had to use this notation instead:

<fo:block>
	<fo:external-graphic src="file:src/docbkx/resources/images/logo.png"/>                  
</fo:block>

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.

mvn

You can download this article as a PDF at http://www.springfuse.com/blog/docbook/maven-docbook-syntax-highlighting.pdf