1TTF2TFM(1) General Commands Manual TTF2TFM(1)
2
6 ttf2tfm - build TeX metric files from a TrueType font
7
9 ttf2tfm ttffile[.ttf|.ttc] [-c caps-height-factor]
10 [-e extension-factor] [-E encoding-id] [-f font-index] [-l]
11 [-L ligature-file[.sfd]] [-n] [-N] [-O] [-p inencfile[.enc]]
12 [-P platform-id] [-q] [-r old-glyphname new-glyphname]
13 [-R replacement-file[.rpl]] [-s slant-factor]
14 [-t outencfile[.enc]] [-T inoutencfile[.enc]] [-u]
15 [-v vplfile[.vpl]] [-V scvplfile[.vpl]] [-w] [-x]
16 [-y vertical-shift-factor] [tfmfile[.tfm]]
17 ttf2tfm --version | --help
18
20 This program extracts the metric and kerning information of a TrueType
21 font and converts it into metric files usable by TeX (quite similar to
22 afm2tfm which is part of the dvips package; please consult its info
23 files for more details on the various parameters (especially encoding
24 files).
25 Since a TrueType font often contains more than 256 glyphs, some means
27 are necessary to map a subset of the TrueType glyphs onto a TeX font.
28 To do this, two mapping tables are needed: the first (called `input' or
29 `raw' encoding) maps the TrueType font to a raw TeX font (this mapping
30 table is used by both ttf2tfm and ttf2pk), and the second (called `out‐
31 put' or `virtual' encoding) maps the raw TeX font to another (virtual)
32 TeX font, providing all kerning and ligature information needed by TeX.
33 This two stage mapping has the advantage that one raw font can be ac‐
35 cessed with various LaTeX encodings (e.g. T1 and OT1) via the virtual
36 font mechanism, and just one PK file is necessary.
37 For CJKV (Chinese/Japanese/Korean/old Vietnamese) fonts, a different
39 mechanism is provided (see SUBFONT DEFINITION FILES below).
40
42 Most of the command line switch names are the same as in afm2tfm for
43 convenience. One or more space characters between an option and its
44 value is mandatory; options can't be concatenated. For historical rea‐
45 sons, the first parameter can not be a switch but must be the font
46 name.
47 -c caps-height-factor
49 The height of small caps made with the -V switch. Default value
50 of this real number is 0.8 times the height of uppercase glyphs.
51 Will be ignored in subfont mode.
53 -e extension-factor
55 The extension factor to stretch the characters horizontally.
56 Default value of this real number is 1.0; if less than 1.0, you
57 get a condensed font.
58 -E encoding-id
60 The TrueType encoding ID. Default value of this non-negative
61 integer is 1.
62 Will be ignored if -N is used.
64 -f font-index
66 The font index in a TrueType Collection. Default is the first
67 font (index 0). [TrueType collections are usually found in some
68 CJK fonts; e.g. the first font index specifies glyphs and met‐
69 rics for horizontal writing, and the second font index does the
70 same for vertical writing. TrueType collections usually have
71 the extension `.ttc'.]
72 Will be ignored for ordinary TrueType fonts.
74 -l Create ligatures in subfonts between first and second bytes of
76 all the original character codes. Example: Character
77 code 0xABCD maps to character position 123 in subfont 45. Then
78 a ligature in subfont 45 between position 0xAB and 0xCD pointing
79 to character 123 will be produced. The fonts of the Korean HLa‐
80 TeX package use this feature. Note that this option generates
81 correct ligatures only for TrueType fonts where the input cmap
82 is identical to the output encoding. In case of HLaTeX, TTFs
83 must have platform ID 3 and encoding ID 5.
84 Will be ignored if not in subfont mode.
86 -L ligature-file
88 Same as -l, but character codes for ligatures are specified in
89 ligature-file. For example, `-L KS-HLaTeX' generates correct
90 ligatures for the Korean HLaTeX package regardless of the plat‐
91 form and encoding ID of the used TrueType font (the file KS-HLa‐
92 TeX.sfd is part of the ttf2pk package).
93 Ligature files have the same format and extension as SFD files.
95 This option will be ignored if not in subfont mode.
96 -n Use PS names (of glyphs) of the TrueType font. Only glyphs with
98 a valid entry in the selected cmap are used.
99 Will be ignored in subfont mode.
101 -N Use only PS names of the TrueType font. No cmap is used, thus
103 the switches -E and -P have no effect, causing a warning mes‐
104 sage.
105 Will be ignored in subfont mode.
107 -O Use octal values for all character codes in the VPL file rather
109 than names; this is useful for symbol or CJK fonts where charac‐
110 ter names such as `A' are meaningless.
111 -p inencfile
113 The input encoding file name for the TTF→raw TeX mapping. This
114 parameter has to be specified in a map file (default:
115 ttfonts.map) recorded in ttf2pk.cfg for successive ttf2pk calls.
116 Will be ignored in subfont mode.
118 -P platform-id
120 The TrueType platform ID. Default value of this non-negative
121 integer is 3.
122 Will be ignored if -N is used.
124 -q Make ttf2tfm quiet. It suppresses any informational output ex‐
126 cept warning and error messages. For CJK fonts, the output can
127 get quite large if you don't specify this switch.
128 -r old-glyphname new-glyphname
130 Replaces old-glyphname with new-glyphname. This switch is use‐
131 ful if you want to give an unnamed glyph (i.e., a glyph which
132 can be represented with `.gXXX' or `.cXXX' only) a name or if
133 you want to rename an already existing glyph name. You can't
134 use the `.gXXX' or `.cXXX' glyph name constructs for
135 new-glyphname; multiple occurrences of -r are possible.
136 If in subfont mode or if no encoding file is specified, this
138 switch is ignored.
139 -R replacement-file
141 Use this switch if you have many replacement pairs; they can be
142 collected in a file which should have `.rpl' as extension. The
143 syntax used in such replacement files is simple: Each non-empty
144 line must contain a pair `old-glyphname new-glyphname' separated
145 by whitespace (without the quotation marks). A percent sign
146 starts a line comment; you can continue a line on the next line
147 with a backslash as the last character.
148 If in subfont mode or if no encoding file is specified, this
150 switch is ignored.
151 -s slant-factor
153 The obliqueness factor to slant the font, usually much smaller
154 than 1. Default of this real number is 0.0; if the value is
155 larger than zero, the characters slope to the right, otherwise
156 to the left.
157 -t outencfile
159 The output encoding file name for the virtual font(s). Only
160 characters in the raw TeX font are used.
161 Will be ignored in subfont mode.
163 -T inoutencfile
165 This is equivalent to `-p inoutencfile -t inoutencfile'.
166 Will be ignored in subfont mode.
168 -u Use only those characters specified in the output encoding, and
170 no others. By default, ttf2tfm tries to include all characters
171 in the virtual font, even those not present in the encoding for
172 the virtual font (it puts them into otherwise-unused positions,
173 rather arbitrarily).
174 Will be ignored in subfont mode.
176 -v vplfile
178 Output a VPL file in addition to the TFM file. If no output en‐
179 coding file is specified, ttf2tfm uses a default font encoding
180 (cmtt10). Note: Be careful to use different names for the vir‐
181 tual font and the raw font!
182 Will be ignored in subfont mode.
184 -V scvplfile
186 Same as -v, but the virtual font generated is a pseudo small
187 caps font obtained by scaling uppercase letters by 0.8 (resp.
188 the value specified with -c) to typeset lowercase. This font
189 handles accented letters and retains proper kerning.
190 Will be ignored in subfont mode.
192 -w Generate PostScript encoding vectors containing glyph indices,
194 primarily used to embed TrueType fonts in pdfTeX. ttf2tfm takes
195 the TFM names and replaces the suffix with .enc; that is, for
196 files foo01.tfm, foo02.tfm, ... it creates foo01.enc,
197 foo02.enc, ... at the same place.
198 Will be ignored if not in subfont mode.
200 -x Rotate all glyphs by 90 degrees counter-clockwise. If no -y pa‐
202 rameter is given, the rotated glyphs are shifted down vertically
203 by 0.25em.
204 Will be ignored if not in subfont mode.
206 -y vertical-shift-factor
208 Shift down rotated glyphs by the given amount (the unit is em).
209 Ignored if not in subfont mode or glyphs are not rotated.
211 --version
213 Shows the current version of ttf2tfm and the used file search
214 library (e.g. kpathsea).
215 --help Shows usage information.
217 If no TFM file name is given, the name of the TTF file is used, includ‐
219 ing the full path and replacing the extension with `.tfm'.
220
222 Contrary to Type 1 PostScript fonts (but similar to the new CID Post‐
223 Script font format), most TrueType fonts have more than one native map‐
224 ping table, also called `cmap', which maps the (internal) TTF glyph in‐
225 dices to the (external) TTF character codes. Common examples are a
226 mapping table to Unicode encoded character positions, and the standard
227 Macintosh mapping.
228 To specify a TrueType mapping table, use the options -P and -E. With
230 -P you specify the platform ID; defined values are:
231 platform platform ID (pid)
233 ──────────────────────────────────
234 Apple Unicode 0
235 Macintosh 1
236 ISO 2
237 Microsoft 3
238 The encoding ID depends on the platform. For pid=0, we ignore the -E
240 parameter (setting it to zero) since the mapping table is always Uni‐
241 code version 2.0. For pid=1, the following table lists the defined
242 values:
243 platform ID = 1
245 script encoding ID (eid)
247 ──────────────────────────────────
248 Roman 0
249 Japanese 1
250 Chinese 2
251 Korean 3
252 Arabic 4
253 Hebrew 5
254 Greek 6
255 Russian 7
256 Roman Symbol 8
257 Devanagari 9
258 Gurmukhi 10
259 Gujarati 11
260 Oriya 12
261 Bengali 13
262 Tamil 14
263 Telugu 15
264 Kannada 16
265 Malayalam 17
266 Sinhalese 18
267 Burmese 19
268 Khmer 20
269 Thai 21
270 Laotian 22
272 Georgian 23
273 Armenian 24
274 Maldivian 25
275 Tibetan 26
276 Mongolian 27
277 Geez 28
278 Slavic 29
279 Vietnamese 30
280 Sindhi 31
281 Uninterpreted 32
282 Here are the ISO encoding IDs:
284 platform ID = 2
286 encoding encoding ID (eid)
288 ASCII 0
289 ISO 10646 1
290 ISO 8859-1 2
291 And finally, the Microsoft encoding IDs:
293 platform ID = 3
295 encoding encoding ID (eid)
297 Symbol 0
298 Unicode 2.0 1
299 Shift JIS 2
300 GB 2312 (1980) 3
301 Big 5 4
302 KS X 1001 (Wansung) 5
303 KS X 1001 (Johab) 6
304 UCS-4 10
305 The program will abort if you specify an invalid platform/encoding ID
307 pair. It will then show the possible pid/eid pairs. Please note that
308 most fonts have at most two or three cmaps, usually corresponding to
309 the pid/eid pairs (1,0), (3,0), or (3,1) in case of Latin based fonts.
310 Valid Microsoft fonts should have a (3,1) mapping table, but some fonts
311 exist (mostly Asian fonts) which have a (3,1) cmap not encoded in Uni‐
312 code. The reason for this strange behavior is the fact that some old
313 MS Windows versions will reject fonts having a non-(3,1) cmap (since
314 all non-Unicode Microsoft encoding IDs are for Asian MS Windows ver‐
315 sions).
316 The -P and -E options of ttf2tfm must be equally specified for ttf2pk;
318 the corresponding parameters in a map file are `Pid' and `Eid', respec‐
319 tively.
320 The default pid/eid pair is (3,1).
322 Similarly, an -f option must be specified as `Fontindex' parameter in a
324 map file.
325 If you use the -N switch, all cmaps are ignored, using only the Post‐
327 Script names in the TrueType font. The corresponding option in a map
328 file is `PS=Only'. If you use the -n switch, the default glyph names
329 built into ttf2tfm are replaced with the PS glyph names found in the
330 font. In many cases this is not what you want because the glyph names
331 in the font are often incorrect or non-standard. The corresponding op‐
332 tion in a map file is `PS=Yes'.
333 Single replacement glyph names specified with -r must be given directly
335 as `old-glyphname new-glyphname' in a map file; -R is equivalent to the
336 `Replacement' option.
337
339 You must specify the encoding vectors from the TrueType font to the raw
340 TeX font and from the raw TeX font to the virtual TeX font exactly as
341 with afm2tfm, but you have more possibilities to address the character
342 codes. [With `encoding vector' a mapping table with 256 entries in
343 form of a PostScript vector is meant; see the file T1-WGL4.enc of this
344 package for an example.] With afm2tfm, you must access each glyph with
345 its Adobe glyph name, e.g. `/quotedsingle' or `/Acircumflex'. This has
346 been extended with ttf2tfm; now you can (and sometimes must) access the
347 code points and/or glyphs directly, using the following syntax for
348 specifying the character position in decimal, octal, or hexadecimal no‐
349 tation: `/.c<decimal-number>', `/.c0<octal-number>', or `/.c0x<hexadec‐
350 imal-number>'. Examples: `/.c72', `/.c0646', `/.c0x48'. To access a
351 glyph index directly, use the character `g' instead of `c' in the just
352 introduced notation. Example: `/.g0x32'. [Note: The `.cXXX' notation
353 makes no sense if -N is used.]
354 For pid/eid pairs (1,0) and (3,1), both ttf2tfm and ttf2pk recognize
356 built-in default Adobe glyph names; the former follows the names given
357 in Appendix E of the book `Inside Macintosh', volume 6, the latter uses
358 the names given in the TrueType Specification (WGL4, a Unicode subset).
359 Note that Adobe names for a given glyph are often not unique and do
360 sometimes differ, e.g., many PS fonts have the glyph `mu', whereas this
361 glyph is called `mu1' in the WGL4 character set to distinguish it from
362 the real Greek letter mu. Be also aware that OpenType (i.e. True‐
363 Type 2.0) fonts use an updated WGL4 table; we use the data from the
364 latest published TrueType specification (1.66). You can find those
365 mapping tables in the source code file ttfenc.c.
366 On the other hand, the switches -n and -N makes ttf2tfm read in and use
368 the PostScript names in the TrueType font itself (stored in the `post'
369 table) instead of the default Adobe glyph names.
370 Use the -r switch to remap single glyph names and -R to specify a file
372 containing replacement glyph name pairs.
373 If you don't select an input encoding, the first 256 glyphs of the
375 TrueType font with a valid entry in the selected cmap will be mapped to
376 the TeX raw font (without the -q option, ttf2tfm prints this mapping
377 table to standard output), followed by all glyphs not yet addressed in
378 the selected cmap. However, some code points for the (1,0) pid/eid
379 pair are omitted since they do not represent glyphs useful for TeX:
380 0x00 (null), 0x08 (backspace), 0x09 (horizontal tabulation), 0x0d (car‐
381 riage return), and 0x1d (group separator). The `invalid character'
382 with glyph index 0 will be omitted too.
383 If you select the -N switch, the first 256 glyphs of the TrueType font
385 with a valid PostScript name will be used in case no input encoding is
386 specified. Again, some glyphs are omitted: `.notdef', `.null', and
387 `nonmarkingreturn'.
388 If you don't select an output encoding, ttf2tfm uses the same mapping
390 table as afm2tfm would use (you can find it in the source code file
391 texenc.c); it corresponds to TeX typewriter text. Unused positions
392 (either caused by empty code points in the mapping table or missing
393 glyphs in the TrueType font) will be filled (rather arbitrarily) with
394 characters present in the input encoding but not specified in the out‐
395 put encoding (without the -q option ttf2tfm prints the final output en‐
396 coding to standard output). Use the -u option if you want only glyphs
397 in the virtual font which are defined in the output encoding file, and
398 nothing more.
399 One feature missing in afm2tfm has been added which is needed by La‐
401 TeX's T1 encoding: ttf2tfm will construct the glyph `Germandbls' (by
402 simply concatenating two `S' glyphs) even for normal fonts if possible.
403 It appears in the glyph list as the last item, marked with an asterisk.
404 Since this isn't a real glyph it will be available only in the virtual
405 font.
406 For both input and output encoding, an empty code position is repre‐
408 sented by the glyph name `/.notdef'.
409 In encoding files, you can use `\' as the final character of a line to
411 indicate that the input is continued on the next line. The backslash
412 and the following newline character will be removed.
413
415 CJKV (Chinese/Japanese/Korean/old Vietnamese) fonts usually contain
416 several thousand glyphs; to use them with TeX it is necessary to split
417 such large fonts into subfonts. Subfont definition files (usually hav‐
418 ing the extension `.sfd') are a simple means to do this smoothly.
419 A subfont file name usually consists of a prefix, a subfont infix, and
421 a postfix (which is empty in most cases), e.g.
422 ntukai23 → prefix: ntukai, infix: 23, postfix: (empty)
424 Here the syntax of a line in an SFD file, describing one subfont:
426 <whitespace> <infix> <whitespace> <ranges> <whitespace>
428 <infix> :=
431 anything except whitespace. It is best to use only alphanumeri‐
432 cal characters.
433 <whitespace> :=
435 space, formfeed, carriage return, horizontal and vertical tabs
436 -- no newline characters.
437 <ranges> :=
439 <ranges> <whitespace> <codepoint> |
440 <ranges> <whitespace> <range> |
441 <ranges> <whitespace> <offset> <whitespace> <range>
442 <codepoint> :=
444 <number>
445 <range> :=
447 <number> `_' <number>
448 <offset> :=
450 <number> `:'
451 <number> :=
453 hexadecimal (prefix `0x'), decimal, or octal (prefix `0')
454 A line can be continued on the next line with a backslash ending the
456 line. The ranges must not overlap; offsets have to be in the range
457 0-255.
458 Example:
460 The line
462 03 10: 0x2349 0x2345_0x2347
464 assigns to the code positions 10, 11, 12, and 13 of the subfont hav‐
466 ing the infix `03' the character codes 0x2349, 0x2345, 0x2346, and
467 0x2347 respectively.
468 The SFD files in the distribution are customized for the CJK package
470 for LaTeX.
471 You have to embed the SFD file name into the TFM font name (at the
473 place where the infix will appear) surrounded by two `@' signs, on the
474 command line resp. a map file; both ttf2tfm and ttf2pk switch then to
475 subfont mode.
476 It is possible to use more than a single SFD file by separating them
478 with commata and no whitespace; for a given subfont, the first file is
479 scanned for an entry, then the next file, and so on. Later entries
480 override entries found earlier (possibly only partially). For example,
481 the first SFD file sets up range 0x10-0xA0, and the next one modifies
482 entries 0x12 and 0x25. As can be easily seen, this algorithm allows
483 for adding and replacing, but not for removing entries.
484 Subfont mode disables the options -n, -N, -p, -r, -R, -t, -T, -u, -v,
486 -V and -w for ttf2tfm; similarly, no `Encoding' or `Replacement' param‐
487 eter is allowed in a map file. Single replacement glyph names are ig‐
488 nored too.
489 ttf2tfm will create all subfont TFM files specified in the SFD files
491 (provided the subfont contains glyphs) in one run.
492 Example:
494 The call
496 ttf2tfm ntukai.ttf ntukai@Big5,Big5-supp@
498 will use Big5.sfd and Big5-supp.sfd, producing all subfont files
500 ntukai01.tfm, ntukai02.tfm, etc.
501
503 ttf2tfm returns 0 on success and 1 on error; warning and error messages
504 are written to standard error.
505
507 Both ttf2pk and ttf2tfm use either the kpathsea, emtexdir, or MiKTeX
508 library for searching files (emtexdir will work only on operating sys‐
509 tems which have an MS-DOSish background, i.e. MS-DOS, OS/2, Windows;
510 MikTeX is specific to MS Windows).
511 As a last resort, both programs can be compiled without a search li‐
513 brary; the searched files must be then in the current directory or
514 specified with a path. Default extensions will be appended also (with
515 the exception that only `.ttf' is appended and not `.ttc').
516 kpathsea
518 The actual version of kpathsea is displayed on screen if you call ei‐
519 ther ttf2pk or ttf2tfm with the --version command line switch.
520 Here is a table of the file type and the corresponding kpathsea vari‐
522 ables. TTF2PKINPUTS and TTF2TFMINPUTS are program specific environment
523 variables introduced in kpathsea version 3.2:
524 .ttf and .ttc TTFONTS
526 ttf2pk.cfg TTF2PKINPUTS
527 .map TTF2PKINPUTS
528 .enc TTF2PKINPUTS, TTF2TFMINPUTS
529 .rpl TTF2PKINPUTS, TTF2TFMINPUTS
530 .tfm TFMFONTS
531 .sfd TTF2PKINPUTS, TTF2TFMINPUTS
532 Please consult the info files of kpathsea for details on these vari‐
535 ables.
536 You should set the TEXMFCNF variable to the directory where your
538 texmf.cnf configuration file resides.
539 Here is the proper command to find out to which value a kpathsea vari‐
541 able is set (we use TTFONTS as an example). This is especially useful
542 if a variable isn't set in texmf.cnf or in the environment, thus point‐
543 ing to the default value which is hard-coded into the kpathsea library.
544 kpsewhich -progname=ttf2tfm -expand-var='$TTFONTS'
546 We select the program name also since it is possible to specify vari‐
548 ables which are searched only for a certain program -- in our example
549 it would be TTFONTS.ttf2tfm.
550 A similar but not identical method is to say
552 kpsewhich -progname=ttf2tfm -show-path='truetype fonts'
554 [A full list of format types can be obtained by saying `kpsewhich
556 --help' on the command line prompt.] This is exactly how ttf2tfm (and
557 ttf2pk) searches for files; the disadvantage is that all variables are
558 expanded which can cause very long strings.
559 emtexdir
561 Here the list of suffixes and their related environment variables to be
562 set in autoexec.bat (resp. in config.sys for OS/2):
563 .ttf and .ttc TTFONTS
565 ttf2pk.cfg TTFCFG
566 .map TTFCFG
567 .enc TTFCFG
568 .rpl TTFCFG
569 .tfm TEXTFM
570 .sfd TTFCFG
571 If one of the variables isn't set, a warning message is emitted. The
573 current directory will always be searched. As usual, one exclamation
574 mark appended to a directory path causes subdirectories one level deep
575 to be searched, two exclamation marks cause all subdirectories to be
576 searched. Example:
577 TTFONTS=c:\fonts\truetype!!;d:\myfonts\truetype!
579 Constructions like `c:\fonts!!\truetype' aren't possible.
581 MiKTeX
583 Both ttf2tfm and ttf2pk have been fully integrated into MiKTeX. Please
584 refer to the documentation of MiKTeX for more details on file search‐
585 ing.
586
588 Many vptovf implementations allow only 100 bytes for the TFM header
589 (the limit is 1024 in the TFM file format itself): 8 bytes for checksum
590 and design size, 40 bytes for the family name, 20 bytes for the encod‐
591 ing, and 4 bytes for a face byte. There remain only 28 bytes for some
592 additional information which is used by ttf2tfm for an identification
593 string (which is essentially a copy of the command line), and this lim‐
594 it is always exceeded.
595 The optimal solution is to increase the value of max_header_bytes in
597 the file vptovf.web (and probably pltotf.web too) to, say, 400 and re‐
598 compile vptovf (and pltotf). Otherwise you'll get some (harmless) er‐
599 ror messages like
600 This HEADER index is too big for my present table size
602 which can be safely ignored.
604
606 ttf2pk(1), afm2tfm(1), vptovf(1),
607 the info pages for dvips and kpathsea
608
610 ttf2tfm is part of the FreeType 1 package, a high quality TrueType ren‐
611 dering library.
612
614 Werner LEMBERG <wl@gnu.org>
615 Frédéric LOYER <loyer@ensta.fr>
616FreeType2 version 27-Jun-2013 TTF2TFM(1)