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 |
---|---|
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.
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.
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 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 |
---|---|
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.
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.
Go to menu
→ → → →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.
You can do this by changing the stylesheet parameters.
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.
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.
Enter the following parameters indicating the font for the body text and for the titles:
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:
Make the transformation again. The characters are now displayed correctly.
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>