summaryrefslogtreecommitdiff
path: root/graphics/circuit_macros/doc/body.tex
blob: d1fb66d6261574e288ce8ecb76b772fd4911f41e (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
% body.tex
\newcommand{\bq}{}
\newcommand{\dpic}{{\bq dpic}\xspace}
\newcommand{\Dpic}{{\bq Dpic}\xspace}
\newcommand{\dvips}{{\bq dvips}\xspace}
\newcommand{\gpic}{{\bq gpic}\xspace}
\newcommand{\Gpic}{{\bq Gpic}\xspace}
\newcommand{\groff}{{\bq groff}\xspace}
\newcommand{\latex}{\LaTeX\xspace}
\newcommand{\linespec}{{\sl linespec}\xspace}
\newcommand{\MetaPost}{{\bq MetaPost}\xspace}
\newcommand{\Mfour}{{\bq m4}\xspace}
\newcommand{\mfpic}{{\bq mfpic}\xspace}
\newcommand{\PDF}{{\bq PDF}\xspace}
\newcommand{\pic}{{\bq pic}\xspace}
\newcommand{\Pic}{{\bq Pic}\xspace}
\newcommand{\Postscript}{{\bq Postscript}\xspace}
\newcommand{\PSTricks}{{\bq PSTricks}\xspace}
\newcommand{\SVG}{{\bq SVG}\xspace}
\newcommand{\tex}{\TeX\xspace}
\newcommand{\Textregistered}{\textregistered\xspace}
\newcommand{\TPGF}{{\bq Ti{\it k}z~PGF}\xspace}
\newcommand{\Tikz}{{\bq Ti{\it k}z}\xspace}
\newcommand{\tpic}{{\bq tpic}\xspace}
\newcommand{\xfig}{{\bq xfig}\xspace}
\newcommand{\Xfig}{{\bq Xfig}\xspace}
%
\newcommand{\xection}[1]{\section[\texorpdfstring{#1\ \dotfill}{#1}]{#1}}
\newcommand{\NVL}{\\\hspace*{\parindent}}
\newcommand{\brtt}{\hfill\break\hspace*\parindent}
\newcommand{\lbr}{{\tt\char123}}
\newcommand{\rbr}{{\tt\char125}}
\newcommand{\bsl}{{\tt\char92}}
\newcommand{\SR}[1]{\hyperref[#1]{Section~\ref*{#1}}}
\newcommand{\PR}[1]{\hyperref[#1]{page~\pageref*{#1}}}
\newcommand{\FR}[1]{\hyperref[#1]{Figure~\ref*{#1}}}
\newcommand{\FRS}[1]{\hyperref[#1]{Figures~\ref*{#1}}}
\newcommand{\REF}[1]{\hyperref[#1]{\ref*{#1}}}
\newcommand{\LQ}{\char96}
\newcommand{\RQ}{\char39}
%
\newcommand{\Example}[1]{\vspace{\parsep}\noindent {\bf Example #1:}}
%
  \pdfbookmark[section]{\contentsname}{toc}
\begin{multicols}{2}
  \tableofcontents
\end{multicols}
%\enlargethispage{\baselineskip}
%
\xection{Introduction\label{Introduction:}}
   \begin{quotation}\noindent
%  Before every conference, I find Ph.D.s in on weekends running back
%  and forth from their offices to the printer.
   It appears that people
   who are unable to execute pretty pictures with pen and paper find it
   gratifying to try with a computer~\cite{Landauer95}.
   \end{quotation}

This manual
%\footnote{%
%This manual is best viewed with a reader that shows bookmarks
%for easy navigation and for exploring the list of defined macros.}%
describes a method for drawing electric circuits and
other diagrams in \latex and web documents.
The diagrams are defined in the simple \pic drawing language~\cite{KRpic}
augmented with \Mfour macros~\cite{KRm4}, and are
processed by \Mfour and a \pic processor to
convert them to \TPGF, \PSTricks, other \latex-compatible code, or \SVG.
In its basic form, the method has the advantages and disadvantages of
\tex itself, since it is macro-based and non-WYSIWYG,
with ordinary text input.  The book from which the above quotation
is taken correctly points out that the payoff can be in quality of
diagrams at the price of the time spent in learning how to draw them.

A collection of basic components, most based on IEEE
standards~\cite{IEEEstd},
and conventions for their internal
structure are described.  Macros such as these are only a starting
point, since it is often convenient to customize elements or to package
combinations of them for particular drawings.

\xection{Using the macros\label{Using:}}
This section describes the basic process of adding circuit diagrams to
\latex documents to produce postscript or pdf files.  On some operating
systems, project management software with graphical interfaces can be used
to automate the process,
but the steps can also be performed by a script,
makefile, or by hand for simple documents as described in~\SR{Quickstart:}.

The diagram source file is preprocessed as illustrated in
\FR{Flowdiag}.  A configuration file is read by \Mfour,
followed by the diagram source.
The result is passed through a
\pic interpreter to produce {\tt .tex} output that can be inserted
into a {\tt .tex} document using the \verb|\input| command.

\begin{figure}[hbt]
 \pdftooltip{\input Flowdiag }{Flow diagram for the inclusion of figures}
 \caption{Inclusion of figures and macros in the \latex document.
 \label{Flowdiag}}
 \end{figure}

\noindent
The interpreter output contains
\TPGF~\cite{tikz} commands,
\PSTricks~\cite{pstricks} commands,
basic \latex graphics, 
\tpic specials, or other formats,
depending on the chosen options.
These variations are described in \SR{Alternative:}.

There are two principal choices of \pic interpreter.  One is~\dpic,
described later in this document.  A partial alternative is
GNU {\bq gpic -t} (sometimes simply named \pic)~\cite{gpic}
together with a printer driver
that understands \tpic specials, typically {\bq dvips}~\cite{dvips}.
The \dpic processor extends the pic language in small but important ways;
consequently, some of the macros and examples in this distribution work fully
only with \dpic.
\Pic processors contain basic macro facilities, so some of the
concepts applied here do not require \Mfour.

\subsection{Quick start\label{Quickstart:}}
The contents of file {\tt quick.m4} and resulting diagram are shown in
\FR{quick} to illustrate the language
% to show several ways for placing circuit elements,
%and to provide sufficient information for producing
and the production of basic labeled circuits.
\begin{figure}[h!]
   \parbox{\textwidth}{\small\verbatiminput{quick.m4}}%
   \hfill\llap{\raise-1.15in\hbox{\input quick }}%
%  \hfill\llap{\raise-1.15in\hbox{\pdftooltip{\input quick }%
%  {The file {\tt quick.m4} and resulting diagram.
%    There are several ways of drawing the same picture; for example,
%     nodes (such as {\tt Origin}) can be defined and circuit branches
%     drawn between them; or absolute coordinates can be used (e.g.,
%     {\tt source(up\_ from (0,0) to (0,0.75))} ).  Element sizes and styles
%     can be varied as described in later sections.}}}%
   \vspace*{-\baselineskip}%
   \caption{The file {\tt quick.m4} and resulting diagram.
     There are several ways of drawing the same picture; for example,
      nodes (such as {\tt Origin}) can be defined and circuit branches
      drawn between them; or absolute coordinates can be used (e.g.,
      {\tt source(up\_ from (0,0) to (0,0.75))} ).  Element sizes and styles
      can be varied as described in later sections.\label{quick}}%
   \end{figure}

\subsubsection{\protect{Using \Mfour}%
\label{Usingmfour:}}
The command

  {\vspace*\parsep\tt
    m4 {\sl filename \ldots}
   \vspace*\parsep}

\noindent
causes \Mfour\ to search for the named
files in the current directory and directories specified
by environmental variable {\tt M4PATH}. 
Set {\tt M4PATH} to the full name (i.e., the path) of the directory containing
{\tt libcct.m4} and the other circuit library {\tt .m4} files; otherwise
invoke \Mfour\ as {\tt m4 -I} {\sl installdir} 
where {\sl installdir} is the path to the directory
containing the library files.
Now there are at least two basic possibilities as follows,
but be sure to read \SR{Simplifications:} for simplified use.

\subsubsection{\protect{Processing with \dpic and \PSTricks or \TPGF}%
\label{Processingwithpstricks:}}
If you are using \dpic  with \PSTricks,
put \verb|\usepackage{pstricks}| in the main \latex source file header and
type the following commands or put them into a script:

  {\vspace*\parsep\tt
    m4 pstricks.m4 quick.m4 > quick.pic
    \brtt
    dpic -p quick.pic > quick.tex
   \vspace*\parsep}


\noindent
To produce \TPGF code,
the \latex header should contain \verb|\usepackage{tikz}|.
The commands are modified to read \verb|pgf.m4|
and invoke the {\tt-g} option of \dpic as follows:

  {\vspace*\parsep\tt
% {\tt
  m4 pgf.m4 quick.m4 > quick.pic
    \brtt
  dpic -g quick.pic > quick.tex
   \vspace*\parsep}
 
A configuration file ({\tt pstricks.m4} and {\tt pgf.m4} in the
above examples) is {\em always} the first file to be given to \Mfour.
Put the following or its equivalent in the document body:
\begin{verbatim}
\begin{figure}[hbt]
   \centering
   \input quick
   \caption{Customized caption for the figure.}
   \label{Symbolic_label}
\end{figure}
\end{verbatim}
Then for \PSTricks,
the commands ``{\tt latex} {\sl file}{\tt;} {\tt dvips} {\sl file}''
produce {\sl file}{\tt.ps},
which can be printed or viewed using {\tt gsview}, for example.
For \TPGF,
Invoking PDFlatex on the source produces {\tt .pdf} output directly.
%Whether or not the figure environment is used,
%the essential line in all cases is \verb|\input quick|. 
The essential line is \verb|\input quick| whether or not the figure
environment is used.

The effect of the \Mfour command above is shown in \FR{ConfigA}. 
Configuration files {\tt pstricks.m4} or {\tt pgf.m4}
cause library {\tt libgen.m4}
to be read, thereby defining the macro {\tt cct\_init}.
The diagram source file is then read and
the circuit-element macros in {\tt libcct.m4} are defined during
expansion of {\tt cct\_init}.
\begin{figure}[hbt]
   \input ConfigA
   \caption{The command
     {\tt m4 pstricks.m4 quick.m4 > quick.pic}.
   \label{ConfigA}}
   \end{figure}

\subsubsection{Processing with \gpic\label{Processingwithgpic:}}
If your printer driver understands \tpic specials and
you are using \gpic  (on some systems the \gpic command is {\tt pic}),
the commands are

  {\tt
  m4 gpic.m4 quick.m4 > quick.pic
    \brtt
  gpic -t quick.pic > quick.tex
   \vspace*\parsep}

\noindent
and the figure inclusion statements are as shown:
\begin{verbatim}
\begin{figure}[hbt]
   \input quick
   \centerline{\box\graph}
   \caption{Customized caption for the figure.}
   \label{Symbolic_label}
   \end{figure}
\end{verbatim}

\subsubsection{Simplifications\label{Simplifications:}}
M4 must read a configuration file before any other files,
%followed by the macro definitions in one or more library files,
either before reading the diagram source file or at the beginning of it.
There are several ways to control the process, as follows:
\begin{enumerate}
\item
The macros can be processed by \latex-specific
project software and by graphic applications such as Cirkuit~\cite{KDEApps2009}.
Alternatively when many files are to be processed, a facility such as
Unix ``make,'' which is also available in PC and Mac versions, can be employed
to automate the required commands.  On systems without such
facilities, a scripting language can be used.

\item
The \Mfour commands illustrated above can be shortened to

\verb|m4 quick.m4 > quick.pic|

\noindent
by inserting {\tt include(pstricks.m4)} (assuming \PSTricks processing)
%or {\tt include(libgen.m4)} (assuming the default processor is to be used)
{\em immediately} after the {\tt .PS} line, the effect of which 
%The effect of the first include statement
is shown in \FR{ConfigB}.
However, if you then want to use \TPGF,
the line must be changed to {\tt include(pgf.m4)}.
%and the second in \FR{ConfigC}.
\begin{figure}[h!]
   \input{ConfigB}
   \caption{The command {\tt m4 quick.m4 > quick.pic},
   with {\tt include(pstricks.m4)} preceding {\tt cct\_init}.}
   \label{ConfigB}
   \end{figure}
%\begin{figure}[h!]
%   \input{ConfigC}
%   \caption{The command {\tt m4 quick.m4 > quick.pic},
%   with {\tt include(libgen.m4)} preceding {\tt cct\_init}, causing
%   the default configuration file to be read.}
%   \label{ConfigC}
%   \end{figure}

%\item
%On some systems, setting the environment variable {\tt M4PATH} to {\sl
%installdir} allows the {\tt -I} {\sl installdir} option of \Mfour to
%be omitted, but it will be kept in following examples.

\item
In the absence of a need to examine the file {\tt quick.pic},
the commands for producing the {\tt .tex} file can be reduced
(provided the above inclusions have been made) to

\verb%m4 quick.m4 | dpic -p > quick.tex%

\item
It may be desirable to invoke \Mfour and \dpic automatically from the
document file as shown:

{\tt \verb^\documentclass{article}^ \brtt
\verb^\usepackage{tikz}^ \brtt
\verb^\newcommand\mtotex[2]{\immediate\write18{m4 ^%-I^ {\sl installdir}
\verb^#2.m4 | dpic -#1 > #2.tex}}%^\break
\verb^\begin{document}^ \brtt
\verb^\mtotex{g}{FileA} % Generate FileA.tex^ \brtt
\verb^\input{FileA.tex} \par^ \brtt
\verb^\mtotex{g}{FileB} % Generate FileB.tex^ \brtt
\verb^\input{FileB.tex}^ \brtt
\verb^\end{document}^
   \vspace*\parsep}

The first argument of \verb|\mtotex| is a {\tt p} for pstricks or
{\tt g} for pgf.
Sources \verb|FileA.m4| and \verb|FileB.m4| must contain any required
\verb|include| statements,
and the main document should be processed using
the latex or pdflatex option \verb|-shell-escape|.
If the {\tt M4PATH} environment variable is not set then insert
{\tt -I }{\sl installdir} after {\tt m4} in the command definition,
where {\sl installdir} is the absolute path to the installation directory.
This method processes the picture source each time \latex is run, so for
large documents containing many diagrams, the \verb|\mtotex|
lines could be commented out after debugging the corresponding graphic.
A derivative of this method that allows the insertion of
\pic code into a \Tikz picture is described in \SR{Tikzwithpic:}.

\item
You can put several diagrams into a single source file.
Make each diagram the body of a \latex macro, as shown:

%\enlargethispage{\baselineskip}
\par
\verb|\newcommand{\diaA}{%|\NVL
\verb|.PS|\NVL
{\sl drawing commands}\NVL
\verb|.PE|\NVL
\verb|\box\graph }%  \box\graph not required for dpic|\NVL
\verb|\newcommand{\diaB}{%|\NVL
\verb|.PS|\NVL
{\sl drawing commands}\NVL
\verb|.PE|\NVL
\verb|\box\graph }%  \box\graph not required for dpic|\NVL
Produce a {\tt .tex} file using \verb|\mtotex|
or \Mfour and \dpic or \gpic,
insert the {\tt .tex} into the \latex source, and
invoke the macros \verb^\diaA^ and \verb^\diaB^ at the appropriate places.
\end{enumerate}

\subsection{Including the libraries\label{Libraries:}}
The configuration files for \dpic are as follows,
depending on the output format (see \SR{Alternative:}):
{\tt pstricks.m4, pgf.m4, mfpic.m4, mpost.m4, postscript.m4, psfrag.m4, svg.m4,
 gpic.m4,} or {\tt xfig.m4}.
The file {\tt psfrag.m4} simply defines the macro {\tt psfrag\_} and
then reads {\tt postscript.m4}.
For \gpic, the configuration file is {\tt gpic.m4}.
The usual case for producing circuit diagrams is to read
{\tt pstricks.m4} or {\tt pgf.m4} first when \dpic is the postprocessor or
to set one of these as the default configuration file.

At the top of each diagram source, put one or more initialization
commands; that is,

{\tt cct\_init, log\_init, sfg\_init, darrow\_init, threeD\_init}

\noindent
or, for diagrams not requiring specialized macros, {\tt gen\_init}.
As shown in \FRS{ConfigA} and~\REF{ConfigB},
each initialization command reads in the appropriate macro
library if it hasn't already been read;
for example, {\tt cct\_init} tests whether {\tt libcct.m4} has been
read and includes it if necessary.

A few of the distributed example files contain other experimental macros
that can be pasted into diagram source files; see
{\tt Flow.m4} or {\tt Buttons.m4}, for example.

The libraries contain hints and explanations that might help in debugging
or if you wish to modify any of the macros.  Macros are generally named
using the obvious circuit element names so that programming becomes something
of an extension of the \pic language.  Some macro names end in an underscore
to reduce the chance of name clashes.  These can be invoked in the
diagram source but there is no long-term guarantee that their names and
functionality
will remain unchanged. Finally, macros intended only for internal use
begin with the characters {\tt m4}.

\xection{\Pic essentials\label{Pic:}}

\Pic source is a sequence of lines in a file.
The first line of a diagram begins with {\tt .PS} with optional following
arguments, and the last line is normally {\tt .PE}.
Lines outside of these pass through the \pic processor unchanged.

The visible objects can be divided conveniently into two classes, the
{\em linear} objects {\tt line, arrow, spline, arc,} and the
{\em planar} objects {\tt box, circle, ellipse.}

The object {\tt move} is linear but draws nothing.  A compound object,
or {\tt block,} is planar and consists of a pair of square brackets enclosing
other objects, as described in \SR{Compoundobjects:}.
Objects can be placed using absolute coordinates or relative to other objects.

\Pic allows the definition of real-valued variables, which are alphameric
names beginning with lower-case letters, and computations using them.
Objects or locations on the diagram can be given symbolic names
beginning with an upper-case letter.

\subsection{Manuals\label{Manuals:}}
The classic \pic manual~\cite{KRpic} is still a good introduction to \pic, but
a more complete manual~\cite{Raymond95} can be found in the GNU \groff\
package, and both are available on the web~\cite{KRpic,Raymond95}.  Reading
either will give you competence with \pic in an hour or two.  Explicit mention
of {\tt *roff} string and font constructs in these manuals should be replaced by
their equivalents in the \latex context.  A man-page language summary is
appended to the \dpic manual~\cite{Aplevich2011}.

A web search will yield good discussions of ``little languages'';
for \pic in particular, see Chapter~9 of~\cite{Bentley88}.
Chapter~1 of reference~\cite{Goossens97} also contains a brief
discussion of this and other languages.

\subsection{The linear objects: {\tt line, arrow, spline, arc}%
\label{Linearobjects:}}
A line can be drawn as follows:

{\tt line from} {\sl position} {\tt to} {\sl position}

\noindent
where {\sl position} is defined below or

{\tt line} {\sl direction} {\sl distance}

\noindent
where {\sl direction} is one of {\tt up,} {\tt down,} {\tt left,}
{\tt right.}  When used with the \Mfour macros described here, it is
preferable to add an underscore: {\tt up\_,} {\tt down\_,} {\tt left\_,}
{\tt right\_.}  The {\sl distance} is a number or expression
and the units are inches, but the assignment

{\tt scale = 25.4}

\noindent
has the effect of changing the units to millimetres,
as described in \SR{Scaling:}.

Lines can also be drawn to any distance in any direction.  The example,

{\tt line up\_ 3/sqrt(2) right\_ 3/sqrt(2) dashed}

\noindent
draws a line 3 units long from the current location,
at a $45^\circ$ angle above horizontal.
Lines (and other objects) can be specified as {\tt dotted,} {\tt dashed,} or
{\tt invisible,} as above.

The construction

{\tt line from A to B chop x}

\noindent
truncates the line at each end by {\tt x} (which may be negative)
or, if {\tt x} is omitted, by
the current circle radius, which is convenient when A and B are
circular graph nodes, for example.  Otherwise

{\tt line from A to B chop x chop y}

\noindent
truncates the line by {\tt x} at the start and {\tt y} at the end.

Any of the above means of specifying line (or arrow) direction and length
will be called a \linespec.

Lines can be concatenated.  For example, to draw a triangle:

{\tt line up\_ sqrt(3) right\_ 1 then down\_ sqrt(3) right\_ 1 then left\_ 2}

\subsection{Positions\label{Positions:}}
A {\sl position} can be defined by a coordinate pair, e.g. {\tt 3,2.5},
more generally using parentheses by {\tt (}{\sl expression, expression}{\tt )},
as a sum or difference as
{\tt{\sl position} $+$ ({\sl expression, expression})},
or by the construction {\tt (}{\sl position, position}{\tt )},
the latter taking the $x$-coordinate from the first
position and the $y$-coordinate from the second.  A position can be
given a symbolic name beginning with an upper-case letter,
e.g. {\tt Top:~(0.5,4.5)}.  Such a definition does not affect the calculated
figure boundaries.  The current position {\tt Here} is always defined and
is equal to $(0,0)$ at the beginning of a diagram or block.
The coordinates of a position are accessible, e.g. {\tt Top.x} and
{\tt Top.y} can be used in expressions.  The center, start, and end of
linear objects (and the defined points of other objects as described below)
are predefined positions, as shown in the following example,
which also illustrates how to refer to a previously drawn element if it has
not been given a name:

{\tt line from last line.start to 2nd last arrow.end then to 3rd line.center}

Objects can be named (using a name commencing with an upper-case letter),
for example:

{\tt Bus23: line up right}

\noindent
after which, positions associated with the object can be referenced using the
name; for example:

{\tt arc cw from Bus23.start to Bus23.end with .center at Bus23.center}

An arc is drawn by specifying its rotation, starting point, end point, and
center, but sensible defaults are assumed if any of these are omitted.
Note that

{\tt arc cw from Bus23.start to Bus23.end}

\noindent
does {\em not} define the arc uniquely; there are two arcs that satisfy this
specification.
This distribution includes the \Mfour macros

{\tt arcr( {\sl position, radius, start radians, end radians, modifiers, ht})
\hfill\break\indent
     arcd( {\sl position, radius, start degrees, end degrees, modifiers, ht})
\hfill\break\indent
     arca( {\sl chord linespec,} ccw|cw, {\sl radius, modifiers})
}

\noindent to draw uniquely defined arcs.
If the fifth argument of {\tt arcr} or {\tt arcd} contains {\tt ->} or {\tt <-}
then a midpoint arrowhead of height specified by arg6 is added.
For example,

{\tt arcd((1,-1),{},0,-90,<- outlined "red") dotted}

\noindent draws a red dotted arc with midpoint arrowhead,
 centre at $(1,-1),$ and default radius.
 The example

{\tt arca(from (1,1) to (2,2),{,}1,->)}

\noindent draws an acute angled arc with arrowhead on the chord defined by the
first argument.

The linear objects can be given arrowheads at the start, end, or both ends,
for example:

{\tt line dashed <- right 0.5\hfill\break
\hspace*{\parindent}%
arc <-> height 0.06 width 0.03 ccw from Here to Here+(0.5,0)
 \char92\hfill\break
\hspace*{2\parindent}%
   with .center at Here+(0.25,0)\hfill\break
\hspace*{\parindent}%
spline -> right 0.5 then down 0.2 left 0.3 then right 0.4}

The arrowheads on the arc above have had their shape adjusted using the
{\tt height} and {\tt width} parameters.

\subsection{The planar objects: {\tt box, circle, ellipse}, and text%
\label{Planarobjects:}}
Planar objects are drawn by specifying the width, height, and position, thus:

{\tt A: box ht 0.6 wid 0.8 at (1,1)}

\noindent
after which, in this example, the position {\tt A.center} is defined,
and can be referenced simply as {\tt A}.
The compass points {\tt A.n,} {\tt A.s,} {\tt A.e,} {\tt A.w,} {\tt A.ne,}
{\tt A.se,} {\tt A.sw,} {\tt A.nw} are automatically defined, as are
the dimensions {\tt A.height} and {\tt A.width.}
Planar objects can also be placed by specifying the location of a defined
point; for example, two touching circles can be drawn as shown:

{\tt circle radius 0.2\hfill\break 
\hspace*{\parindent}%
circle diameter (last circle.width * 1.2) with .sw at last circle.ne}

The planar objects can be filled with gray or colour.
For example, either

{\tt box dashed fill\_({\sl number})}\quad or\quad
 {\tt box dashed outlined "{\sl color}" shaded "{\sl color}"}

\noindent
produces a dashed box. The first case has a gray fill determined by
{\sl number}, with $0$ corresponding to black and $1$ to white;
the second case allows color outline and fill, the color strings depending on
the postprocessor.
Postprocessor-compatible RGB color strings are produced by the macro
{\tt rgbstring({\sl red fraction, green fraction, blue fraction})};
to produce an orange fill for example:

{\tt ... shaded rgbstring( 1, 0.645, 0)}

Basic colours for lines and fills are provided by \gpic  and \dpic,
but more elaborate line and fill styles or other effects
can be incorporated, depending on the postprocessor, using
%by inserting postprocessor commands using
%{\tt \char92 special} commands or
%other lines beginning with a backslash in the drawing code.  In fact,
%arbitrary lines can be inserted into the output using

{\tt command "}{\sl string}{\tt "}

\noindent where {\sl string} is one or more postprocessor command lines.

Arbitrary text strings, typically meant to be typeset by \latex, are
delimited by double-quote characters and occur in two ways.  The first
way is illustrated by

\verb|"\large Resonances of $C_{20}H_{42}$"|
 \verb|wid |{\sl x}\verb| ht |{\sl y}\verb| at |{\sl position}

\noindent
which writes the typeset result, like a box, at {\sl position} and tells
\pic its size.  The default size assumed by \pic is given by parameters
{\tt textwid} and {\tt textht} if it is not specified as above.
The exact typeset size of formatted text can be obtained
as described in \SR{Interaction:}.  The second occurrence
associates one or more strings with an object, e.g., the following writes
two words, one above the other, at the centre of an ellipse:
%\enlargethispage{\baselineskip}

\verb|ellipse "\bf Stop" "\bf here"|

\noindent
The C-like \pic function
 {\tt sprintf("{\sl format string}",{\sl numerical arguments})}
is equivalent to a string.

\subsection{Compound objects\label{Compoundobjects:}}
A compound object is a group of statements enclosed in square
brackets.  Such an object is placed by default as if it were a box, but
it can also be placed by specifying the final position of a defined point.
A defined point is the center or compass corner of the bounding box
of the compound object or one of its internal objects.
Consider the last line of the code fragment shown:

\noindent%
\verb|  Ands: [ right_|\\
\verb|          And1: AND_gate|\\
\verb|          And2: AND_gate at And1 - (0,And1.ht*3/2)|\\
\verb|          |$\ldots$\\
\verb|        ] with .And2.In1 at| {\sl position} % (K.x,IC5.Pin9.y)|

The two gate macros evaluate to compound objects containing {\tt Out},
{\tt In1}, and other locations.  The final positions of all objects
inside the square brackets are determined in the last line by
specifying the position of {\tt In1} of gate {\tt And2}.

\subsection{Other language facilities\label{Otherlanguage:}}

All objects have default sizes, directions, and other characteristics,
so part of the specification of an object can sometimes be profitably
omitted.

Another possibility for defining positions is 

{\sl expression} {\tt between} {\sl position}
 {\tt and} {\sl position}

\noindent%
which means 

$\hbox{\sl 1st position} + \hbox{\sl expression} \times 
  (\hbox{\sl 2nd position} - \hbox{\sl 1st position})$

\noindent and which can be abbreviated as

{\sl expression} {\tt <} {\sl position} {\tt ,} {\sl position} {\tt >}

\noindent%
Care has to be used in processing the latter construction with \Mfour,
since the comma may have to be put within quotes, {\tt `,'}
to distinguish it from the {\tt m4} argument separator.

Positions can be calculated using expressions containing variables.
The scope of a position is the current block.  Thus, for example,

{\tt
  theta = atan2(B.y-A.y,B.x-A.x)

  line to Here+(3*cos(theta),3*sin(theta)).
  }

Expressions are the usual algebraic combinations of primary quantities:
constants, environmental parameters such as {\tt scale,} variables,
horizontal or vertical coordinates of terms such as
{\sl position}{\tt.x} or {\sl position}{\tt.y},
dimensions of \pic objects, e.g. {\tt last circle.rad}.
The elementary algebraic operators are
{\tt +, -, *, /, \%, =, +=, -=, *=, /=,} and {\tt \%=,}
similar to the C language.

The logical operators {\tt ==, !=, <=, >=, >,} and {\tt <} apply to
expressions and strings.  A modest selection of numerical functions is
also provided: the single-argument functions {\tt sin, cos, log, exp,
sqrt, int}, where {\tt log} and {\tt exp} are base-10, the two-argument
functions {\tt atan2, max, min,} and the random-number generator {\tt
rand()}.  Other functions are also provided using macros.

A \pic manual should be consulted for details, more examples, and
other facilities, such as the branching facility

\verb|if |{\sl expression}\verb| then { |{\sl anything} 
  \verb|} else { |{\sl anything}\verb| }|,

\noindent%
the looping facility

\verb|for |{\sl variable}\verb| = |{\sl expression}\verb| to |% 
{\sl expression}\verb| by |{\sl expression}\verb| do { |%
{\sl anything}\verb| }|,

\noindent%
%\enlargethispage{\baselineskip}
operating-system commands, \pic macros, and external file inclusion.

\xection{Two-terminal circuit elements\label{Basictwo:}}
There is a fundamental difference between the two-terminal elements, each
of which is drawn along an invisible straight-line segment,
and other elements, which are compound objects mentioned
in \SR{Compoundobjects:}.  The two-terminal element macros follow a
set of conventions described in this section, and other elements will
be described in \SR{Composite:}.

\subsection{Circuit and element basics\label{Basics:}}
A list of the library macros and their arguments is in
\SR{defines}.  The arguments have default values, so that only
those that differ from defaults need be specified.

\FR{BigResistor}, which shows a resistor, also serves as
an example of \pic commands.
%Consider the resistor shown in \FR{BigResistor},
%which also serves as an example of \pic commands.
The first part of the source file for this figure is 
%as follows:
on the left:

\begin{figure}[hbt]
   \parbox{2in}{\tt .PS\\ \hbox{}\quad cct\_init\\ \hbox{}\quad linewid = 2.0\\ 
     \hbox{}\quad linethick\_(2.0)\\ R1: resistor}
   \raisebox{-0.3in}{\hbox{\input{BigResistor.tex}}}
   \caption{Resistor named {\tt R1}, showing the size parameters,
     enclosing block, and predefined positions.}
   \label{BigResistor}
   \end{figure}
The lines of \FR{BigResistor}
and the remaining source lines of the file are explained below:
\begin{itemize}
\item The first line invokes the macro {\tt cct\_init} that
   loads the library {\tt libcct.m4} 
   and initializes local variables needed by some circuit-element macros.

\item
   The sizes of circuit elements are proportional to the \pic environmental
   variable {\tt linewid}, so redefining this variable changes element
   sizes.  The element body is drawn in proportion to {\tt dimen\_},
   a macro that evaluates to {\tt linewid} unless redefined, and the default
   element length is {\tt elen\_}, which evaluates to
   {\tt dimen\_*3/2} unless redefined.
   Setting {\tt linewid} to 2.0 as in the example means that the default element
   length becomes 3.0\,in.
   For resistors, the default length of the body is {\tt dimen\_/2,} and the
   width is {\tt dimen\_/6.} All of these values can be customized.
   Element scaling and the use of SI units is discussed further in
   \SR{Scaling:}.

\item The macro {\tt linethick\_} sets the default thickness of subsequent
   lines (to 2.0\,pt in the example).
   Macro arguments are written within parentheses
   following the macro name, with no space between the name and the
   opening parenthesis.  Lines can be broken before macro arguments
   because \Mfour and \dpic ignore white space immediately preceding
   arguments.  Otherwise, a long line can be continued to the next
   by putting a backslash as the rightmost character. 
\item The two-terminal element macros expand to sequences of drawing commands
   that begin with {\tt `line invis \linespec'},
   where \linespec is the first argument of the macro if it
   is non-blank, otherwise the line is drawn a distance
   {\tt elen\_} in the current direction, which is to the right by
   default.
%  All this is handled by the macro {\tt eleminit\_}, which also
%  calculates the length and angle of the invisible line for later use.
   The invisible line is first drawn, then the element is drawn
   on top of it.
   The element---rather, the initial invisible line---can
   be given a name, {\tt R1} in the example, so that positions
   {\tt R1.start}, {\tt R1.centre}, and {\tt R1.end} are automatically
   defined as shown.
\item The element body is overlaid by a block, which can be
   used to place labels around the element.  The block
   corresponds to an invisible rectangle with horizontal top and bottom lines,
   regardless of the direction in which the element is drawn.  A
   dotted box has been drawn in the diagram to show the block boundaries.
\item The last sub-element, identical to the first in two-terminal
   elements, is an invisible line that can be referenced later to
   place labels or other elements.
%  This might be over-kill.
   If you create your own macros, you might choose simplicity over generality,
   and include only visible lines.
  \end{itemize}

To produce \FR{BigResistor}, the following embellishments
were added after the previously shown source:
{\small \input BigResistor2.verb }

\begin{itemize}
\item The line thickness is set to the default thin value of \hbox{0.4\,pt},
   and the box displaying the element body block is drawn.  Notice how the
   width and height can be specified, and the box centre positioned at
   the centre of the block.
\item The next paragraph draws two objects, a spline with an arrowhead,
   and a string left justified at the end of the spline.  Other
   string-positioning modifiers than {\tt ljust} are {\tt rjust,}
   {\tt above,} and {\tt below.}

\item The last paragraph invokes a macro for dimensioning diagrams.
   \end{itemize}

\subsection{The two-terminal elements\label{Twoterminal:}}
The two-terminal elements are shown in \FRS{CctTable} to~\REF{Diodes}
and \FRS{Fuses} to~\REF{Switches}.
Several elements are included more than once to illustrate
some of their arguments, which are listed in \SR{defines}.
\begin{figure}[h!]
   \input CctTable
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \caption{Basic two-terminal elements, showing some variations.}
   \label{CctTable}
    \end{figure}

The first macro argument specifies
the invisible line segment along which the element is drawn.
If the argument is blank,
the element is drawn from the current position in the current drawing
direction along a default length.
The other arguments produce variants of the default elements.
\begin{figure}[t!]
   \input Sources
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \caption{Sources and source-like elements.}
   \label{Sources}
   \end{figure}
\begin{figure}[t!]
   \input Diodes
   \caption{The macro
     {\tt diode(\linespec,B|CR|D|L|LE[R]|P[R]|S|T|V|v|w|Z|{\sl chars},[R][E])}.
      Appending {\tt K} to the second argument draws an open arrowhead.}
   \label{Diodes}
   \end{figure}
Thus, for example,

{\tt resistor(up\_ 1.25,7)}

\noindent%
draws a resistor 1.25 units long up from the current position, with $7$
vertices per side.
The macro {\tt up\_} evaluates to {\tt up} but also resets the current
directional parameters to point up.

\FR{Emarrows} contains radiation-effect arrows for embellishing two-terminal
and other macros.
The arrow stems are named {\sl A1}, {\sl A2},
and each pair is drawn in a \verb|[]| block, with
the names {\sl Head} and {\sl Tail} defined to
aid placement near another device.  The second argument specifies
absolute angle in degrees (default 135 degrees).
\begin{figure}[h!t]
   \input Emarrows
   \caption{Radiation arrows: {\tt em\_arrows({\sl type, angle, length})}}
   \label{Emarrows}
   \end{figure}
The arrows are drawn relative to the diode direction by the {\tt LE}
option in \FR{Diodes}.  For absolute arrow directions, one can
define a wrapper (see \SR{Writing:}) for the {\tt diode} macro to draw arrows
at 45 degrees, for example:

{\tt define(`myLED',`diode(`\$1'); em\_arrows(N,45)
 with .Tail at last [].ne')}

\begin{figure}[t!]
   \input Fuses
   \caption{Variations of the macros
     {\tt fuse(\linespec, A|dA|B|C|D|E|S|HB|HC, {\sl wid}, {\sl ht})}
     and {\tt cbreaker(\linespec,L|R,D|T|TS)}.}
   \label{Fuses}
   \end{figure}
\begin{figure}[t!]
   \input AmpTable
   \caption{Amplifier, delay, and integrator.}
   \label{AmpTable}
   \end{figure}
\begin{figure}[t!]
   \input Switches
   \caption{The
     {\tt switch(\linespec,L|R,{\sl chars},L|B|D)}
     macro is a wrapper for the macros 
     {\tt lswitch(\linespec,[L|R],[O|C][D][K][A])},
     {\tt bswitch(\linespec,[L|R],[O|C])},
     and the many-optioned
     {\tt dswitch(\linespec,R,W[ud]B[K] {\sl chars})} shown.
     The switch is drawn in the current drawing direction.
     A second-argument {\tt R} produces a mirror
     image with respect to the drawing direction.}
   \label{Switches}
   \end{figure}
Most of the two-terminal elements are oriented; that is, they have
a defined direction or polarity.  Several element macros include an argument
that reverses polarity, but there is also a more general mechanism,
as follows.

The first argument of the macro

{\tt reversed(`}{\sl macro name}{\tt',}{\sl macro arguments}{\tt )}

\noindent
is the name of a two-terminal element in quotes, followed by the
element arguments.  The element is drawn with reversed direction.
Thus,

{\tt diode(right\_ 0.4); reversed(`diode',right\_ 0.4)}

\noindent
draws two diodes to the right, but the second one points left.

Similarly, the macro

{\tt resized(}{\sl factor},`{\sl macro name}',{\sl macro arguments}{\tt )}

\noindent
can be used to resize the body of an element by temporarily multiplying
the {\tt dimen\_} macro by {\sl factor}. More general resizing should be
done by redefining {\tt dimen\_} as described in \SR{Circuitscaling:}.
These two macros can be nested; the following scales the above example
by 1.8, for example

{\tt resized(1.8,`diode',right\_ 0.4);}
{\tt resized(1.8,`reversed',`diode',right\_ 0.4)}

\FR{Variable} shows some two-terminal elements with
arrows or lines overlaid to indicate variability using the macro

{\tt variable(`}{\sl element}{\tt',{\sl type},{\sl angle},{\sl length})},

\noindent
where {\sl type} is one of {\tt A, P, L, N,} with {\tt C} or {\tt S}
optionally appended to indicate continuous or stepwise variation.
Alternatively, this macro
can be invoked similarly to the label macros in
\SR{Labels:} by specifying an empty first argument;
thus, the following line draws the resistor in \FR{Variable}:

   {\tt resistor(down\_ dimen\_); variable(,uN)}

\begin{figure}[h!t]
\vspace*{-\baselineskip}
   \input Variable
   \caption{Illustrating
{\tt variable(`{\sl element}',%
[A|P|L|[u]N][C|S],{\sl angle},{\sl length})}.
   For example,\break {\tt variable(`capacitor(down\_ dimen\_)')} draws
   the leftmost capacitor shown above, and {\tt variable(`resistor(down\_
   dimen\_)',uN)} draws the resistor.  The default angle is
   45${}^{\circ}$, regardless of the direction of the element.  The array
   on the right shows the effect of the second argument.}
   \label{Variable}
   \end{figure}

\subsection{Branch-current arrows\label{Branchcurrent:}}
Arrowheads and labels can be added to conductors using basic
\pic statements.  For example, the following line adds a labeled
arrowhead at a distance {\tt alpha} along a horizontal line that has
just been drawn.  Many variations of this are possible:

  \verb|arrow right arrowht from last line.start+(alpha,0) "$i_1$" above|

%\enlargethispage{\baselineskip}
Macros have been defined to simplify labelling two-terminal
elements, as shown in \FR{currents}.
The macro

   {\tt b\_current({\sl label,} above\_|below\_, In|O[ut], Start|E[nd],
   {\sl frac})}

\noindent
draws an arrow from the start of the last-drawn two-terminal element
{\sl frac} of the way toward the body.
\begin{figure}[h!t]
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \input currents
   \caption{Illustrating {\tt b\_current, larrow,} and {\tt rarrow}.
      The drawing direction is to the right.}
   \label{currents}
   \end{figure}

If the fourth argument is {\tt End}, the arrow is drawn from the end
toward the body.
If the third element is {\tt Out}, the arrow is drawn outward from the body.
The first argument is the desired label, of which the default position is
the macro {\tt above\_,} which evaluates to {\tt above} if the current
direction is right or to {\tt ljust, below, rjust} if the current
direction is respectively down, left, up.  The label is assumed to be
in math mode unless it begins with {\tt sprintf} or a double quote, in which
case it is copied literally.  A non-blank second argument specifies the
relative position of the label with respect to the arrow, for example
{\tt below\_,} which places the label below with respect to the current
direction.  Absolute positions, for example {\tt below} or {\tt ljust},
also can be specified.

For those who prefer a separate arrow to indicate the reference
direction for current, the macros {\tt larrow({\sl label}, ->|<-,{\sl dist})}
and {\tt rarrow({\sl label}, ->|<-,{\sl dist})} are provided.  The label is
placed outside the arrow as shown in \FR{currents}.  The first
argument is assumed to be in math mode unless
it begins with {\tt sprintf} or a double
quote, in which case the argument is copied literally.  The third argument
specifies the separation from the element.
%\begin{figure}[hbt]
%   \input lrarrows
%   \caption{The {\tt larrow} and {\tt rarrow} macros draw
%    reference-direction arrows adjacent to the element.}
%   \label{lrarrows}
%   \end{figure}

\pagebreak%
\subsection{Labels\label{Labels:}}
   Special macros for labeling two-terminal elements are included:
\par
{\tt
   llabel(} {\sl arg1,arg2,arg3} {\tt )
      \hfill\break\hspace*{\parindent}%
   clabel(} {\sl arg1,arg2,arg3} {\tt )
      \hfill\break\hspace*{\parindent}%
   rlabel(} {\sl arg1,arg2,arg3} {\tt )
      \hfill\break\hspace*{\parindent}%
   dlabel(} {\sl long,lat,arg1,arg2,arg3,}{\tt[X][A|B][L|R])}

The first macro places the three arguments, which are treated as math-mode
strings, on the left side of the element block {\em with respect to the
current direction:} {\tt up, down, left, right.}
The second places the arguments along the centre, and the third along the
right side.
A simple circuit example with labels is shown in \FR{Loop}.
The macro {\tt dlabel} performs these functions for an
obliquely drawn element, placing the three macro arguments at
{\tt vec\_(-long,lat),} {\tt vec\_(0,lat),} and {\tt vec\_(long,lat)}
respectively relative to the centre of the element.
In the fourth argument, an {\tt X} aligns the labels with respect to the line
joining the two terminals rather than the element body, and
{\tt A, B, L, R} use absolute {\tt above, below, left,} or {\tt right} alignment
respectively for the labels.
Labels beginning
with {\tt sprintf} or a double quote are copied literally rather than
assumed to be in math mode.

   Arbitrary \latex including {\bsl\tt includegraphics,} for example,
   can also be placed on a diagram using

   {\tt "}{\sl \latex text}{\tt" wid {\sl width} ht {\sl height}
      at {\sl position}}

\begin{figure}[ht]
   \vspace*{-\baselineskip}
   \parbox{4in}{\small \verbatiminput{Loop.m4}}%
   \hfill\raise-0.5in\hbox{\input Loop }
   \vspace*{-\baselineskip}
   \caption{A loop containing labeled elements, with its source code.}
   \label{Loop}
   \end{figure}

\xection{Placing two-terminal elements\label{Placing:}}
The length and position of a two-terminal element
are defined by a straight-line segment and, possibly, a direction, so
four numbers are required to place the element as in the following example:

{\tt resistor(from (1,1) to (2,1))}.

\noindent
However, \pic has a very useful concept of the current point (explicitly
named {\tt Here}); thus,

{\tt resistor(to (2,1))}

\noindent
is equivalent to

{\tt resistor(from Here to (2,1)).}

Any defined position can be used; for example, if {\sl C1} and {\sl L2}
are names of previously defined two-terminal elements,
then, for example, the following places the resistor: 

{\tt resistor(from L2.end to C1.start)}

A line segment starting at the current position can also be defined using
a direction and length.
To draw a resistor up $d$ units from the current position, for example:

{\tt resistor(up\_ d)}

\noindent
\Pic stores the current drawing direction,
the latter unfortunately limited to {\tt up, down, left, right,}
which is assumed when necessary.
The circuit macros need to know the current direction, so
whenever {\tt up, down, left, right} are used they should be written
respectively as the macros {\tt up\_, down\_, left\_, right\_} as in
the above example.

To allow drawing circuit objects in other than the standard four directions,
a transformation matrix
is applied at the macro level to generate the required \pic code.
Potentially, the matrix can be used for other transformations.
The macro

{\tt setdir\_({\sl direction, default direction})}

\noindent
is preferred when setting drawing direction.  The {\sl direction} arguments
are of the form

{\tt R[ight] | L[eft] | U[p] | D[own] | {\sl degrees}},

\noindent
but the macros
{\tt Point\_(}{\sl degrees}{\tt ),}
{\tt point\_(}{\sl radians}{\tt ),}
and {\tt rpoint\_(}{\sl relative linespec}{\tt )} are employed in many macros
to re-define the entries
of the matrix
(named {\tt m4a\_}, {\tt m4b\_}, {\tt m4c\_}, and {\tt m4d\_})
for the required rotation.
The macro {\tt eleminit\_} in the two-terminal elements invokes
{\tt rpoint\_} with a specified or default {\sl linespec}
to establish element length and direction.

As shown in \FR{Oblique},
``{\tt Point\_(-30); resistor}'' draws a resistor
along a line with slope of~-30 degrees, and ``{\tt rpoint\_(to Z)}'' sets
the current direction cosines to point from the current location to location Z.
Macro {\tt vec\_(x,y)}
evaluates to the position {\tt (x,y)} rotated as defined by the
argument of the previous
{\tt setdir\_, Point\_, point\_} or {\tt rpoint\_} command.
The principal device used to define relative locations in the circuit macros
is {\tt rvec\_(x,y)}, which evaluates to position {\tt Here + vec\_(x,y)}.
Thus, {\tt line to rvec\_(x,0)} draws a line of length {\tt x} in the current
direction.

\FR{Oblique} illustrates that some hand placement of labels
using {\tt dlabel} may be useful when elements are drawn obliquely.
The figure also illustrates that any commas within \Mfour arguments must
be treated specially because the arguments are separated by commas.
Argument commas are protected either by parentheses as in
{\tt inductor(from Cr to Cr+vec\_(elen\_,0))}, or by multiple single quotes
as in {\tt ``,'',} as necessary.
Commas also may be avoided by writing
{\tt 0.5 between L and T} instead of {\tt 0.5<L,T>.}
\begin{figure}[h!t]
\vspace{-\baselineskip}
   \parbox{4.5in}{\small \verbatiminput{Oblique.m4}}%
   \hfill\raise-0.7in\llap{\hbox{\input Oblique }}%
   \vspace{-\baselineskip}
   \caption{Illustrating elements drawn at oblique angles.}
   \label{Oblique}
   \end{figure}

\subsection{Series and parallel circuits\label{Seriesandparallel:}}

To draw elements in series, each element can be placed by specifying
its line segment as described previously, but the \pic language
makes some geometries particularly simple.  Thus,

{\tt setdir\_(Right)\\ \hspace*{\parindent}%
  resistor; llabel(,R); capacitor; llabel(,C);
  inductor; llabel(,L)}

\noindent
draws three elements in series
as shown in the top line of \FR{Series}.
\begin{figure}[h!t]
\vspace{-\baselineskip}
   \input Series
   \caption{Three ways of drawing basic elements in series.}
   \label{Series}
   \end{figure}
However, the default length {\tt elen\_}
appears too long for some diagrams.  It can be redefined temporarily
(to {\tt dimen\_}, say),
by enclosing the above line in the pair

{\tt pushdef(`elen\_',dimen\_)
 resistor$\ldots$ popdef(`elen\_')}

\noindent
with the result shown in the middle row of the figure.

Alternatively, the length of each element can be tuned individually; for
example, the capacitor in the above example can be shortened as shown,
producing the bottom line of \FR{Series}:

{\tt resistor; llabel(,R)\\
 \hspace*{\parindent}%
  capacitor(right\_ dimen\_/4); llabel(,C)\\
 \hspace*{\parindent}%
  inductor; llabel(,L)}

If a macro that takes care of common cases automatically is to be preferred,
you can use the macro {\tt series\_({\sl elementspec, elementspec, $\ldots$})}.
This macro draws elements of length {\tt dimen\_} from the current
position in the current drawing
direction, enclosed in a {\tt [ ]} block.  The internal names
{\tt Start}, {\tt End}, and {\tt C} (for centre) are defined, along with
any element labels.  An {\sl elementspec} is of the form
{\tt[{\sl Label}:] {\sl element}; [{\sl attributes}]},
where an attribute is zero or more of
 {\tt llabel($\ldots$), rlabel($\ldots$)}, or {\tt b\_current($\ldots$)}.

Drawing elements in parallel requires a little more effort but, for example,
three elements can be drawn in parallel using the code snippet shown,
producing the left circuit in \FR{ParSeries}:
\begin{verbatim}
  define(`elen_',dimen_)
  L: inductor(right_ 2*elen_,W); llabel(+,L,-)
  R1: resistor(right elen_ from L.start+(0,-dimen_)); llabel(,R1)
  R2: resistor; llabel(,R2)
  C: capacitor(right 2*elen_ from R1.start+(0,-dimen_)); llabel(,C)
     line from L.start to C.start
     line from L.end to C.end
\end{verbatim}

\begin{figure}[h!t]
%  \vspace*{-\baselineskip}
   \input ParSeries
   \vspace*{-\baselineskip}
   \caption{Illustrating the macros {\tt parallel\_} and {\tt series\_},
       with {\tt Start} and {\tt End} points marked.}
   \label{ParSeries}
   \end{figure}

A macro that produces the same effect automatically is

{\tt parallel\_({\LQ {\sl elementspec}\RQ, \LQ {\sl elementspec}\RQ,}
 $\ldots$)}

The arguments {\em must be quoted} to delay expansion, unless an argument
is a nested {\tt parallel\_} or {\tt series\_} macro,
in which case it is not quoted.
The elements are drawn in a {\tt [ ]} block with defined points
{\tt Start}, {\tt End}, and {\tt C}.
An {\sl elementspec} is of the form

{\tt [Sep={\sl val};][{\sl Label}:] {\sl element}; [{\sl attributes}]}

\noindent
where an {\sl attribute} is of the form

{\tt [llabel($\ldots$);] | [rlabel($\ldots$)] | [b\_current($\ldots$);]}

Putting {\tt Sep={\sl val};} in the first branch sets the default
separation of all branches to {\sl val}; in a later
element, {\tt Sep={\sl val}}; applies only to that branch.  
An element may have normal arguments but should
not change the drawing direction. 

%\pagebreak%
\xection{Composite circuit elements\label{Composite:}}
Many basic elements are not two-terminal. These elements are usually enclosed in
a \verb|[ ]| \pic block, and contain named interior locations and components.
The block must be placed by using its compass corners, thus:
  {\sl element} {\tt with} {\sl corner} {\tt at} {\sl position} 
or, when the block contains a predefined location, thus:
  {\sl element} {\tt with} {\sl location} {\tt at} {\sl position}.
A few macros are positioned with the first argument;
the {\tt ground} macro, for example:
  {\tt ground(}{\tt at} {\sl position}{\tt ).} 
In some cases, an invisible line can be specified by the first argument
to determine length and direction (but not position) of the block.

Nearly all elements drawn within blocks can be customized by adding an
extra argument, which is executed as the last item within the block.

The macro {\tt
   potentiometer(\linespec,{\sl cycles},{\sl fractional pos},{\sl length},
    $\ldots$)},
shown in \FR{Potentiometers},
first draws a resistor along the specified line, then adds arrows for taps
at fractional positions along the body, with default or specified length.
A negative length draws the arrow from the right of the current drawing
direction.
\begin{figure}[h!t]
   \input Potentiometers
   \caption{Default and multiple-tap potentiometer.}
   \label{Potentiometers}
   \end{figure}

The macro {\tt
    addtaps([{\sl arrowhd} | type={\sl arrowhd};name={\sl Name}],
    {\sl fraction, length, fraction, length,}
    $\ldots$)},
shown in \FR{Taps}, will add taps to the
immediately preceding two-terminal element.
\begin{figure}[h!t]
   \input Taps
   \caption{Macros for adding taps to two-terminal elements.}
   \label{Taps}
   \end{figure}
However, the default names
{\tt Tap1, Tap2} $\ldots$ may not be unique in the current scope.  An
alternative name for the taps can be specified or, if preferable, the
tapped element can be drawn in a [ ] block using the macro {\tt
  tapped(`{\sl two-terminal element}',
  [{\sl arrowhd} | type={\sl arrowhd};name={\sl Name}],
    {\sl fraction, length, fraction, length,} $\ldots$)}.
   Internal names {\tt .Start, .End,} and {.C} are defined automatically,
   corresponding to the drawn element. These and the tap names can be used
   to place the block.
These two macros require the two-terminal element to be drawn either up,
down, to the left, or to the right; they are not designed for obliquely
drawn elements.

A few composite symbols derived from two-terminal elements
are shown in \FR{Composite}.
\begin{figure}[h!t]
   \vspace*{-0.5ex}
   \input Composite
   \vspace*{-0.5ex}
   \caption{Composite elements {\tt KelvinR({\sl cycles},[R],{\sl cycle wid})}
      and {\tt FTcap({\sl chars})} .}
   \label{Composite}
   \end{figure}

The ground symbol is shown in \FR{Grounds}.
The first argument specifies position; for example, the two lines shown
have identical effect:

{\tt move to (1.5,2); ground

ground(at (1.5,2)) }

\noindent The second argument truncates
the stem, and the third defines the symbol type.
The fourth argument specifies the angle at which the symbol is drawn,
with D (down) the default.
This macro is one of several in which a temporary drawing direction
is set using the
 {\tt setdir\_( U|D|L|R|{\sl degrees, default} R|L|U|D|{\sl degrees} )}
macro and reset at the end using {\tt resetdir\_}.
\begin{figure}[ht!]
   \input Grounds
   \caption{The 
     {\tt ground( at }{\sl position}{\tt,
       T, N|F|S|L|P|E, U|D|L|R|{\sl degrees} )}
     macro.}
   \label{Grounds}
   \end{figure}

The arguments of the macro
{\tt antenna( at }{\sl position}{\tt,
  T, A|L|T|S|D|P|F, U|D|L|R|{\sl degrees} )}
shown in \FR{Antennas} are similar to those of {\tt ground}.
\begin{figure}[h!t]
   \input Antennas
   \caption{Antenna symbols, with macro arguments shown above and
     terminal names below.}
   \label{Antennas}
   \end{figure}

\FR{Opamp} illustrates the macro
{\tt opamp({\sl\linespec, - label, + label, size, chars})\label{OPAMP}}.
\begin{figure}[b!t]
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \input Opamp
   \caption{Operational amplifiers.  The {\tt P} option adds
     power connections.  The second and third arguments can be used
     to place and rotate arbitrary text at {\tt In1} and {\tt In2}.}
   \label{Opamp}
   \end{figure}
The element is enclosed in a block
containing the predefined internal locations shown.
These locations can be referenced in later
commands, for example as ``{\tt last [].Out}.''
The first argument defines the direction and length of the opamp, but the
position is determined either by the enclosing block of the opamp,
or by a construction such as ``{\tt opamp with .In1 at Here}'', which places
the internal position {\sl In1} at the specified location.
There are optional second and third arguments for which the defaults
are {\tt \char92{}scriptsize\$-\$} and {\tt \char92{}scriptsize\$+\$}
respectively, and the fourth argument changes the size of the opamp.
The fifth argument is a string of characters.  {\tt P}
adds a power connection, {\tt R} exchanges the second and
third entries, and {\tt T} truncates the opamp point.

Typeset text associated with circuit elements is not rotated by default,
as illustrated by the second and third opamps in \FR{Opamp}.
The {\tt opamp} labels can be rotated if necessary by 
using postprocessor commands (for example \PSTricks \verb|\rput|)
as second and third arguments.

The code in \FR{oax} places an opamp with three connections.
\begin{figure}[h!t]
   \parbox{4in}{\small \verbatiminput{oaxbody.m4}}%
   \quad\raise-0.2in\hbox{\input oax }%
   \vspace{-\baselineskip}
   \caption{A code fragment invoking the
    {\tt opamp(\linespec,-,+,{\sl size},[R][P])} macro.}
   \label{oax}
   \end{figure}

\FR{Xform} shows variants of the transformer macro,
which has predefined internal locations
{\sl P1,} {\sl P2,} {\sl S1,} {\sl S2,} {\sl TP,} and {\sl TS.}
The first argument
specifies the direction and distance from {\sl P1} to {\sl P2}, with
position determined by the enclosing block as for opamps.  The second
argument places the secondary side of the transformer to the left
or right of the drawing direction.  The optional third and fifth arguments
specify the number of primary and secondary arcs respectively.
If the fourth argument string contains an {\tt A}, the iron core
is omitted; 
if a {\tt P}, the core is dashed (powder);
and if it contains a {\tt W}, wide windings are drawn.
A {\tt D1} puts phase dots at the {\sl P1, S1} end, {\tt D2} at the
{\sl P2, S2} ends, and {\tt D12} or {\tt D21} puts dots at opposite ends.
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\fi%
   \input Xform
   \vspace{-\baselineskip}
  \caption{The {\tt transformer(\linespec,L|R,{\sl np},%
[A|P][W|L][D1|D2|D12|D21],{\sl ns})}
     macro (drawing direction {\tt down}), showing predefined terminal
     and centre-tap points.}
   \label{Xform}
   \end{figure}
\iffalse
A transformer with four connections is illustrated
in \FR{tran}.
\begin{figure}[hbt]
   \parbox{4in}{\small \verbatiminput{tranbody.m4}}%
   \quad\raise-0.2in\hbox{\input tran }%
   \vspace{-\baselineskip}
   \caption{Showing the
    {\tt transformer(\linespec,L|R,np,A,ns)} macro.}
   \label{tran}
   \end{figure}
\fi

%\enlargethispage{\baselineskip}
\FR{Audio} shows some audio devices, defined in {\tt []} blocks,
with predefined internal locations as shown.
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\fi%
   \input Audio
   \ifpdf\vspace*{-\baselineskip}\fi%
   \caption{Audio components:
   {\tt speaker(U|D|L|R|{\sl degrees},{\sl size},{\sl type}),
     bell, microphone, buzzer,
     earphone}, with their internally named positions and components.}
   \label{Audio}
   \end{figure}
The first argument specifies the device orientation.

Thus,

{\tt S: speaker(U) with .In2 at Here}

\noindent
%\enlargethispage{\baselineskip}
places an upward-facing speaker with input {\sl In2} at the
current location.

The {\tt nport({\sl box specs {\tt[;} other commands{\tt]},
  nw, nn, ne, ns, space ratio, pin lgth, style})}
macro is shown in \FR{Nport}.
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\fi
   \input Nport
   \ifpdf\vspace*{-\baselineskip}\fi
   \caption{The {\tt nport} macro draws a sequence of pairs of named pins
     on each side of a box.  The pin names are shown.  The default is a twoport.
     The {\tt nterm} macro draws single pins instead of pin pairs.}
   \label{Nport}
   \end{figure}
The macro begins with the line
 \verb|define(`nport',`[Box: box `$1'|,
so the first argument is a box specification such as size, fill,
or text.
The second to fifth arguments specify the number of ports
(pin pairs) to be drawn respectively on the west, north, east, and south
sides of the box.  The end of each pin is named according to the
side, port number, and $a$ or $b$ pin, as shown.
The sixth argument
specifies the ratio of port width to inter-port space, the seventh is
the pin length, and setting the eighth argument to {\tt N} omits the pin
dots.
The macro ends with \verb|`$9']')|, so that a ninth argument can be used
to add further customizations within the enclosing block.

The {\tt nterm({\sl box specs, nw, nn, ne, ns, pin lgth, style})} macro
illustrated in \FR{Nport} is similar to the {\tt nport} macro but
has one fewer argument, draws single pins instead of pin pairs, and
defaults to a 3-terminal box.

Many custom labels or added elements may be required, particularly for
2-ports\label{Nports:}. These elements can be added using the first
argument and the ninth of the {\tt nport} macro.
For example, the following code adds a pair of labels to the box
immediately after drawing it but within the enclosing block:

{\tt nport(; {`"${}0$"'\ at Box.w ljust; `"$\infty$"'\ at
 Box.e rjust})}

If this trick were to be used extensively, then the following custom wrapper
would save typing, add the labels, and pass all arguments to
{\tt nport}:

\begin{verbatim}
define(`nullor',`nport(`$1'
  {`"${}0$"' at Box.w ljust
   `"$\infty$"' at Box.e rjust},shift($@))')
\end{verbatim}

The above example and the related gyrator macro are illustrated in
\FR{NLG}. 
\begin{figure}[h!t]
   \input NLG
   \ifpdf\vspace*{-1.5\baselineskip}\fi%
   \caption{The {\tt nullor} example and the {\tt gyrator}
    macro are customizations of the {\tt nport} macro.}
   \label{NLG}
   \end{figure}

A basic winding macro for magnetic-circuit sketches and similar figures
is shown in \FR{Windings}.
\begin{figure}[h!t]
   \vspace*{-\baselineskip}%
%  \ifpdf\vspace*{-2\baselineskip}\else \vspace{-\baselineskip}\fi
   \input Windings
   \ifpdf\vspace*{-\baselineskip}\else\vspace*{-1ex}\fi
   \caption{The {\tt winding(L|R, diam, pitch, turns, core wid, core color)}
     macro draws a coil with axis along the current drawing direction.
     Terminals {\tt T1} and {\tt T2} are defined.
     Setting the first argument to {\tt R} draws a right-hand winding.}
   \label{Windings}
   \end{figure}
For simplicity, the complete spline
is first drawn and then blanked in appropriate places using the background
(core) color (\verb!lightgray! for example, default \verb!white!).

\FR{Relay} shows the macro {\tt contact({\sl chars})},
which contains predefined locations {\sl P, C, O}
for the armature and normally closed and normally
open terminals.
An {\tt I} in the first argument draws open circles for contacts.
The macro {\tt relay({\sl poles, chars})}
defines coil terminals {\sl V1, V2} and contact
terminals {\sl P$_i$, C$_i$, O$_i$.} 
\begin{figure}[ht]
   \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
   \input Relay
   \vspace{-1ex}
   \caption{The {\tt contact({\sl chars})}
     and {\tt relay({\sl poles, chars})}
     macros (default direction right).}
   \label{Relay}
   \end{figure}

The double-throw switches shown in \FR{NPDT} are drawn in the
current drawing direction like the two-terminal elements, but are
composite elements that must be placed accordingly.
\begin{figure}[h!t]
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \input NPDT
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \caption{Multipole double-throw switches drawn by
    {\tt NPDT({\sl npoles}, [R])}.}
   \label{NPDT}
   \end{figure}

The {\tt jack} and {\tt plug} macros and their defined points are
 illustrated in \FR{Jack}.
\begin{figure}[h!t]
   \input Jack
   \vspace{-1ex}
   \caption{The {\tt jack(U|D|L|R|{\sl degrees}, {\sl chars})}
 and {\tt plug(U|D|L|R|{\sl degrees},[2|3][R])} components
 and their defined points.}
   \label{Jack}
   \end{figure}
 The first argument of both macros
 establishes the drawing direction. The second argument is a string of
 characters defining drawn components.
 An {\tt R} in the string specifies a
 right orientation with respect to the drawing direction.
 The two principal terminals of
 the jack are included by putting \hbox{{\tt L} {\tt S}}
%
% This is a kludge to put a blank line on the bottom
\phantom{or both into the string with associated make ({\tt M})
or break ({\tt B}) points.  Thus, {\tt LMB} within the third}\hfill\break
\phantom{or both into the string with associated make ({\tt M})
or break ({\tt B}) points.  Thus, {\tt LMB} within the third}\hfill\break
%
%
 or both into the string with associated make ({\tt M})
 or break ({\tt B}) points.  Thus, {\tt LMB} within the third
 argument draws the {\tt L} contact with
 associated make and break points. Repeated {\tt L[M|B]}
 or {\tt S[M|B]} substrings add auxiliary contacts with 
 specified make or break points.

%\pagebreak
A macro for drawing headers is in \FR{Headers},
and some experimental connectors are shown in \FR{Conn} and \FR{Pconn}.
The {\tt tstrip} macro allows {\sl key}{\tt =}{\sl value}{\tt ;} arguments
\begin{figure}[h!t]
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \input Headers
   \ifpdf{\vspace*{-0.5ex}}\fi%
   \caption{Macro {\tt Header(1|2, {\sl rows, wid, ht, type})}.}
   \label{Headers}
   \end{figure}
for width and height.
\begin{figure}[h!t]
   \input Conn
   \ifpdf{\vspace*{-0.5ex}}\fi%
   \caption{Macros {\tt tstrip(R|L|U|D|{\sl degrees}, {\sl chars})},
     {\tt ccoax(at} {\sl location}, {\tt M|F, {\sl diameter})},
     {\tt tconn(\linespec, >|>>|<|<<|O[F], {\sl wid})}, and
     {\tt tbox({\sl text, wid, ht}, <|>|<>,{\sl type})}. }
   \label{Conn}
   \ifpdf{\vspace*{-1ex}}\fi%
   \end{figure}
\begin{figure}[h!t]
   \ifpdf{\vspace*{-1ex}}\fi%
   \input Pconn
   \ifpdf{\vspace*{-0.5ex}}\fi%
   \caption{A small set of power connectors drawn by
    {\tt pconnex(R|L|U|D|}{\sl degrees, chars}{\tt)}. Each connector has
    an internal {\tt H}, {\tt N}, and where applicable, a {\tt G} shape.}
   \label{Pconn}
   \end{figure}

\subsection{Semiconductors\label{Semiconductors:}}%
\FR{Bip} shows the variants of bipolar transistor macro
{\tt bi\_tr(\linespec,L|R,P,E)}
which contains predefined internal locations {\sl E},
{\sl B}, {\sl C}.
The first argument defines the distance and direction
from {\sl E} to {\sl C,} with location determined by the enclosing
block as for other elements, and the base placed
\begin{figure}[h!b]
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \input Bip
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \caption{Bipolar transistor variants (current direction upward).}
   \label{Bip}
   \end{figure}
to the left or right of the
current drawing direction according to the second argument.  Setting the third
argument to {\tt P} creates a PNP device instead of NPN, and setting the
fourth to {\tt E} draws an envelope around the device.
\FR{Darlington} shows a composite macro with several optional internal elements.
\begin{figure}[h!t]
   \input Darlington
   \caption{Macro {\tt Darlington(L|R,[E][P][B1][E1|R1][E2|R2][D][Z])},
     drawing direction {\tt up\_}.}
   \label{Darlington}
   \end{figure}

The code fragment example in \FR{bitr} places a bipolar transistor,
connects a ground to the emitter, and connects a resistor to the collector.
\begin{figure}[h!t]
\vspace*{-\baselineskip}
   \quad\quad\parbox{4in}{\small \verbatiminput{bitrbody.m4}}%
   \quad\raise-0.4in\hbox{\input bitr }%
   \vspace{-\baselineskip}
   \caption{The {\tt bi\_tr(\linespec,L|R,P,E)} macro.}
   \label{bitr}
   \end{figure}

The {\tt bi\_tr} and {\tt igbt} macros are wrappers for
the macro {\tt bi\_trans(\linespec, L|R, {\sl chars}, E)}, which
draws the components of the transistor according to the characters in its
third argument.  For example, multiple emitters and collectors can be
specified as shown in \FR{bitrans}.
\begin{figure}[h!t]
\vspace*{-0.5\baselineskip}
   \input bi_trans
   \caption{The {\tt bi\_trans(\linespec,L|R,{\sl chars},E)} macro.
   The sub-elements are specified by the third argument.  The substring
   {\tt E}{\sl n} creates multiple emitters {\sl E0} to {\sl En}.
   Collectors are similar.}
   \label{bitrans}
   \end{figure}

A UJT macro with predefined internal locations {\sl B1,} {\sl B2,}
and {\sl E} is shown in \FR{ujt},
and a thyristor macro with predefined internal locations
 {\sl G} and {\sl T1,} {\sl T2,} or
 {\sl A,} {\sl K} is in \FR{thyristor}.
Except for the {\sl G} terminal, a thyristor (the {\tt IEC} variant excluded)
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
   \input ujt
   \ifpdf\vspace*{-0.5\baselineskip}\fi%
   \caption{UJT devices, with current drawing direction {\tt up\_}. }
   \label{ujt}
   \end{figure}
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\else\vspace*{-0.5\baselineskip}\fi%
   \input thyristor
   \vspace*{-1ex}
   \caption{The top two rows illustrate use of the
    {\tt thyristor({\sl linespec, chars})} macro,
    drawing direction {\tt down\_}, and the bottom row shows wrapper
    macros (drawing direction {\tt right\_}) that place
    the thyristor like a two-terminal element. Append {\tt K}
    to the second argument to draw open arrowheads.}
   \label{thyristor}
   \end{figure}
is much like an two-terminal element.  The wrapper macro
{\tt scr({\sl linespec, chars, label})} and similar macros
{\tt scs, sus,} and {\tt sbs} place thyristors
using {\sl linespec} as for a two-terminal element,
but require a third argument for the label for the compound block; thus,

{\tt scr(from A to B,{,}Q3); line right from Q3.G}

\noindent
draws the element from position {\sl A} to position {\sl B} with label
{\sl Q3}, and draws a line from {\sl G}.

Some FETs with predefined internal locations {\sl S,} {\sl D,} and {\sl G} are
also included, with similar arguments to those of {\tt bi\_tr,} as shown in
\FR{fet}.
In all cases the first argument is a linespec,
and entering
{\tt R} as the second argument orients the {\sl G} terminal to the right of the
current drawing direction.
The macros in the top three rows of the figure are wrappers for the
general macro {\tt mosfet(\linespec,R,{\sl characters},E)}.
The third argument of this macro is a subset of the characters
$\{${\tt BDEFGLMQRSTXZ}$\}$, each letter corresponding to
a diagram component as shown in the bottom row of the figure. 
Preceding the characters {\tt B}, {\tt G}, and {\tt S} by {\tt u} or {\tt d}
adds an up or down arrowhead to the pin, preceding {\tt T} by {\tt d}
negates the pin, and preceding {\tt M} by {\tt u} or {\tt d} puts the pin
at the drain or source end respectively of the gate.
The obsolete letter {\tt L} is equivalent to {\tt dM} and has been kept
temporarily for compatibility.
This system allows considerable freedom in choosing or customizing components,
as illustrated in \FR{fet}.
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\fi%
   \input fet
   \ifpdf\vspace*{-\baselineskip}\fi%
   \caption{JFET, insulated-gate enhancement and depletion MOSFETs,
     and simplified versions.
     These macros are wrappers that invoke the {\tt mosfet}
     macro as shown in the middle and bottom rows.
     The two lower-right examples show custom devices, the first
     defined by omitting the substrate connection, and the second
     defined using a wrapper macro.}
   \label{fet}
   \end{figure}

\pagebreak
The number of possible semiconductor symbols is very
large, so these macros must be regarded as prototypes.
Often an element is a minor modification of existing elements.  For example,
the {\tt thyristor(\linespec, {\sl chars})} macro illustrated in
\FR{thyristor} is derived from the diode and bipolar transistor macros.
Another example is the {\tt tgate} macro shown in \FR{Tgate}, which
also shows a pass transistor.
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\fi%
   \input Tgate
   \caption{The {\tt tgate({\sl linespec,} [B][R|L])} element, derived from
     a customized diode and {\tt ebox}, and the
     {\tt ptrans(\linespec, [R|L])} macro.
     These are not two-terminal elements, so the {\sl linespec} argument
     defines the direction and length of the line from $A$ to $B$ but not
     the element position.}
   \label{Tgate}
   \end{figure}

Some other non-two-terminal macros are {\tt dot}, which has an
optional argument ``{\tt at} {\sl location}'', the line-thickness
macros, the {\tt fill\_} macro, and {\tt crossover}, which is a useful if
archaic method to show non-touching conductor crossovers, as in
\FR{bistable}.
\begin{figure}[h!t]
   \input bistable
   \vspace{-1ex}
   \caption{Bipolar transistor circuit, illustrating {\tt crossover}
      and colored elements.}
   \label{bistable}
   \end{figure}

This figure also illustrates how elements and labels can be colored
using the macro

{\tt rgbdraw({\sl r}, {\sl g}, {\sl b}, {\sl drawing commands})}

\noindent
where the {\sl r, g, b} values are in the range 0 to 1
(integers from 0 to 255 for \SVG)
 to specify the rgb color.
This macro is a wrapper for the following, which may be more convenient
if many elements are to be given the same color:

   {\tt setrgb({\sl r}, {\sl g}, {\sl b})}
      \hfill\break\hspace*{\parindent}%
   {\sl drawing commands}
      \hfill\break\hspace*{\parindent}%
   {\tt resetrgb}

A macro is also provided for colored fills:

{\tt rgbfill({\sl r}, {\sl g}, {\sl b}, {\sl drawing commands})}

\noindent%
These macros depend heavily on the postprocessor and are intended only for 
\PSTricks, \TPGF, \MetaPost, \SVG, and the Postscript or PDF output of \dpic.

\xection{Corners\label{Corners:}}%
If two straight lines meet at an angle then, depending on the postprocessor,
the corner may not be mitred or rounded unless the two lines belong to
a multisegment line, as illustrated in \FR{Corners}.
\begin{figure}[ht]
   \input Corners
   \caption{Producing mitred angles and corners.}
   \label{Corners}
   \end{figure}
This is normally
not an issue for circuit diagrams unless the figure is magnified or thick
lines are drawn.  Rounded corners can be obtained by setting post-processor
parameters, but the figure shows the effect of
macros {\tt round} and {\tt corner}.
The macros
{\tt mitre\_({\sl Position1,Position2,Position3,length,attributes})}
and
{\tt Mitre\_({\sl Line1,Line2,length,attributes})}
may assist as shown.
Otherwise, a right-angle line can be extended
by half the line thickness (macro {\tt hlth}) as shown on the upper row
of the figure,
or a two-segment line can be overlaid at the corner to produce the same effect.

\xection{Looping\label{Looping:}}
Sequential actions can be performed using either the
 \dpic command

{\tt for {\sl variable}={\sl expression} to {\sl expression}
 [by {\sl expression}] do $\lbrace$ {\sl actions} $\rbrace$}

\noindent
or at the
\Mfour processing stage.  The {\tt libgen} library defines the macro

{\tt for\_({\sl start}, {\sl end}, {\sl increment}, `{\sl actions}')}

\noindent
for this and other purposes.  Nested loops are allowed and the innermost loop
index variable is {\tt m4x.}
The first three arguments must be
integers and the {\sl end} value must be reached exactly; for example,
\verb|for_(1,3,2,`print In`'m4x')| prints locations {\sl In1} and {\sl In3},
but \verb|for_(1,4,2,`print In`'m4x')| does not terminate since the
index takes on values 1, 3, 5, $\ldots$.

Repetitive actions can also be performed with the {\tt libgen} macro

{\tt Loopover\_(`{\sl variable}', {\sl actions}, {\sl value1},
 {\sl value2}, $\ldots$)}

\noindent
which evaluates {\sl actions} for each instance of {\sl variable} set
to {\sl value1, value2, $\ldots$}.

\xection{Logic gates\label{Logicgates:}}
\FR{Logic} shows the basic logic gates included in
library {\tt liblog.m4}.
The first argument of the gate macros can be an integer $N$ from $0$ to $16,$
specifying the number of input
locations {\tt In1,} $\ldots$ {\tt In}$N,$ as illustrated for
the NOR gate in the figure.
By default, $N=2$ except for macros {\tt NOT\_gate} and {\tt BUFFER\_gate},
which have one input {\tt In1} unless they are given a
first argument, which is treated as the line specification of a
two-terminal element.
\begin{figure}[h!t]
   \input Logic
   \caption{Basic logic gates.  The input and output locations of
      a three-input NOR gate are shown.  Inputs are negated by
      including an {\tt N} in the second argument letter sequence.  A {\tt B}
      in the second argument produces a box shape as shown in the rightmost
      column, where the second example has AND functionality and
      the bottom two are examples of exclusive OR functions.}
   \label{Logic}
   \end{figure}

Input locations retain their positions relative to the gate body
regardless of gate orientation, as in \FR{FF}.
\begin{figure}[h!t]
   \vspace*{-\baselineskip}
   \parbox{4.75in}{\small \verbatiminput{FF.m4}}%
   \input FF
   \vspace*{-\baselineskip}
   \caption{$SR$ flip-flop.}
   \label{FF}
   \end{figure}
\begin{figure}[h!t]
   \input mplex
   \caption{Eight-input multiplexer, showing a gate with wings.}
   \label{exVIII}
   \end{figure}
Beyond a default number (6) of inputs, the
gates are given wings as in \FR{exVIII}.
\pagebreak
Negated inputs or outputs are marked by circles drawn using the
\verb|NOT_circle| macro.  The name marks the point at the outer edge of the
circle and the circle itself has the same name prefixed by~{\tt N\_}.
For example, the output circle of a nand gate is named
{\tt N\_Out} and the outermost point of the circle is named {\tt Out.}
Instead of a number, the first argument can be a sequence of letters {\tt P}
or {\tt N} to define normal or negated inputs; thus for example,
{\tt NXOR\_gate(NPN)} defines a 3-input nxor gate with not-circle
inputs {\tt In1} and {\tt In3} and normal input {\tt In2}
as shown in the figure.
The macro {\tt IOdefs} can also be used to create a sequence of custom
named inputs or outputs.

Gates are typically not two-terminal elements and are normally drawn
horizontally or vertically (although arbitrary directions may be set
with e.g. {\tt Point\_({\sl degrees})}).
Each gate is contained in a
block of typical height {\tt 6*L\_unit} where {\tt L\_unit} is a macro
intended to establish line separation for an imaginary grid on which
the elements are superimposed.

Including an \verb|N| in the second
argument character sequence of any gate negates the inputs, and including
\verb|B| in the second argument invokes the
general macro {\tt BOX\_gate([P|N]...,[P|N],{\sl horiz size},{\sl
vert size},{\sl label})}, which draws box gates.  Thus, {\tt
BOX\_gate(PNP,N,,8,\char92 geq 1)} creates a gate of default width,
eight {\tt L\_unit}s height, negated output, three inputs with the
second negated, and internal label ``$\geq1$''.
If the fifth argument begins with {\tt sprintf} or a double quote then
the argument is copied literally; otherwise it is treated as scriptsize
mathematics.

The macro {\tt BUFFER\_gate(\linespec,[N|B],{\sl wid},{\sl ht},%
 [N|P]\char42,[N|P]\char42)}
is a wrapper for the composite element {\tt BUFFER\_gen}.
If the second argument is {\tt B}, then a box gate is drawn; otherwise
the gate is triangular.  Arguments 5 and 6 determine the number of defined
points along the northeast and southeast edges respectively, with an {\tt N}
adding a NOT circle.
If the first argument is non-blank however, then the buffer is drawn along
an invisible line like a two-terminal element, which is convenient sometimes
but requires internal locations of the block to be referenced using
{\tt last []}, as shown in \FR{Buffer}.
\begin{figure}[h!t]
   \input Buffer
   \caption{The {\tt BUFFER\_gate} and {\tt BUFFER\_gen} macros.
     The bottom two examples show how the gate can be drawn as a two-terminal
     macro but internal block locations must be referenced using
     {\tt last []}.}
   \label{Buffer}
   \end{figure}

\pagebreak
A good strategy for drawing complex logic circuits might be summarized
as follows:
\begin{itemize}\itemsep=0pt
\item Establish the absolute locations of gates and other major components
  (e.g. chips) relative to a grid of mesh size commensurate with
  {\tt L\_unit}, which is an absolute length.
\item Draw minor components or blocks relative to the major ones, using
   parameterized relative distances.
\item Draw connecting lines relative to the components and previously drawn
   lines.
\item Write macros for repeated objects.
\item Tune the diagram by making absolute locations relative, and by tuning
   the parameters.
   Some useful macros for this are the following, which are in units of
  {\tt L\_unit}:
   \begin{itemize}
   \item[] {\tt AND\_ht, AND\_wd}: the height and width of basic AND and
     OR gates
   \item[] {\tt BUF\_ht, BUF\_wd}: the height and width of basic buffers
   \item[] {\tt N\_diam}: the diameter of NOT circles
   \end{itemize}
   \end{itemize}

\FR{Multiplexer} shows a multiplexer block with variations, and
 \FR{Demultiplexer} shows
the very similar demultiplexer.
\begin{figure}[h!t]
   \input Multiplexer
   \caption{The {\tt Mux({\sl input count}, {\sl label}, 
      [L][B|H|X][N[$n$]|S[$n$]][[N]OE],{\sl wid},{\sl ht})} macro.}
   \label{Multiplexer}
   \end{figure}
\begin{figure}[h!t]
   \input Demultiplexer
   \caption{The {\tt Demux({\sl input count}, {\sl label}, 
      [L][B|H|X][N[$n$]|S[$n$]][[N]OE],{\sl wid},{\sl ht})} macro.}
   \label{Demultiplexer}
   \end{figure}

\FR{FlipFlops} shows
the macro {\tt FlipFlop(D|T|RS|JK, {\sl label, boxspec})}, which is a
wrapper for the more general macro {\tt FlipFlopX(}{\sl boxspec, label,
leftpins, toppins, rightpins, bottompins}{\tt )}.
\begin{figure}[h!t]
   \input FlipFlop
   \caption{The {\tt FlipFlop} and {\tt FlipFlopX} macros, with variations.}
   \label{FlipFlops}
   \end{figure}
Each of arguments 3 to 6 is null or a string of {\sl pinspecs} separated
by semicolons ({\tt;}).  {\sl Pinspecs} are either empty (null) or of the form
{\tt[}{\sl pinopts}{\tt]:[}{\sl label}{\tt[:}{\sl Picname}{\tt]]}.
The first colon draws the pin.
Pins are placed top to bottom or left to right along the box edges with
null pinspecs counted for placement. Pins are named by side and number
by default; eg {\tt W1, W2, ..., N1, N2, ..., E1, ..., S1, ...} ; however,
if {\tt:}{\sl Picname} is present in a {\sl pinspec} then {\sl Picname}
replaces the default name. A {\sl pinspec} label is text placed at the pin
base. Semicolons are
not allowed in labels; use eg \verb|\char59{}| instead, and to put a bar over
a label, use {\tt lg\_bartxt(}{\sl label}{\tt)}.
The {\sl pinopts} are {\tt [L|M|I|O][N][E]} as for the \verb|lg_pin| macro.

Customized gates can be defined simply.
For example, the following code defines the custom flipflops in \FR{ShiftR}.
\begin{figure}[h!t]
   \input ShiftR
   \caption{A 5-bit shift register.}
   \label{ShiftR}
   \end{figure}
\begin{verbatim}
define(`customFF',`FlipFlopX(wid 10*L_unit ht FF_ht*L_unit,,
    :S;NE:CK;:R, N:PR, :Q;;ifelse(`$1',1,:lg_bartxt(Q)), N:CLR) ')
\end{verbatim}
This definition makes use of macros \verb|L_unit| and
\verb|FF_ht| that predefine dimensions.
There are three pins on the right side; the centre pin is null and
the bottom is null if the first macro argument is 1.

For hybrid applications, the \verb|dac| and \verb|adc| macros are
illustrated in \FR{Dac}.
The figure shows the default and predefined internal locations, the number
of which can be specified as macro arguments.
\begin{figure}[h!t]
   \ifpdf\vspace*{-\baselineskip}\fi%
   \input Dac
   \ifpdf\vspace*{-\baselineskip}\fi%
   \caption{The {\tt dac({\sl width,height},nIn,nN,nOut,nS)}
   and {\tt adc({\sl width,height},nIn,nN,nOut,nS)} macros.}
   \label{Dac}
   \end{figure}

In addition to the logic gates described here, some experimental
IC chip diagrams are included with the distributed example files.

\pagebreak
\xection{Element and diagram scaling\label{Scaling:}}

There are several issues related to scale changes.  You may wish to use
millimetres, for example, instead of the default inches.  You may wish
to change the size of a complete diagram while keeping the relative
proportions of objects within it.  You may wish to change the sizes or
proportions of individual elements within a diagram.  You must take
into account that line widths are scaled separately from drawn objects,
and that the size of typeset text is independent of the \pic language.

The scaling of circuit elements will be described first, then
the \pic scaling facilities.

\subsection{Circuit scaling\label{Circuitscaling:}}
The circuit elements all have default dimensions
that are multiples of the \pic environmental parameter {\tt linewid,}
so changing this parameter changes default element dimensions.
The scope of a \pic variable is the current block; therefore, a sequence
such as

\begin{verbatim}
  resistor
T: [linewid = linewid*1.5; up_; Q: bi_tr] with .Q.B at Here
  ground(at T.Q.E)
  resistor(up_ dimen_ from T.Q.C)
\end{verbatim}

\noindent%
connects two resistors and a ground to an enlarged transistor.
Alternatively, you may redefine the default length {\tt elen\_}
or the body-size parameter {\tt dimen\_.}  For example, adding the line

{\tt define(`dimen\_',(dimen\_*1.2))}

\noindent%
after the {\tt cct\_init} line of {\tt quick.m4} produces slightly
larger body sizes for all circuit elements.  For logic elements, the
equivalent to the {\tt dimen\_} macro is {\tt L\_unit}, which has
default value {\tt (linewid/10)}.

The macros {\tt capacitor, inductor,} and {\tt resistor} have arguments
that allow the body sizes to be adjusted individually.  The macro
{\tt resized} mentioned previously can also be used.

\subsection{Pic scaling\label{Picscaling:}}
There are at least three kinds of graphical elements to be considered:
\begin{enumerate}
\item When generating final output after reading the {\tt.PE} line,
  \pic processors divide distances and sizes by the value of the
  environmental parameter {\tt scale}, which is 1 by default.  Therefore,
  the effect of assigning a value to {\tt scale} at the beginning of the
  diagram is to change the drawing unit (initially 1 inch) throughout
  the figure.  For example, the file {\tt quick.m4} can be modified to
  use millimetres as follows:
  \begin{verbatim}
  .PS                            # Pic input begins with .PS
  scale = 25.4                   # mm
  cct_init                       # Set defaults

  elen = 19                      # Variables are allowed
  ...
  \end{verbatim}
\vspace*{-1.5\baselineskip}
  The default sizes of \pic objects
  are redefined by assigning new values to the environmental parameters
  {\tt arcrad,} {\tt arrowht,} {\tt arrowwid,} {\tt boxht,} {\tt boxrad,}
  {\tt boxwid,} {\tt circlerad,} {\tt dashwid,} {\tt ellipseht,}
  {\tt ellipsewid,} {\tt lineht,} {\tt linewid,} {\tt moveht,}
  {\tt movewid,}
  {\tt textht,} and {\tt textwid.}
  The $\ldots${\tt ht} and $\ldots${\tt wid} parameters refer to the
  default sizes of vertical and horizontal lines, moves, etc., except for
  {\tt arrowht} and {\tt arrowwid}, which are arrowhead dimensions.
  The {\tt boxrad} parameter can be used to put rounded corners on boxes.
  Assigning a new value to {\tt scale} also multiplies all of these 
  parameters except {\tt arrowht,} {\tt arrowwid,} {\tt textht,} and
  {\tt textwid} by the new value of {\tt scale} (\gpic multiplies them all).
  Therefore, objects drawn to default sizes are unaffected by changing
  {\tt scale} at the beginning of the diagram.
  To change default sizes, redefine the appropriate parameters explicitly.

\item The {\tt .PS} line can be used to scale the entire drawing, regardless
  of its interior.  Thus, for example, the line {\tt.PS 100/25.4}
  scales the entire drawing to a width of 100$\,$mm.
  Line thickness, text size, and \dpic arrowheads are unaffected by
  this scaling.

  If the final picture width exceeds {\tt maxpswid}, which
  has a default value of 8.5, then the picture is scaled to this size.
  Similarly, if the height exceeds {\tt maxpsht} (default 11), then the
  picture is scaled to fit.  These parameters can be assigned
  new values as necessary, for example, to accommodate landscape figures.

\item The finished size of typeset text is independent of \pic variables,
  but can be determined as in \SR{Interaction:}.  Then,
  {\tt "text" wid $x$ ht $y$} tells \pic the size of {\tt text},
  once the printed width $x$ and height $y$ have been found.

\item Line widths are independent of diagram and text scaling, and have
  to be set explicitly.  For example,
  the assignment {\tt linethick = 1.2} sets the default line width to 1.2\,pt.
  The macro {\tt linethick\_({\sl points})} is also provided, together
  with default macros {\tt thicklines\_} and {\tt thinlines\_}.

\end{enumerate}

\xection{Writing macros\label{Writing:}}
The \Mfour language is quite simple and is
described in numerous documents such as the original reference~\cite{KRm4}
or in later manuals~\cite{Seindal94}.  If a new circuit
or other element is required, then it may suffice to modify and rename one of
the library definitions or simply add an option to it.
Hints for drawing general two-terminal elements are given in
{\tt libcct.m4}.  However, if an element or block is to be drawn in
only one orientation then most of the elaborations used for general
two-terminal elements in \SR{Basictwo:} can be dropped.
If you develop a library of custom macros in the installation
directory then the statement {\tt include(}{\sl mylibrary}{\tt.m4)}
can bring its definitions into play.

It may not be necessary to define your own macro if all that is needed is
a small addition to an existing element that is defined in an enclosing
\verb|[ ]| block.  After the element arguments are expanded,
one argument beyond the normal list is automatically expanded before
exiting the block, as mentioned near the beginning of \SR{Composite:}.
This extra argument can be used to embellish the element.  

A macro is defined using quoted name and replacement text as follows:

{\tt define(`}{\sl name}{\tt',`}{\sl replacement text}{\tt ')}

After this line is read by the \Mfour processor, then whenever {\sl name}
is encountered as a separate string, it is replaced by its replacement
text, which may have multiple lines.  The quotation characters are used
to defer macro expansion.  Macro arguments are referenced inside a
macro by number; thus {\tt \$1} refers to the first argument.
A few examples will be given.

%\enlargethispage{\baselineskip}
%\noindent\hbox{}\\ {\bf Example 1:}
%\par\noindent {\bf Example 1:}
\Example{1}
Custom two-terminal elements can often be defined by writing a wrapper
for an existing element.  For example, an enclosed thermal switch
can be defined as shown in \FR{Thermal}.
\begin{figure}[h!]
   \parbox{4.2in}{\tt define(`thermalsw',\hfill\break
   \hbox{}\space`dswitch(`\$1',`\$2',WDdBT)\hfill\break
   \hbox{}\space\space circle rad distance(M4T,last line.c)
     at last line.c ') }%
   \hfill\raise-0.15in\hbox{\input Thermal }
   \caption{A custom thermal switch defined from the {\tt dswitch} macro.}
   \label{Thermal}
   \end{figure}

%\par\noindent {\bf Example 2:}
\Example{2}
In the following,
two macros are defined to simplify the repeated drawing
of a series resistor and series inductor, and the macro {\tt tsection} defines
a subcircuit that is replicated several times to generate \FR{Tline}.
{\small \verbatiminput{Tline.m4}}
\begin{figure}[h!]
   \ifpdf\vspace*{-\baselineskip}\fi%
   \input Tline
   \caption{A lumped model of a transmission line, illustrating the
    use of custom macros.}
   \label{Tline}
   \end{figure}

\Example{3}
%\par\noindent {\bf Example 3:}
Composite elements containing several basic elements may be
required.  \FR{HybridPi} shows a circuit that can be drawn in
any reference direction prespecified by {\tt Point\_({\sl degrees})},
containing labels that always appear in their natural horizontal orientation.
\begin{figure}[h!t]
   \vspace*{-0.5ex}
   \input HybridPi
   \vspace*{-0.5ex}
   \caption{A composite element containing several basic elements}
   \label{HybridPi}
   \end{figure}
Two flags in the argument determine the circuit orientation with respect to
the current drawing direction and whether a mirrored circuit is drawn.  
The key to writing such a macro is to observe that the \pic language
allows two-terminal elements to change the current drawing direction,
so the value of {\tt rp\_ang} should be saved and restored as necessary
after each internal two-terminal element has been drawn.
A draft of such a macro follows:
\begin{verbatim}
#                               `Point_(degrees)
#                                hybrid_PI_BJT([L][M])
#                                L=left orientation; M=mirror'
define(`hybrid_PI_BJT',
`[                              # Size (and direction) parameters:
   hunit = ifinstr(`$1',M,-)dimen_
   vunit = ifinstr(`$1',L,-)dimen_*3/2
   hp_ang = rp_ang              # Save the reference direction

 Rpi: resistor(to rvec_(0,-vunit)); point_(hp_ang)    # Restore direction
 DotG: dot(at rvec_(hunit*5/4,0))
 Gm: consource(to rvec_(0,vunit),I,R); point_(hp_ang) # Restore direction
   dot(at rvec_(hunit*3/4,0))
 Ro: resistor(to rvec_(0,-vunit)); point_(hp_ang)     # Restore direction
   line from Rpi.start to Rpi.start+vec_(-hunit/2,0) chop -lthick/2 chop 0
 Base: dot(,,1)
   line from Gm.end to Ro.start+vec_(hunit/2,0) chop -lthick/2 chop 0
 Collector: dot(,,1)
   line from Rpi.end to Ro.end chop -lthick/2
 DotE: dot(at 0.5 between Rpi.end and DotG)
   line to rvec_(0,-vunit/2)
 Emitter: dot(,,1)
                                # Labels
 `"$\mathrm{r_\pi}$"' at Rpi.c+vec_(hunit/4,0)
 `"$ + $"' at Rpi.c+vec_(-hunit/6, vunit/4)
 `"$ - $"' at Rpi.c+vec_(-hunit/6,-vunit/4)
 `"$\mathrm{v_\pi}$"' at Rpi.c+vec_(-hunit/4,0)
 `"$\mathrm{g_m}$$\mathrm{v_\pi}$"' at Gm.c+vec_(-hunit*3/8,-vunit/4)
 `"$\mathrm{r_o}$"' at Ro.c+vec_(hunit/4,0)
 `$2' ] ')
\end{verbatim}

\pagebreak
\Example{4}
%\par\noindent {\bf Example 4:}
A number of elements have arguments meant explicitly for customization.
\FR{Sinus} customizes the {\tt source} macro to show a cycle of a horizontal
sinusoid with adjustable phase given by argument 2 in degrees,
as might be wanted for a 3-phase circuit:
\begin{figure}[ht]
\hfill\input Sinus
 \vspace*{-0.5in}
\begin{verbatim}
define(`phsource',`source($1,
#`Set angle to 0, draw sinusoid, restore angle'
 m4smp_ang = rp_ang; rp_ang = 0
 sinusoid(m4h/2,twopi_/(m4h),
  ifelse(`$2',,,`($2)/360*twopi_+')pi_/2,-m4h/2,m4h/2) with .Origin at Here
 rp_ang = m4smp_ang,
$3,$4,$5)')
\end{verbatim}
\vspace*{-\baselineskip}
   \caption{A source element customized using its second argument.}
   \label{Sinus}
   \end{figure}

\Example{5}
%\par\noindent {\bf Example 5:}
Repeated subcircuits might have different orientations
% but the potential orientations often
that
include only the element and its mirror image, for example, so the
power of the \verb|vec_()| and \verb|rvec_()| macros is not required.
Suppose that an optoisolator is to be drawn with left-right or right-left
orientation as shown in \FR{Opto}.
%\vspace*{-0.5em}
\begin{figure}[h!t]
   \input Opto
   \caption{Showing {\tt opto} and {\tt opto(BR)} with defined labels.}
   \label{Opto}
   \end{figure}

The macro interface could be something like the following:

{\tt opto( [L|R][A|B] )},

\noindent where an {\tt R} in the argument string signifies a right-left
(mirrored) orientation and the element is of either {\tt A} or {\tt B} type;
that is, there are two related elements that might be drawn in either
orientation, for a total of four possibilities.
Those who find such an interface to be too cryptic might prefer to
invoke the macro as

{\tt opto(orientation=Rightleft;type=B)},

\noindent
which includes semantic sugar surrounding the {\tt R} and {\tt B} characters
for readability; this usage is made possible by testing the argument string
using the {\tt ifinstr()} macro rather than requiring an exact match.
A draft of the macro follows, and the file {\tt Optoiso.m4} in the examples
directory adds a third type option.
\begin{verbatim}
#                           `opto([R|L][A|B])'
define(`opto',`[{u = dimen_/2
 Q: bi_trans(up u*2,ifinstr(`$1',R,R),ifinstr(`$1',B,B)CBUdE)
 E: Q.E; C: Q.C; A:ifinstr(`$1',R,Q.e+(u*3/2,u),Q.w+(-u*3/2,u)); K: A-(0,u*2)
   ifinstr(`$1',B,line from Q.B to (Q.B,E); B: Here)
 D: diode(from A to K)
   arrow from D.c+(0,u/6) to Q.ifinstr(`$1',R,e,w)+(0,u/6) chop u/3 chop u/4
   arrow from last arrow.start-(0,u/3) to last arrow.end-(0,u/3)
 Enc: box rad u wid abs(C.x-A.x)+u*2 ht u*2 with .c at 0.5 between C and K
  `$2' }]')
\end{verbatim}
Two instances of this subcircuit are
drawn and placed by the following code, with the result
shown in \FR{Opto}.
\begin{verbatim}
Q1: opto
Q2: opto(type=B;orientation=Rightleft) with .w at Q1.e+(dimen_,0)
\end{verbatim}


\iffalse
\noindent {\bf Example 4:}
Repeated subcircuits might have different orientations.
Suppose that a simple opamp subcircuit might have to be drawn in any direction.
The subcircuit will be placed in a {\tt [} {\tt ]} block, with
internal points {\sl In}, {\sl Out}, and {\sl G}. 
The macro interface could be something like the following:

{\tt fbfilter( U|D|L|R|{\sl degrees}, [L|R], {\sl opamp label},
  {\sl C label}, {\sl R label} )}

\noindent The first argument specifies the drawing direction as for the
{\tt antenna} macro, for example.  Setting the second argument to {\tt
R} specifies right orientation with respect to the drawing direction,
and the last three arguments are labels
for three internal elements.  Two instances of this subcircuit are
drawn and placed by the following code, with the result
shown in \FR{fbfilter}.
\begin{verbatim}
F1: fbfilter(,,K_3,C_{24},R_4)
  ground(at F1.G)
  dot(at F1.In); line up_ elen_/4
F2: fbfilter(L,R,K_2,C_{23},R_3) with .In at F1.In
  ground(at F2.G)
\end{verbatim}
\vspace*{-0.5em}
\begin{figure}[h!t]
   \input fbfilter
   \caption{Showing the result of two invocations of the {\tt fbfilter} macro,
     with labels.}
   \label{fbfilter}
   \end{figure}
A draft macro for the subcircuit follows:
\begin{verbatim}
define(`fbfilter',
`[ setdir_(ifelse(`$1',,0,`$1'))    # Process arg 1, default to the right
   eleminit_                        # Assign rp_ang, rp_len
   tmpang = rp_ang                  # Save rp_ang 
   hunit = elen_                    # Dimension parameters
   vunit = ifinstr(`$2',R,-)elen_/2
 K: opamp(,,,,`$2')
   move to K.In`'ifinstr(`$2',R,2,1); line to rvec_(-hunit/4,0)
 J: dot
 R: resistor(to rvec_(-elen_,0)); point_(tmpang) # Reset rp_ang
 In: Here
   move to K.In`'ifinstr(`$2',R,1,2); line to rvec_(-hunit/4,0)
 G: Here
   dot(at K.Out)
   { line to rvec_(hunit/4,0)
 Out: Here } 
   line to rvec_(0,vunit)
 C: capacitor(to rvec_(-distance(K.Out,0.5 between J and G),0)); point_(tmpang)
   line to J
   ifelse(`$3',,,"$`$3'$" at K.C)   # Add the labels if non-blank.
   ifelse(`$4',,,"$`$4'$" at C+vec_(0,-vunit/3))
   ifelse(`$5',,,"$`$5'$" at R+vec_(0,-vunit/4))
   resetdir_
   ]')
\end{verbatim}
The drawing direction is unknown when the macro is defined, so the
macros {\tt vec\_} and {\tt rvec\_} are used for drawing lines and
elements.
Thus, {\tt (vec\_({\sl x,y}))} is position {\tt ({\sl x,y})} rotated
by angle {\tt rp\_ang}.
A side effect of drawing a two-terminal element is to change the
drawing direction (in conformity with the \pic language), so the angle must
be saved and reset as needed. Normally, the {\tt fbfilter} block will be
placed by specifying the position of one of its defined points; by
default it will be placed as if it were a box.
\fi

\xection{Interaction with \latex\label{Interaction:}}
The sizes of typeset labels and other \tex boxes are generally unknown
prior to processing the diagram by \latex.
Although they are not needed for many circuit diagrams,
these sizes may be required explicitly for calculations or implicitly
for determining the diagram bounding box.  
The following example shows how text sizes can affect the overall size of
a diagram:

\begin{verbatim}
.PS
B: box
  "Left text" at B.w rjust
  "Right text: $x^2$" at B.e ljust
.PE
\end{verbatim}

The \pic interpreter cannot know the size of the text to the left
and right of the box, and the diagram is generated using
default text values.  One solution to this problem is to measure the
text sizes by hand and include them literally, thus:\hfill\break
\hbox{}\quad%
\verb|"Left text" wid 38.47pt__ ht 7pt__ at B.w rjust|\hfill\break
but this is tedious.

Often, a better solution is to process the diagram twice.  The
diagram source is processed as usual by \Mfour and a \pic processor, and the
main document source is \latex{}ed to input the diagram and format the
text, and also to write the text dimensions into a supplementary file.
Then the diagram source is processed again, reading the required
dimensions from the supplementary file and producing a diagram ready
for final \latex{}ing.  This hackery is summarized below, with an example
in \FR{stringdim}.
\begin{itemize}
\item Put \verb|\usepackage{boxdims}| into the document source.
\item Insert the following at the beginning of the diagram source,
 where {\sl jobname} is the name of the main \latex file:\hfill\break
 \quad{\tt sinclude({\sl jobname}.dim)\hfill\break
 \quad s\_init({\sl unique name})}
\item Use the macro {\tt s\_box({\sl text})} to produce
 typeset text of known size, or alternatively, invoke the macros
 \verb|\boxdims| and \verb|boxdim| described later.
 The argument of {\tt s\_box} need not be text exclusively; it can
 be anything that produces a \TeX\ box.
\end{itemize}
\begin{figure}[h!t]
   \parbox{3.5in}{\small\tt.PS\\
     gen\_init\\
     sinclude(Circuit\_macros.dim)\\
     s\_init(stringdims)\\
     B: box\\
       \hbox{}\quad s\_box(Left text) at B.w rjust\\
       \hbox{}\quad s\_box(Right text: \$x\^{}{\%g}\$,2) at B.e ljust\\
     .PE}%
   \hfill\llap{\raise-0.25in\hbox{\input stringdims }}%
   \caption{The macro {\tt s\_box} sets string dimensions automatically
    when processed twice.  If two or more arguments are
    given to {\tt s\_box}, they
    are passed through {\tt sprintf}.  The dots show the figure bounding box.}
   \label{stringdim}
   \end{figure}

\noindent The macro \verb|s_box(|{\sl text}\verb|)| evaluates initially to

 \verb|"\boxdims{|{\sl name}\verb|}{|{\sl text}\verb|}"|
  \verb|wid boxdim(|{\sl name}\verb|,w) ht boxdim(|{\sl name}\verb|,v)|

\noindent
On the second pass, this is equivalent to

 {\tt "{\sl text}" wid {\sl x} ht {\sl y}}

 \noindent
 where {\sl x} and {\sl y} are the typeset dimensions of the
 \latex input text.  If {\tt s\_box} is given two or more arguments
 as in \FR{stringdim}
 then they are processed by {\tt sprintf}.

The argument of {\tt s\_init}, which should be unique within {\tt{\sl
jobname}.dim}, is used to generate a unique \verb|\boxdims| first
argument for each invocation of \verb|s_box| in the current file.  If
\verb|s_init| has been omitted, the symbols ``{\bf !!}'' are inserted
into the text as a warning.  Be sure to quote any commas in the
arguments.  Since the first argument of {\tt s\_box} is \latex source,
make a rule of quoting it to avoid comma and name-clash problems.  For
convenience, the macros {\tt s\_ht}, {\tt s\_wd}, and {\tt s\_dp}
evaluate to the dimensions of the most recent {\tt s\_box} string or to
the dimensions of their argument names, if present.

The file \verb|boxdims.sty| distributed with this package should be installed
where \latex can find it.
The essential idea is to define a two-argument \latex macro
\verb|\boxdims| that writes out definitions for the width, height and
depth of its typeset second argument into file {\sl jobname.}\verb|dim|,
where {\sl jobname} is the name of the main source file.
The first argument of \verb|\boxdims| is used to construct unique symbolic
names for these dimensions. 
Thus, the line

{\tt box \verb|"\boxdims{Q}{\Huge Hi there!}"| }

\noindent has the same effect as

{\tt box \verb|"\Huge Hi there!"|}

\noindent except that the line

{\tt define(`Q\_w',77.6077pt\_\_)define(`Q\_h',17.27779pt\_\_)%
define(`Q\_d',0.0pt\_\_)dnl}

\noindent is written into file {\sl jobname.}\verb|dim|
(and the numerical values depend on the current font).
These definitions are required by the \verb|boxdim| macro
described below.

The \latex macro

\verb|\boxdimfile{|{\sl dimension file}\verb|}|

\noindent is used to specify an alternative to {\sl jobname.}\verb|dim| as the
dimension file to be written.  This simplifies cases where {\sl jobname}
is not known in advance or where an absolute path name is required.

Another simplification is available.  Instead of the
{\tt sinclude({\sl dimension file})} line
above, the dimension file can be read by \Mfour before reprocessing the source
for the second time:

{\tt m4 {\sl library files} {\sl dimension file} {\sl diagram source file} ...} 

Here is a second small example.  Suppose that the file {\tt tsbox.m4} contains
the following:
\begin{verbatim}
\documentclass{article}
\usepackage{boxdims,ifpstricks(pstricks,tikz)}
\begin{document}
.PS
cct_init s_init(unique) sinclude(tsbox.dim)
[ source(up_,AC); llabel(,s_box(AC supply)) ]; showbox_
.PE
\end{document}
\end{verbatim}
The file is processed twice as follows:

{\tt m4 pgf.m4 tsbox.m4 | dpic -g > tsbox.tex; pdflatex tsbox}
\par
{\tt m4 pgf.m4 tsbox.m4 | dpic -g > tsbox.tex; pdflatex tsbox}

\noindent
The first command line produces a file {\tt tsbox.pdf} with
incorrect bounding box.  The second command reads the data in {\tt tsbox.dim}
to size the label correctly.  The equivalent pstricks commands (note
the {\tt ifpstricks} macro in the second source line) are

{\tt m4 pstricks.m4 tsbox.m4 | dpic -p > tsbox.tex; latex tsbox}
\par
{\tt m4 pstricks.m4 tsbox.m4 | dpic -p > tsbox.tex; latex tsbox; dvips tsbox}
 
\hbox{}

Objects can be taylored to their attached text by invoking
\verb|\boxdims| and \verb|boxdim| explicitly.
The small source file in \FR{boxdims}, for example,
produces the box in the figure.
%\vspace*{-\baselineskip}%
\begin{figure}[h!t]
   \parbox{4.2in}{\small \input eboxdims.verb }%
   \hfill\llap{\raise-0.35in\hbox{\input eboxdims }}%
   \vspace{-\baselineskip}
   \caption{Fitting a box to typeset text.}
   \label{boxdims}
   \end{figure}

The figure is processed twice, as described previously.
The line \verb|sinclude(|{\sl jobname}\verb|.dim)| reads the named file
if it exists.  The macro \verb|boxdim(|{\sl
name,suffix,default}\verb|)| from {\tt libgen.m4} expands the
expression \verb|boxdim(Q,w)| to the value of \verb|Q_w| if it is
defined, else to its third argument if defined, else to 0, the latter
two cases applying if {\sl jobname.}\verb|dim| doesn't exist yet.  The
values of \verb|boxdim(Q,h)| and \verb|boxdim(Q,d)| are similarly
defined and, for convenience, \verb|boxdim(Q,v)| evaluates to the sum
of these.  Macro \verb|pt__| is defined as \verb|*scale/72.27| in {\tt
libgen.m4}, to convert points to drawing coordinates.

Sometimes a label needs a plain background in order to blank
out previously drawn components overlapped by the label,
as shown on the left of \FR{fbox}.
The technique illustrated in \FR{boxdims} is automated by the
macro
{\tt f\_box(}{\sl boxspecs}, {\sl label arguments}{\tt )}.
For the special case of only one argument,
e.g., {\tt f\_box(Wood chips),} this macro
simply overwrites the label on a white box of identical size.
Otherwise, the first argument specifies the box characteristics
(except for size), and the macro evaluates to

{\tt box }{\sl boxspecs} {\tt s\_box(}{\sl label arguments}{\tt)}.
 
\noindent%
For example, the result of the following command
is shown on the right of \FR{fbox}.

\verb|f_box(color "lightgray" thickness 2 rad 2pt__,"\huge$n^{%g}$",4-1)|
\begin{figure}[h!b]
%\begin{figure}[b!]
   \input woodchips
   \vspace{-0.5\baselineskip}
   \caption{Illustrating the {\tt f\_box} macro.}
   \label{fbox}
   \end{figure}

More tricks can be played.  The example

\verb|Picture: s_box(`\includegraphics{|{\it file}\verb|.eps}') with .sw at|
{\sl location}

\noindent shows a nice way of including eps graphics in a diagram.  The
included picture (named {\tt Picture} in the example) has known position and
dimensions, which can be used to add vector graphics or text to the
picture.  To aid in overlaying objects, the macro {\tt boxcoord(}{\sl
object name, x-fraction, y-fraction}{\tt)} evaluates to a position,
with {\tt boxcoord(}{\sl object name}{\tt,0,0)} at the lower left
corner of the object, and {\tt boxcoord(}{\sl object name}{\tt,1,1)} at
its upper right.

\xection{\PSTricks and other tricks\label{Pstricks:}}
This section applies only to a \pic processor (\dpic) that is
capable of producing output compatible with
\PSTricks, \TPGF, or in principle, other graphics postprocessors. 

By using {\tt command} lines,
or simply by inserting \latex graphics directives along with strings to
be formatted, one can mix
arbitrary \PSTricks (or other) commands with \Mfour input
to create complicated effects. 

Some commonly required effects are particularly simple. For example,
the rotation of text by \PSTricks postprocessing is illustrated by the file

{\small \verbatiminput{Axes.m4}}

\noindent%
which contains both horizontal text and text rotated $90^\circ$ along the
vertical line.
This rotation of text is also implemented by the macro
{\tt rs\_box}, which is similar
to {\tt s\_box} but rotates its text argument by $90^\circ,$ a default angle
that can be changed by preceding invocation with
\verb|define(`text_ang',|{\sl degrees}{\tt )}.  The {\tt rs\_box} macro
requires either \PSTricks or \TPGF and, like {\tt s\_box}, it calculates the
size of the resulting text box but requires the diagram to be
processed twice.

Another common requirement is the filling of arbitrary shapes, as
illustrated by the following lines within a {\tt .m4} file:

\vspace{\parsep}
\noindent%
\verb|command "`\pscustom[fillstyle=solid,fillcolor=lightgray]{'"|
\hfill\break
{\sl drawing commands for an arbitrary closed curve}
\hfill\break
\verb|command "`}%'"|
\vspace{\parsep}

For colour printing or viewing, arbitrary
colours can be chosen, as described in the \PSTricks manual.
\PSTricks parameters can be set by inserting the line

\vspace{\parsep}
\noindent\verb|command "`\psset{|{\sl option=value,}$\;\ldots$\verb|}'"|
\vspace{\parsep}

\noindent%
in the drawing commands or by using the macro
{\tt psset\_(}{\sl PSTricks options}{\tt )}.

The macros
 {\tt shade(}{\sl gray value},{\sl closed line specs}{\tt )}
and
 {\tt rgbfill(}{\sl red value, green value, blue value, closed line specs}%
 {\tt )}
can be invoked to accomplish the same effect as the above fill example, but
are not confined to use only with \PSTricks.

Since arbitrary \latex can be output, either in ordinary strings or by
use of {\tt command} output, complex examples such as found in
reference~\cite{Girou94},
for example, can be included.  The complications
are twofold: \latex and \dpic may not know the dimensions of the formatted
result, and the code is generally unique to the postprocessor.
Where postprocessors are capable of equivalent results, then
macros such as {\tt rs\_box}, {\tt shade}, and {\tt rgbfill} mentioned
previously can be used to hide code differences.

\subsection{\Tikz\ with pic}\label{Tikzwithpic:}
%The line
%
%\vspace{\parsep}
%\noindent{\tt command "}{\sl string}{\tt "}
%\vspace{\parsep}
%
%\noindent
%allows arbitrary postprocessor code to be embedded in \pic output.  However,
%one can also embed 
Arbitrary \pic output can be inserted into a {\tt \bsl{}tikzpicture} 
environment.  The trick is to keep the \pic and \Tikz coordinate systems
the same.
The lines

\vspace{\parsep}
\noindent\verb|\begin{tikzpicture}[scale=2.54]|\\
\noindent\verb|\end{tikzpicture}|
\vspace{\parsep}

\noindent in the {\tt dpic -g} output must be changed to

\vspace{\parsep}
\noindent\verb|\begin{scope}[scale=2.54]|\\
\noindent\verb|\end{scope}|
\vspace{\parsep}

This is accomplished, for example, by adapting the {\tt \bsl{}mtotex}
macro of \SR{Simplifications:} as follows:

\vspace{\parsep}
\noindent
\verb^\newcommand\mtotikz[1]{\immediate\write18{m4 pgf.m4 #1.m4 | dpic -g^\\
\verb^  | sed -e "/begin{tikzpicture}/s/tikzpicture/scope/"^\\
\verb^        -e "/end{tikzpicture}/s/tikzpicture/scope/" > #1.tex}\input{./#1.tex}}%^\break
%\verb^        -e "/end{tikzpicture}/s/tikzpicture/scope/"^\\
%\verb^  > #1.tex}\input{./#1.tex}}%^\break

Then, from within a \Tikz pictdure, 
{\tt \bsl{}mtotikz\lbr{}{\sl filename}\rbr}
will create {\sl filename}{\tt .tex} from {\sl filename}{\tt .m4}
and read the result into the \Tikz code.

In addition, the \Tikz code may need to refer to nodes defined in
the \pic diagram.
The included \Mfour macro
{\tt tikznode(}{\sl tikz node name,[position],[string]}{\tt)}
defines a zero-size \Tikz node at the given \pic position, which is
{\tt Here} by default.
This macro must be
invoked in the outermost scope of a pic diagram, and the
{\tt .PS} {\sl value} scaling construct may not be used. 

\xection{Web documents, {\ttfamily pdf}, and alternative output formats%
\label{Alternative:}}

Circuit diagrams contain graphics and symbols, and the issues related to
web publishing are similar to those for other mathematical documents.
Here the important factor is that \gpic\ {\tt -t} generates output
containing \tpic \verb|\special| commands, which must be converted
to the desired output, whereas \dpic can generate several alternative
formats, as shown in \FR{Workflow}.
One of the easiest methods
for producing web documents is to generate postscript as usual and to
convert the result to pdf format with Adobe
Distiller
%\Textregistered
or equivalent.

PDFlatex produces pdf without first creating a postscript file
but does not handle \tpic \verb|\special|s, so \dpic must be
installed.

%\enlargethispage{\baselineskip}
Most PDFLatex distributions are not directly compatible with \PSTricks, but
the \TPGF output of \dpic is compatible with both \latex and PDFLatex.
Several alternative \dpic output formats such as
\mfpic and \MetaPost also work well.
To test \MetaPost, create a file {\sl filename}{\tt .mp}
containing appropriate header lines, for example:
%\pagebreak
\begin{verbatim}
  verbatimtex
  \documentclass[11pt]{article}
  \usepackage{times,boxdims,graphicx}
  \boxdimfile{tmp.dim}
  \begin{document} etex
\end{verbatim}
Then append one or more diagrams by using the equivalent of

{\tt m4 <}{\sl installdir}{\tt >mpost.m4 {\sl library files}
  {\sl diagram}.m4 | dpic -s >> {\sl filename}.mp}

The command ``{\tt mpost --tex=latex } {\sl filename}{\tt .mp end}''
processes this file, formatting the diagram text by creating a
temporary {\tt .tex} file, \latex{}ing it, and recovering the {\tt .dvi}
output to create {\sl filename}{\tt .1} and other files.  If the {\tt boxdims}
macros are being invoked, this process must be repeated to handle
formatted text correctly as described in \SR{Interaction:}.
In this case, either put {\tt sinclude(tmp.dim)} in the diagram {\tt .m4}
source or read the {\tt .dim} file at the second invocation of
\Mfour as follows:

{\tt m4 <}{\sl installdir}{\tt >mpost.m4 {\sl library files} tmp.dim
  {\sl diagram}.m4 | dpic -s >> {\sl filename}.mp}

On some operating systems, the absolute path name for {\tt tmp.dim} has
to be used to ensure that the correct dimension file is written and
read.  This distribution includes a {\tt Makefile} that simplifies the
process; otherwise a script can automate it.

Having produced {\sl filename}{\tt .1}, rename it to {\sl filename}{\tt .mps}
and, {\it voil\`a,} you can now run PDFlatex on a {\tt .tex} source
that includes the diagram using
\verb|\includegraphics{|{\sl filename}\verb|.mps}|
as usual.

The \dpic processor is capable of other output formats, as illustrated in
\FR{Workflow} and in example files included with the distribution.
The \latex drawing commands alone or with {\tt eepic} or {\tt pict2e}
extensions are suitable only for simple diagrams. 
\begin{figure}[h!b]
%  \ifpdf\vspace*{-\baselineskip}\fi%
   \input Workflow
   \ifpdf\vspace*{-\baselineskip}\fi%
   \caption{Output formats produced by \gpic {\tt -t} and \dpic.
      SVG output can be read by Inkscape or used directly in web documents.}
   \label{Workflow}
   \end{figure}

\xection{Developer's notes\label{Developersnotes:}}
Years ago in the course of writing a book, I took a few days off to
write a \pic-like interpreter (\dpic) to automate the tedious
coordinate calculations required by \latex picture objects.  The
macros in this distribution and the interpreter are the result of that
effort, drawings I have had to produce since, and suggestions received from
others.  The interpreter has been upgraded over time to generate
\mfpic, \MetaPost~\cite{metapost}, raw \Postscript, \Postscript with
{\tt psfrag} tags, raw PDF, \PSTricks, and
Ti{\it k}Z PGF output, the latter two my preference
because of their quality and flexibility, including facilities for colour
and rotations, together with simple font selection.
\Xfig{}-compatible output was introduced early on to allow the creation of
diagrams both by programming and by interactive graphics.
\SVG output was added relatively recently, and seems suitable for
producing web diagrams directly and for further editing by the
Inkscape interactive graphics editor.  The latest addition
is raw PDF output, which has very basic text capability and is most
suitable for creating diagrams without labels, but on which sophisticated
text can be overlaid.  \Dpic can write the coordinates of selected
locations to an external file to be used in overlaying text or other
items on the diagram.

Instead of using \pic macros, I preferred the equally simple
but more powerful \Mfour macro processor, and therefore \Mfour is
required here, although \dpic  now supports \pic-like macros.  Free
versions of \Mfour are available for Unix, Windows, and other
operating systems.

If starting over today would I not just use one of the other drawing
packages available these days?  It would depend on the context, but
\pic remains a good choice for line drawings because it is easy to learn
and read but powerful enough for coding the geometrical calculations
required for precise component sizing and placement. It would be nice
if arbitrary rotations and scaling were simpler and if a general path
element with clipping were available as in \Postscript.  However, all the
power of \Postscript or \TPGF, for example, remains available,
as arbitrary postprocessor code can be included with \pic code.

The main value of this distribution is not in the use of a specific
language but in the element data encoded in the macros, which have been
developed with reference to standards and refined over two decades.
Some of them have become less readable as more options and flexibility
have been added, and if starting over today, perhaps I would change
some details. Compromises have been made in order to retain reasonable
compatibility with the variety of postprocessors.  No choice of tool
is without compromise, and producing good graphics seems to be time
consuming, no matter how it is done, especially for circuits
or other diagrams that contain random detail.

The \dpic interpreter has several output-format options that may be
useful.  The {\tt eepicemu} and {\tt pict2e} extensions of the
primitive \latex picture objects are supported.  The \mfpic output
allows the production of Metafont alphabets of circuit elements or
other graphics, thereby essentially removing dependence on device
drivers, but with the complication of treating every alphabetic
component as a \tex box.  The \xfig output allows elements to be
precisely defined with \dpic  and interactively placed with \xfig.
Similarly, the SVG output can be read directly by the Inkscape graphics
editor, but SVG can also be used directly for web pages.
\Dpic will also generate low-level \MetaPost or \Postscript code, so
that diagrams defined using \pic can be manipulated and combined with
others.  The \Postscript output can be imported into
CorelDraw
%\Textregistered
and Adobe Illustrator
%\Textregistered
for further processing.
With raw \Postscript, \PDF, and \SVG output, the user is
responsible for ensuring that the correct fonts are provided and for
formatting the text.

Many thanks to the people who continue to send comments, questions,
and, occasionally, bug fixes. What began as a tool for my own use changed
into a hobby that has persisted, thanks to your help and advice.

\xection{Bugs\label{Bugs:}}
This section provides hints and a list of common errors.

The distributed macros are not written for maximum robustness.
Arguments could be entered in a key--value style (for example, {\tt
resistor(up\_ elen\_,style=N;cycles=8}) instead of by positional
parameters, but it was decided early on
to keep macro usage as close as possible to \pic\ conventions.
Macro arguments could be tested for correctness and
explanatory error messages could be written as necessary, but that
would make the macros more difficult to read and to write.  You will
have to read them when unexpected results are obtained or when you wish
to modify them.

Maintaining reasonable compatibility with both \gpic\ and \dpic
and, especially, for different postprocessors, has
resulted in some macros becoming more complicated than is preferable.

Here are some hints, gleaned from experience and from comments I have
received.
\newcommand{%
 \bflistitem}[2]{\phantomsection\pdfbookmark[subsection]{#1}{#2}{\bf #1: }}
\begin{enumerate}

%\item {\bf Misconfiguration:}
\item
\bflistitem{Misconfiguration}{misconfig}%
  One of the configuration files
  listed in \SR{Libraries:} and {\tt libgen.m4}
  {\em must} be read by \Mfour before any other library macros.
  Otherwise, the macros assume default configuration.
  To aid in detecting the default condition, a {\tt WARNING}
  comment line is inserted into the {\tt pic} output.
  If only \PSTricks is to be used, for example, then
  the simplest strategy is to set it as the default processor by 
  typing ``make psdefault'' in the installation directory to
  change the mention of {\tt gpic} to {\tt pstricks}
  near the top of {\tt libgen.m4}.
  Similarly if only \TPGF will be used, change {\tt gpic} to {\tt pgf}
  using the Makefile.
  The package default is to read {\tt gpic.m4} for historical compatibility.
  The processor options must be chosen correspondingly,
  {\tt gpic -t} for {\tt gpic.m4} and, most often,
  {\tt dpic -p} or {\tt dpic -g} when \dpic is employed.
  For example, the pipeline for \PSTricks output from file {\tt quick.m4} is

  {\tt m4 -I {\sl installdir} pstricks.m4 quick.m4 | dpic -p > quick.tex}

  \noindent%
  but for \TPGF processing, the configuration file and \dpic option have to
  be changed:
  
  {\tt m4 -I {\sl installdir} pgf.m4 quick.m4 | dpic -g > quick.tex}

  Any non-default configuration file must appear explicitly in the command
  line or in an {\tt include()} statement.

\iffalse
\item 
\bflistitem{Initialization}{initialization}
If the first element macro evaluated is not two-terminal or is within a
\Pic block, then later macros evaluated outside the block may produce
the error message

{\tt there is no variable `rp\_ang'}

\noindent because {\tt rp\_ang} is not defined in the outermost scope of the
diagram.  To cure this problem, make sure that the line

{\tt cct\_init}

\noindent appears immediately after the .PS line or prior to the first block.
It is entirely permissible to modify {\tt cct\_init} to include customized
diagram initializations such as the {\tt thicklines\_} statement.
One way to do this is to define a macro {\tt local\_init} in
{\tt libgen.m4}.
\fi

\item
\bflistitem{Pic objects versus macros}{objects}%
  A common error is to write something like

{\tt line from A to B; resistor from B to C; ground at D}

\noindent when it should be

{\tt line from A to B; resistor(from B to C); ground(at D)}

\noindent This error is caused by an unfortunate inconsistency between
\pic object attributes and the way \Mfour and \pic pass macro arguments.

\item 
\bflistitem{Commas}{commas}
Macro arguments are separated by commas, so any comma that is
part of an argument must be protected by parentheses or quotes.  Thus,

{\tt shadebox(box with .n at w,h)}

\noindent produces an error, whereas

{\tt shadebox(box with .n at w`,'h)}

\noindent and

{\tt shadebox(box with .n at (w,h))}

\noindent do not. The parentheses are preferred.
For example,
a macro invoked by circuit elements contained the line

\verb|command "\pscustom[fillstyle=solid`,'fillcolor=m4fillv]{%"|

\noindent which includes a comma, duly quoted.  However, if such an
element is an argument of another macro, the quotes are removed and the
comma causes obscure ``too many arguments'' error messages.
Changing this line to

\verb|command sprintf("\pscustom[fillstyle=solid,fillcolor=m4fillv]{%%")|

\noindent
cured the problem because the protecting parentheses are not stripped away.

\item 
\bflistitem{Default directions and lengths}{defaultdir}
The \linespec argument of element
macros defines a straight-line segment, which requires
the equivalent of four parameters to be specified uniquely.
If information is omitted, default values are used.  Writing

{\tt source(up\_)}

\noindent draws a source up a distance equal to the current
{\tt lineht} value, which may cause confusion.
Writing

{\tt source(0.5)}

\noindent draws a source of length 0.5 units
in the current \pic default direction, which is one of
{\tt right,} {\tt left,} {\tt up,} or {\tt down.}
The best practice is
to specify both the direction and length of an element, thus:

{\tt source(up\_ elen\_).}

The effect of a \linespec argument is independent of any direction
set using the {\tt Point\_} or similar macros. 
To draw an element at an obtuse angle (see \SR{Corners:}) try,
for example,

{\tt Point\_(45); source(to rvec\_(0.5,0))}

\item 
\bflistitem{Processing sequence}{sequence}
It is easy to forget that \Mfour finishes before \pic processing
begins. Consequently, it may be puzzling that the following mix of
a \pic loop and the \Mfour macro {\tt s\_box} does not appear to produce
the required result:

{\tt for i=1 to 5 do \lbr s\_box(A[i]); move \rbr}

\noindent In this example, the {\tt s\_box} macro is expanded only once
and the index {\tt i} is not a number.  This particular example can be
repaired by using an \Mfour loop:

{\tt for\_(1,5,1,`s\_box(A[m4x]); move')}

\item 
\bflistitem{Quotes}{quotes}
 Single quote characters are stripped in pairs by \Mfour, so the string

{\tt "{`}{`}inverse{'}{'}"}

\noindent will become

{\tt "{`}inverse{'}".}

\noindent The cure is to add single quotes in pairs as necessary.

  The only subtlety required in writing
  \Mfour macros is deciding when to quote macro arguments.  In the context
  of circuits it seemed best to assume that arguments would not
  be protected by quotes at the level of macro invocation, but should
  be quoted inside each macro.  There may be cases where this rule is
  not optimal or where the quotes could be omitted, and there are
  rare exceptions such as the {\tt parallel\_} macro.

\item 
\bflistitem{Dollar signs}{dollarsigns}
The $i$-th argument of an \Mfour macro is {\tt \$}$i,$ where $i$ is
an integer, so the following construction can cause an error when it
is part of a macro,

{\tt "\$0\$" rjust below}

\noindent since {\tt \$0} expands to the name of the macro itself.
To avoid this problem, put the string in quotes or write
 {\tt "\$`'0\$".}

\item 
\bflistitem{Name conflicts}{conflicts}
 Using the name of a macro as part of a comment or string is a
 simple and common error. Thus,

{\tt arrow right \verb|"$\dot x$"| above}

\noindent produces an error message because {\tt dot} is a macro
name.   Macro expansion can be avoided by adding quotes, as follows:

{\tt arrow right `\verb|"$\dot x$"|'\ above}

Library macros intended only for internal use have names that begin
with {\tt m4} or {\tt M4} to avoid name clashes, but in addition,
a good rule is to quote all \latex in the diagram input.

If extensive use of strings
that conflict with macro names is required, then one possibility is
to replace the strings by macros to be expanded by \latex, for example
the diagram

{\tt
.PS\hfill\break
   \hspace*{\parindent} box \verb|"\stringA"|\hfill\break
.PE
}

\noindent with the \latex macro

{\tt
  \verb|\newcommand{\stringA}{|%

   \verb|Circuit containing planar inductor and capacitor}|
}

\item 
\bflistitem{Current direction}{currdir}
 Some macros, particularly those for labels, do
unexpected things if care is not taken to preset the current direction
using macros {\tt right\_,} {\tt left\_,} {\tt up\_,} {\tt down\_,}
or {\tt rpoint\_($\cdot$).}
Thus for two-terminal macros it is good practice to write, e.g.

{\tt resistor(up\_ from A to B); rlabel(,R\_1)}

\noindent%
rather than 

{\tt resistor(from A to B); rlabel(,R\_1),}

\noindent%
which produce different results if the last-defined drawing direction is not
{\tt up}.  It might be possible to change the label macros to avoid this problem
without sacrificing ease of use.

\item
\bflistitem{Position of elements that are not 2-terminal}{nottwoterm}
  The \linespec argument of elements defined in {\tt[} {\tt]}
  blocks must be understood as defining a direction and length, but
  not the position of the resulting block.
  In the \pic language, objects inside these brackets are placed by
  default {\em as if the block were a box}.  Place the
  element by its compass corners or defined interior points
  as described in the first paragraph of \SR{Composite:} on
  \PR{Composite:}, for example  
  
{\tt igbt(up\_ elen\_) with .E at (1,0)}

\item
\bflistitem{Pic error messages}{errormessages}
 Some errors are detected only after scanning
  beyond the end of the line containing the error.  The semicolon
  is a logical line end, so putting a semicolon at the end of lines may
  assist in locating bugs. 

\item
\bflistitem{Line continuation}{continuation}
 A line is continued to the next if the
  rightmost character is a backslash or, with \dpic, if the backslash is
  followed immediately by the {\tt \#} character.
  A blank after the backslash, for example, produces a \pic error.

\item
\bflistitem{Scaling}{scaling}
 \Pic and these macros provide several ways to scale
  diagrams and elements within them, but subtle unanticipated effects
  may appear.  The line {\tt.PS} $x$ provides a convenient way to force
  the finished diagram to width $x.$  However, if \gpic is the
  \pic processor then all scaled parameters are affected, including those
  for arrowheads and text parameters, which may not be the desired
  result.  A good general rule is to use the {\tt scale} parameter for
  global scaling unless the primary objective is to specify overall
  dimensions.

\item
\bflistitem{Buffer overflow}{overflow}
 For some \Mfour implementations,
  the error message {\tt pushed back more than 4096 chars}
  results from expanding large macros or macro arguments, and can be
  avoided by enlarging the buffer.  For example, the option {\tt
  -B16000} enlarges the buffer size to 16000 bytes.  However, this
  error message could also result from a syntax error.

\item
\bflistitem{\PSTricks anomaly}{anomaly}
 If you are using \PSTricks and
  you get the error message {\tt Graphics parameter `noCurrentPoint'
  not defined..} then your version of \PSTricks is older than
  August 2010.  You can do the following:
\begin{enumerate}
\item Update your \PSTricks package.
\item Instead, comment out the second definition of {\tt M4PatchPSTricks} in
  {\tt pstricks.m4}.  The first definition works for some older
  \PSTricks distributions.
\item Insert {\tt define(`M4PatchPSTricks',)} immediately after the
   {\tt .PS} line of your diagram.
  This change prevents the line
  \verb|\psset{noCurrentPoint}| from being added to the {\tt .tex}
  code for the diagram.  This line is a workaround for a ``feature''
  of the current \PSTricks \verb|\psbezier| command that changes its
  behaviour within the \verb|\pscustom| environment.  This situation
  occurs rarely and so the line is unnecessary for many diagrams.
\item For very old versions of \PSTricks such as pstricks97, disable the
  workaround totally by changing the second definition in {\tt pstricks.m4}
  to {\tt define(`M4PatchPSTricks',)}.  Undo the change if you later update
  \PSTricks.
  \end{enumerate}

\item
\bflistitem{m4 {\tt -I} error}{mfourerror}\label{Mfourerror:}
  Some old versions of m4 may not implement
  the {\tt -I} option or the {\tt M4PATH} environment variable that
  simplify file inclusion.
  The simplest course of action is probably to install GNU m4, which is
  free and widely available. 
  Otherwise, all {\tt include({\sl filename})} statements in the libraries and
  calling commands have to be given absolute {\sl filename} paths. 
  You can define the {\tt HOMELIB\_} macro in {\tt libgen.m4} to the
  path of the installation directory and change the library
  include statements to the form {\tt include(HOMELIB\_`'{\sl filename})}.

\end{enumerate}

\xection{List of macros\label{Listofmacros:}}
\label{defines}
The following table lists macros in the libraries, configuration
files, and selected macros from example diagrams.  Some of the sources
in the {\tt examples} directory contain
additional macros, such as for flowcharts, Boolean logic, and binary
trees.

Internal macros defined within the libraries begin with the characters
m4 or M4 and, for the most part, are not listed here.

The library in which each macro is found is given, and a brief description.
\input defines
\endinput
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

 I think you want the pdfcomment package. This includes a \pdftooltip command.

 This lets you add a tool tip to the PDF using
  \pdftooltip{item}{tooltip},
  where the item can be almost anything
 (e.g. \pdftooltip{\includegraphics[]{}}{description of my figure}).

 In your case, you could use

 \pdftooltip{abbreviation}{what that TLA means}

 But with pdfcomment, the tool tip cannot be anything but plain,
 unformatted text.

  Try the \pdfcomment package. There's an option to add a tool tip to
  the PDF using \pdftooltip{item}{tooltip}, where the item can be a float
  (e.g. \pdftooltip{\includegraphics[]{}}{description of my figure}).

  The overall process that I've settled on to produce 508-compliant
  documents is to

  Produce a high-quality PDF from \latex which includes all of the tooltips
  Run the PDF through the tagging tool that is provided by Adobe Acrobat X
  (Adobe how-to).