Man page 1 : ttf2tfm

ttf2tfm - build TeX metric files from a TrueType font

.na

ttf2tfm 'in +\n(.ku ttffile [ .ttf | .ttc ] [\c -c  caps-height-factor\c ] [\c -e  extension-factor\c ] [\c -E  encoding-id\c ] [\c -f  font-index\c ] [\c

-l\c ] [\c

-L \c ligature-file [ .sfd ]\c ] [\c

-n\c ] [\c

-N\c ] [\c

-O\c ] [\c

-p \c inencfile [ .enc ]\c ] [\c -P  platform-id\c ] [\c

-q\c ] [\c -r  old-glyphname new-glyphname\c ] [\c

-R \c replacement-file [ .rpl ]\c ] [\c -s  slant-factor\c ] [\c

-t \c outencfile [ .enc ]\c ] [\c

-T \c inoutencfile [ .enc ]\c ] [\c

-u\c ] [\c

-v \c vplfile [ .vpl ]\c ] [\c

-V \c scvplfile [ .vpl ]\c ] [\c

-w\c ] [\c

-x\c ] [\c -y  vertical-shift-factor\c ] [\c tfmfile [ .tfm ]\c ]

ttf2tfm --version |

--help . . . . . .ie '\*(.T'dvi' \ . . .ie '\*(.T'dvi' .ds LE \*(LX\h'0.15m'2\v'0.20v'\f(MI\N'34'\fP\v'-0.20v' . . . . . . . .

This program extracts the metric and kerning information of a TrueType font and converts it into metric files usable by \*(TX (quite similar to

afm2tfm which is part of the

dvips package; please consult its info files for more details on the various parameters (especially encoding files).

Since a TrueType font often contains more than 256 glyphs, some means are necessary to map a subset of the TrueType glyphs onto a \*(TX font. To do this, two mapping tables are needed: the first (called `input' or `raw' encoding) maps the TrueType font to a raw \*(TX font (this mapping table is used by both

ttf2tfm and

R ttf2pk ), and the second (called `output' or `virtual' encoding) maps the raw \*(TX font to another (virtual) \*(TX font, providing all kerning and ligature information needed by \*(TX.

This two stage mapping has the advantage that one raw font can be accessed with various \*(LX encodings (e.g. T1 and OT1) via the virtual font mechanism, and just one .C PK file is necessary.

For CJKV (Chinese/Japanese/Korean/old Vietnamese) fonts, a different mechanism is provided (see

SUBFONT DEFINITION FILES below). . .

Most of the command line switch names are the same as in

afm2tfm for convenience. One or more space characters between an option and its value is mandatory; options can't be concatenated. For historical reasons, the first parameter can notbe a switch but must be the font name.

• -c  caps-height-factor
      The height of small caps made with the

-V switch. Default value of this real number is 0.8 times the height of uppercase glyphs.

Will be ignored in subfont mode.

• -e  extension-factor
      The extension factor to stretch the characters horizontally. Default value of this real number is 1.0; if less than 1.0, you get a condensed font.
• -E  encoding-id
      The TrueType encoding ID. Default value of this non-negative integer is 1.

Will be ignored if

-N is used.

• -f  font-index
      The font index in a TrueType Collection. Default is the first font (index 0). [TrueType collections are usually found in some CJK fonts; e.g. the first font index specifies glyphs and metrics for horizontal writing, and the second font index does the same for vertical writing. TrueType collections usually have the extension `\c .C .ttc '.]

Will be ignored for ordinary TrueType fonts.

-l

    Create ligatures in subfonts between first and second bytes of all the original character codes. Example: Character code 0xABCD maps to character position 123 in subfont 45. Then a ligature in subfont 45 between position 0xAB and 0xCD pointing to character 123 will be produced. The fonts of the Korean H\*(LX package use this feature. Note that this option generates correct ligatures only for TrueType fonts where the input cmap is identical to the output encoding. In case of H\*(LX, TTFs must have platform ID 3 and encoding ID 5.

Will be ignored if not in subfont mode.

• -L  ligature-file
      Same as

R -l , but character codes for ligatures are specified in ligature-file . For example, `\c .C -L KS-HLaTeX ' generates correct ligatures for the Korean H\*(LX package regardless of the platform and encoding ID of the used TrueType font (the file .C KS-HLaTeX.sfd is part of the ttf2pk package).

Ligature files have the same format and extension as .C SFD files. This option will be ignored if not in subfont mode.

-n

    Use PS names (of glyphs) of the TrueType font. Only glyphs with a valid entry in the selected cmap are used.

Will be ignored in subfont mode.

-N

    Use only PS names of the TrueType font. No cmap is used, thus the switches

-E and

-P have no effect, causing a warning message.

Will be ignored in subfont mode.

-O

    Use octal values for all character codes in the .C VPL file rather than names; this is useful for symbol or CJK fonts where character names such as `A' are meaningless.

• -p  inencfile
      The input encoding file name for the TTF(->raw \*(TX mapping. This parameter has to be specified in a map file (default: .C ttfonts.map ) recorded in .C ttf2pk.cfg for successive

ttf2pk calls.

Will be ignored in subfont mode.

• -P  platform-id
      The TrueType platform ID. Default value of this non-negative integer is 3.

Will be ignored if

-N is used.

-q

    Make

ttf2tfm quiet. It suppresses any informational output except warning and error messages. For CJK fonts, the output can get quite large if you don't specify this switch.

• -r  old-glyphname new-glyphname
      Replaces old-glyphnamewith new-glyphname . This switch is useful if you want to give an unnamed glyph (i.e., a glyph which can be represented with `.gXXX' or `.cXXX' only) a name or if you want to rename an already existing glyph name. You can't use the `.gXXX' or `.cXXX' glyph name constructs for new-glyphname ; multiple occurrences of

-r are possible.

If in subfont mode or if no encoding file is specified, this switch is ignored.

• -R  replacement-file
      Use this switch if you have many replacement pairs; they can be collected in a file which should have `\c .C .rpl ' as extension. The syntax used in such replacement files is simple: Each non-empty line must contain a pair `\c "old-glyphname new-glyphname" ' separated by whitespace (without the quotation marks). A percent sign starts a line comment; you can continue a line on the next line with a backslash as the last character.

If in subfont mode or if no encoding file is specified, this switch is ignored.

• -s  slant-factor
      The obliqueness factor to slant the font, usually much smaller than 1. Default of this real number is 0.0; if the value is larger than zero, the characters slope to the right, otherwise to the left.
• -t  outencfile
      The output encoding file name for the virtual font(s). Only characters in the raw \*(TX font are used.

Will be ignored in subfont mode.

• -T  inoutencfile
      This is equivalent to ` -p inoutencfile

-t inoutencfile '.

Will be ignored in subfont mode.

-u

    Use only those characters specified in the output encoding, and no others. By default,

ttf2tfm tries to include all characters in the virtual font, even those not present in the encoding for the virtual font (it puts them into otherwise-unused positions, rather arbitrarily).

Will be ignored in subfont mode.

• -v  vplfile
      Output a .C VPL file in addition to the .C TFM file. If no output encoding file is specified,

ttf2tfm uses a default font encoding (cmtt10).

Note: Be careful to use different names for the virtual font and the raw font!

Will be ignored in subfont mode.

• -V  scvplfile
      Same as

R -v , but the virtual font generated is a pseudo small caps font obtained by scaling uppercase letters by 0.8 (resp. the value specified with

R -c ) to typeset lowercase. This font handles accented letters and retains proper kerning.

Will be ignored in subfont mode.

-w

    Generate PostScript encoding vectors containing glyph indices, primarily used to embed TrueType fonts in pdf\*(TX.

ttf2tfm takes the .C TFM names and replaces the suffix with .C .enc ; that is, for files .C foo01.tfm , .C foo02.tfm , . . . it creates .C foo01.enc , .C foo02.enc , . . .  at the same place.

Will be ignored if not in subfont mode.

-x

    Rotate all glyphs by 90 degrees counter-clockwise. If no

-y parameter is given, the rotated glyphs are shifted down vertically by 0.25em.

Will be ignored if not in subfont mode.

• -y  vertical-shift-factor
      Shift down rotated glyphs by the given amount (the unit is em ).

Ignored if not in subfont mode or glyphs are not rotated.

--version

    Shows the current version of

ttf2tfm and the used file search library (e.g.

R kpathsea ).

--help

    Shows usage information.

If no .C TFM file name is given, the name of the .C TTF file is used, including the full path and replacing the extension with `\c .C .tfm '. . .

Contrary to Type 1 PostScript fonts (but similar to the new CID PostScript font format), most TrueType fonts have more than one native mapping table, also called `cmap', which maps the (internal) TTF glyph indices to the (external) TTF character codes. Common examples are a mapping table to Unicode encoded character positions, and the standard Macintosh mapping. To specify a TrueType mapping table, use the options

-P and

R -E . With

-P you specify the platform ID; defined values are:

3iC "platform platform ID (pid)"

3iR Apple Unicode 0
Macintosh 1
ISO 2
Microsoft 3

The encoding ID depends on the platform. For pid=0, we ignore the

-E parameter (setting it to zero) since the mapping table is always Unicode version 2.0. For pid=1, the following table lists the defined values:

3iC platform ID = 1

"script encoding ID (eid)"

3iR Roman 0
Japanese 1
Chinese 2
Korean 3
Arabic 4
Hebrew 5
Greek 6
Russian 7
Roman Symbol 8
Devanagari 9
Gurmukhi 10
Gujarati 11
Oriya 12
Bengali 13
Tamil 14
Telugu 15
Kannada 16
Malayalam 17
Sinhalese 18
Burmese 19
Khmer 20
Thai 21
Laotian 22
Georgian 23
Armenian 24
Maldivian 25
Tibetan 26
Mongolian 27
Geez 28
Slavic 29
Vietnamese 30
Sindhi 31
Uninterpreted 32

Here are the ISO encoding IDs:

3iC platform ID = 2

"encoding encoding ID (eid)"

3iR ASCII 0
ISO 10646 1
ISO 8859-1 2

And finally, the Microsoft encoding IDs:

3iC platform ID = 3

"encoding encoding ID (eid)"

3iR Symbol 0
Unicode 2.0 1
Shift JIS 2
GB 2312 (1980) 3
Big 5 4
KS X 1001 (Wansung) 5
KS X 1001 (Johab) 6
UCS-4 10

The program will abort if you specify an invalid platform/encoding ID pair. It will then show the possible pid/eid pairs. Please note that most fonts have at most two or three cmaps, usually corresponding to the pid/eid pairs (1,0), (3,0), or (3,1) in case of Latin based fonts. Valid Microsoft fonts should have a (3,1) mapping table, but some fonts exist (mostly Asian fonts) which have a (3,1) cmap not encoded in Unicode. The reason for this strange behavior is the fact that some old MS Windows versions will reject fonts having a non-(3,1) cmap (since all non-Unicode Microsoft encoding IDs are for Asian MS Windows versions).

The

-P and

-E options of

ttf2tfm must be equally specified for

R ttf2pk ; the corresponding parameters in a map file are `Pid' and `Eid', respectively.

The default pid/eid pair is (3,1).

Similarly, an

-f option must be specified as `Fontindex' parameter in a map file.

If you use the

-N switch, all cmaps are ignored, using only the PostScript names in the TrueType font. The corresponding option in a map file is `PS=Only'. If you use the

-n switch, the default glyph names built into

ttf2tfm are replaced with the PS glyph names found in the font. In many cases this is not what you want because the glyph names in the font are often incorrect or non-standard. The corresponding option in a map file is `PS=Yes'.

Single replacement glyph names specified with

-r must be given directly as `\c "old-glyphname new-glyphname" ' in a map file;

-R is equivalent to the `Replacement' option. . .

You must specify the encoding vectors from the TrueType font to the raw \*(TX font and from the raw \*(TX font to the virtual \*(TX font exactly as with

R afm2tfm , but you have more possibilities to address the character codes. [With `encoding vector' a mapping table with 256 entries in form of a PostScript vector is meant; see the file .C T1-WGL4.enc of this package for an example.] With

R afm2tfm , you must access each glyph with its Adobe glyph name, e.g. \c `/quotedsingle' or `/Acircumflex'. This has been extended with

R ttf2tfm ; now you can (and sometimes must) access the code points and/or glyphs directly, using the following syntax for specifying the character position in decimal, octal, or hexadecimal notation: `/.c\c <decimal-number> ', `/.c0\c <octal-number> ', or `/.c0x\c <hexadecimal-number> '. Examples: `/.c72', `/.c0646', `/.c0x48'. To access a glyph index directly, use the character `g' instead of `c' in the just introduced notation. Example: `/.g0x32'. [Note: The `.cXXX' notation makes no sense if

-N is used.]

For pid/eid pairs (1,0) and (3,1), both

ttf2tfm and

ttf2pk recognize built-in default Adobe glyph names; the former follows the names given in Appendix E of the book `Inside Macintosh', volume 6, the latter uses the names given in the TrueType Specification (WGL4, a Unicode subset). Note that Adobe names for a given glyph are often not unique and do sometimes differ, e.g., many PS fonts have the glyph `mu', whereas this glyph is called `mu1' in the WGL4 character set to distinguish it from the real Greek letter mu. Be also aware that OpenType (i.e. TrueType 2.0) fonts use an updated WGL4 table; we use the data from the latest published TrueType specification (1.66). You can find those mapping tables in the source code file .C ttfenc.c .

On the other hand, the switches

-n and

-N makes

ttf2tfm read in and use the PostScript names in the TrueType font itself (stored in the `post' table) instead of the default Adobe glyph names.

Use the

-r switch to remap single glyph names and

-R to specify a file containing replacement glyph name pairs.

If you don't select an input encoding, the first 256 glyphs of the TrueType font with a valid entry in the selected cmap will be mapped to the \*(TX raw font (without the

-q option,

ttf2tfm prints this mapping table to standard output), followed by all glyphs not yet addressed in the selected cmap. However, some code points for the (1,0) pid/eid pair are omitted since they do not represent glyphs useful for \*(TX: 0x00 (null), 0x08 (backspace), 0x09 (horizontal tabulation), 0x0d (carriage return), and 0x1d (group separator). The `invalid character' with glyph index 0 will be omitted too.

If you select the

-N switch, the first 256 glyphs of the TrueType font with a valid PostScript name will be used in case no input encoding is specified. Again, some glyphs are omitted: `.notdef', `.null', and `nonmarkingreturn'.

If you don't select an output encoding,

ttf2tfm uses the same mapping table as

afm2tfm would use (you can find it in the source code file .C texenc.c ); it corresponds to \*(TX typewriter text. Unused positions (either caused by empty code points in the mapping table or missing glyphs in the TrueType font) will be filled (rather arbitrarily) with characters present in the input encoding but not specified in the output encoding (without the

-q option

ttf2tfm prints the final output encoding to standard output). Use the

-u option if you want only glyphs in the virtual font which are defined in the output encoding file, and nothing more.

One feature missing in

afm2tfm has been added which is needed by \*(LX's T1 encoding:

ttf2tfm will construct the glyph `Germandbls' (by simply concatenating two `S' glyphs) even for normal fonts if possible. It appears in the glyph list as the last item, marked with an asterisk. Since this isn't a real glyph it will be available only in the virtual font.

For both input and output encoding, an empty code position is represented by the glyph name `/.notdef'.

In encoding files, you can use `\\' as the final character of a line to indicate that the input is continued on the next line. The backslash and the following newline character will be removed.

. .

CJKV (Chinese/Japanese/Korean/old Vietnamese) fonts usually contain several thousand glyphs; to use them with \*(TX it is necessary to split such large fonts into subfonts. Subfont definition files (usually having the extension `\c .C .sfd ') are a simple means to do this smoothly.

A subfont file name usually consists of a prefix, a subfont infix, and a postfix (which is empty in most cases), e.g.

ntukai23 (-> prefix: ntukai, infix: 23, postfix: (empty)

Here the syntax of a line in an .C SFD file, describing one subfont:

• <whitespace> <infix> <whitespace> <ranges> <whitespace>
      
  
  
• <infix>  :=
      anything except whitespace. It is best to use only alphanumerical characters.
• <whitespace>  :=
      space, formfeed, carriage return, horizontal and vertical tabs -- no newline characters.
• <ranges>  :=
       "<ranges> <whitespace> <codepoint>"  |
  "<ranges> <whitespace> <range>"  |
  <ranges> <whitespace> <offset> <whitespace> <range>
• <codepoint>  :=
      .I <number>
  
• <range>  :=
       <number>  `_'  <number>
  
• <offset>  :=
       <number>  `:'
• <number>  :=
      hexadecimal (prefix `0x'), decimal, or octal (prefix `0')

A line can be continued on the next line with a backslash ending the line. The ranges must not overlap; offsets have to be in the range 0-255.

Example:

The line

.C "03 10: 0x2349 0x2345_0x2347"

assigns to the code positions 10, 11, 12, and 13 of the subfont having the infix `03' the character codes 0x2349, 0x2345, 0x2346, and 0x2347 respectively.

The .C SFD files in the distribution are customized for the CJK package for \*(LX.

You have to embed the .C SFD file name into the .C TFM font name (at the place where the infix will appear) surrounded by two signs, on the command line resp. a map file; both

ttf2tfm and

ttf2pk switch then to subfont mode.

It is possible to use more than a single .C SFD file by separating them with commata and no whitespace; for a given subfont, the first file is scanned for an entry, then the next file, and so on. Later entries override entries found earlier (possibly only partially). For example, the first .C SFD file sets up range 0x10-0xA0, and the next one modifies entries 0x12 and 0x25. As can be easily seen, this algorithm allows for adding and replacing, but not for removing entries.

Subfont mode disables the options

R -n ,  -N ,  -p ,

R -r ,  -R ,  -t ,

R -T ,  -u ,  -v ,  -V and

-w for

R ttf2tfm ; similarly, no `Encoding' or `Replacement' parameter is allowed in a map file. Single replacement glyph names are ignored too.

ttf2tfm will create all subfont .C TFM files specified in the .C SFD files (provided the subfont contains glyphs) in one run.

Example:

The call

.C "ttf2tfm ntukai.ttf ,Big5-supp@"

will use .C Big5.sfd and .C Big5-supp.sfd , producing allsubfont files .C ntukai01.tfm , .C ntukai02.tfm , etc. . .

ttf2tfm returns 0 on success and 1 on error; warning and error messages are written to standard error. . .

Both

ttf2pk and

ttf2tfm use either the

R kpathsea ,

R emtexdir , or

MiK\*(TX library for searching files ( emtexdir will work only on operating systems which have an MS-DOSish background, i.e. MS-DOS, OS/2, Windows;

Mik\*(TX is specific to MS Windows).

As a last resort, both programs can be compiled without a search library; the searched files must be then in the current directory or specified with a path. Default extensions will be appended also (with the exception that only `\c .C .ttf ' is appended and not `\c .C .ttc '). . .

9.1. kpathsea ▲

9.2. emtexdir ▲

9.3. MiK\*(TX ▲

Many

vptovf implementations allow only 100 bytes for the .C TFM header (the limit is 1024 in the .C TFM file format itself): 8 bytes for checksum and design size, 40 bytes for the family name, 20 bytes for the encoding, and 4 bytes for a face byte. There remain only 28 bytes for some additional information which is used by

ttf2tfm for an identification string (which is essentially a copy of the command line), and this limit is always exceeded. The optimal solution is to increase the value of max_header_bytesin the file .C vptovf.web (and probably .C pltotf.web too) to, say, 400 and recompile

vptovf (and

R pltotf ). Otherwise you'll get some (harmless) error messages like

.C "This HEADER index is too big for my present table size"

which can be safely ignored. . .

R ttf2pk (1),

R afm2tfm (1),

R vptovf (1),
the info pages for

dvips and

kpathsea . .

ttf2tfm is part of the FreeType 1 package, a high quality TrueType rendering library. . .

Werner LEMBERG .C <>
Fr('ed('eric LOYER .C <>