summaryrefslogtreecommitdiff
path: root/Build/source/texk/ttf2pk/ttf2tfm.1
blob: a1edc31eaaee419b08898f3c04abaa4fbb5260f3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
.\" man page for ttf2tfm
.
.TH TTF2TFM 1 10-Jan-2002 "FreeType version 1.5"
.SH NAME
ttf2tfm \- build TeX metric files from a TrueType font
.SH SYNOPSIS
.na
.nh
.B ttf2tfm
'in +\n(.ku
.IR ttffile [ .ttf | .ttc ]
[\c
.BI \-c \ \%caps-height-factor\c
]
[\c
.BI \-e \ \%extension-factor\c
]
[\c
.BI \-E \ \%encoding-id\^\c
]
[\c
.BI \-f \ \%font-index\c
]
[\c
.B \-l\c
]
[\c
.B \-L\ \c
.IR \%ligature-file [ .sfd ]\c
]
[\c
.B \-n\c
]
[\c
.B \-N\c
]
[\c
.B \-O\c
]
[\c
.B \-p\ \c
.IR \%inencfile [ .enc ]\c
]
[\c
.BI \-P \ \%platform-id\^\c
]
[\c
.B \-q\c
]
[\c
.BI \-r \ \%old-glyphname\ \%new-glyphname\c
]
[\c
.B \-R\ \c
.IR \%replacement-file [ .rpl ]\c
]
[\c
.BI \-s \ \%slant-factor\c
]
[\c
.B \-t\ \c
.IR \%outencfile [ .enc ]\c
]
[\c
.B \-T\ \c
.IR \%inoutencfile [ .enc ]\c
]
[\c
.B \-u\c
]
[\c
.B \-v\ \c
.IR \%vplfile [ .vpl ]\c
]
[\c
.B \-V\ \c
.IR \%scvplfile [ .vpl ]\c
]
[\c
.B \-w\c
]
[\c
.B \-x\c
]
[\c
.BI \-y \ \%vertical-shift-factor\c
]
[\c
.IR \%tfmfile [ .tfm ]\c
]
.br
.in
.B "ttf2tfm \-\^\-version"
|
.B \-\^\-help
.ad
.hy
.
.
.
.\" ====
.\" ==== macro definitions
.\" ====
.
.\" here we define \TeX for troff and nroff
.if t .ds TX T\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X
.if n .ds TX TeX
.
.\" and here the same for \LaTeX
.if t \{\
.ie '\*(.T'dvi' \
.ds LX L\h'-0.36m'\v'-0.15v'\s-3A\s0\h'-0.15m'\v'0.15v'\*(TX
.el .ds LX L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*(TX
.\}
.if n .ds LX LaTeX
.
.\" \LaTeXe
.\" note that we need \vareps for TeX instead of \eps which can only be
.\" accessed with the \N escape sequence (in the Math Italic font)
.if t \{\
.ie '\*(.T'dvi' .ds LE \*(LX\h'0.15m'2\v'0.20v'\f(MI\N'34'\fP\v'-0.20v'
.el .ds LE \*(LX\h'0.15m'2\v'0.20v'\(*e\v'-0.20v'
.\}
.if n .ds LE LaTeX\ 2e
.
.\" a typewriter font
.if t \{\
.de C
\fC\\$1\fP\\$2\fC\\$3\fP\\$4
..
.\}
.if n \{\
.de C
\\$1\\$2\\$3\\$4
..
.\}
.
.\" ====
.\" ==== end of macro definitions
.\" ====
.
.
.
.SH DESCRIPTION
This program extracts the metric and kerning information of a TrueType
font and converts it into metric files usable by \*(TX
(quite similar to
.B afm2tfm
which is part of the
.B dvips
package; please consult its info files for more details on the various
parameters (especially encoding files).
.PP
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
.B ttf2tfm
and
.BR 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.
.PP
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.
.PP
For CJKV (Chinese/Japanese/Korean/old Vietnamese) fonts, a different
mechanism is provided (see
.B "SUBFONT DEFINITION FILES"
below).
.
.
.SH PARAMETERS
Most of the command line switch names are the same as in
.B 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
.I not
be a switch but must be the font name.
.TP
.BI \-c \ caps-height-factor
The height of small caps made with the
.B \-V
switch.
Default value of this real number is\ 0.8 times the height of uppercase
glyphs.
.IP
Will be ignored in subfont mode.
.TP
.BI \-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.
.TP
.BI \-E \ encoding-id
The TrueType encoding ID.
Default value of this non-negative integer is\ 1.
.IP
Will be ignored if
.B \-N
is used.
.TP
.BI \-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 '.]
.IP
Will be ignored for ordinary TrueType fonts.
.TP
.B \-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.
.IP
Will be ignored if not in subfont mode.
.TP
.BI \-L \ ligature-file
Same as
.BR \-l ,
but character codes for ligatures are specified in
.IR \%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).
.IP
Ligature files have the same format and extension as
.C SFD
files.
This option will be ignored if not in subfont mode.
.TP
.B \-n
Use PS names (of glyphs) of the TrueType font.
Only glyphs with a valid entry in the selected cmap are used.
.IP
Will be ignored in subfont mode.
.TP
.B \-N
Use only PS names of the TrueType font.
No cmap is used, thus the switches
.B \-E
and
.B \-P
have no effect, causing a warning message.
.IP
Will be ignored in subfont mode.
.TP
.B \-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.
.TP
.BI \-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
.B ttf2pk
calls.
.IP
Will be ignored in subfont mode.
.TP
.BI \-P \ platform-id
The TrueType platform ID.
Default value of this non-negative integer is\ 3.
.IP
Will be ignored if
.B \-N
is used.
.TP
.B \-q
Make
.B 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.
.TP
.BI \-r \ old-glyphname\ new-glyphname
Replaces
.I \%old-glyphname
with
.IR \%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
.IR \%new-glyphname ;
multiple occurrences of
.B \-r
are possible.
.IP
If in subfont mode or if no encoding file is specified, this switch is
ignored.
.TP
.BI \-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
.IR "\%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.
.IP
If in subfont mode or if no encoding file is specified, this switch is
ignored.
.TP
.BI \-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.
.TP
.BI \-t \ outencfile
The output encoding file name for the virtual font(s).
Only characters in the raw \*(TX
font are used.
.IP
Will be ignored in subfont mode.
.TP
.BI \-T \ inoutencfile
This is equivalent to
.RB ` \-p
.I inoutencfile
.B \-t
.IR inoutencfile '.
.IP
Will be ignored in subfont mode.
.TP
.B \-u
Use only those characters specified in the output encoding, and no
others.
By default,
.B 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).
.IP
Will be ignored in subfont mode.
.TP
.BI \-v \ vplfile
Output a
.C VPL
file in addition to the
.C TFM
file.
If no output encoding file is specified,
.B ttf2tfm
uses a default font encoding (cmtt10).
.B Note:
Be careful to use different names for the virtual font and the raw font!
.IP
Will be ignored in subfont mode.
.TP
.BI \-V \ scvplfile
Same as
.BR \-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
.BR \-c )
to typeset lowercase.
This font handles accented letters and retains proper kerning.
.IP
Will be ignored in subfont mode.
.TP
.B \-w
Generate PostScript encoding vectors containing glyph indices, primarily
used to embed TrueType fonts in pdf\*(TX.
.B 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.
.IP
Will be ignored if not in subfont mode.
.TP
.B \-x
Rotate all glyphs by 90 degrees counter-clockwise.
If no
.B \-y
parameter is given, the rotated glyphs are shifted down vertically
by\ 0.25em.
.IP
Will be ignored if not in subfont mode.
.TP
.BI \-y \ vertical-shift-factor
Shift down rotated glyphs by the given amount (the unit is
.IR em ).
.IP
Ignored if not in subfont mode or glyphs are not rotated.
.TP
.B \-\^\-version
Shows the current version of
.B ttf2tfm
and the used file search library (e.g.
.BR kpathsea ).
.TP
.B \-\^\-help
Shows usage information.
.PP
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 '.
.
.
.SH CMAPS
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
.B \-P
and
.BR \-E .
With
.B \-P
you specify the platform ID; defined values are:
.PP
.in +4m
.ta 3iC
.I "platform	platform ID (pid)"
.sp
.ta 3iR
Apple Unicode	0
.br
Macintosh	1
.br
ISO	2
.br
Microsoft	3
.PP
The encoding ID depends on the platform.
For pid=0, we ignore the
.B \-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:
.PP
.in +4m
.ta 3iC
.ti -2m
platform ID = 1
.sp
.I "script	encoding ID (eid)"
.sp
.ta 3iR
Roman	0
.br
Japanese	1
.br
Chinese	2
.br
Korean	3
.br
Arabic	4
.br
Hebrew	5
.br
Greek	6
.br
Russian	7
.br
Roman Symbol	8
.br
Devanagari	9
.br
Gurmukhi	10
.br
Gujarati	11
.br
Oriya	12
.br
Bengali	13
.br
Tamil	14
.br
Telugu	15
.br
Kannada	16
.br
Malayalam	17
.br
Sinhalese	18
.br
Burmese	19
.br
Khmer	20
.br
Thai	21
.br
Laotian	22
.br
Georgian	23
.br
Armenian	24
.br
Maldivian	25
.br
Tibetan	26
.br
Mongolian	27
.br
Geez	28
.br
Slavic	29
.br
Vietnamese	30
.br
Sindhi	31
.br
Uninterpreted	32
.PP
Here are the ISO encoding IDs:
.PP
.in +4m
.ta 3iC
.ti -2m
platform ID = 2
.sp
.I "encoding	encoding ID (eid)"
.sp
.ta 3iR
ASCII	0
.br
ISO 10646	1
.br
ISO 8859-1	2
.PP
And finally, the Microsoft encoding IDs:
.PP
.in +4m
.ta 3iC
.ti -2m
platform ID = 3
.sp
.I "encoding	encoding ID (eid)"
.sp
.ta 3iR
Symbol	0
.br
Unicode 2.0	1
.br
Shift JIS	2
.br
GB 2312 (1980)	3
.br
Big 5	4
.br
KS X 1001 (Wansung)	5
.br
KS X 1001 (Johab)	6
.br
UCS-4	10
.PP
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).
.PP
The
.B \-P
and
.B \-E
options of
.B ttf2tfm
must be equally specified for
.BR ttf2pk ;
the corresponding parameters in a map file are `Pid' and `Eid',
respectively.
.PP
The default pid/eid pair is (3,1).
.PP
Similarly, an
.B \-f
option must be specified as `Fontindex' parameter in a map file.
.PP
If you use the
.B \-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
.B \-n
switch, the default glyph names built into
.B 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'.
.PP
Single replacement glyph names specified with
.B \-r
must be given directly as `\c
.IR "old-glyphname new-glyphname" '
in a map file;
.B \-R
is equivalent to the `Replacement' option.
.
.
.SH INPUT AND OUTPUT ENCODINGS
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
.BR 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
.BR afm2tfm ,
you must access each glyph with its Adobe glyph name, e.g.\ \c
\%`/quotedsingle' or \%`/Acircumflex'.
This has been extended with
.BR 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
.IR <decimal-number> ',
`/.c0\c
.IR <octal-number> ',
or `/.c0x\c
.IR <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
.B \-N
is used.]
.PP
For pid/eid pairs (1,0) and (3,1), both
.B ttf2tfm
and
.B 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 .
.PP
On the other hand, the switches
.B \-n
and
.B \-N
makes
.B 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.
.PP
Use the
.B \-r
switch to remap single glyph names and
.B \-R
to specify a file containing replacement glyph name pairs.
.PP
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
.B \-q
option,
.B 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.
.PP
If you select the
.B \-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'.
.PP
If you don't select an  output encoding,
.B ttf2tfm
uses the same mapping table as
.B 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
.B \-q
option
.B ttf2tfm
prints the final output encoding to standard output).
Use the
.B \-u
option if you want only glyphs in the virtual font which are defined
in the output encoding file, and nothing more.
.PP
One feature missing in
.B afm2tfm
has been added which is needed by \*(LX's T1 encoding:
.B 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.
.PP
For both input and output encoding, an empty code position is
represented by the glyph name \%`/.notdef'.
.PP
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.
.PP
.
.
.SH SUBFONT DEFINITION FILES
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.
.PP
A subfont file name usually consists of a prefix, a subfont infix, and
a postfix (which is empty in most cases), e.g.
.PP
.in +2m
ntukai23 \(-> prefix: ntukai, infix: 23, postfix: (empty)
.PP
Here the syntax of a line in an
.C SFD
file, describing one subfont:
.in +2m
.TP
.I <whitespace> <infix> <whitespace> <ranges> <whitespace>
.sp
.TP
.IR <infix> \ :=
anything except whitespace.
It is best to use only alphanumerical characters.
.TP
.IR <whitespace> \ :=
space, formfeed, carriage return, horizontal and vertical tabs -- no
newline characters.
.TP
.IR <ranges> \ :=
.IR "<ranges> <whitespace> <codepoint>" \ |
.br
.IR "<ranges> <whitespace> <range>" \ |
.br
.I <ranges> <whitespace> <offset> <whitespace> <range>
.TP
.IR <codepoint> \ :=
.I <number>
.br
.TP
.IR <range> \ :=
.IR <number> \ `_' \ <number>
.br
.TP
.IR <offset> \ :=
.IR <number> \ `:'
.TP
.IR <number> \ :=
hexadecimal (prefix `0x'), decimal, or octal (prefix `0')
.PP
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.
.PP
Example:
.PP
.in +2m
The line
.PP
.in +4m
.C "03   10: 0x2349 0x2345_0x2347"
.PP
.in +2m
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.
.PP
The
.C SFD
files in the distribution are customized for the CJK package for
\*(LX.
.PP
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
.B ttf2tfm
and
.B ttf2pk
switch then to subfont mode.
.PP
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.
.PP
Subfont mode disables the options 
.BR \-n , \ \-N , \ \-p ,
.BR \-r , \ \-R , \ \-t ,
.BR \-T , \ \-u , \ \-v , \ \-V
and
.B \-w
for
.BR ttf2tfm ;
similarly, no `Encoding' or `Replacement' parameter is allowed in
a map file.
Single replacement glyph names are ignored too.
.PP
.B ttf2tfm
will create all subfont
.C TFM
files specified in the
.C SFD
files (provided the subfont contains glyphs) in one run.
.PP
Example:
.PP
.in +2m
The call
.PP
.in +4m
.C "ttf2tfm ntukai.ttf ntukai@Big5,Big5-supp@"
.PP
.in +2m
will use
.C Big5.sfd
and
.C Big5-supp.sfd ,
producing
.I all
subfont files
.C ntukai01.tfm ,
.C ntukai02.tfm ,
etc.
.
.
.SH "RETURN VALUE"
ttf2tfm returns 0 on success and 1 on error; warning and error
messages are written to standard error.
.
.
.SH "SOME NOTES ON FILE SEARCHING"
Both
.B ttf2pk
and
.B ttf2tfm
use either the
.BR kpathsea ,
.BR emtexdir ,
or
.B MiK\*(TX
library for searching files 
.RB ( emtexdir
will work only on operating systems which have an MS-DOSish background, i.e.
MS-DOS, OS/2, Windows;
.B Mik\*(TX
is specific to MS Windows).
.PP
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 ').
.
.
.SS kpathsea
Please note that older versions of
.B kpathsea
(<3.2) have no special means to seach for TrueType fonts and related
files, thus we use the paths for PostScript related stuff.
The actual version of kpathsea is displayed on screen if you call
either
.B ttf2pk
or
.B ttf2tfm
with the
.B \-\^\-version
command line switch.
.PP
Here is a table of the file type and the corresponding
.B kpathsea
variables.
.C TTF2PKINPUTS
and
.C TTF2TFMINPUTS
are program specific environment variables introduced in
.B kpathsea
version\ 3.2:
.PP
.in +4m
.ta 2i
.C \&.ttf \ and "\ .ttc	TTFONTS"
.br
.C "ttf2pk.cfg	TTF2PKINPUTS"
.br
.C "\&.map	TTF2PKINPUTS"
.br
.C "\&.enc	TTF2PKINPUTS, TTF2TFMINPUTS"
.br
.C "\&.rpl	TTF2PKINPUTS, TTF2TFMINPUTS"
.br
.C "\&.tfm	TFMFONTS"
.br
.C "\&.sfd	TTF2PKINPUTS, TTF2TFMINPUTS"
.PP
And here the same for pre-3.2-versions of
.B kpathsea:
.PP
.in +4m
.ta 2i
.C \&.ttf \ and "\ .ttc	T1FONTS"
.br
.C "ttf2pk.cfg	TEXCONFIG"
.br
.C "\&.map	TEXCONFIG"
.br
.C "\&.enc	TEXPSHEADERS"
.br
.C "\&.rpl	TEXPSHEADERS"
.br
.C "\&.tfm	TFMFONTS"
.br
.C "\&.sfd	TEXPSHEADERS"
.PP
Finally, the same for pre-3.0-versions (as used e.g. in te\*(TX\ 0.4):
.PP
.in +4m
.ta 2i
.C \&.ttf \ and "\ .ttc	DVIPSHEADERS"
.br
.C "ttf2pk.cfg	TEXCONFIG"
.br
.C "\&.map	TEXCONFIG"
.br
.C "\&.enc	DVIPSHEADERS"
.br
.C "\&.rpl	DVIPSHEADERS"
.br
.C "\&.tfm	TFMFONTS"
.br
.C "\&.sfd	DVIPSHEADERS"
.PP
Please consult the info files of
.B kpathsea
for details on these variables.
The decision whether to use the old or the new scheme will be done
during compilation.
.PP
You should set the
.C TEXMFCNF
variable to the directory where your
.C texmf.cnf
configuration file resides.
.PP
Here is the proper command to find out to which value a
.B kpathsea
variable is set (we use
.C TTFONTS
as an example).
This is especially useful if a variable isn't set in
.C texmf.cnf
or in the environment, thus pointing to the default value which is
hard-coded into the
.B kpathsea
library.
.PP
.in +2m
.C "kpsewhich -progname=ttf2tfm -expand-var='$TTFONTS'"
.PP
We select the program name also since it is possible to specify
variables which are searched only for a certain program -- in our
example it would be
.C TTFONTS.ttf2tfm .
.PP
A similar but not identical method is to say
.PP
.in +2m
.C "kpsewhich -progname=ttf2tfm -show-path='truetype fonts'"
.PP
[A full list of format types can be obtained by saying `\c
.C "kpsewhich --help" '
on the command line prompt.]
This is exactly how
.B ttf2tfm
(and
.BR ttf2pk )
searches for files; the disadvantage is that all variables are expanded
which can cause very long strings.
.
.
.SS emtexdir
Here the list of suffixes and their related environment variables to be
set in
.C autoexec.bat
(resp. in
.C config.sys
for OS/2):
.PP
.in +4m
.ta 2i
.C \&.ttf \ and "\ .ttc	TTFONTS"
.br
.C "ttf2pk.cfg	TTFCFG"
.br
.C "\&.map	TTFCFG"
.br
.C "\&.enc	TTFCFG"
.br
.C "\&.rpl	TTFCFG"
.br
.C "\&.tfm	TEXTFM"
.br
.C "\&.sfd	TTFCFG"
.PP
If one of the variables isn't set, a warning message is emitted.
The current directory will always  be searched.
As usual, one exclamation mark appended to a directory path causes
subdirectories one level deep to be searched, two exclamation marks cause
all subdirectories to be searched.
Example:
.PP
.in +2m
.C TTFONTS=c:\\\\fonts\\\\truetype!!;d:\\\\myfonts\\\\truetype!
.PP
Constructions like `\c
.C c:\\\\fonts!!\\\\truetype '
aren't possible.
.
.
.SS MiK\*(TX
Both
.B ttf2tfm
and
.B ttf2pk
have been fully integrated into
.BR MiK\*(TX .
Please refer to the documentation of
.B MiK\*(TX
for more details on file searching.
.
.
.SH PROBLEMS
Many
.B 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
.B 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
.I \%max_header_bytes
in the file
.C vptovf.web
(and probably
.C pltotf.web
too) to, say,\ 400
and recompile
.B vptovf
(and
.BR pltotf ).
Otherwise you'll get some (harmless) error messages like
.PP
.in +2m
.C "This HEADER index is too big for my present table size"
.PP
which can be safely ignored.
.
.
.SH "SEE ALSO"
.BR ttf2pk (1),
.BR afm2tfm (1),
.BR vptovf (1),
.br
the info pages for
.B dvips
and
.B kpathsea
.
.
.SH AVAILABILITY
.B ttf2tfm
is part of the FreeType\ 1 package, a high quality TrueType rendering
library.
.
.
.SH AUTHORS
Werner LEMBERG
.C <wl@gnu.org>
.br
Fr\('ed\('eric LOYER
.C <loyer@ensta.fr>