XSL-FO processors

The <oXygen/> installation package is distributed with the Apache FOP (Formatting Objects Processor) for rendering your XML documents to PDF. FOP is a print and output independent formatter driven by XSL Formatting Objects. FOP is implemented as a Java application that reads a formatting object tree and renders the resulting pages to a specified output.

[Tip]Tip

To include PNG images in the final PDF document you need the JIMI or JAI libraries. For TIFF images you need the JAI library. For PDF images you need the fop-pdf-images library. These libraries are not bundled with <oXygen/> (JIMI and JAI due to Sun's licensing). Using them is as easy as downloading them and creating a external FO processor based on the built-in FOP libraries and the extension library. The external FO processor created in Preferences will have a command line like:

java -cp "${oxygenInstallDir}/lib/xercesImpl.jar:
${oxygenInstallDir}/lib/fop.jar:${oxygenInstallDir}/lib/
avalon-framework-4.2.0.jar:
${oxygenInstallDir}/lib/batik-all-1.7.jar:${oxygenInstallDir}/lib/
commons-io-1.3.1.jar:
${oxygenInstallDir}/lib/xmlgraphics-commons-1.3.1.jar:
${oxygenInstallDir}/lib/commons-logging-1.0.4.jar:
${oxygenInstallDir}/lib/saxon9sa.jar:${oxygenInstallDir}/lib/
saxon9-dom.jar:
${oxygenInstallDir}/lib/xalan.jar:${oxygenInstallDir}/lib/
serializer.jar:
${oxygenInstallDir}/lib/resolver.jar:${oxygenInstallDir}/lib/
fop-pdf-images-1.3.jar:
${oxygenInstallDir}/lib/PDFBox-0.7.3.jar" 
org.apache.fop.cli.Main -fo ${fo} -${method} ${out}

You need to add to the classpath JimiProClasses.zip for JIMI and jai_core.jar, jai_codec.jar and mlibwrapper_jai.jar for JAI. For the JAI package you also need to include the directory containing the native libraries (mlib_jai.dll and mlib_jai_mmx.dll on Windows) in the PATH system variable.

The MacOS X version of the JAI library can be downloaded from http://www.apple.com/downloads/macosx/apple/java3dandjavaadvancedimagingupdate.html. In order to use it, install the downloaded package.

Other FO processors can be configured in the Preferences -> FO Processors panel.

 Add a font to the built-in FOP

If an XML document is transformed to PDF using the built-in Apache FOP processor but it contains some Unicode characters that cannot be rendered by the default PDF fonts then a font that is capable to render these characters must be configured and embedded in the PDF result.

 Locate font

First, you have to find out the name of a font that has the glyphs for the special characters you used. One font that covers the majority of characters, including Japanese, Cyrillic and Greek, is Arial Unicode MS. In the following is described how to embed the true type fonts in the output PDF. Embedding the fonts is necessary to ensure your document is portable.

On Windows the fonts are located into the C:\Windows\Fonts directory. On Mac they are placed in /Library/Fonts. To install a new font on your system is enough to copy it in the Fonts directory.

 Generate font metrics file

Generate a FOP font metrics file from the TrueType font file. This example reads the Windows Arial Unicode MS file and generates an arialuni.xml font metrics file in the current directory. FOP includes an utility application for this task.

I assume you have opened a terminal or command line console and changed the working directory to the oxygen install directory. The FOP files are stored in the lib subdirectory of the Oxygen install directory.

Create the following script file in the Oxygen installation directory. The relative paths specified in the following script file are relative to the Oxygen installation directory so if you decide to create it in other directory you have to adapt the file paths.

For the Mac OS X: ttfConvert.sh

#!/bin/sh 
export LIB=lib
export CMD="java -cp 
"$LIB/fop.jar:$LIB/avalon-framework-4.2.0.jar:$LIB/xercesImpl.jar"
export CMD=$CMD org.apache.fop.fonts.apps.TTFReader" 
export FONT_DIR='/Library/Fonts' 
$CMD $FONT_DIR/Arialuni.ttf Arialuni.xml

For Linux: ttfConvert.sh

#!/bin/sh 
export LIB=lib
export CMD="java -cp 
"$LIB/fop.jar:$LIB/avalon-framework-4.2.0.jar:$LIB/xercesImpl.jar"
export CMD=$CMD org.apache.fop.fonts.apps.TTFReader" 
export FONT_DIR='/Library/Fonts' 
$CMD $FONT_DIR/Arialuni.ttf Arialuni.xml

For Windows: ttfConvert.bat

set LIB=lib
set CMD="java -cp 
"%LIB%\fop.jar;%LIB%\avalon-framework-4.2.0.jar;%LIB%\xercesImpl.jar"
set CMD=%CMD% org.apache.fop.fonts.apps.TTFReader"
set FONT_DIR=C:\Windows\Fonts
%CMD% %FONT_DIR%\Arialuni.ttf Arialuni.xml

The FONT_DIR can be different on your system. Make sure it points to the correct font directory. If java executable is not in the PATH you will have to specify the full path for java.

Execute the script. On Linux and Mac OS X you have to use sh ttfConvert.sh from the command line.

[Note]Note

If Oxygen was installed by an administrator user and now it is used by a standard user who does not have write permission in the Oxygen installation folder (for example on Windows Vista or Linux) then the output location of the font metrics file should be a directory where the user has write permission, for example:

%CMD% %FONT_DIR%\Arialuni.ttf C:\temp_dir\Arialuni.xml

If the font has bold and italic variants, you will have to convert those also. For this you can modify the script, by adding two more lines:

$CMD $FONT_DIR/Arialuni-Bold.ttf Arialuni-Bold.xml
                      $CMD $FONT_DIR/Arialuni-Italic.ttf Arialuni-Italic.xml

In our case the font Arial Unicode MS is not having a Bold and Italic variant, so you will leave the script unchanged.

 Register font to FOP configuration

Create a file and name it for example fopConfiguration.xml.

<fop version="1.0">
  <base>file:/C:/path/to/FOP/font/metrics/files/</base>
  <source-resolution>72</source-resolution>
  <target-resolution>72</target-resolution>
  <default-page-settings height="11in" width="8.26in"/>

  <renderers>
    <renderer mime="application/pdf">
      <filterList>
        <value>flate</value>
      </filterList>
      <fonts>
          <font metrics-url="Arialuni.xml" kerning="yes" 
                embed-url="file:/Library/Fonts/Arialuni.ttf">
              <font-triplet name="Arialuni" style="normal" 
                    weight="normal"/>
          </font>
      </fonts>
    </renderer>
  </renderers>
</fop>
                       

The embed-url attribute points to the TTF file to be embedded. You have to specify it using the URL convention. The metrics-url attribute points to the font metrics file with a path relative to the base element. The triplet refers to the unique combination of name, weight, and style (italic) for each variation of the font. In our case is just one triplet, but if the font had variants, we would have to specify one for each variant. Here is an hypothetic example for the Arial Unicode if it had italic and bold variants:

<fop version="1.0">
  ...
    <fonts>
        <font metrics-url="Arialuni.xml" kerning="yes" 
              embed-url="file:/Library/Fonts/Arialuni.ttf">
            <font-triplet name="Arialuni" style="normal" 
                  weight="normal"/>
        </font>
        <font metrics-url="Arialuni-Bold.xml" kerning="yes" 
              embed-url="file:/Library/Fonts/Arialuni-Bold.ttf">
            <font-triplet name="Arialuni" style="normal" 
                  weight="bold"/>
        </font>
        <font metrics-url="Arialuni-Italic.xml" kerning="yes" 
              embed-url="file:/Library/Fonts/Arialuni-Italic.ttf">
            <font-triplet name="Arialuni" style="italic" 
                  weight="normal"/>
        </font>
    </fonts>
  ...
</fop>
                       

More details about the FOP configuration file are available on http://xmlgraphics.apache.org/fop/0.93/configuration.htmlthe FOP website.

 Set FOP configuration file in Oxygen

Go to menu OptionsPreferencesXMLXSLT / FO / XQueryFO Processors

Click the browse button near Configuration file for the built-in FOP text field and locate the fopConfiguration.xml file.

Click on the OK button to accept the changes.

 Add new font to FO output

You can do this by changing the stylesheet parameters.

 DocBook Stylesheets

Create a transformation scenario that makes use of the docbook.xsl file from the [oXygen-install-dir]/frameworks/docbook/xsl/fo directory. You must do this in the Configure Transformation Scenario dialog.

 

Figure 9.11. The Configure Transformation Scenario dialog

The Configure Transformation Scenario dialog

Also you can use the predefined Docbook PDF scenario which is based on this Docbook stylesheet. Run a test transformation to make sure the PDF is generated. The Unicode characters are not yet displayed correctly. We have to specify to the stylesheet to generate FO output that uses the font Arialuni.

Click on the Parameters button in the transformation scenario edit dialog.

 

Figure 9.12. The Edit Scenario dialog

The Edit Scenario dialog

Enter the following parameters indicating the font for the body text and for the titles:

 

Table 9.1. XSL FO Parameters

NameValue
body.font.familyArialuni
title.font.familyArialuni


 TEI Stylesheets

Create a transformation scenario that makes use of the tei.xsl file from the [oXygen-install-dir]/frameworks/tei/xsl/fo directory. Also you can use the predefined TEI PDF scenario which is based on this XSLT stylesheet. Run a test transformation to make sure the PDF is generated. Just like for the Docbook, we have to specify to the stylesheet to generate FO output that uses the font Arialuni.

Click on the Parameters button of the transformation scenario edit dialog. Enter the following parameters indicating the font for the body text and for other sections:

 

Table 9.2. XSL FO Parameters

NameValue
bodyFontArialuni
sansFontArialuni


Make the transformation again. The characters are now displayed correctly.

 DITA-OT Stylesheets

For setting a font to the Apache FOP processor in the transformation of a DITA map with an IDIOM FOP transformation there are two files that must be modified :

  • font-mappings.xml - available in folder ${frameworks}/dita/DITA-OT/demo/fo/cfg/fo: the font-face element included in each element physical-font having the attribute char-set="default" must contain the name of the font (Arialuni in our example) instead of the default value

  • fop.xconf - available in folder ${frameworks}/dita/DITA-OT/demo/fo/fop/conf: an element font must be inserted in the element fonts which is inside the element renderer having the attribute mime="application/pdf" as in the above fopConfiguration.xml file, for example:

    <renderer mime="application/pdf">
      . . .
       <fonts>
           <font metrics-url="Arialuni.xml" kerning="yes" 
               embed-url="file:/Library/Fonts/Arialuni.ttf">
               <font-triplet name="Arialuni" style="normal" 
                   weight="normal"/>
           </font>
       </fonts>
      . . .
    </renderer>