#docbook4j

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:

<xsl:import href="res:xsl/docbook/fo/docbook.xsl" />

Docbook4j supports XInclude-s out of the box. Just use an xi:include element in you docbook xml file as usual and you are done:

<?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"> ... <chapter> <title>This is a chapter</title> <xi:include href="section0.inc.xml" /> <xi:include href="section1.inc.xml" /> </chapter> </book>

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();