summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/otftotfm.1
blob: 6ecb0a7591fdefe6dc5ed7accaaf77717cae3122 (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
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
'\"t
.ds V 2.108
.de M
.BR "\\$1" "(\\$2)\\$3"
..
.de Sp
.if n .sp
.if t .sp 0.4
..
.de Bp
.IP \(bu 3n
..
.TH OTFTOTFM 1 "LCDF Typetools" "Version \*V"
.SH NAME
otftotfm \- create TeX font metrics from OpenType fonts
.SH SYNOPSIS
.B otftotfm
\%[\fB\-a\fR]
\%[\fBoptions\fR]
\%\fIfontfile\fR [\fItexname\fR]
'
.SH DESCRIPTION
.BR Otftotfm
creates the font metric and encoding files required to use an OpenType font
with TeX.  You supply an OpenType ".otf" or ".ttf" font file, 
a base ".enc" encoding,
and a TeX name "\fItexname\fR" for the resulting font, and say which
OpenType features should be turned on.  Then
.B otftotfm
generates and installs the corresponding TeX-related metric files (".tfm"
TeX font metrics, ".vf" virtual fonts, and ".enc" encoding files).  It
works on both PostScript-flavored and TrueType-flavored OpenType fonts,
although TrueType-flavor support will only work easily with pdftex.
.LP
The easiest way to use
.B otftotfm
is with the
.B \-a
option; see Automatic Mode below.  Without
.BR \-a ,
.B otftotfm
writes all its output files to the current directory.
.LP
After running "\fBotftotfm\fR \fIfontfile\fR \fItexname\fR" and
installing the results (manually or with
.BR \-a ),
you can use the OpenType font in plain TeX with a command like this:
.Sp
.nf
    \efont\emyfont=\fItexname\fR at 10pt
    {\emyfont This text uses the OpenType font.}
.fi
.Sp
LaTeX users will generally make a ".fd" input file so that commands like
"\erenewcommand{\ermdefault}{TeXName}" work correctly.  See the EXAMPLE
section for more; check the DIAGNOSTICS and FREQUENTLY ASKED QUESTIONS
sections if you have trouble.
'
.SS "OpenType Features"
.LP
OpenType fonts support optional
.I features
that change their appearance.  Use the
.B \-f
option to turn on selected features.  For example, "\fB\-f\fRsmcp" replaces
lower-case letters with the corresponding small capitals, in fonts that
support this.  
'
.PP
You'll generally provide at least the "\fB\-f\fRkern" and "\fB\-f\fRliga"
options, which activate pair kerns and f-ligatures.  Other interesting
features include "\fB\-f\fRcpsp", for capital spacing; "\fB\-f\fRdlig", for
optional ligatures; "\fB\-f\fRlnum", "\fB\-f\fRonum", "\fB\-f\fRpnum", and
"\fB\-f\fRtnum", to control digit glyphs; "\fB\-f\fRsmcp", for small
capitals; "\fB\-f\fRswsh", for swash variants; and "\fB\-f\fRcswh", for
contextual swash.  See the FEATURE DIRECTORY section below for more.  The
.M otfinfo 1
program will report which features a font supports; run "\fBotfinfo\fR
\fB\-f\fR \fIfontfile\fR".
'
.PP
Feature options can also apply a feature to a subset of characters in the
font.  For example, "\fB\-\-lf\fR smcp"
.I only
replaces letters with small capitals, whereas "\fB\-f\fRsmcp" might
additionally replace digits and punctuation marks with small-capital
versions.
'
.SS Automatic Mode
.PP
Automatic mode, triggered by the
.BR \-a / \-\-automatic
option, installs font metrics and encoding files where TeX can find them,
and additionally installs a Type 1 font and mapping for 
.M dvips 1 .  
This requires a TeX installation that follows the TeX Directory Structure
standard (http://www.tug.org/tds/), such as most Unix TeX installations.
'
.PP
Automatic mode should run seamlessly out of the box.
.B Otftotfm
will install metrics files, encodings, map files, and Type\~1 fonts into
.I $HOME/.texmf-var
or any other writable TEXMF directory, and run
.M updmap 1
to update the global lists of installed fonts.  (On older teTeX
installations, you may first need to copy the system's
.I updmap.cfg
file to
.I $HOME/texmf/web2c
and run
.M mktexlsr 1 .
On newer TeXLive installations, you may need to set the TEXMFVAR environment
variable.)
You can then run "\fBotftotfm\fR
.B \-a
.IR fontfile
.IR texname \&"
and immediately refer to the font in TeX using the
.I texname
you supplied.  Again, you will have to write ".fd" files and/or typescripts
to make the font conveniently accessible from LaTeX or ConTeXt.  See the
DIAGNOSTICS section if you have problems with these instructions.
'
.PP
In automatic mode,
.B otftotfm
searches your $TEXMFVAR or $TEXMF path for a writable directory, then
installs files under that directory tree as follows:
'
.TS
l	l	l	.
\fBFile type\fR	\fBDirectory\fR	\fBFilename\fR
TFM	TEXMF/fonts/tfm/\fIvendor\fR/\fItypeface\fR/	\fItexname\fR[\-\-base].tfm
VF	TEXMF/fonts/vf/\fIvendor\fR/\fItypeface\fR/	\fItexname\fR.vf
PL	TEXMF/fonts/pl/\fIvendor\fR/\fItypeface\fR/	\fItexname\fR[\-\-base].pl
VPL	TEXMF/fonts/vpl/\fIvendor\fR/\fItypeface\fR/	\fItexname\fR.vpl
encoding	TEXMF/fonts/enc/dvips/\fIvendor\fR/	a_\fIsignature\fR.enc
	or TEXMF/dvips/\fIvendor\fR/
font map	TEXMF/fonts/map/dvips/\fIvendor\fR/	\fIvendor\fR.map
	or TEXMF/dvips/\fIvendor\fR/
.TE
.PP
"TEXMF" stands for the writable TEXMF directory.  \fITexname\fR is the
font name supplied as 
.BR otftotfm 's
second argument.  The \fIvendor\fR and \fItypeface\fR strings are required
by TDS; they default to "lcdftools" and the font's family name,
respectively, but see the
.B \-\-vendor
and
.B \-\-typeface
options.  \fISignature\fR is an opaque 6-character encoding signature.
.PP
.B Otftotfm
also installs a font file suitable for printing.  PostScript-flavored
OpenType fonts are translated to Type 1 format and installed as PFB fonts.
TrueType-flavored fonts are normally installed as is, since pdftex and
pdflatex can read TrueType directly; but if you provide the
.B \-\-type42
option,
.B otftotfm
will translate TrueType fonts to Type 42 format, which dvips understands.
.B Otftotfm
does not overwrite existing font files.
.PP
The installation paths are as follows, where \fIPSname\fR is the font's
PostScript name.
.TS
l	l	l	.
PFB	TEXMF/fonts/type1/\fIvendor\fR/\fItypeface\fR/	\fIPSname\fR.pfb
TrueType	TEXMF/fonts/truetype/\fIvendor\fR/\fItypeface\fR/	\fIfontfile\fR
Type 42	TEXMF/fonts/type42/\fIvendor\fR/\fItypeface\fR/	\fIPSname\fR.t42
.TE
.PP
You can override these directories with environment variables and options
as follows.  Options take precedence over environment variables.
'
.TS
l	l	l	.
\fBFile type\fR	\fBEnvironment variable\fR	\fBOption\fR
TFM	TFMDESTDIR	\-\-tfm\-directory
VF	VFDESTDIR	\-\-vf\-directory
PL	PLDESTDIR	\-\-pl\-directory
VPL	VPLDESTDIR	\-\-vpl\-directory
encoding	ENCODINGDESTDIR	\-\-encoding\-directory
PFB	T1DESTDIR	\-\-type1\-directory
TrueType	TRUETYPEDESTDIR	\-\-truetype\-directory
Type 42	T42DESTDIR	\-\-type42\-directory
font map	\-	\-\-map\-file
.TE
.PP
.B Otftotfm
will update the
.I TEXMF/ls-R
file when installing files under TEXMF.  It will also run the
.M updmap 1
program after changing a map file, unless the 
.B \-\-no\-updmap
option was supplied.  However, if an executable file called
.IR TEXMF/dvips/updmap
exists, this file is executed (from the
.I TEXMF/dvips
directory) rather than the global
.BR updmap .
This is so you can write a fast, customized version of
.B updmap
if desired.
'
.SH EXAMPLE
This section uses MinionPro to show one way to install OpenType fonts for
LaTeX.  We begin with six fonts: "MinionPro-Regular.otf",
"MinionPro-It.otf", "MinionPro-Semibold.otf", "MinionPro-SemiboldIt.otf",
"MinionPro-Bold.otf", and "MinionPro-BoldIt.otf".
.PP
Our first task is to decide how to encode the fonts.  The "encoding scheme"
is used by TeX to decide how to typeset accents and symbols like "$".  The
"LY1" encoding scheme has reasonable accent support and is a good choice
for many OpenType fonts.  LY1 corresponds to the "texnansx.enc" encoding
file, so we will supply
.B otftotfm
with the "\fB\-e\fR texnansx" option.
.RS
.LP
Expert note: Strictly speaking, LY1 corresponds to the "texnansi.enc"
encoding file.  Since the "texnansx.enc" version omits duplicate
characters, it has more room for font-specific glyphs and is generally a
better choice; but if you plan to type characters like "ae" directly into
your editor, rather than using TeX commands like \eae, you should use
"texnansi.enc".
.RE
.PP
Next, we decide on a naming scheme for the font metric files.  Let's use
the OpenType font names as a base.  (There's generally no need to follow
the six-character "Karl Berry" naming scheme.)  Just in case we come back
later and add a different encoding scheme, we'll prepend "LY1--" to each
name.
.PP
We're now ready to run
.B otftotfm
for the first set of fonts.  Note the "\fB\-f\fRkern \fB\-f\fRliga"
options, which access pair kerns and the default "f" ligatures.
.Sp
.nf
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-Regular.otf \e
            \fB\-f\fRkern \fB\-f\fRliga LY1\-\-MinionPro\-Regular
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-It.otf \e
            \fB\-f\fRkern \fB\-f\fRliga LY1\-\-MinionPro\-It
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-Semibold.otf \e
            \fB\-f\fRkern \fB\-f\fRliga LY1\-\-MinionPro\-Semibold
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-SemiboldIt.otf \e
            \fB\-f\fRkern \fB\-f\fRliga LY1\-\-MinionPro\-SemiboldIt
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-Bold.otf \e
            \fB\-f\fRkern \fB\-f\fRliga LY1\-\-MinionPro\-Bold
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-BoldIt.otf \e
            \fB\-f\fRkern \fB\-f\fRliga LY1\-\-MinionPro\-BoldIt
.fi
.Sp
The small-caps fonts are generated with an additional "\fB\-f\fRsmcp"
option.  We append "\-\-fsmcp" to the font metric names as well,
differentiating them from the regular fonts.  Although MinionPro's italic
fonts support small-caps, the LaTeX font selection scheme can't access them
easily, so we've left them off.
.Sp
.nf
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-Regular.otf \e
            \fB\-f\fRkern \fB\-f\fRliga \fB\-f\fRsmcp LY1\-\-MinionPro-Regular\-\-fsmcp
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-Semibold.otf \e
            \fB\-f\fRkern \fB\-f\fRliga \fB\-f\fRsmcp LY1\-\-MinionPro\-Semibold\-\-fsmcp
    \fBotftotfm\fR \fB\-a\fR \fB\-e\fR texnansx MinionPro\-Bold.otf \e
            \fB\-f\fRkern \fB\-f\fRliga \fB\-f\fRsmcp LY1\-\-MinionPro\-Bold\-\-fsmcp
.fi
.Sp
To get old-style numerals, just add the "\fB\-f\fRonum" option to each
invocation -- and, to reduce confusion, append "\-\-fonum" to the font metric
names.
.PP
At this point, all our font metric files are installed, and it's finally
time to create the ".fd" file.  (The ".fd" format is documented in
.IR "The LaTeX Companion" .)
Let's call the LaTeX font family "MinionPro".  Then the ".fd" file is
"LY1MinionPro.fd", and it contains:
.Sp
.nf
    \eDeclareFontFamily{LY1}{MinionPro}{}
    \eDeclareFontShape{LY1}{MinionPro}{m}{n}%
            { <\-> LY1\-\-MinionPro\-Regular }{}
    \eDeclareFontShape{LY1}{MinionPro}{m}{it}{ <\-> LY1\-\-MinionPro\-It }{}
    \eDeclareFontShape{LY1}{MinionPro}{m}{sc}%
            { <\-> LY1\-\-MinionPro\-Regular\-\-fsmcp }{}
    \eDeclareFontShape{LY1}{MinionPro}{sb}{n}%
            { <\-> LY1\-\-MinionPro\-Semibold }{}
    \eDeclareFontShape{LY1}{MinionPro}{sb}{it}%
            { <\-> LY1\-\-MinionPro\-SemiboldIt }{}
    \eDeclareFontShape{LY1}{MinionPro}{sb}{sc}%
            { <\-> LY1\-\-MinionPro\-Semibold\-\-fsmcp }{}
    \eDeclareFontShape{LY1}{MinionPro}{b}{n}{ <\-> LY1\-\-MinionPro-Bold }{}
    \eDeclareFontShape{LY1}{MinionPro}{b}{it}%
            { <\-> LY1\-\-MinionPro\-BoldIt }{}
    \eDeclareFontShape{LY1}{MinionPro}{b}{sc}%
            { <\-> LY1\-\-MinionPro\-Bold\-\-fsmcp }{}
    \eDeclareFontShape{LY1}{MinionPro}{bx}{n}%
            { <\-> ssub * MinionPro/b/n }{}
    \eDeclareFontShape{LY1}{MinionPro}{bx}{it}%
            { <\-> ssub * MinionPro/b/it }{}
    \eDeclareFontShape{LY1}{MinionPro}{bx}{sc}%
            { <\-> ssub * MinionPro/b/sc }{}
.fi
.PP
We're now ready to use MinionPro in LaTeX, with lines like this in the
document preamble:
.Sp
.nf
    \eusepackage[LY1]{fontenc}
    \erenewcommand{\ermdefault}{MinionPro}
    \erenewcommand{\ebfdefault}{b}
.fi
.PP
Of course, we're free at any time to add more MinionPro variants with
.BR otftotfm ;
they'll become accessible to LaTeX as soon as we edit the "MinionPro.fd"
file.
'
.SH OPTIONS
With long options, you need type only as many characters as will make the
option unique.
.SS Font Feature and Transformation Options
.PD 0
.TP 5
.BI \-s " script\fR[.\fIlang\fR], " \-\-script= "script\fR[.\fIlang\fR]"
Apply features suitable to the script system
.I script
and language system
.IR lang .
Scripts and language systems are two-to-four-letter names assigned by
Microsoft and Adobe.  Examples include "latn" (Latin script), "grek" (Greek
script), and "yi.YIC" (Yi script with classic characters).  If
.I lang
is not specified, 
.B otftotfm
will use the default language system for that
script.  You can give this option multiple times.  Run "\fBotfinfo\fR
\-s \fIfont\fR" to see the list of scripts and languages a
font supports.  Defaults to "latn".
'
.Sp
.TP 5
.BI \-f " feature\fR, " \-\-feature= "feature"
Activate the feature named
.IR feature .
Features are four-letter names assigned by Microsoft and Adobe; they are
meant to correspond to font behaviors, such as kerning or small-capitals.
Examples include "liga" (default ligatures), "dlig" (discretionary
ligatures), "kern" (kerning), and "c2sc" (replacing capitals with small
capitals).  Give this option multiple times to apply multiple features.  Run
"\fBotfinfo\fR \-f [\-\-script option] \fIfont\fR" to see the list
of features a font supports for a specified script.
Defaults to any features required by the selected scripts.
'
.Sp
.TP 5
.BI \-\-lf " feature\fR, " \-\-letter\-feature= "feature"
Activate the feature named
.IR feature ,
but only for letters.  For instance, the "\-f smcp" option will apply the
small-caps feature to all characters in the encoding; this may result in
changes to punctuation and numbers as well as letters.  The "\-\-lf smcp"
option will apply the small-caps feature only to letters, meaning
characters with the "Letter" Unicode property.
'
.Sp
.TP 5
.BI \-\-subs\-filter " pattern"
.TP 5
.BI \-\-include\-subs " pattern"
.TP 5
.BI \-\-exclude\-subs " pattern"
.TP 5
.BI \-\-clear\-subs
Limit the characters that
.B otftotfm
will substitute.  Substitution is allowed on an input character if it
matches at least one of the
.B \-\-include
patterns, and none of the
.B \-\-exclude
patterns.  Each pattern applies to all following features, except that the
.B \-\-clear
option clears any accumulated patterns.  The
.BI \-\-subs\-filter " pattern"
option acts like
.B \-\-clear\-subs
followed by
.BI \-\-include\-subs " pattern\fR. "
For pattern syntax, see GLYPH PATTERNS, below.
.Sp
In the command line below, the \&'<Number>' pattern will force the "onum"
feature to substitute only numbers (and not, for example, punctuation).
The "salt" feature can still substitute any character.
.nf
    \fBotftotfm\fR \fB\-f\fRsalt \fB\-\-include\-subs\fR="<Number>" \fB\-f\fRonum \.\.\.
.fi
'
.Sp
.TP 5
.BI \-E " fac\fR, " \-\-extend= fac
Widen, or extend, the font by a factor of
.IR fac .
Like
.M afm2tfm 1 's
.B \-e
option.
'
.Sp
.TP 5
.BI \-S " amt\fR, " \-\-slant= amt
Oblique, or slant, the font by
.IR amt .
Like
.M afm2tfm 1 's
.B \-s
option.
'
.Sp
.TP 5
.BI \-L " amt\fR, " \-\-letterspacing= amt
Letterspace each character by
.IR amt
units, where 1000 units equals one em.  The width of each character
increases by
.IR amt ,
with half the space distributed to each sidebearing.  Boundary-character
kerns are added to maintain alignment at the ends of lines.
'
.Sp
.TP 5
.BR \-\-math\-spacing "[=\fIskewchar\fR]"
Ignore the font's claimed character widths, deriving horizontal metrics
from bounding boxes instead.  This results in similar spacing as the
Computer Modern Math Italic font, with increased sidebearings for letters
like f and j.
.Sp
If you provide
.IR skewchar ,
a number between 0 and 255 or a single character, then
.B otftotfm
adds heuristically-derived kerns to the font that may improve accent
positions in math mode.  To get the benefits, you must tell TeX about the
.I skewchar
with a command like "\eskewchar\efont=\fIskewchar\fR".
'
.Sp
.TP 5
.BI "\-k " "N\fR, " \-\-min\-kern= N
Only output kerning pairs whose absolute value is
.IR N
or larger.  Larger minimum kerns make kerning less precise, but shrink the
output TFM file.  The default minimum kern is 2.0, or 0.002 em.
'
.Sp
.TP 5
.BI \-\-space\-factor= fac
Scale the width of the inter-word space by a factor of
.IR fac .
'
.Sp
.TP 5
.BI \-\-design\-size= size
Set the output font's design size to
.IR size ,
a value in TeX points.  This value is mostly just documentation, since LaTeX
essentially ignores fonts' design sizes, but plain TeX may occasionally use
the design size to decide how large a font should be.  (Loading a font in
TeX "at" a particular size effectively ignores the design size; loading a
font plain or "scaled" by a given factor uses the design size.)  The default
is taken from the input font's optical size feature, or 10pt if it has no
such feature.
'
.Sp
.TP 5
.BI \-\-fixed\-width
Set the font to fixed-width (its space character will have no stretch or
shrink).  Normally you won't need this option; the font will tell
.B otftotfm
whether it is fixed width.  The opposite of
.B \-\-fixed\-width
is
.BR \-\-proportional\-width .
'
.Sp
.TP 5
.BI \-\-italic\-angle= angle
Set the output font's default italic angle to
.IR angle ,
a number of degrees.  This value is used by TeX to position
accents.  Normally you won't need this option; the font will tell
.B otftotfm
its italic angle.
.PD
'
.Sp
.TP 5
.BI \-\-x\-height= val
Set the output font's x-height to
.IR val .
This value is used by TeX to position accents. Normally you won't
need this option.
.IR Val
may be a number expressed in font units; \(oqx\(cq, which uses the
height of the font's lowercase x; or \(oqfont\(cq, which uses the
font's declared x-height metric.
'
.SS Encoding Options
'
.PD 0
.TP 5
.BI \-e " encoding\fR, " \-\-encoding= encoding
Select the output metrics's base
.M dvips 1
encoding. 
.B Otftotfm
will search for
.IR encoding [.enc]
the same way that
.B dvips
would, so you may not need to give a full pathname.  Say
.B \-e \-
to start with the font's default encoding.
See ENCODINGS, below,
for more information.
'
.Sp
.TP 5
.BI \-\-boundary\-char= char
Set the font's boundary character to
.IR char ,
which should either be a single non-digit character, or a number between \-1
and 255. The default is taken from the encoding.
'
.Sp
.TP 5
.BI \-\-altselector\-char= char
Set the font's alternate selector character to
.IR char ,
which should either be a single non-digit character, or a number between
\&\-1 and 255.  Alternate selectors let TeX authors explicitly choose
between versions of a character.  For instance, the
\&'\-\-altselector\-char="*"' option turns the "*" character into a special
switch that cycles between alternates.  For instance, the TeX input "A"
would produce the normal version of the "A" Unicode character, "A*" would
produce the first alternate, "A**" would produce the second alternate, and
so forth.  Furthermore, "s*t" will activate any discretionary "s_t"
ligature in the font.
.Sp
The
.B \-\-altselector\-char
mechanism uses the features specified by
.BR \-\-altselector\-feature
options.
.Sp
The alternate-selector character may also be specified in the encoding; see
ENCODINGS, below.  See Sivan Toledo's article cited in the SEE ALSO section
for more information.
'
.Sp
.TP 5
.BI \-\-altselector\-feature= feature
Activate the feature named
.I feature
for the
.B \-\-altselector\-char
mechanism.  Give this option multiple times to activate multiple
features.  This option activates features only for use with
.BR \-\-altselector\-char ;
use the
.B \-\-feature
option to activate features globally.  Defaults to the
.I salt
and
.I dlig
features.
'
.Sp
.TP 5
.BI \-\-alternates\-filter= pattern
.TP 5
.BI \-\-include\-alternates= pattern
.TP 5
.BI \-\-exclude\-alternates= pattern
.TP 5
.BI \-\-clear\-alternates
Limit the alternate characters that
.B otftotfm
will select.  An alternate is used if it matches at least one of the
.B \-\-include
patterns, and none of the
.B \-\-exclude
patterns.  Each pattern applies to all following features, except that the
.B \-\-clear
option clears any accumulated patterns.  The
.BI \-\-alternates\-filter " pattern"
option acts like
.B \-\-clear\-alternates
followed by
.BI \-\-include\-alternates " pattern\fR. "
For pattern syntax, see GLYPH PATTERNS, below.
.Sp
OpenType fonts can have many alternates per character, most of which aren't
interesting.  For example, the character "a" in WarnockPro-Regular has five
alternates, "ordfeminine", "Asmall", "asuperior", "a.end", and
"orn.013".  The
.B \-\-altselector\-char
option lets you cycle through these alternates, but it's better to leave
out the ones you don't want, to avoid overfull encodings.  Thus, if you were
only interested in ".end" variants, you might supply an
\&'\-\-include\-alternates="*.end"'
option.
.Sp
In the command line below, the \&'*.end' pattern will apply to "aalt"
alternates, but not to "salt" alternates.
.nf
    \fBotftotfm\fR \fB\-f\fRsalt \fB\-\-include\-alternates\fR="*.end" \fB\-f\fRaalt \.\.\.
.fi
'
.Sp
.TP 5
.BI \-\-ligkern= command
Add a LIGKERN
.IR command
to the encoding.  For example, \&'\fB\-\-ligkern\fR "T {L} h"' suppresses any
T_h ligature in the font.  You can supply multiple
.B \-\-ligkern
options.  See ENCODINGS, below.
'
.Sp
.TP 5
.BI \-\-position= command
Add a POSITION
.IR command
to the encoding.  For example, \&'\fB\-\-position\fR "T 10 0 20"' adds ten
units of space to either side of the "T" character.  You can supply
multiple
.B \-\-position
options.  See ENCODINGS, below.
'
.Sp
.TP 5
.BI \-\-unicoding= command
Add a UNICODING
.IR command
to the encoding.  For example, \&'\fB\-\-unicoding\fR "pi1 =: uni03D6"' tells
.B otftotfm 
to encode "/pi1" as U+03D6 GREEK PI SYMBOL.  You can supply multiple
.B \-\-unicoding
options.  See ENCODINGS, below.
'
.Sp
.TP 5
.BI \-\-no\-encoding\-commands
Ignore any LIGKERN and/or UNICODING commands in the encoding file.
'
.Sp
.TP 5
.BI \-\-no\-default\-ligkern
Don't include
.BR otftotfm 's
default LIGKERN commands.
'
.Sp
.TP 5
.BI \-\-coding\-scheme= scheme
Add a CODINGSCHEME to the encoding.  See ENCODINGS, below.
'
.Sp
.TP 5
.BI \-\-warn\-missing
Warn about encoded characters not supported by the font.  See the
WARNMISSING command in ENCODINGS, below.
'
.Sp
.TP 5
.BI \-\-literal\-encoding= encoding
Select the
.M dvips 1
encoding used for the font.  No glyph substitutions will be permitted, so
the output encoding will equal the input encoding (and 
.B otftotfm
will not generate an output encoding).
'
.Sp
.TP 5
.BI \-\-base\-encodings= file
.B Experts only.
Allow the output font to refer to existing "base" fonts.  This can greatly
reduce the number of base fonts generated by
.BR otftotfm ". "
Each line in the
.I file
argument contains a TeX font name (as for
.BR \-\-name )
and a corresponding literal encoding file (as for
.BR \-\-literal\-encoding );
for example:
.nf
    WarnoProReg\-\-eka eka
    WarnoProReg\-\-exp1 exp1
.fi
The named fonts must have been created by prior runs of
.B otftotfm
on the same input OpenType font, with the same
.BR \-\-extend
and
.BR \-\-slant
options as the current run.  The current output font will refer to glyphs
from the named base fonts when possible.  If the base fonts cover all
glyphs required by the output font,
.B otftotfm
won't generate any new base fonts at all.  The
.I file
can also refer to dotless-J fonts using the following syntax:
.nf
    WarnoProReg\-\-lcdfj \- dotlessj
.fi
'
.PD
'
'
.SS Automatic Mode Options
'
.PD 0
.TP 5
.BI \-a "\fR, " \-\-automatic
Select automatic mode.
'
.Sp
.TP 5
.BI \-v " vendor\fR, " \-\-vendor= vendor
Set the font vendor name, which is used to locate files within the TDS.
Defaults to "lcdftools".
.Sp
In automatic mode, TeX and friends will generally find required font files
independently of the vendor you select.
'
.Sp
.TP 5
.BI \-\-typeface= typeface
Set the font typeface name, which is used to locate files within the TDS.
Defaults to the current font's family name with unsuiable characters
removed.
'
.Sp
.TP 5
.BI \-\-no\-type1
Do not use
.M cfftot1 1
to create Type 1 fonts corresponding to the OpenType input fonts.
'
.Sp
.TP 5
.BI \-\-no\-dotlessj
Do not use
.M t1dotlessj 1
to create a special dotless-j font when the input font doesn't have
dotless-j.
'
.Sp
.TP 5
.BI \-\-no\-truetype
Do not install TrueType-flavored fonts.
'
.Sp
.TP 5
.BI \-\-type42
Install TrueType-flavored fonts in translated Type 42 format.
'
.Sp
.TP 5
.BI \-\-no\-updmap
Do not run an
.M updmap 1
program.  This can be useful if you're installing a bunch of fonts; it is
much faster to run
.B updmap
once, at the end, than to run it once per font.
.PD
'
'
.SS Output Options
.PD 0
.TP 5
.BI \-n " texname\fR, " \-\-name= texname
Set the TeX name of the output font, which is used in font map files and,
in automatic mode, to generate the output filename.  The default is derived
from the OpenType font's name and the features you selected.
'
.Sp
.TP 5
.BI \-p "\fR, " \-\-pl
Output human-readable PL and VPL metrics, not binary TFM and VF metrics.
Note: 
.BR Otftotfm 's
PL and VPL output files are legal, but the
.B fontinst
program may not accept them (it has a picky parser).  Make sure to supply a
.BR \-\-coding\-scheme ;
if that doesn't help, run the TFM output through
.M tftopl 1 .
'
.Sp
.TP 5
.BI \-\-no\-virtual
Do not generate virtual fonts (VFs and VPLs). 
.B Otftotfm
will warn if the selected font features cannot be implemented without
virtual fonts.
'
.Sp
.TP 5
.BI \-\-no\-encoding
Do not generate an encoding file.
'
.Sp
.TP 5
.BR \-\-output\-encoding [=\fIfile\fR]
Only generate an encoding file; do not generate any other output.  The
encoding file is written to
.IR file , 
or to standard output if no
.I file
argument is supplied.
'
.Sp
.TP 5
.BI \-\-no\-map
Do not generate a font map line for the font.
'
.\" .Sp
.\" .TP 5
.\" .BI \-\-base\-name name
.\" Experts only: Set the TeX name of the "base" output font.  When
.\" .B otftotfm
.\" needs to make a virtual font (because of font features and/or
.\" letterspacing), it must generate at least two TFM metrics files, one for
.\" the base font and one for the virtual font.  In some cases, multiple
.\" virtual fonts can share the same base metrics, reducing the number of
.\" installed metrics files.  This option lets you explicitly set the name of
.\" the base output font independently from the main output font, and thus
.\" force fonts to share base metrics.  The default base name is derived from
.\" the TeX name, with "\f(CW\-\-base\fR" appended.
.PD
'
'
.SS File Location Options
.PD 0
.TP 5
.BI \-\-tfm\-directory= dir
.TP 5
.BI \-\-pl\-directory= dir
.TP 5
.BI \-\-vf\-directory= dir
.TP 5
.BI \-\-vpl\-directory= dir
.TP 5
.BI \-\-encoding\-directory= dir
.TP 5
.BI \-\-type1\-directory= dir
.TP 5
.BI \-\-truetype\-directory= dir
.TP 5
.BI \-\-type42\-directory= dir
.TP 5
.BI \-\-directory= dir
Set the directory used for various output types.  Each directory may be set
by an environment variable, and defaults to a TDS directory in automatic
mode, or to "." otherwise.  Environment variable names and default TDS
locations are described in the Automatic Mode section above.  The
.B \-\-directory
option sets the default directory for all output types.
'
.Sp
.TP 5
.BI \-\-map\-file= filename
Set file in which
.B otftotfm
will write a font map
line for the font.  The default is the standard output in manual mode, and
"TEXMF/fonts/map/dvips/\fIvendor\fR/\fIvendor\fR.map" (or
"TEXMF/dvips/\fIvendor\fR/\fIvendor\fR.map" on older installations) in
automatic mode.
.PD
'
'
.SS Miscellaneous Options
.PD 0
.TP 5
.BI \-\-glyphlist= file
Use
.I file
as a Adobe glyph list, which helps translate glyph names to Unicode code
points.  Give multiple options to include multiple files.
See ENCODINGS, below, for more information.
'
.Sp
.TP 5
.BR \-V ", " \-\-verbose
Write progress messages to standard error.
'
.Sp
.TP 5
.BR \-\-no\-create
Do not create or modify any files.  Instead, write messages about the
program's hypothetical progress to standard error.
'
.Sp
.TP 5
.BR \-\-force
Generate all files, even if it looks like versions are already installed.
'
.Sp
.TP 5
.BR \-q ", " \-\-quiet
Do not generate any error messages.
'
.Sp
.TP 5
.BI \-\-kpathsea\-debug= flags
Set path searching debugging flags.  See the
.I Kpathsea
manual for details.
'
.Sp
.TP 5
.BR \-h ", " \-\-help
Print usage information and exit.
'
.Sp
.TP 5
.BR \-\-version
Print the version number and some short non-warranty information and exit.
.PD
'
.SH ENCODINGS
.B Otftotfm
interprets encoding files as Unicode.  For example, say an input encoding
has "/dotlessi" at position 10.
.B Otftotfm
detects that position 10 should contain Unicode character U+0131 LATIN
SMALL LETTER DOTLESS I, and uses the font's glyph for that character
(possibly modified by any active features).  The selected glyph might not
be named "dotlessi"; only the Unicode value matters.
.PP
.B Otftotfm
assigns Unicode values to glyph names using a table published by Adobe (SEE
ALSO has a reference), with extensions for TeX.  For more fine-grained
control, add UNICODING commands to the input encoding file.  These commands
have the following format:
.nf
    % UNICODING \fIglyph\fR =: \fIchoice1\fR [\fIchoice2\fR ...] ;
.fi
This tells
.B otftotfm
that the glyph named
.I glyph
translates into the first Unicode value in the
.I choice
list that has a character in the font.  \fIGlyph\fR and the
.IR choice s
are PostScript glyph names; the initial "%" sign is required; and each
UNICODING line can contain multiple commands, separated by spaced
semicolons.  For example,
.nf
    % UNICODING pi1 =: uni03D6 ;
.fi
encodes the character "/pi1" as U+03D6 GREEK PI SYMBOL,
and
.nf
    % UNICODING Delta =: uni0394 uni2206 ;
.fi
makes U+0394 GREEK CAPITAL LETTER DELTA preferred to
U+2206 INCREMENT as an encoding for "/Delta".  You can also supply
glyph names:
.nf
    % UNICODING Delta =: Deltagreek Delta ;
.fi
A mapping with no Unicode values removes that glyph from the input
encoding.  For instance, this erases any f-ligature characters from the
encoding:
.nf
    % UNICODING ff =: ; fi =: ; fl =: ; ffi =: ; ffl =: ;
.fi
The slots are available for
.BR otftfm 's
own use, for example for other characters required by the font.  (If the
f-ligatures themselves are required by the font, for instance by a \&'liga'
feature, then they will be stored into their old slots when possible.)  Map
a glyph to \&'emptyslot' if you don't want
.B otftotfm
to use the slot.  For example, this will leave the \&'ff' slot unused if
the font has no \&'ff' glyph:
.nf
    % UNICODING ff =: ff emptyslot ;
.fi
(Note that most OpenType fonts provide a visible representation for unused
encoding slots, namely a box with an X inside.)
.PP
LIGKERN comments in the encoding can add ligatures and inhibit kerns, as in
.M afm2tfm 1 .
To add a ligature, say:
.nf
    % LIGKERN \fIglyph1\fR \fIglyph2\fR =: \fIresult\fR ;
.fi
The "=:" operator indicates a normal ligature, where both the input glyphs
are removed and replaced by
.IR result .
To preserve the left-hand glyph, for an effect like "\fIglyph1\fR
\fIglyph2\fR =: \fIglyph1\fR \fIresult\fR", use "|=:" instead; to preserve
the right-hand glyph, use "=:|".
.\" The other five ligature operators are not yet supported.
To remove all kerns between two characters, say:
.nf
    % LIGKERN \fIglyph1\fR {} \fIglyph2\fR ;
.fi
A "*" matches any character, so
.nf
    % LIGKERN a {} * ;
.fi
removes all kerns with "a" as the left-hand character, and
.nf
    % LIGKERN * {} * ;
.fi
removes all kerns.
.PP
.B Otftotfm
also supports extended syntax for setting kern values and inhibiting
ligatures.  To add an \fIn\fR-unit kern between two glyphs, say:
.nf
    % LIGKERNX \fIglyph1\fR {\fIn\fR} \fIglyph2\fR ;
.fi
where \fIn\fR is an integer.  This:
.nf
    % LIGKERNX \fIglyph1\fR {L} \fIglyph2\fR ;
.fi
inhibits any ligature between
.I glyph1
and
.IR glyph2 .
"{LK}" and "{KL}" inhibit both ligatures and kerns.
.PP
You can set the
.B \-\-boundary\-char
and
.B \-\-altselector\-char
from an encoding file with commands like this:
.nf
    % LIGKERN || = \fIboundarychar\fR ;
    % LIGKERNX ^^ = \fIaltselectorchar\fR ;
.fi
As with UNICODING, each LIGKERN or LIGKERNX line can contain multiple
commands, separated by spaced semicolons.
.PP
.B Otftotfm
has a default set of eight ligatures, namely:
.nf
    space l =: lslash ; space L =: Lslash ;
    question quoteleft =: questiondown ; exclam quoteleft =: exclamdown ;
    hyphen hyphen =: endash ; endash hyphen =: emdash ;
    quoteleft quoteleft =: quotedblleft ;
    quoteright quoteright =: quotedblright
.fi
LIGKERN commands in the encoding file and
.B \-\-ligkern
options can override these defaults, or supply the
.B \-\-no\-default\-ligkern
option to turn them off.
.PP
The POSITION command shifts a glyph within its bounding box.  The syntax is
.nf
    % POSITION \fIglyph\fR \fIpdx\fR \fIpdy\fR \fIadx\fR ;
.fi
This will add
.I pdx
units of space to
.IR glyph 's
left edge; raise it up by
.I pdy
units; and add
.I adx
units to its width.  For example, to add 10 units of space to either side
of the "T" glyph, supply
.nf
    % POSITION T 10 0 20
.fi
To move the "degree" symbol up by 20 units, supply
.nf
    % POSITION degree 0 20 0
.fi
.PP
The CODINGSCHEME command specifies the coding scheme for fonts using this
encoding.  This is a string, less than 40 characters long and containing no
parentheses, that classifies the encoding for TeX's purposes.  Sample
coding schemes include "TEX TEXT", "TEX MATH ITALIC", and "EXTENDED TEX
FONT ENCODING - LATIN".  For example:
.nf
    % CODINGSCHEME EXTENDED TEX FONT ENCODING - LATIN
.fi
Most tools ignore the coding scheme; fontinst is an exception.
.B Otftotfm
uses the encoding's PostScript name for the default coding scheme.
.PP
Finally, the WARNMISSING command makes any glyphs not supported by the
input font appear as black boxes.  The
.M dvips 1
processor will also print a warning when encountering these glyphs.  For
example:
.nf
    % WARNMISSING yes
.fi
.PP
The
.BR \-\-unicoding ,
.BR \-\-ligkern ,
.BR \-\-position ,
.BR \-\-coding\-scheme ,
and
.B \-\-warn\-missing
options add UNICODING, LIGKERN/LIGKERNX, POSITION, CODINGSCHEME, and
WARNMISSING commands to an encoding, and can override commands in the
encoding itself.  Some common encoding files have commands that are
inappropriate for OpenType fonts; for example, "t1.enc" hard-codes
f-ligatures, which can cause problems with small-cap fonts.  Supply the
.B \-\-no\-encoding\-commands
option to ignore all commands from the encoding file.  Commands from
options like
.B \-\-ligkern
are processed in any case.
'
.SS New Glyphs
.PP
New glyphs, such as ligatures and contextual substitutions, are added to
the encoding in any empty spaces, using their original locations when
possible.  If the encoding doesn't have enough space for all new glyphs,
shorter ligatures composed of unaccented letters get precedence.
'
.SS Synthetic Glyphs
.PP
.B Otftotfm
can synthesize some glyphs using virtual font manipulations, if a required
glyph is not available in the input font. Specifically, it will synthesize:
.Sp
.PD 0
.TP 22
cwm
TeX's compound word mark (a zero-width "strut" rule with height equal to the font's x-height)
.TP
ascendercompwordmark
"cwm" with height equal to the font's ascenders
.TP
capitalcompwordmark
"cwm" with height equal to the font's capitals
.TP
visualspace
A square cup used to represent spaces
.TP
dotlessj
A dotless "j", synthesized with
.M t1dotlessj 1
.TP
dblbracketleft
Kerned version of "[["
.TP
dblbracketright
Kerned version of "]]"
.TP
bardbl
The parallel symbol "||"
.TP
asteriskmath
Vertically-centered "*"
.TP
ringfitted
Ring accent centered on the width of "A"
.TP
twelveudash
2/3-em-wide dash
.TP
threequartersemdash
3/4-em-wide dash
.TP
centigrade
"(degrees)C"
.TP
interrobang
Combined "?!" symbol
.TP
interrobangdown
Inverted interrobang
.TP
pertenthousand
Per-ten-thousand sign (% with two extra 0s)
.TP
IJ
"IJ" ligature
.TP
ij
"ij" ligature
.TP
Germandbls
"SS" (a capital sharp-s)
.TP
SSsmall
Small-capital version of "SS"
.TP
FFsmall
Small-capital version of "FF"
.TP
FIsmall
Small-capital version of "FI"
.TP
FLsmall
Small-capital version of "FL"
.TP
FFIsmall
Small-capital version of "FFI"
.TP
FFLsmall
Small-capital version of "FFL"
.PD
'
'
.SH "GLYPH PATTERNS"
.LP
The
.BR \-\-include\-subs 
and
.BR \-\-include\-alternates
options, and their
.B \-\-exclude
and
.B \-\-*\-filter
variants, accept the following types of pattern.
.Bp
Glyph names.  Example: "Aacute".  For PostScript-flavored fonts, use
.M otfinfo 1 's
.B \-g
option to see a font's glyph names, and "\fBcfftot1\fR \fIfont\fR.otf |
\fBt1testpage\fR" to generate a PostScript file showing each glyph.
.Bp
Glyph name patterns using the shell-style glob-matching rules: "*" matches
any number of characters, "?" matches any single character, and "[...]"
matches any character in a set.  Example: "*.end".
.Bp
Unicode category properties in angle brackets.  Examples: "<Letter>",
"<UppercaseLetter>", "<Lu>".  The complete list of both short and long
names: Letter/L, UppercaseLetter/Lu, LowercaseLetter/Ll,
TitlecaseLetter/Lt, ModifierLetter/Lm, OtherLetter/Lo; Number/N,
DecimalNumber/Nd, LetterNumber/Nl, OtherNumber/No; Punctuation/P,
ConnectorPunctuation/Pc, DashPunctuation/Pd, OpenPunctuation/Ps,
ClosePunctuation/Pe, InitialPunctuation/Pi, FinalPunctuation/Pf,
OtherPunctuation/Po; Symbol/S, MathSymbol/Sm, CurrencySymbol/Sc,
ModifierSymbol/Sk, OtherSymbol/So; Mark/M, SpacingMark/Mc,
EnclosingMark/Me, NonspacingMark/Mn; Separator/Z, SpaceSeparator/Zs,
LineSeparator/Zl, ParagraphSeparator/Zp; Other/C, Surrogate/Cs, Format/Cf,
Control/Cc, PrivateUse/Co, Unassigned/Cn.  Category values current as of
Unicode 4.0.
.Bp
Unicode ranges.  Example: "U+007f-U+008C".
.PP
The "!" prefix negates a pattern, and you can separate multiple patterns by
spaces.
'
.SH "FEATURE DIRECTORY"
.LP
This section lists features common to Western OpenType fonts and describes
how
.B otftotfm 
handles them for common fonts.  Please send the author mail if
.B otftotfm
does not handle a feature you need, or you believe it handles some feature
incorrectly.
.Sp
.PD 0
.TP 5
.IR aalt ", Access All Alternates"
Lets the user choose between all available alternate forms for a character.
This includes things like superscript and subscript variants, different
styles (swash, for example), and even ornaments.  The
.BR \-\-altselector\-feature= aalt
option can help an
.BR \-\-altselector\-char
provide useful access to alternates, but the
.I aalt
feature isn't usually useful on its own.  Try the
.IR salt " and " calt
features instead.
.TP 5
.IR c2sc ", Small Capitals From Capitals"
Replaces capital letters with small capitals: a sort of converse of the
more conventional
.I smcp
feature, which replaces lower-case letters with small capitals.  Supported.
.TP 5
.IR calt ", Contextual Alternates"
Lets the user choose between context-appropriate swash forms for each
character.  For example, given the word "DREW" in a cursive typeface, the "R
E W" might be translated to calmer forms than the initial "D".  There may be
more than one choice for a given letter, in which case the user should be
able to select among them.  TeX can't support complex contextual alternates,
or alternate selection, but 
.B otftotfm 
supports some fonts quite well.  The input encoding should have lots of
empty space for variants, and it should specify a boundary character.  See
also
.IR cswh .
.TP 5
.IR case ", Case-Sensitive Forms"
Shifts punctuation marks up to a position that works well with
all-capital-letter sequences.  For example, the hyphen character, which
generally centers vertically on the x-height, is raised up to center
vertically on a capital letter.  Also replaces text figures with lining
figures, and accent marks with forms more appropriate for capitals.
Supported.
.TP 5
.IR cpsp ", Capital Spacing"
Adds a bit of space on either side of each capital letter.  Supported.
(However, the OpenType tag registry suggests that
.I cpsp
be on by default, but applying to all-caps text only; TeX cannot easily
implement that contextual intelligence.)
.TP 5
.IR cswh ", Contextual Swash"
Lets the user choose between context-appropriate swash forms for each
character.  For example, in the words "Ab AC", the first "A" might be
translated to a swash form, while the second might not.  There may be more
than one choice for a given letter, in which case the user should be able
to select among them.
.B Otftotfm
supports some fonts quite well.  The input encoding should have lots of
empty space for swash variants, and it should specify a boundary
character.  See also
.IR calt " and " swsh .
.TP 5
.IR dlig ", Discretionary Ligatures"
Activates uncommon ligatures, such as "c_t", "s_p", and "s_t".  Supported.
.TP 5
.IR dnom ", Denominators"
Replaces digits and some punctuation marks with smaller forms sitting on
the baseline, intended for fraction denominators.  Supported.
.TP 5
.IR fina ", Terminal Forms"
Substitutes appropriate forms for letters occurring at the ends of words.
This feature doesn't select swash variants; it's intended for normal use,
and the specification recommends that it be on by default.  Partially
supported: TeX will only treat spaces as the ends of words, where a correct
implementation would probably include punctuation too.  See
.IR cswh
for selecting swash variants active at the ends of words.
.TP 5
.IR frac ", Fractions"
Replaces simple sequences like "1/2" with nice-looking fractions.
Supported, but beware: many fonts will translate "11/32" into "1" + "1/3" +
"2".
.TP 5
.IR hist ", Historical Forms"
Replaces characters with historical variants.  Usually, this means at least
translating regular "s" to long "s".  Supported.
.TP 5
.IR kern ", Kerning"
Adjusts the space between characters (pair kerning).  Generally supported,
and you should probably turn it on.  As a special case, "\fB\-f\fRkern" can
also read kerning information from the "kern" table in conventional
TrueType fonts.
.TP 5
.IR liga ", Standard Ligatures"
Activates common ligatures, such as "f_f", "f_i", "f_f_j", and (in some
Adobe fonts) "T_h".  Generally supported, and you should probably turn it
on.
.TP 5
.IR lnum ", Lining Figures"
Uses lining figures, the set of digits that are all about as high as
capital letters.
Supported.  Compare
.IR onum ;
see also
.IR pnum
and
.IR tnum.
.TP 5
.IR numr ", Numerators"
Replaces digits and some punctuation marks with smaller, raised forms
intended for fraction numerators.  Supported, but not usually useful.
.TP 5
.IR onum ", Oldstyle Figures"
Uses old-style figures, also known as text figures.  This is the set of
digits that have ascenders and descenders like lower-case letters.
Supported.  Compare
.IR lnum ;
see also
.IR pnum
and
.IR tnum .
.TP 5
.IR ordn ", Ordinals"
Designed for Spanish and French.  Replaces ordinal numbers, such as "2.o",
with forms where the "o" is raised, and replaces the sequence "No" with an
integrated glyph.  Supported.
.TP 5
.IR ornm ", Ornaments"
Replaces some alphabetic characters in the font with ornaments, and links
the bullet character to a set of all bullet-like ornaments, from which the
user can choose.  Partially supported: TeX can handle alphabetic
substitutions, but not bullet choice.
.TP 5
.IR pnum ", Proportional Figures"
Digits will have different widths.  Supported.  Compare
.IR tnum ;
see also
.IR lnum
and
.IR onum.
.TP 5
.IR salt ", Stylistic Alternates"
Lets the user choose between stylistic alternate forms for a character.
The
.BR \-\-altselector\-char
mechanism provides useful access to this feature.  If you turn on
.IR salt
globally, 
.B otftotfm
takes the first alternate form whenever there's more than one choice.  See
also
.IR aalt
and
.IR ss01 ;
.IR salt
is generally more useful than
.IR aalt
for TeX, since it refers exclusively to stylistic alternates.
.TP 5
.IR sinf ", Scientific Inferiors"
Replaces digits and some punctuation marks with smaller, lowered forms
intended for subscripts.  Supported.  Compare
.IR subs .
.TP 5
.IR size ", Optical Size"
This feature stores information about the range of optical sizes for which
the font was intended.  There is no point in selecting it with 
.BR otftotfm ,
since it should not change the font's appearance in any way.
.TP 5
.IR smcp ", Small Capitals"
Replaces lower-case letters with small capitals.  Supported.  Compare
.IR c2sc .
.TP 5
.IR ss01 - ss20 ", Stylistic Sets 1-20"
Replaces characters with a uniform set of stylistic alternates.  Differs
from features like
.I salt
in that a Stylistic Set is uniform: an
.I ssXX
feature should never involve selection from a set of possible alternate
characters.  Supported.
.TP 5
.IR subs ", Subscript"
Replaces characters with smaller, lowered forms intended for subscripts.
Supported.  Compare
.IR sinf ;
some fonts support
.I sinf
but not
.IR subs .
.TP 5
.IR sups ", Superscript"
Replaces digits, some punctuation marks, and some lower-case letters with
smaller, raised forms intended for superscripts.  Supported.
.TP 5
.IR swsh ", Swash"
Activates all swash forms for each character. There may be more than one
swash form, in which case 
.B otftotfm
will pick the first one listed.  Supported, except that swash variants
other than the first are inaccessible.  Note that some fonts with swash
variants support the
.I cswh
feature exclusively.
.TP 5
.IR tnum ", Tabular Figures"
All digits will have the same width, so that tables and the like will align
visually.  Supported.  Compare
.IR pnum ;
see also
.IR lnum
and
.IR onum.
.TP 5
.IR zero ", Slashed Zero"
Replaces the zero character with a slashed zero.  Supported.
.PD
'
.SH "DIAGNOSTICS AND TROUBLESHOOTING"
'
.TP 5
no writable directory found in $TEXMF
'
.B Otftotfm
could not find a writable directory in your $TEXMFVAR or $TEXMF path.  Did
you create a
.I $HOME/.texmf-var
or
.I $HOME/texmf
directory?  If so, run the command "kpsewhich \-\-expand\-path='$TEXMF'" to
verify that directory is not being found.  You may need to set your TEXMF
environment variable, to \&'{!!'"$HOME"'/texmf,!!$TEXMFMAIN}', for instance
(note the different kinds of quotes; on my machine, this expands to
\&'{!!/home/kohler/texmf,!!$TEXMFMAIN}').
'
.TP 5
\&'\fIchar\fR' has no encoding, ignoring kern removal
.PD 0
.TP 5
(or ligature removal, lig/kern removal, or ligature)
.PD
'
These messages indicate a slight problem with your encoding file: one of
the LIGKERN commands referred to a character not present in the encoding.
This might be due to a misspelling in the LIGKERN command or the encoding
file, or it might be an oversight.  Either fix the encoding file or ignore
the warning.
'
.TP 5
can't map \&'\fIchar\fR' to Unicode
'
Another encoding file problem: One of the glyph names in an UNICODING block
could not be converted to Unicode.  This is problematic since UNICODING
exists wholly to translate glyph names into Unicode.  Fix the encoding file
or ignore the warning.
'
.TP 5
not enough room in encoding, ignoring \fIN\fR glyph(s) ...
'
There wasn't space in the encoding for all the glyphs referred to by the
features you selected.  For example, maybe the font had more ligatures than
there were empty slots in the encoding.  Fix this warning by selecting fewer
features, or by using an encoding with more empty slots, such as the 7t.enc
encoding distributed with 
.BR otftotfm .
'
.TP 5
The \&'\fB\-a\fR' option did not install my font correctly.
'
Try again with the \&'\fB\-\-verbose\fR' option, which causes
.BR otftotfm
to explain its behavior.  Note that by default,
.BR otftotfm
will not re-install files already present in your system's TeX search paths
(in the current directory, for instance).  Use \&'\fB\-\-force\fR' to
override this behavior.
'
.SH "FREQUENTLY ASKED QUESTIONS"
.TP 5
How can I get a small-caps "SS" in place of the German sharp-S?
'
Supply the option \&'\fB\-\-unicoding\fR "germandbls =: SSsmall"'.
'
.TP 5
How can I prevent f-ligatures from forming in a small-caps font?  
'
This should happen automatically, but some overzealous encoding files add
f-ligatures even when the font doesn't request them.  Try the
"\fB\-\-no\-encoding\-commands\fR" option if this is a problem for you.
'
.TP 5
\fBOtftotfm\fR seems to take a long time.
'
Use the
.B \-V
option to see what it's doing.  Often the culprit is the
.M updmap 1
program; if you're planning to run
.B otftotfm
multiple times, give it the
.B \-\-no\-updmap
option and run
.B updmap
manually when you're done.
'
.TP 5
How can I refer to the different forms of phi?
'
\fBOtftotfm\fR follows TeX practice and widely-distributed TeX encoding
vectors, so "/phi" in an input encoding vector should map to a "straight"
phi and "/phi1" should map to a "loopy" phi.  Note that TeX practice
differs from the PostScript standard naming conventions, in which "/phi" is
"loopy" and "/phi1" is "straight"; this means that \fBotftotfm\fR may map
"/phi" in an input encoding vector to a font's "/phi1" glyph, and vice
versa.  Perhaps most unambiguously, you can use "/uni03D5" for the
"straight" form and "/uni03C6" for the "loopy" form.
'
.TP 5
How can I get lining figures (that is, normal line-height digits) with small caps ('\fB\-f\fRsmcp')?
'
Many fonts use old-style figures by default with small caps. Since the
default is not specified, it's wise to explicitly supply \&'\fB\-f\fRlnum' or
\&'\fB-f\fRonum'.
'
.SH "BUGS"
.\" .LP
.\" Presumably some context-sensitive positionings and ligatures could be
.\" implemented with TeX's boundary character, but 
.\" .B otftotfm
.\" doesn't do that yet.
.LP
See the documentation for 
.B \-\-pl
above if you have problems running
.BR otftotfm 's 
output through
.BR fontinst .
'
.SH "SEE ALSO"
.LP
.M pltotf 1 ,
.M tftopl 1 ,
.M vptovf 1 ,
.M afm2tfm 1 ,
.M dvips 1 ,
.M cfftot1 1 ,
.M otfinfo 1 ,
.M t1dotlessj 1 ,
.M t1testpage 1 ,
.M ttftotype42 1 ,
.M kpsewhich 1 ,
.M updmap 1
.LP
.I "Adobe Type 1 Font Format"
.LP
Adobe Technical Notes #5176,
.IR "The Compact Font Format Specification" ,
and #5177,
.I "The Type 2 Charstring Format"
.LP
.IR "OpenType Specification" ,
Version 1.4
.LP
.IR "A Directory Structure for TeX Files" ,
http://www.tug.org/tds/
.LP
.IR "Kpathsea: A library for path searching" ,
http://www.tug.org/kpathsea/
.LP
Sivan Toledo,
.IR "Exploiting Rich Fonts" ,
TUGboat 21(2), 2000,
http://www.tug.org/TUGboat/Articles/tb21-2/tb67tole.pdf
.LP
Michel Goossens, Frank Mittelbach, and Alexander Samarin,
.IR "The LaTeX Companion"
(for information on the .fd file format)
.LP
Adobe Systems, "Unicode and Glyph Names".  Refers to the glyphlist.txt file
used to translate glyph names to Unicode code points.
http://partners.adobe.com/public/developer/opentype/index_glyph.html
'
.SH AUTHOR
Eddie Kohler (ekohler@gmail.com)
.PP
Thanks to Karl Berry, Marco Kuhlmann, Adam Lindsay, Bruce D'Arcus, Thomas
Esser, Claire Connelly, Nelson H.F. Beebe, and Ryuji Suzuki for
suggestions, bug reports, and help.  Particular thanks to Achim Blumensath
and Michael Zedler for suggestions and patches, some of them extensive.