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 special font that is capable to render these characters must be configured and embedded in the PDF result.

Important: If this special font is installed in the operating system, there is a simple way of telling FOP to look for it. See the simplified procedure for adding a font to FOP.

Locate the font.

First, find out the name of a font that has the glyphs for the special characters you used. One font that covers most characters, including Japanese, Cyrillic, and Greek, is Arial Unicode MS.

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 font metrics file from the font file.
1. Open a terminal.
2. Change the working directory to the Oxygen XML Developer install directory.
3. Create the following script file in the Oxygen XML Developer installation directory.
  For Mac OS X and Linux create a file ttfConvert.sh:
```
#!/bin/sh 

export LIB=lib
export CP=$LIB/fop.jar
export CP=$CP:$LIB/avalon-framework-4.2.0.jar
export CP=$CP:$LIB/xercesImpl.jar
export CP=$CP:$LIB/commons-logging-1.1.1.jar
export CP=$CP:$LIB/commons-io-1.3.1.jar
export CP=$CP:$LIB/xmlgraphics-commons-1.5.jar
export CP=$CP:$LIB/xml-apis.jar
export CMD="java -cp $CP org.apache.fop.fonts.apps.TTFReader"
export FONT_DIR='.'

$CMD $FONT_DIR/Arialuni.ttf Arialuni.xml
```
  For Windows create a file ttfConvert.bat:
```
@echo off
set LIB=lib
set CP=%LIB%\fop.jar
set CP=%CP%;%LIB%\avalon-framework-4.2.0.jar
set CP=%CP%;%LIB%\xercesImpl.jar
set CP=%CP%;%LIB%\commons-logging-1.1.1.jar
set CP=%CP%;%LIB%\commons-io-1.3.1.jar
set CP=%CP%;%LIB%\xmlgraphics-commons-1.5.jar
set CP=%CP%;%LIB%\xml-apis.jar
set CMD=java -cp "%CP%" org.apache.fop.fonts.apps.TTFReader
set FONT_DIR=C:\Windows\Fonts
%CMD% %FONT_DIR%\Arialuni.ttf Arialuni.xml
```
  The paths specified in the file are relative to the Oxygen XML Developer installation directory. If you decide to create it in other directory, change the file paths accordingly.
  
  The FONT_DIR can be different on your system. Check that it points to the correct font directory. If the Java executable is not in the PATH, specify the full path of the executable.
  
  If the font has bold and italic variants, convert them too by adding two more lines to the script file:
  - for Mac OS X and Linux:
```
$CMD $FONT_DIR/Arialuni-Bold.ttf Arialuni-Bold.xml
$CMD $FONT_DIR/Arialuni-Italic.ttf Arialuni-Italic.xml
```
  - for Windows:
```
%CMD% %FONT_DIR%\Arialuni-Bold.ttf Arialuni-Bold.xml
%CMD% %FONT_DIR%\Arialuni-Italic.ttf Arialuni-Italic.xml
```
4. Execute the script.
  On Linux and Mac OS X, execute the command sh ttfConvert.sh from the command line. On Windows, run the command ttfConvert.bat from the command line or double click on the file ttfConvert.bat.

Create a FOP configuration file that specifies the font metrics file for your font.

<fop version="1.0">
  <base>./</base>
  <font-base>file:/C:/path/to/FOP/font/metrics/files/</font-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 font file to be embedded. 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, you would have to specify one for each variant. Here is an example for 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 the FOP configuration file in Preferences.
Go to menu Options > Preferences > XML > XSLT/FO/XQuery > FO Processors and enter the path of the FOP configuration file in the Configuration file for the built-in FOP text field.

Set the font on the document content.
This is usually done with XSLT stylesheet parameters and depends on the document type processed by the stylesheet.

For DocBook documents, you can start with the predefined scenario called DocBook PDF, edit the XSLT parameters, and set the font name (in our example Arialuni) to the parameters body.font.family and title.font.family.

For TEI documents, you can start with the predefined scenario called TEI PDF, edit the XSLT parameters, and set the font name (in our example Arialuni) to the parameters bodyFont and sansFont.
For DITA to PDF transformations using DITA-OT modify the following two files:
- ${frameworks}/dita/DITA-OT/plugins/org.dita.pdf2/cfg/fo/font-mappings.xml - 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)
- ${frameworks}/dita/DITA-OT/plugins/org.dita.pdf2/fop/conf/fop.xconf - an element font must be inserted in the element fonts which is inside the element renderer having the attribute mime="application/pdf":
```
<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>
```