summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/FAQ-en/faq-mac-prog.tex
blob: e9a881ba2a57cf4af26e2ea99db05f73740be82c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
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
% $Id: faq-mac-prog.tex,v 1.35 2014/01/28 18:17:36 rf10 Exp rf10 $

\section{Macro programming}

\subsection{``Generic'' macros and techniques}

\Question[Q-linmacnames]{Non-letters in macro names}

New \LaTeX{} users are often suprised that macro definitions
containing non-letters, such as
\begin{quote}
\begin{verbatim}
\newcommand{\cul8r}{Goodbye!}
\end{verbatim}
\end{quote}
fail to compile.  The reason is that the \TeX{} macro language, unlike
most programming languages, allows % ! loin break (twatbili)
\Qref*{nothing but letters in macro names}{Q-whatmacros}.

There are a number of techniques for defining a macro with a name like
\csx{cul8r}.  Unfortunately, none of the techniques is particularly
good:
\begin{enumerate}
\item Use \csx{csname}\dots\csx{endcsname} to define and invoke the
  macro:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter\newcommand
       \csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter\newcommand\csname cul8r\endcsname{Goodbye!}
I said, ``\csname cul8r\endcsname''.
\end{verbatim}
\end{wideversion}
\end{quote}
  \begin{description}
  \item[Pro:] No unexpected side effects
  \item[Con:] So verbose as to be unusable
  \end{description}
\item Define a ``special-command generator'', and  use the resulting
  commands:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand{\DefineRemark}[2]{%
  \expandafter\newcommand
     \csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{%
  \csname rmk-#1\endcsname%
}
...
\DefineRemark{cul8r}{Goodbye!}
...
I said, ``\Remark{cul8r}''.
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand{\DefineRemark}[2]{%
  \expandafter\newcommand\csname rmk-#1\endcsname{#2}%
}
\newcommand{\Remark}[1]{\csname rmk-#1\endcsname}
...
\DefineRemark{cul8r}{Goodbye!}
...
\Remark{cul8r}
\end{verbatim}
\end{wideversion}
\end{quote}
  \begin{description}
  \item[Pro:] Straightforward to use, not too untidy
  \item[Con:] It's hardly doing what we set out to do (experts will
    see that you are defining a macro, but others likely won't)
  \end{description}
\item Convince \TeX{} that ``\texttt{8}'' is a letter:
\begin{quote}
\begin{verbatim}
\catcode`8 = 11 
\newcommand{\cul8r}{Goodbye!}
I said, ``\cul8r''.
\end{verbatim}
\end{quote}
  \begin{description}
  \item[Pro:] \csx{cul8r} can be used directly
  \item[Con:] Likely to break other uses of ``\texttt{8}'' (such as
    numbers or dimensions; so
    \cmdinvoke{setlength}{\csx{paperwidth}}{8in} tells us:
\begin{quote}
\begin{verbatim}
! Missing number, treated as zero.
<to be read again> 
                   8
\end{verbatim}
\end{quote}
  \end{description}
  As a general rule, changing category codes is something to use
  \emph{in extremis}, after detailed examination of options.  It is
  conceivable that such drastic action could be useful for you, but
  most ordinary users are well advised not even to try such a
  technique.
\item Define a macro \csx{cul} which must always be followed by
  ``\texttt{8r}'':
\begin{quote}
\begin{verbatim}
\def\cul8r{Goodbye!}
I said, ``\cul8r''.
\end{verbatim}
\end{quote}
  \begin{description}
  \item[Pro:] \csx{cul8r} can be used directly
  \item[Con~\#1:] Breaks if \csx{cul} is followed by anything other
    than ``\texttt{8r}'', with a confusing diagnostic~---
    \csx{cul99} produces:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
! Use of \cul doesn't match its definition.
<*> \cul9
         9
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
! Use of \cul doesn't match its 
                           definition.
<*> \cul9
         9
\end{verbatim}
\end{narrowversion}
\end{quote}
    (which would confuse someone who hadn't even realised there
    \emph{was} a definition of \csx{cul} in the document).
  \item[Con~\#2:] Silently redefines existing \csx{cul}, if any;
    as a result, the technique cannot be used to define both a
    \csx{cul8r} and, say, a \csx{cul123} macro in the same
    document.
  \end{description}
\end{enumerate}
Technique~3 is in fact commonly used~--- in a limited form~--- within
most \LaTeX{} packages and within \LaTeX{} itself.  The convention is to
use ``\texttt{@}'' within the names of internal macros to hide them
from the user and thereby prevent naming conflicts.  To this end,
\LaTeX{} automatically treats ``\texttt{@}'' as a letter while
processing classes and packages and as a non-letter while processing
the user's document.  The key to this technique is the separation:
internally a non-letter is used for macro names, and the user doesn't
see anything of it, while the status remains ``frozen'' in all the
definitions created within the class or package.  See % ! line break
\Qref[question]{\csx{@} and \texttt{@} in macro names}{Q-atsigns} for
more information.

Note that analogous use of technique~3 in this example would give us
\begin{quote}
\begin{verbatim}
\begingroup
  \catcode`8 = 11 
  \gdef\cul8r{Goodbye!}
  \gdef\later{\cul8r}
\endgroup
I said, ``\later''.
\end{verbatim}
\end{quote}
which works, but rather defeats the object of the exercise.
(\csx{later} has the ``frozen'' catcode for `8', even though the value
has reverted to normal by the time it's used; note, also, the use of
the primitive command \csx{gdef}, since \csx{newcommand} can't make a
macro that's available outside the group.)

\emph{Recommendation}: Either choose another mechanism (such as
\csx{DefineRemark} above), or choose another name for your macro, one
that contains only ordinary letters.  A common approach is to use
roman numerals in place of arabic ones:
\begin{quote}
\begin{verbatim}
\newcommand{\culVIIIr}{Goodbye!}
\end{verbatim}
\end{quote}
which rather spoils the intent of the joke implicit in the example
\csx{cul8r}!
\LastEdit*{2009-06-03}

\Question[Q-repeat-num]{Repeating a command \emph{n} times}

\tex{} was \emph{not} designed as a programming language, but there
are occasions when you want to repeat some part of your document, just
as parts of programs need to run several times.  An obvious
example is \tex{}-based drawing: \latex{}'s \environment{picture}
environment and \Package{pgf} (at least) provide repeat facilities~---
they are useful for drawing repeating patterns.  As a result,
``common'' programming techniques often have to be emulated using
obscure macro \tex{}niques.

This answer deals with repeating an operation a given number of times;
repeating operations once for each of a set of objects is dealt with
in the answer \Qref*{repeating ``over a set''}{Q-repeat-set}.

Plain \tex{} itself provides a \csx{loop} \dots{} \csx{repeat}
contruct, which enables you to repeat a command (or set of commands).
The syntax is simple enough, but it use of \tex{} conditionals is
different enough that many people find it confusing.
\begin{quote}
\begin{verbatim}
\newcount\foo
\foo=10
\loop
  \message{\the\foo}
  \advance \foo -1
\ifnum \foo>0
\repeat
\end{verbatim}
\end{quote}
In this slightly tricky code, \csx{loop} starts the construct ended by
\csx{repeat}, but \csx{repeat} also ``serves as'' the \csx{fi} to the
\csx{ifnum}.  The loop above prints the numbers from 10 down to 1 via
\tex{} \csx{message} (i.e., on the console output).

The \Package{multido} package is also `generic' (usable both in
\plaintex{} and latex{}); it defines a command \csx{multido} with
three arguments:
\begin{quote}
  % ! line break
  \cmdinvoke{multido}{\meta{variables}}{\meta{repetitions}}{\meta{stuff to repeat}}
\end{quote}
When the macro is executing, the \meta{stuff to repeat} gets executed
\meta{repetitions} times; the \meta{variables} gives a list of
variables that can be used in \meta{stuff}.  Each variable is a
composite of a command sequence and how it varies; so a variable
``\csx{iz}\texttt{=2+4}'' sets \csx{iz} to \texttt{2} first time
around, then \texttt{6} and \texttt{10} in the next two iterations,
and so on.  (The variable \csx{iz} is an integer; variables with other
initial letters represent different data types.)

% [do these things matter?]
% The \latexe{} kernel has commands \csx{@for} and \csx{@tfor}.
%
% The \latex{}3 kernel includes the command |\prg_replicate:nn|; this
% information isn't much use unless you're a \latex{}3 user.
Both current \latex{} and (experimental) \latex{}3 have iteration
commands for internal use and for package writers; their use is
probably not recommendable.

The \latex{} distribution package \Package{ifthen} offers the macro
\csx{whiledo}:
\begin{quote}
\begin{verbatim}
\newcounter{ct}
...
\setcounter{ct}{1}
\whiledo {\value{ct} < 5}%
{%
  \thect\
  \stepcounter {ct}%
}
\end{verbatim}
\end{quote}

The \Package{forloop} package provides nothing but \csx{forloop}:
\begin{quote}
\begin{verbatim}
\newcounter{ct}
...
\forloop{ct}{1}{\value{ct} < 5}%
{%
  \thect\
}
\end{verbatim}
\end{quote}
as you can see, the arguments are counter, starting value and
termination condition; an optional argument supplies a step value
(default step is 1).

The \latex{} \environment{picture} environment has a simple command
for repeated drawing:
\begin{quote}
\begin{verbatim}
\multiput(x,y)(xstep,ystep){n}{obj}
\end{verbatim}
\end{quote}
which places \meta{obj} (intended to be a bit of picture)
\meta{n} times at positions (\meta{x}, \meta{y}),
(\meta{x}+\meta{xstep}, \meta{y}+\meta{ystep}),
(\meta{x}+2\meta{xstep}, \meta{y}+2\meta{ystep}) and so on, adding the
displacement again each time.  The command was designed for use in
\environment{picture}, but it makes no check, and may even be used to
provide eccentric typesetting in a ``regular'' sentence, such as:
\begin{quote}
\begin{verbatim}
Here \multiput(0,0)(1,1){3}{we} are again.
\end{verbatim}
\end{quote}
with predictable (if not actually desirable) effect.  It may be used
with nothing but an iterative calculation in the braced argument, in
which case its graphical capabilities have no effect.

The \Package{pgffor} package, which is part of the % ! line break
\Qref*{\Package{pgf} distribution}{Q-drawing}, also
provides iterations to support the needs of graphics.  Its syntax is
in the style of common programming languages:
\begin{quote}
\begin{verbatim}
\usepackage{pgffor}
\newcommand{\cmd}{-x-}
...
\foreach \n in {1,...,4}{\cmd{}}
\end{verbatim}
\end{quote}
typesets ``\texttt{-x-\relax-x-\relax-x-\relax-x-}''

The \csx{foreach} command has the potential drawback that its repeated
unit is executed in a group, so that any calculations done within the
loop are lost (unless their result is made \csx{global}); however, it
does not `build in' its graphical origins (as \csx{multiput} does) so
its potential outside its own graphics environment ``home'' is more
clear.
%
%% can't convince myself that \naturalloop helps with anything
% The \Package{etextools} package provides \csx{naturalloop}, which
% repeats material according to a count argument that you give it.
%
%% this stuff removed, following the observation that the package's use
%% of \repeat is inconsistent with both plain tex and latex; pity --
%% it's a nice package apart from being totally unusable :-(
%
% The \Package{repeat} package provides a \csx{for} command that
% encompasses a lot of the above; for example:
% \begin{quote}
% \begin{verbatim}
% \input repeat
% \newcount\foo
% \repeat
%   \for{foo} \from{1} \to{10} \do{x*}
% \end{verbatim}
% \end{quote}
% which will typeset \texttt{x*} ten times (the count \csx{foo} will
% end up with value 11).
%
% Note the \plaintex{} usage: \Package{repeat} is ``generic'' and
% defines commands that are comfortable to \plaintex{} users, while
% remaining usable by \latex{} users.
%
% The complete syntax is given in the meta-expression:
% \begin{quote}
% \begin{verbatim}
% \repeat
%   \for{var}
%     \from{<start>} \by{<step>} \to{<end>}
%     \downto{<end>} \until{<cond>} \while{<cond>}
% \do{<operate on something>}
% \end{verbatim}
% \end{quote}
% You must choose a consistent set of \csx{from}, \csx{by}, \csx{to},
% \csx{downto}, \csx{until} and \csx{while} (none is actually required,
% but of course any loop has to have \emph{some}).

% In summary, while it is certainly possible to write this sort of code as
% a private project (for example, using the \etex{} \csx{numexpr}
% primitive), one cannot deny that plenty of choice for the task is
% readily available.
%
% (the above ignore Pic\tex{}, which almost certainly has similar
% functions, but in the absence of a manual\dots{})
\begin{ctanrefs}
%\item[etextools.sty]\CTANref{etextools}
\item[forarray.sty]\CTANref{forarray}
\item[forloop.sty]\CTANref{forloop}
\item[ifthen.sty]Distributed as part of \CTANref{latex}
\item[multido.sty]\CTANref{multido}
\item[pgffor.sty]Distributed as part of \CTANref{pgf}
%\item[repeat.tex]\CTANref{repeat}
\end{ctanrefs}
\LastEdit{2013-03-01}

\Question[Q-repeat-set]{Repeating something for each `thing' in a set}

As another question % line break!
(\Qref*{repeating something a given number of times}{Q-repeat-num})
explains, \tex{} is not explicitly designed for `regular' programming
operations. As a result, we must resort to arcane tricks to do the
seemingly simple task of repeating an operation.  This answer deals
with repeating an operation for each of a given set of objects.

The \Package{etoolbox} package provides iteration over a
comma-separated list of items, in its \csx{docsvlist} and
\csx{forcsvlist} commands; they are well-described in the package
documentation.  The \Package{datatool} package manages ``databases''
(of its own definition) and you may iterate over entries in such a
database using the command \csx{DTLforeach}.

The \Package{forarray} package defines its own ``list'' and ``array''
structures, together with commands \csx{ForEach} and \csx{ForArray}
which enable a command to be executed for each element in a list or
array, respectively.

The \Package{dowith} defines a pair of macros \csx{DoWith} and
\csx{StopDoing} that process each ``thing'' between them; a trivial
example of use is:
\begin{quote}
\begin{verbatim}
\usepackage{dowith}
...
\begin{document}
\newcommand{\foo}[1]{\message{#1+}
\DoWith\foo a{BBB}c\StopDoing
\end{verbatim}
\end{quote}
which produces terminal output:
\begin{quote}
\begin{verbatim}
a+ BBB+ c+
\end{verbatim}
\end{quote}
so, the macros have found 3 ``things'', including one with braces
around it.  (The interpolated spaces come from the primitive
\csx{message} command.)

The only constraint is that all commands in the enclosed stuff are
``expandable'' (which means, for example, that you may not use
commands with optional arguments).

From the same stable (as \Package{dowith}) comes the package
\Package{commado}, that provides commands \csx{DoWithCSL} (apply a
command to each element of a comma-separated-variable list) and
\csx{DoWithBasesExts} (apply a command to each of a set of files,
defined by base name and ``extension'').  Use of these \csx{DoWith*}
macros is also expandable (if the command applied to the list elements
is itself expandable).
\begin{ctanrefs}
\item[commado.sty]\CTANref{commado}
\item[datatool.sty]\CTANref{datatool}
\item[dowith.sty]\CTANref{dowith}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[filesdo.sty]Distributed with \CTANref{commado}
\end{ctanrefs}
\LastEdit{2013-02-20}

%See \url{http://tex.stackexchange.com/questions/16189/repeat-command-n-times}
%for details (do i need this any more?)

\Question[Q-findwidth]{Finding the width of a letter, word, or phrase}

Put the word in a box, and measure the width of the box. For example,
\begin{quote}
\begin{verbatim}
\newdimen\stringwidth
\setbox0=\hbox{hi}
\stringwidth=\wd0
\end{verbatim}
\end{quote}
Note that if the quantity in the \csx{hbox} is a phrase, the actual
measurement only approximates the width that the phrase will occupy in
running text, since the inter-word glue can be adjusted in paragraph
mode.

The same sort of thing is expressed in \LaTeX{} by:
\begin{quote}
\begin{verbatim}
\newlength{\gnat}
\settowidth{\gnat}{\textbf{small}}
\end{verbatim}
\end{quote}
This sets the value of the length command |\gnat| to the width of ``small''
in bold-face text.

\Question[Q-patch]{Patching existing commands}

In the general case (possibly sticking something in the middle of an
existing command) this is difficult.  However, the common requirement,
to add some code at the beginning or the end of an existing command,
is conceptually quite easy.  Suppose we want to define a version of a
command that does some small extension of its original definition: we
would naturally write:
\begin{quote}
\begin{verbatim}
\renewcommand{\splat}{\mumble\splat}
\end{verbatim}
\end{quote}
However, this would not work: a call to \csx{splat} would execute
\csx{mumble}, and then call the redefined \csx{splat} again; this is an
`unterminated recursion', that will quickly exhaust \TeX{}'s memory.

Fortunately, the \TeX{} primitive \csx{let} command comes to our
rescue; it allows us to take a ``snapshot'' of the current state of a
command, which we can then use in the redefinition of the command.
So:
\begin{quote}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}{\mumble\OldSmooth}
\end{verbatim}
\end{quote}
effects the required patch, safely.  Adding things at the end of a
command works similarly.

If \csx{smooth} takes arguments, one must pass them on:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}[2]{\mumble\OldSmooth{#1}{#2}}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\let\OldSmooth\smooth
\renewcommand{\smooth}[2]%
             {\mumble\OldSmooth{#1}{#2}}
\end{verbatim}
\end{narrowversion}
\end{quote}

The situation is more difficult still if \csx{smooth} takes an
optional argument; the structure of the command is so complex that the
simple \csx{let} command does not retain the necessary detail.  In
this case, we need the \Package{letltxmacro} package which knows about all
sorts of \latex{} commands and how to replicate them.  Suppose we have
a command defined as:
\begin{quote}
\begin{verbatim}
\newcommand{\rough}[1][\default]{...}
\end{verbatim}
\end{quote}
with an optional argument (substituted with \csx{default} if it's not
present) as well as an ordinary one.  In this case we copy it using
\begin{quote}
\begin{verbatim}
\LetLtxMacro{\NewRough}{\rough}
\end{verbatim}
\end{quote}
and then repeat the technique we had above, with one extension:
\begin{quote}
\begin{verbatim}
\renewcommand{\rough}[1][\newdef]%
             {\mumble\OldRough[{#1}]{#2}}
\end{verbatim}
\end{quote}
We see here that (for tedious argument-matching reasons) it is
necessary to provide braces arround the optional argument that is
being passed on.

The general case may be achieved in two ways.  First, one can use the
\LaTeX{} command \csx{CheckCommand}; this compares an existing command
with the definition you give it, and issues a warning if two don't
match.  Use is therefore:
\begin{quote}
  |\CheckCommand{\complex}{|\meta{original definition}|}|\\
  |\renewcommand{\complex}{|\meta{new definition}|}|
\end{quote}
This technique is obviously somewhat laborious, but if the original
command comes from a source that's liable to change under the control
of someone else, it does at least warn you that your patch is in
danger of going wrong.

Otherwise, \LaTeX{} users may use one of the \Package{patchcmd},
\Package{ted} or \Package{etoolbox} packages.

The \Package{patchcmd} package addresses a slightly simpler task, by
restricting the set of commands that you may patch; you mayn't patch
any command that has an optional argument, though it does deal with
the case of commands defined with \csx{DeclareRobustCommand}.  The
package defines a \csx{patchcommand} command, that takes three
arguments: the command to patch, stuff to stick at the front of its
definition, and stuff to stick on the end of its definition.  So,
after
\begin{quote}
\begin{verbatim}
\def\b{b}
\patchcmd\b{a}{c}
\end{verbatim}
\end{quote}
we will have a new version of \csx{b} defined as ``\texttt{abc}''.

The \Package{ted} package is a `token list editor', and provides a
command \csx{substitute} which will patch the
contents of a macro, putting the result in a token-list, or
(in the form \csx{Substitute*}) using the result to (re)define a
macro.  The following example defines a simple macro, and then changes
its definition:
\begin{quote}
\begin{verbatim}
\newcommand{\myfont}%
    {\Large\sffamily\selectfont}
\Substitute*[\renewcommand{\myfont}]{\myfont}%
    {\Large\sffamily}{\huge\itshape}
\end{verbatim}
\end{quote}
The macro's definition is now:
\begin{quote}
\begin{verbatim}
\huge\itshape\selectfont
\end{verbatim}
\end{quote}

The package also offers a command \csx{ShowTokens}, which shows the
content of its argument, one token to a line, with details of the
token's category code, etc.  This is recommended as a debugging tool.

The \Package{etoolbox} package (which provides user access to \eTeX{}'s
programming facilities) provides a command \csx{patchcmd} which is
very similar to \csx{Substitute}, except that it only replaces a
single instance of the token(s) in its search pattern.  Since not all
commands may be patched in this way, \csx{patchcmd} takes extra
arguments for \emph{success} and \emph{failure} cases.  The
package also provides commands that prepend (\csx{pretocmd}) or append
(\csx{apptocmd}) to the definition of a command.  Not all commands may
be patched in this way; the package provides a command
\csx{ifpatchable} which checks the prerequisites, and checks that the
target command's body does indeed include the patch string you propose
to use.  (The command \csx{ifpatchable*} omits the test on the patch
string.)

The \Package{regexpatch} package deals with cases that are
inaccessible with \Package{etoolbox}; it uses the regular expression
(pattern-matching) package \Package{l3regex} from the \latex{}3
distribution to find the code you need to patch.  The package also
``knows about'' robust commands and about
\Qref*{\Package{biblatex}}{Q-biblatex}.

Finally, we'll briefly consider a package that is (just about)
usable, but not really recommendable.  \Package{Patch} gives you an
ingenious (and difficult to understand) mechanism, and comes as an
old-style \LaTeX{} documented macro file, which can no longer be
processed to \Qref*{produce formatted documentation, etc.\@}{Q-install-doc}.
Fortunately, the file (\File{patch.doc}) may be input directly, and
``documentation'' may found by reading the source of the package.
Roughly speaking, one gives the command a set of instructions
analogous to \ProgName{sed} substitutions, and it regenerates the
command thus amended.  Unless you can't do your job any other way,
\Package{patch} is best avoided.
\begin{ctanrefs}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[l3regex.sty]Distributed as part of \CTANref{l3experimental}[l3regex]
\item[letltxmacro.sty]Distributed as part of \CTANref{oberdiek}[letltxmacro]
\item[patch.doc]\CTANref{patch}
\item[patchcommand.sty]\CTANref{patchcmd}
\item[regexpatch.sty]\CTANref{regexpatch}
\item[ted.sty]\CTANref{ted}
\end{ctanrefs}
\LastEdit{2012-12-21}

\Question[Q-compjobnam]{Comparing the ``job name''}

The token \csx{jobname} amusingly produces a sequence of characters
whose category code is 12 (`other'), regardless of what the characters
actually are.  Since one inevitably has to compare a macro with the
contents of another macro (using \csx{ifx}, somewhere) one needs to
create a macro whose expansion looks the same as the expansion of
\csx{jobname}.  We find we can do this with \csx{meaning}, if we strip
the ``\csx{show} command'' prefix.

The full command looks like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\def\StripPrefix#1>{}
\def\jobis#1{FF\fi
  \def\predicate{#1}%
  \edef\predicate{\expandafter\StripPrefix\meaning\predicate}%
  \edef\job{\jobname}%
  \ifx\job\predicate
}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\def\StripPrefix#1>{}
\def\jobis#1{FF\fi
  \def\predicate{#1}%
  \edef\predicate{\expandafter\StripPrefix
                    \meaning\predicate}%
  \edef\job{\jobname}%
  \ifx\job\predicate
}
\end{verbatim}
\end{narrowversion}
\end{quote}
And it's used as:
\begin{quote}
\begin{verbatim}
\if\jobis{mainfile}%
  \message{YES}%
\else
  \message{NO}%
\fi
\end{verbatim}
\end{quote}
Note that the command \csx{StripPrefix} need not be defined if you're
using \LaTeX{}~--- there's already an % line break!
\Qref*{internal command}{Q-atsigns} \csx{strip@prefix} that you can
use.

\Question[Q-isitanum]{Is the argument a number?}

\TeX{}'s own lexical analysis doesn't offer the macro programmer
terribly much support: while category codes will distinguish letters
(or what \TeX{} currently thinks of as letters) from everything else,
there's no support for analysing numbers.

The simple-minded solution is to compare numeric characters with the
characters of the argument, one by one, by a sequence of direct tests,
and to declare the argument ``not a number'' if any character fails
all comparisons:
\begin{quote}
\begin{verbatim}
\ifx1#1
\else\ifx2#1
...
\else\ifx9#1
\else\isanumfalse
\fi\fi...\fi
\end{verbatim}
\end{quote}
which one would then use in a tail-recursing macro to gobble an
argument.  One could do slightly better by assuming (pretty safely)
that the digits' character codes are consecutive:
\begin{quote}
\begin{verbatim}
\ifnum`#1<`0 \isanumfalse
\else\ifnum`#1>`9 \isanumfalse
     \fi
\fi
\end{verbatim}
\end{quote}
again used in tail-recursion.  However, these forms aren't very
satisfactory: getting the recursion ``right'' is troublesome (it has a
tendency to gobble spaces in the argument), and in any case \TeX{}
itself has mechanisms for reading numbers, and it would be nice to use
them.

Donald Arseneau's \Package{cite} package offers the following test
for an argument being a strictly positive integer:
\begin{quote}
\begin{verbatim}
\def\IsPositive#1{%
  TT\fi
  \ifcat_\ifnum0<0#1 _\else A\fi
}
\end{verbatim}
\end{quote}
which can be adapted to a test for a non-negative integer thus:
\begin{quote}
\begin{verbatim}
\def\IsNonNegative{%
  \ifcat_\ifnum9<1#1 _\else A\fi
}
\end{verbatim}
\end{quote}
or a test for any integer:
\begin{quote}
\begin{verbatim}
\def\gobbleminus#1{\ifx-#1\else#1\fi}
\def\IsInteger#1{%
  TT\fi
  \ifcat_\ifnum9<1\gobbleminus#1 _\else A\fi
}
\end{verbatim}
\end{quote}
but this surely stretches the technique further than is reasonable.

If we don't care about the sign, we can use \TeX{} to remove the
entire number (sign and all) from the input stream, and then look at
what's left:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\testnum#1{\afterassignment\testresult
               \count255=0#1 \end}
\def\testresult#1\end{\ifx\end#1\end}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\testnum#1{\afterassignment\testresult\count255=0#1 \end}
\def\testresult#1\end{\ifx\end#1\end\isanumtrue\else\isanumfalse\fi}
\end{verbatim}
\end{wideversion}
\end{quote}
(which technique is due to David Kastrup; the trick for avoiding the
errors, noted in an earlier version of this answer, was suggested by
Andreas Matthias).
In a later thread on the same topic, Michael Downes offered:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\def\IsInteger#1{%
  TT\fi
  \begingroup \lccode`\-=`\0 \lccode`+=`\0
    \lccode`\1=`\0 \lccode`\2=`\0 \lccode`\3=`\0
    \lccode`\4=`\0 \lccode`\5=`\0 \lccode`\6=`\0
    \lccode`\7=`\0 \lccode`\8=`\0 \lccode`\9=`\0
  \lowercase{\endgroup
    \expandafter\ifx\expandafter\delimiter
    \romannumeral0\string#1}\delimiter
}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\def\IsInteger#1{%
  TT\fi
  \begingroup \lccode`\-=`\0 \lccode`+=`\0
    \lccode`\1=`\0 \lccode`\2=`\0
    \lccode`\3=`\0 \lccode`\4=`\0
    \lccode`\5=`\0 \lccode`\6=`\0
    \lccode`\7=`\0 \lccode`\8=`\0
    \lccode`\9=`\0
  \lowercase{\endgroup
    \expandafter\ifx\expandafter\delimiter
    \romannumeral0\string#1}\delimiter
}
\end{verbatim}
\end{narrowversion}
\end{quote}
which relies on \csx{romannumeral} producing an empty result if its
argument is zero.  Sadly, this technique has the unfortunate property
that it accepts simple expressions such as `\texttt{1+2-3}'; this
could be solved by an initial \csx{gobbleminus}-like construction.

All the complete functions above are designed to be used in \TeX{}
conditionals written ``naturally''~--- for example:
\begin{quote}
\begin{verbatim}
\if\IsInteger{<subject of test>}%
  <deal with integer>%
\else
  <deal with non-integer>%
\fi
\end{verbatim}
\end{quote}
The \LaTeX{} \Class{memoir} class has an internal command of its own,
\cmdinvoke*{checkifinteger}{num}, that sets the conditional command
\csx{ifinteger} according to whether the argument was an integer.

Of course, all this kerfuffle would be (essentially) void if there was
a simple means of ``catching'' \TeX{} errors.  Imagining an
error-catching primitive \csx{ifnoerror}, one might write:
\begin{quote}
\begin{verbatim}
\def\IsInteger#1{%
  TT%
  \ifnoerror
    \tempcount=#1\relax
% carries on if no error
    \expandafter\iftrue
  \else
% here if there was an error
    \expandafter\iffalse
  \fi
}
\end{verbatim}
\end{quote}
thus using \TeX{}'s own integer-parsing code to do the check.  It's a
pity that such a mechanism was never defined (it could be that it's
impossible to program within \TeX{}!).
\begin{ctanrefs}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}

\Question[Q-hash]{Defining macros within macros}

The way to think of this is that |##| gets replaced by |#| in just the
same way that |#1| gets replaced by `whatever is the first argument'.

So if you define a macro:
\begin{quote}
\begin{verbatim}
\newcommand\a[1]{+#1+#1+#1+}
\end{verbatim}
\end{quote}
or (using the \tex{} primitive \csx{def}):
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+#1+#1+}
\end{verbatim}
\end{quote}
and use it as \cmdinvoke{a}{b},
the macro expansion produces `+b+b+b+',
as most people would expect.

However, if we now replace part of the macro:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand\a[1]{+#1+%
                 \newcommand\x[1]{xxx#1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand\a[1]{+#1+\newcommand\x[1]{xxx#1}}
\end{verbatim}
\end{wideversion}
\end{quote}
then \cmdinvoke{a}{b} will give us the rather odd
\begin{quote}
  +b+\cmdinvoke{newcommand}{x}[1]{xxxb}
\end{quote}
so that the new \csx{x} ignores its argument.

If we use the \tex{} primitive: 
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+\def\x #1{xxx#1}}
\end{verbatim}
\end{quote}
\cmdinvoke{a}{b} will expand to `+b+|\def\x b{xxxb}|'.  This
defines \csx{x} to be a macro \emph{delimited} by |b|, and taking no
arguments, which is surely not what was intended!

Actually, to define \csx{x} to take an argument, we need
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\newcommand\a[1]{+#1+%
                 \newcommand\x[1]{xxx##1}}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\newcommand\a[1]{+#1+\newcommand\x[1]{xxx##1}}
\end{verbatim}
\end{wideversion}
\end{quote}
or, using the \tex{} primitive definition:
\begin{quote}
\begin{verbatim}
\def\a#1{+#1+\def\x ##1{xxx##1}}
\end{verbatim}
\end{quote}
and \cmdinvoke{a}{b} will expand to 
\begin{quote}
  +b+|\def\x #1{xxx#1}|
\end{quote}
because |#1| gets replaced by `b'
and |##| gets replaced by |#|.

To nest a definition inside a definition inside a definition then you
need |####1|, doubling the number of |#| signs; and at the next level
you need 8~|#|s each time, and so on.

\Question[Q-spinmacro]{Spaces in macros}

It's very easy to write macros that produce space in the typeset
output where it's neither desired nor expected.  Spaces introduced by
macros are particularly insidious because they don't amalgamate with
spaces around the macro (unlike consecutive spaces that you
type), so your output can have a single bloated space that proves
to be made up of two or even more spaces that haven't amalgamated.
And of course, your output can also have a space where none was wanted
at all.

Spaces are produced, inside a macro as elsewhere, by space or tab
characters, or by end-of-line characters.  There are two basic rules
to remember when writing a macro: first, the rules for ignoring spaces
when you're typing macros are just the same as the rules that apply
when you're typing ordinary text, and second, rules for ignoring
spaces do \emph{not} apply to spaces produced while a macro is being
obeyed (``expanded'').

Spaces are ignored in vertical mode (between paragraphs), at the
beginning of a line, and after a command name.  Since sequences of
spaces are collapsed into one, it `feels as if' spaces are ignored if
they follow another space.  Space can have syntactic meaning after
certain sorts of non-braced arguments (e.g., \emph{count} and
\emph{dimen} variable assignments in \plaintex{}) and after certain
control words (e.g., in \csx{hbox} |to|, so again we have instances
where it `feels as if' spaces are being ignored when they're merely
working quietly for their living.

Consider the following macro, fairly faithfully adapted from one that
appeared on \Newsgroup{comp.text.tex}:
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]
  { \bigskip \makebox[2cm]{ \textbf{#1} } }
\end{verbatim}
\end{quote}
(the original appeared on a single line: it's wrapped here to fit in
the printed \acro{FAQ}'s narrow columns).

\nothtml{\noindent}
\end{narrowversion}
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]{ \bigskip \makebox[2cm]{ \textbf{#1} } }
\end{verbatim}
\end{quote}
\end{wideversion}
The macro definition contains five spaces:
\begin{itemize}
\item after the opening |{| of the macro body; this space will be
  ignored, not because ``because the macro appears at the start of a
  line'', but rather because the macro was designed to operate between
  paragraphs
\item after \csx{bigskip}; this space will be ignored (while the macro
  is being defined) because it follows a command name
\item after the |{| of the mandatory argument of \csx{makebox}; even
  though this space will inevitably appear at the start of an output
  line, it will \emph{not} be ignored
\item after the |}| closing the argument of \csx{textbf}; this space
  will not be ignored, but may be overlooked if the argument is well
  within the |2cm| allowed for it
\item after the |}| closing the mandatory argument of \csx{makebox};
  this space will not be ignored
\end{itemize}
The original author of the macro had been concerned that the starts of
his lines with this macro in them were not at the left margin, and
that the text appearing after the macro wasn't always properly
aligned.  These problems arose from the space at the start of the
mandatory argument of \csx{makebox} and the space immediately after the
same argument.  He had written his macro in that way to emphasise the
meaning of its various parts; unfortunately the meaning was rather
lost in the problems the macro caused.

The principal technique for suppressing spaces is the use of
\texttt{\textpercent{}} characters: everything after a
\texttt{\textpercent{}} is ignored, even the end of line itself (so
that not even the end of line can contribute an unwanted space).  The
secondary technique is to ensure that the end of line is preceded by a
command name (since the end of line behaves like a space, it will be
ignored following a command name).  Thus the above command would be
written (by an experienced programmer with a similar eye to
emphasising the structure):
\begin{quote}
\begin{verbatim}
\newcommand{\stline}[1]{%
  \bigskip
  \makebox[2cm]{%
    \textbf{#1}\relax
  }%
}
\end{verbatim}
\end{quote}
Care has been taken to ensure that every space in the revised
definition is ignored, so none appears in the output.  The revised
definition takes the ``belt and braces'' approach, explicitly dealing
with every line ending (although, as noted above, a space introduced
at the end of the first line of the macro would have been ignored in
actual use of the macro.  This is the best technique, in fact~--- it's
easier to blindly suppress spaces than to analyse at every point
whether you actually need to.  Three techniques were used to suppress
spaces:
\begin{itemize}
\item placing a \texttt{\textpercent{}} character at the end of a line
  (as in the 1st, 3rd and 5th lines),
\item ending a line `naturally' with a control sequence, as in line 2,
  and
\item ending a line with an `artificial' control sequence, as in line
  4; the control sequence in this case (\csx{relax}) is a no-op in many
  circumstances (as here), but this usage is deprecated~--- a
  \texttt{\textpercent{}} character would have been better.
\end{itemize}
Beware of the (common) temptation to place a space \emph{before} a
\texttt{\textpercent{}} character: if you do this you might as well omit
the \texttt{\textpercent{}} altogether.

In ``real life'', of course, the spaces that appear in macros are far
more cryptic than those in the example above.  The most common spaces
arise from unprotected line ends, and this is an error that
occasionally appears even in macros written by the most accomplished
programmers.

\Question[Q-moren9]{How to break the 9-argument limit}

If you think about it, you will realise that Knuth's command
definition syntax:
\begin{quote}
\begin{verbatim}
\def\blah#1#2 ... #9{<macro body>}
\end{verbatim}
\end{quote}
is intrinsically limited to just 9 arguments.  There's no direct way
round this: how would you express a 10th argument?~--- and ensure that
the syntax didn't gobble some other valid usage?

If you really must have more than 9 arguments, the way to go is:
\begin{quote}
\begin{verbatim}
\def\blah#1#2 ... #9{%
  \def\ArgI{{#1}}%
  \def\ArgII{{#2}}%
  ...
  \def\ArgIX{{#9}}%
  \BlahRelay
}
\def\BlahRelay#1#2#3{%
  % arguments 1-9 are now in
  %   \ArgI-\ArgIX
  % arguments 10-12 are in
  %   #1-#3
  <macro body>%
}
\end{verbatim}
\end{quote}
This technique is easily extendible by concert pianists of the \TeX{}
keyboard, but is really hard to recommend.

\LaTeX{} users have the small convenience of merely giving a number of
arguments in the \csx{newcommand} that defines each part of the
relaying mechanism: Knuth's restriction applies to \csx{newcommand}
just as it does to \csx{def}.  However, \LaTeX{} users also have the
way out of such barbarous command syntax: the \Package{keyval}
package.  With \Package{keyval}, and a bit of programming, one can
write really quite sophisticated commands, whose invocation might look
like:
\begin{quote}
\begin{verbatim}
\flowerinstance{species=Primula veris,
  family=Primulaceae,
  location=Coldham's Common,
  locationtype=Common grazing land,
  date=1995/04/24,
  numplants=50,
  soiltype=alkaline
}
\end{verbatim}
\end{quote}
The merit of such verbosity is that it is self-explanatory: the typist
doesn't have to remember that argument twelve is |soiltype|, and so
on: the commands may be copied from field notes quickly and
accurately.
\begin{ctanrefs}
\item[keyval.sty]Distributed as part of \CTANref{graphics}[keyval]
\end{ctanrefs}

        * faq-mac-prog.tex (q-keyval): tweak words about getoptk

\Question[Q-keyval]{Key-value input for macros and package options}

When we discussed % !line break
\Qref*{extending the number of arguments to a macro}{Q-moren9}, we
suggested that large numbers of arguments, distinguished only by their
position, aren't very kind to the user, and that a package such as
\Package{keyval} offers a more attractive user interface.  We now
consider the packages that the macro programmer might use, to create
such a user interface.

The simplest key-value processor (for \latex{}, at least) remains
\Package{keyval}; it has a command \csx{define@key} to declare a key
and a \emph{handler} to process it, and a macro \csx{setkeys} to offer
values to the handler of one or more keys.  Thus:
\begin{quote}
\begin{verbatim}
\define@key{my}{foo}{Foo is #1\par}
\define@key{my}{bar}[99]{Bar is #1\par}
...
\setkeys{my}{foo=3,bar}
\end{verbatim}
\end{quote}
will produce output saying:
\begin{quote}
  Foo is 3\par{}
  Bar is 99
\end{quote}
This has defined two keys `\texttt{foo}' and `\texttt{bar}' in family
`\texttt{my}', and then executed them, the first with argument
`\texttt{3}' and the second with no argument, so that the default
value of `\texttt{99}' is picked up.  In effect, the two calls to
\csx{define@key} are simply defining commands, as (for example):
\begin{quote}
\begin{verbatim}
\newcommand{\KV@my@foo}[1]{Foo is #1}
\end{verbatim}
\end{quote}
(the definition of \csx{KV@my@bar} is similar, but trickier).  The
command \csx{setkeys} knows how to find those commands when it needs to
process each key~--- it is easy to regurgitate the structure of the
command name, with family name (`\texttt{my}', here) after the first
`\texttt{@}', and the key name after the second `\texttt{@}'.  (The
`\texttt{KV}' part is fixed, in \Package{keyval}.)

These simple commands are enough, in fact, to process the botanical
example offered as replacement for multi-argument commands in % ! line break
\Qref[question]{the question mentioned above}{Q-moren9}, or the
optional arguments of the \csx{includegraphics} command of the
\Package{graphicx} package.  (The last is, in fact, what
\Package{keyval} was designed to do.)

However, we need more if we're to to have package options in
`key-value' form.  Packages like \Package{hyperref} have enormously
complicated package options which need key-value processing at
\csx{ProcessOptions} time: \Package{keyval} can't do that on its own.

Heiko Oberdiek's \Package{kvoptions} package comes to our help: it
enables the programmer to declare class or package options that
operate as key and value pairs.  The package defines commands
\csx{DeclareBoolOption} for options whose value should be either
\emph{true} or \emph{false}, and \csx{DeclareStringOption} for all
other options that have a value.  Keys are declared using
\Package{keyval} and may remain available for use within the document,
or may be `cancelled' to avoid confusion.  If you have loaded
\Package{kvoptions}, the \LaTeX{} kernel's \csx{DeclareOption} becomes
\csx{DeclareVoidOption} (it's an option with no value), and
\csx{DeclareOption*} becomes \csx{DeclareDefaultOption}.

Heiko also provides \Package{kvsetkeys} which is a more robust version
of \Package{setkeys}, with some of the rough edges made smoother.

Hendri Adriaens' \Package{xkeyval} offers more flexibility than
the original \Package{keyval} and is more robust than the original,
too.  Like \Package{kvoptions}, the package also has mechanisms to
allow class and package options in key-value form (macros
\csx{DeclareOptionX}, \csx{ExecuteOptionsX} and \csx{ProcessOptionsX}.
\Package{Pstricks} bundle packages use a \Package{xkeyval} derivative
called \Package{pst-xkey} for their own key-value manipulation.
% xkvview? (i think we can ignore xkvltxp for these purposes)

The (widely-respected) \Package{pgf} graphics package has its own
key-value package called \Package{pgfkeys}.  The documentation of the
package (part of the huge \Package{pgf} manual, in part 5,
``utilities'') contains a useful comparison with other key-value
systems; some notable differences are:
\begin{itemize}
\item key organisation: \Package{pgfkeys} uses a tree structure, while
  \Package{keyval} and \Package{xkeyval} both associate keys with a family;
\item \Package{pgfkeys} supports multi-argument key code; and
\item \Package{pgfkeys} can support call-backs when an unknown key
  appears (these things are called \emph{handlers}.
\end{itemize}
Keys are organized in a tree that is reminiscent of the Unix fille
tree.  A typical key might be, \File{/tikz/coordinate system/x} or
just \File{/x}.  When you specify keys you can provide the complete
path of the key, but you usually just provide the name of the key
(corresponding to the file name without any path) and the path is
added automatically.  So a \csx{pgfkeys} command might be:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key=hello,/your keys/main key=something\strange,
  key name without path=something else}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key=hello,
  /your keys/main key=something\strange,
  key name without path=something else}
\end{verbatim}
\end{quote}
\end{narrowversion}
and for each key mentioned, the associated code will be executed.
\dots{} and that code is also set up using \csx{pgfkeys}:
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key/.code=The value is '#1'.}
\end{verbatim}
\end{quote}
after which
\begin{quote}
\begin{verbatim}
\pgfkeys{/my key=hi!}
\end{verbatim}
\end{quote}
will produce just
\begin{quote}
  The value is 'hi!'.
\end{quote}
The manual goes on, showing how to define a key with two arguments,
how to provide default value for a key, and how to define aliases for
particular key sequences (which are called ``styles'').  All in all,
it seems a well thought-out system, offering a lot of flexibility that
isn't available with the other keys packages.  However, there seems to
be no mechanism for using \Package{pgfkeys} keys as part of the
options of another package, in the way that \Package{kvoptions} does.

The \Package{l3kernel} programming layer for \Qref*{\LaTeX{}3}{Q-LaTeX3}
includes the \Package{l3keys} module.  Inspired by \Package{pgfkeys},
it provides a keyval-based method for the programmer to create keys.
As with keyval and derivatives, \Package{l3keys} uses separate macros
for defining and setting keys.  The package \Package{l3keys2e} makes
it possible for \latexe{} class and package
options to be processed using \Package{l3keys}. \Package{L3kernel}
code can be used within existing LaTeX2e documents, so
\Package{l3keys} is also available to the \latexe{} programmer `direct'.

Another key-value system that's part of larger set of macros is
\Package{scrbase}, which uses the facilities of \Package{keyval} to
build a larger set of facilities, originally for use within the
\Class{KOMA-script} bundle.  For English-speaking authors, there are
difficulties from the German-only documentation; however, from a
partial translation available to the author of this answer, a summary
is possible.  The package may build on the facilities either of
\Package{kyeval} or of \Package{xkeyval}, and builds its functionality
on the structure of the `key family'.  The user may define family
`members' and keys are defined relative to the members.  (For example,
the package \Package{scrbase} is part of the \Class{KOMA-script}
bundle; so its keys are all members of the \Package{scrbase.sty}
family within the \Package{KOMA} family.  The function
\csx{FamilyProcessOptions} allows the programmer to decode the options
of the package in terms of the package's key family.  Note that there
is no special provision made for ``traditional'' package options, as
in the \Package{kvoptions} package.

This brief summary was guided by input from two sources: a draft article
for \textsl{TUGboat} by Joseph Wright, and the partial translation of the
documentation of package \Package{scrbase} prepared by Philipp
Stephani.

All the above are (at least) aimed at \latex{} programming; there is
one package, \Package{getoptk}, aimed at the \plaintex{} programmer.
\Package{Getoptk} uses syntax inspired by that offered by \tex{}
primitives such as \csx{hrule} and \csx{hbox}, so we are offered
syntax such as:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\begindisplay file {chapter1} literal offset 20pt
\end{verbatim}
\end{quote}
(taken from the package manual).
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\begindisplay file {chapter1} %
                literal offset 20pt
\end{verbatim}
\end{quote}
(taken from the package manual, but wrapped to fit into narrow
columns).
\end{narrowversion}

There are (we know) people who would swear that such syntax is
wonderful (the present author wouldn't), but the package earns its
place as the only stand-alone key-value macros that will work in \plaintex{}.
\begin{ctanrefs}
\item[getoptk.tex]\CTANref{getoptk}
\item[keyval.sty]Distributed as part of \CTANref{graphics}[keyval]
\item[kvoptions.sty]Distributed as part of \CTANref{oberdiek}[kvoptions]
\item[kvsetkeys.sty]Distributed as part of \CTANref{oberdiek}[kvsetkeys]
\item[l3keys.sty]Distributed as part of \CTANref{l3kernel}
\item[l3keys2e.sty]Distributed as part of \CTANref{l3packages}
\item[pgfkeys.sty]Distributed as part of \CTANref{pgf}
\item[scrbase.sty]Distributed as part of \CTANref{koma-script}
\item[xkeyval.sty]\CTANref{xkeyval}
\end{ctanrefs}
\LastEdit{2011-09-06}

\Question[Q-activechars]{Defining characters as macros}

Single characters can act as macros (defined commands), and both
\plaintex{} and \LaTeX{} define the character
``\texttt{\textasciitilde}'' as a ``non-breakable space''.  A
character is made definable, or ``active'', by setting its
\emph{category code} (catcode) to be \csx{active} (13):
\begin{quote}
\begin{verbatim}
\catcode`\_=\active
\end{verbatim}
\end{quote}
Any character could, in principle, be activated this way and defined
as a macro:
\begin{quote}
\begin{verbatim}
\def_{\_}
\end{verbatim}
\end{quote}
which could be characterised as an over-simple answer to % ! line break
\Qref[question]{using underscores}{Q-underscore}.  However, you must be
wary: whereas people expect an active tilde, other active characters
may be unexpected and interact badly with other macros.  Furthermore,
by defining an active character, you preclude the character's use for
other purposes, and there are few characters ``free'' to be subverted
in this way.

To define the character ``\texttt{z}'' as a command, one would say something
like:
\begin{quote}
\begin{verbatim}
\catcode`\z=\active
\def z{Yawn, I'm tired}%
\end{verbatim}
\end{quote}
and each subsequent ``\texttt{z}'' in the text would become a
yawn. This would be an astoundingly bad idea for most documents, but
might have special applications.  (Note that, in ``\csx{def}\texttt{
  z}'', ``\texttt{z}'' is no longer interpreted as a letter; the space
is therefore not necessary~--- ``\csx{defz}'' would do; we choose to
retain the space, for what little clarity we can manage.)
Some \LaTeX{} packages facilitate such definitions. For example, the
\Package{shortvrb} package with its \csx{MakeShortVerb} command.

\TeX{} uses category codes to interpret characters as they are read 
from the input.
% beware line break
\emph{Changing a catcode value will not affect characters that have already been read}.
Therefore, it is best if characters have fixed category codes for the
duration of a document.  If catcodes are changed for particular
purposes (the \csx{verb} command does this), then the altered
characters will not be interpreted properly when they  appear in the
argument to another command (as, for example, in
% beware line-break
\htmlonly{``}\Qref[question]{\csx{verb} in command arguments}{Q-verbwithin}\htmlonly{''}).
An exemplary case is the \Package{doc} package, which processes .dtx
files using the \Package{shortvrb} package to define
\texttt{\textbar\dots{}\textbar} as a shorthand for
\csx{verb}\texttt{\textbar\dots{}\textbar}. But \texttt{\textbar} is
also used in the preambles of tabular environments, so that tables in
\extension{dtx} files can only have vertical line separation between
columns by employing special measures of some sort.

Another consequence is that catcode assignments made
in macros often don't work as expected % beware linebreak
(\htmlonly{see ``}\Qref{Active characters in command arguments}{Q-actinarg}\htmlonly{''}).
For example, the definition
\begin{quote}
\begin{verbatim}
\def\mistake{%
\catcode`_=\active
\def_{\textunderscore\-}%
}
\end{verbatim}
\end{quote}
does not work because it attempts to define an ordinary \texttt{\_} character:
When the macro is used, the category change does not apply to the 
underscore character already in the macro definition.  Instead, one may
use:
\begin{quote}
\begin{verbatim}
\begingroup
\catcode`_=\active
\gdef\works{%    note the global \gdef
  \catcode`_=\active
  \def_{\textunderscore\-}%
}
\endgroup
\end{verbatim}
\end{quote}
The alternative (``tricksy'') way of creating such an isolated
definition depends on the curious properties of \csx{lowercase}, which
changes characters without altering their catcodes.  Since there is
always \emph{one} active character (``\texttt{\textasciitilde}''), we
can fool \csx{lowercase} into patching up a definition without ever
explicitly changing a catcode:
\begin{quote}
\begin{verbatim}
\begingroup
  \lccode`\~=`\_
  \lowercase{\endgroup
    \def~{\textunderscore\-}%
  }%
\end{verbatim}
\end{quote}
The two definitions have the same overall effect (the character is
defined as a command, but the character does not remain active),
except that the first defines a \csx{global} command.

For active characters to be used only in maths mode, it is much better
to leave the character having its ordinary catcode, but assign it a
special active \emph{maths code}, as with
\begin{quote}
\begin{verbatim}
\begingroup
  \lccode`~=`x
  \lowercase{\endgroup
    \def~{\times}%
  }%
\mathcode`x="8000
\end{verbatim}
\end{quote}
The special character does not need to be redefined whenever it is
made active~--- the definition of the command persists even if the
character's catcode reverts to its original value; the definition
becomes accessible again if the character once again becomes active.
\begin{ctanrefs}
\item[doc.sty]Part of the \LaTeX{} distribution \CTANref{latex}[doc]
\item[shortvrb.sty]Part of the \LaTeX{} distribution \CTANref{latex}[shortvrb]
\end{ctanrefs}


\Question[Q-actinarg]{Active characters in command arguments}

Occasionally, it's nice to make one or two characters active in the
argument of a command, to make it easier for authors to code the
arguments.

Active characters \emph{can} be used safely in such situations; but
care is needed.

An example arose while this answer was being considered: an aspirant
macro writer posted to \Newsgroup{comp.text.tex} asking for help to
make |#| and |b| produce musical sharp and flat signs, respectively,
in a macro for specifying chords.

The first problem is that both |#| and |b| have rather important uses
elsewhere in \TeX{} (to say the least!), so that the characters can
only be made active while the command is executing.

Using the techniques discussed in % beware line break, next line
\htmlonly{``}\Qref[question]{characters as commands}{Q-activechars}\htmlonly{''},
we can define:
\begin{quote}
\begin{verbatim}
\begingroup
  \catcode`\#=\active
  \gdef#{$\sharp$}
\endgroup
\end{verbatim}
\end{quote}
and:
\begin{quote}
\begin{verbatim}
\begingroup
  \lccode`\~=`\b
  \lowercase{\endgroup
    \def~{$\flat$}%
  }
\end{verbatim}
\end{quote}
The second problem is one of timing: the command has to make each
character active \emph{before} its arguments are read: this means that
the command can't actually ``have'' arguments itself, but must be
split in two.  So we write:
\begin{quote}
\begin{verbatim}
\def\chord{%
  \begingroup
    \catcode`\#=\active
    \catcode`\b=\active
    \Xchord
}
\def\Xchord#1{%
    \chordfont#1%
  \endgroup
}
\end{verbatim}
\end{quote}
and we can use the command as \cmdinvoke{chord}{F\#} or
\cmdinvoke{chord}{Bb minor}.

Two features of the coding are important:
\begin{itemize}
\item \csx{begingroup} in \csx{chord} opens a group that is closed by
  \csx{endgroup} in \csx{Xchord}; this group limits the change of
  category codes, which is the \emph{raison d'\^etre} of the whole
  exercise.
\item Although |#| is active while \csx{Xchord} is executed, it's
  \emph{not} active when it's being defined, so that the use of |#1|
  doesn't require any special attention.
\end{itemize}

Note that the technique used in such macros as \csx{chord}, here, is
analogous to that used in such commands as \csx{verb}; and, in just the
same way as \csx{verb} (see
% beware breaking long line
\htmlonly{``}\Qref[question]{\csx{verb} doesn't work in arguments}{Q-verbwithin}\htmlonly{''}),
\csx{chord} won't work inside the argument of another command (the
error messages, if they appear at all, will probably be rather odd).


\Question[Q-csname]{Defining a macro from an argument}

It's common to want a command to create another command: often one
wants the new command's name to derive from an argument.  \LaTeX{}
does this all the time: for example, \csx{newenvironment} creates
start- and end-environment commands whose names are derived from the
name of the environment command.

The (seemingly) obvious approach:
\begin{quote}
\begin{verbatim}
\def\relay#1#2{\def\#1{#2}}
\end{verbatim}
\end{quote}
doesn't work (the \TeX{} engine interprets it
as a rather strange redefinition of |\#|).  The trick is to use
\csx{csname}, which is a \TeX{} primitive for generating command names
from random text, together with \csx{expandafter}.  The definition
above should read:
\begin{quote}
\begin{verbatim}
\def\relay#1#2{%
  \expandafter\def\csname #1\endcsname{#2}%
}
\end{verbatim}
\end{quote}
With this definition, \cmdinvoke{relay}{blah}{bleah} is equivalent to
\csx{def}\cmdinvoke{blah}{bleah}.

Note that the definition of \csx{relay} omits the braces round the
`command name' in the \csx{newcommand} it executes.  This is
because they're not necessary (in fact they seldom are), and in this
circumstance they make the macro code slightly more tedious.

The name created need not (of course) be \emph{just} the argument:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\def\newrace#1#2#3{\expandafter\def
    \csname start#1\endcsname{%
      #2%
  }%
  \expandafter\def
    \csname finish#1\endcsname{%
      #3%
  }%
}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\def\newrace#1#2#3{%
  \expandafter\def\csname start#1\endcsname{%
    #2%
  }%
  \expandafter\def\csname finish#1\endcsname{%
    #3%
  }%
}
\end{verbatim}
\end{wideversion}
\end{quote}
With commands
\begin{quote}
\begin{verbatim}
\def\start#1{\csname start#1\endcsname}
\def\finish#1{\csname finish#1\endcsname}
\end{verbatim}
\end{quote}
these `races' could behave a bit like \LaTeX{} environments.

\Question[Q-cvtlatex]{Transcribing \LaTeX{} command definitions}

At several places in this \acro{FAQ}, questions are answered in terms
of how to program a \LaTeX{} macro.  Sometimes, these macros might
also help users of \plaintex{} or other packages; this answer
attempts to provide a rough-and-ready guide to transcribing such macro
definitions for use in other packages.

The reason \LaTeX{} has commands that replace \csx{def}, is that
there's a general philosophy within \LaTeX{} that the user should be
protected from himself: the user has different commands according to
whether the command to be defined exists (\csx{renewcommand}) or not
(\csx{newcommand}), and if its status proves not as the user expected,
an error is reported.  A third definition command,
\csx{providecommand}, only defines if the target is not already
defined; \LaTeX{} has no direct equivalent of \csx{def}, which ignores
the present state of the command.  The final command of this sort is
\csx{DeclareRobustCommand}, which creates a command which is ``robust''
(i.e., will not expand if subjected to \LaTeX{} ``protected
expansion''); from the \plaintex{} user's point of view,
\csx{DeclareRobustCommand} should be treated as a non-checking version
of \csx{newcommand}.

\LaTeX{} commands are, by default, defined \csx{long}; an optional \texttt{*}
between the \csx{newcommand} and its (other) arguments specifies that
the command is \emph{not} to be defined \csx{long}.  The \texttt{*} is
detected by a command \csx{@ifstar} which uses \csx{futurelet} to switch
between two branches, and gobbles the \texttt{*}: \LaTeX{} users are
encouraged to think of the \texttt{*} as part of the command name.

\LaTeX{}'s checks for unknown command are done by \csx{ifx} comparison
of a \csx{csname} construction with \csx{relax}; since the command name
argument is the desired control sequence name, this proves a little
long-winded.  Since \texttt{\#1} is the requisite argument, we have:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter\ifx
  \csname
    \expandafter\@gobble\string#1%
  \endcsname
  \relax
    ...
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter\ifx
  \csname\expandafter\@gobble\string#1\endcsname
  \relax
    ...
\end{verbatim}
\end{wideversion}
\end{quote}
(\csx{@gobble} simply throws away its argument).

The arguments of a \LaTeX{} command are specified by two optional
arguments to the defining command: a count of arguments (0--9: if the
count is 0, the optional count argument may be omitted), and a default
value for the first argument, if the defined command's first argument
is to be optional.  So:
\begin{quote}
\begin{verbatim}
\newcommand\foo{...}
\newcommand\foo[0]{...}
\newcommand\foo[1]{...#1...}
\newcommand\foo[2][boo]{...#1...#2...}
\end{verbatim}
\end{quote}
In the last case, \csx{foo} may be called as \cmdinvoke{foo}{goodbye},
which is equivalent to \cmdinvoke{foo}[boo]{goodbye} (employing the
default value given for the first argument), or as
\cmdinvoke{foo}[hello]{goodbye} (with an explicit first argument).

Coding of commands with optional arguments is exemplified by the
coding of the last \csx{foo} above:
\begin{quote}
\begin{verbatim}
\def\foo{\futurelet\next\@r@foo}
\def\@r@foo{\ifx\next[%
    \let\next\@x@foo
  \else
    \def\next{\@x@foo[boo]}%
  \fi
  \next
}
\def\@x@foo[#1]#2{...#1...#2...}
\end{verbatim}
\end{quote}

\Question[Q-empty]{Detecting that something is empty}

Suppose you need to know that the argument of your command is empty:
that is, to distinguish between \cmdinvoke{cmd}{\relax} % \relax doesn't print
and \cmdinvoke{cmd}{blah}.  This is pretty simple:
\begin{quote}
\begin{verbatim}
\def\cmd#1{%
  \def\tempa{}%
  \def\tempb{#1}%
  \ifx\tempa\tempb
    <empty case>
  \else
    <non-empty case>
  \fi
}
\end{verbatim}
\end{quote}
The case where you want to ignore an argument that consists of nothing
but spaces, rather than something completely empty, is more tricky.
It's solved in the code fragment \Package{ifmtarg}, which defines
commands \csx{@ifmtarg} and \csx{@ifnotmtarg}, which examine their
first argument, and select (in opposite directions) their second or
third argument.  The package's code also appears in the \LaTeX{}
\Class{memoir} class.

\Package{Ifmtarg} makes challenging reading; there's also a discussion of the
issue in number two of the ``around the bend'' articles by the late
lamented Mike Downes.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}Around the bend series]\CTANref{aro-bend}
\item[ifmtarg.sty]\CTANref{ifmtarg}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}

\Question[Q-whatengine]{Am I using \pdftex{}, \xetex{} or \luatex{}?}
\AliasQuestion{Q-ifpdf}

You often need to know what ``engine'' your macros are running on (the
engine is the \tex{}-derivative or \tex{}-alike processor that
typesets your document).  The reason that you need to know is that the
set of functions available in each engine is different.  Thus, for
\tex{} macros to run on any engine, they need to ``know'' what they
can and cannot do, which depends on the engine in use.  Getting the
right answer is surprisingly tricky (see below for an elaboration of
one apparently simple test).

There is now a comprehensive set of packages that answer the question
for you.  They all create a \tex{} conditional command:
\begin{itemize}
\item \Package{ifpdf} creates a command \csx{ifpdf},
\item \Package{ifxetex} creates a command \csx{ifxetex} and
\item \Package{ifluatex} creates a command \csx{ifluatex}.
\end{itemize}
These \tex{} commands may be used within the \latex{} conditional
framework, as (for example):
\begin{quote}
  \csx{ifthenelse}\texttt{\obracesymbol{}}\cmdinvoke{boolean}{pdf}\texttt{\cbracesymbol{}}\texttt{\obracesymbol{}}\meta{if pdf}\texttt{\cbracesymbol{}}\texttt{\obracesymbol{}}\meta{if not pdf}\texttt{\cbracesymbol{}}
\end{quote}

The \Package{ifxetex} package also provides a command
\csx{RequireXeTeX} which creates an error if the code is not running
under \xetex{}; while the other packages don't provide such a command,
it's not really difficult to write one for yourself.

% khalighi's iftex package, too -- \require's for all engines, but i'm
% not entirely sure of the conditionals, so "for later" if at all

Now for those who want to do the job for themselves: here's a
discussion of doing the job for \pdftex{} and \csx{ifpdf}~--- the
eager programmer can regenerate \csx{ifxetex} or \csx{ifluatex} in the
same fashion.  It's not recommended\dots

Suppose you need to test whether your output will be \acro{PDF} or
\acro{DVI}.  The natural thing is to check whether you have access to
some \PDFTeX{}-only primitive; a good one to try (not least because it
was present in the very first releases of \PDFTeX{}) is
\csx{pdfoutput}.  So you try
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
  ... % not running PDFTeX
\else
  ... % running PDFTeX
\fi
\end{verbatim}
\end{quote}
Except that neither branch of this conditional is rock-solid.  The
first branch can be misleading, since the ``awkward'' user could have
written:
\begin{quote}
\begin{verbatim}
\let\pdfoutput\undefined
\end{verbatim}
\end{quote}
so that your test will falsely choose the first alternative.  While
this is a theoretical problem, it is unlikely to be a major one.

More important is the user who loads a package that uses
\LaTeX{}-style testing for the command name's existence (for example,
the \LaTeX{} \Package{graphics} package, which is useful even to the
\plaintex{} user).  Such a package may have gone ahead of you, so the
test may need to be elaborated:
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
  ... % not running PDFTeX
\else
  \ifx\pdfoutput\relax
    ... % not running PDFTeX
  \else
    ... % running PDFTeX
  \fi
\fi
\end{verbatim}
\end{quote}
If you only want to know whether some \PDFTeX{} extension (such as
marginal kerning) is present, you can stop at this point: you know as
much as you need.

However, if you need to know whether you're creating \acro{PDF}
output, you also need to know about the value of \csx{pdfoutput}:
\begin{quote}
\begin{verbatim}
\ifx\pdfoutput\undefined
  ... % not running PDFTeX
\else
  \ifx\pdfoutput\relax
    ... % not running PDFTeX
  \else
    % running PDFTeX, with...
    \ifnum\pdfoutput>0
      ... % PDF output
    \else
      ... % DVI output
    \fi
  \fi
\fi
\end{verbatim}
\end{quote}
\begin{ctanrefs}
\item[ifpdf.sty]Distributed as part Heiko Oberdiek's bundle
  \CTANref{oberdiek}[ifpdf]
\item[ifluatex.sty]Distributed as part of Heiko Oberdiek's bundle
  \CTANref{oberdiek}[ifluatex]
\item[ifxetex.sty]\CTANref{ifxetex}
\end{ctanrefs}
\LastEdit{2012-02-13}

\Question[Q-subverttoks]{Subverting a token register}

A common requirement is to ``subvert'' a token register that other
macros may use.  The requirement arises when you want to add something
to a system token register (\csx{output} or \csx{every*}), but know
that other macros use the token register, too.  (A common requirement
is to work on \csx{everypar}, but \LaTeX{} changes \csx{everypar} at
every touch and turn.)

The following technique, due to David Kastrup, does what you need, and
allows an independent package to play the exact same game:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\let\mypkg@@everypar\everypar
\newtoks\mypkg@everypar
\mypkg@everypar\expandafter{\the\everypar}
\mypkg@@everypar{\mypkgs@ownstuff\the\mypkg@everypar}
\def\mypkgs@ownstuff{%
  <stuff to do at the start of the token register>%
}
\let\everypar\mypkg@everypar
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\let\mypkg@@everypar\everypar
\newtoks\mypkg@everypar
\mypkg@everypar\expandafter{\the\everypar}
\mypkg@@everypar{\mypkgs@ownstuff
                      \the\mypkg@everypar}
\def\mypkgs@ownstuff{%
  <stuff to do at the start of
                      the token register>%
}
\let\everypar\mypkg@everypar
\end{verbatim}
\end{narrowversion}
\end{quote}
As you can see, the package (\Package{mypkg})
\begin{itemize}
\item creates an alias for the existing ``system'' \csx{everypar}
  (which is frozen into any surrounding environment, which will carry
  on using the original);
\item creates a token register to subvert \csx{everypar} and
  initialises it with the current contents of \csx{everypar};
\item sets the ``old'' \csx{everypar} to execute its own extra code,
  as well as the contents of its own token register;
\item defines the macro for the extra code; and
\item points the token \csx{everypar} at the new token register.
\end{itemize}
and away we go.

The form \csx{mypkg@...} is (sort of) blessed for \LaTeX{} package
internal names, which is why this example uses macros of that form.

\Question[Q-isdef]{Is this command defined?}

Macro sets from the earliest days of \TeX{} programming may be
observed to test whether commands exist by using
\begin{quote}
\csx{ifx} \csx{}\texttt{\emph{command}} \csx{undefined} \meta{stuff} \dots{}
\end{quote}
(which of course actually tests that the command \emph{doesn't}
exist).  \LaTeX{} programmers can make use of the internal command
\begin{quote}
  \cmdinvoke*{@ifundefined}{cmd name}{action1}{action2}
\end{quote}
which executes \texttt{action1} if the command is undefined, and
\texttt{action2} if it is defined
(\emph{cmd name} is the command name only, omitting the `|\|' character).

The \csx{@ifundefined} command is based on the sequence
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\expandafter
    \ifx\csname cmd name\endcsname\relax
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\expandafter \ifx \csname cmd name\endcsname \relax
\end{verbatim}
\end{wideversion}
\end{quote}
which relies on the way \csx{csname} works: if the command doesn't
exist, it simply creates it as an alias for \csx{relax}.

So: what is wrong with these techniques?

Using \csx{undefined} blithely assumes that the command is indeed not
defined.  This isn't entirely safe; one could make the name more
improbable, but that may simply make it more difficult to spot a
problem when things go wrong.  \LaTeX{} programmers who use the
technique will typically employ \csx{@undefined}, adding a single
level of obscurity.

The \csx{@ifundefined} mechanism has the unfortunate property of
polluting the name space: each test that turns out undefined adds a
name to the set \TeX{} is holding, and often all those ``\csx{relax}''
names serve no purpose whatever.  Even so (sadly) there are places in
the code of \LaTeX{} where the existence of the \csx{relax} is relied
upon, after the test, so we can't get away from \csx{@ifundefined}
altogether.

David Kastrup offers the (rather tricky)
\begin{quote}
\begin{wideversion}
\begin{verbatim}
{\expandafter}\expandafter\ifx \csname cmd name\endcsname\relax ...
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
{\expandafter}\expandafter
    \ifx \csname cmd name\endcsname \relax ...
\end{verbatim}
\end{narrowversion}
\end{quote}
which ``creates'' the \csx{relax}-command inside the group of the first
\csx{expandafter}, therefore forgets it again once the test is done.
The test is about as good as you can do with macros.

The \Qref*{\eTeX{} system}{Q-etex} system comes to our help here: it
defines two new primitives:
\begin{itemize}
\item \csx{ifdefined}, which tests whether a thing is defined (the
  negative of comparing with \csx{undefined}, as it were), and
\item \csx{ifcsname} \texttt{cmd name}\csx{endcsname}, which does the
  negative of \csx{@ifundefined} without the \csx{relax}-command
  side-effect.
\end{itemize}
So, in an \eTeX{}-based system, the following two conditional clauses do
the same thing:
\begin{quote}
\begin{verbatim}
\ifdefined\foo
  \message{\string\foo\space is defined}%
\else
  \message{no command \string\foo}%
\fi
%
\ifcsname foo\endcsname
  \message{\string\foo\space is defined}%
\else
  \message{no command \string\foo}%
\fi
\end{verbatim}
\end{quote}
However, after using the \LaTeX{}
\cmdinvoke{@ifundefined}{foo}\dots{}, the conditionals will detect the
command as ``existing'' (since it has been \csx{let} to \csx{relax});
so it is important not to mix mechanisms for detecting the state of a
command.

Since most distributions nowadays use \eTeX{} as their base executable
for most packages, these two primitives may be expected appear widely
in new macro packages.

\subsection{\LaTeX{} macro tools and techniques}

\Question[Q-plninltx*]{Using Plain or primitive commands in \LaTeX{}}

It's well-known that \LaTeX{} commands tend to be more complex, and to
run more slowly than, any \plaintex{} (or primitive) command that they
replace.  There is therefore great temptation not to use \LaTeX{}
commands when macro programming.  Nevertheless, the general rule is
that you should use \LaTeX{} commands, if there are seeming
equivalents.  The exception is when you are sure you know the
differences between the two commands and you know that you need the
\plaintex{} version.  So, for example, use \csx{mbox} in place of \csx{hbox}
unless you know that the extras that \LaTeX{} provides in \csx{mbox}
would cause trouble in your application.  Similarly, use
\csx{newcommand} (or one of its relatives) unless you need one of the
constructs that cannot be achieved without the use of \csx{def} (or friends).

As a general rule, any \LaTeX{} text command will start a new
paragraph if necessary; this isn't the case with \plaintex{}
commands, a fact which has a potential to confuse.

The commands \csx{smallskip}, \csx{medskip} and \csx{bigskip} exist both
in \plaintex{} and \LaTeX{}, but behave slightly differently: in
\plaintex{} they terminate the current paragraph, but in \LaTeX{} they 
don't.  The command \csx{line} is part of picture mode in \LaTeX{},
whereas it's defined as ``\csx{hbox}\texttt{ to }\csx{hsize}'' in
\plaintex{}. (There's no equivalent for users of the \plaintex{} command in
\LaTeX{}: an equivalent appears as the internal command \csx{@@line}).

Maths setting shows a case where the \LaTeX{} version \emph{is}
essentially equivalent to the \TeX{} primitive commands: the \LaTeX{}
\csx{(}\texttt{\ ...\ }\csx{)} does essentially no different to the
primitive \texttt{\$\ ...\ \$}; except for checking that you're not
attempting to open a maths environment when you're already in one, or 
attempting to close one when you're not.
However, \csx{[}\texttt{\ ...\ }\csx{]} has a more significant
difference from \texttt{\$\$\ ...\ \$\$}: the primitive version, used
in \LaTeX{}, can miss the effect of the class option \pkgoption{fleqn}.

Font handling is, of course, wildly different in \plaintex{} and
\LaTeX{}.  \plaintex{}'s font loading command
(\csx{font}\csx{foo=}\meta{fontname}) and its \LaTeX{} equivalent
(\csx{newfont}) should be avoided wherever possible.  They are only
safe in the most trivial contexts, and are potential sources of great
confusion in many circumstances.   Further discussion of this issue
may be found in ``\Qref*{What's wrong with \csx{newfont}?}{Q-newfont*}''.
\LastEdit{2013-09-27}

\Question[Q-atsigns]{\csx{@} and \texttt{@} in macro names}

Macro names containing \texttt{@} are \emph{internal} to \LaTeX{}, and
without special treatment just don't work in ordinary use.  A nice
example of the problems caused is discussed in % ! beware line break
\Qref*{\csx{@} in vertical mode}{Q-atvert}''.

The problems users see are caused by copying bits of a class
(\extension{cls} file) or 
package (\extension{sty} file) into a document, or by including a class or
package file into a \LaTeX{} document by some means other than
\csx{documentclass} or \csx{usepackage}.  \LaTeX{} defines internal
commands whose names contain the character \texttt{@} to
avoid clashes between its internal names and names that we would
normally use in our documents.  In order that these commands may work
at all, \csx{documentclass} and \csx{usepackage} play around with the
meaning of \texttt{@}.

If you've included a file some other way (for example, using
\csx{input}), you can probably solve the problem by using the correct
command.

If you're using a fragment of a package or class, you may well feel
confused: books such as the first edition of the % ! line break
\Qref*{The \LaTeX{} Companion}{Q-latex-books} 
are full of fragments of packages as examples for you to employ.
The second edition of the \emph{Companion} makes clearer how you
should use these fragments, and in addition, the code of
all the examples is now available on \acro{CTAN}.
To see the technique in practice, look at the example below, from file
\File{2-2-7.ltx} in the \emph{Companion} examples directory:
\begin{quote}
\begin{verbatim}
\makeatletter
\renewcommand\subsection{\@startsection
  {subsection}{2}{0mm}%name, level, indent
  {-\baselineskip}%             beforeskip
  {0.5\baselineskip}%            afterskip
  {\normalfont\normalsize\itshape}}% style
\makeatother
\end{verbatim}
\end{quote}
(That example appears on page 29 of \emph{The \LaTeX{} Companion},
second edition.)

The alternative is to treat all these fragments as a package proper,
bundling them up into a \extension{sty} file and including them with
\csx{usepackage}; this way you hide your \LaTeX{} internal code somewhere
that \LaTeX{} internal code is expected, which often looks `tidier'.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}Examples from the Companion]\CTANref{tlc2}
\end{ctanrefs}
\LastEdit{2011-06-01}

\Question[Q-protect]{What's the reason for `protection'?}

Sometimes \LaTeX{} saves data it will reread later. These data are
often the argument of some command; they are the so-called moving
arguments.  (`Moving' because data are moved around.)  Candidates
are all arguments that may go into table of contents, list of figures,
\emph{etc}.; namely, data that are written to an auxiliary file and
read in later.  Other places are those data that might appear in head-
or footlines.  Section headings and figure captions are the most
prominent examples; there's a complete list in Lamport's book
(see \Qref[question]{\TeX{}-related books}{Q-latex-books}).

What's going on really, behind the scenes? The commands in moving
arguments are normally expanded to their internal structure during the
process of saving. Sometimes this expansion results in invalid \TeX{}
code, which shows either during expansion or when the code is
processed again. Protecting a command, using
``\csx{protect}\csx{cmd}'' tells \LaTeX{} to save \csx{cmd} as
\csx{cmd}, without expanding it at all.

So, what is a `fragile command'?~--- it's a command that expands into
illegal \TeX{} code during the save process.

What is a `robust command'?~--- it's a command that expands into legal
\TeX{} code during the save process.

Lamport's book says in its description of every LaTeX command whether
it is `robust' or `fragile'; it also says that every command with an
optional argument is fragile.  The list isn't reliable, and neither
is the assertion about optional arguments; the statements may have
been true in early versions of \LaTeXe{} but are not any longer
necessarily so:
\begin{itemize}
\item Some fragile commands, such as \csx{cite}, have been made robust
  in later revisions of \LaTeX{}.
\item Some commands, such as \csx{end} and \csx{nocite}, are fragile
  even though they have no optional arguments.
\item The ``user's way'' of creating a command with an optional
  argument (using \csx{newcommand} or \csx{newcommand*}) now always
  creates a robust command (though macros without optional arguments
  may still be fragile if they do things that are themselves fragile).
\item There is no reason that a package author should not also make
  robust commands with optional arguments as part of the package.
\item Some robust commands are redefined by certain packages to be
  fragile (the \csx{cite} command commonly suffers this treatment).
\end{itemize}
Further, simply ``hiding'' a fragile command in another command, has
no effect on fragility.  So, if \csx{fred} is fragile, and you write:
\begin{quote}
\begin{verbatim}
\newcommand{\jim}{\fred}
\end{verbatim}
\end{quote}
then \csx{jim} is fragile too.  There is, however, the
\csx{newcommand}-replacement \csx{DeclareRobustCommand}, which
\emph{always} creates a robust command (whether or not it has optional
arguments).  The syntax of \csx{DeclareRobustCommand} is substantially
identical to that of \csx{newcommand}, and if you do the wrapping
trick above as:
\begin{quote}
\begin{verbatim}
\DeclareRobustCommand{\jim}{\fred}
\end{verbatim}
\end{quote}
then \csx{jim} is robust.

Finally, we have the \Package{makerobust} package, which  defines
\csx{MakeRobustCommand} to convert a command to be robust.  With the
package, the ``wrapping'' above can simply be replaced by:
\begin{quote}
\begin{verbatim}
\MakeRobustCommand\fred
\end{verbatim}
\end{quote}
Whereafter, \csx{fred} is robust.  Using the package may be reasonable
if you have lots of fragile commands that you need to use in moving
arguments.

In short, the situation is confusing.  No-one believes this is
satisfactory; the \LaTeX{} team have removed the need for
protection of some things, but the techniques available in 
current \LaTeX{} mean that this is an expensive exercise.  It remains
a long-term aim of the team to remove all need for \csx{protect}ion.
\begin{ctanrefs}
\item[makerobust.sty]Distributed as part of Heiko Oberdiek's bundle
  \CTANref{oberdiek}[makerobust]
\end{ctanrefs}
\LastEdit{2011-06-01}

\Question[Q-edef]{\csx{edef} does not work with \csx{protect}}

Robust \LaTeX{} commands are either ``naturally robust''~--- meaning that
they never need \csx{protect}, or ``self-protected''~--- meaning that
they have \csx{protect} built in to their definition in some
way.  Self-protected commands, and fragile commands with
\csx{protect}ion are only robust in a context where the \csx{protect}
mechanism is properly handled.  The body of an \csx{edef} definition
doesn't handle \csx{protect} properly, since \csx{edef} is a \TeX{}
primitive rather than a \LaTeX{} command.

This problem is resolved by a \LaTeX{} internal command
\csx{protected@edef}, which does the job of \csx{edef} while keeping the
\csx{protect} mechanism working.  There's a corresponding
\csx{protected@xdef} which does the job of \csx{xdef}.

Of course, these commands need to be tended carefully, since they're
% beware line break on next line
internal: see \Qref[question]{'@' in control sequence names}{Q-atsigns}.

\Question[Q-ltxcmds]{The definitions of \LaTeX{} commands}

There are several reasons to want to know the definitions of \LaTeX{}
commands: from the simplest ``idle curiosity'', to the pressing need
to patch something to make it ``work the way you want it''.  None of
these are \emph{pure} motives, but knowledge and expertise seldom
arrive through the purest of motives.

Using a \tex{} executable of some sort, the simple answer is to try
\csx{show}, in a run that is taking commands from the terminal:
\begin{quote}
\begin{verbatim}
*\makeatletter
*\show\protected@edef
> \protected@edef=macro:
->\let \@@protect \protect
  \let \protect \@unexpandable@protect
  \afterassignment \restore@protect \edef .
\end{verbatim}
\end{quote}
(I've rearranged the output there, from the rather confused version
\TeX{} itself produces.)

So, what about \csx{@unexpandable@protect}?:
\begin{quote}
\begin{verbatim}
*\show\@unexpandable@protect
> \@unexpandable@protect=macro:
->\noexpand \protect \noexpand .
\end{verbatim}
\end{quote}
and we're starting to see how one part of the \csx{protect}ion
mechanism works (one can probably fairly safely guess what
\csx{restore@protect} does).

Many kernel commands are declared robust:
\begin{quote}
\begin{verbatim}
*\show\texttt
> \texttt=macro:
->\protect \texttt  .
\end{verbatim}
\end{quote}
so that \csx{show} isn't much help.  Define a command \csx{pshow} as
shown below, and simply execute the command to find its definition:
\begin{quote}
\begin{verbatim}
*\def\pshow#1{{\let\protect\show #1}}
*\pshow\texttt
> \texttt =\long macro:
#1->\ifmmode \nfss@text {\ttfamily #1}%
    \else \hmode@bgroup \text@command {#1}%
          \ttfamily \check@icl #1\check@icr
    \expandafter \egroup \fi .
\end{verbatim}
\end{quote}
Note that the command name that is protected is the `base' command,
with a space appended.  This is cryptically visible, in a couple of
places above.  (Again, the output has been sanitised.)
% Similar provisions are made in the package \Package{show2e} but i
% don't understand them yet...

The command \ProgName{texdef} (or \ProgName{latexdef}~--- the same
command with a different name) will do all that for you and return the
results slightly more tidily than \latex{} itself manages.  For
example:
\begin{quote}
\begin{verbatim}
$ latexdef texttt
\end{verbatim}
\end{quote}
gives:
\begin{quote}
\begin{verbatim}
macro:->\protect \texttt  

\texttt :
#1->\ifmmode \nfss@text {\ttfamily #1}%
    \else \hmode@bgroup \text@command {#1}%
          \ttfamily \check@icl #1\check@icr
    \expandafter \egroup \fi .
\end{verbatim}
\end{quote}
(again, the output has been sanitised~--- but we see that
\ProgName{latexdef} has useful `intelligence' in it, as it has spotted
and dealt with the \csx{protect}.)

With the \texttt{-s} switch, \ProgName{latexdef} will give you a
source location:
\begin{quote}
\begin{verbatim}
$ latexdef -s texttt
% latex.ltx, line 3736:
\DeclareTextFontCommand{\texttt}{\ttfamily}
\end{verbatim}
\end{quote}
though one should note that it doesn't give you the detail of the
actual coding, merely the definition's location.

Environments also surrender their details to \ProgName{latexdef}:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
$ latexdef -E itemize

\itemize:
macro:->\ifnum \@itemdepth >\thr@@ \@toodeep 
  \else \advance \@itemdepth \@ne
    \edef \@itemitem {labelitem\romannumeral \the \@itemdepth}%
    \expandafter \list \csname \@itemitem \endcsname
      {\def \makelabel ##1{\hss \llap {##1}}}%
  \fi 

\enditemize:
macro:->\global \advance \@listdepth \m@ne \endtrivlist 
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
$ latexdef -E itemize

\itemize:
macro:->\ifnum \@itemdepth >\thr@@ \@toodeep 
  \else \advance \@itemdepth \@ne
    \edef \@itemitem {labelitem\romannumeral
                          \the \@itemdepth}%
    \expandafter \list
               \csname \@itemitem \endcsname
    {\def \makelabel ##1{\hss \llap {##1}}}%
  \fi 

\enditemize:
macro:->\global \advance \@listdepth \m@ne
                                \endtrivlist 
\end{verbatim}
\end{narrowversion}
\end{quote}
(Yet again, this is a sanitised version of the macro definition
output, which appears as a single very wide line for each definition.)

If one has a malleable text editor, the same investigation may be
conducted by examining the file \File{latex.ltx} (which is usually to
be found, in a \acro{TDS} system, in directory \path{tex/latex/base}).

In fact, \File{latex.ltx} is the product of a \ProgName{docstrip}
process on a large number of \Qref*{\extension{dtx} files}{Q-dtx}, and
you can refer to those instead.  The \LaTeX{} distribution includes a file
\File{source2e.tex}, and most systems retain it, again in
\path{tex/latex/base}.  \File{Source2e.tex} may be processed to
provide a complete source listing of the \LaTeX{} kernel (in fact the
process isn't entirely straightforward, but the file produces messages
advising you what to do).  The result is a huge document, with a
line-number index of control sequences the entire kernel and a
separate index of changes recorded in each of the files since the
\LaTeX{} team took over.

The printed kernel is a nice thing to have, but it's unwieldy and sits
on my shelves, seldom used.  One problem is that the comments are
patchy: the different modules range from well and lucidly documented,
through modules documented only through an automatic process that
converted the documentation of the source of \LaTeXo{}, to modules
that hardly had any useful documentation even in the \LaTeXo{} original.

In fact, each kernel module \extension{dtx} file will process separately
through \LaTeX{}, so you don't have to work with the whole of
\File{source2e}.  You can easily determine which module defines the
macro you're interested in: use your ``malleable text editor'' to find
the definition in \File{latex.ltx}; then search backwards from that
point for a line that starts % ! line break
\texttt{\textpercent{}\textpercent{}\textpercent{}\ From File:}~--- that line
tells you which \extension{dtx} file contains the definition you are interested
in.  Doing this for \csx{protected@edef}, we find:
\begin{quote}
\begin{verbatim}
%%% From File: ltdefns.dtx
\end{verbatim}
\end{quote}
When we come to look at it, \File{ltdefns.dtx} proves to contain
quite a dissertation on the methods of handling \csx{protect}ion; it
also contains some automatically-converted \LaTeXo{} documentation.

And of course, the kernel isn't all of \LaTeX{}: your command may be
defined in one of \LaTeX{}'s class or package files.  For example, we
find a definition of \csx{thebibliography} in \Class{article}, but
there's no \File{article.dtx}.  Some such files are generated from
parts of the kernel, some from other files in the distribution.  You
find which by looking at the start of the file: in \File{article.cls},
we find:
\begin{quote}
\begin{verbatim}
%% This is file `article.cls',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% classes.dtx  (with options: `article')
\end{verbatim}
\end{quote}
so we need to format \File{classes.dtx} to see the definition in
context.

All these .dtx files are on \acro{CTAN} as part of the main \LaTeX{}
distribution.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}\LaTeX{} distribution]\CTANref{latex}
\item[texdef,\nothtml{\rmfamily aka} latexdef]\CTANref{texdef}
\end{ctanrefs}
\LastEdit{2013-09-27}

\Question[Q-oarglikesect]{Optional arguments like \csx{section}}

Optional arguments, in macros defined using \csx{newcommand}, don't
quite work like the optional argument to \csx{section}.  The default
value of \csx{section}'s optional argument is the value of the
mandatory argument, but \csx{newcommand} requires that you `know' the
value of the default beforehand.

The requisite trick is to use a macro in the optional argument:
\begin{quote}
\begin{verbatim}
\documentclass{article}
\newcommand\thing[2][\DefaultOpt]{%
  \def\DefaultOpt{#2}%
  optional arg: #1,  mandatory arg: #2%
}
\begin{document}
\thing{manda}% #1=#2

\thing[opti]{manda}% #1="opti"
\end{document}
\end{verbatim}
\end{quote}
\LaTeX{} itself has a trickier (but less readily understandable)
method, using a macro \csx{@dblarg}; inside \LaTeX{}, the example
above would have been programmed:
\begin{quote}
\begin{verbatim}
\newcommand\thing{\@dblarg\@thing}
\newcommand\@thing[2][\@error]{%
  optional arg: #1,  mandatory arg: #2%
}
\end{verbatim}
\end{quote}
In that code, \csx{@thing} is only ever called with an optional and a
mandatory argument; if the default from the \csx{newcommand} is
invoked, a bug in user code has bitten\dots{}

\Question[Q-twooptarg]{More than one optional argument}

If you've already read % ! line break
``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}''.
you can probably guess the ``simple'' solution to this problem:
command relaying.

\LaTeX{} allows commands with a single optional argument thus:
\begin{quote}
\begin{verbatim}
  \newcommand{\blah}[1][Default]{...}
\end{verbatim}
\end{quote}

You may legally call such a command either with its optional argument
present, as
\cmdinvoke{blah}[nonDefault] or without, as \csx{blah}; in the latter
case, the code of \csx{blah} will have an argument of |Default|.

To define a command with two optional arguments, we use the relaying
technique, as follows:
\begin{quote}
\begin{verbatim}
\newcommand{\blah}[1][Default1]{%
  \def\ArgI{{#1}}%
  \BlahRelay
}
\newcommand\BlahRelay[1][Default2]{%
  % the first optional argument is now in
  % \ArgI
  % the second is in #1
  ...%
}
\end{verbatim}
\end{quote}
Of course, \csx{BlahRelay} may have as many mandatory arguments as are
allowed, after allowance for the one taken up with its own
optional argument~--- that is, 8.

Variants of \csx{newcommand} (and friends), with names like
\csx{newcommandtwoopt}, are available in the \Package{twoopt} package.
However, if you can, it's probably better to learn to write the commands
yourself, just to see why they're not even a good idea from the
programming point of view.

A command with two optional arguments strains the limit of what's
sensible: obviously you can extend the technique to provide as many
optional arguments as your fevered imagination can summon.  However,
see the comments on the use of the \Package{keyval} package, in 
``\Qref*[question]{breaking the 9-argument limit}{Q-moren9}'',
which offers an alternative way forward.

If you must, however, consider the \Package{optparams} or
\Package{xargs} packages.  \Package{Optparams}
provides a \csx{optparams} command that you use as an intermediate in
defining commands with up to nine optional arguments.  The
documentation shows examples of commands with four optional arguments
(and this from an author who has his own key-value package!).

The \Package{xargs} package uses a key-value package
(\Package{xkeyval}) to \emph{define} the layout of the optional
arguments.  Thus
\begin{quote}
\begin{verbatim}
\usepackage{xargs}
...
\newcommandx{\foo}[3][1=1, 3=n]{...}
\end{verbatim}
\end{quote}
defines a command \csx{foo} that has an optional first argument
(default 1), a mandatory second argument, and an optional third
argument (default n).

An alternative approach is offered by Scott Pakin's
\ProgName{newcommand} program, which takes a command name and a
definition of a set of command arguments (in a fairly
readily-understood language), and emits \AllTeX{} macros which enable
the command to be defined.  The command requires that a
\ProgName{Python} interpreter (etc.\@) be installed on your computer.
\begin{ctanrefs}
\item[newcommand.py]\CTANref{newcommand}
\item[optparams.sty]Distributed as part of \CTANref{sauerj}[optparams]
\item[twoopt.sty]Distributed as part of \CTANref{oberdiek}[twoopt]
\item[xargs.sty]\CTANref{xargs}
\item[xkeyval.sty]\CTANref{xkeyval}
\end{ctanrefs}

\Question[Q-cmdstar]{Commands defined with * options}

\LaTeX{} commands commonly have ``versions'' defined with an asterisk
tagged onto their name: for example \csx{newcommand} and
\csx{newcommand*} (the former defines a \csx{long} version of the
command).

The simple-minded way for a user to write such a command involves use
of the \Package{ifthen} package:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand{\mycommand}[1]{\ifthenelse{\equal{#1}{*}}%
  {\mycommandStar}%
  {\mycommandNoStar{#1}}%
}
\newcommand{\mycommandStar}{starred version}
\newcommand{\mycommandNoStar}[1]{normal version}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand{\mycommand}[1]{%
  \ifthenelse{\equal{#1}{*}}%
    {\mycommandStar}%
    {\mycommandNoStar{#1}}%
}
\newcommand{\mycommandStar}%
                {starred version}
\newcommand{\mycommandNoStar}[1]%
                 {normal version}
\end{verbatim}
\end{quote}
\end{narrowversion}
This does the trick, for sufficiently simple commands, but it has
various tiresome failure modes, and it requires \csx{mycommandnostar}
to take an argument.

The \LaTeX{} kernel does a lot of this, and has its own command,
\csx{@ifstar} (which needs `internal command protection', cf.
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\makeatletter
\newcommand{\mycommand}{%
             \@ifstar
                  \mycommandStar%
                  \mycommandNoStar%
\makeatother
}
\newcommand{\mycommandStar}{starred version}
\newcommand{\mycommandNoStar}{normal version}
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\makeatletter
\newcommand{\mycommand}{\@ifstar
                     \mycommandStar%
                     \mycommandNoStar%
}
\makeatother
\newcommand{\mycommandStar}{starred version}
\newcommand{\mycommandNoStar}{normal version}
\end{verbatim}
\end{narrowversion}
\end{quote}
(Note that arguments to \csx{mycommandStar} and \csx{mycommandNoStar}
are independent~--- either can have their own arguments, unconstrained
by the technique we're using, unlike the trick described above.)
The \csx{@ifstar} trick is all very well, is fast and efficient, but
it requires that the definition be % ! line break
\Qref*{\csx{makeatletter} protected}{Q-atsigns}.

A pleasing alternative is the \Package{suffix} package.  This elegant
piece of code allows you to define variants of your commands:
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\newcommand\mycommand{normal version}
\WithSuffix\newcommand\mycommand*%
                     {starred version}
\end{verbatim}
\end{quote}
\end{narrowversion}
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\newcommand\mycommand{normal version}
\WithSuffix\newcommand\mycommand*{starred version}
\end{verbatim}
\end{quote}
\end{wideversion}
The package needs \Qref*{\elatex{}}{Q-etex}, but any new enough
distribution defines \LaTeX{} as \elatex{} by default.  Command
arguments may be specified in the normal way, in both command
definitions (after the ``\texttt{*}'' in the \csx{WithSuffix}
version).  You can also use the \TeX{} primitive commands, creating a
definition like:
\begin{quote}
\begin{verbatim}
\WithSuffix\gdef\mycommand*{starred version}
\end{verbatim}
\end{quote}

For those of an adventurous disposition, a further option is to use
the \Package{xparse} package from the \Package{l3packages}
distribution.  The package defines a bunch of commands (such as
\csx{NewDocumentCommand}) which are somewhat analagous to
\csx{newcommand} and the like, in \latexe{}.  The big difference is
the specification of command arguments; for each argument, you have a
set of choices in the command specification.  So, to create a
*-command (in \latexe{} style), one might write:
\begin{quote}
\begin{verbatim}
\NewDocumentCommand \foo { s m } {%
  % #1 is the star indicator
  % #2 is a mandatory argument
  ...
}
\end{verbatim}
\end{quote}
The ``star indicator'' (\texttt{s}) argument appears as \texttt{\#1}
and will take values \csx{BooleanTrue} (if there was a star) or
\csx{BooleanFalse} (otherwise); the other (\texttt{m}) argument  is a
normal \tex{}-style mandatory argument, and appears as \texttt{\#2}.

While \Package{xparse} provides pleasing command argument
specifications, it \emph{is} part of the % ! line break
\Qref*{\latex{}~3 experimental harness}{Q-LaTeX3}.
Simply loading the package to provide \csx{DeclareDocumentCommand}
``pulls in'' all of the \latex{}3 kernel (a large bunch of packages)
via the \Package{expl3} package.
\begin{ctanrefs}
\item[ifthen.sty]Part of the \LaTeX{} distribution
\item[suffix.sty]Distributed as part of \CTANref{bigfoot}[suffix]
\item[xparse.sty]Distributed as part of \CTANref{l3packages}[xparse]
\item[expl3.sty]Distributed as part of \CTANref{l3kernel}[expl3]
\end{ctanrefs}
\LastEdit{2014-04-04}

\nothtml{\hrule height 0pt \nobreak\vskip0pt plus2.5in\vskip 0pt\relax}
\Question[Q-ltxabbrv]{\LaTeX{} internal ``abbreviations'', etc.}

In the deeps of time, when \TeX{} first happened, computers had
extremely limited memory, and were (by today's standards) painfully
slow.  When \LaTeX{} came along, things weren't much better, and even
when \LaTeXe{} appeared, there was a strong imperative to save memory
space (and to a lesser extent) \acro{CPU} time.

From the very earliest days, Knuth used shortcut macros to speed
things up.  \LaTeX{}, over the years, has extended Knuth's list by a
substantial amount.  An interesting feature  of the ``abbreviations'' is
that on paper, they may look longer than the thing they stand for;
however, to \AllTeX{} they \emph{feel} smaller\dots{}

The table at the end of this answer lists the commonest of these
``abbreviations''.  It is not complete; as always, if the table
doesn't help, try the \LaTeX{} source.  The table lists each
abbreviation's \emph{name} and its \emph{value}, which provide most of
what a user needs to know.  The table also lists the abbreviation's
\emph{type}, which is a trickier concept: if you need to know, the
only real confusion is that the abbreviations labelled `defn' are
defined using an \csx{\emph{xxxx}def} command.

\begin{tabular}{lll}
Name \tbamp Type \tbamp Value \tbeol
\tbhline
\csx{m@ne} \tbamp count \tbamp \ensuremath{-1} \tbeol
\csx{p@}  \tbamp dimen \tbamp 1pt \tbeol
\csx{z@}  \tbamp dimen \tbamp 0pt \tbeol
\csx{z@skip} \tbamp skip \tbamp 0pt plus 0pt minus 0pt \tbeol
\tbhline
\csx{@ne} \tbamp defn \tbamp 1 \tbeol
\csx{tw@} \tbamp defn \tbamp 2\tbeol
\csx{thr@@} \tbamp defn \tbamp 3 \tbeol
\csx{sixt@@n} \tbamp defn \tbamp 16 \tbeol
\csx{@cclv} \tbamp defn \tbamp 255 \tbeol
\csx{@cclvi} \tbamp defn \tbamp 256 \tbeol
\csx{@m} \tbamp defn \tbamp 1000 \tbeol
\csx{@M} \tbamp defn \tbamp 10000 \tbeol
\csx{@MM} \tbamp defn \tbamp 20000 \tbeol
\tbhline
\csx{@vpt} \tbamp macro \tbamp 5 \tbeol
\csx{@vipt} \tbamp macro \tbamp 6 \tbeol
\csx{@viipt} \tbamp macro \tbamp 7 \tbeol
\csx{@viiipt} \tbamp macro \tbamp 8 \tbeol
\csx{@ixpt} \tbamp macro \tbamp 9 \tbeol
\csx{@xpt} \tbamp macro \tbamp 10 \tbeol
\csx{@xipt} \tbamp macro \tbamp 10.95 \tbeol
\csx{@xiipt} \tbamp macro \tbamp 12 \tbeol
\csx{@xivpt} \tbamp macro \tbamp 14.4 \tbeol
\csx{@xviipt} \tbamp macro \tbamp 17.28 \tbeol
\csx{@xxpt} \tbamp macro \tbamp 20.74 \tbeol
\csx{@xxvpt} \tbamp macro \tbamp 24.88 \tbeol
\tbhline
\csx{@plus} \tbamp macro \tbamp ``\texttt{plus}'' \tbeol
\csx{@minus} \tbamp macro \tbamp ``\texttt{minus}'' \tbeol
%\csx{hb@xt@} \tbamp macro \tbamp ``\csx{hbox} \texttt{to}''
\end{tabular}

\Question[Q-ltxhash]{Defining \LaTeX{} commands within other commands}

\LaTeX{} command definition is significantly different from the \TeX{}
primitive form discussed in an % ! line break
\Qref*[\htmlonly]{earlier question}{Q-hash} about definitions within
macros.

In most ways, the \LaTeX{} situation is simpler (at least in part
because it imposes more restrictions on the user); however, defining a
command within a command still requires some care.

The earlier question said you have to double the |#| signs in command
definitions: in fact, the same rule holds, except that \LaTeX{}
already takes care of some of the issues, by generating argument lists
for you.

The basic problem is that:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}[1]{joy, oh #1!%
  \newcommand{\ghi}[1]{gloom, oh #1!}%
}
\end{verbatim}
\end{quote}
followed by a call:
\begin{quote}
\begin{verbatim}
\cmdinvoke{abc}{joy}
\end{verbatim}
\end{quote}
typesets ``joy, oh joy!'', but defines a command \csx{ghi} that takes
one parameter, which it ignores; \cmdinvoke{ghi}{gloom} will expand to
``gloom, oh joy!'', which is presumably not what was expected.

And (as you will probably guess, if you've read the earlier question)
the definition:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}[1]{joy, oh #1!%
  \newcommand{\ghi}[1]{gloom, oh ##1!}%
}
\end{verbatim}
\end{quote}
does what is required, and \cmdinvoke{ghi}{gloom} will expand to
``gloom, oh gloom!'', whatever the argument to \csx{abc}.

The doubling is needed whether or not the enclosing command has an
argument, so:
\begin{quote}
\begin{verbatim}
\newcommand{\abc}{joy, oh joy!%
  \newcommand{\ghi}[1]{gloom, oh ##1!}%
}
\end{verbatim}
\end{quote}
is needed to produce a replica of the \csx{ghi} we defined earlier.

\Question[Q-printvar]{How to print contents of variables?}
\keywords{typeout, print variables, showthe}

It is often useful to print out the values of variables in the log
file or on the terminal.  Three possible ways to print out the
contents of \csx{textheight} variable are:
\begin{enumerate}
\item \csx{showthe}\csx{textheight}
\item \cmdinvoke{message}{The text height is \csx{the}\csx{textheight}}
\item \cmdinvoke{typeout}{The text height is \csx{the}\csx{textheight}}
\end{enumerate}
These techniques use the \TeX{} primitives \csx{the} (which provides
the value of a variable), \csx{showthe} (print a variable to the
terminal and the log, on a line of its own), and \csx{message}, which
interpolates something into the log.  The command \csx{typeout} is
\LaTeX{}'s general message output mechanism.

In each case, the variable's value is printed as a number of points.

To typeset the value of \csx{textheight}, just
\csx{the}\csx{textheight} is enough, but a more flexible alternative is
to use the \Package{printlen} package.  \Package{Printlen} allows you
to choose the units in which you print a variable; this is useful,
given that the most ordinary people don't think in points
(particularly Knuth's points, of which there are 72.27 to the inch).

So, using \Package{printlen}, we could say:
\begin{quote}
\begin{verbatim}
\newlength{\foo}
\setlength{\foo}{12pt}
\verb|\foo| is \printlength{\foo}
\end{verbatim}
\end{quote}
and get:
\begin{quote}
\csx{foo} is 12pt
\end{quote}
while, if we say:
\begin{quote}
\begin{verbatim}
\newlength{\foo}
\setlength{\foo}{12pt}
\uselengthunit{mm}
\verb|foo| is \printlength{\foo}
\end{verbatim}
\end{quote}
we get:
\begin{quote}
\csx{foo} is 4.21747mm
\end{quote}
\begin{ctanrefs}
\item[printlen.sty]\CTANref{printlen}
\end{ctanrefs}
\LastEdit{2012-03-16}

\Question[Q-labelcount]{Using labels as counter values}

Labels are tempting sources of `numbers'~--- their most common use,
after all, is simply to typeset a number.  However, their seeming
simplicity is deceptive; the packages \Package{babel} and
\Package{hyperref}, at least, fiddle with the definition of
\csx{ref} and \csx{pageref} in ways that make
\begin{quote}
\begin{verbatim}
\setcounter{foo}{\ref{bar}}
\end{verbatim}
\end{quote}
(etc.\@) not work; thus the technique may not be relied upon.

The solution is to use the \Package{refcount} package (incidentally,
by the author of \Package{hyperref}).  The package provides four
commands, all similar to:
\begin{quote}
\begin{verbatim}
\usepackage{refcount}
...
\label{bar}
...
\setcounterref{foo}{bar}
\end{verbatim}
\end{quote}
(the other three are \csx{addtocounterref}, \csx{setcounterpageref}
and \csx{addtocounterpageref}).

The package also provides a command
\cmdinvoke*{getrefnumber}{label-name} that may be used where a
`number' value is needed.  For example:
\begin{quote}
\begin{verbatim}
... \footnote{foo bar ...\label{foofoot}}
...
\footnotemark[\getrefnumber{foofoot}]
\end{verbatim}
\end{quote}
which gives you a second footnote mark reference the the footnote.
(There is also a command \csx{getpagerefnumber}, of course).

The commands could be used by one determined not to use
\Package{changepage} to determine whether % ! line break
\Qref*{the current page is odd}{Q-oddpage}, but it's probably no more
trouble to use the fully-developed tool in this case.
\begin{ctanrefs}
\item[refount.sty]Distributed as part of \CTANref{oberdiek}
\end{ctanrefs}
\LastEdit*{2011-09-08}

\subsection{\LaTeX{} macro programming}

\Question[Q-fixnam]{How to change \LaTeX{}'s ``fixed names''}

\LaTeX{} document classes define several typographic operations that
need `canned text' (text not supplied by the user).  In the earliest
days of \LaTeXo{} these bits of text were built in to the body of
\LaTeX{}'s macros and were rather difficult to change, but ``fixed
name'' macros were introduced for the benefit of those wishing to use
\LaTeX{} in languages other than English.
For example, the special section produced by the \csx{tableofcontents}
command is always called \csx{contentsname} (or rather, what
\csx{contentsname} is defined to mean).
Changing the canned text is now one of the easiest customisations a
user can do to \LaTeX{}.

The canned text macros are all of the form
\csx{\meta{thing}name}, and changing them is simplicity
itself.  Put:
\begin{quote}
\cmdinvoke{renewcommand}{\csx{\meta{thing}name}}{Res minor}
\end{quote}
in the preamble of your document, and the job is done.
(However, beware of the \Package{babel} package, which requires you to
use a different mechanism: be sure to check
% beware line wrap
\Qref[question]{changing \Package{babel} names}{Q-latexwords} if
you're using it.)

The names that are defined in the standard \LaTeX{} classes (and the
\Package{makeidx} package) are listed
below.  Some of the names are only defined in a subset of the classes
(and the \Class{letter} class has a set of names all of its own);
the list shows the specialisation of each name, where appropriate.

\nothtml{\noindent}\begin{tabular}{@{}ll}
\csx{abstractname} \tbamp Abstract\tbeol
\csx{alsoname} \tbamp see also (\Package{makeidx} package)\tbeol
\csx{appendixname} \tbamp Appendix\tbeol
\csx{bibname} \tbamp Bibliography (\Class{report},\Class{book})\tbeol
\csx{ccname} \tbamp cc (\Class{letter})\tbeol
\csx{chaptername} \tbamp Chapter (\Class{report},\Class{book})\tbeol
\csx{contentsname} \tbamp Contents\tbeol
\csx{enclname} \tbamp encl (\Class{letter})\tbeol
\csx{figurename} \tbamp Figure (for captions)\tbeol
\csx{headtoname} \tbamp To (\Class{letter})\tbeol
\csx{indexname} \tbamp Index\tbeol
\csx{listfigurename} \tbamp List of Figures\tbeol
\csx{listtablename} \tbamp List of Tables\tbeol
\csx{pagename} \tbamp Page (\Class{letter})\tbeol
\csx{partname} \tbamp Part\tbeol
\csx{refname} \tbamp References (\Class{article})\tbeol
\csx{seename} \tbamp see (\Package{makeidx} package)\tbeol
\csx{tablename} \tbamp Table (for caption)
\end{tabular}

\Question[Q-latexwords]{Changing the words \Package{babel} uses}

\LaTeX{} uses symbolic names for many of the automatically-generated
text it produces (special-purpose section headings, captions, etc.).
As noted in \Qref[question]{``\LaTeX{} fixed names''}{Q-fixnam} (which
includes a list of the names themselves),
this enables the user to change the
names used by the standard classes, which is particularly useful if
the document is being prepared in some language other than \LaTeX{}'s
default English.  So, for example, a Danish author may wish that her
table of contents was called ``Indholdsfortegnelse'', and so 
would expect to place a command
\begin{verbatim}
\renewcommand{\contentsname}%
    {Indholdsfortegnelse}
\end{verbatim}
in the preamble of her document.

However, it's natural for a user of a non-English language to use
\Package{babel}, because it offers many conveniences and typesetting
niceties for those preparing documents in those languages.  In
particular, when \Package{babel} is selecting a new language, it
ensures that \LaTeX{}'s symbolic names are translated appropriately
for the language in question.  Unfortunately, \Package{babel}'s choice
of names isn't always to everyone's choice, and there is still a need
for a mechanism to replace the `standard' names.

Whenever a new language is selected, \Package{babel} resets all the
names to the settings for that language.  In particular,
\Package{babel} selects the document's main language when
\cmdinvoke{begin}{document} is executed, which immediately destroys
any changes to these symbolic names made in the prologue of a document
that uses \Package{babel}. 

Therefore, babel defines a command to enable users to change the
definitions of the symbolic names, on a per-language basis:
\csx{addto}\csx{captions}\texttt{\meta{language}} is the thing
(\texttt{\meta{language}} being the language option you gave to
\Package{babel} in the first place).  For example:
\begin{verbatim}
\addto\captionsdanish{%
  \renewcommand{\contentsname}%
    {Indholdsfortegnelse}%
}
\end{verbatim}

\Question[Q-running-nos]{Running equation, figure and table numbering}

Many \LaTeX{} classes (including the standard \Class{book} class)
number things per chapter; so figures in chapter 1 are numbered 1.1,
1.2, and so on.  Sometimes this is not appropriate for the user's
needs.

Short of rewriting the whole class, one may use the \Package{chngcntr}
package, which provides commands \csx{counterwithin} (which
establishes this nested numbering relationship) and
\csx{counterwithout} (which undoes it).

So if you have figures numbered by chapter as 1.1, 1.2, 2.1, \dots{},
the command 
\begin{quote}
\begin{verbatim}
\counterwithout{figure}{chapter}
\end{verbatim}
\end{quote}
will convert them to figures 1, 2, 3, \dots{}.  (Note that the command
has also removed the chapter number from the counter's definition.)

More elaborate use could change things numbered per section to things
numbered per chapter:
\begin{quote}
\begin{verbatim}
\counterwithout{equation}{section}
\counterwithin{equation}{chapter}
\end{verbatim}
\end{quote}
(assuming there was a class that did such a thing in the first place...)

The \Package{chngcntr} approach doesn't involve much programming, and
the enthusiastic \LaTeX{} programmer might choose to try the technique
that we had to use before the advent of \Package{chngcntr}.  Each of
the packages \Package{removefr} and \Package{remreset} defines a
\csx{@removefromreset} command, and having included the package one
writes something like:
\begin{quote}
\begin{verbatim}
\makeatletter
\@removefromreset{figure}{chapter}
\makeatother
\end{verbatim}
\end{quote}
and the automatic renumbering stops.  You may then need to redefine the
way in which the figure number (in this case) is printed:
\begin{quote}
\begin{verbatim}
\makeatletter
\renewcommand{\thefigure}{\@arabic\c@figure}
\makeatother
\end{verbatim}
\end{quote}
(remember to do the whole job, for every counter you want to
manipulate, within \csx{makeatletter} \dots{}\@ \csx{makeatother}).

This technique, too, may be used to change where in a multilevel
structure a counter is reset.  Suppose your class numbers figures as
\meta{chapter}.\meta{section}.\meta{figure}, and you want figures
numbered per chapter, try:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
\makeatletter
\@removefromreset{figure}{section}
\@addtoreset{figure}{chapter}
\renewcommand{\thefigure}{\thechapter.\@arabic\c@figure}
\makeatother
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
\makeatletter
\@removefromreset{figure}{section}
\@addtoreset{figure}{chapter}
\renewcommand{\thefigure}%
             {\thechapter.\@arabic\c@figure}
\makeatother
\end{verbatim}
\end{narrowversion}
\end{quote}
(the command \csx{@addtoreset} is a part of \LaTeX{} itself).
\begin{ctanrefs}
\item[chngcntr.sty]\CTANref{chngcntr}
\item[memoir.cls]\CTANref{memoir}
\item[removefr.tex]\CTANref{removefr} (note, this is constructed as a
  ``fragment'' for use within other packages: load by
  \cmdinvoke{input}{removefr})
\item[remreset.sty]Distributed as part of \CTANref{carlisle}[remreset]
\end{ctanrefs}

\Question[Q-labelctr]{Making labels from a counter}

Suppose we have a \LaTeX{} counter, which we've defined with
\cmdinvoke{newcounter}{foo}.  We can increment the value of the counter
by \cmdinvoke{addtocounter}{foo}{1}, but that's pretty clunky for an
operation that happens so often \dots{}~so there's a command
\cmdinvoke{stepcounter}{foo} that does this special case of
increasing-by-one.

There's an internal \LaTeX{} variable, the ``current label'', that
remembers the last `labellable' thing that \LaTeX{} has processed.
You could (if you were to insist) set that value by the relevant
\TeX{} command (having taken the necessary precautions to ensure that
the internal command worked)~--- but it's not necessary.  If, instead
of either of the stepping methods above, you say
\cmdinvoke{refstepcounter}{foo}, the internal variable is set to the
new value, and (until something else comes along), \csx{label} will
refer to the counter.

\Question[Q-oddpage]{Finding if you're on an odd or an even page}

\Qref[Question]{Another question}{Q-marginparside} discusses the issue
of getting \csx{marginpar} commands to put their output in the correct
margin of two-sided documents.  This is an example of the general
problem of knowing where a particular bit of text lies: the output
routine is asynchronous, and \AllTeX{} will usually process quite a
bit of the ``next'' page before deciding to output any page.  As a
result, the |page| counter (known internally in \LaTeX{} as
\csx{c@page}) is normally only reliable when you're actually \emph{in}
the output routine.

The solution is to use some version of the \csx{label} mechanism to
determine which side of the page you're on; the value of the page
counter that appears in a \csx{pageref} command has been inserted in
the course of the output routine, and is therefore safe.

However, \csx{pageref} itself isn't reliable: one might hope that
\begin{quote}
\begin{verbatim}
\ifthenelse{\isodd{\pageref{foo}}}{odd}{even}
\end{verbatim}
\end{quote}
would do the necessary, but both the \Package{babel} and
\Package{hyperref} packages have been known to interfere with the
output of \csx{pageref}; be careful!

The \Package{changepage} package needs to provide this functionality
for its own use, and therefore provides a command \csx{checkoddpage};
this sets a private-use `label', and the page reference part of that
label is then examined (in a \Package{hyperref}-safe way) to set a
conditional \csx{ifoddpage} true if the command was issued on an odd
page.  (The \Class{memoir} class has the same command.)  \latex{}
users who are unfamiliar with \tex{}'s \csx{if...} commands may use
the \Package{ifthen} package:
\begin{wideversion}
\begin{quote}
\begin{verbatim}
\usepackage{ifthen,changepage}
...
\checkoddpage
\ifthenelse{\boolean{oddpage}}{<odd page stuff>}{<even page stuff>}
\end{verbatim}
\end{quote}
\end{wideversion}
\begin{narrowversion}
\begin{quote}
\begin{verbatim}
\usepackage{ifthen,changepage}
...
\checkoddpage
\ifthenelse{\boolean{oddpage}}%
    {<odd page stuff>}%
    {<even page stuff>}
\end{verbatim}
\end{quote}
\end{narrowversion}

Of course, the `label' contributes to \LaTeX{}'s ``Rerun to get
cross-references right'' error messages\dots{}

The Koma-Script classes have an \environment{addmargin*} environment
that also provides the sorts of facilities that the \Package{changepage}
offers.  Koma-Script's supporting command:
\begin{quote}
\cmdinvoke{ifthispageodd}{<true>}{<false>}
\end{quote}
executes different things depending on the page number.

The package \Package{ifoddpage} is designed to provide the same
facility; crucially, it can behave ``sensibly'' even if you are
typesetting for one-side printing only; like the \Package{changepage}
it uses a `check' command \csx{checkoddpage}.  The conditional `side'
flags are set using (Plain) \TeX{} conditionals; they are defined
locally, so that you can minimise their use of \tex{} workspace~---
see the package documentation for the somewhat tricky sequence
involved.  In addition the package provides a command
\csx{ifoddpageoroneside}, which is true on odd pages of a two-side
document, or on all pages of a one-side document.  Usage is:
\begin{quote}
\begin{verbatim}
\checkoddpage
\ifoddpage
  odd-side text
\else
  even-side text
\fi
\end{verbatim}
\end{quote}
The author's recommended usage (trickily) includes the whole operation
in a box; this has the advantage that your test will always work, but
the usual disadvantage that boxes may not split.  In common uses, the
whole work will be done inside a box (as, for example, in the case of
a float), so the elaborate work proposed by the author is not
necessary.
\begin{ctanrefs}
\item[changepage.sty]\CTANref{changepage}
\item[ifoddpage.sty]\CTANref{ifoddpage}
\item[ifthen.sty]Part of the \latex{} distribution: \CTANref{latex}
\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
\item[memoir.cls]\CTANref{memoir}
\end{ctanrefs}

\Question[Q-labelformat]{How to change the format of labels}

By default, when a label is created, it takes on the appearance of the
counter labelled, so the label appears as
\csx{the}\texttt{\meta{counter}}~--- what would be used if you
asked to typeset the counter in your text.  This isn't always what you
need: for example, if you have nested enumerated lists with the outer
numbered and the inner labelled with letters, one might expect to want
to refer to items in the inner list as ``2(c)''.   (Remember, you can
\nothtml{change the structure of list items~--- }%
\Qref{change the structure of list items}{Q-enumerate}.)
The change is of course
possible by explicit labelling of the parent and using that label to
construct the typeset result~--- something like
\begin{quote}
\begin{verbatim}
\ref{parent-item}(\ref{child-item})
\end{verbatim}
\end{quote}
which would be both tedious and error-prone.  What's more, it would be
undesirable, since you would be constructing a visual representation
which is inflexible (you couldn't change all the references to elements
of a list at one fell swoop).

\LaTeX{} in fact has a label-formatting command built into every label
definition; by default it's null, but it's available for the user to
program.  For any label \meta{counter} there's a \LaTeX{} internal
command \csx{p@}\meta{\texttt{counter}}; for example, a label definition
on an inner list item is supposedly done using the command
\cmdinvoke{p@enumii}{\csx{theenumii}}.  Unfortunately, the internal
workings of this aren't quite right, and you need to patch the
\csx{refstepcounter} command:
\begin{quote}
\begin{narrowversion}
\begin{verbatim}
\renewcommand*\refstepcounter[1]{%
  \stepcounter{#1}%
  \protected@edef\@currentlabel{%
    \csname p@#1\expandafter\endcsname
      \csname the#1\endcsname
  }%
}
\end{verbatim}
\end{narrowversion}
\begin{wideversion}
\begin{verbatim}
\renewcommand*\refstepcounter[1]{\stepcounter{#1}%
  \protected@edef\@currentlabel{%
    \csname p@#1\expandafter\endcsname
      \csname the#1\endcsname
  }%
}
\end{verbatim}
\end{wideversion}
\end{quote}
With the patch in place you can now, for example, change the labels on
all inner lists by adding the following code in your preamble:
\begin{quote}
\begin{verbatim}
\makeatletter
\renewcommand{\p@enumii}[1]{\theenumi(#1)}
\makeatother
\end{verbatim}
\end{quote}
This would make the labels for second-level enumerated lists appear as
``1(a)'' (and so on).  The analogous change works for any counter that
gets used in a \csx{label} command.

In fact, the \Package{fncylab} package does all the above (including
the patch to \LaTeX{} itself).  With the package, the code above is
(actually quite efficiently) rendered by the command:
\begin{quote}
\begin{verbatim}
\labelformat{enumii}{\theenumi(#1)}
\end{verbatim}
\end{quote}
In fact, the above example, which we can do in several different ways,
has been rendered obsolete by the appearance of the \Package{enumitem}
package, which is discussed in the answer about % ! line break
\Qref*{decorating enumeration lists}{Q-enumerate}.
\begin{ctanrefs}
\item[enumitem.sty]\CTANref{enumitem}
\item[fncylab.sty]\CTANref{fncylab}
\end{ctanrefs}

\Question[Q-seccntfmt]{Adjusting the presentation of section numbers}

The general issues of adjusting the appearance of section headings are
pretty complex, and are covered in % beware line breaks (2 lines)
\latexhtml{question}{the question on}
\Qref[\htmlonly]{the style of section headings}{Q-secthead}.

However, people regularly want merely to change the way the section
number appears in the heading, and some such people don't mind writing
out a few macros.  This answer is for \emph{them}.

The section number is typeset using the
\begin{dviversion}
  \LaTeX{} internal
\end{dviversion}
\begin{hyperversion}
  \Qref{\LaTeX{} internal}{Q-atsigns}
\end{hyperversion}
\csx{@seccntformat} command, which is given the ``name'' (section,
subsection, \dots{}) of the heading, as argument.  Ordinarily,
\csx{@seccntformat} 
merely outputs the section number, and then a \csx{quad} of space:
\begin{quote}
\begin{verbatim}
\renewcommand*{\@seccntformat}[1]{%
  \csname the#1\endcsname\quad
}
\end{verbatim}
\end{quote}
Suppose you want to put a stop after every section (subsection,
subsubsection, \dots{}) number, a trivial change may be implemented by
simple modification of the command:
\begin{quote}
\begin{verbatim}
\renewcommand*{\@seccntformat}[1]{%
  \csname the#1\endcsname.\quad
}
\end{verbatim}
\end{quote}
However, many people want to modify section numbers, but not
subsection numbers, or any of the others.  To do this, one must make
\csx{@seccntformat} switch according to its argument.  The following
technique for doing the job is slightly wasteful, but is efficient
enough for a relatively rare operation:
\begin{quote}
\begin{verbatim}
\renewcommand*{\@seccntformat}[1]{%
  \csname the#1\endcsname
  \csname adddot@#1\endcsname\quad
}
\end{verbatim}
\end{quote}
which uses a second-level command to provide the dot, if it has been
defined; otherwise it merely appends \csx{relax} (which does nothing
in this context).  The definition of the second-level command (the
version for the \texttt{section}, here) specifies what to put after a
section number, but it could be used to put anything after it:
\begin{quote}
\begin{verbatim}
\newcommand*{\adddot@section}{.}
\end{verbatim}
\end{quote}
Note that all the command definitions above are dealing in
\Qref*{\LaTeX{} internal commands}{Q-atsigns}, so the above
code should be in a package file, for preference.

The \Class{Koma-script} classes have different commands for specifying
changes to section number presentation: \csx{partformat},
\csx{chapterformat} and \csx{othersectionlevelsformat}, but otherwise
their facilities are similar to those of ``raw'' \LaTeX{}.
\begin{ctanrefs}
\item[\nothtml{\rmfamily}KOMA script bundle]\CTANref{koma-script}
\end{ctanrefs}

\Question[Q-spaftend]{There's a space added after my environment}

You've written your own environment \environment{env}, and it works
except that a space appears at the start of the first line of typeset
text after \cmdinvoke{end}{env}.  This doesn't happen with similar
\LaTeX{}-supplied environments.

You could impose the restriction that your users always put a
``\texttt{\textpercent{}}'' sign after the environment~\dots{}\nothtml{\@} but
\LaTeX{} environments don't require that, either.

The \LaTeX{} environments' ``secret'' is an internal flag which causes
the unwanted spaces to be ignored.  Fortunately, you don't have to use
the internal form: since 1996, \LaTeX{} has had a user command
\csx{ignorespacesafterend}, which sets the internal flag.

\Question[Q-labundef]{Finding if a label is undefined}

People seem to want to know (at run time) if a label is undefined (I
don't actually understand \emph{why}, particularly: it's a transient
state, and \LaTeX{} deals with it quite well).

A resolved label is simply a command:
\csx{r@}\texttt{\meta{label-name}}; determining if the label is set is
then simply a matter of detecting if the command exists.  The usual
\LaTeX{} internal way of doing this is to use the command
\csx{@ifundefined}:
\begin{quote}
  \cmdinvoke*{@ifundefined}{\textup{r@}label-name}{undef-cmds}{def-cmds}
\end{quote}
In which, \meta{label-name} is exactly what you would use in
a \csx{label} command, and the remaining two arguments are command
sequences to be used if the label is undefined
(\meta{undef-cmds}) or if it is defined
(\meta{def-cmds}).

Note that any command that incorporates \csx{@ifundefined} is naturally
fragile, so remember to create it with \csx{DeclareRobustCommand} or to
use it with \csx{protect} in a moving argument.

If you're into this game, you may well not care about \LaTeX{}'s
warning about undefined labels at the end of the document; however,
if you are, include the command \csx{G@refundefinedtrue} in
\meta{\texttt{undef-cmds}}.

And of course, remember you're dealing in internal commands, and pay
attention to the \Qref*{at-signs}{Q-atsigns}.

All the above can be avoided by using the \Package{labelcas} package:
it provides commands that enable you to switch according to the state
of a single label, or the states of a list of labels.  The package's
definition is a bit complicated, but the package itself is pretty
powerful.
\begin{ctanrefs}
\item[labelcas.sty]\CTANref{labelcas}
\end{ctanrefs}

\Question[Q-addtoreset]{Master and slave counters}

It's common to have things numbered ``per chapter'' (for example, in
the standard \Class{book} and \Class{report} classes, figures, tables
and footnotes are all numbered thus).  The process of resetting is
done automatically, when the ``master'' counter is stepped (when the
\csx{chapter} command that starts chapter \meta{n} happens, the
\texttt{chapter} counter is stepped, and all the dependent counters are set
to zero).

How would you do that for yourself?  You might want to number
algorithms per section, or corollaries per theorem, for example.  If
you're defining these things by hand, you declare the relationship
when you define the counter in the first place:
\begin{quote}
\cmdinvoke*{newcounter}{new-name}[master]
\end{quote}
says that every time counter \meta{master} is stepped, counter
\meta{new-name} will be reset.

But what if you have an uncooperative package, that defines the
objects for you, but doesn't provide a programmer interface to make
the counters behave as you want?

The \csx{newcounter} command uses a \LaTeX{} internal command, and you
can also use it:
\begin{quote}
\cmdinvoke*{@addtoreset}{new-name}{master}
\end{quote}
(but remember that it needs to be between \csx{makeatletter} and
\csx{makeatother}, or in a package of your own).

The \Package{chngcntr} package encapsulates the \csx{@addtoreset}
command into a command \csx{counterwithin}.  So:
\begin{quote}
\begin{verbatim}
\counterwithin*{corrollary}{theorem}
\end{verbatim}
\end{quote}
will make the corollary counter slave to theorem counters.  The
command without its asterisk:
\begin{quote}
\begin{verbatim}
\counterwithin{corrollary}{theorem}
\end{verbatim}
\end{quote}
will do the same, and also redefine \csx{thecorollary} as % line brk!
\meta{theorem number}.\meta{corollary number}, which is a good scheme
if you ever want to refer to the corollaries~--- there are potentially
many ``corollary~1'' in any document, so it's as well to tie its number
to the counter of the theorem it belongs to.  This is true of pretty
much any such counter-within-another; if you're not using the
\Package{chngcntr}, refer to the answer to % line break!
\Qref*{redefining counters' \csx{the-}commands}{Q-the-commands} for
the necessary techniques.

Note that the technique doesn't work if the master counter is |page|,
the number of the current page.  The |page| counter is stepped deep
inside the output routine, which usually gets called some time after
the text for the new page has started to appear: so special
techniques are required to deal with that.  One special case is dealt
with elsewhere: \Qref*{footnotes numbered per page}{Q-footnpp}.  One
of the techniques described there, using package \Package{perpage},
may be applied to any counter.  The command:
\begin{quote}
\cmdinvoke*{MakePerPage}{counter}
\end{quote}
will cause \meta{counter} to be reset for each page.  The package uses
a label-like mechanism, and may require more than one run of \LaTeX{}
to stabilise counter values~--- \LaTeX{} will generate the usual
warnings about labels changing.
\begin{ctanrefs}
\item[chngcntr.sty]\CTANref{chngcntr}
\item[perpage.sty]Distributed as part \CTANref{bigfoot}[perpage]
\end{ctanrefs}

\Question[Q-fontsize]{Fonts at arbitrary sizes}

Almost all fonts, nowadays, are provided with \LaTeX{} control
(\extension{fd}) files, so the temptation to risk the
\Qref*{problems of \csx{newfont}}{Q-newfont*} is usually easy to
resist.

However, one temptation remains, arising from the way that \LaTeX{}
restricts the sizes of fonts.  In fact, the restriction only
significantly applies to the default (Computer Modern) and the
Cork-encoded (\acro{T}1) EC fonts, but it is widely considered to be
anomalous, nowadays.  In recognition of this problem, there is a
package \Package{fix-cm} which will allow you to use the fonts, within
\LaTeX{}, at any size you choose.  If you're not using scaleable
versions of the fonts, most modern distributions will just generate an
appropriate bitmap for you.

So, suppose you want to produce a heading in Computer Modern Roman at
30 points, you might be tempted to write:
\begin{quote}
\begin{verbatim}
\newfont{\bigfont}{cmr10 at 30pt}
\begin{center}
  \bigfont Huge text
\end{center}
\end{verbatim}
\end{quote}
which will indeed work, but will actually produce a worse result than
\begin{quote}
\begin{verbatim}
\usepackage{fix-cm}
...
\begin{center}
  \fontsize{30}{36}\selectfont
  Huge text
\end{center}
\end{verbatim}
\end{quote}
Note that the \Package{fix-cm} package was not distributed until the
December 2003 edition of \LaTeX{}; if you have an older distribution,
the packages \Package{type1cm} (for \acro{CM} fonts) and
\Package{type1ec} (for \acro{EC} fonts) are available.

\Package{Fix-cm} doesn't has one or two omissions~--- fonts the \latex{}
team did not consider useful, or something; the CM dunhill fonts (as
CM, but with stretched ascenders) and the CM fibonacci font (which is only
available in 8-point design size) are certainly missing.  If
\Package{fix-cm} doesn't do the job, try the \Package{type1xx}
packages, or the \Package{anyfontsize} package.

A further alternative might be to switch to the
\Qref*{\FontName{Latin} \FontName{Modern} fonts}{Q-uselmfonts} (which
provide a close simulacrum of the \FontName{Computer}
\FontName{Modern} set); these fonts were scaleable from their first
distribution, and don't therefore need any such trick as the above.
\begin{ctanrefs}
\item[anyfontsize.sty]\CTANref{anyfontsize}
\item[fix-cm.sty]Distributed as part of \CTANref{latex}[fix-cm] (an unpacked
  version is available at \CTANref{fix-cm})
\item[\nothtml{\rmfamily}\FontName{Latin} \FontName{Modern} fonts]\CTANref{lm}
\item[type1cm.sty]\CTANref{type1cm}
\item[type1ec.sty]\CTANref{type1ec} (the package is actually part of
  the \CTANref{cm-super} distribution, but it works happily in
  the absence of the scaled fonts)
\end{ctanrefs}
\LastEdit{2013-06-04}

\Question[Q-latexqual]{The quality of your \LaTeX{}}

The \Package{l2tabu} tutorial (mentioned in % ! line break
\Qref[question]{online introductions}{Q-man-latex}) is undoubtedly a
good read.

However, it's always difficult to remember the things you should
\emph{not} do, when there are so many things to remember that you
really must do: some automation is useful\dots{}.

The nicely-named \Package{nag} allows you to apply a configurable set
of checks to your document, as you run it through \LaTeX{}; you get
messages like:
\begin{quote}
\begin{wideversion}
\begin{verbatim}
Package nag Warning: Command \bf is an old LaTeX 2.09 command. 
(nag)                Use \bfseries or \textbf instead on input line 30.
\end{verbatim}
\end{wideversion}
\begin{narrowversion}
\begin{verbatim}
Package nag Warning: Command \bf is an old
                          LaTeX 2.09 command. 
(nag)                Use \bfseries or \textbf
                    instead on input line 30.
\end{verbatim}
\end{narrowversion}
\end{quote}
\begin{wideversion}
  (the package provides a demo file which contains most of the sorts
  of errors you might make~--- the example is one of them).
\end{wideversion}
\begin{narrowversion}
  (the error lines above represent two lines which have been wrapped;
  the package provides a demo file which contains most of the sorts of
  errors you might make~--- the example is one of them).
\end{narrowversion}
While \Package{l2tabu} and \Package{nag} alert you to \emph{possible}
programming errors, you should not forget that they are merely
commenting on \emph{style}; don't assume that a \Package{nag} error is
going to damn your code~--- rather, note the issue and try to train
your fingers not to do the same ``next time''.

The \ProgName{lacheck} program analyses your source and comments on
it; its view of what is ``bad'' is \emph{very} subjective (the
documentation says), but it can be useful.

There's also a web site
\href{http://www.kohm.name/markus/texidate.html}{TeXidate}
which will do a static analysis of your document (unfortunately, you
have to paste your document source into a text window).  The site
doesn't seem as comprehensive as \Package{nag}, but it allows you to
download its script, which you can then juggle with to make it more
draconian.
\begin{ctanrefs}
\item[l2tabu]Browse \CTANref{l2tabu} for a copy of the document in a
  language that is convenient for you
\item[lacheck]\CTANref{lacheck}
\item[nag.sty]\CTANref{nag}
\end{ctanrefs}
\LastEdit{2012-10-09}

\Question[Q-ltx-csv]{Process a \acro{CSV} file in \latex{}}

Comma-separated-variable (\acro{CSV}) files are a common means of
interchanging simple data between applications; for example, most
spreadsheet applications can provide files containing tables of
numbers with commas between them.  One can envisage these tables as
``\latex{} tables'', and the packages to process them all provide
table generation, one way or another.

For rather a long time, the canonical tools for dealing with such
files have been those provided in the \Package{datatool} bundle;
packages in the bundle allow the user to write procedures to process
numbers, currency amounts, names, etc., and to display them in tables
(including pie charts).

The \Package{csvsimple} does similar tasks.  Its processing is
controlled by keys established via the \Package{pgfkeys} package,
which define how each row of the \acro{CSV} file is to be processed.

For usage ``nearer to the bone'', one might consider the commands
\csx{docsvlist} and \csx{forcsvlist} (from the \Package{etoolbox}
package).  The first uses the time-honoured \latex{} technique of
changing the definition of a \csx{do} command; it runs through the
list, and processes every item of the list as the argument of the
\csx{do} command; so:
\begin{quote}
\begin{verbatim}
\begin{itemize}
\renewcommand*{\do}[1]{\item #1}
\docsvlist{item1, item2, {item3a, item3b}, item4}
\end{itemize}
\end{verbatim}
\end{quote}
will convert the elements of a \acro{CSV} list into an itemised list.

The macro \csx{forcsvlist} applies a function to each element of a
\acro{CSV} list; this can of course be used to implement
\csx{docsvlist}, at the cost of a little clarity.
\begin{ctanrefs}
\item[csvsimple.sty]\CTANref{csvsimple}
\item[datatool \nothtml{\rmfamily}bundle]\CTANref{datatool}
\item[etoolbox.sty]\CTANref{etoolbox}
\item[pgfkeys.sty]Distributed as part of \CTANref{pgf}
\end{ctanrefs}
\LastEdit*{2013-09-10}