DocBook, FOP and Fonts

I’m proud to say that – during the six years of employment at the company formerly known as Sun Microsystems – I wrote all my documents in DocBook. Of course there was the occasional warning that we were all expected to use StarOffice, but by making sure the DocBook generated output resembled the printed material produced by HQ, it never turned into a big argument. And since my entire DocBook chain was built from open source, I had to use Apache FOP.

Apache FOP has a long history. For some reason, it seems impossible to ever arrive at a version 1.0. The versions I used at Sun unfortunately never supported the keep-with-next poperty, which resulted in weird page-endings, that I then had to manually fix. However, that has been solved with the latest versions, and I think the output generated by the DocBook stylesheets can be quite ok.

That is, if you customize them. And while customizing, you also might want to use other fonts than the standard fonts. However, if you are using Apache FOP, then simply referencing alternative fonts is not going to get you anywhere. You also need to make sure the font metrics can be found. And if you don’t have these font metrics files yet, you first have to generate them.

Apache FOP is providing some utilities for generating font metrics, however none of that is based on Maven. If you are using the Maven Docbkx Plugin, then you might want something that integrates with Maven. Last weekend I realized that – although the Maven Docbkx Plugin supports something like that – it is probably one of its best kept secrets.

So, this is the way you use it.

Add a plugin

First of all, you need to add a plugin to the plugins section.

<plugin>
  <groupId>com.agilejava.docbkx</groupId>
  <artifactId>docbkx-fop-support</artifactId>
  <executions>
    <execution>
      <phase>pre-site</phase>
      <goals>
        <goal>generate</goal>
      </goals>
      <configuration>
        <ansi>true</ansi>
        <sourceDirectory>...</sourceDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>

The sourceDirectory parameter is pointing to a directory containing the .ttf files. To be perfectly honest, I don’t remember exactly what the ansi parameter was about, but AFAIR, it had something to do with being able to search the documents. (Huge disclaimer: it may be about something completely different. Feel free to plough through the FOP documentation to understand what it is about.)

As I said, the font metrics files are required to get something done. However, just generating the files is not going to make a huge difference. In order to reap the benefits from these metrics files, you will need to tell the Maven Docbkx Plugin what to do with it.

The first thing you should do is add some font metadata to the Maven Docbkx Plugin’s configuration:

<fonts>
<font>
  <name>Calibri</name>
  <style>normal</style>
  <weight>normal</weight>
  <embedFile>${fonts.dir}/calibri.ttf</embedFile>
  <metricsFile>${basedir}/target/fonts/calibri-metrics.xml</metricsFile>
</font>
</fonts>

This should be enough to make the plugin aware of the existence of this font, and to have a way resolve its name to the required meta data. With this in place, making the plugin use this font is pretty easy. You can use the fonts name in all places where the stylesheets are referring to a font name. So the below will change the body font to Calibri.

<bodyFontFamily>Calibri</bodyFontFamily>