Configuring Fonts for the Open Toolkit with Apache FOP

While I can’t justify the cost for an expert stylesheet developer or a fancy PDF renderer, I don’t wan’t my PDFs to look like garbage either. Using Jarno Elivirta’s PDF plugin generator is a great place to start for PDF customization, and Apache FOP (bundled with the Open Toolkit) is my only option for a PDF renderer. Once I did a lot of the work in a PDF plugin, I got to the point where I wanted to change fonts. Although despite overuse there’s nothing too offensive about Times New Roman + Arial + Courier, that font set doesn’t conform to any branding guidelines that have been given any thought.

Should be pretty easy to do what I wanted, right?

It took me a while, but after working through an awful lot of instructions that didn’t work I figured it out. Wasting a lot of time was hard. But then when I finally got it, it turned out to be simpler than I expected.

First of all, I just totally failed to change fonts with Open Toolkit 1.5.x. It seems that some changes were made for OT 1.6 that allowed a mere mortal like me to change fonts within a plugin. That is, with OT 1.6 you don’t need to make any changes to fop.xconf, which is where I spent a lot of my wasted time on the path to failure with OT 1.5.x.

The first decision you need to make is which fonts you want to use. Maybe this is common knowledge but it tripped me up: Apache FOP only supports TrueType fonts so you won’t be able to use just any font you have on Windows. Look for C:\Windows\Fonts\*.ttf. You’ll need to use a command-line interface because Windows Explorer won’t show the file extension. Myriad (which DITA for Publishers by Eliot Kimber unfortunately uses as an example) is out; Calibri and Trebuchet are in. You’ll also want a font that contains regular, bold, and italic variants. I had to use Consolas as the fixed-width font instead of Lucida Console as I wanted because my first choice lacks bold and italic styles.

I’m going to use the example of configuring titles to output with Calibri.

First, copy ${dita.dir}/plugins/org.dita.pdf2/cfg/fo/font-mappings.xml to cfg/fo/ in your plugin directory. In this file you have to create a mapping between a logical name and physical name. In the font-mappings/font-table element, create a logical-font element like this:

    <logical-font name="Calibri">
      <physical-font char-set="default">

If you want to have different defaults for logical fonts Sans, Serif, or Monspaced, you can set those in font-mappings.xml also. In some cases the physical font name might be different from the logical font name. For example, the name for Trebuchet to specify inside font-face is “Trebuchet MS”. Again, you can find the correct name by looking in C:\Windows\Fonts.

Next, register the font mappings file with your plugin. Add this line to cfg/catalog.xml:

<uri name="cfg:fo/font-mappings.xml" uri="fo/font-mappings.xml" />

Finally, configure paragraph styles to use the font. In cfg/fo/attrs/custom.xsl, set this attribute in the common.title attribute set:

<xsl:attribute name="font-family">Calibri</xsl:attribute>

That’s it. On your next PDF build you should have Calibri for titles.

4 thoughts on “Configuring Fonts for the Open Toolkit with Apache FOP

  1. This information is great. I was wondering if you have used Apache FOP for processing multiple languages into PDF? In particular, I thought I read somewhere that for non-western languages, particularly Chinese, Korean, Russian, Turkish, that I would need a more robust processor than Apache FOP.. I would need to use the DITA OT plus RenderX or Antenna House processor. In addition, we are looking at replacing our frutiger fonts with a standard font that accommodates 508 compliant PDF output. Knowing that I need to upgrade to DITA OT 1.6 before I even explore using the DITA OT for PDF output is a huge help. I’m currently using DITA OT 1.5.4 to produce html help.


    • I have not done any multi-language output. Unfortunately the Apache FOP documentation is generally impenetrable, and I didn’t see anything about language support. While I think that it’s good to be able to do basic configuration oneself, creating stylesheets and a publishing process for multiple languages sounds like something you might want to engage a consultant for.

  2. Thank’s for helping to sort out what seemed like a simple task. I want to add that for some (True Type) fonts, it looks like their name ends with “Normal”, but it seems that that part should not be included. On my Windows installation, I see “Planet Benson 2 Normal” as a font in my Fonts folder, but had to specify “Planet Benson 2” only for it to work. Also the names listed in the CLI are not the ones to use.

Leave a Reply

Your email address will not be published. Required fields are marked *