Font Support

The following is the initial Font Configuration File. After you have finished XSL Formatter V4.2 installation, this file will be located at [Install directory]/etc. The DTD file font-config.dtd is also located in the same directory.

<?xml version="1.0" encoding="UTF-8" ?>
<!-- DOCTYPE font-config SYSTEM "font-config.dtd" -->
<font-config>
  <font-folder path="[Install directory]/fonts">
    <glyph-list file="ZapfDingbats-glyphname.txt" afm="ZapfDingbats.afm"/>
  </font-folder>
  <!-- add your font folder here -->
  <!-- font-folder path="/home/user-name/fonts" -->
  <!-- /font-folder -->
</font-config>

In XSL Formatter V4.2 Windows version, the following Font Configuration File is installed on [Install directory]. The Windows font directory is set here to [System font directory].

<?xml version="1.0" encoding="UTF-8" ?>
<!-- DOCTYPE font-config SYSTEM "font-config.dtd" -->
<font-config>
  <name-processing-mode mode="windows-name"/>
  <font-folder path="[System font directory]">
  </font-folder>
</font-config>

The following table is a summary of the elements and attributes in the Font Configuration File.

<name-processing-mode mode="windows-name"/>

<font-folder path="/home/user-name/fonts">
  ....
</font-folder>

<glyph-list file="carta.txt" afm="CR______.AFM"/>

<skip-glyphname-mapping afm="CR______.AFM"/>

<font-exclude file="times.ttf"/>

<font-alias file="simsun.ttc" entry="1">
  ....
</font-alias>

<font-alias file="EU______.AFM">
  <alias family-name="Euro" />
</font-alias>
<font-alias file="EUB_____.AFM">
  <alias family-name="Euro" weight="bold" />
</font-alias>

Adobe Type 1 fonts are organized using the following font files.

XSL Formatter V4.2 supports both types of combinations .AFM+.PFB, .PFM+.PFB files. But there are limitations in using .PFM+.PFB file pairs. If you use .AFM files, you can use all of the glyphs defined in .PFB file. In contrast if you use .PFM file, the available glyphs are limited to a maximum 255 due to the current implementation restrictions. We strongly recommend using .AFM+.PFB pairs.

Type 1 font considerations.

• The current version of XSL Formatter V4.2 does not support font outline files with a .PFA (Printer Font ASCII) extension. Most Type1 font products are shipped .PFB format, which is supported by XSL Formatter V4.2.
• Type 1 font metrics data which has the .mmm extension is not supported. This metrics file is used for the Multiple Master Type 1 fonts.

If you want to use Adobe Type 1 fonts, simply specify the font-family, font-weight and font-style property in the FO. The following FO example uses Helvetica for the fo:block.

<fo:block font-family="Helvetica" font-weight="bold" font-style="italic">
  Helvetica (Bold-Italic) will be applied to this text.
</fo:block>

XSL Formatter V4.2 applies the following rules to map font-family, font-weight, font-style to Type 1 fonts. Note that each .AFM and .PFM file has different mapping rules.

Mapping rule in .AFM file

Mapping rule in .PFM file

XSL Formatter V4.2 supports embedding the Type 1 font outlines into PDF files. The followings are required to embed outlines:

• The .AFM+.PFB or .PFM+.PFB font files must be in the folder specified in the <font-folder> of the font configuration file.
• In the Option Setting File specify the target font family name <embed-font> element or specify <pdf-settings embed-all-fonts="true"> entry.

If you do not embed outlines, only .AFM or .PFM files are needed. If fonts are not embedded in the PDF the user will need the actual fonts on their system when they read the PDF file.

To use Adobe Type 1 font with .AFM files, it is important to know how Unicode characters are mapped into Type 1 font glyphs. The following is a brief explanation of how Type 1 fonts are treated in PDF files.

• In the PDF file, letters which are associated with Type 1 fonts are stored using 0..255 value character codes.
• Each Type 1 font in the PDF file has the encoding parameter, which defines the character code to the corresponding glyph-name.
• The PDF reader application (typically Adobe Acrobat reader) converts the character codes to glyph-names using encoding parameters. Then reader then gets the Type 1 glyph outline using the glyph-name as a key index. Finally the glyph is rendered using this outline data.

Example: if the encoding parameter of the Type 1 font is Adobe Standard Encoding, and we want to write a "•" (U+2022 BULLET) to a PDF file, we must select character code 0xB7(183) because the glyph-name of this character is "bullet" and it is defined as 0xB7 in the Adobe Standard Encoding.

Before we can write a character code to the PDF file we must first get the glyph-name from the Unicode. This process is described in the Adobe web site document Unicode and Glyph Names. The most important mapping rule is described in AGL (Adobe Glyph List) file. AGL is a simple text file that defines the Unicode to glyph name mapping rules for over 800 Latin characters. XSL Formatter V4.2 uses this data to map the Unicode to glyph name. Following is a brief description of how XSL Formatter V4.2 maps the Unicode value to glyph name and writes a character code to the PDF file.

• Starting with a Unicode text character in the FO file.
• XSL Formatter V4.2 using the AGL data gets the glyph name from this Unicode character.
• Consulting the .AFM file, determines the encoding parameter for this Type 1 font.
• Also consulting the .AFM file gets the character metrics information and character code from the glyph name.
• Writes the obtained character code and encoding information to the PDF file.

If you are using Adobe Type 1 fonts with .PFM files, XSL Formatter V4.2 maps Unicode to glyphs differently than above, which does not use glyph names.

First, .PFM file has the only one encoding data in the dfCharSet field of PFM header. This one byte field contains the value known as character set. In the Windows environment, there are following character sets are defined in WINGDI.H header file.

Microsoft mapping can be found at the Unicode to code page mapping data. XSL Formatter V4.2 uses this mapping data and converts the Unicode to the character code to write it to the PDF file. This mapping data has a maximum of 256 entries because the code page offers only 8-bit character width. You cannot use glyphs which are not defined in the code page data unless it exists in font the outline data.

As mentioned in Unicode and glyph mapping using the .AFM file, AGL offers the Unicode to glyph name mapping rules. It covers commonly used Latin characters. But there are special fonts which do not fit the AGL. For instance, the Adobe Type 1 product Carta (CR______.AFM, CR______.PFM, CR______.PFB) has 189 pictorial glyphs and non-standard glyph names. If we look up the glyph names into the AGL, we will get the result that only 14-glyph names match and the others do not match with the AGL. If we leave it as it is, we cannot use most of the glyphs in the Carta with the .AFM+.PFB combination.

To solve such problem, XSL Formatter V4.2 offers two solutions. One is to make a glyph list file for this font. Another is to specify the <skip-glyphname-mapping> in the font configuration XML file.

Glyph list file

# Carta sample glyphlist file
# file name:carta-glyphname.txt
0020;space;
E000;circle;
E001;lookoutcontrol;
E002;triangle;
E003;diamond;
E004;hexagon;
E005;explode2;
E006;lookout;
E007;IRBM;
E008;ICBM;
E009;explode1;
E00A;ruin;
E00B;goldbar;
E00C;lighthouse;
E00D;mining;
E00E;gaging;
0030;zero;
0031;one;
0032;two;
0033;three;
0034;four;
0035;five;
0036;six;
0037;seven;
0038;eight;
0039;nine;
E00F;boundary;
...

<font-config>
  <font-folder path="[Install directory]/fonts">
    <glyph-list file="ZapfDingbats-glyphname.txt" afm="ZapfDingbats.afm"/>
  </font-folder>
  <font-folder path="/home/resource/fonts">
    <glyph-list file="carta-glyph-list.txt" afm="CR______.AFM"/>
  </font-folder>
</font-config>

<fo:block font-family="Carta">
&#xE000; &#xE001; &#xE002; &#xE003; &#xE004;
&#xE005; &#xE006; &#xE007; &#xE008; &#xE009;
&#xE00A; &#xE00B; &#xE00C; &#xE00D; &#xE00E;
&#x0030; &#x0031; &#x0032; &#x0033; &#x0034;
&#x0035; &#x0036; &#x0037; &#x0038; &#x0039;
&#xE00F;
</fo:block>

Skipping the glyph name mapping

<font-config>
  <font-folder path="[Install directory]/fonts">
    <glyph-list file="zapfdingbats-glyphname.txt" afm="ZapfDingbats.afm"/>
  </font-folder>
  <font-folder path="/home/resource/fonts">
    <skip-glyphname-mapping afm="CR______.AFM"/>
  </font-folder>
</font-config>

EncodingScheme FontSpecific
StartCharMetrics 189
C 32 ; WX 280 ; N space ; B 0 0 0 0 ;
C 33 ; WX 560 ; N circle ; B 30 150 530 650 ;
C 34 ; WX 620 ; N lookoutcontrol ; B 15 60 605 741 ;
...
C 250 ; WX 1042 ; N boat ; B 30 0 1012 280 ;
C 251 ; WX 852 ; N portofentry ; B 30 123 822 677 ;
C 252 ; WX 946 ; N whwycounty ; B 0 -58 946 857 ;
C 253 ; WX 1154 ; N whwytridown ; B 0 -100 1154 899 ;
C 254 ; WX 1072 ; N whwytriright ; B 0 -121 1073 919 ;
EndCharMetrics

<fo:block font-family="Carta">
&#x0021; &#x0022; &#x0023; &#x0024; &#x0025;
&#x0026; &#x0027; &#x0028; &#x0029; &#x002A;
&#x002B; &#x002C; &#x002D; &#x002E; &#x002F;
&#x0030; &#x0031; &#x0032; &#x0033; &#x0034;
&#x0035; &#x0036; &#x0037; &#x0038; &#x0039;
&#x003A;
</fo:block>

Some Type 1 font family names are troublesome when installed. For instance, if you install Adobe product Eurostile Type 1 font in .AFM+.PFB pair, there occurs a font selection problem depending on the font file combination. The following table describes the font family name problem for some font file combinations.

If you use these fonts with .PFM+.PFB combination, there are no problems because the .PFM file exposes all the different font family names. In contrast, if you install these fonts with .AFM+.PFB combination, all of the font family names are Eurostile only. Furthermore, there are plural fonts that have the same weight value. The Weight value Medium and Roman are interpreted as font-weight="400" and Bold is interpreted as font-weight="700". Therefore the font selection is uncertain when you specify the following description in the FO.

<fo:block font-family="Eurostile">
  It is uncertain which font applies: "Eurostile Medium" or "Eurostile Extended #2"
</fo:block>
<fo:block font-family="Eurostile" font-weight="bold">
  It is uncertain which font applies: "Eurostile Bold" or "Eurostile Bold Extended #2"
</fo:block>

To avoid this problem, define a new family name using the alias element in the font configuration file. The following example defines the .PFM with like family name alias.

<font-config>
  <font-folder path="[Install directory]/fonts">
    <glyph-list file="ZapfDingbats.txt" afm="ZapfDingbats.afm"/>
  </font-folder>
  <font-folder path="/home/resource/fonts">
    <!-- Set the family-name and weight to the PFM definition -->
    <font-alias  file="EU______.AFM">
      <alias family-name="Adobe Eurostile"/>
    </font-alias>
    <font-alias  file="EUB_____.AFM">
      <alias family-name="Adobe Eurostile Bold" weight="normal"/>
    </font-alias>
    <font-alias  file="EUEX____.AFM">
      <alias family-name="Adobe Eurostile ExtendedTwo"/>
    </font-alias>
    <font-alias  file="EUBEX___.AFM">
      <alias family-name="Adobe Eurostile ExtendedTwo" weight="bold"/>
    </font-alias>
  </font-folder>
</font-config>

The alias family name can be used in the FO as follows:

<fo:block font-family="Adobe Eurostile">
  "Eurostile Medium" will be applied to this text.
</fo:block>
<fo:block font-family="Adobe Eurostile Bold">
  "Eurostile Bold" will be applied to this text.
</fo:block>
<fo:block font-family="Adobe Eurostile ExtendedTwo">
  "Eurostile Extended #2" will be applied to this text.
</fo:block>
<fo:block font-family="Adobe Eurostile ExtendedTwo" font-weight="bold">
  "Eurostile Bold Extended #2" will be applied to this text.
</fo:block>

XSL Formatter V4.2 Windows version can print the formatted results without generating a PDF file. Windows functionality is used to do this, thus the font usage is based on Windows. In other words, Windows accesses the fonts using WindowsName in the .PFM file. For this reason, there is a possibility mapping will fail if you use the FamilyName in the .AFM file. This problem can be avoided by specifying <name-processing-mode mode="windows-name"/> in the Font Configuration File. In this case you need to define the alias name for .AFM file because the .AFM file cannot be specified directly.

As a general rule Windows does not normally use/include the .AFM file, so this is not a common problem.

TrueType fonts were originally developed by Apple Computer and have been used in the Windows environment. OpenType fonts were jointly developed by Adobe and Microsoft as cross-platform fonts. Due to the origin, OpenType fonts have two flavors/kinds. One has the TrueType outline. The other has the PostScript outline. OpenType font files that have the TrueType outline have the file extension .TTF or .TTC. OpenType font files that have the PostScript outline have the extension .OTF. This section treats original TrueType fonts and OpenType(TrueType outline) fonts together. From now on, we will use the term TrueType fonts as the contraction of TrueType font and OpenType(TrueType outline).

TrueType fonts are composed of a single file which has the extension .TTF or .TTC. TTC is the abbreviation of the True Type Collection. It contains plural TrueType fonts in a single file structure. It is sometimes used in the CJK fonts.

TrueType font requirements:

• Font must have the cmap table which enables mapping the Unicode to glyph index. (Almost TrueType fonts have the cmap table available.)
• Some older TrueType fonts do not have Code Page information in the OS/2 table (ulCodePageRange1, 2) which can negatively influence XSL Formatter V4.2's font selection algorithms. For this reason we recommend not using old TrueType fonts.

If you want to use TrueType fonts, locate the .TTF (.TTC) files in the directory specified in the <font-folder> element of the font configuration file. Then simply specify the font-family of the targeted font in FO.

<fo:block font-family="Arial" font-weight="bold" font-style="italic">
  If you install arialbi.ttf file,
  TrueType Arial (Bold-Italic) will be applied to this text.
</fo:block>

XSL Formatter V4.2 applies the following rules to map font-family, font-weight, font-style to TrueType fonts.

The information can be found by using Analysis tools for True Type font (TTFdump) provided by Microsoft.
For example, in order to refer to the font family of HG-GothicB, enter fffdump from the command line as follows.

>  ttfdump c:\winnt\fonts\HG-GothicB.ttf

Find the information that corresponds to the above mapping rules from the name table information. The information below maps to HG-GothicB. As Data shows the font family name, the font family name of HG-GothicB is "HGゴシックB".

 9. Platform ID:       3
    Specific ID:       1
    Language ID:       1041
    Name ID:           1
    Length:            14
    Offset:            362
       Data:  0 48  0 47 30 B4 30 B7 30 C3  >  .H.G0ｴ0ｷ0ﾃ
               30 AF  0 42                    >  0ｯ.B

Some fonts have the plural font family name with another Language ID. XSL Formatter V4.2 supports this name for use as the font-family specification. For instance, simsun.ttf has the two family names "SimSun" and "宋体". Both names are valid to use.

XSL Formatter V4.2 supports embedding the TrueType font outline as well as the Type 1 font into the PDF. One big difference is the embedding license. TrueType font has the license information in OS/2 table fsType field. XSL Formatter V4.2 respects this licensing information which will cause embedding errors when you specify font embedding against fonts with restrictions on embedding. In addition, only the used glyphs are embedded with the TrueType fonts.

OpenType (PostScript outline) is one flavor of OpenType fonts as described in Font organization and necessary condition. OpenType (PostScript outline) font files have an extension .OTF and consists of only a single file. In addition, OpenType(PostScript outline) is classified into two categories. One is OpenType (PostScript) CID font and the other is OpenType (PostScript) non-CID font. The following table gives a brief description of these categories.

OpenType is a new format standard requiring no special conditions to use it from XSL Formatter V4.2.

The usage and family-name, font-weight, font-style mapping conditions are the same as for TrueType fonts. Please refer to the Font organization and necessary condition for details.

Some OpenType (PostScript outline) has the font-weight value which is not a multiple of 100. XSL Formatter V4.2 round off the font-weight value.

Font embedding is the same as for TrueType fonts. Please refer to the Embedding TrueType fonts for details.

Some OpenType (PostScript outline) CID fonts have a family name defined per font file. Originally these fonts belonged to the same family and each font file has a different font-weight value.

In the Windows environment it is not allowed to have more than three weight-values in the same family name. (Macintosh does allows such combinations.) As a result, these fonts have different family name per font file. This makes it inconvenient to use these fonts using the different family name. To integrate the family names, the following alias descriptions to the font configuration file should be added.

<font-config>
  <font-folder path="[Install directory]/fonts">
    <glyph-list file="ZapfDingbats.txt" afm="ZapfDingbats.afm"/>
  </font-folder>
  <font-folder path="/home/resource/fonts">
    <!-- Integrate the four OTF font's family name to
         "Heisei Kaku Gothic Std"-->
    <font-alias  file="HeiseiKakuGoStd-W3.otf">
      <alias family-name="Heisei Kaku Gothic Std" weight="300" />
    </font-alias>
    <font-alias  file="HeiseiKakuGoStd-W5.otf">
      <alias family-name="Heisei Kaku Gothic Std" weight="500" />
    </font-alias>
    <font-alias  file="HeiseiKakuGoStd-W7.otf">
      <alias family-name="Heisei Kaku Gothic Std" weight="700" />
    </font-alias>
    <font-alias  file="HeiseiKakuGoStd-W9.otf">
      <alias family-name="Heisei Kaku Gothic Std" weight="900" />
    </font-alias>
  </font-folder>
</font-config>

The alias family name can be used in the FO as follows:

<fo:block font-family="Heisei Kaku Gothic Std" font-weight="300">
  "Heisei Kaku Gothic Std W3" will be applied to this text.
</fo:block>
<fo:block font-family="Heisei Kaku Gothic Std" font-weight="500">
  "Heisei Kaku Gothic Std W5" will be applied to this text.
</fo:block>
<fo:block font-family="Heisei Kaku Gothic Std" font-weight="700">
  "Heisei Kaku Gothic Std W7" will be applied to this text.
</fo:block>
<fo:block font-family="Heisei Kaku Gothic Std" font-weight="900">
  "Heisei Kaku Gothic Std W9" will be applied to this text.
</fo:block>