Creating PDF documentation with Apache ANT and XHTMLRenderer

Generally I believe that telling developers to write documentation as part of a project requirements is not always the right approach. If a developer is convinced that nobody will actually ever take the effort to read the documentation anyhow, why even bother to tell them otherwise. I think there is a certain pride element that might be overlooked, even though the task itself will not get any less boring of course. What if we would be able to supply the developer with some tooling that takes the documentation they have to create anyhow, and leverage it into nice looking corporate branded PDF files. Creating things of beauty, doesn’t solve the problem, but might appeal to the pride aspect and make it more bearable.

For many projects, and certainly Java projects, it seems default to use tools like XSL-FO and Apache FOP, which are powerful but also complex to use at times.

Since a year or so I therefor turned to the Flying Saucer or XHTMLRenderer project which allows me to create PDF documents out of XHTML + CSS3 syntax. Which makes it both comprehensible for me to generate documentation automatically (through Apache ANT), but also for my fellow front-end developers to chip in and write some documentation as HTML is their second language. (Although I must confess I also ran into the developers who still only want to document in Word as they might not see it as a part of their job to write nice documentation, but only to write some documentation).

/* Main document page style */
@page {
  size: A4;
  font-family: Calibri;
  font-face: Calibri;
  font-size  : 12pt;

  @top-left {
    content: element(company-logo);
    text-align: left;
  }
  @top-right {
    content: element(client-logo);
    text-align: right;
  }
  @bottom-left {
    content: element(footer);
  }
}

A simple drawback from the XHTMLRenderer however is that there is no way of weaving multiple XHTML document with different @Page styles (ie. cover, main document, backcover) into a single PDF file unless you dive into Java or scriptdefs. To work around that problem there is a simple Java class you can compile and use as a TaskDef in ANT.

<xhtml2pdf
    src="${common}/cover.xhtml;${src}/manual.xhtml;${common}/backcover.xhtml"
    dest="${dest}/manual.pdf"
>
    <fonts dir="${doc.src.dir}/common/fonts">
        <include name="**/*.ttf" />
        <include name="**/*.TTF" />
        <include name="**/*.otf" />
    </fonts>
</xhtml2pdf>

The XHtml2PDFTask is available for download. In order to run it you need FlyingSaucer R8 or later from xhtmlrenderer.dev.java.net.

Be Sociable, Share!

Tags: , , , , ,

Leave a Comment

This blog is kept spam free by WP-SpamFree.