Rendering docbook documents with docbook4j library
In my spare time i've created a small embeddable java library able to render docbook documents to the well known target output formats like PDF, HTML or RTF.
It can be downloaded here: http://code.google.com/p/docbook4j
Maven users please add following repository and dependency declarations to your POM-File:
This post gives a brief overview how it can be used.
First, depending on what output format you aim to produce, there are 3 possible renderer to use: PDFRenderer, HTMLRenderer and RTFRenderer.
Each renderer requires a Docbook XML resource as input. Optionally you can specify a XSL stylesheet and (only in case of HTMLRenderer) an optional CSS stylesheet to use.
As result each renderer produces an InputStream instance containing generated docbook output in appropriate format.
Note! As resource definition docbook4j supports all filesystem types supported by commons-vfs2 (see http://commons.apache.org/vfs/filesystems.html).
Following few examples demonstrate how docbook4j can be used.
Generate PDF input stream using specified Docbook XML (located within zip archive) and default Docbook XSL:
String xml = "zip:path/to/my/zip/docs.zip!document.xml"; PDFRenderer pdfRenderer = PDFRenderer.create(xml); InputStream in = pdfRenderer.render();
Generate PDF input stream using specified Docbook XML (located within classpath) and custom Docbook XSL (located within external zip archive):
String xml = "res:classpath/to/my/xml/document.xml"; String xsl = = "zip:path/to/my/xsl/zip/xsls.zip!styles.xsl"; PDFRenderer pdfRenderer = PDFRenderer.create(xml, xsl); InputStream in = pdfRenderer.render();
Generate HTML input stream using specified Docbook XML (located in filesystem) and custom CSS:
String xml = "file:///home/someuser/somedir/document.xml"; String css = "file:///home/someuser/somedir/other/my.css"; HTMLRenderer htmlRenderer = HTMLRenderer.create(xml).css(css). InputStream in = htmlRenderer.render();
Additionally some advanced docbook4j features and notes:
While writing a custom Docbook XSL, you usually want to import a default docbook XSL in your stylesheet. With docbook4j just use following xsl import definition:
With docbook4j you are able to use MVEL or OGNL to evaluate dynamic expressions at generation time. Following example gives a brief overview how to use this feature.
Note! To be able to use this feature, you have to add MVEL of OGNL library expicitely to your classpath.
Assume we have some Java Bean defining 3 properties: inceptionYear, name and version:
public class Project { private String inceptionYear; private String version; private String name; // getter / setter goes here }
Furthermore there is a docbook document, referencing this properties via MVEL expressions:
<?xml version="1.0" encoding="UTF-8"?> <book version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:db="http://docbook.org/ns/docbook"> ... <copyright> <year><?mvel project.inceptionYear?></year> <holder>Company Inc. [COMPANY, INC.]. All Rights Reserved.</holder> </copyright> <abstract> <para> This is a documentation example generated with Docbook for project <?mvel project.name?> (v.<?mvel project.version?>). </para> </abstract> ... </book>
To be able to render such a document, we have to specify a variable, that will be used by the appropriate renderer to evaluate the expressions:
Project project = new Project(....); String xml = "...."; // xml document source PDFRenderer renderer = PDFRenderer.create(xml).variable("project", project); InputStream in = renderer.render();
Note! Instead of mvel, you can use ognl keyword like this: <?ognl ....some expression... ?>. This will use OGNL library instead of MVEL to evaluate the expressions.
