summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/fontinst/base/fisource.tex
blob: b5a5cab7e76b2462126a965996e995be98ba6bcc (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
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
%
% Copyright 1998, 1999, 2000 the fontinst maintenance team and any 
% individual authors listed elsewhere in this file.  All rights reserved.
% 
% This file is part of the fontinst system version 1.9.
% -----------------------------------------------------
% 
% It may be distributed under the terms of the LaTeX Project Public
% License, as described in lppl.txt in the base LaTeX distribution.
% Either version 1.0 or, at your option, any later version.
% 
\documentclass{ltxdoc}
\usepackage[dolayout,fileispart]{fisource}

\usepackage{longtable}

\RecordChanges
\EnableCrossrefs

\IndexPrologue{%
   \section*{Index}%
   \addcontentsline{toc}{section}{Index}%
   \markboth{Index}{Index}%
   Compound numbers (numbers with a hyphen) refer to a code line, and 
   the letter that is the first part of such a number specifies the 
   source file the code line is in, as explained by the file key below. 
   Simple numbers refer to pages. Numbers written in italics refer to
   places where the corresponding entry is described, the ones 
   underlined to where it is defined, and the rest to where it is used.
}
\GlossaryPrologue{%
   \section*{Change History}%
   \addcontentsline{toc}{section}{Change History}%
   \markboth{Change History}{Change History}%
}
   

\makeatletter
\newcommand{\offindex}{\let\index\@gobble}

\newcommand{\consumption}{%
   \begingroup
      \endlinechar=`\&\relax
   \expandafter\endgroup\consumption@i
}
\def\consumption@i#1#2{%
   \ifhmode{\parskip=\z@\@plus\p@\relax\par}\fi
   Time elapsed: #1\,s\par
   \tabskip=\leftmargin \advance \tabskip 1em\relax
   \halign{&\hfil##\ \tabskip=\z@skip&##\hfil\tabskip=1em\cr
     \omit\span \textbf{Stacks}&\omit\span \textbf{Others}\cr
     \consumption@ii#2\@nil
   }%
}
%  #1 = number of strings used
%  #3 = string characters used
%  #5 = words of memory used
%  #7 = number of multiletter control sequences used
%  Other parameters are garbage.
\def\consumption@ii#1 #2&#3 #4&#5 #6&#7 #8&#9&{%
   \consumption@iii{{#1}{#3}}{{#5}{#7}}%
}
\def\consumption@iii#1#2#3&#4i,#5n,#6p,#7b,#8s#9\@nil{%
   #4& input sources& \@secondoftwo#2& multiletter control 
     sequences\cr
   #6& parameters& \@firstoftwo#1& strings\cr
   #7& buffer characters& \@secondoftwo#1& string characters\cr
   #8& saved values& \@firstoftwo#2& main memory words\cr
}
\makeatother

\newenvironment{smalldes}{%
   \list{}{%
      \setlength\labelwidth{0pt}%
      \setlength\itemindent{-\leftmargin}%
      \setlength\listparindent{1em}%
      \setlength\parsep{0pt}%
      \setlength\itemsep{0pt plus 1pt}%
      \setlength\topsep{\itemsep}%
      \let\makelabel\descriptionlabel
   }%
}{\endlist}

% \includeonly{}
\iffalse
\MakeShortVerb{\|}
\fi

\title{The \package{fontinst} utility}
\author{Alan Jeffrey, Sebastian Rahtz, Ulrik Vieth, Lars Hellstr\"om}

\begin{document}
\maketitle
\tableofcontents
\clearpage

\part*{About the \package{fontinst} package}
\addcontentsline{toc}{part}{The \package{fontinst} documentation}

This document implements and describes version~1.9 of 
\package{fontinst}.



\section{Files}

\subsection{Source files}

The source for \package{fontinst} is currently split on the six 
source files \texttt{fibasics.dtx}, \texttt{ficommon.dtx}, 
\texttt{fimain.dtx}, \texttt{ficonv.dtx}, \texttt{filtfam.dtx}, and 
\texttt{fimapgen.dtx}.


\subsection{Generated files}

By running the \package{docstrip} installation script 
\texttt{fontinst.ins}, the following files are generated:
\begin{description}
  \item[\texttt{fontinst.sty}] This is the executable file that 
    contains all the commands that set up the \package{fontinst} 
    utility for use.
  \item[\texttt{xfntinst.sty}] This is a variant of 
    \texttt{fontinst.sty} in which the |\latin|\-|family| command 
    behaves differently with respect to from which fonts the digits 
    are picked (see below).
  \item[\texttt{cfntinst.sty}] This is a variant of 
    \texttt{fontinst.sty} which supports the old way of selecting 
    boundarychar for fonts (i.e., by setting the integer 
    |boundarychar|). It requires a bit more memory than 
    \texttt{fontinst.sty} does.
  \item[\texttt{fontinst.ini}] This file contains some very basic 
    initialization code. It is used in case \package{fontinst} is used 
    under ini\TeX\ without a preloaded format.
  \item[\texttt{finstmsc.sty}] This file contains the routines for 
    automatic map file generation, which can now generate map files 
    for the \package{dvips} and \package{dvipdfm} drivers. The system 
    is extendable, so users interested in generating map files for 
    other drivers can extend the mapfile writer's capabilities by 
    adding code to their \texttt{finstmsc.rc} files. \emph{Contributions 
    of such code is welcome}. This file also contains some seldom-used 
    code (the ENC to ETX conversion) that has been broken off from 
    the main \package{fontinst} utility, as it almost always just sat 
    there and used up space for no good reason.
  \item[\texttt{fontdoc.sty}] This file contains the \package{fontdoc} 
    package, which can be used to typeset encoding and metric files.
  \item[\texttt{csc2x.tex}] This file contains the reglyphing commands 
    that set up the common caps-and-small-caps to expert names 
    conversion. See Subsections~\ref{Ssec:Des:Reglyph} 
    and~\ref{Ssec:Reglyph} for details.
  \item[\texttt{csckrn2x.tex}] This file is a variant of 
    \texttt{csc2x.tex}, which doesn't copy the commands that actually 
    set glyphs.
  \item[\texttt{osf2x.tex}] This file is a variant of 
    \texttt{csc2x.tex}, which only changes the names of digits.
\end{description}

\texttt{fontinst.ins} also generates the file \texttt{trig.sty}, which 
contains \index{Carlisle, David} David Carlisle's 
\SortIndex{trig package}{\package{trig} package} \package{trig} 
package, and puts it in the same place as \texttt{fontinst.sty}.
\changes{1.914}{2000/05/14}{Generating \texttt{trig.sty} from 
   source. (LH)}


\subsection{Modules}

The source is split up on the following \package{docstrip} modules:
\begin{description}
  \item[\Module{boundaryCompability}, \texttt{fimain}]
    Guards code that is needed for \package{fontinst} to be compatible 
    with the old interface for boundary ligatures and kerns.
  \item[\Module{!boundaryCompability}, \texttt{fimain}]
    Guards code that is used when \package{fontinst} is not to be 
    compatible with the old interface for boundary ligatures and kerns.
  \item[\Module{debug}, \texttt{filtfam}]
    Guards code in the |\latinfamily| section that writes \texttt{INFO>} 
    messages.
  \item[\Module{doc}, \texttt{fibasics}, \texttt{ficommon}, and 
    \texttt{fimain}]
    Guards code that is to go into \texttt{fontdoc.sty}.
  \item[\Module{driver}, all files]
    Guards the driver code---the short piece of \LaTeX\ code in the 
    beginning of each file that makes it possible to typeset as a 
    \LaTeX\ document. \texttt{docstrip.ins} doesn't extract this 
    code, but it is possible to write a script that makes 
    \package{docstrip} extract this code if one wants to write a 
    modified driver. It's not usual, though.
  \item[\Module{everyjob}, \texttt{fibasics}]
    Guards the code setting |\everyjob| for fontinst formats (by 
    default not used).
  \item[\Module{!glyphs}, \texttt{ficonv}]
    Guards reglyphing setup code that is relevant when commands that 
    set glyphs are not to be copied.
  \item[\Module{glyphs}, \texttt{ficonv}]
    Guards reglyphing setup code that is relevant when commands that 
    set glyphs are to be copied.
  \item[\Module{ini}, \texttt{fibasics}]
    Guards the code for \texttt{fontinst.ini}.
  \item[\Module{map}, \texttt{fimapgen}]
    Guards the code for the automatic map file generation.
  \item[\Module{misc}, \texttt{fibasics}, \texttt{fimain}, and 
    \texttt{ficonv}]
    Guards code that is only to go into \texttt{finstmsc.sty}.
  \item[\Module{!misc}, \texttt{fibasics}]
    Guards code that is not to go into \texttt{finstmsc.sty}.
  \item[\Module{obsolete}, \texttt{ficommon} and \texttt{fimain}]
    Guards miscellaneous pieces of code that are considered obsolete.
  \item[\Module{oldstyle}, \texttt{filtfam}]
    Guards code in the |\latinfamily| section. The purpose of that 
    code is described in more detail in Section~\ref{Sec:NotesOnUsing}.
  \item[\Module{oldTeX}, \texttt{fibasics}]
    Guards code that copes with a bug in \TeX\ versions before 3.141.
  \item[\Module{!oldTeX}, \texttt{fibasics}]
    Guards normal code that wouldn't work satisfactory for 
    \TeX\ versions before 3.141 due to a bug in those \TeX s.
  \item[\Module{pkg}, all files]
    Guards code that is to go into \texttt{fontinst.sty} (and its 
    variants).
  \item[\Module{pkg2}, \texttt{fibasics}]
    A special variant of \Module{pkg} that is used for code that is 
    to end up at the very end of \texttt{fontinst.sty}.
  \item[\Module{reglyphletters}, \texttt{ficonv}]
    Guards code that sets up for changing lower case letter names to 
    corresponding smallcaps names. Used for \texttt{csc2x.tex} and 
    \texttt{csckrn2x.tex}.
  \item[\Module{reglyphfigures}, \texttt{ficonv}]
    Guards code that sets up for changing ordinary figure names to 
    corresponding \texttt{oldstyle} names. Used for 
    \texttt{osf2x.tex}, \texttt{csc2x.tex}, and 
    \texttt{csckrn2x.tex}.
  \item[\Module{reglyph}, \texttt{ficonv}]
    Guards code that is to go to the reglyphing setup files 
    \texttt{csc2x.tex} and \texttt{csckrn2x.tex}.
  \item[\Module{textcomp}, \texttt{filtfam}]
    Guards code in the |\latinfamily| section that generates text symbol 
    (\texttt{TS1}\slash ``text companion'') fonts.
  \item[\Module{underconstruction}, \texttt{main}]
    Guards some code that is ``under construction''.
\end{description}



\section{About previous \package{fontinst} releases}

\subsection{Pre-\package{doc} fontinst releases}

The following is a choice of some \package{fontinst} versions and some 
comments about them. The complete list of versions in the range 
v\,0.01--1.7 can be found in the file \texttt{CHANGES}.
\begin{description}
\item[v\,0.01]
  was begun by Alan Jeffrey in February 1993.  This was the
  very first version recorded in the \texttt{CHANGES} file.
%
\item[v\,0.19]
  was completed in April 1993 and presented at the TUG~'93
  conference in July 1993.  It is described in the proceedings
  in \emph{TUGboat}~14\#3 and represents one of the earliest
  release versions, in which the user interface was still
  subject to change.
%
\item[v\,1.0]
  was begun in August 1993 right after the conference and
  represents the beginning of a complete re-write from scratch.
%
\item[v\,1.333]
  was presented one year later at the TUG~'94 conference and
  is described in the proceedings in \emph{TUGboat}~15\#3.
  It uses a different user interface, which is largely the same
  as in the present version, although the internals of the
  implementation have subsequently changed quite a bit.
%
\item[v\,1.335]
  was released in September 1994 and was the last ``official''
  release version by Alan Jeffrey. Until the summer of 1998 this was 
  still the version to be found in the \texttt{fonts}\slash
  \texttt{utilities}\slash\texttt{fontinst} directory on CTAN.
  It is considered obsolete and should not be used any longer.
%
\item[v\,1.400]
  was prepared in November 1994 and was the first version which
  used |8r|-encoded raw fonts as a basis for virtual fonts.
%
\item[v\,1.500]
  appeared on CTAN in \texttt{fonts}\slash\texttt{psfonts}\slash
  \texttt{tools} in September~1995 together with Sebastian Rahtz's 
  Unix shell scripts to automate the installation. This version 
  included a completely revised implementation of |\latinfamily| and 
  added the |\installrawfont| command to install ligful raw fonts.
%
\item[v\,1.504]
  appeared on CTAN in \texttt{fonts}\slash\texttt{psfonts}\slash
  \texttt{tools} in January~1996. It added code to install (real or 
  faked) small caps fonts and to fake narrow fonts, if they don't 
  exist.
%
\item[v\,1.511]
  was one of the last beta versions by Alan Jeffrey which dates back
  to June~1996, but for some reason was never released.  It uses
  the encodings |9o| and~|9d| instead of |9t| and~|9e| to install
  expertized oldstyle fonts, but this change never found its way
  into subsequent ``unofficial'' releases until v\,1.8.
%
\item[v\,1.6]
  appeared on CTAN in \texttt{fonts}\slash\texttt{psfonts}\slash
  \texttt{tools} in February~1997 and was the first ``unofficial'' 
  version of \package{fontinst} maintained by Sebastian Rahtz. It 
  contains only minor changes compared to v\,1.504, such as switching 
  to lowercase file names, searching for |.pl| files before |.afm| 
  files, and adding the \texttt{textcomp} installation to the 
  distribution.
%
\item[v\,1.6]
  was re-issued on CTAN in September~1997, when the Unix shell
  scripts were replaced by Perl scripts.  The \package{fontinst}
  package itself didn't change apart from minor changes of the
  debugging messages.
%
\item[v\,1.7]
  is the latest ``unofficial version'', which was released on CTAN
  in May~1998.  It includes some changes to the mapping between
  \texttt{fontname} and \LaTeX{} weight codes proposed by Ulrik
  Vieth, as well as some code to support the use of |8r|-encoded
  |.afm| files generated by |ttf2afm|.
%
\end{description}
%

\subsection{About fontinst v\,1.8}

Version~1.8 of the \package{fontinst} utility was the first to have 
been converted to \package{docstrip} format (this was made by Ulrik 
Vieth) and it was first released in June~1998. It is based on 
Sebastian Rahtz's ``unofficial'' \package{fontinst} releases v\,1.6 
and~1.7 as of February~1997 and May~1998, which, in turn, are based 
on Alan Jeffrey's versions v\,1.500 and~1.504 of September~1995
and January~1996.  In addition, version v\,1.8 also incorporated 
some code from Alan Jeffrey's last beta version, v\,1.511,
which dates back to June~1996, but was never released to the
general public for some reason.

% It should be noted that all these versions differ significantly
% from the previous ``official'' version v\,1.335 as of September~1994,
% which was the only one to be found in the \texttt{fontinst} directory 
% on CTAN until the summer of 1998. Version v\,1.335 is now obsolete.

Version~1.8 was agreed upon by the \package{fontinst} hacker community, 
as represented on the \package{fontinst} mailing list, as the new 
officially endorsed version, on which all further additions and 
enhancements can be based.


\section{About this \package{fontinst} release}

Several improvements, some of which fixes old bugs and some of which 
introduces new features, have been made to in particular the generation 
of fonts. The most important are:
\begin{itemize}
  \item The old multiple |\setkern| bug, which resulted in pointless 
    |KRN| instructions being written to (V)PL files have been fixed. 
    In addition, it is now possible to reset kerns (using 
    |\resetkern|) and unset kerns (using |\unsetkerns|, 
    |\noleftkerning|, |\norightkerning|, or |\noleftrightkerning|).
  \item A bug which resulted in too few kerns being written to a font 
    if the same glyph is used in more than one slot (this occurs if 
    you make an all-caps font from an encoding definition file which 
    sets |\lc|, |\lctop|, and |\lclig| to the same to their 
    |\uc|\textellipsis\ counterparts) has been fixed. A consequence of 
    this fix is that you cannot access the number of the slot that 
    glyph \meta{glyph} has been assigned to as |\int|\marg{glyph} 
    (unless you are using \texttt{cfntinst.sty}), but there really is 
    no need for you to do so either.
  \item There is now a proper interface for using left and right 
    boundaries which, in contrast to the old setting of the integer 
    \texttt{boundarychar}, can make use of the full generality of the 
    PL format. (The old interface is still available if you use 
    \texttt{cfntinst.sty}.)
  \item \package{fontinst} can now interpret AFM files which contain 
    non-integer dimensions. There is also a user-level interface for 
    changing the formula according to which the italic corrections of 
    glyphs are computed.
  \item The PL to MTX converter can now cope with the VPL-unique 
    property lists |VTITLE|, |MAP|, and |MAPFONT|, which means that it 
    can now convert VPL files as well. In addition to this, there are 
    a couple of minor bugfixes and improvements in the PL to MTX 
    conversion.
  \item There is now a way of overriding the PL to MTX converter's 
    automatic choice of encoding definition file made based on the 
    |CODINGSCHEME| property of a PL file. The command |\generalpltomtx| 
    lets you select which encoding definition file you want to use, as 
    does the new |\fromplgivenetx| transformed font command.
  \item Several \package{fontinst} commands that were previously 
    missing have been added to the \package{fontdoc} package. The 
    most significant are probably |\inputmtx| and |\inputetx|.
  \item There is now a simple way of changing the names of glyphs in 
    metric files generated from AFM files. 
    % See Subsection~\ref{Ssec:Reglyph} for further details.
  \item The implementation of font metrics transformations, as done by 
    |\transformfont|, has been rewritten and \package{fontinst} now 
    handles uniform scaling internally; the driver only needs to do 
    $x$-scaling and slanting. This can result in different font metrics, 
    but we think only in that it comes out more like one would expect. 
    The user interface is the same. 
  \item There is now a new transformed font command |\fromany| which 
    searches for a font metric file in any of the four formats MTX, 
    PL, AFM, and VPL; converting it to MTX format and possibly 
    generating a PL as well if necessary. This command is also used by 
    |\installfont|, |\installrawfont|, and |\reglyphfont| to search 
    for font metric files, so these can now take VPL files as a 
    source for font metric data.
  \item There is now a mechanism for generating the necessary map files 
    automatically. So far it knows how to generate map files for the 
    \package{dvips} and \package{dvipdfm} drivers, but the system can 
    easily be extended by adding code in the \texttt{finstmsc.rc} file.
  \item There are two new commands |\setscaled|\-|rawglyph| and 
    |\setscaled|\-|notglyph| which generalize the |\setraw|\-|glyph| 
    and |\setnot|\-|glyph| commands. These commands are described in 
    Subsection~\ref{Ssec:Glyph-info}.
  \item The routines for converting metrics to (V)PL format has 
    changed. As a result of this the metrics of fonts are likely to 
    change (slightly), but the conversion is now more accurate than it 
    used to be. A side-effect is that VPL files generated by 
    \package{fontinst} can now be used directly as a base for other 
    fonts (it used to be necessary to convert them to binary format and 
    back to get the metrics right).
  \item \texttt{finstmsc.sty} now contains a new command which 
    generates a Postscript encoding (\texttt{.enc}) file from an ETX 
    file. The syntax of this command is
    \begin{quote}
      |\etxtoenc|\marg{etxfile}\marg{encfile}
    \end{quote}
    Usually you don't need to use this command, since the routines 
    which generate map files will call it when the encoding used in a 
    |\reencodefont| isn't known.
  \item The new command
    \begin{isyntax}
      |\installfontas|\marg{font}\marg{encoding}\marg{family}%
      \penalty0\marg{series}\penalty0\marg{shape}\penalty0\marg{size}
    \end{isyntax}
    adds an entry for \meta{font} with the given NFSS parameters to 
    the corresponding FD file.
  \item The |\set|\textellipsis, |\reset|\textellipsis, and 
    |\unset|\textellipsis\ commands now behaves as one would expect 
    even when they occur between |\install|\-|fonts| and |\end|\-%
    |install|\-|fonts|---the assignments they make are no longer 
    subject to the grouping around the metrics of individual fonts. 
    Assignments made by these commands when they occur in MTX and ETX 
    files \emph{are} however still subject to this grouping, so that 
    behaves as usual.
  \item There are two control flow commands |\for| and |\foreach| 
    which repeatedly execute a given sequence of commands---just like 
    a normal programming language \texttt{for} loop. With |\for| the 
    loop variable is an integer that is incremented or decremented by 
    an amount that is specified in the beginning of the loop. With 
    |\foreach| the loop variable is a string which assumes all the 
    values given in a comma-separated list.
  \item The command |\offcommand| turns a command `off', i.e., makes 
    it gobble its arguments and do nothing. The command |\oncommand| 
    turns a command back on, i.e., restores the original definition of 
    a command that had been turned off. Turning a command off or on 
    when it is already off or on respectively has no effect.
  \item If you begin an item in the file-list argument (\#2) of 
    |\install|\-|font| or |\install|\-|raw|\-|font| with the command 
    |\metrics|, then that item (everything up till the next comma 
    that is not inside a group) will be interpreted as explicit metric 
    commands that are executed after the previous font was loaded and 
    before the next is. Thus you can do e.g.
    \begin{quote}
      |\installfont{|\textellipsis|}{a,\metrics\unsetint{xheight},b,|%
      \textellipsis
    \end{quote}
    if you want font \texttt{a} to be loaded before font \texttt{b}, 
    but want to use the \texttt{xheight} value of font \texttt{b}, 
    and you don't want to bother writing an MTX file that simply 
    contains the command |\unsetint{xheight}|.
  \item There is now a command |\fontinstcc| which switches to the 
    catcodes that are in force for most of the time that 
    \texttt{fontinst.sty} is read (|@| and |_| are letters, |~| is a 
    space, and spaces and newlines are ignored). This makes it simpler 
    to redefine internal control sequences. To switch back to the 
    normal catcodes, there is the |\normalcc| command. Neither 
    command has any arguments.
  \item The |\Unicode| command may be used to specify what 
    ISO\,10646\slash Unicode character a slot corresponds to. See 
    page~\pageref{Unicode} for details.
  \item The third arguments of the |\installfont| and 
    |\install|\-|raw|\-|font| commands can now be a comma-separated 
    list of ETX files.
  \item File names in the second and third arguments of 
    |\install|\-|font| and |\install|\-|raw|\-|font| may now be 
    suffixed by zero or more \emph{modifier clauses} that can change 
    the interpretation of a file by e.g.~assigning special values to 
    some variables while the file is read in. This is described in 
    Subsection~\ref{Ssec:FontInstCmds} below.
  \item The |\setfontdimen| command allows an ETX file to declare 
    which integer variables correspond to font dimensions in a (V)PL 
    file. This correspondence is used both when generating a ligful 
    (V)PL file and when a (V)PL file is converted to an MTX file.
\end{itemize}


\subsection{Metric packages}

\package{fontinst} has traditionally come with a collection of MTX 
files that complement the MTX files generated from base font metrics, 
in that they build glyphs that may be missing from the base fonts or 
in some other way needs to be improved. The most well-known of these 
is the \texttt{latin.mtx} file; other examples include 
\texttt{textcomp.mtx}, \texttt{mathit.mtx}, and \texttt{latinsc.mtx}. 
A problem with these is however that they cannot produce optimal 
results for all fonts simply because there are irregular differences 
in how fonts are set up by the foundries. Most glyphs come out alright, 
but there are usually a few for which the parameters used are more or 
less wrong. Therefore most high quality font installations are made 
with modified versions of these files, where the parameters have been 
tuned to the specific font design.

Modifying in particular \texttt{latin.mtx} is however not an entirely 
easy task, because this is a rather large file (with plenty of 
archaic pieces of code in curious places). Doing it once is no big 
problem, but if one has to do it several times (maybe because some 
errors are discovered in the original \texttt{latin.mtx}) then it is 
probably no fun anymore. Furthermore, if one has two or three 
modified copies of this file because one has made high quality 
installations of that many different fonts then even a trivial bugfix 
might start to feel like entirely too much work.

If one has to make modifications then it is usually easier to deal 
with several small files (many of which can be used unchanged) than 
one big file. Thus it would be better if these big files were split up 
into several smaller ones.
The main problem with splitting up something like \texttt{latin.mtx}
is that there are some commands which are defined at the top and 
which are then used in almost all sections of the file. One must make 
certain that these commands are always loaded, which makes the metric 
files somewhat harder to use (especially if the one who tries to use 
them is not the one who wrote them).

One strategy is to include all definitions needed for a metric file in 
it. This has the slight disadvantage that the commands will have to be 
defined several times. What is worse however, is that the command 
definitions will appear in several files, so if one finds a bug in one 
of them, one cannot simply correct this bug in one place. As the number 
of files can soon become quite large, correcting such bugs can become 
a boring procedure indeed.

Another strategy is to put all the command definitions in one file 
and then explicitly include it in the \meta{file-list} argument of 
|\installfont|. This eliminates the repeated bug fixing problem, but 
requires the user to do something that the computer can actually do 
just as well.

A third strategy is to put the command definitions in one or several 
files and then in each metric file the user explicitly mentions load 
the command definitions needed for that particular file. Metric 
packages uses an improved version of this strategy, since they also 
make it possible for fontinst to remember which packages (i.e., sets 
of command definitions) that have already been loaded, so that they 
are not unnecessarily loaded again. The \texttt{newlatin.mtx} file is 
an alternative to \texttt{latin.mtx} that implements this strategy. 
Most of the actual code is located in the following metric packages:
\begin{longtable}{l p{0.7\linewidth}}
  \texttt{ltcmds.mtx}& Defines some common commands used by the other 
    files.\\
  \texttt{llbuild.mtx}& Builds the latin lower case alphabet 
    (unaccented letters are `unfakable', the rest are constructed if 
    not present in the base fonts).\\
  \texttt{lubuild.mtx}& Builds the latin upper case alphabet.\\
  \texttt{lsbuild.mtx}& Builds accented letters in the latin 
    smallcaps alphabet, but only if there are unaccented letters to 
    build them from in the base fonts.\\
  \texttt{lsfake.mtx}& Fakes a latin smallcaps alphabet by shrinking 
    the upper case alphabet, but only if the glyph had not already 
    been manufactured.\\
  \texttt{lsmisc.mtx}& Make some miscellaneous smallcaps glyphs 
    (mostly ``smallcaps f-ligatures'').\\
  \texttt{ltpunct.mtx}& Makes digits, punctuation marks, and other 
    symbols (mostly by marking as ``unfakable'').
\end{longtable}
\noindent All of these are easy to use as components of equivalents 
of a modified \texttt{latin.mtx} files, and all dependencies of one 
package upon another are handled via explicit |\usemtxpackage| 
commands.

For information on the syntax etcetera of commands related to metric 
packages, see Section~\ref{Sec:Metric files}.


\subsection{Word boundary ligatures and kerns}

One of the new features added in \TeX~3 was that of ligatures and 
kerns with word boundaries. \package{fontinst} has had an interface 
for making such ligatures and kerns, but it has been completely 
redesigned in v\,1.9 and the old interface (setting the integer 
|boundarychar|) is no longer recognized by \package{fontinst}. Files 
which use the old interface can still be processed with 
\texttt{cfntinst.sty}, though.

Before considering the new commands, it is suitable to make a 
distinction between proper glyphs and pseudoglyphs. A proper glyph has 
been set using one of the commands |\setrawglyph|, |\setglyph|, and 
|\resetglyph|. A pseudoglyph is any name used in the context of a 
glyph name which does not denote a proper glyph. If a pseudoglyph 
|g-not| was set using the |\setnotglyph| command, then 
|\ifisglyph{g-not}\then| will evaluate to true, but something can be 
a pseudoglyph even if an |\ifisglyph| test evaluates to false. The 
interesting point about pseudoglyphs when considering word boundaries 
however, is that a pseudoglyph can have ligatures and kerns.

Kerns and ligatures at the left word boundary (beginning of word) are 
specified using the commands |\setleftboundary| and 
|\endsetleftboundary|, which are syntactically identical to 
|\setslot| and |\endsetslot| respectively. One important difference is 
however that the argument to |\setslot| must be a proper glyph, while 
the argument to |\setleftboundary| may be any glyph, hence any 
pseudoglyph will do just fine.

|\ligature| commands between |\setleftboundary| and 
|\endsetleftboundary| will generate beginning of word ligatures. Kerns 
on the right of the glyph specified in |\setleftboundary| will become 
beginning of word kerns.

Kerns and ligatures at the right word boundary (end of word) are 
trickier, due to the asymmetrical nature of the ligkern table in a PL 
file. What a font can do is to specify that the right word boundary, 
for purposes of kerning and ligatures, should be interpreted as 
character $n$. By including a kern or ligature with character $n$ on 
the right, that kern or ligature will be used at the end of a word, 
but it will also be used each time the next character is character 
$n$. Because of this, one usually wants the slot $n$, which the right 
word boundary is interpreted as being, to be empty whenever the 
encoding allows this.

The command
\begin{quote}
  |\setrightboundary|\marg{glyph}
\end{quote}
will mark the current slot as used to denote the right word boundary, 
and leave the slot empty, increasing the current slot number by one 
just like a |\setslot| \textellipsis\ |\endsetslot| block does. Kerns on 
the left of \meta{glyph} will be end of word kerns and |\ligature| 
commands with \meta{glyph} as the second argument will be for the end 
of a word.

The command
\begin{quote}
  |\makerightboundary|\marg{glyph}
\end{quote}
is similar to |\setrightboundary|, but it is a slot command which may 
only be used between a |\setslot| and the matching |\endsetslot|. Like 
|\setrightboundary|, it marks the current slot as used to denote the 
right word boundary, but the glyph specified in the enclosing |\setslot| 
will be written to that slot. Ligatures for the glyph specified by the 
|\setslot| and ligatures for the glyph specified by the 
|\makerightboundary| will both be for this single slot. Kerns on the 
right of the |\setslot| glyph and the |\makerightboundary| glyph will 
similarly both be for this single slot. The idea is that the |\setslot| 
glyph should be used when making a kern or ligature for that glyph, 
while the |\makerightboundary| glyph should be used when making a kern 
or ligature for the end of a word. \package{fontinst} will warn you if 
these two uses of the slot directly contradict each other.


\subsection{Changing the names of glyphs}
\label{Ssec:Des:Reglyph}

Sometimes, primarily when making a virtual font from more than one raw 
font and two of the raw fonts contain different glyphs with the same 
name, it becomes necessary to change the names of some glyphs to make 
some sense out of it. The main source of this kind of trouble is the 
``caps and small caps'' (SC) and ``oldstyle figures'' (OsF) fonts 
within many commercial font families. The typical problem is that what 
is typographically different glyphs---such as the lowercase `a' 
(\texttt{a}, for \package{fontinst}) and the smallcaps `\textsc{a}' 
(\texttt{Asmall}, for \package{fontinst})---are given the same name by 
the foundry. 

One way to get round this is to say for example
\begin{quote}
  |\setglyph{Asmall} \glyph{a}{1000} \endsetglyph|\\
  |\setleftrightkerning{Asmall}{a}{1000}|\\
  |\unsetglyph{a}|\\
  |\noleftrightkerning{a}|
\end{quote}
and continuing like that for all the duplicate glyph names. This is 
however a rather prolix method and if the number of glyphs is large 
then it is usually simpler to use the |\reglyphfont| command.

To reglyph one or several fonts, one writes
\begin{quote}
  |\reglyphfonts|\\
  \vadjust{}\quad \meta{reglyphing commands}\\
  |\endreglyphfonts|
\end{quote}
There are two types of reglyphing commands: the |\reglyphfont| 
command, and the commands that modify what |\reglyphfont| will do to 
the fonts it operates on. The syntax of |\reglyphfont| is
\begin{quote}
  |\reglyphfont|\marg{destination font}\marg{source font}
\end{quote}
The \meta{source font} font here is the name (suffix not included, of 
course) of the font metric file one wants to change the glyph names in. 
This font metric file can be in any of the formats MTX, PL, AFM, and 
VPL, and it will be converted to MTX format if it isn't already in 
that format (this happens just as for files listed in the second 
argument of |\installfont|). \meta{destination font} (which must be 
different from \meta{source font}) will be taken as the name for a 
new \texttt{.mtx} file that will be generated. The destination font 
can differ from the source font only in two ways: the names of some 
glyphs in the source font might be changed, and some of the commands 
from the source font might not have been copied to the destination 
font. To what extent the fonts are different is determined by what 
modifying commands have been executed; when no modifying commands 
have been executed, the source and destination font are equal.

The modifying reglyphing commands are
\begin{quote}
  |\renameglyph|\marg{to}\marg{from}\\
  |\renameglyphweighted|\marg{to}\marg{from}\marg{weight}\\
  |\killglyph|\marg{glyph}\\
  |\killglyphweighted|\marg{glyph}\marg{weight}\\
  |\offmtxcommand|\marg{command}\\
  |\onmtxcommand|\marg{command}
\end{quote}
|\renameglyph| simply declares that occurrences of the glyph name 
\meta{from} should be replaced by the glyph name \meta{to}. To each 
glyph name is also assigned a \emph{weight}, which is used by a 
mechanism which conditions copying of commands from the source font to 
the destination font by the set of glyphs that command mentions. The 
details of this mechanism are however somewhat tricky, so those 
interested in the full generality should go to Subsection~\ref
{Ssec:Reglyph}. Here it needs only be noted that if one applies 
|\killglyph| to a glyph name, then (under most circumstances) commands 
that refer to that glyph name will not be copied to the destination 
font.

|\offmtxcommand| and |\onmtxcommand| also control whether commands are 
copied to the destination font, but they look at the actual command 
rather than the glyphs it refers to. For example, after the command
\begin{quote}
  |\offmtxcommand{\setkern}|
\end{quote}
no |\setkern| commands will be copied. By using |\offmtxcommand|, it 
is possible to achieve effects similar to those of the files 
\texttt{kernoff.mtx} and \texttt{glyphoff.mtx}---the difference is 
that with |\offmtxcommand|, it happens at an earlier stage of the font 
generation. As expected, |\onmtxcommand| undoes the effect of 
|\offmtxcommand|.

A special rule pertains to the |\set|\-|raw|\-|glyph|, 
|\set|\-|not|\-|glyph|, |\set|\-|scaled|\-|raw|\-|glyph|, and 
|\set|\-|scaled|\-|not|\-|glyph| commands, since |\transformfont| 
doesn't care what something was in the source font when it generates 
the transformed font. To turn these commands off while reglyphing, 
you use |\offmtx|\-|command| on |\set|\-|scaled|\-|raw|\-|glyph|.

The effects of modifying reglyphing commands are delimited by 
|\reglyphfonts| and |\endreglyphfonts|, which starts and ends a group 
respectively.

As we expect the most common reglyphing operation will be to go from SC 
glyph names to expert glyph names, there is a file \texttt{csc2x.tex} 
in the \package{fontinst} distribution which contains the modifying 
reglyphing commands needed for setting up that conversion. Thus you 
can write for example
\begin{quote}
  |\reglyphfonts|\\
  |  \input csc2x|\\
  |  \reglyphfont{padrcx8r}{padrc8r}|\\
  |  \reglyphfont{padscx8r}{padsc8r}|\\
  |\endreglyphfonts|
\end{quote}
to alter the glyph names in the SC fonts in the Adobe Garamond 
(\texttt{pad}) family. 
Note that the names of the destination fonts here really are rather 
arbitrary, since they will only exist as \texttt{.mtx} files, and 
thus only need to work within your local file system. In particular, 
all the |\setrawglyph| commands in the destination font files still 
refer to the source font, so it is that font which the drivers need 
to know about.


\subsection{Making map file fragments}

A \emph{map file fragment} is the lines\footnote{Not in general an 
entire map file, hence the word \emph{fragment}.} of a map file that 
the corresponding driver would need for handling some set of fonts. 
When told to, \package{fontinst} can (in a fairly automatic way) create 
the map file fragment which is needed for the set of raw fonts 
\package{fontinst} has (i) installed directly (using |\installrawfont|) 
or (ii) used as a base font for some installed virtual font (generated 
by |\installfont|). \package{fontinst} does not support the map file 
syntaxes of every existing driver, but the system is designed to be 
extendable and contributions that extend its capabilities are welcome. 
Nor can \package{fontinst} examine your \TeX\ system and 
determine every piece of information needed to make the correct map 
file fragments, but you can tell it roughly how your installation 
looks, it can make guesses which work most of the time, and you can 
specify most things explicitly if the guesses turn out to be wrong. 
Should the available options for configuring the process turn out to 
be inadequate for your needs, then please write to the 
\package{fontinst} mailing list about this---there is probably a way 
to improve the system so that your needs can be met.

Now what does one have to do to use this map file fragment writer, 
then? First you need to tell \package{fontinst} to record the 
information the map file fragment writer needs. You do this by giving 
the command
\begin{quote}
  |\recordtransforms{whatever.tex}|
\end{quote}
at the beginning of the run. Here \texttt{whatever.tex} is the name of 
a file that will be created, so you can use some other name if you 
like. After that you do all the calls to |\transform|\-|font|, 
|\install|\-|font|, |\install|\-|raw|\-|font|, |\latin|\-|family|, 
etc.\ you need to make the fonts you want. When you're done, you give 
the command
\begin{quote}
  |\endrecordtransforms|
\end{quote}
and end the run (say |\bye|). The file \texttt{whatever.tex} will now 
contain the information about which fonts were used and what needs to 
be done with them.

The second step is to actually run the map file fragment writer. 
Observe that it is located in the file \texttt{finstmsc.sty}, not 
\texttt{fontinst.sty}! The commands you need to give it can be so few 
that you can type them in at \TeX's \texttt{*} prompt, but if you are 
writing a command file then it should typically have the following 
structure (comments not necessary, of course):
\begin{quote}
  \begin{tabular}{ll}
    |\input finstmsc.sty|& |%| Input command definitions\\
    \meta{general settings} & |%| See below\\
    |\adddriver|\marg{driver name}\marg{output file}& 
      |%| Open output file\\
    |\input whatever.tex|& |%| Write to output file\\
    |\donedrivers|& |%| Close output file(s), tidy up\\
    |\bye|& |%| Quit
  \end{tabular}
\end{quote}
The |\adddriver| command gives the order ``write map file entries for 
the \meta{driver name} DVI driver to the file \meta{output file}.'' The 
plan is that it should be possible to use the name of just about any 
major driver (\texttt{dvips}, \texttt{xdvi},\footnote{Or 
does that use the same map file as \texttt{dvips}? I heard somewhere 
that it did. /LH} \texttt{pdftex},\footnote{pdf\TeX\ can read 
the map files generated for \texttt{dvips}, but a separate driver is 
desirable because the formats are not completely identical.} 
\texttt{OzTeX}, etc.) here and get suitable map file entries for that 
driver as output, but for the moment only the \texttt{dvips} and 
\texttt{dvipdfm}\footnote{Whose support I made very much to illustrate 
that you \emph{don't} have to be a big and ancient driver like 
\texttt{dvips} to have supporting code put into \package{fontinst}. 
(The fact that I just happened to have printed out the documentation and 
that is was easy to read also helped, of course.) Note, however, that 
there won't be any support for a driver unless someone sits down and 
writes the code for it! Don't assume I will. /LH} drivers are supported. 
You may also use \texttt{debug} for \meta{driver name}; the entries in 
the file for that ``DVI driver'' simply contain all the available 
information about each font (hence it should come handy for debugging 
code writing entries for real drivers) in a format that should be easy 
to interpret for a human. It could be the right choice if you're going 
to write the map file manually.

The file \texttt{whatever.tex} in the above example contains the 
commands (|\makemapentry| commands) that actually cause entries to be 
written to the output file. It also contains a number of |\storemapdata| 
commands---these describe how some given font was made. If some 
metric file you have used contains |\setrawglyph| commands that were 
not automatically generated by \package{fontinst}, then there might 
not be a |\storemapdata| for the font they refer to in 
\texttt{whatever.tex}, so you will have to include such a command 
yourself somewhere. This can for example be done in the \meta{general 
settings} part of the above example file. The syntax of the 
|\storemapdata| command is described in Subsection~\ref{Ssec:interface}.

Another class of things that will typically appear in the 
\meta{general settings} part above is commands that will inform the 
routines actually writing output about your \TeX\ system, about the set 
of fonts you are using on this run, or about something else that might 
be useful. Some such commands are of a general nature and affect what 
assumptions \package{fontinst} will make in certain conditions when no 
specific information is available. For the moment there commands are:
\begin{description}
  \item[\cs{AssumeMetafont}] Assume all fonts with PL metrics are 
    bitmaps generated by Metafont, and therefore make no entries for 
    them.
  \item[\cs{AssumeAMSBSYY}] Assume all fonts with PL metrics have their 
    \TeX\ names in all upper case as postscript names---just like the 
    Computer Modern fonts in the AMS\slash Blue~Sky\slash Y\&Y 
    distribution.
  \item[\cs{AssumeBaKoMa}] Assume all fonts with PL metrics have their 
    \TeX\ names in all lower case as postscript names---just like the 
    Computer Modern fonts in the BaKoMa distribution.
\end{description}
Otherwise the default action of the routine for finding out the 
postscript name of a font simply is to observe that it hasn't got a clue 
about what the right value is when the metrics were taken from a PL 
file, and therefore it writes `\texttt{??????}' for the postscript name.
\begin{description}
  \item[\cs{AssumeLWFN}] Assume postscript fonts for which nothing 
    else has been specified are stored in files which are named 
    according to the \mbox{MacOS} scheme for 
    \texttt{LWFN}s.%\footnote{LaserWriter FoNt}
\end{description}
Otherwise the default action is to use the name of the AFM or PL from 
which the metrics was originally taken, and add the file suffix stored 
in the string \texttt{PSfontsuffix}. The default value of this string 
is \texttt{.pfa}, but it can be changed using |\resetstr|.

If neither the default nor the LWFN scheme produce correct results 
then you may use the more specific \DescribeMacro\specifypsfont
|\specifypsfont| command, which describes exactly which file (or files, 
if any) a given font is stored in. For syntax and examples of usage, 
see Subsubsection~\ref{Sssec:Config-interface}. (I consider the 
semantics of this command to still be under development, but in order 
to know how to develop it further I need to know in which cases it is 
insufficient.)

Finally, there is the |\declarepsencoding| command which is used to 
link ETX files to postscript encodings. If no postscript encoding has 
been linked to a given ETX file then \package{fontinst} will 
automatically create a postscript encoding (\texttt{.enc}) file for 
that encoding, and use this file for all reencoding commands. Again, 
see Subsubsection~\ref{Sssec:Config-interface} for syntax and examples 
of usage. The \texttt{8r} encoding is predeclared, and it doesn't 
matter if an encoding is undeclared if you never use it to reencode 
fonts, but there is potentially a problem with not having declared 
encodings you have installed and use for reencoding, as you may then 
find yourself having two files with identical names that define 
encodings that do not have the same name (as far as postscript is 
concerned).


\subsection{On verbatim, typewriter, and monowidth fonts}

The verbatim, typewriter, and monowidth concepts are common sources 
of confusion for those who use \package{fontinst} to install fonts 
with \AllTeX;\footnote{Myself \emph{not} excepted. /LH} in particular 
there are many misconceptions about the relation between them. The 
official view (of which not much has actually been brought forward) 
is that these concepts are really about three quite different things. 

A font is a \emph{monowidth} (monospaced, fixed-pitch) font if all 
glyphs in it have exactly the same width. Some font formats make 
special provisions for such fonts; the most notable example is the 
AFM format, where a single \texttt{CharWidth} keyword specifies the 
width for all glyphs in the font. \package{fontinst} responds to this 
by including the command
\begin{quote}
  |\setint{monowidth}{1}|
\end{quote}
in the MTX file generated from an AFM, but that is everything that is 
hard-wired into the program. That a font is monowidth is however 
something that one should take note of when installing it for \TeX, 
as it means many of the glyphs in it have such a strange appearance 
that they are (pretty much) useless. The \texttt{endash} is for 
example usually only half as long as the \texttt{hyphen} and the 
letters in ligature glyphs are only half as wide as normal letters. 
Many of the ETX and MTX files that come with \package{fontinst} 
contain special commands to avoid making use of such degenerate 
glyphs.

That a font is a \emph{typewriter} font really only means that it has 
a typewriterish look about it. The two most familiar typewriter fonts 
are probably Computer Modern Typewriter (\texttt{cmtt}) and Courier. 
Both of these fonts are monowidth, but there is no absolute rule about 
this. One of the standard \TeX\ fonts is for example Computer Modern 
Variable-width Typewriter (\texttt{cmvtt}), which is not a monowidth 
font, as Figure~\ref{Fig:TTvsVTT} shows.
\begin{figure}
  \begin{tabular}{ll}
    \texttt{cmtt}:& \fontfamily{cmtt}\selectfont
      The quick brown fox jumps over the lazy dog.\\
    \texttt{cmvtt}:& \fontfamily{cmvtt}\selectfont
      The quick brown fox jumps over the lazy dog.
  \end{tabular}
  \caption{Two typewriter fonts}
  \label{Fig:TTvsVTT}
\end{figure}

The verbatim concept has very little to do with fonts at all; in 
\LaTeX\ it is considered to be a property of the environment 
(\texttt{verbatim}, \texttt{macrocode}, etc.) rather than a property 
of the font. The connection there is with fonts is that the encoding 
of the font must contain visible ASCII (as defined in Appendix~C 
of \emph{The \TeX book}~\cite{TeXbook}) as a subset for the text to 
be rendered correctly. The \texttt{cmtt} family is the only one amongst 
the original Computer Modern fonts which meets this criterium and 
that is the primary grounds for the idea that these three concepts 
should be connected. Today that reason is at best a very weak one, as 
all \texttt{T1}-encoded fonts also meet the criterium of containing 
visible ASCII as a subset.

A circumstance which has probably added to the confusion is that 
\texttt{OT1} is usually claimed to be an encoding. In reality the 
Computer Modern fonts that are declared in \LaTeX\ as being 
\texttt{OT1} display as many as five different encodings, as shown in 
Table~\ref{Tab:OT1-fonts}.
\begin{table}
  \begin{tabular}{lccc}
    & \texttt{TEX TEXT}& 
      \begin{tabular}[b]{c}\texttt{TEX TEXT WITHOUT}\\
        \texttt{F-LIGATURES}\end{tabular}&
      \texttt{TEX TYPEWRITER TEXT}\\
      \noalign{\medskip}
    non-italic&
      \begin{tabular}{l}
        \texttt{cmb10}\\
        \texttt{cmbx5}--\texttt{12}\\
        \texttt{cmbxsl10}\\
        \texttt{cmdunh10}\\
        \texttt{cmff10}\\
        \texttt{cmfib8}\\
        \texttt{cmr6}--\texttt{17}\\
        \texttt{cmsl8}--\texttt{12}\\
        \texttt{cmss8}--\texttt{17}\\
        \texttt{cmssbx10}\\
        \texttt{cmssdc10}\\
        \texttt{cmssi8}--\texttt{17}\\
        \texttt{cmssq8}\\
        \texttt{cmssqi8}\\
        \texttt{cmvtt10}
      \end{tabular}&
      \begin{tabular}{l}
        \texttt{cmcsc8}--\texttt{10}\\
        \texttt{cmr5}
      \end{tabular}&
      \begin{tabular}{l}
        \texttt{cmsltt10}\\
        \texttt{cmtcsc10}\\
        \texttt{cmtt8}--\texttt{12}
      \end{tabular}\\
      \noalign{\medskip}
    italic&
      \begin{tabular}{l}
        \texttt{cmbxti10}\\
        \texttt{cmfi10}\\
        \texttt{cmti7}--\texttt{12}\\
        \texttt{cmu10}
      \end{tabular}&&
      \begin{tabular}{l}
        \texttt{cmitt10}
      \end{tabular}
  \end{tabular}
  \caption{``\texttt{OT1}-encoded'' Computer Modern fonts, collected 
    according to the actual font encoding}
  \label{Tab:OT1-fonts}
\end{table}
Since most monowidth fonts are only used for setting verbatim text, 
there is some code in \texttt{ot1.etx} which automatically chooses a 
\texttt{TEX TYPEWRITER TEXT} encoding for the font when the 
\texttt{monowidth} integer is set. The only reason for this is the 
guess that this is what the user wanted.


\subsection{Tuning accent positions---an application of loops}

The accent placements made by \texttt{latin.mtx} certainly aren't 
perfect for all fonts, and the only way to find out where they should 
be put is through trying in text the accented letters you get for a 
couple of values for the position parameter and deciding which one 
works best. Since to try one parameter value you need to (i) edit it 
into an MTX file, (ii) run \package{fontinst}, (iii) run 
\package{VPtoVF}, (iv) run \TeX\ on some test text, and (v) print that 
text, trying one parameter value can take annoyingly much time. 
Repeating the same procedure ten times to test ten values is not 
something one does without being bored (unless one scripts it, of 
course), but it is possible to try ten parameter values in a single 
virtual font, and without doing very much typing.

Say you're not too happy with how \texttt{latin.mtx} positions the 
accent in the \texttt{ohungarumlaut} glyph:
\begin{quote}
  |\setglyph{ohungarumlaut}|\\
  |   \topaccent{o}{hungarumlaut}{500}|\\
  |\endsetglyph|
\end{quote}
The |500| is the horizontal position (in thousandths of the width of 
the \texttt{o}) that the center of \texttt{hungarumlaut} in the glyph 
constructed will have, so that is the position parameter value that 
you want to change. Create an MTX file containing the code
\begin{quote}
  |\for(pos){250}{750}{50}|\\
  |   \setglyph{ohungarumlaut\strint{pos}}|\\
  |      \topaccent{o}{hungarumlaut}{\int{pos}}|\\
  |   \endsetglyph|\\
  |   \setleftrightkerning{ohungarumlaut\strint{pos}}|\\
  |      {ohungarumlaut}{1000}|\\
  |\endfor(pos)|
\end{quote}
This will set eleven glyphs \texttt{ohungarumlaut250}, 
\texttt{ohungarumlaut300}, \texttt{ohungarumlaut350}, \textellipsis\,, 
\texttt{ohungarumlaut750}, each being an Hungarianly umlauted `o' 
(i.e., an `\H{o}') but all having that umlaut in slightly different 
positions. In order to put them in a font, you also need to make an 
encoding that contains them. Therefore create an ETX file which 
contains the code
\begin{quote}
  |\relax\encoding|\\
  |\nextslot{"C0}|\\
  |\for(pos){250}{750}{50}|\\
  |   \setslot{ohungarumlaut\strint{pos}}|\\
  |   \endsetslot|\\
  |\endfor(pos)|\\
  |\endencoding|
\end{quote}
The command for installing this experiment font would be something like
\begin{isyntax}
  |\installfont|\marg{some name}|{|\meta{the normal list of metrics}%
    |,|\penalty0\meta{the new MTX}|}|\penalty0
    |{ot1,|\meta{the new ETX}|}|\penalty0|{OT1}|\textellipsis
\end{isyntax}
The reason for including \texttt{ot1} in the third argument above is 
that you'll need letters other than `\H{o}' against which you can 
compare the experimental glyphs. It would not have been possible to 
use \texttt{t1} instead of \texttt{ot1} (even though that has more 
Hungarian letters) since that would set all slots in the font and 
leave none for these experimental \texttt{ohungarumlaut}s. 

It is even possible to use a loop for making the test text. The 
\LaTeX\ macros
\begin{verbatim}
\newcount\slotcount
\newcommand\testtext[3]{%
  \slotcount=#1\relax
  \begin{description}%
  \loop\item[\the\slotcount]#3%
  \ifnum #2>\slotcount \advance \slotcount 1 \repeat
  \end{description}%
}
\DeclareTextCompositeCommand{\H}{OT1}{o}{\char\slotcount}
\end{verbatim}
will let you write
\begin{quote}
  |\testtext|\marg{first}\marg{last}\marg{text}
\end{quote}
to get the text \meta{text} typeset once for each slot from 
\meta{first} to \meta{last} inclusive, with |\H{o}| ranging through the 
glyphs in this interval. Thus in this case 
|\testtext|\penalty\hyphenpenalty|{"C0}|\penalty\hyphenpenalty|{"CA}|%
\penalty\hyphenpenalty|{Erd\H{o}s}| would be a trivial test.


\subsection{Font installation commands}
\label{Ssec:FontInstCmds}

The |\installfont|, |\installrawfont|, and |\installfontas| commands 
have the respective syntaxes
\begin{isyntax}
  |\installfont|\marg{font-name}\marg{metrics}\marg{etx-list}\penalty0
    \marg{encoding}\marg{family}\marg{series}\marg{shape}\marg{size}\\
  |\installrawfont|\marg{font-name}\marg{metrics}\marg{etx-list}^^A
    \penalty0
    \marg{encoding}\marg{family}\marg{series}\marg{shape}\marg{size}\\
  |\installfontas|\marg{font-name}\penalty0\marg{encoding}^^A
     \marg{family}\marg{series}\marg{shape}\marg{size}
\end{isyntax}
The \meta{font-name} argument and the last five arguments are common 
to all these commands. The first argument is the name of a \TeX\ font 
to install. The last five arguments are the NFSS attributes under which 
that font will be declared to \LaTeX---encoding, family, series, shape, 
and size. It is worth observing that encoding names are usually in 
upper case, whereas the family, series, and shape are usually in lower 
case. The size argument is either a shorthand (declared using 
\DescribeMacro{\declaresize}|\declaresize|) for a particular font 
size (or range of font sizes), or an explicit list of font sizes or 
ranges of sizes, which is copied directly to the font declaration. 
The most common case is to let the size argument be empty, as that is 
declared as a shorthand for ``any size''.

The |\installfontas| command does not itself create the font, it just 
makes a note that the specified font declaration should be written to 
the proper FD file at |\end|\-|install|\-|fonts|. The 
|\install|\-|font| and |\install|\-|raw|\-|font| commands do however 
produce the font, in the sense that they write a VPL and PL 
respectively file for the font. It depends solely on the \meta{metrics} 
and \meta{etx-list} arguments what this font will contain. Many 
features of these arguments are new with \package{fontinst} v\,1.9; 
therefore the complete syntaxes are described below.

Both arguments are comma-separated lists of basically file names (not 
including an extension). The files listed in the \meta{metrics} are 
font metric files which together build up a \emph{glyph base} 
(definitions of glyphs and metrics related to one or several glyphs), 
whereas the files listed in the \meta{etx-list} are encoding definition 
files that select a subset of the glyph base for turning into a 
\TeX\ font. The font metrics can be in either of the four formats 
MTX, PL, AFM, and VPL, which are considered in that order. If the 
metrics are not originally in MTX format then they will be converted 
to this format (a new file will be created) before they are used. 
The encoding definitions must be in ETX format. The files actually 
read will have a suffix \texttt{.mtx}, \texttt{.pl}, \texttt{.afm}, 
\texttt{.vpl}, or \texttt{.etx} appended to the name given, depending 
on which format is expected.

Within each element of the comma-separated list, the actual file name 
is followed by zero or more \emph{modifier clause}s. A \meta{modifier 
clause} consists of a \emph{keyword} followed by some number (usually 
one) of \emph{arguments}, separated by spaces. The whole thing looks 
a lot like the \meta{rule specifications} of e.g.\ the |\vrule| 
command, but here the spaces are mandatory. The currently defined 
\meta{modifier clause}s are
\begin{description}
  \item[\mdseries\textvisiblespace\texttt{option}\textvisiblespace
    \meta{string}]
    Available for metric and encoding files. This adds \meta{string} 
    to the list of options for this file, which may affect what code 
    the file executes. The file can then test, using the |\ifoption| 
    command, whether a specific string is one of the options it was 
    given.
  \item[\mdseries\textvisiblespace\texttt{scaled}\textvisiblespace
    \meta{factor}]
    Available for metric files. Causes the \texttt{rawscale} integer 
    variable to be set to the \meta{factor} (an integer expression) 
    while the file is being read. This scales glyphs and kerns that 
    are added to the glyph base by the \meta{factor}.
  \item[\mdseries\textvisiblespace\texttt{suffix}\textvisiblespace
    \meta{suffix}]
    Available for metric files. Causes \meta{suffix} to be appended 
    to every glyph name appearing in a glyph or kern that file adds 
    to the glyph base. Thus ``\texttt{suffix /2}'' effectively 
    changes a
    \begin{quote}
      |\setrawglyph{a}|\dots
    \end{quote}
    to a
    \begin{quote}
      |\setrawglyph{a/2}|\dots
    \end{quote}
  \item[\mdseries\textvisiblespace\texttt{encoding}\textvisiblespace
    \meta{etx-name}]
    Available for metric files, and forces \package{fontinst} to 
    only consider the PL and VPL formats for this font. 
    As these file formats do not contain glyph names, an ETX file 
    is used to assign glyph names to the slots in the font. 
    This ETX file is usually selected according to the 
    \texttt{CODINGSCHEME} property of the PL or VPL (using the 
    correspondances set up via the |\declare|\-|encoding| command), 
    but that information is not always as one would want it (there 
    are even fonts for which it is quite wrong). An \texttt{encoding} 
    clause bypasses this automatic mechanism, so that the file 
    \meta{etx-name}\texttt{.etx} is used instead.
    
%     % The following is no longer true as of v1.926:
%     \textbf{Note:} The first time that a file in PL or VPL format is 
%     used in a \meta{metrics} argument, a corresponding MTX file is 
%     generated. This means that if the same file reference is used 
%     another time then the reference will be to the MTX file, not to 
%     the original PL or VPL, and thus \texttt{encoding} clauses on 
%     subsequent uses will have no effect. Each font only has one 
%     encoding, so it usually makes no sense to switch the ETX file 
%     used to interpret a font, but since MTX files are not 
%     automatically deleted between runs there is a risk that this 
%     takes away the intended effect of an \texttt{encoding} clause.
    
  \item[\mdseries\textvisiblespace\texttt{mtxasetx}]
    This is available for files in the \meta{etx-list}. The actual 
    function of a
    \begin{quote}
      \meta{file-name} \texttt{mtxasetx}
    \end{quote}
    item in the \meta{etx-list} is that the file 
    \meta{file-name}\texttt{.mtx} is inputted (\emph{not} 
    \meta{file-name}\texttt{.etx}) and that the correspondance 
    between glyph names and slot numbers set up in 
    |\set|\-|raw|\-|glyph| or |\set|\-|scaled|\-|raw|\-|glyph| 
    commands in this file is treated as if it had been set up by 
    |\setslot| commands in an ETX file. Provided the MTX file is 
    transformable, the glyph base will be unaffected.
    
    The purpose of this feature is to simplify quick and dirty 
    installations of odd fonts for which no suitable ETX file is 
    available. This can be useful in early stages of the design of 
    a new font, but is inferior to installation using proper ETX 
    files since one for example cannot specify any ligatures in 
    MTX files.
\end{description}
Furthermore there is a special exception for the \meta{metrics}: if 
the first token in one of the list items is the control sequence 
|\metrics|, then the rest of that item is interpreted as explicit 
metric commands to execute.

If the \meta{metrics} of two subsequent |\install|\-|font| 
or |\install|\-|raw|\-|font| commands are identical then the glyph 
bases will be identical as well. This creates an opportunity for 
optimization, which \package{fontinst} makes use of by caching glyph 
bases from one installation command to the next so that the glyph 
base does not have to be rebuilt in these cases. A side-effect of 
this caching is that local assignments made between two font 
installation commands are cleared out with the glyph base, but 
|\setint| and similar \package{fontinst} commands make global 
assignments when used in such positions.

Some examples might be in order. The first is an adaptation of an 
installation command from \texttt{mfnt-0.59}~\cite{mfnt} by 
Matthias Clasen and Ulrik Vieth: the installation command for the 
8-bit math font \texttt{xma1000} (which can be thought of as being 
to \texttt{cmmi10} sort of as \texttt{ecrm1000} is to \texttt{cmr10}). 
The first three \texttt{encoding} clauses are more fine-tuning---without 
them, a few glyphs would get incorrect names---but the last two are 
quite essential, as the \texttt{msam10} and \texttt{msbm10} fonts 
incorrectly claim to have the coding scheme \texttt{TEX MATH 
SYMBOLS}.
\begin{verbatim}
  \installfont{xma1000}{%
     yma1000 encoding mcin,%
     cmr10 encoding ot1upright,%
     cmmi10,%
     cmsy10 encoding omscal,%
     msam10 encoding msam,%
     msbm10 encoding msbm,%
     mccmhax,mccmkern,mcmissing,%
     cmsy10-base,cmsy10-extra%
  }{mc}{MC}{cm}{m}{n}{<10->}
\end{verbatim}
Also note the explicit \LaTeX\ size specification for the range 
``10\,pt and up''.

The second example makes use of a \texttt{suffix} clause to combine 
the letters from one font with the digits from another.
\begin{verbatim}
  \installfont{msbrj8t}{msbr8r,msbrc8r suffix /2,latin}{digit2,t1}
    {T1}{msbj}{m}{n}{}
\end{verbatim}
In this case, the glyph base contains the glyphs of Monotype Sabon 
(SabonMT)---under names such as \texttt{A} for `A', \texttt{a} for 
`a', and \texttt{one} for a lining digit one---as well as the 
glyphs of Monotype Sabon Small Caps and Oldstyle Figures 
(SabonMT-SCOSF)---under names such as \texttt{A/2} for `A', 
\texttt{a/2} for `\textsc{a}', and \texttt{one/2} for a hanging 
digit one. The \texttt{digit2.etx} file simply makes the definition
\begin{verbatim}
  \setcommand\digit#1{#1/2}
\end{verbatim}
which causes \texttt{t1.etx} to put \texttt{zero/2} in slot 48 (digit 
zero), \texttt{one/2} in slot 49 etc., instead of as it normally 
would \texttt{zero} in slot 48, \texttt{one} in slot 49 and so on. 
The net effect is that the digits in the generated \texttt{msbrj8t} 
is from \texttt{msbrc8r} (SabonMT-SCOSF) but everything else is from 
\texttt{msbr8r} (SabonMT).

The third example makes use of an \texttt{mtxasetx} clause to install 
(with its default encoding) a font for which creating an appropriate 
ETX file seems not worth the trouble.
\begin{verbatim}
  \installrawfont{psyr}{psyr,\metrics 
     \setint{xheight}{\height{alpha}}
  }{txtfdmns,psyr mtxasetx}{U}{psy}{m}{n}{}
\end{verbatim}
The effect of the second \texttt{psyr} is that \texttt{psyr.mtx} is 
read (in case there was no \texttt{psyr.mtx} then it is created from 
(hopefully) \texttt{psyr.afm}) and the information in it will form 
the glyph base. Because of the |\metrics| control sequence, the rest 
of that item will be interpreted as explicit metric commands 
modifying the glyph base, and thus the |\setint| command can provide 
a value for the \texttt{xheight} variable (there doesn't seem to be 
such a value in the AFM). Once the glyph base is completed, the 
|\install|\-|raw|\-|font| starts writing the file \texttt{psyr.pl} 
(that's for the first \texttt{psyr}). The encoding of that font will, 
because of the \texttt{psyr mtxasetx}, be the same as that used in 
\texttt{psyr.mtx}. Finally, the \texttt{txtfdmns} is for 
\texttt{txtfdmns.etx}, an ETX file which sets fontdimens 1--16 as for 
a \texttt{T1} encoded font but does not set any slots. Since 
\texttt{psyr.mtx} reinterpreted as an ETX file sets slots but no 
fontdimens, these complement each other nicely.



\begingroup
\renewcommand\thesubsection{\thesection.\ensuremath{\infty}}

\subsection{Coming attractions}

We\footnote{Well, perhaps it's just me. /LH} have some new features 
which we have pretty much sorted out how they should work and how they 
should be implemented, but didn't want to introduce in this version as 
the large modifications in core systems would require another 
pre-release version before the proper release. Instead these features 
will probably appear in the first pre-release of \package{fontinst} 
v\,2.0.


\subsubsection{Bounding boxes}

Han The Thanh has created an implementation of bounding box support 
for \package{fontinst}, and it is a modified form of that support 
that will make it into \package{fontinst} v\,2.0. One important 
characteristic of this implementation is that the dimensions of the 
bounding box are not bundled into the same data structure (the 
|\g-|\meta{glyph} macros) as the glyph's width, height, depth, and 
italic correction are, but stored in a separate data structure (the 
|\gb-|\meta{glyph} macros). A glyph doesn't need to have its bounding 
box set, it is simply a piece of information that \package{fontinst} 
will store if you tell it to and which you can later retrieve.

The bounding box will be stored as coordinates of the sides in the 
normal AFM coordinate system. The commands for retrieving these 
coordinates will probably be
\begin{center}
  \begin{tabular}{ll}
    \textbf{Command}& \textbf{Side}\\
    |\bbtop|\marg{glyph}& top ($y$-coordinate)\\
    |\bbbottom|\marg{glyph}& bottom ($y$-coordinate)\\
    |\bbleft|\marg{glyph}& left ($x$-coordinate)\\
    |\bbright|\marg{glyph}& right ($x$-coordinate)
  \end{tabular}
\end{center}
In Thanh's implementation the command names are |\ury|, |\lly|, 
|\llx|, and |\urx| respectively instead, but I think the former are 
easier to remember. If no bounding box has been set for a glyph then 
the above commands will instead report the corresponding coordinate of 
the glyph's \TeX\ box (i.e.\ |\height|\marg{glyph}, 
|\neg{\depth|\marg{glyph}|}|, |0|, and |\width|\marg{glyph} 
respectively).

The command for setting the bounding box of a glyph will be
\begin{quote}
  |\setglyphbb|\marg{glyph}\marg{left}\marg{bottom}\marg{right}^^A
  \marg{top}
\end{quote}



\endgroup


\section{Notes on using \package{fontinst}}
\label{Sec:NotesOnUsing}

The primary purpose of \package{fontinst} is to simplify the
installation of PostScript or TrueType text fonts.


\subsection{General notes}

Leaving aside unusual variants which require special attention such 
as alternate or swash fonts, almost all standard font families can 
be installed automatically using the |\latinfamily| command, 
optionally making use of the corresponding expert fonts as well.

Depending on what kind of fonts you have and want to install,
|\latinfamily| supports three different modes of operation:

|\latinfamily|\marg{fam}|{}| installs a normal font family using
|8a|-encoded standard fonts (reencoded to |8r|) and nothing else.
It installs |.fd| files for the \LaTeX{} families \texttt{8r}\meta{fam},
\texttt{OT1}/\meta{fam}, \texttt{T1}/\meta{fam} and 
\texttt{TS1}/\meta{fam}, and generates virtual fonts for the |7t|, 
|8t|, and |8c| encodings.  This is the only option available for most 
typefaces which do not have an expert set.

|\latinfamily{|\meta{fam}|x}{}| installs an expertized font family using
|8a|-encoded standard fonts (reencoded to |8r|) and |8x|-encoded
expert fonts.  It installs |.fd| files for the \LaTeX{} families,
\texttt{OT1}/\meta{fam}\texttt{x}, \texttt{T1}/\meta{fam}\texttt{x} and 
\texttt{TS1}/\meta{fam}\texttt{x}, and generates virtual fonts for the 
|9t|, |9e| and |9c| encodings.

|\latinfamily{|\meta{fam}|j}{}| installs an expertized font family with
oldstyle digits using |8a|-encoded standard fonts (reencoded to
|8r|) and |8x|-encoded expert fonts.  It installs |.fd| files for
the \LaTeX{} families, |OT1|/\meta{fam}|j|, |T1|/\meta{fam}|j| and 
|TS1|/\meta{fam}|j|, and generates virtual fonts for the |9o|, |9d| and 
|9c| encodings. Since \texttt{TS1} has oldstyle digits by default, the 
|9c|-encoded fonts should be the same as in the previous case.  Finally,
|\latinfamily{|\meta{fam}|9}{}| is also supported as an alternative to
|\latinfamily{|\meta{fam}|j}{}| for backwards compatibility.

The whole installation process relies on certain assumptions about
the symbol complement of Adobe's expert fonts.  In particular, it is
assumed that the expert fonts include the oldstyle digits and a
complete set of small caps glyphs, which is an assumption that's not
always satisfied for expert fonts by other suppliers.  If these
glyphs are not included in the expert fonts, the only way to get
them is from real small caps fonts, but this requires some
reshuffling of glyph names.

To support such unusual cases, this source file contains some
optional code embedded between \Module{*oldstyle} \dots\ 
\Module{/oldstyle},
which extends the behaviour of |\latinfamily| for expertized
encodings with oldstyle digits.  Instead of relying only on the
glyphs of the |8r|-reencoded raw font and the |8x|-encoded expert
font, this version also looks for corresponding OsF or SC\&OsF fonts
and uses the default digits from those fonts as oldstyle digits.


\subsection{Notes on small caps and oldstyle fonts}

The |\latinfamily| command is supposed to do a reasonably good job
of installing a complete font family based on all the |.afm| files
it can find.  If it doesn't find a suitable font shape, it is
sometimes possible to fake it by default substitutions.  However, in
the case of small caps fonts, there are several options which may
require some clarification.

For the majority of typefaces, a font family typically consists only
of of roman and italic fonts in several weights.  Since real small
caps fonts are not included, they have to be faked from the roman
fonts, which is implemented by setting |\encoding_shape| to `|c|',
so that different encoding files |OT1c.etx| or |T1c.etx| are used.
Since these files call for glyph names such as `|Asmall|' which are
not found in the roman font, the default substitutions in
|latin.mtx| are eventually used to approximate fake small caps
glyphs by scaling and letterspacing.  The outcome is just an
approximation for a small caps font, but it is better than nothing.

For a small number of typefaces, the standard fonts are complemented
by an expert collection, which usually includes two sets of fonts.
First, for each standard font there is a corresponding expert font
containing additional glyphs such as extra ligatures and symbols,
oldstyle digits and small capital letters.  For Adobe expert fonts
this set is sufficient to build a complete small caps font from the
standard and expert glyphs. Furthermore, the expert collection
usually also contains a number of real small caps font corresponding
to the roman fonts and some OsF fonts corresponding to the italic
fonts.  If these fonts are available, there are several options how
to install small caps fonts.

By default, |\latinfamily| first tries to find a real small caps
font.  If it is found, it is installed using the default encoding
files and metric files, just like any roman or slanted font.
However, once |\latinfamily| has taken this choice, it will fail to
find a corresponding expert font, since it is actually looking for
an expert font in small caps shape which doesn't exist.  (In fact,
it would be an error to substitute an expert font in normal shape.)
The outcome will be a virtual font based only on glyphs from the
real small caps raw font, which implies ending up with oldstyle
digits as the default set of digits, but allows to inherit the
kerning information of the real small caps font.

Another option for an expertized installation would be to make the
real small caps fonts unavailable, so that |\latinfamily| will
attempt to fake a small caps font using glyphs from the standard and
expert fonts in normal shape.  This means that |\encoding_shape| is
again set to `|c|', so that |OT1c.etx| and |T1c.etx| are used, but
this time a glyph named `|Asmall|' does exist in the expert font and
will be used instead of faked one generated by scaling.  The outcome
will be a font based on normal and small caps glyphs from the
standard and expert fonts.  The oldstyle digits will only be used if
they are called for, otherwise the default digits from the roman
font are used.  The only drawback of this approach is that the
kerning around small capital letters will be based on the scaled
kern amounts of the capital letters rather than on the kern pairs
from the real small caps font.

Finally, the most promising approach of all these options would be
to combine the glyphs from standard and expert fonts with kern pairs
from the real small caps fonts. The current version of |\latinfamily| 
does not implement this, but it would be a worthwhile approach, and 
advanced \package{fontinst} users are encouraged to attempt it. The 
file \texttt{csckrn2x.tex} (a variant of \texttt{csc2x.tex}, which is 
mentioned in Subsection~\ref{Ssec:Des:Reglyph}) should come in handy 
for this.


\subsection{\package{fontinst} variables}

The following is a list of the \package{fontinst} variables that are 
accessible for the user through the |\set|\textellipsis, 
|\reset|\textellipsis, |\unset|\textellipsis, etc.\ commands. You may 
of course set or use other variables in the MTX and ETX files you 
write yourself, as does for example the standard MTX file 
\texttt{latin.mtx}, but all variables that \package{fontinst} commands 
implicitly use or set are listed below.

\begin{list}{}{%
   \setlength\labelwidth{0pt}%
   \setlength\itemindent{-\leftmargin}%
   \setlength\parsep{0pt}
   \def\makelabel#1{\hspace\labelsep \normalfont\ttfamily #1}%
}
  \item[acccapheight] (integer denoting length)
    \begin{smalldes}
      \item[Description] The height of accented full capitals.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[address] (string)
    \begin{smalldes}
      \item[Description] Snailmail address put in \BibTeX-style file 
        header of automatically generated ENC files. No 
        \texttt{address} field is written unless the \texttt{address} 
        string is set. Quotes are not automatically inserted around 
        the \texttt{address} string.
      \item[Set by] ETX files.
      \item[Used by] The ETX-to-ENC converter.
    \end{smalldes}
  \item[afm-name] (string)
    \begin{smalldes}
      \item[Description] Name of source font. Internal variable.
      \item[Set by] |\from|\dots\ commands.
      \item[Used by] The |\transform|\-|font|, |\install|\-|font|, 
        |\install|\-|raw|\-|font|, and |\reglyph|\-|font| commands.
    \end{smalldes}
  \item[ascender] (integer denoting length)
    \begin{smalldes}
      \item[Description] The ascender height of the font.
      \item[Set by] MTX files. The AFM-to-MTX converter usually writes 
        |\setint| commands for this integer.
      \item[Used by] Some MTX and ETX files.
    \end{smalldes}
  \item[author] (string)
    \begin{smalldes}
      \item[Description] Author name(s) put in \BibTeX-style file 
        header of automatically generated ENC files. See the macro 
        |\ref_to_sourcefile| for more details.
      \item[Set by] ETX files.
      \item[Used by] The ETX-to-ENC converter. When not set, the 
        value \texttt{"See file }\meta{etx name}\texttt{"} is used 
        instead.
    \end{smalldes}
  \item[\cs{autoinstallfamily}] (command)
    \begin{smalldes}
      \item[Description] Command called by the font installation 
        commands, as
        \begin{quote}
          |\autoinstallfamily|\marg{encoding}\marg{family}
        \end{quote}
        when they are asked to install a font with a combination of 
        \meta{encoding} and \meta{family} that has not been seen 
        before (there was no explicit |\installfamily|).
      \item[Set by] Explicit commands. Defaults to calling 
        |\installfamily|.
      \item[Used by] Font installation commands.
    \end{smalldes}
  \item[axisheight] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{22}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[baselineskip] (integer denoting length)
    \begin{smalldes}
      \item[Description]
        The font designer's recommendation for natural length of the 
        \TeX\ parameter |\baselineskip|.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[bigopspacing1] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\xi\sb{9}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[bigopspacing2] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\xi\sb{10}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[bigopspacing3] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\xi\sb{11}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[bigopspacing4] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\xi\sb{12}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[bigopspacing5] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\xi\sb{13}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[capheight] (integer denoting length)
    \begin{smalldes}
      \item[Description] The height of the font's full capitals.
      \item[Set by] MTX files. The AFM-to-MTX converter usually writes 
        |\setint| commands for this variable.
      \item[Used by] Some MTX and ETX files.
    \end{smalldes}
  \item[codingscheme] (string)
    \begin{smalldes}
      \item[Description] The codingscheme name.
      \item[Set by] ETX files.
      \item[Used by] The (V)PL writer. When not set, the 
        value \texttt{UNKNOWN} is used instead.
    \end{smalldes}
  \item[defaultrulethickness] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\xi\sb{8}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[delim1] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{20}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[delim2] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{21}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[denom1] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{11}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[denom2] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{12}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[descender] (integer denoting length)
    \begin{smalldes}
      \item[Description] The depth of lower case letters with descenders.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[descender_neg] (integer denoting length)
    \begin{smalldes}
      \item[Description] The vertical position of the descender line 
        of the font, i.e., the negative of the font's descender depth.
      \item[Set by] MTX files. The AFM-to-MTX converter usually writes 
        |\setint| commands for this variable.
      \item[Used by] Some MTX and ETX files.
    \end{smalldes}
  \item[designsize] (dimension)
    \begin{smalldes}
      \item[Description] The design size of the font.
      \item[Set by] MTX files. The (V)PL-to-MTX converter usually writes 
        |\setdim| commands for this variable.
      \item[Used by] The (V)PL writer. The design size defaults to 
        $10\,\mathrm{pt}$ if this variable is not set.
      \item[Note] The value of this variable has no effect on how 
        the font is declared to \LaTeX.
    \end{smalldes}
  \item[designunits] (dimension denoting a real number)
    \begin{smalldes}
      \item[Description] The design size of a font expressed in the 
        design unit used in a (V)PL file. 
      \item[Set by] MTX files. The (V)PL-to-MTX converter usually writes 
        |\setdim| commands for this variable.
      \item[Used by] Nothing. If this variable is set, but to any 
        value other than $1\,\mathrm{pt}$, then some metrics are most 
        likely wrong.
    \end{smalldes}
  \item[digitwidth] (integer denoting length)
    \begin{smalldes}
      \item[Description] The median width of the digits in the font.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[email] (string)
    \begin{smalldes}
      \item[Description] Email address put in \BibTeX-style file 
        header of automatically generated ENC files. See the macro 
        |\ref_to_sourcefile| for more details.
      \item[Set by] ETX files.
      \item[Used by] The ETX-to-ENC converter. When not set, the 
        value \texttt{"See file }\meta{etx name}\texttt{"} is used 
        instead.
    \end{smalldes}
  \item[encodingname] (string)
    \begin{smalldes}
      \item[Description] The name by which the encoding in question is 
        made known to a Postscript interpreter.
      \item[Set by] ETX files.
      \item[Used by] The ETX-to-ENC converter. When not set, the 
        value |fontinst-|\nolinebreak[1]|autoenc-|\nolinebreak[1]%
        \meta{etx name} is used instead.
    \end{smalldes}
  \item[etx-name] (string)
    \begin{smalldes}
      \item[Description] Name of ETX file. Internal variable in 
        |\transform|\-|font|.
      \item[Set by] The |\reencodefont| command.
      \item[Used by] The |\mtxtomtx| command.
    \end{smalldes}
  \item[extraspace] (integer denoting length)
    \begin{smalldes}
      \item[Description]
        The natural width of extra interword glue at the end of a 
        sentence.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[fontdimen($n$)] (integer)
    \begin{smalldes}
      \item[Description] Family of semi-internal variables that store 
         the values to use for font dimension $n$. It is preferred 
         that the newer |\set|\-|font|\-|dimen| interface is used for 
         setting these values.
      \item[Set by] ETX files.
      \item[Used by] The (V)PL writer.
    \end{smalldes}
  \item[\cs{iftokeep}] (macro)
    \begin{smalldes}
      \item[Description] |\iftokeep|\,\#1\,|\then|, where \#1 will 
        be a \meta{number}, behaves like a switch and decides whether 
        a glyph is kept or not while reglyphing.
      \item[Set by] Explicit commands. Defaults to
        $$
          \mbox{\cs{iftokeep}\,\#1\,\cs{then}} \mapsto
          \mbox{\cs{ifnum}\,\texttt{-1<}\#1}
        $$
      \item[Used by] The |\reglyphfont| command.
    \end{smalldes}
  \item[interword] (integer denoting length)
    \begin{smalldes}
      \item[Description] The natural width of interword glue (spaces).
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[italicslant] (integer denoting factor)
    \begin{smalldes}
      \item[Description] The italic slant of a font.
      \item[Set by] MTX files generated from AFM or (V)PL files. MTX 
        files generated by |\transformfont|. Locally in the AFM-to-MTX 
        converter for possible use in |\uprightitalcorr| or 
        |\slanteditalcorr|.
      \item[Used by] MTX files (\texttt{latin.mtx} and the like). ETX 
        files (for determining \texttt{fontdimen(1)}).
    \end{smalldes}
  \item[killweight] (integer)
    \begin{smalldes}
      \item[Description] Weight for glyphs that are killed.
      \item[Set by] Explicit commands. Defaults to $-10$ if not set.
      \item[Used by] The |\kill|\-|glyph| command; indirectly 
        the |\reglyphfont| command.
    \end{smalldes}
  \item[letterspacing] (integer denoting length)
    \begin{smalldes}
      \item[Description] Extra width added to all glyphs of a font.
      \item[Set by] ETX or MTX files.
      \item[Used by] The (V)PL writer. Defaults to $0$ if not set.
    \end{smalldes}
  \item[maxdepth] (integer denoting length)
    \begin{smalldes}
      \item[Description] The maximal depth over all slots in the font.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[maxdepth_neg] (integer denoting length)
    \begin{smalldes}
      \item[Description] The negative of the maximal depth of a glyph in 
        the font.
      \item[Set by] MTX files. The AFM-to-MTX converter usually writes 
        |\setint| commands for this variable.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[maxheight] (integer denoting length)
    \begin{smalldes}
      \item[Description] The maximal height of a glyph in the font.
      \item[Set by] MTX files. The AFM-to-MTX converter usually writes 
        |\setint| commands for this variable.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[minimumkern] (integer denoting length)
    \begin{smalldes}
      \item[Description] Kerns whose size in absolute value is less 
        than or equal to this variable are ignored.
      \item[Set by] \package{fontinst} command files or MTX files.
      \item[Used by] The AFM-to-MTX converter and the (V)PL file 
        generator. When not set, the value $0$ is used instead.
    \end{smalldes}
  \item[monowidth] (flag integer)
    \begin{smalldes}
      \item[Description] Set if this font is monowidth, unset otherwise.
      \item[Set by] MTX files. The AFM-to-MTX converter writes a 
        |\setint| command for this variable if the AFM specifies 
        \texttt{IsFixedPitch true}.
      \item[Used by] Some MTX files (\texttt{latin.mtx} and the like), 
         ETX files.
    \end{smalldes}
  \item[num1] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{8}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[num2] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{9}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[num3] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{10}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[quad] (integer denoting length)
    \begin{smalldes}
      \item[Description]
        The quad width of the font, normally approximately equal to 
        the font size and\slash or the width of an `M'.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[PSfontsuffix] (string)
    \begin{smalldes}
      \item[Description] Suffix added to font names to form name of 
        file to download to include font.
      \item[Set by] Explicit commands in \textsf{finstmsc} command 
        files. Defaults to `\texttt{.pfa}'.
      \item[Used by] The map file fragments writer.
    \end{smalldes}
  \item[rawscale] (integer denoting factor)
    \begin{smalldes}
      \item[Description] Scaling factor applied to raw glyphs.
      \item[Set by] The |\installfont| command (\texttt{scaled} 
        clauses in argument \#2). Unset for metric files listed 
        without a \texttt{scaled} clause.
      \item[Used by] The |\set|\-|raw|\-|glyph|, 
        |\set|\-|not|\-|glyph|, |\set|\-|scaled|\-|raw|\-|glyph|, 
        |\set|\-|scaled|\-|not|\-|glyph|, |\set|\-|kern|, and 
        |\reset|\-|kern| commands.
    \end{smalldes}
  \item[renameweight] (integer)
    \begin{smalldes}
      \item[Description] Weight for glyphs that are renamed.
      \item[Set by] Explicit commands. Defaults to $1$ if not set.
      \item[Used by] The |\rename|\-|glyph| command; indirectly 
        the |\reglyphfont| command.
    \end{smalldes}
  \item[requireglyphs] (flag integer)
    \begin{smalldes}
      \item[Description] Set if warnings are to be generated for 
        glyphs listed in ETX files but not present in the glyph 
        base.
      \item[Set by] Explicit commands. By defaults not set.
      \item[Used by] The (V)PL file generator.
    \end{smalldes}
  \item[rightboundary] (string)
    \begin{smalldes}
      \item[Description] The name of a glyph with the property that 
        kerns on the left may be intended as right word boundary kerns.
      \item[Set by] MTX files. The (V)PL-to-MTX converter can write 
        |\setstr| commands for this variable.
      \item[Used by] Some MTX files.
    \end{smalldes}
  \item[shrinkword] (integer denoting length)
    \begin{smalldes}
      \item[Description] 
        The (finite) shrink component of interword glue.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[slant-scale] (integer denoting factor)
    \begin{smalldes}
      \item[Description] Factor to slant by. 
        Internal variable in |\transform|\-|font|.
      \item[Set by] The |\slant|\-|font|, |\xscale|\-|font|, and
        |\scale|\-|font| commands.
      \item[Used by] The |\mtxtomtx| command.
    \end{smalldes}
  \item[\cs{SlantAmount}] (macro expanding to an integer expression)
    \begin{smalldes}
      \item[Description] Slant factor used for faking oblique shape.
      \item[Set by] Explicit commands. Defaults to \texttt{167}.
      \item[Used by] The |\latinfamily| command.
    \end{smalldes}
  \item[\cs{slanteditalcorr}]
    (macro expanding to an integer expression)
    \begin{smalldes}
      \item[Description] The integer expression used to calculate a 
        guess for the italic correction of glyphs in a font with 
        positive slant. It has the syntax
        \begin{quote}
          \cs{slanteditalcorr}\marg{width}\marg{left}\marg{right}^^A
          \marg{bottom}\marg{top}
        \end{quote}
        where \meta{width} is the glyph's advance width, and the 
        remaining arguments are coordinates of sides of the glyph's 
        bounding box. The \texttt{italicslant} integer provides the 
        italic slant of the font.
      \item[Set by] Explicit commands in \textsf{fontinst} command 
        files. Defaults to $\max\{0, \mathit{right}-\mathit{width}\}$.
      \item[Used by] The AFM-to-MTX converter.
    \end{smalldes}
  \item[stretchword] (integer denoting length)
    \begin{smalldes}
      \item[Description]
        The (finite) stretch component of interword glue.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[sub1] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{16}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[sub2] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{17}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[subdrop] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{19}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[sup1] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{13}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[sup2] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{14}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[sup3] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{15}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[supdrop] (integer denoting length)
    \begin{smalldes}
      \item[Description] Math formula parameter $\sigma\sb{18}$.
      \item[Set by] MTX files.
      \item[Used by] Some ETX and MTX files.
    \end{smalldes}
  \item[TFMfileprefix] (string)
    \begin{smalldes}
      \item[Description] Prefix (typically a path) added to names of 
        TFM files.
      \item[Set by] Explicit commands in \textsf{finstmsc} command 
        files. By default not set, which is equivalent to being empty.
      \item[Used by] The \textsf{PLtoTF} ``map file fragments writer''.
    \end{smalldes}
  \item[underlinethickness] (integer denoting length)
    \begin{smalldes}
      \item[Description] The recommended thickness of an underlining 
        rule.
      \item[Set by] MTX files. The AFM-to-MTX converter usually writes 
        |\setint| commands for this variable.
      \item[Used by] Some MTX files (\texttt{latin.mtx} and the like).
    \end{smalldes}
  \item[\cs{uprightitalcorr}]
    (macro expanding to an integer expression)
    \begin{smalldes}
      \item[Description] The integer expression used to calculate a 
        guess for the italic correction of glyphs in a font with 
        non-positive slant. It has the syntax
        \begin{quote}
          \cs{uprightitalcorr}\marg{width}\marg{left}\marg{right}^^A
          \marg{bottom}\marg{top}
        \end{quote}
        where \meta{width} is the glyph's advance width, and the 
        remaining arguments are coordinates of sides of the glyph's 
        bounding box. The \texttt{italicslant} integer provides the 
        italic slant of the font.
      \item[Set by] Explicit commands in \textsf{fontinst} command 
        files. Defaults to $0$.
      \item[Used by] The AFM-to-MTX converter.
    \end{smalldes}
  \item[version] (string)
    \begin{smalldes}
      \item[Description] Version number put in \BibTeX-style file 
        header of automatically generated ENC files. See the macro 
        |\ref_to_sourcefile| for more details.
      \item[Set by] ETX files.
      \item[Used by] The ETX-to-ENC converter. When not set, the 
        value \texttt{"See file }\meta{etx name}\texttt{"} is used 
        instead.
    \end{smalldes}
  \item[verticalstem] (integer denoting length)
    \begin{smalldes}
      \item[Description] The dominant width of vertical stems 
        (usually the width of stems of lower case letters).
      \item[Set by] MTX files. The AFM-to-MTX converter writes 
        |\setint| commands for this variable if the AFM file specifies 
        \texttt{StdVW}.
      \item[Used by] Currently nothing.
    \end{smalldes}
  \item[\texttt{warningspecials}] (switch)
    \begin{smalldes}
      \item[Description] Controls whether |\glyphwarning| commands 
        will generate VPL \texttt{SPECIAL}s. Defaults to `true'.
      \item[Set by] Explicit commands (|\warningspecialstrue| and 
        |\warningspecialsfalse|).
      \item[Used by] The (V)PL file generator.
    \end{smalldes}
  \item[x-scale] (integer denoting factor)
    \begin{smalldes}
      \item[Description] Horizontal scaling factor. 
        Internal variable in |\transform|\-|font|.
      \item[Set by] The |\xscale|\-|font| and |\scale|\-|font| commands.
      \item[Used by] The |\mtxtomtx| command.
    \end{smalldes}
  \item[xheight] (integer denoting length)
    \begin{smalldes}
      \item[Description] The x-height of the font.
      \item[Set by] MTX files. The AFM-to-MTX and (V)PL-to-MTX 
        converters usually write |\setint| commands for this variable.
      \item[Used by] MTX files, and ETX files (for determining 
        \texttt{fontdimen(5)}).
    \end{smalldes}
  \item[y-scale] (integer denoting factor)
    \begin{smalldes}
      \item[Description] Vertical scaling factor. 
        Internal variable in |\transform|\-|font|.
      \item[Set by] The |\yscale|\-|font| and |\scale|\-|font| commands.
      \item[Used by] The |\mtxtomtx| command.
    \end{smalldes}
  \item[\meta{\rmfamily glyph}-spacing] (integer denoting length)
    \begin{smalldes}
      \item[Description] Glyph-specific override for 
        \texttt{letterspacing}; extra width added to the glyph 
        \meta{glyph} as part of the process of writing a VPL 
        file.
      \item[Set by] ETX or MTX files.
      \item[Used by] The (V)PL writer. Defaults to $0$ if not set.
    \end{smalldes}
\end{list}
Besides these, the |\latinfamily| command provides a whole range of 
parameters that are often used somewhat like variables. That subject 
does however deserve to be treated separately.


\section{\package{fontdoc} package overview}

The purpose of the \package{fontdoc} package is to support
typesetting of \texttt{.etx} and \texttt{.mtx} files intended
for use with \package{fontinst}.
The typical format of these files looks something like this:
\begin{quote}
   |\relax|\\
   |\documentclass[twocolumn]{article}|\\
   |\usepackage{fontdoc}|\\[0.5\baselineskip]
   |\begin{document}|\\
   {}~~\textit{\LaTeX\ commands}\\
   |\encoding| or |\metrics| \\
   {}~~\textit{\package{fontinst} commands}\\
   |\endencoding| or |\endmetrics|\\
   {}~~\textit{\LaTeX\ commands}\\
   |\end{document}|
\end{quote}
To make it work, \package{fontdoc} has to define all the user-level
\package{fontinst} commands in terms of typesetting instructions. This 
goal is currently only partially achieved, but the percentage of 
\package{fontinst} commands covered by \package{fontdoc} is still 
fairly large, so it is our impression that problems with commands not 
covered occur only very rarely.


\subsection{Some \package{fontdoc} commands that \package{fontinst} 
  doesn't know}

Some of the commands defined by \package{fontdoc} are not defined by 
\package{fontinst} because they have no meaning in that context. 
Most of these commands are lower-level commands that are used in the 
implementations of commands common to \package{fontinst} and 
\package{fontdoc}, but a few are simply only meant to be used in the 
parts of ETX and MTX files that \package{fontinst} never executes.

With v\,1.916 the mechanism for formatting integer expressions changed 
dramatically. The new base command to use is 
\DescribeMacro{\TypesetIntegerExpression}|\Typeset|\-|Integer|\-%
|Expression|, which takes as its only argument the integer expression 
to format and typesets it. |\Typeset|\-|Integer|\-|Expression| expects 
to be used in math mode only. A similar command is 
\DescribeMacro{\TypesetStringExpression}|\Typeset|\-|String|\-%
|Expression|, which takes a string expression as argument, formats, 
and typesets it. |\Typeset|\-|String|\-|Expression| can be used in any 
mode.

The \DescribeMacro{\macroparameter}|\macroparameter| command is (in 
integer and string expressions) understood as a ``placeholder for a 
macro parameter''. This is primarily useful in comments that describe 
a user-defined macro; see \texttt{ltcmds.mtx} for examples.



% \part*{Implementation}
% \addcontentsline{toc}{part}{Implementation}

\changes{1.800}{1998/06/22}{\texttt{fontinst.sty} and 
   \texttt{fontdoc.sty} now generated from \texttt{fontinst.dtx}. (UV)}
\changes{1.900}{1999/02/05}{\texttt{fontinst.dtx} split into several 
   source files. (LH)}
\changes{1.902}{1999/04/18}{Fixed some silly markup. (LH)}

\DocInclude{fibasics}
\DocInclude{ficommon}
\DocInclude{fimain}
\DocInclude{ficonv}
\DocInclude{filtfam}
\DocInclude{fimapgen}

\PrintIndex
\pagestyle{plain}\tracingmacros=2\tracingcommands=2
\PrintChanges
\tracingcommands=0\tracingmacros=0

\clearpage
\appendix
\part*{Internal notes}
\addcontentsline{toc}{part}{Internal notes}


\section{Typographic treatment}

\begin{itemize}
  \item
    I have been following \emph{The \LaTeX\ Companion} in that I have 
    set all names of packages and the like---\package{fontinst}, 
    \package{fontdoc}, \package{trig}, \package{doc}, and 
    \package{docstrip} (I might have forgotten some)---in sans serif 
    type. Actually, I have defined a command |\package| in 
    \texttt{fisource.sty} (or is that \package{fisource}?) which does 
    this, so if we decide on some other formatting, we can just change 
    that. /LH
  \item
    It seems to me that there should indeed be some space between the 
    `v' and the digits in a version number when it is typeset, but I 
    also think a full space is too much, so I have been using thin 
    spaces. These are unbreakable and under \LaTeX\ you can simply use 
    |\,| to get one (while you are not in math mode, that is). /LH
  \item
    While I went through (some of) the code, I came across a few 
    inconsistencies. \ambiguity{I have marked them out like this%
    \offindex}---some boldfaced text in a paragraph and a large A 
    in the margin. I defined a command |\ambiguity| for doing this. /LH
  \item
    There is also a similar command |\question| which is intended for 
    situations where there isn't really an error, but something seems 
    like it should be taken care of in some other way. \question{The 
    \cs{question} command puts a question mark in the margin.%
    \offindex}
  \item
    I also noticed that there are several \package{fontinst} commands, 
    not all of which are new, which are not defined in \package{fontdoc}. 
    {\offindex\missing{doc}{\foo}}To mark out such things, I have 
    written things like the one shown in the margin by this paragraph. 
    I defined a command |\missing| for doing this. /LH
\end{itemize}


\section{Planning topics}

This section lists items in the larger design of \package{fontinst} 
which need to be resolved in one way or another. Debates about these 
items on the fontinst mailing list are welcome.


\subsection{Reorganisation of the source}

At the moment, all the ideas suggested have been realized.
% \begin{itemize}
%   \item
%     How about moving the first section of \texttt{fimain.dtx} to 
%     \texttt{fibasics.dtx}? /LH
%   \item
%     How about extracting the code which has to do with file 
%     conversions (Sections~\ref{Sec:Conv. input}, 
%     \ref{Sec:Font.trans}, and Subsection~\ref{Ssec:MTX->PL}) from 
%     \texttt{fimain.dtx} and put it in a file of its own 
%     (\texttt{ficonv.dtx}, say)? /LH
% \end{itemize}


\subsection{Files}

Which files should be considered temporary and placed in the location 
specified with |\tempfileprefix|? Should files be explicitly be looked 
for at this location or should it be assumed that fontinst users 
include that location in their \TeX\ input file search path? In the 
former case, \emph{which} files should be looked for in that 
location? Should files be looked for in the temporary location before 
they are looked for without a specified location, or should it be the 
other way round?





\section{Contributors}

[The \package{fontinst} source has been pretty inconsistent in how 
people are credited for what they have done---some appear only as 
acronyms while others appear as rather striking e-mail addresses---so 
I thought it best that this is shaped up a bit. My suggestion is that 
we use names or acronyms in the source and move everything else here. 
I also thought it could be interesting with a short description of 
what each person has done and is doing, so I have started ever so 
slightly on something along those lines. Feel free to add things! /LH]

\medskip

The following people have contributed substantial amounts of code or 
documentation to \package{fontinst}. They are listed in strict 
alphabetical order.

\begin{description}
  \item[Thierry Bouche]
    Thierry saw to that the \texttt{T1} encoded fonts got font 
    dimensions comparable to the \texttt{ec} fonts. Thierry is also 
    the author of several papers (published in the \textit{Cahiers 
    GUTenberg} and \textit{TUGboat}) which deal with non-trivial 
    applications of \package{fontinst}, such as creating metrics for 
    Adobe Minion Multiple Master fonts and developing a corresponding 
    math font setup.
    
    E-mail: \texttt{Thierry.Bouche@ujf-grenoble.fr}
    
  \item[Lars Hellstr\"om (LH)]
    Lars is responsible for most of the things in v\,1.9 that were 
    not there in v\,1.8.
    
    Lars is currently a member of the \package{fontinst} 
    maintenance team. He is also a Ph.D.\ in mathematics looking for 
    employment.
    
  \item[Alan Jeffrey (ASAJ)]
    Alan is the original author of \package{fontinst}. He is not 
    currently on the development team, but he is still managing the 
    \package{fontinst} mailing list.
    
    E-mail (\package{fontinst} mailing list subscriptions):%
    \nobreak\hfill\penalty0\hskip -2em plus -1fill\ \relax
    \vadjust{}\nobreak\hskip 2em\relax
    \texttt{fontinst-request@cogs.susx.ac.uk}.
    
  \item[Constantin Kahn (CK)]
    Constantin is one (Sebastian is the other) of the original coauthors 
    of the current |\latinfamily| command.
    % \footnote{Am I right about this? It's a bit before my time, 
    % I've just read \texttt{CHANGES}. /LH}
    
  \item[Rowland McDonnell]
    Rowland rewrote Alan's old v\,1.5 documentation for 
    \package{fontinst} and updated it for v\,1.8. 
  
  \item[Sebastian Rahtz (SPQR)]
    Sebastian is one (Constantin is the other) of the original coauthors 
    of the current |\latinfamily| command. He has also contributed 
    numerous ETX files and made the ``unofficial'' v\,1.6 and v\,1.7, 
    which included the first \package{fontinst} support for making 
    \texttt{TS1} encoded files.
    
  \item[Ulrik Vieth (UV)]
    Ulrik converted \texttt{fontinst.sty} to \package{doc}\slash
    \package{docstrip} format, reunited Alan's v\,1.511 and 
    Sebastian's v\,1.7, and made the first official release of 
    \package{fontinst} (v\,1.8) for more than two years.
    
    Ulrik is currently a member of the \package{fontinst} 
    maintenance team. He is also involved in the Joint TUG\slash 
    \LaTeX~3 Project Working Group on extended math font encodings.
    
  \item[\textellipsis]
\end{description}
Anyone else?


\section{To do}

This section is based on the \texttt{TODO} file from \package{fontinst} 
v\,1.504, but a couple of new entries have been added and some have 
been equipped with comments.

\subsection{Things to do in the ``near'' future}

\begin{itemize}
  \item
    Update documentation. (Lars, knowing he isn't saying anything new)
  
  \item
    Rewrite the entire substitution mechanism from scratch! The main 
    problem with the current mechanism is that it only allows one 
    substitution per shape and one per series. One cannot substitute 
    the |it| shape for both the |sl| and the |ui| shapes since each 
    new |\substitute|(|noisy|\textbar|silent|) with |it| in the 
    \meta{from} argument will overwrite the setting made by the 
    previous; 
    \begin{quote}
      |\substitutenoisy{ui}{it}|\\
      |\substitutesilent{sl}{it}|
    \end{quote}
    is effectively the same as
    \begin{quote}
      |\substitutesilent{sl}{it}|
    \end{quote}
    Another big problem is that it isn't well defined what the 
    substitution mechanism should do. (Lars)
    
    I've got a sketch for a new substitution mechanism, but I'm not 
    at all sure it will make it into any v\,1.9xx. /LH 
    (The code that was written is now in \texttt{fimain.dtx}, but 
    it's not included in any of the generated files.)
    
    An alternative to substitutions is to use explicit 
    |\installfontas| commands. This provides complete control. /LH
  
  \item
    Consider removing the following unreliable fakes from 
    \texttt{textcomp.mtx}:
    \begin{quote}
      \texttt{asciiacutedbl}, \texttt{asciigravedbl}, 
      \texttt{bardbl}, \texttt{openbracketleft}, and
      \texttt{openbracketright}
    \end{quote}
    and consider adding fakes for the following unavailable glyphs:
    \begin{quote}
      \texttt{dollaroldstyle} (use \texttt{dollar}), 
      \texttt{centoldstyle} (use \texttt{cent}), \texttt{lira} (use 
      \texttt{sterling}), and \texttt{pilcrow} (use 
      \texttt{paragraph})
    \end{quote}
    These suggestions are of course open for debate. (Ulrik)
  
  \item
    One thing I miss in [the typeset form of an encoding 
    specification] is a simple hex/octal/decimal chart showing all 
    the character names in their positions (and ideally even an 
    example of the printed character, although I know that would be 
    harder). (Karl Berry)
    
\end{itemize}


\subsection{Things that probably won't be done in the near future}

\begin{itemize}
  \item
    Find a way to automatically generate math fonts. (Alan)
    
    I doubt that this will ever be possible to do automatically.
    \package{mathptm} and \package{mathptmx} are already hackish enough, 
    not to mention the prototype implementations for new math font 
    encodings. /UV
    
  \item
    Investigate using Alternate sets. (Alan)
    
    AFAIK, Thierry Bouche has done some work with alternate sets 
    for AGaramond, ACaslon and Minion, but this implies a lot of
    manual work to compose the proper calls to \package{fontinst}. /UV
    
  \item
    Create \LaTeX\ packages?  In fact, rethink the whole package
    interface \textellipsis\ (Alan) 
    
    Sebastian's Perl front-end to \package{fontinst} does create trivial
    \LaTeX\ packages automatically for the CTAN fonts. /UV
    
  \item
    Worry about excessive kern tables in \texttt{T1} fonts. (Alan)
    
    I think the best way to get at this would be to write a program 
    that can optimize (for size) kern tables by making use of the |SKIP| 
    instruction. There's often room for quite a lot of compression. 
    Such a program would however have to be written in some compiling 
    language, otherwise it wouldn't be fast enough. /LH
  
  \item
    Consider making |\set|(|left|\textbar|right|)|kerning| parameterized 
    by the size of the other glyph, eg so that faking |<Asmall><T>| can 
    be different from |<Aacutesmall><T>|.  Suggested by Hilmar Schlegel.

\end{itemize}


\subsection{Things that have been done}

\begin{itemize}
  \item
    Update documentation (comments from Karl and Damian).
    
    Rowland has meritoriously done the update requested here. On the 
    other hand, it needs to be updated again, since many new features 
    have been added. /LH
  
  \item
    Investigate using raw SC fonts. (Alan)
    
    This problem comes up on the mailing list from time to time.
    The problem is that \package{fontinst}'s |\latinfamily| command 
    is geared towards fonts that come with standard and expert font 
    sets (as with Adobe and Monotype fonts) rather than fonts that 
    come with standard and small caps (as with Linotype fonts). 
    I'm afraid it would be to complicated to handle both cases
    in the same |\latinfamily| procedure. /UV
  
  \item
    Investigate problems with duplicate kerns appearing in VPL files
    (Hilmar Schlegel).
    
    The problem has been investigated and is solved with v\,1.9. /LH
  
  \item
    Find out why, if you have a font with both medium and light variants
    but no italic, you get |m|/|it| $\mapsto$ |l|/|it| $\mapsto$ 
    |l|/|sl| rather than |m|/|it| $\mapsto$ |m|/|sl|.
    (Sebastian).
    
    Because for every shape that \package{fontinst} is allowed to use 
    a given font for, it will perform all possible series substitutions. 
    If the |\installfont| for |l|/|sl| came before the |\installfont| for 
    |m|/|sl|, then substitutions will be as described above. See also 
    item about the substitution mechanism. /LH
  
  \item
    AFM files can contain real units, not just integers.  (Gintautas
    Grigelionis).
    
    This is fixed with v\,1.9. /LH
  
  \item
    Make \texttt{fontdoc.sty} and co.\ use PS fonts. (Alan)
    
    I think |\useexamplefont| and friends (introduced with v\,1.8) 
    pretty much do what was intended here. /LH
  
  \item
    \texttt{latin.mtx} uses \package{fontinst} rather than 
    \package{fontdoc}!  (Rob Hutchings).
  
  \item
    Allow |.vpl| files to be read as |.pl| files.  (Constantin)
  
  \item
    Richard Walker reports that if you say
    \begin{quote}
      |\latinfamily{mbvx}{}|\\
      |\latinfamily{mbv9}{}|
    \end{quote}
    then the 2nd run doesn't use old-style digits, because the 1st run 
    has already defined |\digit|. If so, this is because |\latinfamily| 
    is missing a bracing level. I should investigate.
    
    I think it is best to do oldstyle and non-oldstyle variants in two
    separate fontinst runs, i.e. don't use |\latinfamily| more than once 
    in a single run.  (IIRC, grouping doesn't work properly since 
    every single font closes and reopens a |\begingroup|-|\endgroup| 
    pair to encapsulate the kerning info\footnote{And glyph metrics 
    info, and glyph mapcommands info \textellipsis /LH} or something 
    like that.) /UV

  \item
    Consider writing an |\installfontas| command which doesn't 
    generate a (V)PL but makes an entry in the FD file. 
    Typical usage: Install an \texttt{sc} shape of a \texttt{TS1} 
    font family by using the font made for the \texttt{n} shape. 
    (Lars)
    
    Done. The described installation for the \texttt{m} series of the 
    \texttt{ptm} font family can be done through
    \begin{quote}
      |\installfontas{ptmr8c}{TS1}{ptm}{m}{sc}{}|
    \end{quote}
    Note however that you need to do it in each series explicitly. /LH
  
  \item
    Use the \texttt{StdVW} property from AFM 4.0 files instead of the 
    width of \textit{I} for standard stem fontdimen. Pointed out by 
    Hilmar Schlegel.
    
    Partially done. |\afmtomtx| writes a 
    |\setint{verticalstem}|\marg{value} when it encounters a 
    \texttt{StdVW} property. The ETX files have not yet (2000/05/30) 
    been changed to use this value. /LH
  
  \item
    \package{fontdoc} has a problem with glyph, integer, string, 
    etc.\ names that contains underscores, since these will cause 
    \TeX\ to jump to math mode when one tries to typeset these things. 
    Unfortunately \package{fontinst} itself writes two such integers: 
    \texttt{descender_neg} and \texttt{maxdepth_neg}. There are at 
    least three solutions to this. The first is to make underscore an 
    `other' character throughout, but this might break some comments in 
    MTX and ETX files. The second is to temporarily change the catcode 
    in the arguments of the commands, but that will complicate the 
    definitions of almost all \package{fontdoc} commands dramatically. 
    The third is to declare this as unsupported by \package{fontdoc} and 
    change \package{fontinst} so that the troublesome integers are 
    renamed, e.g.\ \texttt{descender-neg} and \texttt{maxdepth-neg}, but 
    this can break people's code. (Lars)
    
    After thinking about it for a couple of months, I realized that 
    none of the above is the right solution. That is instead to use 
    something similar to the harmless character strings of the 
    \package{xdoc} package when typesetting names of variables etc.\ 
    in \package{fontdoc}. This got implemented in v\,1.916. /LH
  
  \item
    Modify the (V)PL-to-MTX converter so that |\setint|\discretionary
    {}{}{}|{fontdimen(|\meta{n}|)}|\discretionary{}{}{}|{\int|%
    \marg{name}|}| commands in the ETX file declare that 
    \texttt{PARAMETER} (or equivalent) properties for fontdimen 
    \meta{n} should be converted to |\setint| commands for the integer 
    \meta{name}. This ought to be particularly useful for math fonts. 
    (Lars)
    
    Done with v\,1.917, but only for the new \cs{setfontdimen} 
    command. /LH
  
  \item
    Update \texttt{fontdoc.sty} and co.\ for \LaTeXe. (Alan)
    
    \texttt{fontdoc.sty} underwent a major overhaul from v\,1.916 on, 
    so I suspect this can be said to have been done now. The basic 
    vertical spacing put in by \cs{Aheading} and \cs{Bheading} may 
    however need more work; sometimes it doesn't come out as one 
    would want it to. /LH
  
  \item
    \texttt{latin.mtx} fakes composite SC glyphs [kerning?] from the 
    composite glyph, eg.
    \begin{quote}
      |\setleftrightkerning{Aacutesmall}{Aacute}{900}|,
    \end{quote}
    rather than from the SC non-composite, eg.
    \begin{quote}
      |\setleftrightkerning{Aacutesmall}{Asmall}{1000}|
    \end{quote}
    This may cause problems with SC fonts with explicit SC--C kerns, 
    eg.
    \begin{quote}
      |\setkern{V}{Asmall}{100}|
    \end{quote}
    This needs to be thought about. Pointed out by Hilmar Schlegel.
    
    \texttt{newlatin.mtx} does this right; shrunk glyphs get shrunk 
    kerning, whereas constructed glyphs get kerning from the base 
    letter. /LH
  
\end{itemize}


\subsection{Other notes}

Alan's \texttt{TODO} file also contains some items regarding 
\package{mathptm}, but that seems to have migrated out of 
\package{fontinst} (if it ever really was a part). The problem is that 
\package{mathptm} cannot be changed any more for the sake of checksum 
consistency and backwards compatibility. A new variant called 
\package{mathptmx} tries to do a little better, but there may still be 
room for improvements.



\section{Efficiency}

This section records the results of some (rather simple) test runs 
that have been made to test the efficiency of \package{fontinst}, 
primarily to see how changes in the implementation affect efficiency 
by comparing the time and space used by different \package{fontinst} 
versions to complete the same task.


\subsection{Alan Jeffrey's tests}
\label{Ssec: ASAJ tests}

I compared the version where you try to keep ints as |\mathchardef|s 
with the version where you don't bother, and for a sample font without 
|\mathchardef|s I got:
\begin{quote}
  114673 words of memory out of 150001\\
  Time elapsed: 135.0 seconds
\end{quote}
and with, I got:
\begin{quote}
  114050 words of memory out of 150001\\
  Time elapsed: 134.5 seconds
\end{quote}
so I've saved a little memory and time.  Not brilliant, but I may as
well keep it in.

Where possible, we avoid re-scaling kerns, which saves a bit of time 
and memory.  With a sample font, the version where we didn't avoid
re-scaling used:
\begin{quote}
  114050 words of memory out of 150001\\
  Time elapsed: 134.5 seconds
\end{quote}
whereas the version where we do avoid it used:
\begin{quote}
  113786 words of memory out of 150001\\
  Time elapsed: 124.9 seconds
\end{quote}

We keep the names of the glyphs to kern with as |\l-|\meta{name} and 
|\r-|\meta{name} to save on token space, and this got the resources 
used down to:
\begin{quote}
  88574 words of memory out of 150001\\
  Time elapsed: 106.1 seconds
\end{quote}
Keeping track of the kern amounts as |\|\meta{amount} got the resources
used down to:
\begin{quote}
  75424 words of memory out of 150001\\
  Time elapsed: 97.2 seconds
\end{quote}
Mind you, I then added all the |\transformfont| stuff, and it went
back to:
\begin{quote}
  77079 words of memory out of 150001\\
  Time elapsed: 97.7 seconds
\end{quote}



\subsection{Current tests}

The setup for this test is that \TeX\ is run on a \texttt{.tex} file 
consisting of the following commands.
\begin{quote}
  |\batchmode|\\
  |\input fontinst.sty|\\
  |\latinfamily{pad}{}|\\
  |\tracingstats=1\bye|
\end{quote}
All the font metrics are generated from the AFM files; temporary MTX, 
PL, and VPL files are deleted between test runs. The format used was 
generated by typing |\dump| at ini\TeX's |**| prompt; thus there is no 
overhead from a typesetting format in the space requirements.

[It appears the exact data from these tests will have to wait, since 
I haven't been able to get access to any computer with reliable 
process timing. For the next release perhaps \textellipsis\ /LH]

% The \TeX\ version used is \TeX~3.14159. The \TeX\ implementation used 
% is te\TeX~0.9 (Web2C~7.2), running on a 
% 
% The \emph{input sources} figure lists how many items are used on 
% \TeX's stack for simultaneous input sources. As an input source in 
% this context is considered not only input files, but also (and mainly) 
% various token lists. Most of these token lists are replacement texts 
% and parameters of macros, but token list items on this stack also come 
% from expansions of |\the| (not only when applied to a |\toks| register) 
% and the like. The input source stack sizes of normal \TeX\ 
% implementations are usually several times larger than what 
% \package{fontinst} uses, so this particular resource shouldn't cause 
% any trouble.
% 
% The \emph{parameter} figure is the maximal number of macro parameters that 
% \TeX\ has to remember at any one time. The reason this number is 
% greater than 9 is that it counts parameters in \emph{all} macros that 
% are on the input sources stack, not just those in the top one. The 
% same remark about the likelyhood of \TeX\ running out of this resource 
% during a \package{fontinst} run as for input sources applies for 
% parameters.
% 
% The \emph{buffer characters} stack holds lines read from input files that 
% are partially tokenized (if several files are on the input sources 
% stack then \TeX\ must remember the last line read from each of them) and 
% characters for |\csname| \textellipsis |\endcsname| constructions that 
% are being expanded. This shouldn't cause any trouble either.
% 
% The \emph{save values} figure is the maximum number of items on \TeX's 
% save stack at any time. \package{fontinst} uses massive amounts of 
% space here (compared to normal \TeX\ documents), but there isn't much 
% that can be done about this since \package{fontinst} uses \TeX's 
% grouping mechanism to clear data for one font from memory before 
% processing begins with the next.
% 
% The \emph{multiletter control sequences} figure is exactly 
% that---the number of control sequences whose names consist of more than 
% one character. When these become too many, \TeX\ complains that its 
% hash table is full. Some of these control sequences are macros that 
% \package{fontinst} uses in a procedure-like manner, but many of them are 
% rather used as data tables. As a comparision of the figure I might 
% mension that my \LaTeX\ used 3748 multiletter control sequences for 
% typesetting this document, so \package{fontinst} rather average in 
% this respect (perhaps a bit above, but not much).
% 
% The \emph{strings} figure tells how many items \TeX\ put in its string 
% pool and the \emph{string characters} figure tells how many characters 
% these contain altogether. There are two main categories of things that 
% occur here: names of multiletter control sequences and \TeX's builtin 
% error messages. One thing which certainly doesn't occur here is the 
% texts you save using \package{fontinst}'s |\setstr| command; these will 
% instead become token lists and occupy main memory space (the \emph{names} 
% of string variables will however become part of a control sequence name, 
% so that will be stored as a string). Unlike some other \TeX\ 
% implementations however, the Web2C \TeX\ seems to only report new 
% entries in the string pool, so the \emph{strings} and \emph{string 
% characters} figures below do not include the builtin error messages. 
% On the other hand, they don't include the names of the 322 primitive 
% multiletter control sequences either, which is why the figures below 
% report more control sequences than strings.
% 
% The \emph{main memory}, finally, is where \TeX\ stores almost 
% everything else (I've skipped some of the memory categories \TeX\ 
% reports since they are ``only'' used for typesetting), most notably 
% tokens. Each token occupies one word of memory. I don't think 
% \package{fontinst}'s consumption of main memory is that high (in 
% comparision with normal \LaTeX\ jobs) since \package{fontinst} doesn't 
% have to store any boxes here and thus frees space for more tokens.
% 
% \begin{description}
%   \item[v\,1.801]
%     \consumption{126.68}{%954.9
% %  5261 strings out of 8681
% %  54607 string characters out of 136047
% %  112422 words of memory out of 200001
% %  3814 multiletter control sequences out of 10000
% %  8 words of font info for 0 fonts, out of 180000 for 256
% %  0 hyphenation exceptions out of 2551
% %  30i,0n,42p,220b,1696s stack positions out of 600i,150n,200p,3000b,4094s
%  3903 strings out of 13688
%  42612 string characters out of 101822
%  112422 words of memory out of 263001
%  3961 multiletter control sequences out of 10000+0
%  7 words of font info for 0 fonts, out of 200000 for 1000
%  0 hyphenation exceptions out of 1000
%  30i,0n,42p,220b,1770s stack positions out of 300i,100n,500p,30000b,4000s
%     }% Compulsory comment; TeX inserts a & at the end of this line
%     % as a side-effect of the implementation of \consumption.
%   \item[v\,1.902]
%     \consumption{139.59}{%997.4
% %  6196 strings out of 8681
% %  69530 string characters out of 136047
% %  112617 words of memory out of 200001
% %  4749 multiletter control sequences out of 10000
% %  8 words of font info for 0 fonts, out of 180000 for 256
% %  0 hyphenation exceptions out of 2551
% %  28i,0n,42p,220b,2004s stack positions out of 600i,150n,200p,3000b,4094s
%  4690 strings out of 13688
%  52734 string characters out of 101822
%  112613 words of memory out of 263001
%  4748 multiletter control sequences out of 10000+0
%  7 words of font info for 0 fonts, out of 200000 for 1000
%  0 hyphenation exceptions out of 1000
%  28i,0n,42p,220b,2000s stack positions out of 300i,100n,500p,30000b,4000s
%     }%
%     Comparing the figures for v\,1.902 with those of v\,1.801, there 
%     are mainly three things which are of interest. The first is that 
%     the number of items on the save stack have increased quite a lot. 
%     Most of this is due to the mechanism by which \package{fontinst} 
%     avoids writing multiple kerns to (V)PL files. The second thing to 
%     notice is that the number of control sequences has increased quite 
%     dramatically (over 20\%). This is to be expected, as a number of 
%     new features have been added and the implementation of these 
%     features requires many new macros.
%     
%     Some 200 of these new control sequences are however not there 
%     because of new features, but because of a silly implementation of 
%     how slot numbers for glyphs are stored. In an attempt to save 
%     tokens, I (LH) stored these numbers as control sequence names 
%     rather than token sequences, just like kern amounts have been 
%     stored for some time now. One notable feature of kern 
%     amounts is however that although these may assume just about any 
%     value you can think of, within any given font family they tend to 
%     assume only a handful of values. This means that the number of 
%     hash positions occupied by such control sequences is never very 
%     large and the storage is efficient. On the other hand, the set of 
%     slot numbers that occur usually consists of all integers in the 
%     range 0--255, with each slot number occuring in at most one 
%     position. This means that the storage method, although efficient 
%     in the number of tokens, really squanders space in the hash table.
%     A much better method (which should be implemented, once I get round 
%     to it) is to store slot numbers in the character codes of `ordinary' 
%     tokens.
%     
%     The third noticable thing is that although the number of macros 
%     has grown quite a lot, the amount of main memory used has hardly 
%     increased at all! Some of this is probably due to that the ENC to 
%     ETX converter was moved to \texttt{finstmsc.sty}, since this 
%     consists of only two macros but lots of tokens. Another factor 
%     that has probably helped is that |\glyph| now avoids rescaling a 
%     glyph by one thousand; this saves 9 tokens for each time 
%     |\glyph|\marg{name}|{1000}| gets executed.
%   \item[v\,1.907]
%     \consumption{138.88}{%1019.9
% %  6226 strings out of 8681
% %  69918 string characters out of 136047
% %  113820 words of memory out of 200001
% %  4779 multiletter control sequences out of 10000
% %  8 words of font info for 0 fonts, out of 180000 for 256
% %  0 hyphenation exceptions out of 2551
% %  28i,0n,42p,220b,2006s stack positions out of 600i,150n,200p,3000b,4094s
% %  6225 strings out of 8681
%  4719 strings out of 13688
%  53105 string characters out of 101822
%  113814 words of memory out of 263001
%  4777 multiletter control sequences out of 10000+0
%  7 words of font info for 0 fonts, out of 200000 for 1000
%  0 hyphenation exceptions out of 1000
%  28i,0n,42p,220b,2002s stack positions out of 300i,100n,500p,30000b,4000s
%     }%
%     This is pretty much what could be expected. A couple of new 
%     features have been added, so naturally some of the numbers have 
%     grown a little.
%   \item[v\,1.908]
%     This version is devoted to optimizing \package{fontinst}.
%     
%     The first idea was to avoid moving the contents of 
%     |\glyph_map_commands| and |\glyph_map_fonts| to a macro and back 
%     again each time these are updated. This changed the numbers to
%     \consumption{135.64}{%
%  4719 strings out of 13688
%  53105 string characters out of 101822
%  113810 words of memory out of 263001
%  4777 multiletter control sequences out of 10000+0
%  7 words of font info for 0 fonts, out of 200000 for 1000
%  0 hyphenation exceptions out of 1000
%  28i,0n,42p,220b,2002s stack positions out of 300i,100n,500p,30000b,4000s
%     }%
%     Hence I've earned a few seconds.
%     
%     The next idea is to expand the |\space|s in |\out_lline| and 
%     friends when these are defined, instead of expanding them anew 
%     each time an output line is written.
%   \item[v\,1.909]
%     \consumption{}{%1159.8 % Ow! It's getting worse.
% %  6155 strings out of 8681
% %  68824 string characters out of 136047
% %  113918 words of memory out of 200001
% %  4708 multiletter control sequences out of 10000
% %  8 words of font info for 0 fonts, out of 180000 for 256
% %  0 hyphenation exceptions out of 2551
% %  28i,0n,42p,220b,1982s stack positions out of 600i,150n,200p,3000b,4094s
%     }
%   \item[v\,1.910]
%     \consumption{}{%1031.6 % Perhaps not ...
% %  5949 strings out of 8681
% %  68261 string characters out of 136047
% %  113840 words of memory out of 200001
% %  4502 multiletter control sequences out of 10000
% %  8 words of font info for 0 fonts, out of 180000 for 256
% %  0 hyphenation exceptions out of 2551
% %  28i,0n,42p,220b,1756s stack positions out of 600i,150n,200p,3000b,4094s
%     }
% \end{description}
% 


\begin{thebibliography}{99}
\bibitem{Fontname}
  Karl Berry: \textit{Fontname}, CTAN:\discretionary{}{}{}%
  \texttt{info}\slash \texttt{fontname}\slash \texttt{fontname.texi} 
  (and most of the other files in that directory as well).
\bibitem{mfnt}
  Matthias Clasen and Ulrik Vieth: 
  \texttt{mfnt} (their ``work with math fonts''), 1997--8,
  see \textsc{http}:/\slash \texttt{www.tug.org}\slash 
  \texttt{twg}\slash \texttt{mfg}\slash\texttt{archives}/.
\bibitem{LaTeX-companion}
  Michel Goossens, Frank Mittelbach, Alexander Samarin:
  \textit{The \LaTeX\ Companion}, 
  Ad\-di\-son-Wes\-ley, Reading, MA, USA, 1994.
  % Addison and Wesley are names of two persons, but they 
  % should be joined by a hyphen since Addison-Wesley is
  % a company name. Tricky that.
\bibitem{LaTeX-graph-comp}
  Michel Goossens, Sebastian Rahtz, Frank Mittelbach:
  \textit{The \LaTeX\ Graphics Companion: Illustrating Documents with 
  \TeX\ and PostScript},
  Ad\-di\-son-Wes\-ley, Reading, MA, USA, 1997; 
  ISBN~0-201-85469-4.
\bibitem{TAOCP2}
  Donald E.\ Knuth: \textit{The art of computer programming},
  vol.~2 (\textit{Seminumerical algorithms}), 3rd ed., 
  Ad\-di\-son-Wes\-ley, 1997.
\bibitem{TeXbook}
  Donald E.\ Knuth, Duane Bibby (illustrations): 
  \textit{The \TeX book}, 
  Ad\-di\-son-Wes\-ley, 1991, ISBN~0-201-13448-9; 
  also volume A of \textit{Computers and typesetting},
  ISBN~0-201-13447-0.
\bibitem{fntguide}
  \LaTeX3 Project Team: \textit{\LaTeXe{} font selection}, 
  CTAN: \texttt{macros}\slash
  \texttt{latex}\slash\texttt{base}\slash\texttt{fntguide.tex}.
\end{thebibliography}


\end{document}