1. xemacs
  2. x-symbol

Source

x-symbol / man / x-symbol.texi

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
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
3891
3892
3893
3894
3895
3896
3897
3898
3899
3900
3901
3902
3903
3904
3905
3906
3907
3908
3909
3910
3911
3912
3913
3914
3915
3916
3917
3918
3919
3920
3921
3922
3923
3924
3925
3926
3927
3928
3929
3930
3931
3932
3933
3934
3935
3936
3937
3938
3939
3940
3941
3942
3943
3944
3945
3946
3947
3948
3949
3950
3951
3952
3953
3954
3955
3956
3957
3958
3959
3960
3961
3962
3963
3964
3965
3966
3967
3968
3969
3970
3971
3972
3973
3974
3975
3976
3977
3978
3979
3980
3981
3982
3983
3984
3985
3986
3987
3988
3989
3990
3991
3992
3993
3994
3995
3996
3997
3998
3999
4000
4001
4002
4003
4004
4005
4006
4007
4008
4009
4010
4011
4012
4013
4014
4015
4016
4017
4018
4019
4020
4021
4022
4023
4024
4025
4026
4027
4028
4029
4030
4031
4032
4033
4034
4035
4036
4037
4038
4039
4040
4041
4042
4043
4044
4045
4046
4047
4048
4049
4050
4051
4052
4053
4054
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069
4070
4071
4072
4073
4074
4075
4076
4077
4078
4079
4080
4081
4082
4083
4084
4085
4086
4087
4088
4089
4090
4091
4092
4093
4094
4095
4096
4097
4098
4099
4100
4101
4102
4103
4104
4105
4106
4107
4108
4109
4110
4111
4112
4113
4114
4115
4116
4117
4118
4119
4120
4121
4122
4123
4124
4125
4126
4127
4128
4129
4130
4131
4132
4133
4134
4135
4136
4137
4138
4139
4140
4141
4142
4143
4144
4145
4146
4147
4148
4149
4150
4151
4152
4153
4154
4155
4156
4157
4158
4159
4160
4161
4162
4163
4164
4165
4166
4167
4168
4169
4170
4171
4172
4173
4174
4175
4176
4177
4178
4179
4180
4181
4182
4183
4184
4185
4186
4187
4188
4189
4190
4191
4192
4193
4194
4195
4196
4197
4198
4199
4200
4201
4202
4203
4204
4205
4206
4207
4208
4209
4210
4211
4212
4213
4214
4215
4216
4217
4218
4219
4220
4221
4222
4223
4224
4225
4226
4227
4228
4229
4230
4231
4232
4233
4234
4235
4236
4237
4238
4239
4240
4241
4242
4243
4244
4245
4246
4247
4248
4249
4250
4251
4252
4253
4254
4255
4256
4257
4258
4259
4260
4261
4262
4263
4264
4265
4266
4267
4268
4269
4270
4271
4272
4273
4274
4275
4276
4277
4278
4279
4280
4281
4282
4283
4284
4285
4286
4287
4288
4289
4290
4291
4292
4293
4294
4295
4296
4297
4298
4299
4300
4301
4302
4303
4304
4305
4306
4307
4308
4309
4310
4311
4312
4313
4314
4315
4316
4317
4318
4319
4320
4321
4322
4323
4324
4325
4326
4327
4328
4329
4330
4331
4332
4333
4334
4335
4336
4337
4338
4339
4340
4341
4342
4343
4344
4345
4346
4347
4348
4349
4350
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361
4362
4363
4364
4365
4366
4367
4368
4369
4370
4371
4372
4373
4374
4375
4376
4377
4378
4379
4380
4381
4382
4383
4384
4385
4386
4387
4388
4389
4390
4391
4392
4393
4394
4395
4396
4397
4398
4399
4400
4401
4402
4403
4404
4405
4406
4407
4408
4409
4410
4411
4412
4413
4414
4415
4416
4417
4418
4419
4420
4421
4422
4423
4424
4425
4426
4427
4428
4429
4430
4431
4432
4433
4434
4435
4436
4437
4438
4439
4440
4441
4442
4443
4444
4445
4446
4447
4448
4449
4450
4451
4452
4453
4454
4455
4456
4457
4458
4459
4460
4461
4462
4463
4464
4465
4466
4467
4468
4469
4470
4471
4472
4473
4474
4475
4476
4477
4478
4479
4480
4481
4482
4483
4484
4485
4486
4487
4488
4489
4490
4491
4492
4493
4494
4495
4496
4497
4498
4499
4500
4501
4502
4503
4504
4505
4506
4507
4508
4509
4510
4511
4512
4513
4514
4515
4516
4517
4518
4519
4520
4521
4522
4523
4524
4525
4526
4527
4528
4529
4530
4531
4532
4533
4534
4535
4536
4537
4538
4539
4540
4541
4542
4543
4544
4545
4546
4547
4548
4549
4550
4551
4552
4553
4554
4555
4556
4557
4558
4559
4560
4561
4562
4563
4564
4565
4566
4567
4568
4569
4570
4571
4572
4573
4574
4575
4576
4577
4578
4579
4580
4581
4582
4583
4584
4585
4586
4587
4588
4589
4590
4591
4592
4593
4594
4595
4596
4597
4598
4599
4600
4601
4602
4603
4604
4605
4606
4607
4608
4609
4610
4611
4612
4613
4614
4615
4616
4617
4618
4619
4620
4621
4622
4623
4624
4625
4626
4627
4628
4629
4630
4631
4632
4633
4634
4635
4636
4637
4638
4639
4640
4641
4642
4643
4644
4645
4646
4647
4648
4649
4650
4651
4652
4653
4654
4655
4656
4657
4658
4659
4660
4661
4662
4663
4664
4665
4666
4667
4668
4669
4670
4671
4672
4673
4674
4675
4676
4677
4678
4679
4680
4681
4682
4683
4684
4685
4686
4687
4688
4689
4690
4691
4692
4693
4694
4695
4696
4697
4698
4699
4700
4701
4702
4703
4704
4705
4706
4707
4708
4709
4710
4711
4712
4713
4714
4715
4716
4717
4718
4719
4720
4721
4722
4723
4724
4725
4726
4727
4728
4729
4730
4731
4732
4733
4734
4735
4736
4737
4738
4739
4740
4741
4742
4743
4744
4745
4746
4747
4748
4749
4750
4751
4752
4753
4754
4755
4756
4757
4758
4759
4760
4761
4762
4763
4764
4765
4766
4767
4768
4769
4770
4771
4772
4773
4774
4775
4776
4777
4778
4779
4780
4781
4782
4783
4784
4785
4786
4787
4788
4789
4790
4791
4792
4793
4794
4795
4796
4797
4798
4799
4800
4801
4802
4803
4804
4805
4806
4807
4808
4809
4810
4811
4812
4813
4814
4815
4816
4817
4818
4819
4820
4821
4822
4823
4824
4825
4826
4827
4828
4829
4830
4831
4832
4833
4834
4835
4836
4837
4838
4839
4840
4841
4842
4843
4844
4845
4846
4847
4848
4849
4850
4851
4852
4853
4854
4855
4856
4857
4858
4859
4860
4861
4862
4863
4864
4865
4866
4867
4868
4869
4870
4871
4872
4873
4874
4875
4876
4877
4878
4879
4880
4881
4882
4883
4884
4885
4886
4887
4888
4889
4890
4891
4892
4893
4894
4895
4896
4897
4898
4899
4900
4901
4902
4903
4904
4905
4906
4907
4908
4909
4910
4911
4912
4913
4914
4915
4916
4917
4918
4919
4920
4921
4922
4923
4924
4925
4926
4927
4928
4929
4930
4931
4932
4933
4934
4935
4936
4937
4938
4939
4940
4941
4942
4943
4944
4945
4946
4947
4948
4949
4950
4951
4952
4953
4954
4955
4956
4957
4958
4959
4960
4961
4962
4963
4964
4965
4966
4967
4968
4969
4970
4971
4972
4973
4974
4975
4976
4977
4978
4979
4980
4981
4982
4983
4984
4985
4986
4987
4988
4989
4990
4991
4992
4993
4994
4995
4996
4997
4998
4999
5000
5001
5002
5003
5004
5005
5006
5007
5008
5009
5010
5011
5012
5013
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025
5026
5027
5028
5029
5030
5031
5032
5033
5034
5035
5036
5037
5038
5039
5040
5041
5042
5043
5044
5045
5046
5047
5048
5049
5050
5051
5052
5053
5054
5055
5056
5057
5058
5059
5060
5061
5062
5063
5064
5065
5066
5067
5068
5069
5070
5071
5072
5073
5074
5075
5076
5077
5078
5079
5080
5081
5082
5083
5084
5085
5086
5087
5088
5089
5090
5091
5092
5093
5094
5095
5096
5097
5098
5099
5100
5101
5102
5103
5104
5105
5106
5107
5108
5109
5110
5111
5112
5113
5114
5115
5116
5117
5118
5119
5120
5121
5122
5123
5124
5125
5126
5127
5128
5129
5130
5131
5132
5133
5134
5135
5136
5137
5138
5139
5140
5141
5142
5143
5144
5145
5146
5147
5148
5149
5150
5151
5152
5153
5154
5155
5156
5157
5158
5159
5160
5161
5162
5163
5164
5165
5166
5167
5168
5169
5170
5171
5172
5173
5174
5175
5176
5177
5178
5179
5180
5181
5182
5183
5184
5185
5186
5187
5188
5189
5190
5191
5192
5193
5194
5195
5196
5197
5198
5199
5200
5201
5202
5203
5204
5205
5206
5207
5208
5209
5210
5211
5212
5213
5214
5215
5216
5217
5218
5219
5220
5221
5222
5223
5224
5225
5226
5227
5228
5229
5230
5231
5232
5233
5234
5235
5236
5237
5238
5239
5240
5241
5242
5243
5244
5245
5246
5247
5248
5249
5250
5251
5252
5253
5254
5255
5256
5257
5258
5259
5260
5261
5262
5263
5264
5265
5266
5267
5268
5269
5270
5271
5272
5273
5274
5275
5276
5277
5278
5279
5280
5281
5282
5283
5284
5285
5286
5287
5288
5289
5290
5291
5292
5293
5294
5295
5296
5297
5298
5299
5300
5301
5302
5303
5304
5305
5306
5307
5308
5309
5310
5311
5312
5313
5314
5315
5316
5317
5318
5319
5320
5321
5322
5323
5324
5325
5326
5327
5328
5329
5330
5331
5332
5333
5334
5335
5336
5337
5338
5339
5340
5341
5342
5343
5344
5345
5346
5347
5348
5349
5350
5351
5352
5353
5354
5355
5356
5357
5358
5359
5360
5361
5362
5363
5364
5365
5366
5367
5368
5369
5370
5371
5372
5373
5374
5375
5376
5377
5378
5379
5380
5381
5382
5383
5384
5385
5386
5387
5388
5389
5390
5391
5392
5393
5394
5395
5396
5397
5398
5399
5400
5401
5402
5403
5404
5405
5406
5407
5408
5409
5410
5411
5412
5413
5414
5415
5416
5417
5418
5419
5420
5421
5422
5423
5424
5425
5426
5427
5428
5429
5430
5431
5432
5433
5434
5435
5436
5437
5438
5439
5440
5441
5442
5443
5444
5445
5446
5447
5448
5449
5450
5451
5452
5453
5454
5455
5456
5457
5458
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468
5469
5470
5471
5472
5473
5474
5475
5476
5477
5478
5479
5480
5481
5482
5483
5484
5485
5486
5487
5488
5489
5490
5491
5492
5493
5494
5495
5496
5497
5498
5499
5500
5501
5502
5503
5504
5505
5506
5507
5508
5509
5510
5511
5512
5513
5514
5515
5516
5517
5518
5519
5520
5521
5522
5523
5524
5525
5526
5527
5528
5529
5530
5531
5532
5533
5534
5535
5536
5537
5538
5539
5540
5541
5542
5543
5544
5545
5546
5547
5548
5549
5550
5551
5552
5553
5554
5555
5556
5557
5558
5559
5560
5561
5562
5563
5564
5565
5566
5567
5568
5569
5570
5571
5572
5573
5574
5575
5576
5577
5578
5579
5580
5581
5582
5583
5584
5585
5586
5587
5588
5589
5590
5591
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603
5604
5605
5606
5607
5608
5609
5610
5611
5612
5613
5614
5615
5616
5617
5618
5619
5620
5621
5622
5623
5624
5625
5626
5627
5628
5629
5630
5631
5632
5633
5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
5660
5661
5662
5663
5664
5665
5666
5667
5668
5669
5670
5671
5672
5673
5674
5675
5676
5677
5678
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700
5701
5702
5703
5704
5705
5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
5742
5743
5744
5745
5746
5747
5748
5749
5750
5751
5752
5753
5754
5755
5756
5757
5758
5759
5760
5761
5762
5763
5764
5765
5766
5767
5768
5769
5770
5771
5772
5773
5774
5775
5776
5777
5778
5779
5780
5781
5782
5783
5784
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795
5796
5797
5798
5799
5800
5801
5802
5803
5804
5805
5806
5807
5808
5809
5810
5811
5812
5813
5814
5815
5816
5817
5818
5819
5820
5821
5822
5823
5824
5825
5826
5827
5828
5829
5830
5831
5832
5833
5834
5835
5836
5837
5838
5839
5840
5841
5842
5843
5844
5845
5846
5847
5848
5849
5850
5851
5852
5853
5854
5855
5856
5857
5858
5859
5860
5861
5862
5863
5864
5865
5866
5867
5868
5869
5870
5871
5872
5873
5874
5875
5876
5877
5878
5879
5880
5881
5882
5883
5884
5885
5886
5887
5888
5889
5890
5891
5892
5893
5894
5895
5896
5897
5898
5899
5900
5901
5902
5903
5904
5905
5906
5907
5908
5909
5910
5911
5912
5913
5914
5915
5916
5917
5918
5919
5920
5921
5922
5923
5924
5925
5926
5927
5928
5929
5930
5931
5932
5933
5934
5935
5936
5937
5938
5939
5940
5941
5942
5943
5944
5945
5946
5947
5948
5949
5950
5951
5952
5953
5954
5955
5956
5957
5958
5959
5960
5961
5962
5963
5964
5965
5966
5967
5968
5969
5970
5971
5972
5973
5974
5975
5976
5977
5978
5979
5980
5981
5982
5983
5984
5985
5986
5987
5988
5989
5990
5991
5992
5993
5994
5995
5996
5997
5998
5999
6000
6001
6002
6003
6004
6005
6006
6007
6008
6009
6010
6011
6012
6013
6014
6015
6016
6017
6018
6019
6020
6021
6022
6023
6024
6025
6026
6027
6028
6029
6030
6031
6032
6033
6034
6035
6036
6037
6038
6039
6040
6041
6042
6043
6044
6045
6046
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056
6057
6058
6059
6060
6061
6062
6063
6064
6065
6066
6067
6068
6069
6070
6071
6072
6073
6074
6075
6076
6077
6078
6079
6080
6081
6082
6083
6084
6085
6086
6087
6088
6089
6090
6091
6092
6093
6094
6095
6096
6097
6098
6099
6100
6101
6102
6103
6104
6105
6106
6107
6108
6109
6110
6111
6112
6113
6114
6115
6116
6117
6118
6119
6120
6121
6122
6123
6124
6125
6126
6127
6128
6129
6130
6131
6132
6133
6134
6135
6136
6137
6138
6139
6140
6141
6142
6143
6144
6145
6146
6147
6148
6149
6150
6151
6152
6153
6154
6155
6156
6157
6158
6159
6160
6161
6162
6163
6164
6165
6166
6167
6168
6169
6170
6171
6172
6173
6174
6175
6176
6177
6178
6179
6180
6181
6182
6183
6184
6185
6186
6187
6188
6189
6190
6191
6192
6193
6194
6195
6196
6197
6198
6199
6200
6201
6202
6203
6204
6205
6206
6207
6208
6209
6210
6211
6212
6213
6214
6215
6216
6217
6218
6219
6220
6221
6222
6223
6224
6225
6226
6227
6228
6229
6230
6231
6232
6233
6234
6235
6236
6237
6238
6239
6240
6241
6242
6243
6244
6245
6246
6247
6248
6249
6250
6251
6252
6253
6254
6255
6256
6257
6258
6259
6260
6261
6262
6263
6264
6265
6266
6267
6268
6269
6270
6271
6272
6273
6274
6275
6276
6277
6278
6279
6280
6281
6282
6283
6284
6285
6286
6287
6288
6289
6290
6291
6292
6293
6294
6295
6296
6297
6298
6299
6300
6301
6302
6303
6304
6305
6306
6307
6308
6309
6310
6311
6312
6313
6314
6315
6316
6317
6318
6319
6320
6321
6322
6323
6324
6325
6326
6327
6328
6329
6330
6331
6332
6333
6334
6335
6336
6337
6338
6339
6340
6341
6342
6343
6344
6345
6346
6347
6348
6349
6350
6351
6352
6353
6354
6355
6356
6357
6358
6359
6360
6361
6362
6363
6364
6365
6366
6367
6368
6369
6370
6371
6372
6373
6374
6375
6376
6377
6378
6379
6380
6381
6382
6383
6384
6385
6386
6387
6388
6389
6390
6391
6392
6393
6394
6395
6396
6397
6398
6399
6400
6401
6402
6403
6404
6405
6406
6407
6408
6409
6410
6411
6412
6413
6414
6415
6416
6417
6418
6419
6420
6421
6422
6423
6424
6425
6426
6427
6428
6429
6430
6431
6432
6433
6434
6435
6436
6437
6438
6439
6440
6441
6442
6443
6444
6445
6446
6447
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457
6458
6459
6460
6461
6462
6463
6464
6465
6466
6467
6468
6469
6470
6471
6472
6473
6474
6475
6476
6477
6478
6479
6480
6481
6482
6483
6484
6485
6486
6487
6488
6489
6490
6491
6492
6493
6494
6495
6496
6497
6498
6499
6500
6501
6502
6503
6504
6505
6506
6507
6508
6509
6510
6511
6512
6513
6514
6515
6516
6517
6518
6519
6520
6521
6522
6523
6524
6525
6526
6527
6528
6529
6530
6531
6532
6533
6534
6535
6536
6537
6538
6539
6540
6541
6542
6543
6544
6545
6546
6547
6548
6549
6550
6551
6552
6553
6554
6555
6556
6557
6558
6559
6560
6561
6562
6563
6564
6565
6566
6567
6568
6569
6570
6571
6572
6573
6574
6575
6576
6577
6578
6579
6580
6581
6582
6583
6584
6585
6586
6587
6588
6589
6590
6591
6592
6593
6594
6595
6596
6597
6598
6599
6600
6601
6602
6603
6604
6605
6606
6607
6608
6609
6610
6611
6612
6613
6614
6615
6616
6617
6618
6619
6620
6621
6622
6623
6624
6625
6626
6627
6628
6629
6630
6631
6632
6633
6634
6635
6636
6637
6638
6639
6640
6641
6642
6643
6644
6645
6646
6647
6648
6649
6650
6651
6652
6653
6654
6655
6656
6657
6658
6659
6660
6661
6662
6663
6664
6665
6666
6667
6668
6669
6670
6671
6672
6673
6674
6675
6676
6677
6678
6679
6680
6681
6682
6683
6684
6685
6686
6687
6688
6689
6690
6691
6692
6693
6694
6695
6696
6697
6698
6699
6700
6701
6702
6703
6704
6705
6706
6707
6708
6709
6710
6711
6712
6713
6714
6715
6716
6717
6718
6719
6720
6721
6722
6723
6724
6725
6726
6727
6728
6729
6730
6731
6732
6733
6734
6735
6736
6737
6738
6739
6740
6741
6742
6743
6744
6745
6746
6747
6748
6749
6750
6751
6752
6753
6754
6755
6756
6757
6758
6759
6760
6761
6762
6763
6764
6765
6766
6767
6768
6769
6770
6771
6772
6773
6774
6775
6776
6777
6778
6779
6780
6781
6782
6783
6784
6785
6786
6787
6788
6789
6790
6791
6792
6793
6794
6795
6796
6797
6798
6799
6800
6801
6802
6803
6804
6805
6806
6807
6808
6809
6810
6811
6812
6813
6814
6815
6816
6817
6818
6819
6820
6821
6822
6823
6824
6825
6826
6827
6828
6829
6830
6831
6832
6833
6834
6835
6836
6837
6838
6839
6840
6841
6842
6843
6844
6845
6846
6847
6848
6849
6850
6851
6852
6853
6854
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866
6867
6868
6869
6870
6871
6872
6873
6874
6875
6876
6877
6878
6879
6880
6881
6882
6883
6884
6885
6886
6887
6888
6889
6890
6891
6892
6893
6894
6895
6896
6897
6898
6899
6900
6901
6902
6903
6904
6905
6906
6907
6908
6909
6910
6911
6912
6913
6914
6915
6916
6917
6918
6919
6920
6921
6922
6923
6924
6925
6926
6927
6928
6929
6930
6931
6932
6933
6934
6935
6936
6937
6938
6939
6940
6941
6942
6943
6944
6945
6946
6947
6948
6949
6950
6951
6952
6953
6954
6955
6956
6957
6958
6959
6960
6961
6962
6963
6964
6965
6966
6967
6968
6969
6970
6971
6972
6973
6974
6975
6976
6977
6978
6979
6980
6981
6982
6983
6984
6985
6986
6987
6988
6989
6990
6991
6992
6993
6994
6995
6996
6997
6998
6999
7000
7001
7002
7003
7004
7005
7006
7007
7008
7009
7010
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021
7022
7023
7024
7025
7026
7027
7028
7029
7030
7031
7032
7033
7034
7035
7036
7037
7038
7039
7040
7041
7042
7043
7044
7045
7046
7047
7048
7049
7050
7051
7052
7053
7054
7055
7056
7057
7058
7059
7060
7061
7062
7063
7064
7065
7066
7067
7068
7069
7070
7071
7072
7073
7074
7075
7076
7077
7078
7079
7080
7081
7082
7083
7084
7085
7086
7087
7088
7089
7090
7091
7092
7093
7094
7095
7096
7097
7098
7099
7100
7101
7102
7103
7104
7105
7106
7107
7108
7109
7110
7111
7112
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124
7125
7126
7127
7128
7129
7130
7131
7132
7133
7134
7135
7136
7137
7138
7139
7140
7141
7142
7143
7144
7145
7146
7147
7148
7149
7150
7151
7152
7153
7154
7155
7156
7157
7158
7159
7160
7161
7162
7163
7164
7165
7166
7167
7168
7169
7170
7171
7172
7173
7174
7175
7176
7177
7178
7179
7180
7181
7182
7183
7184
7185
7186
7187
7188
7189
7190
7191
7192
7193
7194
7195
7196
7197
7198
7199
7200
7201
7202
7203
7204
7205
7206
7207
7208
7209
7210
7211
7212
7213
7214
7215
7216
7217
7218
7219
7220
7221
7222
7223
7224
7225
7226
7227
7228
7229
7230
7231
7232
7233
7234
7235
7236
7237
7238
7239
7240
7241
7242
7243
7244
7245
7246
7247
7248
7249
7250
7251
7252
7253
7254
7255
7256
7257
7258
7259
7260
7261
7262
7263
7264
7265
7266
7267
7268
7269
7270
7271
7272
7273
7274
7275
7276
7277
7278
7279
7280
7281
7282
7283
7284
7285
7286
7287
7288
7289
7290
7291
7292
7293
7294
7295
7296
7297
7298
7299
7300
7301
7302
7303
7304
7305
7306
7307
7308
7309
7310
7311
7312
7313
7314
7315
7316
7317
7318
7319
7320
7321
7322
7323
7324
7325
7326
7327
7328
7329
7330
7331
7332
7333
7334
7335
7336
7337
7338
7339
7340
7341
7342
7343
7344
7345
7346
7347
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357
7358
7359
7360
7361
7362
7363
7364
7365
7366
7367
7368
7369
7370
7371
7372
7373
7374
7375
7376
7377
7378
7379
7380
7381
7382
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395
7396
7397
7398
7399
7400
7401
7402
7403
7404
7405
7406
7407
7408
7409
7410
7411
7412
7413
7414
7415
7416
7417
7418
7419
7420
7421
7422
7423
7424
7425
7426
7427
7428
7429
7430
7431
7432
7433
7434
7435
7436
7437
7438
7439
7440
7441
7442
7443
7444
7445
7446
7447
7448
7449
7450
7451
7452
7453
7454
7455
7456
7457
7458
7459
7460
7461
7462
7463
7464
7465
7466
7467
7468
7469
7470
7471
7472
7473
7474
7475
7476
7477
7478
7479
7480
7481
7482
7483
7484
7485
7486
7487
7488
7489
7490
7491
7492
7493
7494
7495
7496
7497
7498
7499
7500
7501
7502
7503
7504
7505
7506
7507
7508
7509
7510
7511
7512
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523
7524
7525
7526
7527
7528
7529
7530
7531
7532
7533
7534
7535
7536
7537
7538
7539
7540
7541
7542
7543
7544
7545
7546
7547
7548
7549
7550
7551
7552
7553
7554
7555
7556
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569
7570
7571
7572
7573
7574
7575
7576
7577
7578
7579
7580
7581
7582
7583
7584
7585
7586
7587
7588
7589
7590
7591
7592
7593
7594
7595
7596
7597
7598
7599
7600
7601
7602
7603
7604
7605
7606
7607
7608
7609
7610
7611
7612
7613
7614
7615
7616
7617
7618
7619
7620
7621
7622
7623
7624
7625
7626
7627
7628
7629
7630
7631
7632
7633
7634
7635
7636
7637
7638
7639
7640
\input texinfo
@c Copyright (C) 1998-2003 Free Software Foundation, Inc.
@c
@c Author: Christoph Wedler <wedler@users.sourceforge.net>
@c Maintainer: (Please use `M-x x-symbol-package-bug' to contact the maintainer)
@c Keywords: WYSIWYG, LaTeX, HTML, wp, math, internationalization
@c X-URL: http://x-symbol.sourceforge.net/

@c %**start of header
@setfilename x-symbol.info
@settitle X-Symbol Manual
@setchapternewpage odd

@set edition 4.5.2
@set version 4.5.1
@set update December 2003
@set url http://x-symbol.sourceforge.net
@set maintainer wedler@@users.sourceforge.net
@set listdevel x-symbol-devel@@lists.sourceforge.net

@set imagemagickurl http://www.imagemagick.org/
@set proofgeneralurl http://proofgeneral.inf.ed.ac.uk
@set sgmlentitiesurl http://www.w3.org/TR/REC-html40/sgml/entities.html

@c for cross references to other manuals
@ifset GNU
@set subedition Emacs
@set emacs emacs
@set emacsman GNU Emacs Manual
@end ifset

@ifclear GNU
@set subedition XEmacs
@set emacs xemacs
@set emacsman XEmacs User's Manual
@end ifclear

@set auctex auctex
@set auctexman AUC@TeX{}

@set reftex reftex
@set reftexman Ref@TeX{} User Manual

@set kpathsea kpathsea
@set kpathseaman Kpathsea Manual

@syncodeindex fn vr
@c %**end of header
@dircategory Editors
@direntry
* X-Symbol::      Semi WYSIWYG for LaTeX, HTML and other "token languages"
@end direntry

@ifinfo
This file documents X-Symbol, a package providing semi-@sc{wysiwyg} for
La@TeX{}, HTML and other ``token languages''.  It uses additional fonts
and provide input methods to insert their characters into your document.

This is Edition @value{edition} (@value{subedition}) of the X-Symbol
Manual for X-Symbol @value{version}, @value{update}.

Copyright (c) 1998-2003 Free Software Foundation, Inc.

@c default
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``Copying'' and ``GNU General Public License'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@c end default
@end ifinfo

@finalout
@titlepage
@title X-Symbol Manual
@subtitle Semi-@sc{wysiwyg} for La@TeX{}, HTML and other ``token languages''
@subtitle Edition @value{edition} (@value{subedition}), for X-Symbol @value{version}, @value{update}
@author by Christoph Wedler

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2003 Free Software Foundation, Inc.

@c default (slight change)
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
     
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derive work is distributed under the terms of a
permission notice identical to this one.
     
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@c end default

@end titlepage

@c ===========================================================================

@ifinfo
@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top X-Symbol

When you edit La@TeX{}, HTML, BibTeX or @TeX{}info sources in Emacs,
package X-Symbol provides some kind of @sc{wysiwyg} by using real
characters for tokens like @code{\oplus} or @code{&trade;}.  It also
provides various input methods to insert these characters.  Thumbnails
for included images and real super-/subscripts and are also supported.

The first part of this master menu lists the major nodes in this Info
document, including the indexes.  The rest of the menu lists all the
lower level nodes in the document.

This is Edition @value{edition} (@value{subedition}) of the X-Symbol
Manual for X-Symbol @value{version}, @value{update}.  For recent
changes, see @ref{News}.

Bug fixes, bug reports, improvements, and suggestions are strongly
appreciated.  If you want to contact the maintainer of package X-Symbol,
please read @ref{Bug Reports}.
@end ifinfo

@menu
* Introduction::                Introduction to X-Symbol.
* Installation::                What to do before using package X-Symbol.
* Concepts::                    Token language, conversion, coding, etc.
* Input Methods::               How to insert X-Symbol characters.
* Features::                    Super-/subscripts, images, info, etc.
* Supported Languages::         Details of the predefined token languages.
* X-Symbol Internals::          How package X-Symbol works.
* Problems::                    Annoyances, contacting the maintainer.
* History::                     Changes, wishlist, projects.
* Indexes::                     Menus covering various topics.

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Copying::                     X-Symbol is GPL'd.
* Summary::                     A brief summary of package X-Symbol.
* About::                       About this manual.

Installation

* Requirements::                Which programs you need for X-Symbol.
* Installing Files::            Basics 1: Put the files into your home dir.
* System-wide Installation::    Alternative:  Put the files into the XEmacs dir.
* Installing Lisp::             Basics 2: Initialize X-Symbol during startup.
* Installing Image Converter::  Recommended: How to install @code{convert}.
* Package Integration::         How X-Symbol interacts with other packages.
* Installing Fonts::            Optional: What to do when using other fonts.
* Installing Fonts Exceed::     If appropriate: What to do when using Exceed.
* Installing Fonts Lisp::       If appropriate: Lisp coding for other fonts.
* Installing Manual::           Optional: How to create the manual.
* Checking Installation::       Is package X-Symbol completely installed?

Package Integration

* LaTeX Packages::              Packages used in La@TeX{} buffers.
* Syntax Hiliting Packages::    Package @code{font-lock} and support modes.
* File IO Packages::            Compression, encryption, remote files, etc.
* Miscellaneous Packages::      Other packages.

Concepts of Package X-Symbol

* Token Language::              What does a X-Symbol character represent.
* Conversion::                  Decoding tokens, encoding characters.
* Minor Mode::                  How to control the behavior of X-Symbol.
* Poor Mans Mule::              Running X-Symbol under XEmacs/no-Mule.
* Role of font-lock::           Why does X-Symbol need @code{font-lock}.
* Char Group::                  Character group and token classes.

Conversion: Decoding and Encoding

* Default Coding::              Normal File and Default Encoding.
* File Coding::                 Specific encoding of a file.
* Controlling 8bit Coding::     Do you want to store 8bit characters?
* Unique Decoding::             Restrict decoding to avoid normalization?
* Conversion Commands::         Interactive encoding and decoding.
* Copy with Conversion::        Copy & paste with conversion.
* Char Aliases::                Different charsets include the same chars.

X-Symbol's Input Methods

* Introducing Input Methods::   Common behavior of all input methods.
* Input Method Token::          Replace token by character.
* Input Method Read Token::     Minibuffer input with completion.
* Input Method Menu::           Select a menu item.
* Input Method Grid::           Choose highlighted character.
* Input Method Keyboard::       Compose a key sequence.
* Input Method Context::        Replace character sequence.
* Input Method Electric::       Automatically replace character sequence.
* Input Method Quail::          A Mule input method "x-symbol".
* Customizing Input Method::    How to customize the input methods.

Features of Package X-Symbol

* Super and Subscripts::        Use special fonts for super-/subscripts.
* Images::                      Images after image insertion commands.
* Info::                        Display information in echo area.
* Ascii Representation::        Derive label from a buffer contents.
* Package Information::         Invoke info system, use WWW browser.

Images at the end of Image Insertion Commands

* Image Display::               When to display images.
* Image Conversion::            Producing a scaled-down image.
* Image Caching::               Speeding up the image processing.
* Special Images::              Signaling specific situations.
* Image Editor::                Editing the original image file.

Supported Token Languages

* Pseudo Language::             Token language ``x-symbol charsym''.
* TeX Macro::                   Token language @code{tex}.
* SGML Entity::                 Token language @code{sgml}.
* BibTeX Macro::                Token language @code{bib}.
* TeXinfo Command::             Token language @code{texi}.
* External Languages::          Languages defined in other Emacs Packages.

Token Language ``@TeX{} macro'' (@code{tex})

* TeX Macro Basics::            Basics of language ``@TeX{} macro''.
* TeX Macro Features::          Super-/subscripts and images in La@TeX{}.
* TeX Macro Problems::          Problems with @TeX{} macros.
* TeX Macro Conversion::        How the conversion of @TeX{} macros works.
* TeX Macro Symbols::           Extra Symbols of Language ``@TeX{} Macro''.

Token Language ``@sc{sgml} entity'' (@code{sgml})

* SGML Entity Basics::          Basics of Language ``@sc{sgml} entity''.
* SGML Entity Features::        Super-/Subscripts and Images in @sc{html}.
* SGML Entity Conversion::      How the conversion of @sc{sgml} entities works.

X-Symbol Internals

* Char Representation::         How X-Symbol represents X-Symbol chars.
* Defining Charsets::           How X-Symbol defines additional chars.
* Defining Input Methods::      How X-Symbol defines the input methods.
* Extending X-Symbol::          How to add fonts and token languages.
* Various Internals::           How X-Symbol handles other aspects.
* Design Alternatives::         Why X-Symbol is not designed differently.
* Language Internals::          How X-Symbol handles languages.
* Misc Internals::              Various.  TODO.

Defining Input Methods

* Input Method Objectives::     Input methods should be intuitive/consistent.
* Intro Char Descriptions::     An example introducing char descriptions.
* Char Descriptions::           The aspects and the contexts of a character.
* Example Char Descriptions::   A complete example defining input methods.
* Customizing Input Methods::   How to customize the input methods.

Extending Package X-Symbol

* Extending with Fonts::        How to add fonts to X-Symbol.
* Input Definitions::           Guidelines for input definitions.
* Font Definition File::        How to define new character in a file.
* Language Extension File::     Extending an existing language.
* Language Definition File::    Defining a new language.

Various Internals

* Tagging Insert Commands::     Don't break input methods Token and Electric.
* Avoiding Flickering::         Moving cursor in invisible commands.

Design Alternatives

* Alt Token Representations::   Why we need the conversion.
* Alt Global Mode::             How to turn on X-Symbol globally.
* Alt Auto Conversion::         When do we convert automatically.

Problems, Troubleshooting

* Nomule Problems::             X-Symbol provides a @emph{poor} man's Mule.
* Spurious Encodings::          Some commands turn off X-Symbol mode.
* No Encoding::                 The encoding does not work in a rare case.
* FAQ::                         Frequently asked questions.
* Bug Reports::                 How to contact the maintainer of X-Symbol.

Frequently Asked Questions

* FAQ XEmacs Core::             XEmacs crashes when using input method Token
* FAQ font-lock::               X-Symbol's fontification does not work.
* FAQ Strange Chars::           The buffer contains strange characters
* FAQ No Subscripts::           I cannot see any/some super-/subscripts.
* FAQ Stupid Subscripts::       I see subscripts where I don't want them.
* FAQ Font Size::               The characters are too small or too big.
* FAQ Conversion::              The conversion changes some tokens.
* FAQ Additional Spaces::       A space is added during the encoding.
* FAQ 8bit Chars::              I do not want 8bit characters in the file.
* FAQ Hyphen::                  I cannot distinguish @code{hyphen} from @samp{-}.
* FAQ Spell Check::             I have problems with spell-checking.
* FAQ News and Mail::           I want to use X-Symbol in Gnus or @sc{vm}.

History and Projects

* News::                        Changes in recent versions.
* Wishlist::                    Projects for X-Symbol.
* Open Questions::              How you can contribute.
* Acknowledgments::             People having contributed.

News: Changes in Recent Versions of X-Symbol

* Changes New::                 To be announced.
* Changes 4.5::                 Released Mar 2003 as beta.
* Changes 4.4::                 Released June 2002 as beta.
* Changes 4.1::                 Released Mar 2002 as beta.
* Changes 3.4::                 Released Mar 2002.
* Changes 3.3::                 Released Jan 1999.
* Changes 3.2::                 Released Dec 1998.
* Changes 3.1::                 Released Oct 1998.
* Changes 3.0::                 Released Sep 1998 as beta.
* Changes Old::                 Overview of old releases.

Wishlist: Projects for X-Symbol

* Wishlist Languages::          Additional token languages.
* Wishlist Fonts::              Automatically generated fonts.
* Wishlist Emacs::              Changes in Emacs/XEmacs.
* Wishlist LaTeX::              Changes in La@TeX{}.
* Wishlist Various::            Other changes.
* Wishlist Rejected::           Rejected Suggestions for X-Symbol.

Indexes

* Key Index::                   Key sequences.
* Program Index::               Programs and Emacs packages.
* Variable Index::              Commands, functions, variables.
* Concept Index::               Various topics.

@end detailmenu
@end menu

@c ===========================================================================

@node  Introduction, Installation, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex Overview
@cindex Introduction

When you edit La@TeX{}, HTML, BibTeX or @TeX{}info sources in Emacs,
package X-Symbol provides some kind of @sc{wysiwyg} by using real
characters for tokens like @code{\oplus} or @code{&trade;}.  It also
provides various input methods to insert these characters.  Thumbnails
for included images and real super-/subscripts and are also supported.

@menu
* Copying::                     X-Symbol is GPL'd.
* Summary::                     A brief summary of package X-Symbol.
* About::                       About this manual.
@end menu

@c ====================================================================

@node Copying, Summary, Introduction, Introduction
@comment  node-name,  next,  previous,  up
@section X-Symbol's Copying Conditions: GPL
@cindex Copying
@cindex Copyright
@cindex GPL
@cindex General Public License
@cindex License
@cindex Warranty

(This text is stolen from the @TeX{}info manual, Edition 4.0).

The programs currently being distributed that relate to X-Symbol include
Emacs Lisp files and X11 font files.  These programs are @dfn{free};
this means that everyone is free to use them and free to redistribute
them on a free basis.  The X-Symbol related programs are not in the
public domain; they are copyrighted and there are restrictions on their
distribution, but these restrictions are designed to permit everything
that a good cooperating citizen would want to do.  What is not allowed
is to try to prevent others from further sharing any version of these
programs that they might get from you.

Specifically, we want to make sure that you have the right to give away
copies of the programs that relate to X-Symbol, that you receive source
code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the X-Symbol related programs, you must give the recipients
all the rights that you have.  You must make sure that they, too,
receive or can get the source code.  And you must tell them their
rights.

Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to X-Symbol.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.

The precise conditions of the licenses for the programs currently being
distributed that relate to X-Symbol are found in the General Public
Licenses that accompany them.

@c ====================================================================

@node Summary, About, Copying, Introduction
@comment  node-name,  next,  previous,  up
@section Brief Summary of X-Symbol
@cindex Summary
@cindex Brief Summary
@cindex X-Symbol in a Nutshell

@itemize @bullet
@item
X-Symbol provides a @strong{minor mode} which make use of characters in
the Latin-1, Latin-2, Latin-3, Latin-5, and Latin-9 font (179 chars +
294 char aliases), the Adobe symbol font (109 chars) and the xsymb1 font
(165 chars, distributed with the package).  Additional fonts could be
used easily.

@item
These characters are used in the buffer to represent @strong{tokens}
(e.g., @TeX{} macros, @sc{sgml} entities, more ``token languages'' could be
added easily) in the file.  The @emph{conversion} is done automatically
when visiting the file, saving the buffer and turning the minor mode
on/off.

@item
Defines 8 @strong{input methods} for these characters: @emph{Menu},
@emph{Grid} (selecting a character with the mouse), @emph{Keyboard},
@emph{Context} (replace/modify similar-looking char sequence),
@emph{Electric} (automatic replace), @emph{Quail} (a Mule input method),
@emph{Token} (replace token by corresponding char), @emph{Read Token}
(completing minibuffer input of token).

@item
Offers some @strong{info} in the echo area for these characters (e.g.,
that the character under point represents the TeX macro @code{\leadsto}
and that the macro is defined in La@TeX{} package @file{latexsym.sty}).

@item
Allows to use a @strong{8bit file encoding} which is different from your
"normal" 8bit file encoding, e.g., you can visit @TeX{} files with
@code{\usepackage[latin5]@{inputenc@}} even if you normally use a Latin-2
font.

@item
Provides a kind of ``@strong{poor man's Mule}'' when running on an
XEmacs without Mule support: it can @emph{display} more than 256
characters via @code{font-lock} and removes most annoyances resulting
from the fact that, without Mule support, many ``X-Symbol characters''
are actually a sequence of two chars.

@item
Provides fonts for single-line innermost @strong{super-} and
@strong{subscripts} to be displayed with per-buffer control. The
invisible part, like @code{<sub>} in HTML, is revealed at point.

@item
Displays thumbnails for @strong{images} at the end of image insertion
commands with per-buffer control (e.g.,
@code{\includegraphics@{@var{file}@}} in La@TeX{}, @code{<img
src=@var{file}>} in HTML).  They show a scaled-down version of the
included image files (using @code{convert} from
@uref{@value{imagemagickurl},ImageMagick}).  A single mouse click
on the image or command invokes the image editor for the corresponding
image file.

@item
It @emph{does not} and @emph{will not} provide commands to hide (more or
less) uninteresting parts of your document or fontify them differently.
This is more the task of the corresponding major mode or
@code{font-lock}, e.g., @code{font-latex}.  (I admit, the support of
super- and subscripts might let you think that this is a good point for
the todo list of package X-Symbol.)  Using @code{outline-minor-mode} or
folding might also be an alternative.
@end itemize

If you prefer a more @sc{wysiwyg}-like document processor, you should
probably use @code{LyX} or @code{GNU TeXmacs}.  Here are some reasons
why you would use Emacs/XEmacs with package X-Symbol instead:

@itemize @bullet
@item
You have complete control over the La@TeX{} source.  X-Symbol supports
more characters.

@item
You can read any La@TeX{} source and you write normal La@TeX{} code,
i.e., package X-Symbol does not use any special format.

@item
It also supports HTML and @TeX{}info documents and BibTeX entries.

@item
You can use your favorite editor, i.e., Emacs or XEmacs.
@end itemize

@c ====================================================================

@node About,  , Summary, Introduction
@comment  node-name,  next,  previous,  up
@section About this Manual
@cindex About
@cindex Web Pages
@cindex Info Pages
@cindex Manual
@cindex Online Help

Apart from this manual, there are two other sources of information about
X-Symbol:

@itemize @bullet
@item
The web pages of X-Symbol provide a summary of X-Symbol, including some
screen shots.  You are strongly encouraged to read them carefully.  They
probably provide enough info for the standard user and can be found at:

@display
  @uref{@value{url}/}
@end display

@item
The online help for commands (functions) and user options (variables) is
quite technical.  It is shown during customization and when using Emacs'
Help menu.
@end itemize

This manual is somewhere in between: it more detailed than the web pages
and less technical than the online help.  For example, when explaining
some functionality, it states the default behavior, gives an impression
of what can be customized, and it even lists all related user options,
but it does not describes the technical format of possible values of
each option.

If you want to learn something about X-Symbol's internals, e.g., if you
want to define your own token language, see @ref{X-Symbol Internals}.

This manual does not explain Emacs in general or some optional programs
used by this package such as @code{convert} (used to produce the image
thumbnails).  It also includes no installation instructions for those
programs and the author of this package will not help you with the
installation of those programs (sorry for that).

You do not have to learn this manual by heart before sending a question
to the maintainer of X-Symbol, but you should give the impression that
your really have tried to find the necessary information yourself and
spend some time making your report precise.  Before sending a problem
report, please read @ref{Bug Reports}.

@c ===========================================================================

@node Installation, Concepts, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Installation
@cindex Installation

The short version of the installation instructions for package X-Symbol
on XEmacs is: uncompress & extract the @emph{binary distribution} in
directory @file{~/.xemacs/xemacs-packages/}, add
@code{(x-symbol-initialize)} to your @file{~/.emacs} and install
ImageMagick for the image support (unless you want to get a warning).

Please check the web page @emph{additionally} to the sections here for
the installation instructions for package X-Symbol on Emacs.

The rest of this chapter contains the long version.  I recommend that
you read this chapter completely after a short test of X-Symbol,
especially if you have customized your Emacs more or less heavily or if
you get some problems.

@menu
* Requirements::                Which programs you need for X-Symbol.
* Installing Files::            Basics 1: Put the files into your home dir.
* System-wide Installation::    Alternative:  Put the files into the XEmacs dir.
* Installing Lisp::             Basics 2: Initialize X-Symbol during startup.
* Installing Image Converter::  Recommended: How to install @code{convert}.
* Package Integration::         How X-Symbol interacts with other packages.
* Installing Fonts::            Optional: What to do when using other fonts.
* Installing Fonts Exceed::     If appropriate: What to do when using Exceed.
* Installing Fonts Lisp::       If appropriate: Lisp coding for other fonts.
* Installing Manual::           Optional: How to create the manual.
* Checking Installation::       Is package X-Symbol completely installed?
@end menu

@c ====================================================================

@node Requirements, Installing Files, Installation, Installation
@comment  node-name,  next,  previous,  up
@section Requirements
@cindex Requirements
@cindex Binary Package
@cindex Source Package
@cindex Old Version
@cindex Window System
@cindex X
@cindex Windows
@cindex MS-Windows
@cindex Character Terminal
@cindex TTY
@pindex Emacs
@pindex XEmacs

This development version of package X-Symbol works with Emacs-21.1 or
higher, and XEmacs 20.4 or higher (XEmacs-21.1.9 is strongly
recommended, @ref{FAQ XEmacs Core}), with or without Mule support.

X-Symbol should work with all window systems Emacs is running under (Mac
is not testet and might not work).  Under X, no restrictions apply.
Under Windows with Emacs, images will not be displayed (they are not yet
supported by Emacs under Windows).  Under Windows with XEmacs, X-Symbol
just supports a limited number of characters (Latin-1, Latin-5, and half
the math symbols) and no super- and subscripts, due to missing
MS-Windows fonts (@pxref{Wishlist Fonts}).  Under a character terminal,
X-Symbol just supports Latin-1 characters only, no super- and subscripts
and no images.

@pindex font-lock
@pindex lazy-shot
@pindex texmathp
@pindex auctex
This package require package @code{font-lock} (distributed with Emacs
and XEmacs), the use of package @code{lazy-shot} is recommended, see
@ref{Syntax Hiliting Packages}.

@pindex convert
If you want to see the images at the end of image insertion commands,
install @code{convert} from
@uref{@value{imagemagickurl},ImageMagick},
see @ref{Installing Image Converter}.  They show a scaled-down version
of the included image files.

@pindex makeinfo
@pindex texi2dvi
@pindex latex2html
If you want to produce the Info files yourself (they are included in the
binary distribution), you need @code{makeinfo}, Version 1.68 or higher.
If you want to produce a PS file from the manual, you need
@code{texi2dvi}.  If you want to produce an HTML version of this manual,
you need @code{texi2html}, Version 1.62 or higher.  @xref{Installing
Manual}.


@c ====================================================================

@node Installing Files, System-wide Installation, Requirements, Installation
@comment  node-name,  next,  previous,  up
@section Put the Files into your Home Directory
@cindex Basic Installation
@cindex Uncompress Tarball
@cindex Extract Tarball
@cindex Tarball
@cindex Binary Distribution

If you use Emacs, please check the @uref{@value{url}/news.html,web pages
of X-Symbol}.

In this section, we assume that you want to install the binary
distribution (also called the binary tarball) of package X-Symbol in
your home directory.  To install it somewhere below the XEmacs root (it
might be already there), see @ref{System-wide Installation}.  If you use
the source distribution, you should know what do to instead.

In directory @file{~/.xemacs/xemacs-packages/}, run
@example
zcat x-symbol-pkg.tar.gz | tar xvf -
@end example

Remember that @code{tar} does not overwrite write-protected files.

X-Symbol's @file{pcf} files and font directory must be world-readable 
since you do not own the X11 font server process.  You are on the safe
side, if you run
@example
chmod -R a+rx ~/.xemacs/xemacs-packages
@end example

If package X-Symbol has been installed system-wide and you install a
newer version in your @file{~/.xemacs/xemacs-packages/}, you get a warning during
XEmacs' startup (autoload error: already loaded).  You can safely ignore
this warning, but there is unfortunately no good way to get rid of it.
Yes, XEmacs' packaging system is excellent, but there is still a place
for improvements@dots{}.

Before XEmacs-21.0: the user package directory was @file{~/.xemacs/}
instead of @file{~/.xemacs/packages/}; also: delete and recompile the
@file{.elc} files.

@c ====================================================================

@node System-wide Installation, Installing Lisp, Installing Files, Installation
@comment  node-name,  next,  previous,  up
@section System-wide Installation: Put the Files into the XEmacs Directory
@cindex System-wide Installation
@cindex Installing System-wide
@cindex @file{default.el}
@cindex @file{site-start.el}

You can skip this section if your have installed X-Symbol in your home
directory according to the previous section.

If you install package X-Symbol system-wide, use @file{default.el} and
@file{@var{xemacs}/site-packages/} whenever @file{~/.emacs} and
@file{~/.xemacs/xemacs-packages/} are mentioned in the previous or
following subsections.  @file{@var{xemacs}/site-packages/} is the
directory of independent packages for XEmacs.

Under XEmacs-21, you can uncompress and extract the tarball by

@example
M-x package-admin-add-binary-package @key{RET} @var{dir}/x-symbol-pkg.tar.gz
@end example

Then, @file{@var{xemacs}/} is the default directory of buffer
@file{*Package Output*} (use @kbd{C-x C-f} in that buffer to see it).
It might be @file{/usr/local/lib/xemacs/xemacs-packages/} (the first
element in variable @code{late-packages}).

Under XEmacs-20, @file{@var{xemacs}/} might be
@file{/usr/local/lib/xemacs-@var{version}/}.  Here, you have to
uncompress and extract the tarball as described in @ref{Installing
Files}.  You also have to load the autoload file explicitly by putting
the following line into file @file{site-start.el}:

@lisp
(load "@var{xemacs}/lisp/x-symbol/auto-autoloads")
@end lisp

I would appreciate if you would set the following variables:

@vtable @code
@item x-symbol-installer-address
Please set this variable to your email address to catch problems which
could be solved locally.  In your private @file{~/.emacs}, you might
want to set this variable to @code{nil}.

@item x-symbol-package-url
If you have a local copy of the web pages (@pxref{Installing Manual}), set
this variable to the corresponding @sc{url}.
@end vtable

@c ====================================================================

@node Installing Lisp, Installing Image Converter, System-wide Installation, Installation
@comment  node-name,  next,  previous,  up
@section Make XEmacs Initialize X-Symbol During Startup
@cindex Installing Lisp
@cindex Lisp Installation
@cindex Elisp Installation
@cindex @file{.emacs}
@findex x-symbol-initialize

Put the following into your @file{~/.emacs} (or @file{~/.xemacs/init.el}):

@lisp
(x-symbol-initialize)
@end lisp

Basically, that's it!  If your XEmacs runs on a different machine, check
@ref{Installing Fonts}.

If you get a warning about X-Symbol not being able to deduce a default
encoding (or about limited support with XEmacs under Windows or a
character terminal, @ref{Requirements}), set the default coding
(@pxref{Default Coding}) by putting the following in front of the line
above:

@lisp
(setq x-symbol-default-coding 'iso-8859-1)
@end lisp

When running Emacs under a character terminal, you might need to use the
following (with or without X-Symbol):

@lisp
(unless window-system (standard-display-european 1))
@end lisp

If your character terminal does not support Latin characters, there is
no reason to use package X-Symbol.  In this case, use the following
instead:

@lisp
(when window-system (x-symbol-initialize))
@end lisp

The initialization can be controlled by the following variable:

@vtable @code
@item x-symbol-initialize
By default, package X-Symbol does a full initialization.  This includes
an integration with some packages, see also @ref{Package Integration}.
@end vtable

If you use a B/W monitor and XEmacs/no-Mule, it might be necessary to
remove the font properties of any face which is used on regions with
X-Symbol characters: @code{isearch}, @code{highlight},
@code{primary-selection}, @code{secondary-selection},
@code{paren-match}, @code{paren-mismatch}, @code{paren-blink-off},
@code{underline}.  I.e., for each @var{face}, use:

@lisp
(remove-specifier (get (get-face '@var{face}) 'font))
@end lisp

@c ====================================================================

@node Installing Image Converter, Package Integration, Installing Lisp, Installation
@comment  node-name,  next,  previous,  up
@section Installing the Image Converter from ImageMagick
@cindex Installing Image Converter
@cindex Installing @code{convert}
@cindex Image Converter Installation
@cindex @code{convert} Installation

@pindex convert
Program @code{convert} from ImageMagick is used to display images at the
end of image insertion commands.  The images show a scaled-down version
of the included image files.

@vindex x-symbol-image-converter
While the installation of @code{convert} is optional, you get a warning
if @code{convert} is not found on your system or if there is no image
format supported by both @code{convert} and Emacs.  Set variable
@code{x-symbol-image-converter} to @code{nil} if you don't want to get
the warning.

@vindex x-symbol-image-convert-program
On Unix, @code{convert} must be in your @code{$PATH}.  On Windows, it is
assumed to be found at @file{C:\ImageMagick\convert}.  If this is not
the case, you have to customize the variable
@code{x-symbol-image-convert-program}.

Check @uref{@value{imagemagickurl}} for the installation
instructions.  Run @samp{convert -h} and @samp{convert -list Format} (in
newer versions of ImageMagick) in your shell to check whether the
installation of ImageMagick was successful.  If you have problems, check
the ImageMagick web page for FAQs and mailing lists.
@comment ImageMagick-5.0..5.37 failed to show formats sometimes

If you do not have a truecolor device (i.e., just 256 colors), package
X-Symbol uses @code{convert} with a colormap by default (@pxref{Image
Conversion}).  You might create and use your own colormap instead.  It
should be tuned to include the colors you use in Emacs anyway, i.e., the
face colors.

@c ====================================================================

@node Package Integration, Installing Fonts, Installing Image Converter, Installation
@comment  node-name,  next,  previous,  up
@section Package Integration
@cindex Package Integration
@cindex Integrating Package
@cindex Other Packages

You might skip this section when trying package X-Symbol the first time.
Nevertheless, I strongly recommend to read this section if you have
customized your Emacs more or less heavily or if you get some problems.

Some features of X-Symbol work by hooking itself into existing functions
of Emacs or related packages via predefined hooks.  A potential problem
arises if your customization or other packages use the same hooks, or if
other packages assume these hooks not to be used, e.g., some packages
assume the buffer contents to contain the same characters as the
corresponding file.

This section lists some special adaptation for other packages
(everything is fine if you do not use these packages).  It also lists
potential problems in combination with other packages.  If you discover
some problems in combination with other packages, please let me know.

@menu
* LaTeX Packages::              Packages used in La@TeX{} buffers.
* Syntax Hiliting Packages::    Package @code{font-lock} and support modes.
* File IO Packages::            Compression, encryption, remote files, etc.
* Miscellaneous Packages::      Other packages.
@end menu


@node LaTeX Packages, Syntax Hiliting Packages, Package Integration, Package Integration
@comment  node-name,  next,  previous,  up
@subsection La@TeX{} Packages
@cindex La@TeX{} Packages
@cindex Integrating La@TeX{} Packages

Objectives: relate positions in buffer to positions in file, do
conversion in master/slave buffers, preserve highlighting, improve input
methods and other things.

@table @code
@item auctex
@pindex auctex
@pindex texmathp
@findex TeX-next-error
@vindex TeX-translate-location-hook
@findex x-symbol-tex-error-location
Use Version 9.9c or higher, which includes @code{texmathp}.  There is
some special X-Symbol adaptation for Auc@TeX{}:

@itemize @minus
@item
@vindex TeX-master
X-Symbol supports Auc@TeX{}'s multifile documents: it respects the
variable @code{TeX-master} when searching for the file encoding
(@pxref{File Coding}) and when converting image files with relative
names (@pxref{Image Display}).

@item
@vindex TeX-region-hook
X-Symbol supports Auc@TeX{}'s region commands: it ensures that
characters in @file{_region_.tex} buffer are converted according to the
parent buffer.  Initialization changes @code{TeX-region-hook}.  Requires
Auc@TeX{}, v9.8a or higher.

@item
X-Symbol's input method Electric (@pxref{Input Method Electric}) with
token language @code{tex} uses package @code{texmathp}.

@item
@vindex LaTeX-math-insert-function
Auc@TeX{}'s math mode commands also inserts X-Symbol characters
(@pxref{Mathematics,,,
@value{auctex},
@value{auctexman}}).
Initialization sets @code{LaTeX-math-insert-function}.  Requires
Auc@TeX{}, v9.8a or higher.

@item
@findex TeX-next-error
@vindex TeX-translate-location-hook
If @TeX{} displays an error message, it also displays the context of the
error position.  Auc@TeX{} uses the context to set point to this
position when @kbd{M-x TeX-next-error} is invoked.  The former context
are characters in the file, the latter characters in the buffer,
X-Symbol provides the translation.  Initialization changes
@code{TeX-translate-location-hook}.
@end itemize

@item bib-cite
@pindex bib-cite
Use Version 3.0 or higher.  Initialization of package X-Symbol changes
the installation of package bib-cite to make X-Symbol's decoding not
overwrite @code{bib-cite}s highlighting of @code{\cite} and friends.

@item preview-latex
@pindex preview-latex
@findex x-symbol-tex-preview-locations
@TeX{}'s error positions are also used by package @code{preview-latex},
which was clever enough to reuse the above mentioned hook of Auc@TeX{}.
Unfortunately, that hook is @dots{} and does not allow a fast translation of
error positions, so @code{preview-latex} allows to provide better
variants of functions in that hook.  X-Symbol's variant is
@code{x-symbol-tex-preview-locations}.

@item reftex
@pindex reftex
@vindex reftex-translate-to-ascii-function
Use Version 3.26 or higher.  For a workaround for some minor annoyances
with the combination Ref@TeX{}/X-Symbol/Multifile Document, see
@ref{Problems and Work-arounds,,,@value{reftex},@value{reftexman}}.  By
default, the initialization of package X-Symbol makes Ref@TeX{}'s label
creation use the nicer Asciification of package X-Symbol (@pxref{Ascii
Representation}) by setting @code{reftex-translate-to-ascii-function}.

@item whizzytex
Use the newest.
@end table


@node Syntax Hiliting Packages, File IO Packages, LaTeX Packages, Package Integration
@comment  node-name,  next,  previous,  up
@subsection Syntax Highlighting Packages (@code{font-lock} and add-ons)
@cindex Syntax Highlighting Packages
@cindex @code{font-lock} Packages
@cindex Integrating @code{font-lock} Packages

Objectives: start highlighting after conversion.  Highlighting is
needed for super- and subscripts and when using XEmacs without Mule
support.

@table @code
@item fast-lock
@pindex fast-lock
@vindex fast-lock-save-faces
I recommend to use package @code{lazy-shot} instead.  By default, the
initialization of package X-Symbol sets @code{fast-lock-save-faces} to
@code{nil} to make package @code{fast-lock} work with X-Symbol.

@item font-latex
@pindex font-latex
@vindex font-lock-maximum-decoration
I suggest to set @code{font-lock-maximum-decoration} to value @code{t},
2 or higher if you do not want to use super- and subscripts in arguments
of @code{\label} and friends.  @xref{FAQ Stupid Subscripts}.

@item font-lock
@pindex font-lock
@vindex font-lock-auto-fontify
Is required by this package (@pxref{Role of font-lock}).  I strongly
recommend @emph{not} to turn on font-lock in @emph{any} mode hook, set
@code{font-lock-auto-fontify} to @code{t} instead (this is the default,
anyway).  See also @code{lazy-shot}.

If you turn on font-lock in a mode-hook, visiting a file would become
slower, since X-Symbol mode is usually turned on @emph{after} the
functions in the mode hook have been run, i.e., the fontification is
getting useless if the tokens are automatically decoded.

@item lazy-lock
@pindex lazy-lock
From XEmacs-20.3 on, the successor is called @code{lazy-shot}.

@item lazy-shot
@pindex lazy-shot
Is strongly recommended.
@end table


@node File IO Packages, Miscellaneous Packages, Syntax Hiliting Packages, Package Integration
@comment  node-name,  next,  previous,  up
@subsection File I/O Packages
@cindex File I/O Packages
@cindex I/O Packages
@cindex Remote File Packages
@cindex Compression Packages
@cindex Encryption Packages
@cindex Integrating I/O Packages

Issue: compression, encryption and so on can be seen as some kind of
conversion.  When doing multiple conversion, the sequence matters.

@table @code
@item ange-ftp
@pindex ange-ftp
See also @code{efs} and @code{jka-compr}.

@item comint
@pindex comint
@vindex comint-input-sender
The default installation makes @code{comint}s in-/output use X-Symbol's
conversion function.  If you set variable @code{comint-input-sender},
set it before initializing package X-Symbol.

@item crypt
@itemx crypt++
@pindex crypt
@pindex crypt++
@findex save-buffer
@vindex x-symbol-auto-conversion-method
I recommend to use package @code{jka-compr} instead.  @xref{Spurious
Encodings}.  @xref{No Encoding}.  If you use @code{crypt} or  @code{crypt++} and the
character @code{alpha} looks like @samp{\233a} after @code{save-buffer},
set this variable to @code{slowest}.  @xref{Open Questions}.

@item efs
@pindex efs
XEmacs' version of @code{ange-ftp}.  See also @code{jka-compr}.

@item iso-cvt
@pindex iso-cvt
There is no need to use it.  Package X-Symbol already provides the
conversion between Latin-1 characters and ``@TeX{} macros''.  Package
X-Symbol does not provide the German and Spanish conversion tables,
though.

@item iso-sgml
@pindex iso-sgml
There is no need to use it.  Package X-Symbol already provides the
conversion between Latin-1 characters and ``@sc{sgml} entities''.
@xref{Miscellaneous Packages}, package @code{psgml-html}.

@item jka-compr
@pindex jka-compr
Can be used with package X-Symbol, preferred to @code{crypt}.  The
following is absolutely necessary (with or without using package
X-Symbol, at least in older Emacsen): load @code{jka-compr} after
@code{efs}/@code{ange-ftp}!

@item latin-unity
@pindex latin-unity
This XEmacs package can be used with package X-Symbol, functionality is already provided by
X-Symbol for Latin-@{1,2,3,5,9@} characters: remapping (@pxref{Char
Aliases}) and recoding (@pxref{File Coding}).  Has some safe-encoding
mechanism, but the test comes currently too early (@pxref{Wishlist
Emacs}).

@c TODO: test mule-ucs.el with Emacs-21.4
@item ucs-tables
@pindex ucs-tables
@findex unify-8859-on-decoding-mode
@findex unify-8859-on-encoding-mode
The Emacs minor modes @code{unify-8859-on-decoding-mode} and
@code{unify-8859-on-encoding-mode} can be used with package X-Symbol.

@item vc
@pindex vc
@findex vc-next-action
If you use package @code{crypt}, @code{vc-next-action} and friends
encode characters to tokens.  @xref{Spurious Encodings}.
@end table


@node Miscellaneous Packages,  , File IO Packages, Package Integration
@comment  node-name,  next,  previous,  up
@subsection Miscellaneous Packages
@cindex Miscellaneous Packages

@table @code
@item abbrev
@pindex abbrev
On XEmacs without Mule support, I recommend to set variable
@code{words-include-escapes} to @code{t}.  @xref{Nomule Problems}.

@item completion
@pindex completion
Should work with X-Symbol (earlier version of X-Symbol had problems with
input method token).

@item desktop
@pindex desktop
XEmacs' version (an old one) does not save its @file{.emacs.desktop}
files with a coding system.  Emacs' version save it with an incorrect
coding system.  Thus, strings which contain X-Symbol's private
characters might get corrupted.  See also package @code{session} below.

@item flyspell
@pindex flyspell
@findex global-flyspell-mode
Should work apart from the general problem of @code{ispell}.

@item func-menu
@pindex func-menu
Should work with X-Symbol.

@item ispell
@pindex ispell
The package @code{ispell} assumes the buffer contents to be the same as
the file contents and does not provide any hook to fix this.  This
should be fixed in @code{ispell}, see @ref{Wishlist Emacs}.  @xref{FAQ
Spell Check}.

@item ProofGeneral
@pindex ProofGeneral
Use a future version (hopefully v3.4).  Includes special X-Symbol
initialization/handling and defines additional token languages.
@xref{External Languages}.

@item psgml-html
@pindex psgml
@pindex psgml-html
@code{psgml-html}: Do not set @code{html-auto-sgml-entity-conversion} to
non-@code{nil}.  @xref{File IO Packages}, package @code{iso-sgml}.

@item session
@pindex session
Use Version 1.5a or higher.  If strings in this file should always be
read correctly, you should put @code{(x-symbol-init-input)} into your
@file{~/.emacs}; otherwise strings containing X-Symbol's private
characters read from the @file{~/.session} file might look funny.  See
also package @code{desktop} above.

@item x-compose
@pindex x-compose
All characters from @code{x-compose} are also supported by package
X-Symbol.  Thus, I recommend to use @kbd{@key{multi-key}} instead
@kbd{C-=} when running under XEmacs without Mule support.
@xref{Introducing Input Methods}.
@end table

@c ===========================================================================

@node Installing Fonts, Installing Fonts Exceed, Package Integration, Installation
@comment  node-name,  next,  previous,  up
@section Installing Additional Fonts
@cindex Installing Fonts
@cindex Fonts
@cindex X11 Fonts

You don't have to install X-Symbol fonts in usual circumstances (with
the binary distribution, Emacs runs on the same machine, you are happy
with the default fonts).

If your Emacs runs on a different machine, please follow the steps 5 and
6 below or read the next section.

If you want to install additional fonts (since the binary distribution
contains only a limited selection of fonts and font sizes), please
follow the following sequence which worked for me (on SunOS
5.4-5.6/Solaris).  If you have to do s.th. (completely) different on
your system, please let me know---I will include your hints.

If you are lost with the following instructions, use the standard fonts
from the binary distribution.  (Sorry, I do not have to time to answer
general Unix font questions.  Or to be more exact, I'm not an expert in
this area@dots{}.  Nevertheless, if you have a clearer explanation for
the installation sequence below, please send me a patch to
@file{man/x-symbol/x-symbol.texi}.)

@enumerate
@item
@pindex xfd
@pindex xfontsel
Find the font which you want to replace by checking fonts with the X11
program @code{xfontsel} or @code{xfd}.  The bad news is that there is no
general way to say which character belongs to which font.  My only goal
was to use standard fonts whenever possible; the rest belong the the
xsymb1 font (which I have designed).  If you want to use a font as an
alternative to another font, it must have the same charset
registry-encoding.

@item
Find the @file{.bdf} files of your preferred fonts in your file system
or by Internet search engines like Google.  The source distribution of
package X-Symbol contains @file{.bdf} files for additional fonts sizes
of all fonts except the xsymb1 font (@pxref{Wishlist Fonts}).

There are two categories of @file{.bdf} files.  The first category
contains files for fonts which are already installed; the files are
needed to create and install the super- and subscript versions.  Copy
these files to @file{~/.xemacs/xemacs-packages/etc/x-symbol/origfonts/}.  The second
category contains files for fonts which are not installed.  Copy these
files to @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}.

@item
In file @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/Makefile},
change variables @code{ORIGBDFS} for the first category and @code{BDFS}
for the second category accordingly.

@item
@pindex perl
In directory @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/},
execute @code{make mkdirs}, and @code{make pcfs}.  You need GNUs
@code{make} and @code{perl}, Version 5 (or higher).  You might need to
check the permissions of the created files (@pxref{Installing Files}).

@item
If your Emacs runs on a different machine or if you want to use the
fonts outside Emacs, too, add X-Symbol's fonts to your font path by
inserting the following in your @file{~/.xsession} (X11 startup file).

@pindex xset
@example
xset +fp ~/.xemacs/xemacs-packages/etc/x-symbol/pcf/
@end example

For a system-wide installation, you might want to add this directory to
the system-wide font path instead.

If your system doesn't have @code{xset}, you should copy all @file{.pcf}
files (compiled fonts) from @file{~/.xemacs/xemacs-packages/etc/x-symbol/pcf/} into
directory @file{/usr/lib/X11/fonts/75dpi/} (Slackware distribution) and
run @samp{mkfontdir 75dpi} in that directory.

@item
Your are on the safe side if you restart X11 after this.

@item
Set the Emacs Lisp variables which define the fonts.  @xref{Installing Fonts Lisp}.
@end enumerate

@c ====================================================================

@node Installing Fonts Exceed, Installing Fonts Lisp, Installing Fonts, Installation
@comment  node-name,  next,  previous,  up
@section Installing Fonts for Exceed (X-server on Windows)
@cindex Installing Fonts
@cindex Fonts
@pindex Exceed
@cindex Windows
@cindex Windows
@cindex X-Server

If your X-server on Windows is Exceed and if you have configured
Exceed to use the ``native window manager'' for your Unix screens, you
must install the X-Symbol fonts on Windows.  The following works with
Exceed 6.0 & NT 4.0 and Exceed 7.0 & Windows 2000:

@enumerate
@item
In Unix, edit file @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/makesub} to limit 
the shift for superscript to 3 points:
@smallexample
%supoffs = ('08',3, 10,3, 12,3, 14,3, 16,3, 18,3, 24,3);
@end smallexample

@item
Then, execute @code{make mkdirs}, and @code{make gens} in
@file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}.  If you have problems, please read 
the previous section.

@item
In Exceed's configuration window, click on @key{Font} to open Window
@file{Font Settings}.  In this window, click on @key{Select All}, then
on @key{Compile Fonts...}.

@item
Copy X-Symbol's @file{bdf} files in @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}
and @file{~/.xemacs/xemacs-packages/etc/x-symbol/genfonts/} to a Windows directory
and select this directory in the Exceed Window @file{Compile Fonts}.
Click on @key{Compile}.

@item
In Window @file{Font Settings}, click on @key{Font Database...}.  In
this window, click on @key{Add...}.  Enter the output directory from the
previous step as the @samp{Font Directory} and @code{xsymb} as the
@samp{File Name (*.fdb)}.  Click on @key{OK}.

@item
You might want to rearrange the sequence of Font DB files to let files
@file{75dpi} appear prior to files @file{100dpi}, because X-Symbol's
fonts are designed for 75dpi.

@item
In Window @file{Font Database}, click on @key{Rebuild Database...} and
then on @key{OK}.
@end enumerate

Note: @emph{Windows NT 4.0 will crash (bluescreen) if you use fonts
compiled by Exceed from the @file{pcf} files or if you missed step 1,
i.e., limiting the superscript shift!}  With Exceed 7.0 & Windows 2000,
there is no crash, but these fonts cannot be displayed.

If you use XEmacs with Exceed as your X-server on Windows, X-Symbol
cannot warn you about undefined fonts, because XEmacs in general cannot
recognizes in that case, whether a font exists.

@c ====================================================================

@node Installing Fonts Lisp, Installing Manual, Installing Fonts Exceed, Installation
@comment  node-name,  next,  previous,  up
@section Lisp Coding when Using Other Fonts
@cindex Font Lisp Setup
@cindex Font Lisp Installation

Package X-Symbol needs to know which fonts to use for the X-Symbol
characters and super- and subscripts.  It also must interact with
package @code{font-lock} to display them (@pxref{Role of font-lock}).

If you have installed additional fonts (@pxref{Installing Fonts}) for
use with package X-Symbol, you might have to change the following
variables:

@vtable @code
@item x-symbol-latin1-fonts
@itemx x-symbol-latin2-fonts
@itemx x-symbol-latin3-fonts
@itemx x-symbol-latin5-fonts
@itemx x-symbol-latin9-fonts
@itemx x-symbol-xsymb0-fonts
@itemx x-symbol-xsymb1-fonts
The value of each variable consists of three elements: one for the
normal text, one for subscripts and one for the superscripts.  Each
element is a list of fonts which are tried in order---the first which
exists on your system is used.

If you change the values of one of these variables, do only specify the
same charset registry@minus{}encoding (e.g., @samp{adobe-fontspecific})
as specified by the fonts in the default value of this variable.

@item x-symbol-font-sizes
Here you can specify the sizes for all fonts in the above mentioned
variables.  The value consists of regular expressions matching font
names and numbers which replace all occurences of @samp{%d} in the
names.
@end vtable

E.g., if you prefer larger fonts, you might want to insert the following
into your @file{~/.emacs}:

@smalllisp
(setq x-symbol-font-sizes
  '(18 ("_su[bp]-" . 14) ("\\`-etl-" . 16)))
(setq x-symbol-xsymb0-fonts
  '(("-adobe-symbol-medium-r-normal-*-*-%d0-*-*-*-*-adobe-fontspecific"
     "-xsymb-xsymb0-medium-r-normal--%d-%d0-75-75-p-85-adobe-fontspecific")
    ("-adobe-symbol_sub-medium-r-normal-*-*-%d0-*-*-*-*-adobe-fontspecific"
     "-xsymb-xsymb0_sub-medium-r-normal--%d-%d0-75-75-p-74-adobe-fontspecific")
    ("-adobe-symbol_sup-medium-r-normal-*-*-%d0-*-*-*-*-adobe-fontspecific"
     "-xsymb-xsymb0_sup-medium-r-normal--%d-%d0-75-75-p-74-adobe-fontspecific")))
@end smalllisp

The first assignment changes the font sizes, the second makes X-Symbol
using the original Adobe symbol font instead of my minor modification
(appearance) of it.  The xsymb1 font will be scaled, which might not
look nice (@pxref{FAQ Font Size}).

You might want to change the following variables:

@vtable @code
@item x-symbol-latin-force-use
Package X-Symbol defines Latin characters even when the corresponding
fonts are missing (this can be changed by this variable).  Characters
for the symbol fonts are only defined if the corresponding fonts are
available.

@item x-symbol-mule-change-default-face
Package X-Symbol does not change the fonts of pre-defined Mule charsets
(this can be changed by this variable).  Thus, the variables from
@ref{Installing Fonts Lisp} might have no influence if Emacs
already has defined fonts for the corresponding charsets.
@end vtable

@c ====================================================================

@node Installing Manual, Checking Installation, Installing Fonts Lisp, Installation
@comment  node-name,  next,  previous,  up
@section Installing Info, Postscript and HTML Files
@cindex Installing Manual
@cindex Info
@cindex Texinfo
@cindex Postscript
@cindex HTML
@cindex Manual
@cindex Documentation

@pindex makeinfo
To create the info files, execute @code{make info} in directory
@file{~/.xemacs/xemacs-packages/man/x-symbol/} of the distribution.  It requires
@code{makeinfo}, Version 1.68 or higher.  This should not be necessary
if you use the binary distribution of package X-Symbol.

If no entry for X-Symbol is automatically added to the info directory
listing, add the following line to @file{~/.xemacs/xemacs-packages/info/dir}:
@smallexample
* X-Symbol::	 Semi WYSIWYG for LaTeX, HTML and other "token languages"
@end smallexample


@pindex texi2dvi
Optionally, you might want to create a printed document from the @TeX{}info
file.  Execute @code{make ps} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/}
of the distribution.  It requires @code{texi2dvi}.

@pindex latex2html
Optionally, you can create an online manual for a web browser by
executing @code{make html} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/} of
the distribution.  It requires @code{texi2html}.

All formats of the manual are created by executing @code{make all}.

@c ====================================================================

@node Checking Installation,  , Installing Manual, Installation
@comment  node-name,  next,  previous,  up
@section Checking the Correct Installation of Package X-Symbol
@cindex Checking Installation
@cindex Final Installation Checks
@cindex Installation Checks

After having completed the installation, exit and restart Emacs.

@itemize @bullet
@item
Type @kbd{M-x show-message-log} to check whether you got problems so
far, e.g., whether errors occurred when loading a file.  If you do,
identity and correct the offender.

@item
Type @kbd{M-x x-symbol-grid} in buffer @file{*scratch*}.  If you get the
Grid but if you see less characters than you see on the web page of
package X-Symbol, you have decided to use other fonts but failed to
install them correctly.  This is also mentioned in buffer
@file{*Warnings*}.  @xref{Installing Fonts}.

@item
Move your mouse pointer to any X-Symbol character in buffer
@file{*X-Symbol Grid (x-symbol charsym)*}, press the right mouse button
and initialize successively all token languages.

@item
Again, type @kbd{M-x show-message-log} to check whether you got problems
so far, e.g., whether errors occurred when loading a file.  If you do,
identity and correct the offender.

@item
If buffer @file{*Warnings*} does not exist in the buffer menu,
everything is fine.  So is (for me as the author of package X-Symbol),
if @samp{X-Symbol} is not mentioned there.  If there is a warning with
@samp{no valid image converter}, you have forgotten to install
ImageMagick (@pxref{Installing Image Converter}).
@end itemize

@c ===========================================================================

@node Concepts, Input Methods, Installation, Top
@comment  node-name,  next,  previous,  up
@chapter Concepts of Package X-Symbol
@cindex Concepts
@cindex Terminology
@cindex Basics

This chapter describes the concepts of package X-Symbol.  It contains
quite a few forward references to feature which are based on these
concepts, such as @ref{Input Methods}, and @ref{Features}.

@menu
* Token Language::              What does a X-Symbol character represent.
* Conversion::                  Decoding tokens, encoding characters.
* Minor Mode::                  How to control the behavior of X-Symbol.
* Poor Mans Mule::              Running X-Symbol under XEmacs/no-Mule.
* Role of font-lock::           Why does X-Symbol need @code{font-lock}.
* Char Group::                  Character group and token classes.
@end menu

@c ===========================================================================

@node Token Language, Conversion, Concepts, Concepts
@comment  node-name,  next,  previous,  up
@section Token Language
@cindex Token Language
@cindex Language

As mentioned in the overview, ``X-Symbol Characters'' in the buffer are
represented by ``tokens'' in the file.  The correspondence between these
is determined by the @dfn{token language} which is in close relation to
the major mode of the current buffer.  E.g., character @code{alpha}
stands for @code{\alpha} in La@TeX{} buffers.

For details of predefined token languages ``@TeX{} macro'' (@code{tex}),
``@sc{sgml} entity'' (@code{sgml}), ``Bib@TeX{} macro'' (@code{bib}), and
``@TeX{}info command'' (@code{texi}), see @ref{Supported Languages}.

The token language determines the conversion between X-Symbol characters
and tokens (@pxref{Conversion}), the input methods (@pxref{Input
Methods}), and various other features (@pxref{Features}).

The token language is defined by the following buffer-local variable:

@vtable @code
@item x-symbol-language
Token language used in current buffer.  You can set this variable in the
``local variables list'' near the end of the file (@pxref{File
Variables,,,@value{emacs},@value{emacsman}}), e.g.:

@example
%% Local Variables:
%% x-symbol-language: tex
%% End:
@end example
@end vtable

Package X-Symbol uses a reasonable value according to the major mode and
the file name of a buffer if the variable is not already buffer-local.
A valid token language is required to turn on X-Symbol Minor mode, see
@ref{Minor Mode}.

A token language must be @dfn{registered}, if you want to use it.  By
default, the above mentioned token languages are registered.

@c ===========================================================================

@node Conversion, Minor Mode, Token Language, Concepts
@comment  node-name,  next,  previous,  up
@section Conversion: Decoding and Encoding
@cindex Conversion
@cindex Decoding
@cindex Encoding

As mentioned, X-Symbol characters in the buffer are represented by
tokens in the file.  Thus, we need some conversion from tokens to
characters, called @dfn{decoding}, and some conversion from characters
to tokens, called @dfn{encoding}.

We have the additional problem that some characters are not only
represented by tokens, but also via some 8bit character encoding.

Package X-Symbol supports the following 8bit character encodings:
Latin-1 (@code{iso-8859-1}), Latin-2 (@code{iso-8859-2}), Latin-3
(@code{iso-8859-3}), Latin-5 (@code{iso-8859-9}), and Latin-9
(@code{iso-8859-15}).  It currently supports less encodings with XEmacs
on Windows (@pxref{Requirements}).


@menu
* Default Coding::              Normal File and Default Encoding.
* File Coding::                 Specific encoding of a file.
* Controlling 8bit Coding::     Do you want to store 8bit characters?
* Unique Decoding::             Restrict decoding to avoid normalization?
* Conversion Commands::         Interactive encoding and decoding.
* Copy with Conversion::        Copy & paste with conversion.
* Char Aliases::                Different charsets include the same chars.
@end menu


@node Default Coding, File Coding, Conversion, Conversion
@comment  node-name,  next,  previous,  up
@subsection Normal File and Default Encoding
@cindex Default Coding
@cindex Default Encoding
@cindex Default Font
@cindex Coding, Default
@cindex Encoding, Default
@cindex Font, Default

As mentioned, some characters have a 8bit file encoding, and X-Symbol
needs to know which 8bit file encoding you use normally when visiting a
file and saving a buffer.

With Mule support, Emacs/XEmacs can recognize the @dfn{normal file
encoding}, also called a coding system (@pxref{Recognize
Coding,,,@value{emacs},@value{emacsman}}).

Without Mule support, XEmacs can usually only support 8bit characters of
one encoding; this encoding corresponds to the charset/registry of your
default font.  Here, the @dfn{normal file encoding} is the default
encoding:

@vtable @code
@item x-symbol-default-coding
The default encoding.  The value must be a symbol denoting one of the
supported encodings or @code{nil}.  The variable must be set before
X-Symbol has been initialized.  @xref{Installing Lisp}.
@end vtable

The @dfn{default encoding} is not only used to determine the normal file
encoding without Mule, but also for the following:

@itemize @bullet
@item
X-Symbol has its own mechanism to recognize a file encoding which only
works with a specified default encoding.  @xref{File Coding}.

@item
The same character can be included in various Latin charsets and
X-Symbol needs to know which of the instances (which Emacs views as
different characters) to support.  @xref{Char Aliases}.

@item
Without Mule support, the default encoding is also needed to decide
which characters have to be faked by 2 characters internally: exactly
the characters in those charsets which do not correspond to the default
encoding.  @xref{Poor Mans Mule}.
@end itemize

To deduce the default value, X-Symbol inspects the Mule language
environment and the output of the shell command @code{locale}, or to be
more exact:

@example
locale -ck code_set_name charmap
@end example

Without Mule support, you get a warning if the command does not exist on
your system or lists an encoding which is not supported by X-Symbol,
such as some Asian encoding.  Value @code{nil} is the same as
@code{iso-8859-1}.

With Mule support, you get a warning if the command lists a supported
encoding which is different from the encoding deduced from the Mule
language environment.  Value @code{nil} makes sure that X-Symbol file
encoding detection (@pxref{File Coding}) only works if Emacs has
detected the same encoding; it works like @code{iso-8859-1} otherwise.


@node File Coding, Controlling 8bit Coding, Default Coding, Conversion
@comment  node-name,  next,  previous,  up
@subsection File Coding of 8bit Characters
@cindex File Coding
@cindex Coding in File
@cindex Encoding in File
@cindex 8bit File Coding
@cindex Latin File Coding
@cindex Recoding

X-Symbol can use a different encoding for single buffers/files, even if
you use X-Symbol on XEmacs without Mule support.  To do so, set the
following buffer-local variable:

@vtable @code
@item x-symbol-coding
8bit character encoding in the file visited by the current buffer.
Value @code{nil} represents the normal file encoding (@pxref{Default
Coding}).

With Mule support, any value other than @code{nil} is considered invalid
if the normal file encoding is neither the same as this value nor the
same as the default encoding.  I.e., if your default encoding is
@code{nil}, X-Symbol's file encoding detection never takes precedence
over Emacs' one, i.e., the normal file encoding.

You can set this variable in the ``local variables list'' near the end
of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}),
e.g.:

@example
<!-- Local Variables: -->
<!-- x-symbol-coding: iso-8859-2 -->
<!-- End: -->
@end example
@end vtable

If the variable is not already buffer-local, a reasonable value is
deduced when turning on X-Symbol (@pxref{Minor Mode}) by searching for
some language dependent headers at the beginning of the file:

@vtable @code
@item x-symbol-auto-coding-search-limit
X-Symbol usually searches for something like
@samp{\usepackage[@dots{}]@{inputenc@}} (@pxref{TeX Macro}) or @samp{<meta @dots{}
charset=@dots{}>} (@pxref{SGML Entity}) in the first 10000 characters.
@end vtable

If you choose not to save a file containing 8bit characters
(@pxref{Controlling 8bit Coding}), the file encoding is still important,
since the file might contain 8bit characters when you visit it.

If the file encoding is different to the normal file encoding, X-Symbol
performs the necessary recoding itself.  @dfn{Recoding} changes a
character with code position @var{pos} in one charset to a character
with the same code position @var{pos} in another charset.  If the normal
file encoding is different to the default encoding, X-Symbol also
resolves character aliases (@pxref{Char Aliases}).

If you have specified an invalid file encoding (including an encoding
different to a non-default normal file encoding), we have the following
cases:

@itemize @bullet
@item
If the normal file encoding is unsupported (any file encoding is invalid
in this case) or if the normal file encoding is supported and the file
does not contain 8bit characters, we always encode all X-Symbol
character (@pxref{Controlling 8bit Coding}).  The modeline includes
@samp{-i} to represent the file encoding (@pxref{Minor Mode}), except if
the default encoding is @code{nil}, the normal file encoding is
unsupported, and the variable @code{x-symbol-coding} is not specified.

@item
If the normal file encoding is supported and the file contains at least
one 8bit character, X-Symbol does not touch 8bit characters and never
produces them, neither via decoding (@pxref{Unique Decoding}) nor via
input methods.  The modeline includes @samp{-err} to represent the file
encoding (@pxref{Minor Mode}).
@end itemize

We end with a little example: if your normal file encoding and default
encoding is Latin-1, and you visit a file with
@samp{\usepackage[latin9]@{inputenc@}} producing some document containing
the Euro sign, you see the Euro character in Emacs when X-Symbol is
enabled, but you see the currency character without X-Symbol.


@node Controlling 8bit Coding, Unique Decoding, File Coding, Conversion
@comment  node-name,  next,  previous,  up
@subsection Store or Encode 8bit Characters
@cindex Storing 8bit Characters
@cindex Controlling 8bit Coding
@c @cindex Buffer 8bit Control
@cindex 8bit Coding Control
@cindex Latin in File

You can specify that 8bit characters (according to the coding in your
file, see @ref{File Coding}), are not encoded to tokens (when saving a
file), by setting the following buffer-local variable:

@vtable @code
@item x-symbol-8bits
Whether to store 8bit characters when saving the current buffer.

You can set this variable in the ``local variables list'' near the end
of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}),
e.g.:

@example
%% Local Variables:
%% x-symbol-8bits: t
%% End:
@end example
@end vtable

If the variable is not already buffer-local, a reasonable value is
deduced when turning on X-Symbol (@pxref{Minor Mode}) by setting it the
the value of @code{x-symbol-coding}, or searching in the file for 8bit
characters:

@vtable @code
@item x-symbol-auto-8bit-search-limit
If there is a 8bit character in the file when visiting it, X-Symbol will
also store 8bit characters when saving the buffer.
@end vtable

If the file encoding is invalid (@pxref{File Coding}), we always search
for 8bit characters in the complete document and set
@code{x-symbol-8bits} accordingly.  Then, a non-@code{nil} value also
implies unique decoding (@pxref{Unique Decoding}).

While the variable @code{x-symbol-8bits} usually only influences the
encoding, it also influences the decoding if you choose to decode
uniquely (@pxref{Unique Decoding}).

Setting variable @code{x-symbol-8bits} to @code{nil} does not
necessarily mean that the file will not contain 8bit characters: the
characters might have no token representation in the current token
language (@pxref{TeXinfo Command}), or they are glyphs for ununsed code
points in the Latin-3 charset.  In both cases, it is unlikely that you
have inserted these invalid characters via X-Symbol's input methods
(@pxref{Introducing Input Methods}), you have probably copied them into
the current buffer.


@node Unique Decoding, Conversion Commands, Controlling 8bit Coding, Conversion
@comment  node-name,  next,  previous,  up
@subsection Unique Decoding
@cindex Unique Decoding
@cindex Restricted Decoding
@cindex Unique @TeX{} macro

Token languages might define more than one token representing the same
character.  When decoding and encoding these tokens, they will be
@dfn{normalized} to one form, the @dfn{canonical representation}.  E.g.,
with language @code{tex}, visiting a file with tokens @code{\neq} and
@code{\ne} converts both tokens to character @code{lessequal}, saving
the buffer stores the character as token @code{\neq} in both
occurrences.

It can also happen that a file contains both a 8bit character and a
token which would be converted to exactly that character.  When saving
the file, both characters are either not encoded, or both are encoded to
the same token.

Normally, this is no problem.  But if you redefine standard @TeX{}
macros, it certainly could be the case (@pxref{TeX Macro Problems})!
For this reason, package X-Symbol provides the following buffer-local
variable:

@vtable @code
@item x-symbol-unique
Whether to limit the decoding in such a way that no normalization will
happen.  That means: only decode canonical tokens, and, if
@code{x-symbol-8bits} is non-@code{nil} (@pxref{Controlling 8bit
Coding}), do not decode tokens which would be decoded to 8bit characters
(according to the coding in your file, see @ref{File Coding}).

You can set this variable in the ``local variables list'' near the end
of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}),
e.g., together with a setting for @code{x-symbol-8bits}:

@example
%% Local Variables:
%% x-symbol-8bits: t
%% x-symbol-unique: t
%% End:
@end example
@end vtable

If the variable is not already buffer-local, a reasonable value is
deduced when turning on X-Symbol (@pxref{Minor Mode}): it will be set to
@code{t} if X-Symbol mode is not automatically turned on.

If the file encoding is invalid (@pxref{File Coding}) and
@code{x-symbol-8bits} is non-@code{nil} (@pxref{Controlling 8bit
Coding}), X-Symbol always uses unique decoding (@pxref{Unique
Decoding}).


@node Conversion Commands, Copy with Conversion, Unique Decoding, Conversion
@comment  node-name,  next,  previous,  up
@subsection Conversion Commands
@cindex Conversion Commands
@cindex Automatic Conversion
@cindex Interactive Conversion
@cindex Explicit Conversion

First the good news: most of the time, the necessary conversions are
performed automatically when you would expect them to be performed:

@itemize @bullet
@item
Turning X-Symbol minor mode (@pxref{Minor Mode}) on/off also performs
decoding/encoding.

@item
Saving a buffer where X-Symbol is enabled will encode the characters to
tokens in the file (of course, you keep to have the characters in the
buffer).

@item
Inserting a file into a buffer where X-Symbol is enabled will decode the
tokens in the inserted region.
@end itemize

Nevertheless, you might want to perform the conversions explicitly in
some situations by using one of the following commands (also to be found
in the menu):

@table @kbd
@item M-x x-symbol-decode-recode
@findex x-symbol-decode-recode
Recode all characters (if necessary) and decode all tokens to
characters.

@item M-x x-symbol-decode
@findex x-symbol-decode
Decode all tokens to characters, do not recode characters.

@item M-x x-symbol-encode-recode
@findex x-symbol-encode-recode
Encode all characters in buffer to tokens or recode them.

@item M-x x-symbol-encode
@findex x-symbol-encode
Encode all characters in buffer to tokens.  No recoding will be
performed since 8bit characters will always be encoded if the file
coding is different to the default coding, since @code{x-symbol-8bits}
is relative to the file coding, see @ref{Controlling 8bit Coding}.
@end table

All commands work on the region if it is active, or the (narrowed part
of the) buffer if no region is active.

If the file coding is the same as the default coding, the variants with
and without recoding (@pxref{File Coding}) do the same.  The variants
with recodings are the ones used when doing the conversion
automatically.  The variants without recodings are the ones used when
using the special Copy & Paste commands presented in the next
subsection.


@node Copy with Conversion, Char Aliases, Conversion Commands, Conversion
@comment  node-name,  next,  previous,  up
@subsection Copy & Paste with Conversion
@cindex Copy and Conversion
@cindex Copy Encoded
@cindex Paste and Conversion
@cindex Paste Decoded
@cindex Yank Decoded

You probably use X-Symbol, because you want to produce some
non-@sc{ascii} characters in your final document, but you are not really
interested what kind of token you would need to write.  (After all, you do
not use a hex editor to produce documents using some non-@sc{ascii}
encoding in the file, since you are not interested in the byte sequence
of individual characters.)

Consequently, all editing operations really work on characters, not on
the corresponding tokens for the token language of the current buffer.
This includes copying and pasting: if you copy the character
@code{plusminus} from a LaTeX buffer to a HTML buffer, you really copy
that character and not the three characters of the TeX macro @code{\pm}.

If you copy text to a buffer where X-Symbol is not enabled, like a mail
buffer, that is probably not what you want.  Similarly, you would
probably like to see the X-Symbol characters for tokens in a text which
you have copied from such a buffer.  Therefore, X-Symbol provides the
following commands (also to be found in the menu):

@table @kbd
@item M-x x-symbol-copy-region-encoded
@findex x-symbol-copy-region-encoded
@vindex kill-ring
Save the region in the @code{kill-ring} with all X-Symbol characters
encoded like by @kbd{M-x x-symbol-encode}, i.e., without recoding.

@item M-x x-symbol-yank-decoded
@findex x-symbol-yank-decoded
Reinsert the last text in the @code{kill-ring} and decode the inserted
text like @kbd{M-x x-symbol-decode}, i.e., without recoding.
@end table

You could get the same result with the usual copy & paste commands and
the conversion commands from the previous section (@pxref{Conversion
Commands}), but this would clutter the undo information of the current
buffer and would require an additional undo operation for the copy.


@node Char Aliases,  , Copy with Conversion, Conversion
@comment  node-name,  next,  previous,  up
@subsection Character Aliases
@cindex Char Aliases
@cindex Character Aliases
@cindex Aliases of Characters
@cindex Latin Character Aliases
@cindex Remapping Characters

A @dfn{character alias} or @dfn{char alias} is a character which is also
a character in a font with another registry, e.g., @code{adiaeresis} is
defined in all supported Latin fonts.  Emacs distinguish between these
five characters.  In package X-Symbol, one of them, with
@code{x-symbol-default-coding} (@pxref{Default Coding} if possible, is
supported by the input methods, the other ones are char aliases to the
supported one.

The reason is that it would be confusing for the user to choose among
different @code{adiaeresis}es and that there are neither different
@code{adiaeresis}es in Unicode nor in the token representations of
languages @code{tex} and @code{sgml}.

8bit characters in files with a file coding @code{x-symbol-coding} other
than @code{x-symbol-default-coding} are converted to the ``normal''
form.  E.g., if you have a Latin-1 font by default, the
@code{adiaeresis} in a Latin-2 encoded file is a Latin-1
@code{adiaeresis} in the buffer.  When saving the buffer, its is again
the right 8bit character in the Latin-2 encoded file.

Thus, in normal cases, buffers do not have char aliases.  In Emacs with
Mule support, this is only possible if you copy characters from buffers
with characters considered as char aliases by package X-Symbol, e.g.,
from the Mule file @file{european.el}.  In XEmacs without Mule support,
this is only possible if you use commands like @kbd{C-q 2 3 4}.

If you have char aliases in the current buffer, you might want to use
(it is not really necessary, just when searching for characters):

@table @kbd
@item M-x x-symbol-unalias
@findex x-symbol-unalias
Resolve all character aliases in buffer.  If the region is active, only
resolve char aliases in the region.
@end table

A single char alias before point can be resolved by command
@code{x-symbol-modify-key} and @code{x-symbol-rotate-key}, see
@ref{Input Method Context}.

@pindex latin-unity
The XEmacs package @code{latin-unity} provides a command to ``remap''
characters to one character set (if possible).  X-Symbol's unaliasing
can be seen as remap operations to a fixed sequence of character sets.

@c ===========================================================================

@node Minor Mode, Poor Mans Mule, Conversion, Concepts
@comment  node-name,  next,  previous,  up
@section Minor Mode
@cindex Minor Mode
@cindex Mode
@cindex X-Symbol Mode

X-Symbol is a minor mode (@pxref{Minor
Modes,,,@value{emacs},@value{emacsman}}) which enables the features
mentioned in this manual:

@itemize @bullet
@item
X-Symbol mode is required to do the conversions.  Turning the minor mode
on/off also includes decoding/encoding (@pxref{Conversion Commands}).

@item
X-Symbol mode provides the minor mode menu which includes: various
commands, commands to insert characters (@pxref{Input Method Menu}), and
entries to change some global and buffer-local variables mentioned in
this manual.

@item
X-Symbol mode is required for most input methods (@pxref{Input Methods})
and other features (@pxref{Features}).
@end itemize

With the default installation, X-Symbol mode is automatically turned on
when it is appropriate to do so (see below for details).  You can
control it for individually by the following command:

@table @kbd
@item M-x x-symbol-mode
@findex x-symbol-mode
@vindex x-symbol-mode
Toggle X-Symbol mode.  If provided with a prefix argument, turn X-Symbol
mode on if the numeric value of the argument is positive, else turn it
off.  If no token language can be deduced, ask for a token language; if
provided with a non-numeric prefix argument (@kbd{C-u M-x
x-symbol-mode}), always ask.

By default, X-Symbol mode is disabled in special major-modes visiting a
file, e.g., @code{vm-mode} (@pxref{FAQ News and Mail}).  Use a prefix
argument to be asked whether to turn in on anyway.
@end table

Turning X-Symbol mode on requires that you have a valid token language
for the current buffer.  Since turning X-Symbol mode on also decodes
tokens, it is also useful to set the variables which control the
conversion (@pxref{Conversion}).

Since people usually do not want to write some Emacs Lisp functions to
do some customizations, X-Symbol provides the following variables which
induce X-Symbol to set the necessary buffer-local variables when
X-Symbol is turned on:

@vtable @code
@item x-symbol-auto-style-alist
You can use the major mode and/or the name of the buffer or visited
file, and specific functions to set the following variables (if not
already buffer-local):

@itemize @minus
@item
@code{x-symbol-token-language} (@pxref{Token Language}), indicated in
the modeline, e.g. @samp{tex},
@item
@code{x-symbol-mode}, i.e., whether it is appropriate to turn on
X-Symbol mode automatically,
@item
@code{x-symbol-coding} (@pxref{File Coding}), indicated in the modeline
if different from the default coding, e.g. @samp{-l2} for Latin-2,
@item
@code{x-symbol-8bits} (@pxref{Controlling 8bit Coding}), indicated in
the modeline by @samp{8},
@item
@code{x-symbol-unique} (@pxref{Unique Decoding}), indicated in
the modeline by @samp{*},
@item
@code{x-symbol-subscripts} (@pxref{Super and Subscripts}), indicated in
the modeline by @samp{s},
@item
@code{x-symbol-image} (@pxref{Images}), indicated in the modeline by
@samp{i},
@end itemize

@item x-symbol-@var{lang}-modes
Major modes which use token language @var{lang} by default.
@xref{Supported Languages}.  The languages are checked in registration
order (the order shown in the language selection submenus).

@item x-symbol-@var{lang}-auto-style
Default values for the above mentioned variables @code{x-symbol-mode},
@code{x-symbol-coding}, @code{x-symbol-8bits}, @code{x-symbol-unique},
@code{x-symbol-subscripts}, and @code{x-symbol-image} if not already
buffer-local.

@item x-symbol-auto-mode-suffixes
Regular expression matching file suffixes to be ignored when checking
file names for the derivation above, e.g., extension @file{.orig}.

@item x-symbol-modeline-state-list
This variable controls the modeline appearance just mentioned.


The menu might also include individual entries for a token
language (@pxref{TeX Macro Basics}):

@item x-symbol-@var{lang}-extra-menu-items
Extra menu items for each token language @var{lang} (@pxref{TeX Macro
Basics}).
@end vtable

@c ====================================================================

@node Poor Mans Mule, Role of font-lock, Minor Mode, Concepts
@comment  node-name,  next,  previous,  up
@section Poor Man's Mule: Running Under XEmacs/no-Mule
@cindex Poor Man's Mule
@cindex No Mule
@cindex XEmacs without Mule

Using XEmacs/no-Mule normally means that you are restricted to use not
more than 256 different characters in your documents.

Package X-Symbol provides a lot more characters which can also be used
with XEmacs/no-Mule.  Internally, all X-Symbol characters except the
ones of your default font (@pxref{Default Coding}) are represented by
two characters, see @ref{Char Representation}.

This can lead to a lot of problems, which are resolved by the following
methods (some annoyances remain, @pxref{Nomule Problems}) when X-Symbol
mode is turned on (@pxref{Minor Mode}):

@itemize @bullet
@item
After each editing command, i.e., point movement, deletion of text and
insertion of text, package X-Symbol checks whether just one of the two
internal characters of an X-Symbol character has been affected.

@item
Package @code{font-lock} is used to display these two-character
sequences with the correct fonts.  The potential problem lies in the
set-up of the corresponding font-lock keywords, see @ref{Role of
font-lock}.

@ftable @code
@item x-symbol-nomule-fontify-cstrings
Alternatively to enabling @code{font-lock}, you can run this functions
in buffers having the special two-character sequences.  With the default
installation, this function is run in the selection buffers of package
@code{reftex}.
@end ftable
@end itemize

@c ====================================================================

@node Role of font-lock, Char Group, Poor Mans Mule, Concepts
@comment  node-name,  next,  previous,  up
@section The Role of @code{font-lock}
@cindex Role of @code{font-lock}
@cindex @code{font-lock} Use
@cindex Special Fonts

Package X-Symbol uses package @code{font-lock} to display super- and
subscripts (@pxref{Super and Subscripts}) and to display its special
characters under XEmacs/no-Mule (@pxref{Poor Mans Mule}).  Thus, you
should enable @code{font-lock} in buffers where you want to use X-Symbol
(it is by default).  @xref{Syntax Hiliting Packages}.

When X-Symbol mode is turned on, it automatically adds the necessary
font-lock keywords to the buffer-local value of
@code{font-lock-keywords} and all font-lock keywords which are commonly
used with the current token language.

Setting all font-lock keywords is important since @code{font-lock} might
not yet been turned on or since you might want to change
@code{font-lock}s decoration of the current buffer after X-Symbol has
been turned on.

Please note that switching the mode by typing @kbd{M-x latex-mode}
@emph{does not set} the La@TeX{}'s font-lock keywords!  They are set at
the end of @kbd{C-x C-f}.  If you switch the mode, turn on
@code{font-lock} by yourself.

Independently from package X-Symbol, the following command might be
useful in some situations:

@table @kbd
@item M-x x-symbol-fontify
@findex x-symbol-fontify
Refontify buffer.
@end table

@c ====================================================================

@node Char Group,  , Role of font-lock, Concepts
@comment  node-name,  next,  previous,  up
@section Character Group and Token Classes
@cindex Character Group
@cindex Group of Characters
@cindex Similar Characters
@cindex Category of Character
@cindex Syntax of Character
@cindex Token Classes
@cindex Classes of Tokens
@cindex Coloring Scheme

Each X-Symbol character belongs to a @dfn{character group}, e.g.,
@code{natnums} belongs to @code{setsymbol}.  A character group should
consists of similar characters where ``similar'' means similar meaning,
not similar appearance.  Two characters which have nearly the same
appearance, should be in the same group, though.  The group determines:

@itemize @bullet
@item
The Grid and submenu header under which the character can be found
(@pxref{Input Method Grid}, @ref{Input Method Menu}).

@item
The default bindings of characters (@pxref{Input Method Keyboard}) of
some groups.

@item
Whether to show the context info for a character (@pxref{Info}).

@item
The default @sc{ascii} representation of a character (@pxref{Ascii
Representation}).

@item
When using Emacs/XEmacs with Mule support, the syntax of a character
(@pxref{Syntax,,,@value{emacs},@value{emacsman}}).
@end itemize

The character group is independent from any token language, but is
probably somewhat related to some of its @dfn{token classes}.  For each
token language, each character is assigned to a list of token classes,
which can be used for the following:

@itemize @bullet
@item
Information in the echo area (@pxref{Info}), it could inform users to
include a specific La@TeX{} package when they want to use that character
in the document.

@item
Using a @dfn{coloring scheme} when displaying the characters in the echo
area (@pxref{Info}) or the Grid of characters (@pxref{Input Method
Grid}), useful for characters which can just be used in a specific
context, like @TeX{}'s math-mode characters.

@item
Restricting the ``electricity'' of input method Electric (@pxref{Input
Method Electric}), useful to disable this input methods for @TeX{}'s
math-mode characters if we are in text-mode.
@end itemize

The token classes for individual token languages are explained in the
corresponding sections of @ref{Supported Languages}:

@vtable @code
@item x-symbol-@var{lang}-header-groups-alist
The Grid and Menu headers for each token language @var{lang}.

@item x-symbol-@var{lang}-class-alist
Strings for the character info in the echo area for each token language
@var{lang}.

@item x-symbol-@var{lang}-class-face-alist
The coloring scheme for each token language @var{lang}.
@end vtable

@c ===========================================================================

@node Input Methods, Features, Concepts, Top
@comment  node-name,  next,  previous,  up
@chapter X-Symbol's Input Methods
@cindex Input Methods
@cindex Character Insertion

An X-Symbol @dfn{input method} is a way, provided by package X-Symbol,
to insert a X-Symbol character (not in the sense of Mule's ``input
methods'').  For a short overview with screenshots, see the
@uref{@value{url}/details.html,web pages of X-Symbol}.

Input methods Token and Electric change the normal way to insert
characters a bit.  Therefore, they require X-Symbol mode to be turned on
and can be turned off explicitly.  The other input methods are provided
with additional commands and key prefixes, they can also be used in
buffers where X-Symbol mode is turned off.

With Auc@TeX{}, Version 9.8a or higher, its math mode commands also
inserts X-Symbol characters
(@pxref{Mathematics,,,@value{auctex},@value{auctexman}}).

@menu
* Introducing Input Methods::   Common behavior of all input methods.
* Input Method Token::          Replace token by character.
* Input Method Read Token::     Minibuffer input with completion.
* Input Method Menu::           Select a menu item.
* Input Method Grid::           Choose highlighted character.
* Input Method Keyboard::       Compose a key sequence.
* Input Method Context::        Replace character sequence.
* Input Method Electric::       Automatically replace character sequence.
* Input Method Quail::          A Mule input method "x-symbol".
* Customizing Input Method::    How to customize the input methods.
@end menu

@c ===========================================================================

@node Introducing Input Methods, Input Method Token, Input Methods, Input Methods
@comment  node-name,  next,  previous,  up
@section Common Behavior of All Input Methods
@cindex Input Methods, General
@cindex Input Methods, Common
@cindex Input Methods, Standard
@cindex Valid Character
@cindex Allowed Character
@cindex Key Prefix
@cindex Prefix Argument
@cindex Prefix Key
@cindex Defined Character
@cindex Compose Key

Input methods normally just inserts @dfn{valid characters} which are
those characters which have a useful representation in the file:

@vtable @code
@item x-symbol-valid-charsym-function
When X-Symbol is turned off, a character is valid if it is an 8bit
character according to the value of @code{x-symbol-default-coding}.

When X-Symbol is turned on, a character is valid if the characters could
be encoded to a token in language @code{x-symbol-language} (@pxref{Token
Language}).
@end vtable

If a buffer is read-only (@pxref{Misc
Buffer,,,@value{emacs},@value{emacsman}}), most input methods push the
character to insert onto the kill ring instead.  Typing @kbd{C-y} lets
you then insert the character
(@pxref{Yanking,,,@value{emacs},@value{emacsman}}).

The input methods Keyboard, Menu and Grid (the character selection with
@kbd{@key{button2}}) have the same interpretation of the prefix
argument:

@itemize @bullet
@item
With prefix argument @samp{0}, do not insert anything, just barf, if the
character is not valid.

@item
With a positive prefix argument, insert a character that many times.
Barf, if the character is not valid.

@item
With a negative prefix argument, insert a character as many times as
specified by the absolute value of the prefix argument.  A character is
also inserted if it is not valid.

@item
With one or more @kbd{C-u}s with no digits, insert the token of a
language to choose, including ``x-symbol charsym'' (@pxref{Pseudo
Language}).
@end itemize

Many input commands of package X-Symbol uses the same key prefix in its
default binding:

@vtable @code
@item x-symbol-compose-key
@kindex C-=
@kindex @key{multi-key}
By default, @kbd{C-=} is used as the key prefix.  Under XEmacs/no-Mule,
you might want to use @kbd{@key{multi-key}} instead:

@lisp
(unless (featurep 'mule) (setq x-symbol-compose-key '(multi-key)))
@end lisp

@item x-symbol-auto-key-autoload
Set this to @code{nil}, if you do not want that pressing @kbd{C-=}
automatically initializes the input methods.
@end vtable

@c ===========================================================================

@node Input Method Token, Input Method Read Token, Introducing Input Methods, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Token: Replace Token by Character
@cindex Input Method Token
@cindex Token, Input Method
@cindex Replace Token
@cindex Abbrev, Token           @c pre-2.2

If X-Symbol mode is on, input method @dfn{Token} automatically replaces
the token by the corresponding character when inserting the next
character following the token (in some token languages you need the next
character to decide whether the token is completed) if it is valid.

The token will be replaced only if the next character has been inserted
without prefix argument or with prefix argument 0 (@kbd{C-u 0}), the
latter will therefore just induce the replacement.

Please note that the token is really replaced by the characters, it is
not just @code{font-lock} which highlights the token to look like a
character.

You might want to press @kbd{C-/} or @kbd{C-x u} to undo the
replacement.  Input method Token requires X-Symbol mode to be enabled,
it can be disabled (and re-enabled) by setting the following variable:

@vtable @code
@item x-symbol-token-input
A boolean which can also be changed via the X-Symbol menu.
@end vtable

Individual token language might slightly change the way input method
Token works exactly; from the predefined language, it is just @code{tex}
(@pxref{TeX Macro}).

@c ===========================================================================

@node Input Method Read Token, Input Method Menu, Input Method Token, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Read Token: Minibuffer Completion
@cindex Input Method Read Token
@cindex Read Token, Input Method
@cindex Minibuffer Completion, Token

You can insert a character by reading the corresponding token in the
minibuffer.  You are offered completion over the known tokens
(@pxref{Completion,,,@value{emacs},@value{emacsman}}).

@table @kbd
@item M-x x-symbol-read-token-direct
@itemx C-= @key{TAB}
@findex x-symbol-read-token-direct
@kindex C-= @key{TAB}
Insert character by selecting a token in the current token language
(even if X-Symbol mode is turned off) or an ``x-symbol charsym''
(@pxref{Pseudo Language}).

@item M-x x-symbol-read-token
@itemx C-= @key{RET}
@findex x-symbol-read-token
@kindex C-= @key{RET}
Insert character by first selecting the token language and then a token
in that language.
@end table

Input method Read Token also works if X-Symbol mode is not enabled.  It
uses the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Menu, Input Method Grid, Input Method Read Token, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Menu: Select a Menu Item
@cindex Input Method Menu
@cindex Menu, Input Method

If X-Symbol mode is turned on, a @dfn{Menu} @code{X-Symbol} appears in
the menubar (@pxref{Minor Mode}).  It also appears over non-highlighted
parts in the Grid and the Key Completions buffer (@pxref{Input Method
Grid}).  The menu allows to change buffer-local and global variables
(some directly, some via package @code{custom}).  It has a submenu with
the most interesting commands of package X-Symbol.

The menu has submenus with commands to insert X-Symbol characters.  The
submenu headers are the same as the headers in the Grid, see
@ref{Char Group}.  The appearance of the menu can be customized:

@vtable @code
@item x-symbol-local-menu
With a valid token language, the X-Symbol menu only contains insertion
commands for valid characters.  The entries are mentioned and sorted
according to the token.  Otherwise, the X-Symbol menu contains all
characters, the entries are mentioned according to their charsym name.

@item x-symbol-menu-max-items
The submenus do not contain more than 30 insertion commands for X-Symbol
characters.  A submenu is split if necessarily.
@end vtable

Input method Menu also works if X-Symbol mode is not enabled.  It uses
the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Grid, Input Method Keyboard, Input Method Menu, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Grid: Choose Highlighted Character
@cindex Input Method Grid
@cindex Grid, Input Method
@cindex Table of Characters
@cindex Highlighted Character

Probably the easiest way to insert a character is by using a @dfn{Grid}
of characters:

@table @kbd
@item M-x x-symbol-grid
@itemx C-= C-=
@findex x-symbol-grid
@kindex C-= C-=
Pops up a buffer displaying X-Symbol characters in a grid like fashion.
You can select a character with the mouse or @kbd{@key{RET}}, see below.
@end table

In the Grid buffer and the buffer with the possible completions for an
X-Symbol key sequence (@pxref{Input Method Keyboard}), the following
commands are used if the mouse pointer is over an highlighted character.

@table @kbd
@item @key{button2}
@itemx @key{RET}
@itemx @key{SPC}
@c @itemx x-symbol-list-selected
@kindex @key{button2}
@kindex @key{RET}
@kindex @key{SPC}
@c @findex x-symbol-list-selected
Insert highlighted character (or character under point, respectively)
into the buffer of @code{point} if @code{point} is not in the same
buffer as the highlighted character.  Otherwise, insert the character
into the reference buffer, i.e., the buffer where you have invoked the
grid or the key completions from.  (The reference to the buffer is
erased when an X-Symbol character is inserted into any buffer.)

@item @key{button3}
@kindex @key{button3}
Pops up a highlight menu where you can select to insert the token of
various token languages instead the character itself.  In order not to
load and initialize all additional token language you have not yet used,
the menu offers to do so explicitly for supported (registered) token
languages (@pxref{Token Language}).
@end table

Over all non-highlighted parts, the following commands are used:

@table @kbd
@item @key{button2}
@kindex @key{button2}
@c @findex x-symbol-list-selected
Scroll Grid or Key Completions buffer down in upper half of the window
and scroll up in the lower half of the window.

@item @key{button3}
@kindex @key{button3}
Pops up the X-Symbol menu, see @ref{Input Method Menu}).
@end table

When using the keyboard to select a character, the following command
could be useful:

@table @kbd
@item M-x x-symbol-list-info
@itemx ?
@itemx h
@itemx i
@findex x-symbol-list-info
@kindex ?
@kindex h
@kindex i
Display info for character under point in echo area.

@item M-x x-symbol-list-bury
@itemx q
@findex x-symbol-list-bury
@kindex q
Bury list buffer while trying to use the old window configuration.
@end table

You can control the grid by the following variables:

@vtable @code
@item x-symbol-local-grid
With a valid token language, the Grid only contains insertion commands
for valid characters and might use a coloring scheme.  Otherwise, it
contains all characters.

@item x-symbol-temp-grid
Inserting an X-Symbol character does not restore the window
configuration current before the invocation of the Grid.

@item x-symbol-grid-reuse
Use old Grid when invoking command @code{x-symbol-grid}, if this is
reasonably to do.  If @code{x-symbol-grid} is called with a prefix
argument, always create new Grid.

@item x-symbol-grid-ignore-charsyms
The Grid does not contain @code{nobreakspace}.

@item x-symbol-grid-tab-width
The tab width in the Grid buffer should correspond the font in
@code{x-symbol-heading-face} which is also used as the default font in
the Grid buffer.

@item x-symbol-heading-strut-glyph
Use larger interline spacing if a line in the Grid starts with a header.
@end vtable

The headers in the Grid are the same as the submenu headers, see
@ref{Char Group}.  Similar looking characters for one headers are
grouped together.  @xref{Input Method Context}.

Input method Grid also works if X-Symbol mode is not enabled.  It uses
the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Keyboard, Input Method Context, Input Method Grid, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Keyboard: Compose Key Sequence
@cindex Input Method Keyboard
@cindex Keyboard, Input Method

Key sequences starting with @kbd{C-=} (@pxref{Introducing Input
Methods}) are used to insert X-Symbol characters, e.g., @kbd{C-= ~ >}
inserts @code{leadsto}.  The Ascii sequence of the keys after @kbd{C-=}
look similar to the character which you are going to insert.  It is the
same as the sequence which is replaced by input method Context, see
@ref{Input Method Context}.

If many characters are represented by the same Ascii sequence, the
binding is extended by @samp{1}, @samp{2} and so on.  If you do not know
how to continue your key sequence, the following commands might be
useful:

@table @kbd
@item M-x x-symbol-help
@itemx C-= @var{zero-or-more-keys} @key{help}
@itemx C-= @var{zero-or-more-keys} C-h
@findex x-symbol-help
@kindex C-= @key{help}
@kindex C-= C-h
@kindex @key{help}
@kindex C-h
Pops up a buffer displaying possible completions for the key sequence
@kbd{C-= @var{zero-or-more-keys}}.  You do not have to type the key
sequence again, i.e., @kbd{C-= @var{zero-or-more-keys}} is also used for
the next input.

@item C-= @var{zero-or-more-keys} @key{button1}
@itemx C-= @var{zero-or-more-keys} @key{button2}
@itemx C-= @var{zero-or-more-keys} @key{button3}
@kindex @key{button1}
@kindex @key{button2}
@kindex @key{button3}
Use the normal bindings of @kbd{@key{button1}},  @kbd{@key{button2}} or
@kbd{@key{button3}}, respectively (@pxref{Input Method Grid}).  The key sequence
is not used for the next input.

@item C-= @var{zero-or-more-keys} M-@key{prior}
@itemx C-= @var{zero-or-more-keys} M-@key{next}
@itemx C-= @var{zero-or-more-keys} M-@key{home}
@itemx C-= @var{zero-or-more-keys} M-@key{end}
@kindex M-@key{prior}
@kindex M-@key{next}
@kindex M-@key{home}
@kindex M-@key{end}
Execute the commands @code{scroll-other-window-down},
@code{scroll-other-window}, @code{beginning-of-buffer-other-window} or
@code{end-of-buffer-other-window}, respectively.  You do not have to
type the key sequence again, i.e., @kbd{C-= @var{zero-or-more-keys}} is
also used for the next input.
@end table

@vtable @code
@item x-symbol-temp-help
Inserting an X-Symbol character restores the window configuration
current before the invocation of the Grid.

@item x-symbol-map-default-keys-alist
Defines the bindings mentioned above.
@end vtable

Input method Keyboard also works if X-Symbol mode is not enabled.  It
uses the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Context, Input Method Electric, Input Method Keyboard, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Context: Replace Char Sequence
@cindex Context, Input Method
@cindex Input Method Context
@cindex Character Sequence Input
@cindex Ascii Sequence Input
@cindex Modify Chain
@cindex Rotate Chain
@cindex Greek Input

The idea of the input method @dfn{Context} is to replace a sequence of
characters by a character which looks similar to the whole sequence.  If
the sequence consists only of Ascii characters, it is also used for the
key bindings, see @ref{Input Method Keyboard}.

There will be some info in the echo area that the character sequence
before point can be replace via input method Context.  The following
commands are provided:

@table @kbd
@item M-x x-symbol-modify-key
@itemx C-,
@itemx C-= @key{left}
@itemx C-= @key{right}
@findex x-symbol-modify-key
@kindex C-,
@kindex C-= @key{left}
@kindex C-= @key{right}
If character before point is an X-Symbol character, ``modify'' it to an
alternative character (if you do it often enough, you are back at your
first character).  Otherwise replace sequence of characters by a
character which looks similar to the whole sequence.

@item M-x x-symbol-rotate-key
@itemx C-.
@itemx C-= @key{up}
@itemx C-= @key{down}
@findex x-symbol-rotate-key
@kindex C-.
@kindex C-= @key{up}
@kindex C-= @key{down}
If character before point is an X-Symbol character, ``rotate'' its
``direction'' (or change uppercase/lowercase).
@end table

Both commands can also be used to resolve a character alias before
point, see @ref{Char Aliases}.  If the region is active, restrict
replacement to use that region since the input method Context only
considers the longest sequence of characters with a replacement.

Input method Context can be customized by changing the following
variables:

@vtable @code
@item x-symbol-rotate-prefix-alist
If you provide a prefix argument to command @code{x-symbol-rotate-key},
you can specify the direction you want to have: it is according to
numerical keypads, e.g., with prefix argument @samp{7} you specify the
direction ``north-west''.

@item x-symbol-rotate-suffix-char
Command @code{x-symbol-rotate-key} is also used to ``Greekify'' the
previous character: typing @kbd{a C-.} is shorter than @kbd{a # C-,}.

@item x-symbol-context-ignore
Constrains whether a context/charsym can be replaced.  No constraints by
default.

@item x-symbol-context-init-ignore
Contexts starting with a space cannot be replaced.  This variable must
be set before X-Symbol has been initialized.
@end vtable

@c ===========================================================================

@node Input Method Electric, Input Method Quail, Input Method Context, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Electric: Automatic Context
@cindex Input Method Electric
@cindex Electric, Input Method
@cindex Aggressive Context      @c 2.6
@cindex Automatic Context

The idea of input method @dfn{Electric} is to have the input method
Context (@pxref{Input Method Context}) do its replacement automatically.
X-Symbol automatically replaces some character sequences of input method
Context by the X-Symbol character as soon as the last character in the
sequence of the sequence has been pressed.

Input method Electric has nothing to do with the display of
super-/subscripts (@pxref{Super and Subscripts}).

You might want to press @kbd{C-/} or @kbd{C-x u} to undo the
replacement.  Input method Electric requires X-Symbol mode to be
enabled, it can be disabled (and re-enabled) by setting the following
variable:

@vtable @code
@item x-symbol-electric-input
A boolean which can also be changed via the X-Symbol menu.
@end vtable

To make input method Electric useful and not annoying, several
conditions must be met for X-Symbol to do the auto-replacement:

@itemize @bullet
@item
Not all contexts will be replaced automatically.  E.g., while input
method Context allows both pre- and postfixes for accented characters,
@kbd{:} and @kbd{'} only act as prefixes, and @kbd{`} and @kbd{~} only
as postfixes for input method Electric, since these are the combinations
where those characters are quite likely not used literally.

@item
The character must be valid in the current token language, see
@ref{Introducing Input Methods}.

@item
All characters of the context have been typed without any other command
in between, e.g., @kbd{- >} inserts @code{arrowright}, "- @key{left}
@key{right} > simply inserts @samp{->}.

@item
No prefix argument has been used for any character in the context.

@item
The electric context must not be a suffix of a longer valid context for
another character.  E.g., @kbd{' ' o} does not insert
@samp{'@code{oacute}} because @samp{''o} is the context for
@code{ohungarumlaut} (which cannot be inserted by input method
Electric).

@item
It should be ``allowed'' to change the context to the character via
input method Context.

@item
Individual contexts/charsyms can be disabled by setting the following
variables:

@vtable @code
@item x-symbol-electric-ignore
The context should neither be @samp{'s} (this would be annoying when
writing English), nor include a space.  If you want to disable input
method Electric for all accented characters, use

@lisp
(setq x-symbol-electric-ignore
      "[ \t]\\|[A-Za-z][~`]\\|[:'][A-Za-z]")
@end lisp

@item x-symbol-@var{lang}-electric-ignore
Individual contexts/charsyms can be disabled for each token language
@var{lang}.
@end vtable
@end itemize

@c ===========================================================================

@node Input Method Quail, Customizing Input Method, Input Method Electric, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Quail: a Mule Input Method
@cindex Input Method Quail
@cindex Mule Input Method

Another way to insert a characters is by using the Emacs/Mule
multilingual text input method ``x-symbol'' (@pxref{Input
Methods,,,@value{emacs},@value{emacsman}})..

Again, the Ascii sequence used there is the same as the sequence which
is replaced by input method Context, see @ref{Input Method Context}.  A
one-letter key sequence is extended by @key{;}.

If input method Quail is selected for a buffer, input method Electric
(@pxref{Input Method Electric}) is disabled in that buffer.

@c TODO: more

@c ===========================================================================

@node Customizing Input Method,  , Input Method Quail, Input Methods
@comment  node-name,  next,  previous,  up
@section Customizing Input Methods
@cindex Customizing Method Internals
@cindex Input Methods Customization

You may safely define key bindings not using the @code{x-symbol-map}
(i.e., starting with @kbd{C-=}).  E.g., for @code{alpha} on @kbd{A-a} ,
use

@lisp
(global-set-key [(alt a)] 'x-symbol-INSERT-alpha)
@end lisp

Please note that the command @code{x-symbol-INSERT-alpha} is not defined
before the main file (@file{x-symbol}) in the package has been loaded
(if you really need it, function @code{autoload} is your friend).

Other possibilities to customize the input methods are by setting the
following variables:

@vtable @code
@item x-symbol-header-groups-alist
Defines the groups whose characters appear after that header in the Grid
and in submenus with that header.  @xref{Char Group}.  Extra variables
exists for the language dependent Grid and Menu.

@item x-symbol-group-input-alist
@itemx x-symbol-user-table
These are variables which are used to compute the input definitions.
While this kind of indirection might seem complicated to you (it is), it
actually ensures consistency across all input methods.  @xref{Defining
Input Methods}.

For example, if you prefer charsym @code{epsilon1} over @code{epsilon}
you might want to use:

@lisp
@group
(setq x-symbol-user-table
      '((epsilon1 t (greek1 "e" nil "epsilon") nil -3000)))
@end group
@end lisp

@item x-symbol-list-mode-hook
Additional functions to execute after setting up the Grid and Key
Completions buffer.

@item x-symbol-after-init-input-hook
You can change the input methods directly by functions in these hooks.
@end vtable

@c ===========================================================================

@node Features, Supported Languages, Input Methods, Top
@comment  node-name,  next,  previous,  up
@chapter Features of Package X-Symbol
@cindex Features of X-Symbol
@cindex Supported Features

Package X-Symbol not only provides input methods for X-Symbol
characters, it also provides more features which support an easy and
comfortable preparation of documents.

@menu
* Super and Subscripts::        Use special fonts for super-/subscripts.
* Images::                      Images after image insertion commands.
* Info::                        Display information in echo area.
* Ascii Representation::        Derive label from a buffer contents.
* Package Information::         Invoke info system, use WWW browser.
@end menu

@c ===========================================================================

@node Super and Subscripts, Images, Features, Features
@comment  node-name,  next,  previous,  up
@section Super- and Subscripts
@cindex Superscripts
@cindex Subscripts
@cindex Invisible, Revealing
@cindex Point, Invisible
@cindex Cursor, Invisible
@cindex Keywords for Subscripts

Package X-Symbol displays the characters inside super-/subscript
commands in a way to make them look like super-/subscripts.  It also
marks the super-/subscript command itself as invisible, so you don't see
it on the screen.  For example, the three characters @samp{a^2} in the
buffer are @emph{displayed} as an @samp{a} and a raised, smaller
@samp{2}---the @samp{^} is still in the buffer.

Therefore, the display of super- and subscripts has nothing to do with
Input Method Electric (@pxref{Input Method Electric}).

Do not confuse the special Latin characters @code{twosuperior},
@code{threesuperior}, @code{ordfeminine} and @code{masculine} with the
characters @samp{2}, @samp{3}, @samp{a} and @samp{o} when displayed as
superscripts.  You might notice that the characters look a bit
different, but to help you seeing the difference, X-Symbol will display
an info in the echo area (@pxref{Info}) for the special Latin
characters when point is before or after the character in question.

X-Symbol only displays the innermost super- and subscripts, since we
would need even more additional fonts otherwise.  It is also restricted
to display single-line super- and subscripts.

The display of super- and subscripts requires @code{font-lock} to be
enabled (@pxref{Role of font-lock}).

Super- and subscripts are by default enabled if the they are defined for
the token language and it would be appropriate to turn on X-Symbol
automatically for the current buffer (@pxref{Minor Mode}).  They can be
disabled (and re-enabled) by setting the following buffer-local
variable:

@vtable @code
@item x-symbol-subscripts
A boolean which can also be changed via the X-Symbol menu.
@end vtable

As mentioned before, X-Symbol marks the super-/subscript command itself
as invisible, except when point is directly before, inside or directly
after this command.  During the time where this this is the case,
X-Symbol makes the super-/subscript command reappear and highlights it
with pink.  This feature can be disabled (and re-enabled) by setting the
following variables:

@vtable @code
@item x-symbol-reveal-invisible
A boolean which can also be changed via the X-Symbol menu.

@item x-symbol-revealed-face
The face used for the super-/subscript command when revealed.

@item x-symbol-idle-delay
Time in seconds of idle time before revealing invisible characters.
@end vtable

Super-/subscript commands are @code{^}/@code{_} (@pxref{TeX Macro}) and
@code{<sup>}/@code{<sub>} (@pxref{SGML Entity}):

@c ===========================================================================

@node Images, Info, Super and Subscripts, Features
@comment  node-name,  next,  previous,  up
@section Images at the end of Image Insertion Commands
@cindex Images
@cindex Glyphs

@pindex convert
Package X-Symbol can display @dfn{images} at the end of image insertion
commands.  They show thumbnails (scaled-down version of the image) for
the included image files (using @code{convert}, @pxref{Installing Image
Converter}).  Using the middle mouse button invokes the image editor for
the image under the mouse pointer.

@menu
* Image Display::               When to display images.
* Image Conversion::            Producing a scaled-down image.
* Image Caching::               Speeding up the image processing.
* Special Images::              Signaling specific situations.
* Image Editor::                Editing the original image file.
@end menu


@node Image Display, Image Conversion, Images, Images
@comment  node-name,  next,  previous,  up
@subsection Display of Images
@cindex Image Display
@cindex Image Control
@cindex Image Commands
@cindex Controlling Images
@cindex Image Keywords
@cindex Keywords for Images

The display of images is by default enabled if the image commands are
defined for the token language and it would be appropriate to turn on
X-Symbol automatically for the current buffer (@pxref{Minor Mode}).  It
can be disabled (and re-enabled) by setting the following buffer-local
variable:

@vtable @code
@item x-symbol-image
A boolean which can also be changed via the X-Symbol menu.
@end vtable

Image commands are @code{\includegraphics} and others (@pxref{TeX
Macro}), and @code{<img>} (@pxref{SGML Entity}):

@vtable @code
@item x-symbol-@var{lang}-image-keywords
The keywords (image commands & arguments) for each token language
@var{lang}.
@end vtable

File names in the image commands must be interpreted correctly.  They
can be:

@itemize @minus
@item
@dfn{absolute}, start with @samp{/} or @samp{~},
@item
@dfn{explicitly relative}, start with @samp{./} or @samp{../},
@item
@dfn{implicitly relative}, assumed otherwise, e.g., @file{image.eps}, or
@item
special, like having some special URL prefix like @file{http:} or @file{ftp:}.
@end itemize

Relative file names can be relative to some @dfn{master directory}
(usually the current directory of the file) or to directories in some
@dfn{search path} (only used with token language @code{tex}):

@vtable @code
@item x-symbol-@var{lang}-master-directory
The master directory for each token language @var{lang}.

@item x-symbol-@var{lang}-image-searchpath
The image search path for each token language @var{lang}.  Defaults to
the current directory.

@item x-symbol-image-searchpath-follow-symlink
Directories in the search path ending with @file{//} (double slash) are
recursive: all subdirectories not starting with a dot are also included
in the search path.  If this variable has value @code{nil} (the
default), subdirectories which are symbolic links are not included.
@end vtable

For details, see the section of the individual token languages
(@pxref{Supported Languages}).


@node Image Conversion, Image Caching, Image Display, Images
@comment  node-name,  next,  previous,  up
@subsection Image Conversion
@cindex Image Conversion
@cindex Converting Images
@cindex Colormap
@cindex Image Cache File

The file mentioned inside the image insertion command is not used
directly to display the image after the command.  The image might be too
big, it might use too many colors or the image format might not be
supported by Emacs.  Therefore, it is converted to an @dfn{image cache
file}, see @ref{Image Caching}.

@vtable @code
@item x-symbol-image-max-width
The image is not wider than 120 points.

@item x-symbol-image-max-height
The image is not higher than 80 points.

@item x-symbol-image-convert-colormap
Colormap used in function @code{x-symbol-image-convert-colormap} below.
A colormap is a normal image whose colors are the only ones used for
producing other images.  The distribution of package X-Symbol includes
two colormaps: @file{etc/colormap138.xpm} and @file{etc/colormap66.xpm}.

@item x-symbol-image-colormap-allocation
Package X-Symbol allocates the colors of the colormap at start-up and
prevents them to be de-allocated.

@item x-symbol-image-converter
@pindex convert
Program @code{convert} from ImageMagick is used to convert the images
(@pxref{Installing Image Converter}).  Set this variable to @code{nil},
if you don't want to convert images.

The following variables controls the invocation of the program
@code{convert} from ImageMagick:

@vtable @code
@item x-symbol-image-convert-program
The name of the program @code{convert}, it is
@samp{C:\\ImageMagick\\convert} when running on Windows and
@samp{convert} otherwise.

@item x-symbol-image-convert-file-alist
Program @code{convert} needs to be told that @file{@var{file}.pstex} is
a Postscript file.
@end vtable

The following functions are possible values in
@code{x-symbol-image-converter}:

@ftable @code
@item x-symbol-image-start-convert-mono
Produces monochrome images.  Used if your device has less than 32
colors.

@item x-symbol-image-start-convert-truecolor
Produce images with original colors.  Used if your device has more than
767 colors.

@item x-symbol-image-start-convert-color
Produce images with maximal four colors (just four because different
images might use a different sets of colors).  Used otherwise without a
colormap.

@item x-symbol-image-start-convert-colormap
Produce image with colors from the colormap.  Used otherwise with a
colormap.

@vtable @code
@item x-symbol-image-convert-mono-regexp
Function @code{x-symbol-image-start-convert-colormap} just produces
monochrome images for temporary image cache files (@pxref{Image
Caching}) since @code{convert} is slower when using a colormap.
@end vtable
@end ftable
@end vtable


@node Image Caching, Special Images, Image Conversion, Images
@comment  node-name,  next,  previous,  up
@subsection Image Caching
@cindex Image Caching
@cindex Caching of Images
@cindex Glyph Caching
@cindex Memory Cache for Images
@cindex File Cache for Images

Editing would be extremely slow, if an image cache file would be
produced every time an image insertion command has been recognized.
Therefore, package X-Symbol uses the following techniques:

@itemize @bullet
@item
It uses an asynchronous process to create the image cache file.  You can
edit your file during the conversion.

@item
It uses a @dfn{file cache}: image cache file can be kept for future
Emacs sessions.

@item
It uses a @dfn{memory cache}: images from the most common file names are
cached in a buffer-local memory cache.  The cached is initialized when
parsing the whole buffer for image keywords.  Rescan the buffer if you
want to display the the images of new image files by using the following
command:

@table @kbd
@item M-x x-symbol-image-parse-buffer
@findex x-symbol-image-parse-buffer
Parse the buffer to recognize image insertion commands.  Usually, this
is done automatically.
@end table
@end itemize

File and memory caching can be controlled by the following variables:

@vtable @code
@item x-symbol-image-update-cache
The image cache is automatically updated if it does not exist yet or if it
is older than the corresponding image file.

@item x-symbol-image-cache-directories
Cache files for images in your home directory are stored in directory
@file{~/.images/}, e.g., image @file{~/d/img.eps}, is cached in
@file{~/.images/d/img.png}.

Images outside your home directory are just temporarily cached, or not
displayed at all if they cannot be stored in the memory cache.

You could also specify that the cache files uses a relative
subdirectory, e.g., that @file{~/d/img.eps} is cached in
@file{~/d/.img/img.eps} or that the image is not displayed at all.

@item x-symbol-image-temp-name
Temporary image files are stored in a temporary directory (@file{/tmp/})
having some unique name.  They are not supported on Emacs.

@item x-symbol-image-use-remote
Package X-Symbol only displays images which can be stored in the memory
cache.  With value @code{t}, it tries to find the image file during
editing (ignoring the search path for speed, though).  Editing lines
with image files not in the memory cache would be slow, since file
accesses are necessary for every command.
@end vtable

The memory cache only stored image file from the current directory or
some standard image directories like @file{figures/} (@pxref{TeX
Macro}), or @file{images/} or @file{pictures/} (@pxref{SGML Entity}).
Otherwise, the image file is considered similar to remote files:

@vtable @code
@item x-symbol-@var{lang}-image-cached-dirs
The directories with images which are stored in the memory cache.  Can
be separately defined for each token language @var{lang}.
@end vtable


@node Special Images, Image Editor, Image Caching, Images
@comment  node-name,  next,  previous,  up
@subsection Special Images for Specific Situations
@cindex Special Images
@cindex Images for Specific Situations
@cindex Glyph for Specific Situations

If package X-Symbol cannot display images representing the included
image files, it uses special images instead:

@itemize @bullet
@item
@dfn{Remote:} An Escher knot is displayed if the file is remote or if
the image cannot be cached in the memory cache, see @ref{Image Caching}.

@item
@dfn{Junk}: A recycle sign is displayed if there is no image converter
(@pxref{Image Conversion}), if it should not use a file cache or if the
file cache cannot be written.

@item
@dfn{Locked:} A terminal with a lock is displayed if the image cache file
cannot be read or written.

@item
@dfn{Design:} An ink pen is displayed if the image file does not exist.

@item
@dfn{Create:} An hour glass is displayed used during the creation of the
image cache file, an old image cache is used instead if it exists.

@item
@dfn{Broken:} A tombstone is displayed if the creation of the image
cache file has failed.
@end itemize

To customize the glyphs for the special images, use:

@vtable @code
@item x-symbol-image-data-directory
Directory of files for the special images.

@item x-symbol-image-special-glyphs
File names of special images and their image format.
@end vtable


@node Image Editor,  , Special Images, Images
@comment  node-name,  next,  previous,  up
@subsection Image Editor
@cindex Image Editor
@cindex Editing Image Files
@cindex Designing Images
@cindex Scale Factor, Images
@cindex Image Highlight Menu

If you move the mouse pointer to an image insertion command or its
image, it is highlighted.

@table @kbd
@item @key{button2}
@kindex @key{button2}
Start image editor for highlighted image.  If the image is searched in
the searchpath (@pxref{Image Caching}), edit first existing image file.
If no image exists, open a new file in the first directory of the
searchpath.

@item @key{button3}
@kindex @key{button3}
Pop up the @dfn{image highlight menu}.  You can rescan the buffer for
image insertion commands (@pxref{Image Display}).

It also displays all directories in the searchpath if the file name is
implicitly relative, or the current directory otherwise.  Selecting a
directory starts the image editor in that directory (relatively to that
directory if the file name has a directory part).

@item M-x x-symbol-image-editor
@findex x-symbol-image-editor
Start image editor.  Asks for the image file.
@end table

You can control which editor to use:

@vtable @code
@item x-symbol-image-editor-alist
@pindex display
@pindex xfig
Normally, program @code{display} is used to edit the highlighted image
file.  But for image names @file{@var{file}.eps}, @file{@var{file}.ps}
or @file{@var{file}.pstex}, program @code{xfig} is invoked with
@file{@var{file}.fig}.  It also uses a scale method, e.g., with
@file{img.80.eps}, we edit @file{img.fig} (which should be exported with
scale=80%).

@item x-symbol-image-scale-method
If a scale method is used for a file name and the file name without
extension ends with a dot and two digits, these three characters are
removed from the file name.

@item x-symbol-image-current-marker
Directories with an existing image for the specified file name are
marked with an @samp{*}.  The first of these represents the file which
is used when pressing @kbd{@key{button2}}.
@end vtable

@c ===========================================================================

@node Info, Ascii Representation, Images, Features
@comment  node-name,  next,  previous,  up
@section Info in Echo Area
@cindex Info in Echo Area
@cindex Echo Area Info
@cindex Character Info
@cindex Context Info
@cindex Minibuffer Info

The echo area (@pxref{Echo Area,,,@value{emacs},@value{emacsman}}) is
used by X-Symbol to give some information about the character around
point, and whether there is a context before point which can be replaced
by input method Context (@pxref{Input Method Context}).

It will be controlled by the following variables (also to be found in
the menu):

@vtable @code
@item x-symbol-character-info
A three-value variable which controls whether to display some info for
the character after or around point.  The info for the character after
point includes the character itself and the following infos:

@itemize @minus
@item
the token of the current language, eventually colored according to some
coloring scheme (@pxref{Char Group}),

@item
infos using the token classes (@pxref{Char Group}), which could inform
users to include a specific La@TeX{} package when they want to use that
character in the document,

@item
the codings in which the characters is considered to be a 8bit character
(@pxref{File Coding}), and

@item
the key bindings (@pxref{Input Method Keyboard}).
@end itemize

@item x-symbol-context-info
If X-Symbol mode is on and some conditions are met, display some info
for the character which would replace the context before point when
pressing @kbd{C-,} (@pxref{Input Method Context}).  It can be controlled
by the following variables:

@vtable @code
@item x-symbol-context-info-ignore
@findex x-symbol-default-context-info-ignore
The default value @code{x-symbol-default-context-info-ignore} makes the
following variables control whether to display the context info.

@item x-symbol-context-info-threshold
The context does not consist of a single character.

@item x-symbol-context-info-ignore-regexp
The context does not solely consist of letters.

@item x-symbol-context-info-ignore-groups
The context is not replaced by an accented character, see @ref{Char
Group}.
@end vtable

@item x-symbol-idle-delay
Time in seconds of idle time before showing the info.
@end vtable

@c ====================================================================

@node Ascii Representation, Package Information, Info, Features
@comment  node-name,  next,  previous,  up
@section Ascii Representation of Strings 
@cindex Ascii Representation
@cindex Representation of Characters
@cindex Label Creation

@pindex reftex
If you want to derive labels from a buffer contents (provided e.g., by
Emacs packages @code{reftex} or @code{bibtex}), you need a Ascii
representation of strings containing X-Symbol characters.  This is
provided by the following function:

@ftable @code
@item x-symbol-translate-to-ascii
Takes a string and returns a string only consisting of Ascii characters.

@vtable @code
@item x-symbol-charsym-ascii-alist
You might want to define the German way to Asciify accented characters
by:
@lisp
@group
(setq x-symbol-charsym-ascii-alist
      '((adiaeresis . "ae") (Adiaeresis . "Ae")
        (odiaeresis . "oe") (Odiaeresis . "Oe")
        (udiaeresis . "ue") (Udiaeresis . "Ue")))
@end group
@end lisp

@item x-symbol-charsym-ascii-groups
By default, ``Ascii''fying accented characters means removing the
accents.  Other characters have built-in Ascii representation, e.g,
@code{sigma1} has the Ascii representation @samp{sigma}.
@end vtable
@end ftable

@c ====================================================================

@node Package Information,  , Ascii Representation, Features
@comment  node-name,  next,  previous,  up
@section X-Symbol Package Information
@cindex Package Information
@cindex WWW Browsing
@cindex URL for X-Symbol

@table @kbd
@item M-x x-symbol-package-info
@findex x-symbol-package-info
Read documentation for package X-Symbol in the info system.

@item M-x x-symbol-package-web
@findex x-symbol-package-web
Ask a WWW browser to load the URL of package X-Symbol.

@item M-x x-symbol-package-bug
@findex x-symbol-package-bug
Use this command to contact the maintainer of package X-Symbol @emph{in
any case}, e.g., for suggestions, bug and problem reports, see @ref{Bug
Reports}.  Use @kbd{C-u 9 M-x x-symbol-package-bug} for patches
(including corrections of this manual, which are strongly appreciated)
and for other messages.
@end table

@vtable @code
@item x-symbol-installer-address
E-mail address of the person who has installed package X-Symbol
system-wide (@pxref{System-wide Installation}).

@item x-symbol-package-url
URL of package X-Symbol, used by @code{x-symbol-package-web}.
@end vtable

@c ====================================================================

@node Supported Languages, X-Symbol Internals, Features, Top
@comment  node-name,  next,  previous,  up
@chapter Supported Token Languages
@cindex Supported Languages
@cindex Default Languages
@cindex Built-in Languages
@cindex Provided Languages
@cindex Languages in Distribution

The chapter describe the predefined token language.  It also presents
the language specific behavior for @ref{Concepts}, @ref{Input Methods},
and @ref{Features}.

@menu
* Pseudo Language::             Token language ``x-symbol charsym''.
* TeX Macro::                   Token language @code{tex}.
* SGML Entity::                 Token language @code{sgml}.
* BibTeX Macro::                Token language @code{bib}.
* TeXinfo Command::             Token language @code{texi}.
* External Languages::          Languages defined in other Emacs Packages.
@end menu

@c ====================================================================

@node Pseudo Language, TeX Macro, Supported Languages, Supported Languages
@comment  node-name,  next,  previous,  up
@section Pseudo Token Language ``x-symbol charsym''
@cindex Pseudo Language
@cindex Charsym
@cindex X-Symbol Charsym

If no (or an invalid) token language is set for a buffer, the info in
the echo area (@pxref{Info}) for a X-Symbol Character in the buffer (if
it exists) uses the name of its @dfn{charsym}.  In this manual, we
actually refer to X-Symbol characters by their charsym name, e.g.,
@code{alpha}.

A charsym is a symbol which is used internally to represent a X-Symbol
character.  Charsyms are used instead characters in all user variables
of package X-Symbol.

The highlight menu of the Grid (@pxref{Input Method Grid}) also offers
to insert a charsym name.  Charsyms can also be used for input method
Read Token, see @ref{Input Method Read Token}.

You cannot use this pseudo language to turn on the X-Symbol minor mode
(@pxref{Minor Mode}), you cannot decode charsyms to their characters, and
you cannot encode characters to charsyms.

@c ===========================================================================

@node TeX Macro, SGML Entity, Pseudo Language, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``@TeX{} macro'' (@code{tex})
@cindex Token Language @code{tex}
@cindex Language @code{tex}
@cindex @TeX{} macro
@cindex @code{tex}
@cindex La@TeX{}

For buffers using the major mode @code{latex-mode}, @code{tex-mode} or
@code{plain-tex-mode}, we use token language @dfn{@TeX{} macro}
(@code{tex}).  This language provides the display of super-/subscripts
and images.  If the buffer visits a file with extension @file{.tex},
X-Symbol mode is automatically turned on.

@menu
* TeX Macro Basics::            Basics of language ``@TeX{} macro''.
* TeX Macro Features::          Super-/subscripts and images in La@TeX{}.
* TeX Macro Problems::          Problems with @TeX{} macros.
* TeX Macro Conversion::        How the conversion of @TeX{} macros works.
* TeX Macro Symbols::           Extra Symbols of Language ``@TeX{} Macro''.
@end menu


@node TeX Macro Basics, TeX Macro Features, TeX Macro, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Basics of Language ``@TeX{} macro''
@cindex TeX Macro Basics
@cindex Basics TeX Macro
@cindex Choosing TeX Macro
@cindex TeX Macro Use
@cindex TeX Macro Modes

The standard behavior can be controlled by the following variables:

@vtable @code
@item x-symbol-tex-modes
@itemx x-symbol-tex-auto-style
The variables known from @ref{Minor Mode}.  If the buffer visits a file
with extension @file{.tex}, super-/subscripts and images are displayed,
otherwise unique decoding (@pxref{Unique Decoding}) will be used.

@item x-symbol-tex-auto-coding-alist
Used there to automatically deduce the specific encoding of the file
(@pxref{File Coding}) if the file visited by the buffer has the
extension @file{.tex}.  It searches for one of the following two strings
in the current buffer, including the comment:

@example
\usepackage[@var{encoding}]@{inputenc@}
%& -translation-file=i@var{enc}
@end example

where @var{encoding} should be one of @samp{latin1}, @samp{latin2},
@samp{latin3}, @samp{latin5}, or @samp{latin9}, and @var{enc} should be
one of @samp{l1} or @samp{l2}.  8bit characters are not encoded if the
file if the search was successful (@pxref{Controlling 8bit Coding}).

@item x-symbol-tex-coding-master
@vindex TeX-master
If one of the above strings cannot be found in the current buffer, and
the current buffer has a buffer-local string value of @code{TeX-master},
also search in the file denoted by that value for the strings.
(Buffer-local variables will not be inherited.)
@end vtable

The input methods and the character info in the echo area are controlled
by:

@vtable @code
@item x-symbol-tex-header-groups-alist
We use the standard Grid and Menu headers.

@item x-symbol-tex-extra-menu-items
There is an extra menu item to remove the braces around text-mode
letters and other text-mode symbols.
@c TODO: detailed list of additional commands

@item x-symbol-tex-electric-ignore
@itemx x-symbol-tex-electric-ignore-regexp
@pindex texmathp
Input method Electric (@pxref{Input Method Electric}) is disabled if the
character is not of the correct @TeX{} mode, i.e., it only produces a
math-mode character in a math area and a text-mode character in a text
area (this test requires package @code{texmathp}, see @ref{LaTeX Packages}).
Postfix tilde is not electric, because @samp{~} produces a space in
@TeX{}.

@item x-symbol-tex-token-suppress-space
Input method Token (@pxref{Input Method Token}) only converts a token
ending with a control word like @code{\i}, if the character following
the token is no letter.  If that token is a text-mode token and a
@key{SPC} has been entered without a prefix argument, the @key{SPC} will
only perform the replacement, it will not insert a space, i.e., it will
act like @kbd{C-u 0 @key{SPC}}.

@item x-symbol-tex-class-alist
@itemx x-symbol-tex-class-face-alist
Various token classes (@pxref{Char Group}) are defined.  They are used
to give some info (@pxref{Info}) about the characters spacing behavior,
which La@TeX{} packages are necessary to use the character (@pxref{TeX
Macro Symbols}), and about the conversion (@pxref{TeX Macro
Conversion}).  X-Symbol uses blue for text-mode only and purple for
math-mode only characters in the Grid (@pxref{Input Method Grid} and the
character info.
@end vtable


@node TeX Macro Features, TeX Macro Problems, TeX Macro Basics, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Super-/Subscripts and Images in La@TeX{}
@cindex TeX Macro Features
@cindex Features TeX Macro
@cindex TeX Macro Superscripts
@cindex TeX Macro Subscripts
@cindex TeX Macro Images

The display of super- and subscripts (@pxref{Super and Subscripts}) is
controlled by:

@vtable @code
@itemx x-symbol-tex-font-lock-limit-regexp
The superscript command @code{^} and the subscript command @code{_} is
recognized.  The argument can be provided with and without braces.  The
argument should not span more than one line and should not contain a
super-/subscript command.

@item x-symbol-tex-font-lock-allowed-faces
The characters @samp{^} and @samp{_} are not always commands (@pxref{TeX
Macro Problems}), e.g., in the argument of @code{\ref}.  X-Symbol uses
the usual syntax highlighting keywords to decide whether to recognize
these characters as super-/subscript commands: they are commands if they
are not highlighted or highlighted with the usual math-mode faces.

This might lead to problems: @ref{FAQ No Subscripts}, @ref{FAQ Stupid
Subscripts}.  Using @code{texmathp} (@pxref{LaTeX Packages}) has even
more problems:

@itemize @minus
@item
The syntax highlighting (which is used for super-/subscripts) would be
much too slow.

@item
With own La@TeX{} environments, you would need to customize
@code{texmathp}.

@item
It is actually wrong: whether @samp{^} and @samp{_} are
super-/subscripts commands does not depend on whether we are in @TeX{}'s
math mode, it depends on its catcodes (which are changed by commands
like @code{\ref}).
@end itemize
@end vtable

The display of images (@pxref{Images}) is controlled by:

@vtable @code
@item x-symbol-tex-image-keywords
The following commands are recognized.  Extension @var{ext} stands for
@file{eps} (which is the default extension for both versions of
@code{\includegraphics} if the extension is omitted there), @file{ps},
@file{gif}, @file{png}, @file{jpeg}, @file{jpg}, or @file{pdf}.  Options
@var{options} can be omitted with their surrounding brackets or
preceding comma, respectively.

@example
\input@{@var{file}.pstex_t@}
\includegraphics[@var{options}][@var{options}]@{@var{file}.@var{ext}@}
\includegraphics*[@var{options}][@var{options}]@{@var{file}.@var{ext}@}
\epsfig@{file=@var{file}.@var{ext},@var{options}@}
\psfig@{file=@var{file}.@var{ext},@var{options}@}
\epsfbox[@var{options}]@{@var{file}.@var{ext}@}
\epsffile[@var{options}]@{@var{file}.@var{ext}@}
@end example

@item x-symbol-tex-master-directory
@vindex TeX-master
Relative file names (@pxref{Image Display}, explicitly or implicitly)
are relative to the directory part of variable @code{TeX-master} if it
is buffer-local and a string.  Otherwise, they are relative to the
directory of the current file.

@item x-symbol-tex-image-searchpath
@vindex TEXPICTS
@vindex TEXINPUTS
Files with implicitly relative names are meant to be searched in a
search path.  It defaults to the list of directories specified by the
environment variable @code{TEXPICTS} or @code{TEXINPUTS} (@pxref{TeX
environment variables,,,@value{kpathsea},@value{kpathseaman}}),
extended by @file{./} if necessary.

Each directory in this list is used to expand the file name.  The first
expansion naming a readable file is used.  Relative directories in this
list are expanded in the master directory mentioned above.

This mimics the standard behavior of @TeX{}, omitting the ``built-in''
directories of the search path (@pxref{Path
sources,,,@value{kpathsea},@value{kpathseaman}}).

@item x-symbol-tex-image-cached-dirs
The file name in the image command should not have a directory part or
the directory part should be @file{figures/} if the image should be
cached in the memory cache.
@end vtable


@node TeX Macro Problems, TeX Macro Conversion, TeX Macro Features, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Problems with @TeX{} Macros
@cindex TeX Macro Problems
@cindex Problems TeX Macro

Like with other token languages, the conversion between characters and
@TeX{} macros induce the problem that we have two conflicting
requirements: we would like X-Symbol not to change the file when
visiting and saving a file, and we would like X-Symbol to use characters
for all corresponding macros.  @xref{Unique Decoding}.

The additional problem with @TeX{} macros is that there is no fixed and
simple definition of @TeX{} macros, and many users have their personal
@TeX{} style, while many users are probably not aware that the style
also influences @TeX{}'s typesetting:

@itemize @bullet
@item
The tokens in @TeX{} are not ended by a dedicated character (like
@sc{sgml} entities are ended by @samp{;}).  Instead, we need the next
char to decide whether a macro ends, which would be no problem if @TeX{}
would have a character which has no meaning except separating tokens
(like space in most programming languages).  Unfortunately, this is not
the case: after an @dfn{control word} (an all-letter macro), a space has
no meaning, but it does produce a space in the output after characters
and other macros, except in math mode.

During decoding, a text-mode control word has to be replaced either with
its trailing spaces or not be replaced at all.  Since the number of
spaces can vary and X-Symbol does not remember the original @TeX{}
sequence of a character, X-Symbol would change the file if it would use
characters for all sequences.

@item
During encoding, a space after a character in the buffer must produce a
space in the document output, since users normally do not care whether
the character is represented by a control word or not.  Let us assume
that we (Bavarians) want to produce the output @samp{Ma@ss{}@ Bier}.
@ifinfo
In the info file, you will probably not see any 8bit characters (the
sharp @samp{s} is shown as @samp{@ss{}}).
@end ifinfo

@itemize @minus 
@item
Many people would use @samp{Ma\ss\@ Bier}.  This is (almost ever) fine
in text mode, but a @samp{\@ } in math mode is not ignored (whereas the
spaces after characters are).  If we have text- and math-mode control
word, we have a problem, since math-mode detection cannot work properly
without @TeX{} processing.

@item
Many people would use @samp{Ma\ss@{@}@ Bier}.  This has less problems and
is therefore used by X-Symbol.  The @samp{@{@}} at the end of the control
word is not used if the character is not followed by a space, e.g., to
produce @samp{Stra@ss{}e}, we use @samp{Stra\ss@ e}.  Consequently,
@samp{Ma\ss\@ Bier} in the file would be decoded to @samp{Ma@ss{}\@ Bier},
which would be encoded to the original sequence in the file.

@item
Some people would always use @samp{@{@}} after a text-mode control word,
even it is not followed by a space, like @samp{Stra\ss@{@}e}.  This is
wrong, since it breaks ligatures and kerns.  For example, compare the
output of @samp{\L@ V} with @samp{\L@{@}V} using @samp{T1} font encoding.

@item
Up to Version 4.1, X-Symbol surrounded a text-mode control word with
braces, like @samp{Stra@{\ss@}e}.  This was probably even worse than
always adding @samp{@{@}} at the end of the control word.  It was used,
because it is required by Bib@TeX{} (@pxref{BibTeX Macro}).
Unfortunately, Bib@TeX{} sends this bad sequence directly to La@TeX{},
but this has nothing to do with X-Symbol.
@end itemize

@item
The accented characters are not represented by one tokens in @TeX{}.
Most people use @samp{\"a} to produce an @samp{@"a}, while some use
@samp{\"@{a@}}.  X-Symbol uses the former, it does not even decode the
latter automatically.  Up to Version 4.1, X-Symbol used @samp{@{\"a@}},
having the same problems as using @samp{Stra@{\ss@}e}.

@item
Around a dozen characters can be produced by more than one @TeX{} macro,
like @code{\neq} and @code{\ne}.  Here, X-Symbol decodes both forms,
because it is probably a bad idea to redefine standard @TeX{} macros.
This will not be done with in style files (@pxref{Unique Decoding}).

@item
In @TeX{}, you can change the lexer on the fly, i.e., in a strict sense,
any conversion is unsafe without @TeX{} processing.  Since the most
likely change is to change the catcode of the character @samp{@@} to a
letter (used in La@TeX{}'s style files), this character is considered a
letter by X-Symbol.  This means that although both @samp{\ss@ @@} and
@samp{\ss@@} usually produce the same output, only the first is decoded
to @samp{@ss{}@@}.

@item
In @TeX{}, the definitions of macros can also change on the fly i.e., in
a strict sense, any conversion is unsafe without @TeX{} processing.
X-Symbol assumes that you do not do something like that except as done
by the standard La@TeX{} @code{\verb} command, and the @code{verbatim}
and @code{tabbing} environments.
@end itemize


@node TeX Macro Conversion, TeX Macro Symbols, TeX Macro Problems, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection The Conversion of @TeX{} Macros
@cindex TeX Macro Conversion
@cindex Conversion of TeX Macros

The @TeX{} macros for Latin characters are according to the La@TeX{}
package @file{inputenc.sty}, v0.97+.  Package X-Symbol uses U00B5 for
@code{\mathmicro}, not for @code{\mu}, though!  @xref{Wishlist LaTeX}.

It is assumed that you do not redefine standard @TeX{} macros like
@code{\ne} (@pxref{TeX Macro Conversion}), if you do so, you should
better use unique decoding (@pxref{Unique Decoding}).

The encoding of characters to @TeX{} macros works as follows:

@itemize @bullet
@item
If the character is preceded by an odd number of backslashes, insert a
space before the character.

@item
Accented characters are encoded without braces, e.g., we encode @samp{@,{c}}
to @samp{\c@ c}.  Accents are encoded with braces, e.g., we use
@samp{\c@{@ @}} and @samp{\u@{@}}.
@end itemize

Additionally, the encoding of characters to @TeX{} macros which are
@dfn{control words} (all-letter macros), or whose @TeX{} representation
ends with a control word (like @samp{\'\i}) works as follows:

@itemize @bullet
@item
If the character is followed by a letter, replace the character by the
macro and insert a space.

@item
If the macro is a text-mode macro and followed by one or more blanks,
replace the character and insert @samp{@{@}}.

@item
Otherwise, just replace the character.
@end itemize

The decoding of @TeX{} macros which are control words to characters
works as follows:

@itemize @bullet
@item
If the macro is a text-mode macro and followed by @samp{@{@}} which is
followed by a blank, replace the macro and delete the braces.

@item
If the macro is a text-mode macro and followed by one are more blanks,
we have the following rule:

@itemize @minus
@item
If we have exactly one blank, the blank is a space, and it is not
followed by a @samp{%} (comment character), replace the macro by the
corresponding character and delete the space.  (With unique decoding,
the character following the space must be a letter.)

@item
Otherwise, do @emph{not decode} the macro!
@end itemize

@item
Otherwise, just replace the macro.
@end itemize

To clarify, @dfn{letter} means @samp{A}-@samp{Z}, @samp{a}-@samp{z}, or
@samp{@@}, @dfn{blank} means a space, newline or the end of the buffer
(therefore, the last character in the buffer is always followed by a
blank).

There are three control words which are both text-mode and math mode
macros: @code{\ldots}, @code{\vdots}, and (by accident) @code{\angle}.
They are all treated like math-mode characters, but their minibuffer
info (@pxref{Info}) includes @samp{gobbles space} (spaces in the buffer
after the character have no impact on the document),

Additionally, the following commands and environments are processed
during decoding (but we are just looking for strings, i.e., they are
also processed in comments):

@vtable @code
@item x-symbol-tex-verb-delimiter-regexp
If the command @code{\verb} is found, its argument is not decoded if it
is delimited by one of the following characters: @samp{-}, @samp{!},
@samp{#}, @samp{$}, @samp{&}, @samp{*}, @samp{+}, @samp{/}, @samp{=},
@samp{?}, @samp{^}, @samp{|}, or @samp{!}.

@item x-symbol-tex-env-verbatim-regexp
The contents of the @code{verbatim} environment is not decoded.  To
produce accented characters inside this environment, use the La@TeX{}
package @file{inputenc.sty}.

@c Inside @code{\hyphenation}@{@dots{}@}, you can only use Latin characters.

@c David Kastrup: Wrong.  inputenc.sty converts things like @"a into \"a
@c anyway (take a look into your table of contents file, xxx.toc, for
@c example).  Both @"a and \"a will not work in hyphenation patterns when you
@c are using a font encoding without such a character (like the default OT1
@c encoding), both @"a and \"a will work if something like
@c \usepackage[T1]{fontenc} is active.  This holds for LaTeX; plain TeX is
@c not as sophisticated as to replace \"a with a single character when in
@c T1 encodings.

@item x-symbol-tex-env-tabbing-regexp
Inside a @code{tabbing} environment, the macro sequences starting with
@samp{\`}, @samp{\'}, @samp{\=} and @samp{\-} are not decoded.  It is
probably better (with or without X-Symbol) to use the La@TeX{} package
@file{inputenc.sty} or to the @code{Tabbing} environment, to be found in
the @sc{ctan} archives.
@end vtable

During encoding, these commands and environments are not respected,
since it does not make any sense to have X-Symbol's private characters
in the @TeX{} file.

@ifinfo
Final note: in the info file, you will probably not see any 8bit
characters.
@end ifinfo

You might want change the conversion between characters and tokens in
language @code{tex} by changing:

@vtable @code
@item x-symbol-tex-user-table
You can define you own tokens for X-Symbol characters.  E.g., if you
like to have the command @code{\sqrt} represented by a character
(shadowing the entry for @code{\surd}), add the following to your
@file{~/.emacs}:

@lisp
(setq x-symbol-tex-user-table '((radical (math special) "\\sqrt")))
@end lisp
@end vtable


@node TeX Macro Symbols,  , TeX Macro Conversion, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Extra Symbols of Language ``@TeX{} Macro''
@cindex Extra Symbols for @TeX{}
@cindex Defining @code{tex}
@cindex Initializing @code{tex}
@cindex @TeX{} Macro Installation
@cindex Installing @code{tex}
@pindex @file{latexsym.sty}
@pindex @file{amssymb.sty}
@pindex @file{stmaryrd.sty}
@pindex @file{fontenc.sty}
@pindex @file{inputenc.sty}

This section describes what you should put into your private style file
or your document if you want to use extra symbols, i.e., characters
whose info in the echo area (@pxref{Info}) contains s.th. like
@samp{@var{package}.sty} or @samp{user}.  If you do not use the
corresponding characters, you do not have to do anything, of course.

The @TeX{} macros @code{\Box}, @code{\Diamond}, @code{\leadsto},
@code{\Join}, @code{\lhd}, @code{\mho}, @code{\rhd}, @code{\sqsupset},
@code{\sqsubset}, @code{\unlhd}, @code{\unrhd}, are defined in La@TeX{}
package @file{latexsym.sty}:

@example
\usepackage@{latexsym@}
@end example

Note that these macros are also defined @file{amssymb.sty}.  Since the
first four macros are defined differently (better) in
@file{latexsym.sty}, it does make sense to load both La@TeX{} packages
(e.g., @file{amssymb.sty} simply defines @code{\Diamond} to be the same
as @code{\lozenge}).

The @TeX{} macros @code{\boldsymbol}, @code{\circledast},
@code{\circledcirc}, @code{\circleddash}, @code{\digamma},
@code{\gtrapprox}, @code{\gtrsim}, @code{\lessapprox}, @code{\lesssim},
@code{\triangleq}, @code{\varkappa} are defined in AMS La@TeX{} package
@file{amssymb.sty}:

@example
\usepackage@{amssymb@}
@end example

The @TeX{} macros @code{\bigsqcap}, @code{\llbracket},
@code{\rrbracket}, @code{\llparenthesis}, @code{\rrparenthesis} are
defined in the La@TeX{} package @file{stmaryrd.sty}:

@example
\usepackage@{stmaryrd@}
@end example

The @TeX{} macros @code{\guilsinglleft}, @code{\guilsinglright},
@code{\dj}, @code{\NG}, @code{\ng}, @code{\DH}, @code{\DJ}, @code{\dh},
@code{\dj}, @code{\TH}, @code{\th}, @code{\guillemotleft},
@code{\guillemotright} and the ogonek characters are only defined if
you use T1 font encoding:

@example
\usepackage[T1]@{fontenc@}
@end example

The @TeX{} macro @code{\mathmicro} for U00B5 can be defined by
(@pxref{Wishlist LaTeX}):

@example
\let\mathmicro\mu
@end example

You should define the following in your La@TeX{} file (if you use the
corresponding characters), the first can only be used with T1 font encoding.

@example
\DeclareTextSymbol@{\textbackslash@}@{T1@}@{92@}
\newcommand@{\nsubset@}@{\not\subset@}
\newcommand@{\textflorin@}@{\textit@{f@}@}
\newcommand@{\setB@}@{@{\mathord@{\mathbb B@}@}@}
\newcommand@{\setC@}@{@{\mathord@{\mathbb C@}@}@}
\newcommand@{\setN@}@{@{\mathord@{\mathbb N@}@}@}
\newcommand@{\setQ@}@{@{\mathord@{\mathbb Q@}@}@}
\newcommand@{\setR@}@{@{\mathord@{\mathbb R@}@}@}
\newcommand@{\setZ@}@{@{\mathord@{\mathbb Z@}@}@}
\newcommand@{\coloncolon@}@{\mathrel@{::@}@}
@c \newcommand@{\lsemantics@}@{\mathopen@{\lbrack\mkern-3mu\lbrack@}@}
@c \newcommand@{\rsemantics@}@{\mathclose@{\rbrack\mkern-3mu\rbrack@}@}
@c \newcommand@{\lcata@}@{\mathopen@{(\mkern-3mu\mid@}@}
@c \newcommand@{\rcata@}@{\mathclose@{\mid\mkern-3mu)@}@}
@end example

The @TeX{} macros @code{\textordfeminine}, @code{\textordmasculine},
@code{\textdegree}, @code{\textonequarter}, @code{\textonehalf},
@code{\textthreequarters}, @code{\mathonesuperior},
@code{\mathtwosuperior}, @code{\maththreesuperior},
@code{\textcopyright} are only defined when using La@TeX{} package
@file{inputenc.sty}:

@example
\usepackage[latin1]@{inputenc@}
@end example

The @TeX{} macros @code{\textcent}, @code{\textcurrency},
@code{\textyen}, @code{\textbrokenbar}, @code{\textmalteseH},
@code{\textmalteseh} are defined as not available in La@TeX{} package
@file{inputenc.sty}.  @xref{Wishlist LaTeX}.  If you use this package
and want to define these commands, use @code{\renewcommand} (or
@code{\def}) after, e.g.:

@example
\usepackage[latin1]@{inputenc@}
\usepackage@{wasysym@}  %% defines \cent, \currency, \brokenvert
\usepackage@{amssymb@}  %% defines \yen
\renewcommand@{\textcent@}@{\cent@}
\renewcommand@{\textcurrency@}@{\currency@}
\renewcommand@{\textyen@}@{\yen@}
\renewcommand@{\textbrokenbar@}@{brokenvert@}
@end example

@c ===========================================================================

@node SGML Entity, BibTeX Macro, TeX Macro, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``@sc{sgml} entity'' (@code{sgml})
@cindex HTML
@cindex SGML entity
@cindex Token Language @code{sgml}
@cindex Language @code{sgml}
@pindex Netscape

For buffers using the major mode @code{html-mode}, @code{hm--html-mode},
@code{html-helper-mode}, @code{sgml-mode} or @code{xml-mode}, we use
token language @dfn{@sc{sgml} entity} (@code{sgml}).  This language
provides the display of super-/subscripts and images.  If the buffer
visits a file and uses a @sc{html} mode, X-Symbol mode is automatically
turned on.

@menu
* SGML Entity Basics::          Basics of Language ``@sc{sgml} entity''.
* SGML Entity Features::        Super-/Subscripts and Images in @sc{html}.
* SGML Entity Conversion::      How the conversion of @sc{sgml} entities works.
@end menu


@node SGML Entity Basics, SGML Entity Features, SGML Entity, SGML Entity
@comment  node-name,  next,  previous,  up
@subsection Basics of Language ``@sc{sgml} entity''
@cindex SGML Entity Basics
@cindex Basics SGML Entity
@cindex Choosing SGML Entity
@cindex SGML Entity Use
@cindex SGML Entity Modes

The standard behavior can be controlled by the following variables:

@vtable @code
@item x-symbol-sgml-modes
@itemx x-symbol-sgml-auto-style
The variables known from @ref{Minor Mode}.  If the buffer uses a
@sc{html} mode, super-/subscripts and images are displayed, otherwise
unique decoding (@pxref{Unique Decoding}) will be used.

@item x-symbol-sgml-auto-coding-alist
Used there to automatically deduce the specific encoding of the file
(@pxref{File Coding}).  It searches for the following string in the
current buffer, including the comment:

@example
<meta http-equiv="content-type"
      content="text/html; charset=@var{encoding}">
@end example

where @var{encoding} should be one of @samp{iso-8859-1},
@samp{iso-8859-2}, @samp{iso-8859-3}, @samp{iso-8859-9}, or
@samp{iso-8859-15}.  8bit characters are not encoded if the file if the
search was successful (@pxref{Controlling 8bit Coding}).
@end vtable

The input methods and the character info in the echo area are controlled
by:

@vtable @code
@item x-symbol-sgml-header-groups-alist
Defines the headers and their characters for the language specific Grid
and Menu.

@item x-symbol-sgml-extra-menu-items
There are no special entries in the X-Symbol menu.

@item x-symbol-sgml-electric-ignore
There is no additional constraint to the ones mentioned in @ref{Input
Method Electric}.

@item x-symbol-sgml-class-alist
@itemx x-symbol-sgml-class-face-alist
Token classes (@pxref{Char Group}) are only used to define a coloring
scheme.  X-Symbol uses dark orange or dark red for non-Latin-1
characters in the Grid (@pxref{Input Method Grid} and the character info
(@pxref{Info}), dark red for characters without defined entity names in
@sc{html} (@pxref{SGML Entity Conversion}).
@end vtable


@node SGML Entity Features, SGML Entity Conversion, SGML Entity Basics, SGML Entity
@comment  node-name,  next,  previous,  up
@subsection Super-/Subscripts and Images in @sc{html}
@cindex SGML Entity Features
@cindex Features SGML Entity
@cindex SGML Entity Superscripts
@cindex SGML Entity Subscripts
@cindex SGML Entity Images

The display of super- and subscripts (@pxref{Super and Subscripts}) is
controlled by:

@vtable @code
@item x-symbol-sgml-font-lock-regexp
@itemx x-symbol-sgml-font-lock-limit-regexp
@itemx x-symbol-sgml-font-lock-alist
@itemx x-symbol-sgml-font-lock-contents-regexp
The superscript command @code{<sup>}@dots{}@code{</sup>} and the subscript
command @code{<sub>}@dots{}@code{</sub>} is recognized.  The contents should
contain at least one character which is not a space or a
@code{nobreakspace}.
@end vtable

The display of images (@pxref{Images}) is controlled by:

@vtable @code
@item x-symbol-sgml-image-keywords
The following commands are recognized.  Extension @var{ext} stands for
@file{gif}, @file{png}, @file{jpeg} or @file{jpg}.

@example
<img @var{@dots{}} src="@var{file}.@var{ext}" @var{@dots{}}>
@end example

@item x-symbol-sgml-master-directory
@itemx x-symbol-sgml-image-searchpath
Relative file names (@pxref{Image Display}) are relative to the
directory of the current file.

@item x-symbol-sgml-image-file-truename-alist
The file name prefix @file{file:} is ignored.  For any other file name
which starts with letters and then a colon, e.g., with @file{http:} or
@file{C:\} (which is no @sc{url} anyway), the image insertion command
will be skipped.  By changing this variable, you could specify that the
prefix @file{http://www.fmi.uni-passau.de/~wedler/} corresponds to
@file{~/public_html/}.

@item x-symbol-sgml-image-cached-dirs
The file name in the image command should not have a directory part or
the directory part should be @file{images/} or @file{pictures/} if the
image should be cached in the memory cache.
@end vtable


@node SGML Entity Conversion,  , SGML Entity Features, SGML Entity
@comment  node-name,  next,  previous,  up
@subsection The Conversion of @sc{sgml} Entities
@cindex SGML Entity Conversion
@cindex Conversion of SGML Entities

Most character entities of HTML-4.0 are supported, except the following:
uppercase Greek which look like uppercase Latin, ``markup-significant
and internationalization'' characters, and some quotes.  See
@uref{@value{sgmlentitiesurl}}.

By default, we encode to entity references like @code{&amp;}, and decode
from both entity references and character references like @code{&#38;}.
For Latin-N characters without defined entity names in @sc{html} (e.g.
@code{scedilla}), we can only use character references.

Do not expect Netscape before v6 to display non-Latin-1 characters
correctly (this might work by specifying the charset UTF-8 and using
character references).

You might want change the conversion between characters and tokens in
language @code{sgml} by changing:

@vtable @code
@item x-symbol-sgml-token-list
@findex x-symbol-sgml-token-list-name
@findex x-symbol-sgml-token-list-code
@findex x-symbol-sgml-token-list-netscape
A symbol, which defines whether to use entity references, character
references, or entity references for Latin-1 characters and character
references for others.

@item x-symbol-sgml-user-table
It is probably not a good idea to change the defined tokens (except via
the variable above), but you might want to add some definitions:

@example
(setq x-symbol-sgml-user-table '((circ () 999 "&bcomp;")))
@end example
@end vtable

@c ====================================================================

@node BibTeX Macro, TeXinfo Command, SGML Entity, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``Bib@TeX{} macro'' (@code{bib})
@cindex Token Language @code{bib}
@cindex Language @code{bib}
@cindex Bib@TeX{} macro
@cindex @code{bib}
@cindex Bib@TeX{}

For buffers using the major mode @code{bibtex-mode}, we use token
language @dfn{Bib@TeX{} macro} (@code{bib}).  This language does not
provide the display of super-/subscripts and images.  If the buffer
visits a file, X-Symbol mode is automatically turned on.  It is
controlled by:

@vtable @code
@item x-symbol-bib-modes
@itemx x-symbol-bib-auto-style
The variables known from @ref{Minor Mode}.  There is no automatic
deduction of the file encoding, 8bit characters are usually encoded, and
there is usually no unique decoding.  @xref{Conversion}.
@end vtable

@pindex bibtex
The major difference between this language and the token language
@code{tex} is that the tokens for text-mode characters are most likely
enclosed by braces.  This has some problems (@pxref{TeX Macro
Problems}), but is required by the program @code{bibtex}.

The input methods and most features except super-/subscripts and images
work like in token language @code{tex} (@pxref{TeX Macro}):

@vtable @code
@item x-symbol-bib-header-groups-alist
@itemx x-symbol-bib-electric-ignore
@itemx x-symbol-bib-class-alist
@itemx x-symbol-bib-class-face-alist
Like in @ref{TeX Macro Features}.

@item x-symbol-bib-extra-menu-items
There are no special entries in the X-Symbol menu.
@end vtable

You might want change the conversion between characters and tokens in
language @code{bib} by changing:

@vtable @code
@item x-symbol-bib-user-table
@itemx x-symbol-tex-user-table
Use the former for @code{bib}-only changes, the latter also influences
the conversion with token language @code{tex}.
@end vtable

@c ====================================================================

@node TeXinfo Command, External Languages, BibTeX Macro, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``@TeX{}info command'' (@code{texi})
@cindex Token Language @code{texi}
@cindex Language @code{texi}
@cindex @TeX{}info command
@cindex @code{texi}
@pindex texinfo
@pindex GNU texinfo

For buffers using the major mode @code{texinfo-mode}, we use token
language @dfn{@TeX{}info command} (@code{texi}).  This language does not
provide the display of super-/subscripts and images.  If the buffer
visits a file, X-Symbol mode is automatically turned on.  It is
controlled by:

@vtable @code
@item x-symbol-texi-modes
@itemx x-symbol-texi-auto-style
The variables known from @ref{Minor Mode}.  There is no automatic
deduction of the file encoding, 8bit characters are usually encoded, and
there is usually no unique decoding.  @xref{Conversion}.
@end vtable

With @code{x-symbol-8bits} having value @code{nil} (the default), it
might still happen that the saved file contains 8bit characters, since
token language @code{texi} does not define tokens for all characters in
the Latin charsets supported by X-Symbol.  @xref{Controlling 8bit
Coding}.

With @code{x-symbol-unique} having value @code{nil} (the default), we
have unique decoding anyway, since token language @code{texi} does only
define one token per character, i.e., the value is not important if
@code{x-symbol-8bits} is @code{nil}.  @xref{Unique Decoding}.

The input methods and the character info in the echo area are controlled
by:

@vtable @code
@item x-symbol-texi-header-groups-alist
Defines the headers and their characters for the language specific Grid
and Menu.

@item x-symbol-texi-extra-menu-items
There are no special entries in the X-Symbol menu.

@item x-symbol-texi-electric-ignore
There is no additional constraint to the ones mentioned in @ref{Input
Method Electric}.

@item x-symbol-texi-class-alist
@itemx x-symbol-texi-class-face-alist
Only a few token classes (@pxref{Char Group}) are defined, the most
interesting induces the character info (@pxref{Info}) to display
@samp{not as code} for @code{@@minus@{@}} (@code{@@minus@{@}} should not
used inside @code{@@code} and @code{@@example}).  No coloring scheme is
defined.
@end vtable

@pindex makeinfo
At least with @code{makeinfo-4.0}, you do not get accented characters in
the info file for the corresponding @TeX{}info commands in the
@file{.texi} file, the @sc{html} output might contain illegal
``@sc{sgml} entities'' like @code{&140;}.

@pindex texi2html
At least with @code{texi2html-1.62}, you see accented characters in the
@sc{html} output for the corresponding @TeX{}info commands in the
@file{.texi} file, but the output might also contain illegal ``@sc{sgml}
entities'' like @code{&140;}.

You might want change the conversion between characters and tokens in
language @code{texi} by changing:

@vtable @code
@itemx x-symbol-texi-user-table
Extra entries for the conversion.
@end vtable

@c ====================================================================

@node External Languages,  , TeXinfo Command, Supported Languages
@comment  node-name,  next,  previous,  up
@section Languages Defined in Other Emacs Packages
@cindex Foreign Languages
@cindex External Languages
@cindex Other Languages

It is no problem for other Emacs packages to define their own token
language (@pxref{Extending X-Symbol}).

I know of the following package---please check its manual for details.

@itemize @bullet
@item
@pindex ProofGeneral
@cindex Isabelle Symbol
Package @uref{@value{proofgeneralurl},ProofGeneral} defines token
language ``Isabelle symbol''.
@end itemize

@c ===========================================================================

@node X-Symbol Internals, Problems, Supported Languages, Top
@comment  node-name,  next,  previous,  up
@chapter X-Symbol Internals
@cindex Internals, X-Symbol
@cindex X-Symbol Internals

This section is outdated, it currently describes Version 3.4.2 of X-Symbol.

Package X-Symbol is distributed in two ways.  End-users should use the
@emph{binary package} which contains pre-compiled files.  X-Symbol
developers should use the @emph{source package} which contains some
additional files.

@menu
* Char Representation::         How X-Symbol represents X-Symbol chars.
* Defining Charsets::           How X-Symbol defines additional chars.
* Defining Input Methods::      How X-Symbol defines the input methods.
* Extending X-Symbol::          How to add fonts and token languages.
* Various Internals::           How X-Symbol handles other aspects.
* Design Alternatives::         Why X-Symbol is not designed differently.
* Language Internals::          How X-Symbol handles languages.
* Misc Internals::              Various.  TODO.
@end menu

@c ====================================================================

@node Char Representation, Defining Charsets, X-Symbol Internals, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Internal Representation of X-Symbol Characters
@cindex Charsym
@cindex Leading Character
@cindex Octet
@cindex Cstring
@cindex Mule Character

As mentioned in @ref{Pseudo Language}, most functions do not operate
on X-Symbol characters directly, they use ``x-symbol charsyms''.  These
charsyms have a symbol property @code{x-symbol-cstring} which points to
a string, called @dfn{cstring}, containing the X-Symbol character.

@itemize @bullet
@item
Under Emacs and XEmacs/Mule, the string only contains the character
which is a normal Mule character created by @code{make-char}.

@item
@pindex font-lock
Under XEmacs/no-Mule, the string only contains the 8bit character if the
X-Symbol character is a 8bit character according to
@code{x-symbol-default-coding} (@pxref{Default Coding}).  Otherwise, the
string contains of a @dfn{leading character} (with range @samp{\200} to
@samp{\237}) and an @dfn{octet}.  Package @code{font-lock} is used to
display them correctly as X-Symbol characters (@pxref{FAQ Strange
Chars}).  E.g., with @samp{\251} is @code{copyright}, we get

@lisp
(get 'Idotaccent 'x-symbol-cstring)
     @result{} "\235\251"
@end lisp
@end itemize

If the character is also a 8bit character in some encoding (@pxref{File
Coding}), the charsym also has the symbol property
@code{x-symbol-file-cstrings} for the representation in the file and
property @code{x-symbol-buffer-cstrings} to recognize character aliases
(@pxref{Char Aliases}).  E.g., under XEmacs/no-Mule, with @samp{\335} is
@code{Yacute}, @samp{\251} is @code{copyright}, we get

@lisp
(get 'Idotaccent 'x-symbol-file-cstrings)
     @result{} (iso-8859-9 "\335" iso-8859-3 "\251")
(get 'Idotaccent 'x-symbol-buffer-cstrings)
     @result{} (iso-8859-9 "\234\335" iso-8859-3 "\235\251")
@end lisp

The values are plists (@pxref{Property Lists,,,lispref,XEmacs Lisp
Reference Manual}) mapping the file coding to the strings in the file or 
the buffer, respectively.

After token languages have been initialized, the charsym also has the
symbol properties @code{x-symbol-tokens} (@pxref{Token Language}) and
@code{x-symbol-classes} (@pxref{Char Group}):

@lisp
(get 'Idotaccent 'x-symbol-tokens)
     @result{} (sgml "&#304;" tex "@{\\.I@}")
(get 'Idotaccent 'x-symbol-classes)
     @result{} (sgml (non-l1) tex (text aletter))
@end lisp

@c ====================================================================

@node Defining Charsets, Defining Input Methods, Char Representation, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Defining X-Symbol Charsets
@cindex Cset
@cindex Charset
@cindex Final Byte

An X-Symbol charset, called @dfn{cset} in the code and the docstrings,
handles one font used by package X-Symbol.  Each cset must use the
same char registry@minus{}encoding as the corresponding variables for
the fonts (@pxref{Installing Fonts Lisp}).

You have to tell X-Symbol, how to define Mule charsets with Emacs or
XEmacs/Mule and which leading character to use with XEmacs/no-Mule.  As
an example, we use the definition of the Adobe symbol font.

@lisp
@group
(defvar x-symbol-xsymb0-cset
  '((("adobe-fontspecific") ?\233 -3600)
    (xsymb0-left  "X-Symbol characters 0, left"  94 ?:) .
    (xsymb0-right "X-Symbol characters 0, right" 94 ?\;)))
@end group
@end lisp

Mule charsets (@pxref{Charsets,,,lispref,XEmacs Lisp Reference Manual})
may be used for 94 or 96 characters (this example: 94, only charset with
dimension 1 can be defined with X-Symbol).  Thus, if your font provides
more characters, you are likely to use both the left and the right half
of the font to define two Mule charsets.  For both of them, you have to
define a unique, free final character/byte of the standard ISO 2022
escape sequence designating the charset (this example: @samp{:} and
@samp{;}).  The remaining free (reserved by Emacs for users) are
@samp{>} and @samp{?}, the latter is already used in XEmacs.

For XEmacs/no-Mule, you have to define the leading character (this
example: @samp{\233}).

@vtable @code
@item x-symbol-latin1-cset
@itemx x-symbol-latin2-cset
@itemx x-symbol-latin3-cset
@itemx x-symbol-latin5-cset
Cset definitions only using the upper halves of the fonts where the
corresponding Mule charsets are known and which define characters which
are considered 8bit characters in the corresponding encoding, see
@ref{File Coding}.

@item x-symbol-xsymb0-cset
@itemx x-symbol-xsymb1-cset
Cset definitions using both halves of the fonts where no corresponding
Mule charset are yet known.
@end vtable

@c ====================================================================

@node Defining Input Methods, Extending X-Symbol, Defining Charsets, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Defining Input Methods
@cindex Input Method Internals
@cindex Internals, Input Method
@cindex Defining Input Methods

This is probably the hardest section in this manual@dots{}.

@menu
* Input Method Objectives::     Input methods should be intuitive/consistent.
* Intro Char Descriptions::     An example introducing char descriptions.
* Char Descriptions::           The aspects and the contexts of a character.
* Example Char Descriptions::   A complete example defining input methods.
* Customizing Input Methods::   How to customize the input methods.
@end menu


@node Input Method Objectives, Intro Char Descriptions, Defining Input Methods, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Defining Input Methods: Objectives
@cindex Input Method Objectives
@cindex Objectives, Input Methods
@cindex Consistent Input Methods

Input methods should be intuitive.  This requires consistency:

@itemize @bullet
@item
Characters should be found under the same header in the Grid and in the
Menu.

@item
If one character can be modified or rotated to another character
(@pxref{Input Method Context}), both should stand near to each other in
the Grid.  E.g., since @code{arrowsouthwest} rotates to
@code{arrowdown}, they stand next to each other.

@item
The key binding should be similar to the context of input method
Context.  If two characters are defined to have the same context, they
should have the same key prefix and the suffix should be a number which
increases with the ``modify-to'' behavior.  E.g., @code{reflexsubset}
with key binding @kbd{C-= < _ 2} modifies to @code{reflexsqsubset} with
key binding @kbd{C-= < _ 3}.

@item
Consistent definition of ``modify-to'' and ``rotate-to'': if A can be
modified to B and rotated to C and C can be modified to D, B can be
rotated to D in most cases.

@item
It should be possible to load character definitions later on, e.g., when
new token languages get initialized.

@itemize @minus
@item
Existing key bindings should not be overwritten.  If some of them have to
change, it should be done in a uniform way (solution: key suffix
@samp{1}).

@item
Also, modifying or rotating a new character to/from old ones should be
possible without changing the input definitions of the old characters.
@end itemize
@end itemize

Observation: It is impossible, especially with the possibility to load
character definitions later on, to define the input methods directly,
i.e., by something like @code{define-key}.  The solution is an indirect
definitions with ``character descriptions''.


@node Intro Char Descriptions, Char Descriptions, Input Method Objectives, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection X-Symbol Character Descriptions: Example
@cindex Character Descriptions, Intro
@cindex Character Descriptions, Example

As an example for ``character descriptions'', look at the definition of
@code{longarrowright} in @code{x-symbol-xsymb1-table} (@samp{95} is the
encoding in the font and not of interest here).  Some terms are defined
in the next section:

@lisp
@group
(longarrowright 95
 (arrow) (size big . arrowright) nil ("->" t "-->") (emdash))
@end group
@end lisp

With this definition, package X-Symbol automatically defines:

@itemize @bullet
@item
Key bindings @kbd{C-= - - >} and @kbd{C-= - > 2}, the latter has suffix
2, because @kbd{C-= - >} is also ``wanted'' by @code{arrowright} which
now has the key binding @kbd{C-= - > 1} (the ``score'' of
@code{longarrowright} is higher, due to @samp{size big}).  @xref{Input
Method Keyboard}.

@item
@code{arrowright} modifies to @code{longarrowright}, which modifies to
@code{arrowright}.  @xref{Input Method Context}.

@item
@code{longarrowleft} rotates to @code{longarrowright}, which rotates to
@code{longarrowboth} (which rotates to @code{longarrowleft}).  (The
``rotate aspects'' are inherited from @code{arrowright}.)  @xref{Input
Method Context}.

@item
The following contexts can be modified to @code{longarrowright}:
@samp{-->} or @code{minus1} / @code{endash} / @code{macron} /
@code{emdash} / @code{hyphen} and @samp{->} (since all define context
@samp{-}) and @code{emdash} and @samp{>} (since @code{emdash} defines
context @samp{--}).  @samp{->} is used for @code{arrowright}, which has
a lower score, see above.  @xref{Input Method Context}.

@item
Input method Electric will change context @samp{-->} (is tagged with
@code{t} in the definition) to @code{longarrowright}, also @code{emdash}
and @samp{>} (only theoretically, since input method Electric will
produce @code{emdash} only in @TeX{}'s text mode, and
@code{longarrowright} only in @TeX{}'s math mode).  @xref{Input Method
Electric}.

@item
The character will appear in the Grid under the header @samp{Arrow}.
You will probably recognize that the placement is based on the modify-to
and rotate-to behavior above.  @xref{Input Method Grid}.

@item
The character will appear in the Menu under one of the headers
@samp{Arrow @var{n}}".  The submenus are sorted alphabetically.
@xref{Input Method Menu}.
@end itemize

Consider that this character would be missing in package X-Symbol and
you want to define your own character (in your own font).  With the
current scheme, the one line above is enough!  Have fun defining all the
consequences directly instead@dots{}.


@node Char Descriptions, Example Char Descriptions, Intro Char Descriptions, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Defining Input Methods by Character Descriptions
@cindex Character Descriptions
@cindex Aspects of Characters
@cindex Parent Character
@cindex Component of Characters
@cindex Modify Scores
@cindex Rotate Scores
@cindex Modify Aspects
@cindex Rotate Aspects
@cindex Score of a Character
@cindex Modify Chain
@cindex Exclusive Modify Chain
@cindex Rotate Chain
@cindex Horizontal Chain
@cindex Key Chain

Characters are defined with @dfn{character descriptions} which consist
of different @dfn{aspects} and @dfn{contexts}, which can also be
inherited from a @dfn{parent} character.  All characters which are
connected with parents, form a @dfn{component}.  Aspects and contexts
are used to determine the modify-to and rotate-to chain for characters,
the contexts for input method Context and Electric, the key bindings,
and the position in the Menu and the Grid.

If you want to check the component, scores, etc of a specific character,
look at the symbol property (e.g., with @kbd{M-x hyper-apropos-get-doc})
of the corresponding charsym, e.g., @code{arrowright}.  See also the
docstrings of @code{x-symbol-init-cset} and @code{x-symbol-init-input}.

Remember, all characters which are connected with parents, form a
component.  @dfn{Contexts} are the contexts of input method Context
(@pxref{Input Method Context}).  If a table entry of a charsym does not
define its own contexts, they are the same as the contexts of the
charsym in an earlier position in the modify chain (see below), or the
contexts of the first charsym with defined contexts in the modify chain.
The @dfn{modify context} of a charsym is the first context.

@vtable @code
@item x-symbol-rotate-aspects-alist
Characters in the same component whose aspects only differ by their
@code{direction} (@code{east},@dots{}), a key in this alist, are
circularly connected by ``rotate-to''.  The sequence in the @dfn{rotate
chain} is determined by @dfn{rotate scores} depending on the values in
the @dfn{rotate aspects}.  Charsyms with the same ``rotate-aspects'' are
not connected (charsyms with the smallest modify scores are preferred).

@lisp
(get 'longarrowright 'x-symbol-rotate-aspects)
     @result{} (-1500 direction east)
@end lisp

@item x-symbol-modify-aspects-alist
Characters in the same components whose aspects only differ by their
@code{size} (@code{big},@dots{}), @code{shape} (@code{round},
@code{square}@dots{}) and/or @code{shift} (@code{up},
@code{down},@dots{}), keys in this alist, are circularly connected by
``modify-to'', if all their modify contexts are used exclusively, i.e.,
no other modify chain uses any of them.  The sequence in the @dfn{modify
chain} is determined by @dfn{modify scores} depending on the values in
the @dfn{modify aspects}, the charsym score defined in the definition
tables and the score of the whole cset (@pxref{Defining Charsets}).

@lisp
(get 'longarrowright 'x-symbol-score)
     @result{} -3500
(get 'longarrowright 'x-symbol-modify-aspects)
     @result{} (1500 shift nil shape nil size big)
@end lisp

Otherwise, the ``modify chain'' is divided into modify subchains, which
are those charsyms sharing the same modify context.  All modify
subchains using the same modify context, build a @dfn{horizontal chain}
whose charsyms are circularly connected by ``modify-to''.

We build a @dfn{key chain} for all contexts (not just modify contexts),
consisting of all charsyms (sorted according to modify scores) having
the context.  Input method Context modifies the context to the first
charsym in the key chain.

@item x-symbol-key-suffix-string
If there is only one charsym in the key chain, @kbd{C-=} plus the
context inserts the charsym.  Otherwise, we determine a suffix for each
charsym in the key chain by its index and this string.  @kbd{C-=} plus
the context plus the suffix inserts the charsym.
@end vtable


@node Example Char Descriptions, Customizing Input Methods, Char Descriptions, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Defining Input Methods: Example
@cindex Character Descriptions, Example

@smallexample
An example:  Modify  Modify  Rotate  Rotate  Modify   Other
             Score   Aspect  Score   Aspect  Context  Contexts
--------------------------------------------------------------
charsym 1w    150     nil     100     west    `a'      `c'
charsym 2w    200     nil     100     west    `b'       -
charsym 3w    350     big     100     west   (`b')     (-)
charsym 1e    100     nil     200     east   (`a')    (`b')
charsym 2e    250     big     200     east    `a'      `b'
charsym 3e    300     big     200     east    `a'       -
charsym 1n    100     nil     300     north   `d'      `c'
charsym 2n    200     big     300     north   `c'       -
@end smallexample

Assuming that all charsyms form one component, we have:

@smallexample
Rotate chains:     (1w,2w)-1e-1n @r{and} 3w-(2e,3e)-2n.
Modify chains:     1w-2w-3w @r{and} 1e-2w-3w and 1n-2n.
Horizontal chains: 1e-1w-2e-3e       @r{(for modify context @samp{a})}
                   2w-3w             @r{(for modify context @samp{b})}
Key chains:        1e-1w-2e-3e       @r{(for context @samp{a})}
                   1e-2w-2e-3w       @r{(for context @samp{b})}
                   1n-1w-2n          @r{(for context @samp{c})}
                   1n                @r{(for context @samp{d})}
@end smallexample

That makes the following bindings:

@smallexample
Rotate-to: 1w->1e, 2w->1e, 1e->1n, 1n->1w
           3w->2e, 2e->2n, 3e->2n, 2n->3w
Modify-to: 1e->1w, 1w->2e, 2e->3e, 3e->1e     @r{(horizontal chain)}
           2w->3w, 3w->2w                     @r{(horizontal chain)}
           1n->2n, 2n->1n  @r{(modify chain with exclusive modify contexts)}
CONTEXTS:  `a'->1e, `b'->1e, `c'->1n, `d'->1n
KEY:       `a1'=1e, `a2'=1w, `a3'=2e, `a4'=3e, `b1'=1e, ..., `d'=1n
@end smallexample


@node Customizing Input Methods,  , Example Char Descriptions, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Customizing Input Methods
@cindex Customizing Input Methods
@cindex Input Methods Customization

When defining contexts for characters, you should try to use default
contexts to make them and key bindings as consistent as possible.  E.g.,
package X-Symbol only defines explicit contexts for 186 of the 437
characters.

@vtable @code
@item x-symbol-group-input-alist
Defines default scores and bindings for characters of a group
(@pxref{Char Group}).  E.g., the definition (in
@code{x-symbol-latin1-table})

@lisp
(aacute 225 (acute "a" Aacute))
@end lisp

defines @code{aacute} without any explicit contexts, but having the
group @code{acute} and the subgroup @samp{a}.  The default input for the 
group is defined by the following element in this variable:

@lisp
(acute 0 "%s'" t "'%s")
@end lisp

That means: 0 is added to the normal ``modify-score'' of the character.
@samp{%s'} and @samp{'%s} with @samp{%s} substituted by the subgroup,
i.e., @samp{a'} and @samp{'a}, are the contexts for @code{aacute}.  The
context @samp{'a} is also used for input method Electric since it is
prefixed by @code{t}.

@item x-symbol-key-min-length
It is quite unlikely that a one-character context is not the prefix of
another context, at least when loading additional font definitions.  In
order not to have to change key bindings @kbd{C-= @var{key}} to @kbd{C-=
@var{key} 1}, it is required that the length of the key binding without
@kbd{C-=} is at least 2.
@end vtable

@c ====================================================================

@node Extending X-Symbol, Various Internals, Defining Input Methods, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Extending Package X-Symbol
@cindex Extending X-Symbol

In this section, you are told what to consider and what to do when
extending package X-Symbol with new characters and new token languages.
If you only want to define a token language using existing characters,
you only have to read the last section.

@menu
* Extending with Fonts::        How to add fonts to X-Symbol.
* Input Definitions::           Guidelines for input definitions.
* Font Definition File::        How to define new character in a file.
* Language Extension File::     Extending an existing language.
* Language Definition File::    Defining a new language.
@end menu


@node Extending with Fonts, Input Definitions, Extending X-Symbol, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Extending X-Symbol with New Fonts
@cindex Extending with Fonts
@cindex Adding Fonts
@cindex Font Extension
@cindex Guidelines, Font Extension

If you add a new token language to package X-Symbol which should
represent tokens by characters which are not yet defined by package
X-Symbol, you have to add a new font to package X-Symbol, first.

When adding new fonts to package X-Symbol, consider that X-Symbol has to
run under Emacs, XEmacs/Mule and XEmacs/no-Mule.

Running under Emacs and XEmacs/Mule requires that you cannot use all
encodings in a font for characters: you should probably only use
encodings 33 to 126 and 160 to 255.  You should also use a unique pair
of charset properties @samp{CHARSET_REGISTRY} and
@samp{CHARSET_ENCODING}.

Running under XEmacs/no-Mule can leads to problems when major modes do
not check whether the previous character is an escape character (in our
case, a leading character, @pxref{Char Representation}) when looking at a
character.  Thus, you should probably not use encodings which represent
characters in your default font with a special syntax.

@itemize @bullet
@item
In general, escape sequences use the digits of the current font.  Thus,
you should probably define the encodings 48 to 57 as digits @samp{0} to
@samp{9}.

@item
In La@TeX{} buffers, characters in @samp{$%\@{@}} have a special
syntax.  Thus, you should probably not use encodings 36, 37,
92, 123 and 125 for characters which could also be useful with token
languages @code{tex} and @code{utex}.

@item
In HTML buffers, characters in @samp{&<>} have a special syntax.  Thus,
you should probably not use encodings 38, 60 and 62 for
characters which could also be useful with token language @code{sgml}.
@end itemize

You have to tell package X-Symbol which fonts to use for the normal
text, subscripts and superscripts.  @xref{Installing Fonts Lisp}.

You have to tell X-Symbol, how to define Mule charsets with Emacs and
XEmacs/Mule and which leading character to use with XEmacs/no-Mule.
@xref{Defining Charsets}.


@node Input Definitions, Font Definition File, Extending with Fonts, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Guidelines for Input Definitions
@cindex Input Definitions, Guidelines
@cindex Guidelines, Input Definitions

Read section @ref{Defining Input Methods}.  Look at the tables in
@file{x-symbol.el}.  Here are some guidelines of how to define the input
methods for new characters:

@enumerate
@item
Define reasonable character groups for new characters, see @ref{Char
Group}.  E.g., if you add the IPA font for phonetic characters, you
are likely to define at least one additional charset group.  If you do
not know whether to use one or two groups for a set of characters, use
two.

@item
Define under which Grid/Menu header the character of the new character
group should appear.  You may also want to add additional headers for
these characters.  @xref{Char Group}.

@item
If reasonable, define default contexts for characters of a group, see
@ref{Customizing Input Methods}.

@item
For the other characters, define contexts by Ascii sequences which look
similar to the character.

@item
Form a component for a set of characters which are strongly related to
each other.  In most cases, characters of a component are in the same
group but not vice versa.  E.g., the simple arrows already defined by
package X-Symbol form one component.  You form a component of characters
by specifying parents in their definition, see @ref{Char Descriptions}.

@item
Use aspects to describe the new characters.  Add new aspects to
@code{x-symbol-modify-aspects-alist} and
@code{x-symbol-rotate-aspects-alist} if necessary (@pxref{Char
Descriptions}).

@item
Finish the definition of your font file (@pxref{Font Definition File}),
load it with @kbd{M-x load-file}, and initialize the input methods,
e.g., by invoking the grid (@kbd{M-x x-symbol-grid}).

@item
If there are no errors, you are likely to get warnings about equal
modify scores.  In this case, the sequence of characters in the
modify-to chain is random, so are the numerical suffixes of key bindings.

@enumerate a
@item
Define a base score for the whole X-Symbol charset (``cset score'')
which should be a positive number in order not to change the key bindings 
of previously defined X-Symbol characters.

@item
Define reasonable scores for newly defined aspects and character groups.

@item
Finally, fine-tune your definitions by charsym scores in the tables.
This should be necessary only for a few characters.
@end enumerate
@end enumerate


@node Font Definition File, Language Extension File, Input Definitions, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Emacs Lisp File Defining a New Font
@cindex Font Definition File

Now put all things together in a separate font definition file.  You
should not put it in a language definition file.

Here is a tiny example using only the lower half of the font:

@lisp
(provide 'x-symbol-myfont)
@group
(defvar x-symbol-myfont-fonts
  '(("-xsymb-myfont-medium-r-normal--14-140-75-75-p-85-xsymb-myfont")
    ("-xsymb-myfont_sub-medium-r-normal--12-120-75-75-p-74-xsymb-myfont")
    ("-xsymb-myfont_sup-medium-r-normal--12-120-75-75-p-74-xsymb-myfont")))
@end group
@group
(defvar x-symbol-myfont-cset
  '((("xsymb-myfont") ?\200 1000)
    (myfont-left "My font characters, left"  94 63) . nil))
@end group
@end lisp

@lisp
@group
(defvar x-symbol-myfont-table
  '((longarrownortheast 33 (arrow) (size big . arrownortheast))
    (koerper 34 (setsymbol "K"))
    (circleS 35 (symbol "S") nil nil "SO")))
@end group
@group
(x-symbol-init-cset x-symbol-myfont-cset x-symbol-myfont-fonts
		      x-symbol-myfont-table)
@end group
@end lisp

Due to an XEmacs bug with char syntax @code{inherit}, you should also
add the following line to files @file{x-symbol-xmas20.el} and
@file{x-symbol-xmas21.el}:

@lisp
  (modify-syntax-entry ?\200 "\\" (standard-syntax-table))
@end lisp


@node Language Extension File, Language Definition File, Font Definition File, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Emacs Lisp File Extending a Token Language
@cindex Language Definition File

If you want to use the new font to extend an existing token language,
define a new token language which inherits most variables from the
``parent language''.  E.g., token language @code{utex} inherits most
variables from @code{tex}, see @file{x-symbol-utex.el}.

A language must define variables for all language aspects, see
@ref{Language Internals}.  Our example defines a language @code{mytex}
using the additional characters from @ref{Font Definition File}.

First, you have to register the language in a startup file:

@lisp
(defvar x-symbol-mytex-name "My TeX macro")
(defvar x-symbol-mytex-modes nil)
(x-symbol-register-language 'mytex 'x-symbol-mytex x-symbol-mytex-modes)
@end lisp

The language definition file should look like (leaving out most parts
which are similar to the ones in @file{x-symbol-utex.el}):

@lisp
(provide 'x-symbol-mytex)
(require 'x-symbol-tex)
(defvar x-symbol-mytex-required-fonts '(x-symbol-myfont))
(put 'mytex 'x-symbol-font-lock-keywords 'x-symbol-tex-font-lock-keywords)
@end lisp

@lisp
(defvar x-symbol-mytex-user-table nil)
@group
(defvar x-symbol-mytex-myfont-table
  '((longarrownortheast (math arrow user) "\\longnortheastarrow")
    (koerper (math letter user) "\\setK")
    (circleS (math ordinary amssymb) "\\circledS")))
@end group
@group
(defvar x-symbol-mytex-table
  (append x-symbol-mytex-user-table
          '(nil)
          x-symbol-mytex-myfont-table
          x-symbol-tex-table))
@end group
@end lisp

It is important that you do not define a variable for the language
access @code{x-symbol-font-lock-keywords}, but rather use the variable
of the parent language directly, see @ref{Language Internals}.

During the testing phase, you should probably leave out the
@samp{'(nil)} which prevents warnings about redefinitions for the
following elements.


@node Language Definition File,  , Language Extension File, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Emacs Lisp File Defining a New Token Language
@cindex Language Definition File

You might also want to define a new token language not based on another
language.

As an example, consider a token language ``My Unicode'' (@code{myuc})
for buffers with major mode @code{myuc-mode}.  Thus, we register the
language by:

@lisp
(defvar x-symbol-myuc-name "My Unicode")
(defvar x-symbol-myuc-modes '(myuc-mode))
(x-symbol-register-language 'myuc 'x-symbol-myuc x-symbol-myuc-modes)
@end lisp

Each token if language @code{myuc} consists of @samp{#} plus the
hexadecimal representation of the Unicode with hexadecimal values where
the case of digits is not important and the preferred case is upcase.  A 
single @samp{#} is represented by the token @code{##}.  In order to be
more flexible, we want to define the tokens by their decimal value in
the table.  There are no subscript and no images.  The code below
(@file{x-symbol-myuc.el}) is included in the source distribution of
package X-Symbol.

@lisp
(provide 'x-symbol-myuc)
(defvar x-symbol-myuc-required-fonts nil)
(defvar x-symbol-myuc-modeline-name "myuc")
@group
(defvar x-symbol-myuc-class-alist
  '((VALID "My Unicode" (x-symbol-info-face))
    (INVALID "no My Unicode" (red x-symbol-info-face))))
@end group
(defvar x-symbol-myuc-font-lock-keywords nil)
(defvar x-symbol-myuc-image-keywords nil)
@dots{}
@end lisp

@lisp
(defvar x-symbol-myuc-case-insensitive 'upcase)
(defvar x-symbol-myuc-token-shape '(?# "#[0-9A-Fa-f]+\\'" . "[0-9A-Fa-f]"))
(defvar x-symbol-myuc-exec-specs '(nil (nil . "#[0-9A-Fa-f]+")))
(defvar x-symbol-myuc-input-token-ignore nil)
@end lisp

@lisp
@group
(defun x-symbol-myuc-default-token-list (tokens)
  (list (format "#%X" (car tokens))))
@end group
(defvar x-symbol-myuc-token-list 'x-symbol-myuc-default-token-list)
(defvar x-symbol-myuc-user-table nil)
@group
(defvar x-symbol-myuc-xsymb0-table
  '((alpha () 945) (beta () 946)))
@end group
@group
(defvar x-symbol-myuc-table
  (append x-symbol-myuc-user-table x-symbol-myuc-xsymb0-table))
@end group
@dots{}
@end lisp

@c ====================================================================

@node Various Internals, Design Alternatives, Extending X-Symbol, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Various Internals

@menu
* Tagging Insert Commands::     Don't break input methods Token and Electric.
* Avoiding Flickering::         Moving cursor in invisible commands.
@end menu


@node Tagging Insert Commands, Avoiding Flickering, Various Internals, Various Internals
@comment  node-name,  next,  previous,  up
@subsection Tagging Insert Commands for Token and Electric
@cindex Insert Commands, Tagging
@cindex Tagging Insert Commands
@cindex Recognizing Insert Commands

Input methods Token (@pxref{Input Method Token}) and Electric
(@pxref{Input Method Electric}) stop their auto replacement if you use a 
command which is not an insert command.

@ftable @code
@item self-insert-command
@itemx newline
@itemx newline-and-indent
@itemx reindent-then-newline-and-indent
@itemx tex-insert-quote
@itemx TeX-insert-quote
@itemx TeX-insert-punctuation
@itemx TeX-insert-dollar
@itemx sgml-close-angle
@itemx sgml-slash
These commands and commands aliased to these are recognized as input
commands by having a non-@code{nil} value of its symbol property
@code{x-symbol-input}.
@end ftable


@node Avoiding Flickering,  , Tagging Insert Commands, Various Internals
@comment  node-name,  next,  previous,  up
@subsection Avoiding Hide/Show-Invisible Flickering
@cindex Avoiding Flickering
@cindex Flickering, Invisible
@cindex Invisible Flickering

Starting a command makes a previously revealed super- or subscript
command (@pxref{Super and Subscripts}) invisible again.  Repeatedly
invoking commands which moves the point just by a small amount can lead
to some flickering.

@ftable @code
@item forward-char
@itemx forward-char-command
@itemx backward-char
@itemx backward-char-command
If the point position after the execution of these commands is still
``at'' the super- or subscript command, the command won't be made
invisible at the first place.  Each of these four commands have a
function (@code{1+} and @code{1-}) as the value of its symbol property
@code{x-symbol-point-function} which returns the position ``after'' when
called with the position ``before''.
@end ftable

@c ====================================================================

@node Design Alternatives, Language Internals, Various Internals, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Design Alternatives

This section describes potential design alternatives and why they were
not used.

@menu
* Alt Token Representations::   Why we need the conversion.
* Alt Global Mode::             How to turn on X-Symbol globally.
* Alt Auto Conversion::         When do we convert automatically.
@end menu


@node Alt Token Representations, Alt Global Mode, Design Alternatives, Design Alternatives
@comment  node-name,  next,  previous,  up
@subsection Alternative Token Representations
@cindex Alternative Token Representations
@cindex Token Representation, Alternatives

Package X-Symbol represents tokens in the file by characters in the
buffer.  This requires an automatic conversion when visiting a file or
saving a buffer, see @ref{Conversion}.

Another possibility would be to use the tokens directly in the buffer
and just display them differently.  You would need no conversion and you
could copy the text easily to a message buffer.  This could be done by a
special face and an additional font-lock keyword for every token.  The
disadvantages make this approach unfeasible:

@itemize @bullet
@item
The editing commands would work on the tokens which are invisible for
the user.

@item
Extremely resource and startup-time consuming.  If as many characters
should be supported as done by package X-Symbol, including superscripts
and subscripts, more than 2000 faces with display tables would have to
be defined even without considering char aliases!

@item
Time consuming.  More than 2000 entries in you font-lock keywords would
slow down the fontification considerably, which would be too much even
when using @code{lazy-shot}!
@end itemize

Another possibility would be to adapt @TeX{} to the representations of
the corresponding characters in Emacs' buffer.  Again, you would need no
conversion.  The disadvantages make this approach too restrictive:

@itemize @bullet
@item
You cannot adopt @sc{sgml} to this approach.

@item
You cannot read normal La@TeX{} files directly, you do not write normal
La@TeX{} files.

@item
You would have different @TeX{} versions: one for X-Symbol with Emacs
and XEmacs/Mule, one with XEmacs/no-Mule.

@item
If you are not an extremely good @TeX{} hacker, it would be impossible
to adopt this approach to support more than 256 characters.
@end itemize

A third alternative would be very similar to the method used in this
package.  There would be just a slight difference when running under
XEmacs/no-Mule: the internal representation of a character is always
just one character, but we would also provide font properties for
characters not of your default font.  The disadvantages make this
approach too unsafe:

@itemize @bullet
@item
Problems with current search/replace commands.

@item
Problems with the current version of @code{font-lock} (it should @emph{never}
overwrite the font property for this character, even if the character
matches some @var{match} in @code{font-lock-keywords} and
@var{overwrite} is non-@code{nil}).  This gets even more difficult with
superscripts/subscripts.

@item
Unless you can provide a syntax table for faces (you cannot), characters
in different faces with the same encoding are in the same syntax class,
which is irritating: e.g., @code{\leftrightarrow} and @code{\approx}
would be delimiters.
@end itemize


@node Alt Global Mode, Alt Auto Conversion, Alt Token Representations, Design Alternatives
@comment  node-name,  next,  previous,  up
@subsection Alternative Ways to Turn on X-Symbol Globally
@cindex Alternative Global Mode
@cindex Global Mode, Alternatives
@cindex Turn on Globally, Alternatives

This package hooks itself into @code{hack-local-variables-hook} which
makes the installation very simple.

Another possibility would be to use the major-mode hooks which is the
normal way how to turn on a minor mode.  The disadvantages are:

@itemize @bullet
@item
The installation is more complicated.

@item
Local variables in files are not yet processed (this was the main reason
not to do it this way).
@end itemize

Another possibility would be to hook X-Symbol into
@code{find-file-hooks}, as it is done in old versions of package
X-Symbol.  It would be as easy as the current approach but we would have
to be careful with sequence of functions in @code{find-file-hooks},
especially with the function hooked in by @code{font-lock}.


@node Alt Auto Conversion,  , Alt Global Mode, Design Alternatives
@comment  node-name,  next,  previous,  up
@subsection Alternative Auto Conversion Methods
@cindex Alternative Auto Conversion
@cindex Auto Conversion, Alternatives

@vindex hack-local-variables-hook
@vindex after-insert-file-functions
@vindex write-region-annotate-functions
Without package @code{crypt}, this package automatically decodes tokens
when turning on the minor mode (in @code{hack-local-variables-hook},
@pxref{Alt Global Mode}) or in @code{after-insert-file-functions}.  This
package automatically encodes characters in
@code{write-region-annotate-functions}.  The disadvantage is that the
possibility to change buffers in @code{write-region-annotate-functions}
is not official (@pxref{Wishlist Emacs}), i.e., not mentioned in the
docstring (only mentioned for corresponding encode-functions of package
@code{format} which use a similar loop in the C code).

@vindex write-file-hooks
With package @code{crypt}, this package automatically decodes tokens
when turning on the minor mode.  This package automatically encodes
characters in @code{write-file-hooks}.  The disadvantage is that the
encoding is slower (use @code{jka-compr} instead @code{crypt}) and the
problem with @code{vc-next-action} (@pxref{Spurious Encodings}).

@vindex write-file-data-hooks
Without package @code{crypt}, Version 2.6 of this package automatically
encoded characters in @code{write-file-data-hooks}.  The advantage was
that changing buffers there is official, the disadvantage is that it is
also more complicated.

@pindex format
A totally different method would be to use package @code{format}.
Unfortunately, this is not really possible, since a @var{regexp} in
@code{format-alist} is much too weak, i.e., X-Symbol's decoding does not
change any file headers which would represent the file format.  In
XEmacs, this package also fails to work properly with @code{jka-compr}
and @code{crypt}.

@c ====================================================================

@node Language Internals, Misc Internals, Design Alternatives, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Language Internals
@cindex Language Internals
@cindex Token Language Internals
@cindex Internals, Languages
@cindex Registered Languages
@cindex Loaded Language
@cindex Initialized Language
@cindex Language Access
@cindex Accessing Language Depending Variables

In order to use a token language or accessing one of the language
dependent values, the following conditions must be met:

@itemize @bullet
@item
The language must be @dfn{registered}.  This makes it possible to select
the language in the menus.  It also prevents to load a potentially
dangerous file when a file specifies a buffer-local value of
@code{x-symbol-language}.

@ftable @code
@item x-symbol-register-language
Registering a language includes stating the name of the feature (i.e., a
file) which provides the language.  The name of the language must have
been already defined.
@end ftable

@item
The file providing the language must have been @dfn{loaded}.  This will
be done automatically when the language is initialized.  Customizing
X-Symbol will also load the language files.

@item
The language must be @dfn{initialized}.  This will be done automatically
if the language is used.  This loads the language file and fails if the
language has not been registered.  If some minor language information is
needed, e.g., in the highlight menu of the Grid (@pxref{Input Method
Grid}), you should initialize the language explicitly, e.g., by the
following command:

@table @kbd
@item M-x x-symbol-init-language-interactive
@findex x-symbol-init-language-interactive
Initialized a token language if it is not already initialized.
@end table
@end itemize

Language dependent values are accessed by language accesses:

@table @code
@item x-symbol-language-value
@findex x-symbol-language-value
Returns the language depending value.  Also initializes language if
necessary.  E.g., we get the name of a language by the language access
@code{x-symbol-name}.  With a simplified expansion, we get

@lisp
(x-symbol-language-value 'x-symbol-name 'tex)
     @expansion{} (symbol-value (get 'tex 'x-symbol-name))
     @result{} (symbol-value 'x-symbol-tex-name)
     @result{} "TeX macro"
@end lisp

@item x-symbol-language-access-alist
@vindex x-symbol-language-access-alist
List of all language accesses.  A token language @emph{must} define all
variables accessed by language accesses.  A @dfn{language access} is a
property of the language symbol, its value is the symbol naming a
variable whose value is used.

If the language is a derived language, e.g., like language @code{utex},
the language access @code{x-symbol-font-lock-keywords}, should point
directly to the variable of the parent language (here @code{tex}), see
file @file{x-symbol-utex.el}.
@end table


@c Hi, X-Symbol's interna have changed considerably with v4.3.1-alpha.  For
@c token languages to work with new versions of X-Symbol, it is important
@c to define some new language accesses (you
@c can also delete some if you do not want X-Symbol backward compatiblity)

@c The reason for the change is:

@c  * more general ways to define the "grammar" of tokens, also useful for
@c    ProofGeneral's languages, see below.
@c  * faster conversion (I also dropped the support of executables)


@c As an example, let's look at x-symbol-texi.el:

@c The following vars must now be defined (value nil...)

@c    (defvar x-symbol-texi-generated-data nil)

@c Now the interesting part:

@c (defvar x-symbol-texi-token-grammar
@c   '(x-symbol-make-grammar
@c     :encode-spec (?@)
@c     :decode-regexp
@c     "@\\(?:[A-Za-z]+{[A-Za-z]?}\\|[{}]\\|[~^\"'`][A-Za-z]\\|,{[A-Za-z]}\\)"
@c     :decode-spec (?@))
@c   "Token grammar for language `texi'.")

@c In short, not too difficult if the token grammar is regular (even
@c simpler for SGML entities).  The good news: powerful enough for
@c irregular token grammar which couldn't be defined with previous versions
@c of X-Symbol.

@c The conversion now works as follows:

@c  1. decode (token->char): search for regexp, then decode match except if
@c     context is "bad".
@c  2. encode (char->token): search for non-ascii/8bit, then encode match.
@c     Surround by spaces if context is "bad".

@c The "token grammar" is simply a definition of the regexp and the bad
@c contexts, which can be different for different "shapes" of the token.
@c A special BEFORE context is the escape character: this character may
@c appear exactly even times before the token; it will be used for
@c all shapes.

@c Lets assume a language "Isabelle Symbol" plus symbols for identifiers
@c and operators (see below for lisp coding):

@c   shape nil:  \<NAME>
@c   shape id:   [A-Za-z_][A-Za-z_0-9]+
@c   shape op:   [<>!+-*/|&]+

@c To make the conversion fast, the shape must be given at definition time,
@c i.e., the init must get tokens in the form (TOKEN . SHAPE).
@c Either per hand or computed via function in language access
@c x-symbol-token-list...

@c The decode-regexp must match all tokens and:

@c  a. should be specific enough to make the conversion fast
@c  b. must be general enough to match strings which should not be
@c     considered to contain a token even if a substring is a token (to
@c     avoid excessive context checking)

@c In our example, the regexp would be something like

@c   "\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+"

@c No bad context has to be defined for decoding since the regexp is
@c general enough.

@c For encoding, we have to define the following bad contexts (no context
@c can be defined for shape nil):

@c   shape id:  BEFORE: [A-Za-z_0-9], AFTER: [A-Za-z_0-9]
@c   shape op:  BEFORE: [<>!+-*/|&],  AFTER: [<>!+-*/|&]

@c BEFORE is a regexp used via `string-match' with the character before the
@c character to encode; if it matches, we put a space before the token for
@c the character.  AFTER is a regexp used with `looking-at' with point
@c after the character.  We would put a space after the token.

@c There is probably no escape char defined for Isabelle Symbols (i.e.,
@c "\\" is no token).

@c The input-token-grammar is very similar to the decode-grammar: the
@c regexp should end with \\' such that only matches ending at point will
@c get replaced, and we should define a bad context (which will be
@c tried to match against `last-command-char').

@c This makes the grammar below.

@c Hope this helps,
@c - Christoph


@c (defvar x-symbol-xisa-token-grammar
@c   '(x-symbol-make-grammar
@c     :encode-spec '(((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")) .
@c  		  ((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")))
@c     :decode-spec nil
@c     :decode-regexp "\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+"
@c     :token-list #'x-symbol-xisa-default-token-list))

@c (defvar x-symbol-xisa-input-token-grammar
@c   '(("\\(?:\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+\\)\\'")
@c     ((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]"))
@c     (id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")))

@c (defun x-symbol-xisa-default-token-list (tokens)
@c   (mapcar (lambda (x)
@c 	    (cons x (cond ((string-match "\\`[A-Za-z_][A-Za-z_0-9]+\\'" x) 'id)
@c 			  ((string-match "\\`[<>!+-*/|&]+\\'" x) 'op))))
@c 	  tokens))

@c (defun x-symbol-xisa-table
@c   '((product () "\\<Prod>")
@c     (longarrowright () "-->")
@c     (alpha () "alpha")))


@c ====================================================================

@node Misc Internals,  , Language Internals, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Miscellaneous Internals

TODO.  This is currently just a collection of unrelated stuff.

@c was in "Char Group
Characters might also define a @dfn{subgroup} which is a string defining
some order on characters in the same group (@pxref{Char Group}) and is
also used for default contexts/bindings (@pxref{Customizing Input
Methods}).

@vtable @code
@item x-symbol-group-syntax-alist
Lists all valid character groups.  Under Emacs and XEmacs/Mule, this
list also determines the syntax of characters.
@end vtable

The character group could probably also be used to define character
categories if they are implemented in XEmacs.

@c ===========================================================================

@node Problems, History, X-Symbol Internals, Top
@comment  node-name,  next,  previous,  up
@chapter Problems, Troubleshooting
@cindex Problems
@cindex Troubleshooting
@cindex Annoyances
@cindex Bugs

This section is based on a successful installation of package X-Symbol.
@xref{Checking Installation}.

@menu
* Nomule Problems::             X-Symbol provides a @emph{poor} man's Mule.
* Spurious Encodings::          Some commands turn off X-Symbol mode.
* No Encoding::                 The encoding does not work in a rare case.
* FAQ::                         Frequently asked questions.
* Bug Reports::                 How to contact the maintainer of X-Symbol.
@end menu

@c ===========================================================================

@node Nomule Problems, Spurious Encodings, Problems, Problems
@comment  node-name,  next,  previous,  up
@section Problems under XEmacs/no-Mule
@cindex Nomule Problems
@cindex @code{transpose-chars} Problems
@cindex Replace Problems
@cindex Rectangle Problems
@cindex Abbrev Problems
@cindex Invisible Point
@cindex Parenthesis Problems
@cindex Fill Problems

If you use package X-Symbol under XEmacs/no-Mule, there are some
annoyances which result from the fact that additional ``X-Symbol
characters'' are represented by two characters internally.  Package
X-Symbol just provides a kind of ``@emph{poor} man's Mule'', see
@ref{Poor Mans Mule}.  This means: I have provided workarounds for the
most annoying ones, but some remain (and will remain: I am not going to
provide workarounds for these):

@itemize @bullet
@item
If @code{font-lock} is not prepared to display these two-character
sequences, i.e., if you installation is incomplete (@pxref{Role of
font-lock}), they look like @samp{\233a} instead @code{alpha}.

@item
Commands which add more than one entry to the @code{buffer-undo-list}
and involve X-Symbol characters might lead to strange results,
e.g. @kbd{C-t} (@code{transpose-chars}) with point between character
@code{alpha} and @samp{b}, leads to @code{beta}@samp{a}.  Simple
deletion and insertion works OK, though.

@item
Selecting or inserting a rectangle with X-Symbol characters on the left
or right margin might not work properly.

@item
Be careful with @kbd{M-%} (@code{query-replace}): the first character of
@var{from-string} can probably match the second of the two ``internal''
characters of an X-Symbol character.

@item
If you use @kbd{C-x '} (@code{expand-abbrev}) without @kbd{M-'}
(@code{abbrev-prefix-mark}) and the last word before point starts
directly after a X-Symbol character, @kbd{C-x '} could behave strange:

@itemize @minus
@item
If @code{words-include-escapes} is @code{t}, there will be no expansion.

@item
If @code{words-include-escapes} is @code{nil}, the second ``internal''
character could be the first character of the last word before point
which is going to be replaced by the abbrev mechanism.
@end itemize

@item
If the character under point is a X-Symbol character, you will not see
the cursor if you exit a command with an error or with quit (@kbd{C-g}).
Unfortunately, XEmacs (as opposed to Emacs) does not run the hooks in
@code{post-command-hook} in these cases.  Solution: move point right
(@kbd{C-f}).

@item
If you provide prefix arguments to commands, they are likely to consider
just ``internal'' characters.  E.g., @kbd{C-u 2 C-f} before @code{alpha}
behaves like @kbd{C-f}.

@item
Column position considers ``internal'' characters, e.g., @kbd{C-n} might
jump to an unexpected position (well, typically just one character
left/right from the expected position, if at all).

@item
Auto-filling also considers ``internal'' characters, i.e., might break
the line too early.

@item
There are no syntax definitions for the new characters, e.g.,
@kbd{M-C-f} before @code{floorleft} does not move to the closing
@code{floorright}.

@item
In some cases, e.g., when using the minibuffer for input via @kbd{M-%}
or @kbd{C-s}, the internal representation of X-Symbol characters
(@pxref{Char Representation}) are displayed directly (@pxref{FAQ Strange
Chars})
@end itemize

@c ====================================================================

@node Spurious Encodings, No Encoding, Nomule Problems, Problems
@comment  node-name,  next,  previous,  up
@section Spurious Encodings
@cindex Spurious Encodings
@cindex Version Control Problems
@cindex @code{write-file} Problems
@cindex @code{vc} Problems
@cindex Revert Buffer Problems

@pindex vc
In rare cases, some commands (mostly from package @code{vc}) encode
characters to tokens or even turn off X-Symbol mode.  Package X-Symbol
will not provide a workaround for these problems, because the situations
in which they appear are too rare, the workarounds are easy, and the
problems are not really caused by package X-Symbol.

@itemize @bullet
@item
@pindex crypt
Doing the next logical version control operation (@kbd{C-x v v} and
friends) encode characters to tokens when using package @code{crypt}.

Solution: use package @code{jka-compr} instead @code{crypt} (this is
recommended anyway, @pxref{File IO Packages}).  Or kill the buffer and
revisit the file.

@item
@pindex auctex
When using Auc@TeX{} with its default-mode algorithm, getting rid of the
recently checked-in version of a file without reverting the buffer
afterwards (@kbd{C-u C-x v c}) turns off X-Symbol mode without encoding
the characters, e.g. under XEmacs/no-Mule, you see some strange
characters like @samp{\233a}.

Explanation: when using Auc@TeX{}'s @code{TeX-default-mode}, the final
@code{major-mode} is different from the initial @code{major-mode}
deduced using @code{auto-mode-alist}.  If this is the case, the VC
command executes @code{normal-mode} which kills all local-variables
including turning-off @code{x-symbol-mode}.

Solution: Turn on X-Symbol mode or change @code{auto-mode-alist} to
directly choose @code{latex-mode}:

@lisp
(push '("\\[tT]e[xX]\\'" . latex-mode) auto-mode-alist)
@end lisp

@item
@findex write-file
@vindex change-major-mode-with-file-name
When using Auc@TeX{} with its default-mode algorithm, writing a La@TeX{}
buffer into a file with another file name turns off X-Symbol mode.

Explanation: Emacs sets the major mode with the file name.  When using
Auc@TeX{}'s @code{TeX-default-mode}, we get the problems as described in
the previous item.

Solution: Set @code{change-major-mode-with-file-name} to @code{nil} or
use the solution from the previous item.
@end itemize

@c ====================================================================

@node No Encoding, FAQ, Spurious Encodings, Problems
@comment  node-name,  next,  previous,  up
@section The Encoding Does Not Work
@cindex No Encoding
@cindex @code{write-region} Problems

In a rare case, X-Symbol cannot do its encoding, i.e., convert the
characters to tokens.

@itemize @bullet
@item
@findex write-region
@pindex crypt
@vindex write-file-hooks
@kbd{M-x write-region} fails to do the encoding if you use package
@code{crypt}.

Explanation: with package @code{crypt}, the encoding has to be done by a
function in @code{write-file-hooks} which is not used by
@code{write-region}.

Solution: use package @code{jka-compr} instead @code{crypt} (this is
recommended anyway, @pxref{File IO Packages}).  Or visit the region file
and save it again via @kbd{C-x C-s}.
@end itemize


@c ===========================================================================

@node FAQ, Bug Reports, No Encoding, Problems
@comment  node-name,  next,  previous,  up
@section Frequently Asked Questions
@cindex Frequently Asked Questions
@cindex FAQ X-Symbol

It is assumed that you had successfully installed package X-Symbol, see
@ref{Checking Installation}.

@menu
* FAQ XEmacs Core::             XEmacs crashes when using input method Token
* FAQ font-lock::               X-Symbol's fontification does not work.
* FAQ Strange Chars::           The buffer contains strange characters
* FAQ No Subscripts::           I cannot see any/some super-/subscripts.
* FAQ Stupid Subscripts::       I see subscripts where I don't want them.
* FAQ Font Size::               The characters are too small or too big.
* FAQ Conversion::              The conversion changes some tokens.
* FAQ Additional Spaces::       A space is added during the encoding.
* FAQ 8bit Chars::              I do not want 8bit characters in the file.
* FAQ Hyphen::                  I cannot distinguish @code{hyphen} from @samp{-}.
* FAQ Spell Check::             I have problems with spell-checking.
* FAQ News and Mail::           I want to use X-Symbol in Gnus or @sc{vm}.
@end menu


@node FAQ XEmacs Core, FAQ font-lock, FAQ, FAQ
@comment  node-name,  next,  previous,  up
@subsection XEmacs Crashes when using Input Method Token
@cindex XEmacs Core
@cindex Core XEmacs
@cindex Crash XEmacs
@cindex Input Method Token

It has been reported that XEmacs-21.0 to XEmacs-21.1.8 might produce
cores when you use input method Token.  That's why I strongly recommend
to use XEmacs-21.1.9 or higher with package X-Symbol, see
@ref{Requirements}.

You get a warning during X-Symbol's initialization when using these
XEmacs versions.  If you don't want to upgrade, but also don't want to
see the warning, you might want to set variable
@code{x-symbol-xmas-warn-about-core} to @code{nil}.

A core in XEmacs always indicates a bug in XEmacs itself, not in a Lisp
package like X-Symbol.  Thus, send a bug report to the XEmacs team if
you get cores with the @emph{newest} version of XEmacs (please put me in
the CC).


@node FAQ font-lock, FAQ Strange Chars, FAQ XEmacs Core, FAQ
@comment  node-name,  next,  previous,  up
@subsection X-Symbol's Fontification does Not Work
@pindex font-lock
@cindex No fontification
@cindex @code{font-lock} Problems

In this case, super- and subscripts are not properly displayed
(@pxref{FAQ No Subscripts}) and under XEmacs/no-Mule, the buffer
contains s.th. like @samp{\233a} (@pxref{FAQ Strange Chars}).
Possible causes:

@itemize @bullet
@findex x-symbol-fontify
@item
You have turned off @code{font-lock} or @code{font-lock} is out of sync.
Use @kbd{M-x x-symbol-fontify}.  @xref{Role of font-lock}.

@item
The font-lock keywords of the current buffer are not prepared to display
X-Symbol characters.  @xref{Role of font-lock}.

@item
@vindex fast-lock-save-faces
You use package @code{fast-lock}.  Solution: set
@code{fast-lock-save-faces} to @code{nil} (done by default
installation).

@item
You use some version control commands.  You have probably noticed that
these versions control commands also turn off @code{font-lock} in modes
where you don't use X-Symbol, i.e., this is not a problem of package
X-Symbol.  @xref{Wishlist Emacs}.  @xref{Spurious Encodings}.
@end itemize


@node FAQ Strange Chars, FAQ No Subscripts, FAQ font-lock, FAQ
@comment  node-name,  next,  previous,  up
@subsection The Buffer Contains Strange Characters
@cindex Strange Characters
@cindex Funny Characters
@cindex Character Problems
@cindex Escape Character Problems
@pindex Mathematica

If you see s.th. like @samp{\233a}, you see the internal representation
of X-Symbol characters under XEmacs/no-Mule (@pxref{Char
Representation}) directly.  Possible causes:

@itemize @bullet
@item
You have @code{font-lock} problems, see @ref{FAQ font-lock}.

@item
More complicated editing commands like @kbd{C-t} may produce strange
character sequences which do not represent X-Symbol characters, see
@ref{Nomule Problems}.

@item
In some cases, e.g., when using the minibuffer for input via @kbd{M-%}
or @kbd{C-s}, it would be too much work to fontify these character
sequences in order to display proper X-Symbol characters.  @xref{Nomule
Problems}.
@end itemize

If Emacs shows some strange glyphs for some characters in your buffers
but not the Grid, there is a font in you font path which pretends to
have charset registry-encoding @code{adobe-fontspecific}, but in fact
uses another encoding.  E.g., Mathematica's fonts cause the characters
intersection and union to mix up.  Possible solutions:

@itemize @bullet
@item
Delete that font from the font path.  Maybe moving it at the end also
works.

@item
In Emacs-21, you have the chance to disable the use of some fonts (if
you know something similar for XEmacs, please let me know).  For
example, to disable the fonts from Mathematica, use

@lisp
(setq face-ignored-fonts '("\\`-wri-math1"))
@end lisp

@item
If the characters show up correctly initially, but mix up after some
font changing command, don't use that command.  E.g., the font selection
in XEmacs via the Options menu seems to loose some information about the
original font.  OK, this is not really a satisfying solution, but the
whole issue isn't my fault, either.
@end itemize


@node FAQ No Subscripts, FAQ Stupid Subscripts, FAQ Strange Chars, FAQ
@comment  node-name,  next,  previous,  up
@subsection I Cannot See any/some Super- or Subscripts
@cindex No Subscripts
@cindex Subscript Problems
@cindex Superscript Problems

If you cannot select @samp{Super-/Subscripts} in the menu, the first of
the following points is more likely the cause, the others otherwise.

@itemize @bullet
@item
You have @code{font-lock} problems, see @ref{FAQ font-lock}.

@item
There are cases where super- and subscripts are not displayed, see
@ref{Super and Subscripts}.

@item
The argument in braces are not correctly recognized, since the
@code{font-lock} syntax-table is not correct.  It should include
@samp{@{} as the only open parenthesis and @samp{@}} as the only close
parenthesis character.  Note that this is quite difficult to archive
under Emacs and XEmacs/Mule.  This is a minor bug in the corresponding
@code{font-lock} package, but would require other changes there,
therefore not likely to be fixed.  Fortunately, this does not happen
often.
@end itemize


@node FAQ Stupid Subscripts, FAQ Font Size, FAQ No Subscripts, FAQ
@comment  node-name,  next,  previous,  up
@subsection I See Super- and Subscripts where I Don't Want Them.
@pindex font-lock
@pindex font-latex
@cindex Stupid Subscripts
@cindex Annoying Subscripts
@cindex Label Subscripts
@cindex Subscript Problems
@cindex Superscript Problems

E.g., I see a subscript in arguments of @code{\label}.  Package X-Symbol
only uses super- and subscripts if they are in braces, if the
@code{asciicircum}/@code{underscore} has not been fontified yet or is
only fontified with faces which are allowed by
@code{x-symbol-tex-font-lock-allowed-faces}, see @ref{Super and
Subscripts}.

@itemize @bullet
@item
You use the default @code{tex-font-lock-keywords}: The argument of
@code{\include} and friends are not fontified by these, i.e., the use of super-
and subscripts are not prohibited.  Solution: add your own keyword for
these commands or use package @code{font-latex}, see below.

@item
You use package @code{font-latex}.  Solution: set
@code{font-lock-maximum-decoration} to value @code{t}, 2 or higher.
Package X-Symbol will still use subscripts in @code{\verb}, in the
@code{verbatim} environment, in the argument of @code{\includegraphics}
and probably other commands.  Some of these problems will probably be
solved by future versions of @code{font-latex}.

@item
You use my font-lock keywords (file @file{x-font-lock.el}): everything
should work fine.  Please note that this file is not meant to be a
replacement of @file{font-latex.el} useful to all users.  Also,
highlighting is a matter of taste, i.e., I am not going to change the
@file{x-font-lock.el} to support La@TeX{}-2.09, @TeX{}'s math regions,
other likings, etc.

@item
You use your own font-lock keywords for @TeX{}.  In this case, you be able
to adapt the solutions from the previous points to your situation.
@end itemize


@node FAQ Font Size, FAQ Conversion, FAQ Stupid Subscripts, FAQ
@comment  node-name,  next,  previous,  up
@subsection The Characters are Too Small or Too Big
@cindex Font Size
@cindex Big Characters
@cindex Small Characters

Why aren't there more different font sizes?  Because nobody (including
the author) was in the mood to design them (actually only the xsymb1
font needs to be designed).  @emph{Please do only ask the author whether they
are in work if you are serious to do it yourself otherwise!}

Why do I get a lower-case letter when I should get a capital letter (or
vice versa)?  Please convince yourself (@pxref{Info}) that you actually
get the correct letter---they are just of different sizes.
@xref{Installing Fonts Lisp}.

I was told that the xsymb1 font scales reasonably well to a larger font
size---if you don't think so, design a new font and send me the result.


@node FAQ Conversion, FAQ Additional Spaces, FAQ Font Size, FAQ
@comment  node-name,  next,  previous,  up
@subsection The Conversion Changes Some Tokens
@cindex Token Changes
@cindex Conversion Problems
@cindex Encoding Problems

In most token languages, a character might be represented by different
tokens.  If this character is encoded (when saving the buffer), the
canonical representation is saved.  @xref{Unique Decoding}.

@itemize @bullet
@item
Solution: Do not redefine standard @TeX{} macros or use unique
decoding.  @xref{TeX Macro Problems}.
@end itemize


@node FAQ Additional Spaces, FAQ 8bit Chars, FAQ Conversion, FAQ
@comment  node-name,  next,  previous,  up
@subsection A Space is Added During the Encoding
@cindex Additional Spaces
@cindex Token Problems
@cindex Encoding Problems
@cindex Space Problems

A space is added after some characters during the encoding to tokens.
With token languages @code{tex} and @code{utex} (not with language
@code{sgml}), there must be a space after the token to recognize its end
in some cases.

E.g., if your buffer contains @samp{a+b} (where + stands for the
character @code{circleplus}), this is encoded to @samp{a\oplus b} (note
the space after @code{\oplus}).  Decoding it yields @samp{a+ b}.

I admit, this looks ugly.  The space is only added if the symbol
character is followed by a letter or by @samp{@@}.  Thus, decoding
@samp{a\oplus\beta} yields @samp{a+b} (without space!).

@itemize @bullet
@item
Suggestion: Also use a space before @code{\oplus}.  The alternative
would be to delete the space which other people won't like.
@end itemize

For an exact description, @xref{TeX Macro Conversion} for an exact description.


@node FAQ 8bit Chars, FAQ Hyphen, FAQ Additional Spaces, FAQ
@comment  node-name,  next,  previous,  up
@subsection I Don't Want 8bit Characters in the File
@cindex 8bit Character Problems
@cindex No 8bit Characters

By default, these are not encoded if the buffer-local variable
@code{x-symbol-8bits} is non-@code{nil}.

By default, this variable is only set to non-@code{nil}, if something like

@example
\usepackage[latin1]@{inputenc@}
@end example

is found at the beginning of the file.  That line does not make sense if
you do not have 8bit characters in the file, i.e., delete it.
@xref{File Coding}.  Note: commenting the line is not enough!  (I do not
run La@TeX{} to check for the line, I just do plain text search.)


@node FAQ Hyphen, FAQ Spell Check, FAQ 8bit Chars, FAQ
@comment  node-name,  next,  previous,  up
@subsection I Cannot Distinguish Character @code{hyphen} from @samp{-}
@cindex Hyphen Versus Minus
@cindex Minus Versus Hyphen

In most fonts, the Latin character @code{hyphen} cannot be distinguish
from the Ascii character @samp{-}.  If you do not want to decode the
corresponding token @code{\-} or @code{&shy;}, put the following into
your @file{~/.emacs}:

@lisp
(setq x-symbol-tex-user-table '((hyphen)))
(setq x-symbol-sgml-user-table '((hyphen)))
@end lisp

A better alternative would be to make @code{font-lock} display these
character in a different color.


@node FAQ Spell Check, FAQ News and Mail, FAQ Hyphen, FAQ
@comment  node-name,  next,  previous,  up
@subsection Problems with Spell-checking
@cindex Spell Checking
@pindex ispell
@findex ispell-word
@findex ispell-region

As explained in @ref{Miscellaneous Packages}, @code{ispell} assumes the
buffer contents to be the same as the file contents and does not provide
any hook to fix this.  This might break @code{ispell-word} and
@code{ispell-region}.  Possible symptoms:

@itemize @bullet
@item
A word which contains letters which the program @code{ispell} does not
know about is either not spell-checked or parts of it are spell-checked
as independent words.

Solution: Use the @code{ispell}s 8bit dictionaries even if you do not
store 8bit characters in the file.  This should fix the problem for
almost every word, except, e.g., words containing the Latin-9 character
@code{oe} if you use a Latin-1 encoding.

@item
Spell-checking might stop with the error message @samp{Ispell
misalignment}.  I can reproduce this only with Emacs, not with XEmacs.

Question: If you know some settings (like for
@code{process-coding-system-alist}) which solves this problem, please
let me know!

Solution: turn X-Symbol off before spell-checking your buffer.  This is
of course no option if you use @code{flyspell}.
@end itemize

The real solution would be to fix @code{ispell}, at least by providing a
useful hook which allows X-Symbol to fix the problem.  @xref{Wishlist
Emacs}.  You are strongly encouraged to send a patch to the maintainer
of @code{ispell}, you even get a paragraph here in
@ref{Acknowledgments}!


@node FAQ News and Mail,  , FAQ Spell Check, FAQ
@comment  node-name,  next,  previous,  up
@subsection How to Use X-Symbol with Gnus or @sc{vm}
@cindex News Reader
@cindex Mail Reader
@pindex Gnus
@pindex VM
@pindex Message

You can also use X-Symbol to read and write your News and Mails.  This
sections includes coding for your @file{~/.emacs} if you want to do so.
It has been tested for Gnus-5.8.8 and @sc{vm}-6.96; if you use
@sc{rmail} or @sc{mh-e}, you have to try to find a solution yourself
(please send it to me).  Support for Gnus might become a standard
part of X-Symbol.

@lisp
(custom-set-variables
 '(x-symbol-auto-style-alist
   '(((mail-mode message-mode gnus-article-mode vm-presentation-mode)
      tex nil nil nil nil t nil))))
@end lisp

This is optional (you might want to use the Custom interface for the
same effect) and tells Emacs/X-Symbol to use token language @code{tex}
and to display super-/subscripts (if @code{font-lock} is enabled),
X-Symbol is not automatically turned on.  @xref{Minor Mode}.

@findex mail
@findex message-mail
@findex vm-mail
@vindex mail-send-hook
@vindex message-send-hook
@vindex vm-mail-send-hook
@lisp
(defun x-symbol-x-mail-send-hook ()
  (if x-symbol-mode (x-symbol-mode 0)))
(add-hook 'mail-send-hook 'x-symbol-x-mail-send-hook)
(add-hook 'message-send-hook 'x-symbol-x-mail-send-hook)
(add-hook 'vm-mail-send-hook 'x-symbol-x-mail-send-hook)
@end lisp

This tells tells Emacs to automatically turn off X-Symbol (which
includes encoding characters to token) before actually sending the
message.

@findex gnus
@vindex gnus-article-prepare-hook
@lisp
(defun x-symbol-x-gnus-prepare ()
  (when x-symbol-mode
    (setq x-symbol-mode nil)
    (x-symbol-mode-internal nil)))
(add-hook 'gnus-article-prepare-hook 'x-symbol-x-gnus-prepare)
@end lisp

Since Gnus reuses the @file{*Article*} buffer, where X-Symbol could
have been turned on previously, we must make sure that X-Symbol is
turned off with the new article.

@findex vm
@vindex vm-select-message-hook
@lisp
(defun x-symbol-x-vm-prepare ()
  (and (boundp 'vm-presentation-buffer)
       (buffer-live-p vm-presentation-buffer)
       (save-excursion
	 (set-buffer vm-presentation-buffer)
	 (when x-symbol-mode
	   (setq x-symbol-mode nil)
	   (x-symbol-mode-internal nil)))))
(add-hook 'vm-select-message-hook 'x-symbol-x-gnus-prepare)
@end lisp

The same thing for @sc{vm}, although the hook is not as nice as
Gnus' one; the function therefore might depend a bit too much on
@sc{vm}'s interna.

@findex vm-mode
@findex vm-presentation-mode
@lisp
(put 'vm-mode 'x-symbol-mode-disable
     "Use VM Presentation Mode to turn on X-Symbol")
(custom-set-variables '(vm-fill-paragraphs-containing-long-lines 80))
@end lisp

You cannot use X-Symbol in @sc{vm} Mode, only in @sc{vm} Presentation Mode
(X-Symbol would change your @file{INBOX}).  The first (optional) Emacs
Lisp expression gives you a better error message when you try to turn on
X-Symbol Mode in @sc{vm} Mode.  The second line makes sure that @sc{vm}
always uses @sc{vm} Presentation Mode to display the articles.

@c ===========================================================================

@node Bug Reports,  , FAQ, Problems
@comment  node-name,  next,  previous,  up
@section How to Send a Bug/Problem Report
@cindex Bug Reports
@cindex Problem Reports
@cindex Contacting the Maintainer
@cindex Maintainer Address
@cindex Email to the Maintainer
@cindex Reports of Bugs

Bug fixes, bug/problem reports, improvements, and suggestions are
strongly appreciated.  So are corrections to this manual (better
explanations, correcting my English, @dots{}).  Especially useful would be
some feedback by people using default fonts with a charset
registry-encoding other than @code{iso8859-1} (Western encoding).

Please read this section carefully, even if you generally know how to
send a bug report (@pxref{Bugs,,,@value{emacs},@value{emacsman}}).
This might look tedious to you, but it actually saves a lot of time
(your time, too).

The @strong{general recommendation} for bug/problem reports is: give the
impression that your really have tried to find the necessary information
yourself and make your report precise while including all information
you have.

For each bug/problem report or question you want to send to the
maintainer, please use the following sequence:

@enumerate
@item
Make sure that you use the @strong{newest version} of X-Symbol.  You are
reading Edition @value{edition} (@value{subedition}) of the manual for
X-Symbol @value{version}.

@item
Read the manual, especially @ref{Checking Installation}, @ref{Problems},
and @ref{FAQ}.  The four indexes (@pxref{Indexes}) might also lead you
to an answer to your question.

@item
Use @kbd{M-x x-symbol-package-bug} (also to be found in X-Symbol's
Command submenu) to write your report describing @emph{one} bug or
problem, i.e., use @strong{different mails} for @strong{unrelated
problems}.  Please do not ``reuse'' a mail thread with the maintainer,
i.e., if you start a section with ``Here is another problem'', you do
something wrong.

If Emacs is not your mail tool, copy the Subject header line and the
message body from Emacs' @file{*mail*} buffer to your mail tool.

If @kbd{M-x x-symbol-package-bug} fails to work, you have a problem with
your installation and your report should be about this problem.  In this
case, use @samp{x-symbol @var{version}; @var{summary}} as Subject header
where @var{version} is the version of X-Symbol (it should be
@value{version}) and @var{summary} is a brief summary of your
installation problem.

(@emph{Rationale}: This command automatically extracts some essential
information without any work by you.  Don't waste your time pondering whether
you should really use this command to write your report.)
@c The additional advantage is that I can see who doesn't have any problems
@c wasting my time.

@item
Start your report with:

@quotation
In the manual, I checked the sections @var{section1}, @var{section2},
@dots{}, but didn't find anything which helped me with the following
problem:
@end quotation

The sections @var{section1}, @var{section2}, etc are names of the
sections (not whole chapters) in the manual where you would expect an
answer to your question/problem/bug.

If you didn't know which sections to inspect, please check the indexes.
If they are not helpful, send me words/terms which should be included in
the indexes.

(@emph{Rationale}: This way, I get an idea where to improve the manual,
especially by adding cross references.)
@c It also ensures that you really have tried to find the relevant
@c information yourself.

@item
If buffer @file{*Warnings*} does not exist in the buffer menu,
everything is fine so far.  So is (for me as the author of package
X-Symbol), if @samp{X-Symbol} is not mentioned there.  Otherwise,
include the contents of buffer @file{*Warnings*} into your bug report.

@c TODO: without warnings.el from Emacs-21.4
Temporary Emacs (< v21.4) note: the warnings might be somewhere hidden
in buffer @file{*Messages*}; please check that buffer.

@item
Put the parts of the code from @file{~/.emacs} and the system-wide files
which causes the problem into a fresh file @file{@var{my-problem}.el}.
The problem/error should be visible when invoking

@example
xemacs -no-site-file -q -l @var{my-problem}.el
@end example

In the minimal case, @file{@var{my-problem.el}} just contains the
following line (@pxref{Installing Lisp}):

@lisp
(x-symbol-initialize)
@end lisp

If the error has disappeared after you have included your complete
@file{~/.xemacs/init.el} and @file{~/.emacs}, the problem is likely
caused by some code of your system-wide installation.  Include the code,
which can be found using command @kbd{M-x find-library} with files
@file{site-start} and @file{default} (everything is fine if these files
do not exist).

If you use @file{x-symbol-site.el} (its use is deprecated), copy its
contents into @file{@var{my-problem.el}} and delete the corresponding
@code{load} command.

Attach the file @file{@var{my-problem}.el} to your report.
@strong{Please try to minimize the size of @file{@var{my-problem}.el}}!
A standard technique is recursive halving: Delete the second half of
@file{@var{my-problem.el}}.  If the problem disappears, delete the first
half instead.  Do the same with the smaller file again, @dots{}.

(@emph{Rationale}: Most problems are a consequence of some specific
customizations, but I don't have time to debug each user's init file.)

@item
If you have set variable @code{custom-file} in
@file{@var{my-problem}.el}, attach the corresponding file to your report.

@item
If the error can only be reproduced in combination with another Emacs
package, please send me:

@itemize @minus
@item
If it is included in the standard Emacs/XEmacs distribution / if is an
XEmacs package: the version you use if it is not that from the
Emacs/XEmacs distribution (use @kbd{M-x find-library} to check whether
you really use the version from the Emacs/XEmacs distribution).

@item
If it is a non-standard (and non-obscure) package: the URL of the
distribution and/or the source.

@item
Otherwise: include its code into @file{@var{my-problem}.el} and delete
the corresponding @code{load} or @code{require} command.  Then, reduce
the size of @file{@var{my-problem}.el} as described above.
@end itemize

@item
If the problem is not reproducible with an @emph{arbitrary}
(@file{.tex}, @file{.html}, @dots{}) file, include the file with its full file
name into your bug report.  (If you like, you can try to minimize the
file if the problem is still reproducible.)

(@emph{Rationale}: Most problems are only reproducible with specific
files.)

@ignore
@item
I would appreciate, if you would set variable @code{debug-on-error} to
@code{t} before you trigger the error and send me the contents of buffer
@file{*Backtrace*}.  At best, using the uncompiled versions of the
functions involved, i.e., by jumping to its definition and evaluation it:

@example
M-x find-function @key{RET} @var{function} @key{RET} C-M-f C-x C-e
@end example
@end ignore

@item
Finally, include the exact key sequence which causes the problem into
your bug report.  You should also tell me the name of the buffer in
which the problem occurred and how you have created that buffer (e.g.,
by @kbd{C-x C-f @var{file} @key{RET}}).

At best, you start your Emacs, and then try to reproduce the problem as
fast as possible (i.e., with a minimum number of key/mouse strokes).

As soon as the problem appears, press @kbd{C-h l} and include the
contents of buffer @file{*Help*} in your bug report.

(@emph{Rationale}: Most problems are only reproducible with point being
at a specific position in the file, with specific key sequences, etc.)

@item
If you have problem with the display of images, please include the
output of the shell commands @samp{convert -h} and @samp{convert -list
Format} in your bug report.  If the first command fails, you have a
problem with the program @code{convert}, not X-Symbol.

@item
If necessary, include a screen-shot in your bug report.

@item
If you could not use @kbd{M-x x-symbol-package-bug}, include the
contents of buffer @file{*Help*} after the following actions:

@itemize @minus
@item
Type @kbd{C-h v x-symbol-version @key{RET}}.
@item
Type @kbd{C-h v emacs-version @key{RET}}.
@item
Type @kbd{C-h v features @key{RET}}.
@end itemize

@end enumerate

If you have solved your problem during this sequence, but you think your
situation is worth to be mention in this manual (e.g., in @ref{Package
Integration}), I would appreciate if you would send me a some new text
for this manual or a normal bug report together with your solution.

@c ===========================================================================

@node History, Indexes, Problems, Top
@comment  node-name,  next,  previous,  up
@chapter History and Projects

@menu
* News::                        Changes in recent versions.
* Wishlist::                    Projects for X-Symbol.
* Open Questions::              How you can contribute.
* Acknowledgments::             People having contributed.
@end menu

@c ===========================================================================

@node News, Wishlist, History, History
@comment  node-name,  next,  previous,  up
@section News: Changes in Recent Versions of X-Symbol
@cindex New Features
@cindex Changes
@cindex History

This is the complete history of X-Symbol.  It just lists the major
changes before Version 3.0.

@menu
* Changes New::                 To be announced.
* Changes 4.5::                 Released Mar 2003 as beta.
* Changes 4.4::                 Released June 2002 as beta.
* Changes 4.1::                 Released Mar 2002 as beta.
* Changes 3.4::                 Released Mar 2002.
* Changes 3.3::                 Released Jan 1999.
* Changes 3.2::                 Released Dec 1998.
* Changes 3.1::                 Released Oct 1998.
* Changes 3.0::                 Released Sep 1998 as beta.
* Changes Old::                 Overview of old releases.
@end menu



@node Changes New, Changes 4.5, News, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol @value{version}

Version @value{version} has not yet been announced.

@itemize @bullet
@item
Various bug fixes and minor changes.
@end itemize


@node Changes 4.5, Changes 4.4, Changes New, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 4.5

Version 4.5 has been released on March 2003 as beta.

@itemize @bullet
@item
X-Symbol finally respects the Mule coding system of each individual buffer.

@item
Bug fix: would mess up encoding of math-mode characters with token
language @code{bib}.  Other conversion fixes for languages @code{bib}
and @code{texi}.

@item
Bug fix (workaround for bug in XEmacs): auto-save files would have
length 0.

@item
Bug fix (Emacs): package now works with package
@code{crypt}/@code{crypt++}.

@item
Token language @code{sgml}: always encode characters to entity
references by default (where defined by the HTML standard).  Include
@code{hm--html-mode}, @code{html-helper-mode}, remove @code{sgml-mode}
as typical major modes which use X-Symbol.

@item
Token language @code{tex}: support some symbols of package
@file{stmaryrd.sty}.

@item
Change the auto-style, formerly auto-mode, mechanism.

@item
Image support when running on Emacs.

@item
New input method Quail, a usual Mule input method.

@item
Corrected Latin-5 definitions.  Support Latin-5 (``Turkish'') on XEmacs
running under Windows.

@item
X-Symbol works with Emacs/XEmacs running under a character terminal.

@item
Improments for external languages.  Super-/subscript matching of token
languages has changed.

@item
X-Symbol can use package @code{format} and does not require special
fonts for super-/subscripts with Emacs-21.4+.  Still open whether this
will be used@dots{}.

@item
Dropped support for XEmacs-20.3.

@item
Various bug fixes and minor changes.
@end itemize


@node Changes 4.4, Changes 4.1, Changes 4.5, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 4.2 to 4.4

Version 4.4 has been released on June 2002 as beta.

@itemize @bullet
@item
Token language TeX has changed: no excessive use of braces anymore, no
excessive normalization, and aware of environments @code{@{tabbing@}} and
@code{@{verbatim@}}, and macro @code{\verb}.  Reading and saving
``old-encoded'' files works without changes in the file (the buffer
looks different), there is also a command to remove the unwanted braces
around accented letters.

@item
New token language ``Bib@TeX{} Macro'' (@code{bib}, similar to old
@code{tex}), used for Bib@TeX{} files.

@item
Nuked executables, the Lisp conversion for all languages is now 2-5
times faster.

@item
Latin-9 support.  Latin-9 font included in distribution.

@item
Works with XEmacs-21.4+ on Windows.  Of course, it just supports a
limited number of characters and no super- and subscripts there due to
missing fonts.

@item
More likely to save 8bit characters in the file by default: also look
for 8bit characters in the file when visiting the file, also inspect
master file (@code{TeX-master}) with token language @code{tex}.

@item
New buffer-local variable @code{x-symbol-unique}: when non-@code{nil},
decodes much less tokens to avoid near to all normalizations, used for
@TeX{}'s style files (but X-Symbol is not automatically turned on).
Dropped token language @code{utex}.

@item
Menu changes, new commands: submenu ``Conversion'', menu items ``Copy
Encoded'', ``Paste Decoded'' and others.

@item
Special coding for @code{preview-latex}.  Using X-Symbol now only gives
a 10% overhead of @code{preview}s parsing time.

@item
X-Symbol now works with Whizzy@TeX{}.

@item
The interface for defining a token language has changed, it is also much
more general, useful for ProofGeneral.

@item
Changed final bytes of ISO 2022 escape sequence for X-Symbol charsets
since Emacs reserves the characters @samp{0-9} for itself.  Does XEmacs
has any policy here (it also uses @samp{?})?

@item
Dropped workaround for minor bug in XEmacs-20.X.

@item
Various bug fixes and minor changes.
@end itemize


@node Changes 4.1, Changes 3.4, Changes 4.4, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 4.1

Version 4.1 has been released on Mar 2002 as beta.

@itemize @bullet
@item
X-Symbol works with Emacs-21.1 or higher.  Porting is not complete, yet.

@item
New token language ``@TeX{}info command'' (@code{texi}).

@item
Slightly different definition of ``valid character''.

@item
Remove the ``local if set'' and ``default: @dots{}'' submenu stuff.
@end itemize


@node Changes 3.4, Changes 3.3, Changes 4.1, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.4

Version 3.4 has been released on Mar 2002.

@itemize @bullet
@item
Moved to SourceForge.net.  Added files for nicer HTML output of manual.

@item
Would sometimes perform strange conversions when
@code{global-flyspell-mode} is enabled.

@item
Bug fixes: command @kbd{M-x write-region} would always save the whole
buffer if X-Symbol is enabled for that buffer, writing a remote file via
ange-ftp would not work (was OK with efs).

@item
Automatically deduce default coding via @code{locale -ck LC_CTYPE}.

@item
Issue warning when running on XEmacs-21.0 to XEmacs-21.1.8.  Update
manual: XEmacs user package directory is @file{~/.xemacs/packages}.

@item
Directories ending with @file{//} in image search paths are recursive.

@item
New characters used for token languages ``@TeX{} macro'' and ``Isabelle
symbol''.

@item
Make sure to convert just the first part of a multi-part image.

@item
Source distribution includes files for building an RPM package, all
files also compile without Mule support.

@item
Minor changes.  Manual changes.
@end itemize


@node Changes 3.3, Changes 3.2, Changes 3.4, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.3

Version 3.3 has been released on Jan 1999.

@itemize @bullet
@item
Package X-Symbol is really a proper XEmacs package: no need to create
fonts and to set the font path.  With XEmacs/no-Mule, I still recommend
to create the executables (type @kbd{M-x x-symbol-exec-create}).

@item
New functions used for interaction with Emacs package @code{comint}.
This is necessary for new token language ``Isabelle symbol'', to be
distributed with Emacs package ProofGeneral.

@item
New characters used for token languages ``@TeX{} macro'' and ``Isabelle
symbol''.

@item
Minor changes.  Manual changes.
@end itemize


@node Changes 3.2, Changes 3.1, Changes 3.3, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.2

Version 3.2 has been released on Dec 1998.

@itemize @bullet
@item
Package X-Symbol is a proper XEmacs package.  The installation process
is much easier (using the binary package).  It has changed, though!
The use of file @file{x-symbol-site.el} is deprecated.

@item
Reverting the buffer and using @code{vc} commands do not encode
characters when not using @code{crypt}.  (This did not work always.)

@item
Workaround for bug (segfault) in XEmacs-21/Mule betas.

@item
Command @code{x-symbol-package-bug} is less restrictive.  Please use
this command to contact the maintainer.

@item
Bug fixes.  Minor changes.  Manual changes.
@end itemize


@node Changes 3.1, Changes 3.0, Changes 3.2, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.1

Version 3.1 has been released on Oct 1998.

@itemize @bullet
@item
@TeX{} macro @code{\mu} is represented by a character in the Adobe Symbol
font, not in a Latin-@{1,3,5@} font anymore.

@item
Support for most @sc{sgml} entities in HTML-4.0 specification.

@item
Additional characters for @code{\therefore}/@code{&there4;},
@code{&oline;} and @code{&euro;}.

@item
Package X-Symbol has been customized.

@item
The documentation has been completed (as @TeX{}info file).

@item
Handle special URL prefixes @file{file:}, @file{http:} for images.

@item
Bug fixes, configuration changes.
@end itemize


@node Changes 3.0, Changes Old, Changes 3.1, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.0

Version 3.0 has been released on Sep 1998 as beta.

@itemize @bullet
@item
Package X-Symbol now works on XEmacs with and without Mule support.
Dropped support for XEmacs 19.13 to 19.16/20.2.

@item
Full support of token language @code{sgml} (executables, subscripts, images).

@item
X-Symbol is a proper minor mode.

@item
Easier (automatic) 8bit character control (e.g., for @code{\times}
@code{\pm},@dots{}).  By default, the encoding when saving only writes
8bit characters, if @samp{\usepackage[latin@var{n}]@{inputenc@}} with
@var{n}=1,2,3,5 was found in the first 10000 characters of the file
(including commentary).

@item
Package X-Symbol can be easily extended with new token languages and
fonts due to its modular design.  It consistently handles situations
where an entry for an additional character defines the same preferred
key binding (and context) as for a previously defined character

@item
Key bindings have completely changed.  They are now consistent with the
contexts of input method Context (which have changed a bit).

@item
The keys @kbd{@@} and @kbd{!} are not used anymore as Modify- and
Rotate-Key.  The Rotate key (instead of the Modify-Key) is used to
``Greek''ify the previous Ascii char.

@item
Input method Aggressive Context is now called input method Electric and
is much more restrictive (using package @code{texmathp} with language
``@TeX{} macro'').

@item
Easier installation despite many additional features.

@item
Supports more characters.

@item
Nicer grid, info in echo area.

@item
Better cooperation with packages: @code{vc} (check-out does not convert
characters), @code{reftex} (no strange characters @samp{\237}, help with
label creation), @code{auctex}, @code{ispell}, @code{font-latex} (no
annoyances with @code{\exists}).

@item
Safer use of executables.

@item
The code has completely changed.  You have to redo your installation.
@end itemize


@node Changes Old,  , Changes 3.0, News
@comment  node-name,  next,  previous,  up
@subsection Changes in Old Releases.

This sections gives just an overview of the major changes in the releases.

Version 2.6 has been released on Oct 1998.

@itemize @bullet
@item
Fixed serious bug when used under tty.
@end itemize

Version 2.5 has been released on Mar 1998.

@itemize @bullet
@item
Image support.
@end itemize

Version 2.4 has been released on  Mar 1997.

@itemize @bullet
@item
Token language @code{sgml}.  (X-Symbol can handle more then token
language @code{tex}.)

@item
Input method Aggressive Context (precursor of input method Electric),
input method Context has been much improved.

@item
Fixed performance bug when saving a file with package @code{crypt}.

@item
Control of Conversion and 8bit character has changed.
@end itemize

Version 2.3 has been released on Sep 1996.

@itemize @bullet
@item
Distributed with own font for more math characters.

@item
Info for the character around point in echo area.
@end itemize

Version 2.2 has been released on June 1996.

@itemize @bullet
@item
Input method Grid.  Help when using input method Keyboard.

@item
Control of Conversion and 8bit character has changed.
@end itemize

Version 2.1 has been released on April 1996.

@itemize @bullet
@item
Fixed serious performance bug when loading files with
font-lock/lazy-lock.  Use executables for conversion of large buffers.

@item
The package @code{iso-cvt} is not integrated anymore.  Now this package
can also convert to/from Latin-1 characters, it is much faster.

@item
Menu support, including input method Menu.

@item
@code{isearch} works with X-Symbol characters.

@item
First multi-file version.
@end itemize

Version 1.4 has been released on Feb 1996.

@itemize @bullet
@item
Provide some kind of ``poor man's Mule'' to remove most Nomule-Problems.
@end itemize

Version 1.3 has been released on Jan 1996.

@itemize @bullet
@item
Input method Abbrev (precursor of input method Token).

@item
Super-/subscript support.
@end itemize

Version 1.2 has been released on Jan 1996.  It was the first release.

@itemize @bullet
@item
Conversion between characters and @TeX{} tokens.  Do so automatically
when visiting a file and saving the buffer.

@item
Input method Keyboard.
@end itemize

@c ====================================================================

@node Wishlist, Open Questions, News, History
@comment  node-name,  next,  previous,  up
@section Wishlist: Projects for X-Symbol
@cindex Wishlist
@cindex Project
@cindex Future Features
@cindex Contributions
@cindex Your Contribution

You are encouraged to try to provide a solution to one of the problems
of this section.  In fact, it is quite unlikely that I do it myself
without any contributions from you, see also @ref{Open Questions}.

Providing a solution to these problems is the second way of making your
name appear in @ref{Acknowledgments}.

@menu
* Wishlist Languages::          Additional token languages.
* Wishlist Fonts::              Automatically generated fonts.
* Wishlist Emacs::              Changes in Emacs/XEmacs.
* Wishlist LaTeX::              Changes in La@TeX{}.
* Wishlist Various::            Other changes.
* Wishlist Rejected::           Rejected Suggestions for X-Symbol.
@end menu



@node Wishlist Languages, Wishlist Fonts, Wishlist, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Additional Token Languages
@cindex More Token Languages
@cindex Language Additions
@cindex Ams@TeX{}
@cindex IPA Fonts

Making a contribution here would require just a basic knowledge of Emacs
and X-Symbol.  In fact, I would do the non-trivial part of the Emacs Lisp
part (@pxref{Extending X-Symbol}) for general-interest token languages
(e.g., Ams@TeX{}).

It is likely that this would require additional fonts: available fonts
(e.g., IPA font), hand-crafted, or generated (@pxref{Wishlist
Fonts}).


@node Wishlist Fonts, Wishlist Emacs, Wishlist Languages, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Generated Fonts
@cindex Generated Fonts
@cindex Fonts from Other Sources
@cindex Fonts for Windows
@cindex MS-Windows Fonts
@cindex Windows Fonts

@pindex bdftofon
A specific direction of font generation would be from @file{.bdf} or
@file{.pcf} font files to Windows fonts to get rid of the limited
support for XEmacs on Windows (@pxref{Requirements}).  If you have
successfully converted X-Symbol's fonts from the Unix format to the
Windows format (via @code{bdftofon} or whatever) or if you have free and
real Latin-N fonts for Windows, please @emph{let me know}!  I would also
appreciate if you would actively try to get those missing Windows fonts.

The general direction is to automatically generate the @file{.bdf} or
@file{.fon} fonts from other sources.  This would have various
advantages:

@itemize @bullet
@item
We could easily create different sizes for our symbol font.

@item
It would be quite simple to create a font for Ams@TeX{} macros, etc.,
which would be displayed as X-Symbol characters by package X-Symbol.

@item
We could easily create different sizes for our symbol font.

@item
We would have fonts for both X11 and Windows.
@end itemize

New fonts for X-Symbol are being worked on.  You can find material to
generate them at the @uref{@value{url}/news.html,web pages of X-Symbol}.
Quite a few problems needs to be fixed though, so it is considered as
experimental.  You are welcome to try, fix and report on the
@uref{mailto:@value{listdevel},X-Symbol development mailing list}.

General open design issues (i.e., they could be re-thought for the
currently used handcrafted fonts, too) are:

@itemize @bullet
@item
Different @TeX{} macros (same appearance, different @TeX{} class =
different spacing) use the same MetaFont character, e.g., @code{\dagger}
and @code{\dag}.  Therefore, we need different X11 characters for them.

@item
Some Ascii characters have a special meaning in @TeX{}.  The
corresponding MetaFont character is therefore produced by a TeX macro,
e.g., @samp{@{} by @code{\@{}.
@c @}@}
We need a X11 character which looks similar to the character but not
exactly like it.
@end itemize

We could ask the question whether we should really distinguish the
characters by appearance@dots{}we have the minibuffer info for the X-Symbol
character anyway@dots{}.  Here are the options:

@itemize @minus
@item
distinguished by size/underlining/miscellaneous (currently used),
@item
distinguished by different spacing (my current favorite),
@item
not distinguished
@end itemize


@node Wishlist Emacs, Wishlist LaTeX, Wishlist Fonts, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Changes in Emacs/XEmacs
@cindex Emacs Changes
@cindex XEmacs Changes
@cindex Changes in Emacs
@cindex Changes in XEmacs

Changes in Emacs and/or XEmacs would improve package X-Symbol, too:

@itemize @bullet
@item
In Emacs: a package system similar to XEmacs' one.  The installation
would be easier.

@item
@pindex ispell
The package @code{ispell} assumes the buffer contents to be the same as
the file contents and does not provide any hook to fix this.  This
should be fixed in @code{ispell} (it will be better in Emacs-21.4),
see @ref{Miscellaneous Packages}.

@item
@pindex vc
Some versions control commands turn off @code{font-lock}.  This should
be changed.

@item
Provide a face property @code{raise}: we wouldn't need extra fonts for
super- and subscripts.  Emacs: it's already a display property, make it
a face property, too (or make @code{font-lock} set properties other than
faces).  XEmacs: no such property, yet.

@item
You are sometimes unnecessarily asked (because X-Symbol will encode the
corresponding characters anyway) for a safe coding system.  In Emacs
(will be fixed in Emacs-21.4) for non-default Latin characters.  In
XEmacs, for all non-default characters if you use package
@code{latin-unity} (@pxref{File IO Packages}).

@item
@findex isearch
In Emacs, will be fixed in 21.4.  Using @code{isearch} and the input
method Grid would not work.

@item
@vindex after-insert-file-functions
In XEmacs, fixed in 21.X.  In @code{after-insert-file-functions}, there
should be a possibility to get to know the start position of the region
which is inserted.  If @code{insert-file-contents} is called with
argument @code{replace} being non-@code{nil}, it is not always point.

@item
@vindex write-region-annotate-functions
In Emacs and XEmacs, will be fixed in Emacs-21.4.  Make possibility to
change buffers in @code{write-region-annotate-functions} official, see
@ref{Alt Auto Conversion}, have a way to get the original buffer.

@item
Since @code{font-lock} uses duplicable text properties in some cases, I
need a function like @code{insert-buffer-substring-without-extents}.
(Currently, I remove the extents afterwards, which looks slow for me.)

@item
@vindex post-command-hook
In XEmacs.  Run hooks in @code{post-command-hook} even if command exits
with an error or quit (as it is in Emacs) or having some
@code{post-error-or-quit-hook}.  @xref{Nomule Problems}.

@item
In XEmacs.  There are some bugs in package @code{custom}/@code{widget}
(still in XEmacs-21.4) which are visible during the customization of
X-Symbol.

@end itemize


@node Wishlist LaTeX, Wishlist Various, Wishlist Emacs, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Changes in La@TeX{}
@cindex La@TeX{} Changes
@cindex Changes in La@TeX{}
@cindex @file{inputenc.sty} Changes
@pindex @file{inputenc.sty}

Changes in La@TeX{}, especially @file{inputenc.sty}, would improve package
X-Symbol, too:

@itemize @bullet
@item
To make the definition of the character U00B5 consistent with Unicode,
@file{inputenc.sty} should define the character to stand not for the
token @code{\mu} (U03BC is the right character), but for an extra token,
e.g., something like @code{\textmicro}.  X-Symbol uses @code{\mathmicro}
here in order to avoid changing @code{\mu} to the character U00B5 if you
have chosen to store 8bit characters.
@c X-Symbol should not define it as \textmicro because then there would
@c be a major difference between `x-symbol-8bits' nil and non-nil.

@item
Use same encoding for both text and math, i.e. use @code{periodcentered}
for both @code{\textperiodcentered} (the default) and @code{\cdot}.  At
least provide text-and-math versions for characters where no alternative
is more obvious than the other.  If that is not possible, always choose
text mode except for @code{\lnot}, @code{\pm}, @code{\times} and
@code{\division}: use
@code{\textonesuperior} for U00B9, \texttwosuperior for U00B2, and
@code{\textthreesuperior} for U00B3.

@item
The @TeX{} macros @code{\textcent}, @code{\textcurrency},
@code{\textbrokenbar}, @code{\textyen} are defined as not available with
OT1 and T1 font encoding.  This should be changed.
@end itemize


@node Wishlist Various, Wishlist Rejected, Wishlist LaTeX, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Various Projects for X-Symbol

The following suggestions seem to be useful, though not essential:

@itemize @bullet
@item
@cindex Print Buffer
@cindex Buffer Printing
@pindex ps-print
It would be nice if we could print the buffer contents.  Currently, you
see strange characters instead X-Symbol's own characters.

Printing non-standard fonts is only possible via the Emacs package
@code{ps-print}.  A newer version of @code{ps-print} might be probably
already capable of doing it.  Thus, you are encouraged to help the
XEmacs team updating this package.
@end itemize


@node Wishlist Rejected,  , Wishlist Various, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Rejected Suggestions for X-Symbol
@cindex Rejected Suggestions

The following suggestions seem to be not useful enough to be worth the
additional effort and increased package size.  I might be convinced
otherwise by patches (i.e., code, not text), though:

@itemize @bullet
@item
@cindex Input Method Token
It would be nice if X-Symbol would replace the token with the last
character of the token if this is possible (@pxref{Input Method Token}),
not just with the next character.  Well, during typing, this is not
really annoying and after a while, you will use input method Token only
for very short tokens.
@end itemize

@c ===========================================================================

@node Open Questions, Acknowledgments, Wishlist, History
@comment  node-name,  next,  previous,  up
@section Open Questions
@cindex Open Questions
@cindex Various Questions
@cindex Questions I Have

This section lists some minor open questions.

@itemize @bullet
@item
@findex x-symbol-initialize
@cindex Auto Initialization
Loading file @file{x-symbol.el} will initialize package X-Symbol (via
function @code{x-symbol-initialize}), since all functions will need the
initialization.  In my opinion, this is no problem, since all
customization options are defined an other files which do not require
file @file{x-symbol.el}.  Thus, customizing package X-Symbol will not
initialize package X-Symbol.

The alternative would be to call function @code{x-symbol-initialize} in
every function which can be autoloaded.  This seems quite tedious to
me.  Also, I do not see a reason not to call @code{x-symbol-initialize}
top-level in file @file{x-symbol.el}.  If I am wrong here, please let me 
know (with an explanation).  Batch-compilation might be an issue@dots{}

@item
@pindex crypt
@vindex x-symbol-auto-conversion-method
When is necessary to set @code{x-symbol-auto-conversion-method} to
@code{slowest}?  Of course, it is only necessary when using
@code{crypt}.  Is the other necessary condition to use the computer pool
of the University of Edinburgh?
@end itemize

@c ===========================================================================

@node Acknowledgments,  , Open Questions, History
@comment  node-name,  next,  previous,  up
@section Acknowledgments
@cindex Acknowledgments
@cindex Contributions
@cindex Marlet, Renaud
@cindex Bradfield, Julien
@pindex math-mode
@cindex Adobe
@pindex frame-icon
@cindex Thanks

Stefan Monnier did many of the changes necessary for porting X-Symbol to
Emacs-21.  Fortunately, he not only changed X-Symbol to use a quite
different API on Emacs for things like charsets and menus, he also made
the necessary changes in Emacs itself.  Before that, Sang-Min Lee
started porting X-Symbol to Emacs-20.4, which was important for moving
the status of the Emacs port of X-Symbol from ``todo'' to ``in work''.

David Kastrup demonstrated that the old way of encoding characters to
@TeX{} macros generally inhibited ligatures and kerns, i.e., it was
worse than expected.  He also discussed the details of how to do the
encoding and decoding right.  Christophe Raffalli suggested to use a
decode method which can be used for a larger class of token languages.
He also proved that it is faster.

Solofo Ramangalahy is working on scripts to generate X-Symbol fonts from
other sources.  This has various advantages and is discussed in more detail at
@ref{Wishlist Fonts}.  His work is now available at the
X-Symbol download area.

Package @code{math-mode} by Renaud Marlet and the extension of it by
Julian Bradfield gave the basic idea for the following features:
supporting @TeX{}'s math macros, input methods token, context/electric,
super-/subscript support.  The shell script @code{makesub} is a merge
and change of the scripts @code{makesupers} and @code{makesub} by
Julian.

The font @samp{xsymb0}, which is distributed with this package, is a
minor modification (appearance) of the Adobe symbol font, thanks to its
non-restrictive copyright.  You may use the Adobe font instead.  The
special images are from package @code{frame-icon}.

The idea for Help during an X-Symbol key sequence is from package
@code{x-compose}.  The general idea for showing some info in the echo
area is from package @code{eldoc}.  The trick which stops
@code{expand-abbrev} is from package @code{mail-abbrevs}.  The idea for
@code{x-symbol-image-cache-directories} is from package
@code{fast-lock}.  The code for image command parsing is influenced by
some code in package @code{font-lock}.  The code around
@code{x-symbol-image-delete-extents} is based on some code in package
@code{bib-cite}.

@i{Thanks for patches/reports/suggestions to}: Adrian Aichner, Vladimir Alexiev, David
Aspinall, Masayuki Ataka, Neal Becker, Matthias Berberich, Stefano
Bianchi, Janusz S. Bien, Uwe Brauer, Alastair Burt, John Collins,
Laurent Descamps, Frederic Devernay, Carsten Dominik, Steve Dunham,
Michael Ebner, Stephen Eglen, Paul Furnanz, Jeffrey Grandy, Clemens
Gr@"opl, Kenichi Handa, Meik Hellmund, Ryurick M. Hristev, Adriaan
Joubert, Marcin Kasperski, David Kastrup, Richard Ketchersid, Felix
E. Klee, Gerwin Klein, Thomas Kleymann, Ekkehard Koehler, Fred Labrosse,
Jan-Ake Larsson, Bernhard Lehner, Stefan Monnier, Harald Muehlboeck,
Karsten Muehlmann, Jakub Narebski, Peter M@o{}ller Neergaard, Raymond
Nijssen, David von Oheimb, Alex Ott, Sudeep Kumar Palat, Arshak
Petrosyan, Jim Radford, Christophe Raffalli, Solofo Ramangalahy, Alex
Russell, Marciano Siniscalchi, Richard M. Stallman, Axel Thimm, Eli
Tziperman, Jan Vroonhof, Markus Wenzel, Sabine Wetzel, Pierre-Henri
Wuillemin, Roland Zumkeller, Marco Zunino, Gerard Zwaan.

@i{Thanks for general information to:} Per Abrahamsen, Steve L. Baur,
Kenichi Handa, David Kastrup, Gerd Moellmann, Stefan Monnier, Primoz
Peterlin, Martin Ramsch, Peter Schmitt, Toby Speight, Jan Vroonhof, Eli
Zaretskii.

I made use of information from the following URLs:

@display
  @url{http://www.fmi.uni-passau.de/~ramsch/iso8859-1.html}
  @url{http://czyborra.com/charsets/iso8859.html}
  @url{http://www.bbsinc.com/iso8859.html}
  @url{http://www.bbsinc.com/iso8879.html}
  @url{http://ppewww.ph.gla.ac.uk/~flavell/charset/internat.html}
  @url{http://ppewww.ph.gla.ac.uk/~flavell/iso8859/iso8859-pointers.html}
  @url{http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html}
@end display

I do not intend to update this list in the future---this is just an
"Acknowledgment" section.


@node Indexes,  , History, Top
@comment  node-name,  next,  previous,  up@unnumbered Indexes
@unnumbered Indexes

You should consult the following indexes if you are interested in a
specific feature or aspect of package X-Symbol.  You should also consult
them before sending a report to the maintainer (@pxref{Bug Reports}),

@menu
* Key Index::                   Key sequences.
* Program Index::               Programs and Emacs packages.
* Variable Index::              Commands, functions, variables.
* Concept Index::               Various topics.
@end menu

The links lead you to the manual sections describing X-Symbol's commands
and variables.  @xref{About}.

@comment workaround for bug with the length of the lists
@iftex
@vskip 6ex plus 1ex minus 4ex
@end iftex

@node Key Index, Program Index, Indexes, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Key Index
@printindex ky

@comment workaround for bug with the length of the lists
@iftex
@page
@end iftex

@node Program Index, Variable Index, Key Index, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Program and Package Index
@printindex pg

@comment workaround for bug with the length of the lists
@iftex
@page
@end iftex

@node Variable Index, Concept Index, Program Index, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Command, Function and Variable Index
@printindex vr

@comment workaround for bug with the length of the lists
@iftex
@page
@end iftex
@node Concept Index,  , Variable Index, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Concept Index
@printindex cp

@contents
@bye
@c Local IspellPersDict: .ispell_xsymb