summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pmx/pmx274.tex
blob: 3d6630157f47266799b20155811fb9c700c54f00 (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
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% pmx274.tex 20 Feb 2016
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass[11pt]{article}
%
\let\reft\ref
   \usepackage[dvips,colorlinks=true,linkcolor=blue]{hyperref}
   \usepackage[dvips]{graphicx}
   \usepackage{multicol}
%
\def\MusiXTeX{MusiX\TeX}
\def\bs{{\tt\char'134}}
\newcommand\PMXX{\textbf{PMX}}
\newcommand\PMX{\PMXX~}
\newcommand\IMA{\href{http://Icking-Music-Archive.org}{\underline{Icking Music Archive}}}
%
% Use \bfx for program names only.  Use \bf for single embedded letters 
%
\font\bfx=cmb10 scaled\magstephalf
\font\bfi=cmbxti10 scaled\magstephalf
\font\specfig=cmrj
\setcounter{secnumdepth}3
\setcounter{tocdepth}3
\def\Bslash{\tt\char'134}
\def\|{{\tt\char'174}}
\def\LBR{{\tt\char'173}}
\def\RBR{{\tt\char'175}}
\textheight= 9.5in \voffset-.8in%
\textwidth= 6.5in \hoffset-1.0in
\def\newfrom{2.59}  % changed every now and then 
\def\NEW#1{\ifdim#1 pt<\newfrom pt\else% 
\marginpar{\fbox{#1}}\fi}

\hoffset-54pt

%\let\rulet\rule\def\rule#1#2{\if#1<#2\rulet{.05in}{#2}\else\rulet{#1}{.05in}\fi} 

\begin{document}

\raggedright
\parindent24pt

\title{
  \Huge\bf
  PMX~--~a Preprocessor for \MusiXTeX{}\\
  \null\vskip-15pt
  \Large\sl
  Version 2.74~--~February 2016\\ 
  \author{\Large\rm Don \sc Simons\\
  \large\sl
  Dr. Don's PC and Harpsichord Emporium\\
  \normalsize\sl
  Redondo Beach, California, USA.\\
% To make the bitmapped eps: (1) TeX file with cmtt scaled 2500,
% (2) dvips -> gsview -> pdf.
% (3) gwin32 -sDEVICE=pnggray -sOutputFile=file.png -r100 -dEPSCrop -dbatch -q 
%    -dNOPAUSE -dTextAlphaBits=4 file.eps -c quit
% (4) file.png -> GIMP (crop out blank space) -> save as .eps.
%
  \includegraphics[scale=0.4]{file600.eps}}}

\date{}

\maketitle

\section*{Preface}
Compared to version 2.73, \PMX version 2.74 has minor enhancements to lyrics capabilities,
behind-the-scenes modifications to allow staff-crossing chords that are unbeamed or beamed as
illustrated in {\tt staffcrossall.pmx},
and several bugfixes in \bf scor2prt and {\tt pmx.tex}.

\setcounter{page}1
\tableofcontents
%\setcounter{secnumdepth}1
\pagestyle{headings}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\def\boxitsep{10pt}
\let\hrt\hrule\def\hrule{\hrt height2pt}
\let\vrt\vrule\def\vrule{\vrt width2pt}
\def\boxit#1{\vbox{\hrule\hbox{\vrule\kern\boxitsep\vbox{%
\kern\boxitsep\hbox{#1}\kern\boxitsep}\kern\boxitsep\vrule}\hrule}}
\font\ded=cmssdc10 scaled \magstep3 
\bigskip
\setbox4=\vbox{
  \hsize3in\noindent\strut 
     \centerline{\ded Dedication}
\vskip 3pt
The \MusiXTeX~community was stunned by the sudden death of Werner Icking on 
\break February 8, 2001.  He had been a benevolent patriarch, touching many 
of us not only
with his technical savvy and gentle guidance, but also his genuine kindness 
and generosity.  His spirit runs deep through all of \PMX.  His encouragement
fueled its development from its very beginning.  Many 
enhancements have been his proposals, including one he made on what
turned out to be his last day.  Werner, my friend, I dedicate this work to
you and your memory.  
}
\vfill
$$\boxit{\box4}$$
\let\hrule\hrt\let\vrule\vrt
\vfill
\eject

\section{Introduction}
%\setcounter{secnumdepth}1

        \PMX is a preprocessor for \MusiXTeX{}.  Before using it you should 
have installed \MusiXTeX~Version 1.21 \NEW{2.71} or higher, and 
any available version of \TeX~that includes e-\TeX.  The goal of \PMX is to 
facilitate the efficient typesetting of scores and parts
that have an almost professional appearance.  It can do {\it all} the work
involved in setting up {\tt \bs notes-\bs enotes} groupings, 
selecting groups of
notes to be beamed, defining beam heights and slopes, spreading the
entire piece evenly over specified numbers of systems and pages, and inserting
extra spaces where needed to make room for accidentals, flags, dots,
and new clefs. The input language for \PMX is much simpler than
\MusiXTeX.  You can enter note values and rests from 64ths to double 
whole notes ({\it breves}), ornaments, slurs, and limited text strings.  Every
voice in every bar must have exactly the correct number of beats in
the current meter, but you may change the meter at the beginning of any
measure, with or without printing the new time signature.  Before making a 
\TeX{} file, \PMX checks these timings and other aspects of the input.
\PMX has special features for dealing with baroque chamber music, including
the ability
to notate figured bass below the bottom staff in each system.  If \PMX hasn't
yet learned to do something you want to do, you can usually work around the 
problem by inserting literal \TeX\ strings in the \PMX input file.

     You can automatically create parts from a score using {\bfx scor2prt}.  
This auxiliary program generates a set of {\tt .pmx} input files, one for 
each part, from a single {\tt .pmx} file for the score.  
You can control the appearance of the 
parts with special commands in the main file, thereby making it  
possible to include within a single input file all the information 
that defines the score and the individual parts.

The basic \PMX
distribution as of this version of the manual is 
\href{http://icking-music-archive.org/software/pmx/pmx273.zip}
{\underline{\tt pmx273.zip}}.\NEW{2.73} It 
contains the FORTRAN sources, binaries that will run in a DOS
window on a PC with WINDOWS95 or higher, manuals for useage and for installation 
in DOS/Windows, and example typesetting files. Alternatively, the 
\href{http://www.icking-music-archive.org/software/htdocs/Getting_Started_Four_Scenar.html}
{\underline{software section}} of the Werner Icking Music Archive (WIMA) has instructions
for acquiring and installing \MusiXTeX~and \PMX on various platforms
(Windows, Mac-OSX, Unix-like systems) including using automated procedures from
several external \TeX~distribution sites.
The packages from those other sites will 
all eventually incorporate all the upgrades in {\tt pmx273.zip} but will take 
varying amounts of time to do so. \PMX is often upgraded; the most current version will
always be available directly from the ``News'' paragraph
\href{http://www.icking-music-archive.org/software/htdocs/htdocs.html}{\underline{here}}. 

\subsection{Conventions for This Manual}

	Hey, this is boring stuff, but if you take a minute to understand
the typographic conventions and a little jargon, 
it may avoid some confusion down the road.

	The typewriter typeface always indicates verbatim text as it would
be input to a computer.  This includes file names, \MusiXTeX{} tokens, and 
\PMX commands, e.g., {\tt barsant.pmx, \bs internote, c44}. 

	Bold is used for program names (e.g., {\bfx pmxab}), or when applied
to a single letter, to relate a \PMX command to its meaning (e.g., ``{\tt e}
signifies a l{\bf e}ft shift'').

        When\NEW{2.5}~viewing the PDF version of this document on a computer 
screen, clickable internal hyperlinks are colored blue, and clickable external 
links are underlined and colored cyan. 

        Italics may mean several different things depending on the context:
simple emphasis, or the first appearance of {\it jargon} 
(buzz-words that need to be explicitly defined), or finally  
to represent input variables for which some verbatim text would need to be 
substituted.  In the latter case the variable will be surrounded by
square brackets, e.g., [{\it basename}], but the brackets are not to be 
included with the substituted text.

        Speaking of jargon, there are several special words that have very 
specific meanings here: A {\it staff} is one set of 5 lines (plural 
{\it staves}), a {\it system} is a group of staves, and {\it voice} refers to 
one of the one or two 
simultaneous allowable sequences of notes in a staff. Note that this  
is a change \NEW{2.5}from versions prior to 2.5, where {\it voice} was used 
interchangeably with staff.

A \PMX {\it command} is a string of characters with no spaces between them. 
The first character determines the type of command. Any other characters 
are parameters that may be either required or optional. Sometimes we loosely 
use the word {\it command} to refer just to the initial character. 

\subsection{Setup}

	Here we briefly describe the setup for the Windows OS,
assuming \TeX\ and \MusiXTeX\ have already been installed. After compiling the
FORTRAN source code, users of other OS's 
may either adapt these instructions as needed or use one of the other setup 
methods referenced earlier. 

After decompressing the distribution file {\tt pmx273.zip}, 
you should have these 
files: \NEW{2.73} {\tt pmx273.for}, {\tt scor2prt.for}, two 
Windows executables {\tt pmxab.exe} and {\tt scor2prt.exe}, several sample 
{\tt .pmx} files,
{\tt pmx.tex}, {\tt ref273.tex} (\TeX\ source for a command summary),
{\tt pmx273.tex }(\TeX\ source for this file), 
PDF images of the latter two files, {\tt pmx25-273.html} showing 
changes from version 2.50 to 2.73, and {\tt install\_run\_PMX.pdf} which gives more 
details about installing and running on different platforms.

%If necessary, compile the FORTRAN programs.
%I have tried to keep the source code as generic as possible, but minor 
%modifications may be needed for FORTRAN-to-C translation and/or other
%compilers.  

	Once you have assembled a full set of files, put the executables 
somewhere in the path or in your working directory, {\tt pmx.tex} into the 
texinput directory, the sample {\tt *.pmx} files in your working 
directory (the one from which you will run \PMXX), and the source code and 
document files wherevever you wish.

\subsection{Basic Operation, by Example}

Edit the 15th line of {\tt barsant.pmx} to contain the path to the 
directory where you want \PMX to write the {\tt .tex} file.  For example, 
if you want this to be the same as the working directory, type {\tt .\bs}~for Windows, 
or {\tt ./} for UNIX.   

If you haven't done so, open a command window and navigate to the 
folder containing {\tt barsant.pmx}. Execute \PMX by typing 
{\tt pmxab barsant} . Alternatively, you may 
just type {\tt pmxab <return>} and you will be prompted
for a jobname, which in this case is just {\tt barsant} .  
{\bfx pmxab} will always generate two files in the working 
directory: {\tt barsant.pml}
is a log file, and {\tt pmxaerr.dat} contains a single integer, 0 if 
the run was successful, otherwise the line number in the {\tt .pmx} file of the 
fatal error (useful for batch processing).   Also, on successful completion, 
{\tt barsant.tex} will be placed in the path specified in the setup.  

Now you are right where you would be after 
entering, debugging, and rough-editing the {\tt .tex} file manually.  To see 
the results, process {\tt barsant.tex} just as you would for any \MusiXTeX{} 
file, running all three passes, and view the {\tt .dvi} file, or go on and run 
{\bf dvips} to create a postscript file and view that with a postscript viewer
such as {\bf GSview}.  To make 
separate parts, run {\bfx scor2prt} by typing {\tt scor2prt barsant} .\NEW{2.0} 
The program will create a new {\tt .pmx} file for each instrument, in this
case {\tt barsant1.pmx} and {\tt barsant2.pmx}.
You may then process these 
files like you did the original one to create separate parts.

\section{Elements of PMX}
\def\l@subsection{\@dottedtocline{2}{5em}{20em}}%original 2 3.8 3.2
%\setcounter{secnumdepth}2

\subsection{Setup Data in the Input File} \label{setupdata}

	To see how the input file is put together, we'll look at 
{\tt barsant.pmx}.  For reference, here are are the first few lines:  
\begin{verbatim}
%----------------%
%
%  barsant.pmx   Revised 29 June 2002
% 
%----------------%
%
% nv,noinst,mtrnuml,mtrdenl,mtrnmp,mtrdnp,xmtrnum0,isig,
  2    2      4       4        0      6      0       0 
%
% npages,nsyst,musicsize,fracindent
    1      7     20        0.07
Basso
Recorder
bt
./
\end{verbatim}
The lines 
with {\tt \%} in column 1 are comments.  
Some special handling of comment lines will be 
discussed in the section on creating parts from a score in  
section~\ref{scor2prt}.
   
The rest of the lines in this example are the {\it setup data}.  
Starting in the first non-comment line above,   

{\tt nv} (integer$\leq$24) \NEW{2.6} is the total number of 
sta{\bf v}es per system.  Each staff may contain either one or two voices,
but the total number of voices at any one time may not exceed 24.

{\tt noinst} (integer$\leq${\tt nv}) is number of {\it instruments}.  Each 
instrument has a unique name (see below), and any instrument
with more than one staff will have its staves joined with a curly bracket. 
Usually there is only one staff per instrument and {\tt noinst=nv}.  There
are two ways to assign more than one staff to one or more instruments. 
If only the first (lowest) instrument has more than one staff, such as in
a score for piano and a solo instrument, simply make
{\tt noinst$<$nv} and any difference will show up in instrument 1, the bottom
one in each system.  
\NEW{1.4} For a
more general distribution of staves among instruments, 
put a minus sign in front of {\tt noinst},
and follow {\tt noinst} with the number of staves in each  instrument  in
succession, separated by spaces.  These numbers must add up to {\tt nv} or your
computer will explode.  For a typical example of keyboard music, see 
{\tt mwalmnd.pmx}, in which {\tt nv=2} and {\tt noinst=1}, producing two 
staves per system with a curly bracket at the left.  

The number of instruments can be changed as well after the start of the 
score, but only to a number less than the original one.  See 
section~\ref{movbrk} to learn how to start with a smaller
number of instruments and later increase it.  

{\tt mtrnuml} is the {\it logical} numerator of the meter, or the number of 
beats per measure; {\tt mtrdenl} the denominator.  Please note the special
considerations in the paragraph after the next. If {\tt mtrnuml} is 
divisible by 2 or 3, beam grouping will be automatic; otherwise you will
have to force all beams using {\tt [}$\dots${\tt ]} as described in 
section~\ref{beams}.

{\tt mtrnmp} and {\tt mtrdnp} are the {\it printed} numerator and denominator.  
These determine the appearance of the meter in the printed output but 
have no effect on the internal timing analysis.  If {\tt mtrnmp$>$0} then it 
and {\tt mtrdnp} are printed literally as the numerator and denominator 
of the time signature.  Please note the special considerations in the following 
paragraph. If 
{\tt mtrnmp$<$0}, then the numerator is abs({\tt mtrnmp}) and the 
entire time signature will be printed with a vertical slash through 
it.  If {\tt mtrnmp}=0, then {\tt mtrdnp} determines the printed meter 
as follows: 

\medskip

\begin{tabular}{ll}
\tt 0 & No meter is printed ({\it blind} meter change)\\
\tt 1, 2, 3, or 4 & A single digit, between the 2nd and 4th lines\\
\tt 5 &  Cut time (alla breve)\\
\tt 6 &  Common time\\
\tt 7 &  Numeral 3 with a vertical slash\\
\end{tabular}

\medskip

There are special considerations for n/16 and n/1 time signatures (where the 
latter "1" normally means a whole note).  To get
n/1 time, use {\tt 0} (zero) for {\tt mtrdenl} and {\tt 1} for {\tt mtrdnp}.  To 
remember this rule, recall that the printed denominator is taken literally,
while the logical denominator can always be represented
by the same single digit used for the corresponding time value when entering 
ordinary notes (see section~\ref{notes}). So
for n/16 time, use {\tt 1} for {\tt mtrdenl} and {\tt 16} for {\tt mtrdnp}. 

If the first bar is a partial bar containing a pickup, {\tt xmtrnum0} is 
the number of beats in it; otherwise set it to 0.  It need not be an 
integer.  The first bar is the {\it only} bar that can have a different 
number of beats than the current value of {\tt mtrnuml} (Later we'll see how 
to change the meter).

{\tt isig} is the key signature, positive integer for sharps, negative for 
flats.

If {\tt npages}$>$0, it is the number of pages and {\tt nsyst} is the total 
number of systems in the entire piece.  \PMX will spread the entire 
piece horizontally over this number of systems, and vertically over 
{\tt npages} pages.  For proper vertical spacing there should be from 
about 9 to 16 staves per page.  If you specify too many staves for the number
of pages, one or more staves may spill over onto an extra sheet.  If this 
happens it will only become obvious when you preview the {\tt .dvi} file.  
One solution is to use the global option {\tt Ae} 
(see section~\ref{AeDirective}); another is to increase {\tt npages} or 
decrease {\tt nsyst}.

If {\tt npages} is set to 0, then {\tt nsyst} is interpreted as the average 
number of measures per system.  This is useful while building up a 
file a little at a time. \PMX will calculate how many systems to use, and
spread them over an appropriate number of pages.

{\tt musicsize} is 16, 20, 24, or 29, the height of a staff in points, with
20 considered the default\NEW{2.6}.

{\tt fracindent} is the indentation of the first system from the left 
margin, expressed as a decimal fraction of the total line width.

Next come the names of the {\tt noinst} instruments as you want them to 
appear within the indentation in the first system, one per line, 
starting with the {\it bottom} instrument.  If you've set {\tt fracindent}=0 
and don't 
want instrument names to appear, you must still leave {\tt noinst}
blank lines here.  Next comes a single string of {\tt nv} 
letters or numbers for the clefs, again starting with the bottom staff: 
\label{ClefCodes}
{\tt b,~r,~n,~a,~m,~s,~t,~f,~8} or digits 0-8 \NEW{2.71} respectively for {\bf b}ass, 
ba{\bf r}itone, te{\bf n}or, {\bf a}lto, {\bf m}ezzo-soprano, {\bf s}oprano, 
{\bf t}reble,\NEW{2.2} {\bf F}rench violin clef, or octave treble clef.   
The last line of setup data contains the path to the directory 
where you want the {\tt tex} file to go when \PMX creates it.  The one 
in {\tt barsant.pmx}~, 
{\tt ./}~, represents the current directory in UNIX and some versions of DOS.  
The path must terminate with {\tt /} or {\tt \bs}~.

\subsection{Structure of the Body of the Input File} \label{structure}

	The rest of the {\tt .pmx} file is the {\it body} of the input.  
The basic unit of input from here on is called an {\it input block} or 
just {\it block}, each one representing an integral number of bars.  If there
is a pickup bar defined by {\tt xmtrnum0} $>$ 0, 
it must be included in the first block {\it together with at least one full bar}. 
If you wish to put a pickup in a separate block, for example at the start
of a new movement, set the initial logical
meter to fit the pickup bar, then after the pickup bar do a blind meter change
as described in section~\ref{MeterChange}).

There will usually be 
4 to 8 bars in a block.  15 is the most allowed.  It is good practice 
to separate the blocks with comment lines that state which bars are 
represented, as I've done in {\tt barsant.pmx}.  
It is also advisable, although not required, to separate the bars with
the command {\tt |}. Its main functions 
are to provide visual separation in the input file, and to help isolate input
errors: if you put one anywhere except 
at a bar-end, {\bfx pmxab} will stop and show you where it detected the 
timing error. Otherwise, with several minor exceptions,
{\tt |} has no effect.  

At the start of each block there may be a few special commands 
(described starting in section~\ref{pmxcmds}).  
Next come the input data for the selected number 
of bars of the first (lowest in the system) voice in the first staff, followed by 
either {\tt /} to move to the next staff, or {\tt //} to move to the next voice 
on the same staff.  Each new voice must start on a new line 
in the input file, i.e., there should be no further data on the same input line
after {\tt /} or {\tt // }. 
   Continue entering other voices, each with 
{\it exactly} the same number of bars as the first, 
terminated by {\tt /} or {\tt //}, until
 the last (topmost in the system) ends with a {\tt /} and the block is 
finished.  Within 
a block every voice must have the same number of bars, but every block 
needn't have the same number of bars as other blocks.  The number of 
voices in a staff can only be 1 or 2, and cannot change within a block, but
may vary from block to block. 

	The data for each voice in each staff are a sequence of commands 
containing one or more adjacent characters.  Commands are separated from each
other by spaces.  The line-terminating commands {\tt /} and {\tt //} should also
naturally be preceded by a space.

\subsubsection{Notes} \label{notes}

	Commands for notes always start with a lower-case letter and, as 
with all commands, end at 
the first space. The first letter is the note name ({\tt a-g}).  The 
rest of the characters can be in any order with only a few 
restrictions.  The first digit defines the {\it basic time value} of the 
note: {\tt 9, 0, 2, 4, 8, 1, 3} or {\tt 6} respectively for double-whole,
whole, half, quarter, 
eighth, sixteenth, thirty-second, and sixty-fourth notes.  The second 
digit sets the octave (for reference, octave 4 runs from middle C to 
the B above).  Certain letters may appear after the initial one: {\tt d} 
for {\bf d}ot; {\tt dd} for \NEW{1.4} double dot; 
{\tt f, n,} or {\tt s} for {\bf f}lat, {\bf n}atural, 
or {\bf s}harp (repeat the letter  
immediately for a double); {\tt u} or {\tt l}, which  force the stem 
direction of any un-beamed note; {\tt e} or {\tt r} to shift the notehead 
l{\bf e}ft 
or {\bf r}ight by its own width; and {\tt a} (for {\bf a}lone) which inhibits 
beaming for this note (or, if the first note of an xtuplet, for the
entire xtuplet). \NEW{2.4}A single accidental may be followed by {\tt c} to
make it {\bf c}autionary, i.e., surround it with parentheses.
Alternatively, it may also be followed by {\tt i} to 
suppress typesetting \NEW{2.3} but still have 
the M{\bf I}DI processor honor the accidental.  Other characters allowed in note 
commands are {\tt +}, {\tt -}, {\tt .}(period), {\tt ,}(comma), {\tt x}, and 
several special characters following {\tt x}, all to be described below.  
Between the first letter and the end or {\tt x} if present,
non-digits can be in any order with respect to each other and to the digits, 
with minor exceptions involving shifting dots and accidentals.  

To move
a dot from its default location, simply follow the {\tt d}
with one or two decimal numbers, each predeced by 
{\tt +} or {\tt -}.  
The first is the 
vertical shift in \bs{\tt internote}s, the second, the horizontal shift in 
notehead widths.  

\label{AccidentalPosition}
Accidentals \NEW{1.4} can be shifted too.  One way is to enter 
{\tt +} or {\tt -} right after the accidental character, 
then an integer 
for the vertical shift, then another {\tt +} or {\tt -} followed by the 
horizontal shift in notehead widths.  If you use this method, you {\it must}
enter both numbers.  Or, to just shift horizontally, use
{\tt <} or {\tt >} followed by the shift in notehead widths.  When shifting
a sharp to avoid another sharp, a left shift of 0.85 is usually best.  When 
shifting a flat to avoid a flat above it, a left shift of 0.3 is suggested.
In chords (see section~\ref{chords}), if all the notes are in the same \NEW{2.4}voice, 
\PMX will automatically shift accidentals if required. This will be disabled 
for the current chord 
if any user-defined accidental shifts are entered, unless {\tt A} is entered 
along with the shift, e.g., {\tt zcsA<.5} . In that case the user-defined 
shift will be added to the PMX-computed one. 
\NEW{2.4} Another option that affects accidental positioning in 
chords is {\tt Ao},
entered in the main note command of a chord.  It will force the accidentals 
in that chord will be posted in the order
they come in the source file (starting with the main note), each one as far
to the right as it will go without crashing into a notehead, stem, or
another accidental. 


  Dots and accidentals always have to be entered when and if a note 
calls for them. i.e., they are never carried over from previous notes.  
On the other hand, the octave only needs to be entered if the note is 
more than a fourth away from the most recent note in the same voice.  
This feature lets you go for long stretches in a voice before needing 
to enter the octave.  An alternate way to jump more than a fourth but 
less than a twelfth is to type {\tt +} or {\tt -}.  In other words, these 
mean to put the note an octave higher or lower than it 
otherwise would have gone.  Two {\tt +}'s will raise the pitch two octaves 
above what it otherwise would have been, and so forth.  
The basic time 
value is also carried over from the past if it is not re-entered,   
except for the first note or rest in each voice in an input block, 
for which it {\it must} be entered.   
Therefore, when the melody jumps more than a 4th, using {\tt +} or {\tt -} is 
often more convenient than using a digit.  This is because in order to 
use the digit, you must first enter the basic time value whether it 
changes or not.  

	For example {\tt c44 d e f g a b c c0-} is an ascending quarter-note  
scale starting on middle C, followed by an octave jump down to a 
whole note middle C.  

	Explicit octave \NEW{2.1} numbers can be combined with one or
more {\tt +} or {\tt -} .  In earlier versions, {\tt +} or {\tt -} was
ignored if an octave number was specified.  This is a slight backward 
incompatibility; \PMX prints a warning when it happens.

Stem length \NEW{2.73} can be {\bf s}hortened or {\bf l}engthened by {\it x} 
\bs{\tt internote} with the options {\tt S}{\it x} or {\tt L}{\it x}~. 
{\it x} is restricted to the range (0.5,4.0) for shortening and 0.5 to 27.5 
for lengthening.
The shortening can be made ``sticky'' by following the number {\it x} with 
{\tt :} . Then every note's stem in the voice will be shortened until 
one is encountered with the option {\tt S:} . By lengthening a stem enough 
to span to the next staff and connect with notes there, unflagged staff-spanning 
chords can be constructed. See section \ref{chords}~for further details 
about staff-spanning chords.

The first note command in each voice in a block must 
contain at a minimum the note name or {\tt r} for a rest (see below), 
and a basic time value.  For notes, it is good practice and can simplify 
editing
if in addition an explicit octave is set here.  However if it is not, 
\PMX will make some assumptions.  At \NEW{2.4} the start of the first 
input block the pitch will be set as if the prior note were middle C.
In later blocks \PMX will use the
obvious inheritance rules from the end of the prior block.  
However, if the number of voices in a staff  
has changed from the prior block, it is safest to reset the octave at the
start of a new block.  Duration is never inherited and must be set at the
start of each input block.   

	Dots can be a little tricky, because even though they affect the 
actual time value, they don't affect the basic time value, and it is only the
latter that is ``sticky".  Therefore, if a note is to be dotted, you always have to 
enter a {\tt d} (or a period, see next paragraph) somewhere within the 
command, after 
the note name, even if the actual time value and octave are the same 
as the prior note.  But the {\it basic} time value need not be re-entered if 
it hasn't changed (unless the note is more than a fourth from the 
prior note {\it and} you have for some strange reason elected to indicate the 
octave with a number rather than {\tt +} or {\tt -} ). So for example, 
consecutive dotted half notes, each within a fourth of the previous 
one, could be most cleanly entered as {\tt cd24 ed gd ed}, whereas {\tt cd24 e}
would represent a dotted half note followed by a plain half note 
(since the basic time value---as defined by the first digit---was a half 
note all along).

	There are two special shortcut rhythmic notations.  For normal dotted
rhythms (3:1 ratio), if you    
include a period ({\tt .}) in the note command, it will 
(a) assign a dot to the note just entered, (b) terminate that note, 
(c) prepare to 
receive the next note name {\it without any space}, and (d)~automatically 
assign a time value to the second note equal to one-third of the first one.
No time value may be entered for the second note, but octave and accidental
data may.  Ornaments and slurs (see below) following this command will apply 
to the second member. If you need to follow the main note 
with some modifying 
\NEW{2.3} 
command, you can still use the shortcut ({\tt .}) after that command and a
space. 
The main advantage of this shortcut comes if you want to 
follow one dotted pair with another of the same rhythm; then you 
needn't enter any explicit time value for {\it either} member of the second pair.  
This is possible because after using the shortcut,
the basic (inheritable) duration is set to that of the
{\it first} note in the pair, without the dot.

     For paired notes with 2:1 rhythmic ratios, the character {\tt ,}~(comma)
behaves similarly to the {\tt .}~(period) for 3:1 rhythms.

	Xtuplets, or groups of notes with their stems connected,
can have from 2 to 24 notes or\NEW{1.4} rests. Normally they
all have the same duration, but there are several options---described
below---to change this. The command for the first note of an xtuplet begins 
exactly like a 
note or rest command, with the name of the first note in the xtuplet, or
{\tt r} if it starts with a {\bf r}est (see next subsection), and an optional 
time value.  
However, the actual time value (including a dot if present and a basic 
duration that may have been inherited from the prior note) now represents the 
{\it total} duration of the xtuplet.  Next (with no space, as usual) comes 
{\tt x} followed by a one- or two-digit integer for the number of notes in 
the xtuplet.  The only options allowed immediately following the number are 
{\tt d} and {\tt n} . \NEW{2.4}{\tt d} signifies that the {\it first} note 
of the xtuplet should have a dot and the second, and extra flag.  
{\tt n} controls the printing of the {\bf n}umber and bracket. 
If {\tt n} is followed by a blank, then no number will be
printed. On the other hand, 
an \NEW{2.3}{\it unsigned} integer here is taken as a substitute number to
be printed instead of the natural one.  
If one or two {\it signed} decimal numbers follow {\tt n} 
(each starting with {\tt +} or {\tt -}), the first 
is a vertical shift in {\tt \bs internote}s, and the second, a horizontal shift 
in notehead widths. Another suboption to {\tt n} is {\tt f}, 
to {\bf f}lip the number vertically from its default position. A \NEW{2.5}final 
suboption to {\tt n} is {\tt s} followed by a signed integer. It applies only 
to non-beamed xtuplets, for which it tweaks the slope of the bracket above or 
below the xtuplet. For non-beamed xtuplets, you can further change the 
appearance of the bracket and number as explain in section~\ref{ATDirective}.

The second through last notes of the xtuplet are each then 
represented by a separate command containing a subset of the characters 
permitted for ordinary notes or rests: note name or {\tt r} (the only required 
character), accidental, and octave change character ({\tt +} or {\tt -}). 
\NEW{1.4} The octave may be given explicitly instead, and any integer will be 
interpreted as such, as no time values or dots are permitted.

The last note of an xtuplet may not be a\NEW{1.4} rest. 

To double\NEW{2.3} the duration of any note in an xtuplet, add the 
character {\tt D} to the command for that note. This will decrease the expected
number of notes in the xtuplet by one.  To add a dot to the doubled note
(as Bach sometimes did), use {\tt F} instead of {\tt D}.  
\NEW{2.4}To add a dot to one  
note and an extra flag to the next, include {\tt d} in the note command,
{\it after} the {\tt x} if it's the first note of the xtuplet as noted above.   

As an example, an ascending quarter-note triplet scale would be 
notated\hfil\break {\tt~c44x3~d~e~f4x3~g~a~b4x3~c~d~\dots} 

\subsubsection{Rests}

	The command for a rest starts with {\tt r}.  
Then for a normal rest, in either order come a digit for the basic time value 
(using same codes as for notes, optional if unchanged from previous value),  
a {\tt d} if the rest is dotted, and a second {\tt d} if double dotted.
\NEW{2.0} The basic time value of a rest 
affects future notes and rests the same as if it had come from a note, 
i.e., it applies until another value is entered with a subsequent note 
or rest in the same voice.  The command {\tt rp} represents a 
full-bar rest notated with a {\bfi p}{\it ause} character (whole rest) 
regardless of 
the time signature; in this case no other duration information is 
needed or allowed.  {\tt rb}, followed if necessary by a duration 
specifier, denotes a {\bfi b}{\it lank} rest, one that occupies space and time 
but is invisible. This is most often used when there are
two voices in a staff and one drops out for some of the duration
of the current input block.  (See {\tt mwalmnd.pmx} for examples).  
\NEW{1.4} The 
option {\tt o} (for {\bf o}ff-center) suppresses centering a full bar rest.  If
you don't exercise this option, then 
{\it all} full-bar rests will be horizontally centered between bar 
lines, including pauses ({\tt rp}) as well as normal rests that fill the bar. 
\label{MultibarRest}{\tt rm} followed immediately by an integer will generate a 
{\bfi m}{\it ulti-bar} 
rest, a special combination of characters between two bar lines with an integer 
above representing two or more bars of rest.   
This command will generally only be used in separate parts 
after having been automatically generated by {\bfx scor2prt}. However, it
\NEW{2.4}may be used in a multi-line score, provided it is entered for the same
number of bars in every staff.

	The default vertical position of a rest depends on whether there
are one or two voices in the staff. 
For one voice it is just the \MusiXTeX{} default 
(approximately centered on the middle line).  On the other hand, in  
the lower voice in 
a two-voice staff, the rest is lowered {\tt 4\bs internote}, while 
in the upper voice it is raised {\tt 2\bs internote}.  The \PMX default can be 
manually overridden by appending {\tt +}~or~{\tt -} and an integer 
representing the offset from the {\it middle} line of the staff 
(not from the \PMX default if there are two voices in the staff!).  
So for example, in a single staff 
in 3/4 meter, two voices, each with a half note followed by its own
quarter rest would be either 
\begin{verbatim}
c24 r4 //
c25 r4 / 
\end{verbatim}
or equivalently
\begin{verbatim}
c24 r4-4 //
c25 r4+2 / 
\end{verbatim}
while
\begin{verbatim}
c24 r4+0 //
c25 r4b /
\end{verbatim}
would produce two notes followed by a single, vertically centered rest.

Another way to override the default vertical positioning of rests is useful in
keyboard scores, or in fact any score containing two voices on a staff. 
The option {\tt K} (for {\bf K}eyboard) in the
{\tt A} command generally causes rests to be 
aligned horizontally with notes in the voice in which they are entered. See
section~\ref{Acommands} for a detailed description.

\subsubsection{Chords}\label{chords}

      Chordal notes, which always share a stem and the same time value as the 
prior note, are symbolized with {\tt z} (for {\bf z}ero time) followed by a note name and 
optionally an accidental, {\tt +} or {\tt -} as octave indicator, and {\tt e} 
or {\tt r} for a l{\bf e}ft or {\bf r}ight shift by one notehead width.
No basic time value is allowed.  If the main note
is dotted, then the chordal note will appear with a dot regardless of whether
a {\tt d} is entered.  The only time a {\tt d} is required in a chordal note
command is if the dot's position is to be adjusted; in this case the
{\tt d} is required, followed by one or two decimal numbers, each preceded by
{\tt +} or {\tt -}.  The first is the vertical shift in \bs{\tt internote}s;
the second, the horizontal shift in notehead widths. 
Any number of chordal notes can follow a 
single main note.  The stem direction of a chord is controlled by the main
note, but may be manually overridden with {\tt u} or {\tt l} in the main note
command.

    When chordal notes are beamed together, the default height and angle of 
the beam will be determined by the main note on each stem (the one without 
{\tt z}).  If a beam joining chordal notes looks bad, you can usually  
fix it either by changing which note acts as the main one, 
or by fine-tuning the beam parameters as described 
in section~\ref{beams}.

\PMX uses a complex algorithm to automatically position accidentals in chords. 
If you are unhappy with the result, you can manually tweak the horizontal 
positions as described in section~\ref{AccidentalPosition}.

Although there is no dedicated command for it, chords can be made to span from
one staff to another using various techniques\NEW{2.73}. The approach will depend on
whether 
the chord is single-stemmed with no flag, single-stemmed with a flag, or beamed. 
If beamed, it will also depend on whether it is an xtuplet or not. Examples of all
the basic possibilities are contained in the sample file {\tt staffcrossall.pmx}.  

For unbeamed, unflagged staff-crossing chords, 
by lengthening the stem with the {\tt L} option on the main note, it can 
be made long enough to join with an unflagged single-stemmed note or chord in the 
next staff. Single-stemmed notes with one or more flags can be joined across staves 
with a trick discovered by Andre Van Ryckeghem: In one staff create a standard note or 
chord with 
the stem pointing away from the other staff. In the other staff, place the chord notes
in a one-note forced beam that has been lowered or raised into the first staff
(e.g. {\tt [-10 b14 ]}); that
will stretch the stem to join the other notes, but with just one note (or chord) in the
beam, the crossbar will have zero length and be invisible. 

Beamed chords may also span from one staff to another, using joined beams (see 
section~\ref{beams}). The general approach is to construct a set of chords 
(or single notes, if the other chord notes are in the other staff) in each of
the two staves, enclose each set in a separate forced beam, and join the two 
beams with {\tt ]j}...{\tt [j}~. It is important to remember that the
lower staff is processed first. So in most cases, the end of the segment in the lower
staff must be joined (using {\tt ]j}) to the start of the upper segment (with {\tt [j}).
It turns out that for non-xtuplet beamed chords, in all cases where the chord at the 
beginning of the beam has a note 
in the {\it lower} staff, this works fine provided that the forced beams are of equal
duration and cover the same time span, and that positions in either staff with no note 
are represented with 
blank rests \bs{\tt rb} inside the force beam. So for example a set of beamed chords 
that starts only in the
lower staff and ends only in the upper could be represented by

\medskip
{\tt [+28 g83 g g rb ]j /

[jf rb g84 g g ] /}
\medskip

This example highlights some other issues, viz., that the beam height or direction of one 
or both beam groups may need to be altered. Often this will require trial and error. 

Unfortunately this two-group procedure breaks down if the first chord in the beam has no
notes in the lower staff. There are tricks to get around this; the user is referred to
the file {\tt staffcrossall.pmx} for examples. However, there is a much more 
straightforward way to define 
staff-crossing beamed chords that begin in the upper staff: it simply requires defining 
the beamed group in each staff as an xtuplet within a forced beam. It turns out that 
the treatment of 
staff-crossing beamed xtuplets is more robust than for non-xtuplets, and will admit
more intuitive coding. So for example, the reverse of the above example, where
the beam starts in the upper staff and ends in the lower, could be obtained with

\medskip
{\tt [+28 rb2x4n g3 g g ]j /

[jf g24x4 g g rb ] /}

\medskip
\newdimen\psav\psav=\parindent\parindent=0pt where we used the option {\tt n} to  
suppress printing the number. As you might expect, more general staff-crossing 
beamed chordal xtuplets follow the same concepts already described for non-xtuplets,
but as noted, they are more robust and admit patterns that start in the upper staff
and end in the lower one. {\tt staffcrossall.pmx} also contains examples this
approach.
 
\parindent=\psav

\subsubsection{Grace notes}\label{graces}

	A grace note command starts with a {\tt G}.  It is entered in its natural
order, normally before the main note, but sometimes after.  After {\tt G} and
before the note name, comes any 
combination of the following options: an unsigned integer (which may have 2 digits)
representing the number of 
notes in the grace (default is 1), {\tt m} and a digit for 
{\bfi m}{\it ultiplicity} 
(number of flags or beams, default is 1, 0 is allowed), 
{\tt s} for {\bf s}lur (joining all notes of the 
grace to the main note; no other {\bf s} is needed on the main note), 
{\tt x} for a slash (only for single graces), 
{\tt l} or {\tt u} to force the direction of the stem(s), 
{\tt X} followed by a decimal number {\it x} to insert a gap of {\it x}
notehead widths between a normal grace and its main note\NEW{2.6},
{\tt A} (for
{\bf A}fter) or {\tt W} (for {\bf W}ay-after) to associate 
the grace note with the {\it prior} note.  Next comes the only 
required character, the 
first note name.  No time value can be entered, but if needed, the 
octave or an accidental can be given as in a normal note.  Second and 
later notes must follow immediately in sequence, set apart by spaces, likewise 
without any time value, and without any intervening commands.

	Normal or after-graces will be placed {\it immediately} before or after
the main note; way-after's, as far to right as possible before the next note 
or bar line.  If either type of after-grace is slurred, the slur will start 
on the main note and end on the last one in the grace.  
	

\subsubsection{Ornaments}

	Commands for ornaments are entered {\it after} their associated 
note command.  The ornaments now available are shake ({\tt ot}), {\bf m}ordent 
({\tt om}), ``x"- or ``+"-shaped ornament symbols ({\tt ox, o+}), pizzicato 
({\tt ou}), strong {\bf p}izzicato ({\tt op}), left parenthesis before
notehead ({\tt o(}), right parenthesis after notehead ({\tt o)}), 
upper {\bf f}ermata ({\tt of}), {\bf d}own {\bf f}ermata ({\tt ofd}), 
staccato ({\tt o.}), tenuto ({\tt o\_}), two different se{\bf g}nos 
({\tt og} or {\tt oG}), {\bf C}oda ({\tt oC})\NEW{2.71}, 
arbitrary-length wavy-line {\bf t}rill with {\it tr} ({\tt oT}), 
arbitrary-length wavy-line
trill without {\it tr} ({\tt oTt}), sforzando ({\tt o>}), 
%duncecap ({\tt o}\hbox to 6pt{\tt\^~}), \NEW{2.4}{\bf c}aesura ({\tt oc}), and 
duncecap ({\tt o\verb|^|}), \NEW{2.4}{\bf c}aesura ({\tt oc}), and 
{\bf b}reath ({\tt ob}).
All except the parentheses, staccato,
tenuto, and down fermata will normally 
appear above the staff; the parentheses appear at the level of the note 
head, and staccato and tenuto just above or below depending on the 
stem direction.  The only difference between staccato and 
pizzicato is the vertical positioning of the dot.

Either type of trill may immediately include an unsigned decimal number 
to specify the length of the printed symbol in current \bs{\tt noteskip}s; the 
default is 1. Thus {\tt oT0} represents {\it tr} with no wavy line.

Once the ornament type has been specified, most of them can be raised 
or lowered from their default position by appending
a signed integer to the command, representing the vertical offset
in \bs{\tt internote}s. \NEW{2.4}. A second signed integer specifies a 
horizontal shift from default in notehead widths.  

The caesura and breath marks differ from the others in their default horizontal position, 
which is 0.5\bs{\tt noteskip} past the note. 

The {\tt og} segno has several special properties. It must be entered in the first (lowest) 
staff, but will appear above
every staff. Its vertical position cannot be altered, but if appended by a number...unsigned
if positive...all appearances will be shifted horizontally by that number of points. On the 
other hand, the {\tt oG} segno\NEW{2.71} has a smaller symbol than {\tt og}, 
applies only to the note after which it is entered, and can be shifted just as a 
normal ornament.

     An ornament can be automatically repeated on a series of consecutive notes,
provided the notes are all in the same voice and the same input block.  
To activate this feature, terminate  
the first ornament command with~{\tt:}~.  Then every note in that voice will 
have the same ornament until a note is followed by the repeat terminator
{\tt o:} . 

\subsubsection{Editorial accidentals}

     To place a small sharp, flat, natural, or question mark above the staff, 
after the affected note enter {\tt oe} followed by {\tt s, f, n} or {\tt ?}. 
\NEW{2.2} You may also put a question mark right after the accidental.

\subsubsection{Slurs} \label{slurs}

        By default \PMX will use \MusiXTeX's built-in font-based slurs.
But through user intervention it is possible to use either one of 
\NEW{2.4}two different types of postscript slurs. {\it Type K} slurs, 
developed by Stanislav Kneifl, are directly supported by \PMX and will
be the focus of any future \PMX enhancements. 
They are globally activated with {\tt Ap} and several global
defaults set with other options to the {\tt A} command as described in
section~\ref{ApDirective}. If these are used, so will an alternate
set of hairpins (see section~\ref{dynamics}).   
The other postscript slur option is Hiroaki Morimoto's {\it Type M} slurs. 
These
are not directly supported by \PMXX, but are intended to be fully
compatible with the default font-based slurs. To use them, one would
use the in-line \TeX~command \bs\bs{\tt input musixpss}\bs~, and be sure
{\it not} to enter {\tt Ap} .  From \PMXX's standpoint they are no different
from font-based slurs.

There are some advanced options available only
with Type K postscript slurs, and a few obsolete ones only with font-based.
At this point the main
difference in functionality between the two is that with postscript, \PMX
provides support for 
true ties, which are shaped and positioned slightly differently from
slurs.  Future enhancements
will probably only work with Type K postscript slurs. Some users do still 
prefer
font-based, possibly because Type K postscript slurs are not visible in some 
DVI viewers. 
New users should experiment with the various types of slurs and decide for
themselves.

	The normal commands for slurs are {\tt (} placed with a space 
before a note, and {\tt )} placed after.  The command {\tt s} is equivalent to
{\it both} of them (!), except that it always follows the affected note.
With font-based slurs, {\tt t} is equivalent to {\tt s} but 
with several minor differences to be explained later. With postscript slurs,
{\tt t} signals to use a true tie.
The commands {\tt s} and {\tt t} are {\it toggles}, turning
a slur or tie off if it's already on and starting one otherwise.

A \NEW{2.5} slur or tie may end on a rest, but not start on one. The default 
ending height in this case will be the same as the starting height, and it 
may be tweaked as described below.

   The first character is optionally followed by
a single-character ID code {\tt 0-9} or {\tt A-Z}, then by other
options described below.  ID codes are only needed if two or more slurs are 
open at the same time within one voice, such as when several chord 
notes are tied.  Using ID codes in such cases tells \PMX which open slur to
close. ID codes cannot be used with font-based {\tt t} slurs. 
 
The rules for finding the default direction and position of a slur
are complex; many factors enter into defining visually pleasing values.  But 
there's no need for gory details here; the result will usually satisfy, and if 
not, it can easily be tweaked.  The default direction of curvature can be 
overridden with {\tt u} ({\bf u}pper), {\tt l} ({\bf l}ower),
or equivalently {\tt d} ({\bf d}own).  
Starting or ending position can be shifted from its default by
entering one or two explicitly signed numbers.  The first, which must be
an integer, represents the vertical shift in \bs{\tt internote}s; the second,  
which may be decimal, the horizontal offset in notehead widths. \NEW{2.71}Starting 
or ending
position of a postscript slur or tie can be made to align with the end of the stem 
of an unbeamed note by using the option {\tt v}. No other options are permitted
with {\tt sv}, but any desired position can be forced with the numeric options.

The shape of the slur may be altered as well\NEW{2.1}. This paragraph
deals with font-based slurs, for which the shapes may be less 
than fully satisfying due to fundamental limitations of \MusiXTeX.
At the slur termination only, one or three
more parameters may follow the ones just described.  The first, a signed,
nonzero
integer, is a vertical adjustment to the mid-height of the slur in  
\bs{\tt internote}s.  The next two, integers between 1 and 7 following a 
``{\tt :}", are alterations to the starting and ending slopes.
These numbers are
passed directly as arguments of the \MusiXTeX{} macros \bs{\tt midslur}
(if only
one is given) or \bs{\tt curve} (if there are three).

For \NEW{2.4}Type-K slurs,
the shape may be changed locally by including {\tt f} in either the
slur's starting or ending command to flatten it a bit, or {\tt h},
{\tt H}, or {\tt HH} to
increase its curvature and raise or lower its middle by increasing degrees.
The default \NEW{2.5}curvature can be altered from normal 
with new suboptions 
to {\tt Ap} as described in section~\ref{ApDirective}. Local 
curvature tweaks will take precedence over the global default. A special 
option {\tt n} to the slur command can be used to locally restore the normal
curvature if the default curvature has been globally changed.

Another option peculiar to Type-K slurs and ties is to locally 
override the global
setting for automatic height adjustment (to avoid tangencies with staff
lines).  The global defaults may be changed with the {\tt A} command as
described in section~\ref{ApDirective}. To
override the global setting for the current slur or tie only, use
the option {\tt p} in the command that starts the slur or tie,
followed by {\tt +} or {\tt -} (to turn adjustment
on or off), followed by {\tt s} or {\tt t} (for slur or tie). 

A dotted \NEW{1.41} slur is activated by including the option {\tt b} (for
{\bf b}roken) in the command that starts the slur. 

Slurs involving grace notes are specified within the command for the grace 
(see section~\ref{graces}).

For font-based slurs, the unique aspect of {\tt t} slurs is that if one
starts or ends on the same
note as an {\tt s} slur, the former will be moved away from the notehead to 
avoid a collision.  {\it This only works if neither slur has an ID code.}
This feature is only retained for backward compatibility.

The available options should cover most circumstances, but if not, 
the \TeX\ macros \bs{\tt isu} etc, defined in {\tt pmx.tex}, can be entered 
as in-line \TeX\ commands (see section~\ref{LitTeX}).  
These commands have three arguments: 
slur number, vertical position (pitch, or offset from bottom staff line in 
\bs{\tt internote}s), and horizontal offset in
notehead widths.  When using these commands, you must choose an explicit
slur number.  Use one large enough to avoid
conflicts with \PMXX 's automatic slurs, which are numbered from \NEW{2.4}
0 upward. 
Also, remember that non-spacing in-line \TeX\ commands such as this one must 
come {\it before} the note they apply to, in contrast with the \PMX 
slur toggles which may come after.  

\subsubsection{Ties}

With font-based slurs, in \PMX the only difference between ties and slurs
is the default positioning.
Ordinary slur ends are centered horizontally above or below the notehead, 
while tie ends are shifted inboard and closer to the midheight of the 
notehead.  To specify a font-based tie in \PMXX, use a slur command and 
include the option {\tt t} 
in it, somewhere after the initial {\tt ( , ) , s } or {\tt t} .

\NEW{2.4} With postscript slurs, ties---indicated with {\tt t} or
{\tt st}---will have similar differences
in endpoint positions,
but in addition will have a different shape (somewhat flatter) and will
always end at the same height they start. There is also an option to the
{\tt A} command that affects ties across line breaks 
(see section~\ref{ApDirective}). By default the 
second part of such ties will be drawn as a complete tie symbol.  However,
if you want them to be a {\it half tie}---a special shape that is horizontal
at its left end---use the command {\tt Ap+h} at the start of the file. 

In addition to the notation options just mentioned, ties may also be 
%indicated with the character {\tt\{} before the starting note and {\tt\}} after
indicated with the character {\tt$\{$} before the starting note and {\tt$\}$} after
the ending note\NEW{2.6}.

\subsubsection{Line-breaking Type K slurs and ties} \NEW{2.5} \label{lbslurs}

No special action is required if a slur or tie happens to cross a line break.
However, some special, manual adjustments are available for Type K postscript
slurs in these cases. The global option {\tt Apl} by itself adjusts several 
parameters as described in section~\ref{ApDirective}. Further, if {\tt Apl} 
has been issued, 
then case-by-case adjustments for line-breaking Type K slurs and ties are 
available as suboptions to the
slur commands. To tweak the horizontal and vertical positions of the end of 
the first segment, enter the suboption {\tt s} in the command that starts 
the line-breaking slur or tie, followed by two signed numbers representing 
respectively the vertical shift 
in \bs{\tt internote}s and the the horizontal shift in notehead widths. To
tweak the position of the start of the second segment, follow the above by 
another {\tt s} and two more signed numbers. The usual curvature options 
{\tt h}, {\tt H}, {\tt HH}, and {\tt f}, if included in
the starting command for a line-breaking slur, will apply only to the first
segment, and if in the closing command, to the second segment. If the tweaked 
slur or tie does not happen to come at a linebreak,
the special position tweaks (after {\tt s} ) will all be ignored, and the 
curvature tweaks on the closing note will take precedence as they normally 
would.

\subsubsection{Dynamics} \label{dynamics}

\NEW{2.3}
After the affected note, enter {\tt D} followed by one of the 
following {\tt pppp, ppp, pp, p, ffff, fff, ff, f, mf, mp, fp, sfz,
"[{\it any text}]", >,}
or {\tt <} .  The last two are diminuendo and crescendo, and they are toggles, 
i.e., the first one of each starts the symbol and the next one ends it.  
The one surrounded by double quotes is an arbitrary text string.
With any dynamic mark, you can also 
enter position shifts, vertical as a signed integer representing
the number of {\tt \bs internote}s, then horizontal as a signed number representing 
number of notehead widths.  There can only be one of the letter-groups on each 
note, but there may also be {\tt D<} and/or {\tt D>} on the same note.  These must be 
entered as separate {\tt D...} commands, and must come in the right order, e.g.,

\medskip
[{\it some notes}] {\tt D<} [{\it more notes}] {\tt D< Dffff D>} 
[{\it more notes}] {\tt D>}
\medskip
 
Hairpins \NEW{2.7} may span from one input block to the next.  

There are numerous context-sensistive automagic adjustments to the positions 
of all the dynamic symbols.  If you don't like the result you can adjust the
position as just described.  

Due to \MusiXTeX's limitations, 
there are some restrictions on hairpins when using font-based slurs.
They cannot be longer than 68mm, they cannot wrap over a system break, and they
must be horizontal. Finally, 
only certain specific lengths are available so some horizontal position
tweaking may be needed, especially when letter-groups and 
hairpins are combined.
These restrictions are all removed when using postscript slurs.

\subsubsection{Beams} \label{beams}

	For the most part, \PMX automatically takes care of the details of 
defining beams: selecting which notes are beamed together, and setting 
the angle, direction, height, and {\it multiplicity} (the number of bars 
along the top or bottom).  However, one may define a {\it forced} 
beam---which overrides \PMXX 's selection of which notes are beamed 
together---by 
surrounding the included notes with {\tt [} and {\tt ]}, being certain to 
separate these commands and their options from the included note commands with
spaces.  One may also wish to edit certain features of a beam even when 
\PMXX 's grouping decision 
would otherwise be acceptable; here again the beamed notes must be set 
apart with {\tt [} and {\tt ]}.  

The {\tt [} may optionally be followed 
immediately by several options. 

{\tt u} or {\tt l} will override 
\PMXX 's selection of the direction of the beam, while {\tt f} will
{\bf f}lip it from whatever \PMX decided. 

{\tt j} {\bf j}oins the beam
grouping to a prior one started in another system (see below).  

One, two, or three consecutive integers, each preceded with {\tt +} 
or {\tt -} , will affect the beam's appearance.  The first integer is 
an adjustment to the starting level (in \bs{\tt internote}s) and may range 
from -30 to 30; the second is a slope adjustment with the same 
permissible range; the third is an alternate adjustment to the 
starting level (in beam thicknesses) and may only range from 1 to 3, 
always acting to increase the stem length.  The latter may be used to 
align consecutive horizontal beams which have internal multiplicity 
changes.  For example, in 2/4 time, {\tt c84~c1~c~c~c~c8} would cause two 
beams but the 
first one would be lower than the second; {\tt [+0+0+1~c84~c1~c~]~c~c~c8}
would align the tops of the beams with each other.  Due to the 
complexity of \PMXX 's beam analysis procedures, these editing commands 
may sometimes produce unexpected results, and some iteration may be 
required to get exactly what you want.  For example, 
{\tt [+0+0+3~cd8~c3~c6~c~]~c~c~c3~cd8} 
will not produce two aligned beams as desired, because 
when \PMX analyzes the first beam, it automatically raises the starting 
level a bit for another reason, namely, to avoid too short a stem on 
the 64th notes at the end of that beam.  In this case, 
the user could counteract \PMXX 's internal adjustment by using 
{\tt [-1+0+3~cd8~c3~c6~c~]~c~c~c3~cd8}.

The character {\tt m} followed by a digit 1-4 forces the {\bf m}ultiplicity 
of the
beam, the number of stem-joining bars.  

The option {\tt h} forces the beam to be {\bf h}orizontal.

        By default, xtuplets are set apart with their own beam.  To beam 
an xtuplet together with other non-xtuplets, just include it with the 
other notes in a forced beam.

        Rests may also be included within forced beams, provided they are 
shorter than quarter rests, and of course that they come {\it between} the first
and last notes under the beam.

It's \NEW{2.5} now easy to define a repeating forced beam pattern. 
If the option {\tt :}~(colon) is included in the starting command {\tt [}~for 
a forced beam, then after you end the beam, more beams of the same duration 
will be forced in 
that voice, until stopped. They will be stopped at either the next regular 
forced beam, or the end of the input block for that voice, whichever comes 
first.

	Some users may wish to define beamed groupings with subgroups 
joined by a single beam.  The command {\tt ][}, standing alone between two 
note commands in a forced beam, causes the multiplicity to decrease to 
unity and immediately increase to its natural value for the next note.  
For example, {\tt [~c14~c~c~c~][~c~c~c~c~]} will generate two doubly-beamed 
groups connected by a single beam.

Related \NEW{2.3} to this is a {\it single-slope beam group}, which is the 
same as described
in the previous paragraph except that the beam disappears between segments. 
Segments should be separated by {\tt ]-[} standing alone between two notes 
inside the forced beam.

        If there are large jumps in pitch between notes in a beam within
a single staff, as a matter of taste you may wish 
to start the beam for example as an upper one and end it as a 
lower.  \PMX will never do this automatically, but you can accomplish
it by forcing the beam with appropriately modified up/down-ness, starting level,
and slope.  If you use this technique, there are two details to note: (1)~if 
there are any intermediate multiplicity changes, they will only be handled
properly if the initially specified up-down-ness is consistent with the 
vertical position
of the intermediate notes involved, and (2)~for proper appearance in crowded
scores you may wish
to insert hardspace or shifts as described in 
section~\ref{hardspace}.  Some examples are included in {\tt most.pmx}. 

       Beams cannot normally jump staves.  But if that is desired, start
the beam normally in one staff, and terminate the part of the beam in that
staff with {\tt ...~]j} .  Then resume the beam in the new, adjacent staff with 
{\tt [j~...} . For staff-jumping beams, it's OK to have just a single note 
inside one or both of the members.  Some adjustment of the beam height and
slope may be required.  Sometimes the ending section's up-downness must be 
overridden; you will know this is so if the ending is shifted horizontally 
from its proper position by one notehead width.  
Each voice must still have the right number
of beats, so you will probably need to fill time with blank rests after the 
first member of the beam in one staff and before the second member in the other.  
There can
still only be one staff-jumping beam open at a time. 

\subsubsection{Clefs}

	A clef change is signaled by {\tt C} followed by a single lower-case 
letter or digit using the code specified in 
section~\ref{ClefCodes}.  If clefs come out at the wrong 
vertical position, refer to the note in {\tt pmx.tex}.

\subsubsection{Arpeggios}

To set an arpeggio (a vertical wavy line), simply place the command {\tt ?} 
after the commands for both the first and last note. To shift the symbol to
the left by {\it x} notehead widths, use the option {\tt -}[{\it x}]\NEW{2.6} . 

\subsubsection{Lyrics}\NEW{2.73}\label{lyrics}

Lyrics depend on the underlying \TeX\ command {\tt\bs pmxlyr} developed by Dirk
Laurie, which is defined in {\tt pmx.tex}. It in turn makes use of the macro 
package {\tt musixlyr.tex} developed by Rainer Dunker. So to enable lyrics within \PMXX, 
you will need to 
ensure that {\tt musixlyr.tex} is installed somewhere in your system where your 
\TeX\ processor can find it. 

Lyrics can be inserted by enclosing them in double-quotes inside the music line 
just before the first note to which they apply, as in
{\tt "us-ing lyr---ics now\_\hglue1pt\_ "}. Once the first double quote is encountered, \PMX will
ensure that {\tt musixflx.tex} is input into the \TeX~file. 

Lyrics for several notes can be defined in one go. 
The lyrics in each input string demand a specific number of notes, depending on
the number of syllables, hyphens, and underscores. If there are not enough lyrics, 
question marks will appear; if too many, the excess syllables will not appear.

The rules for aligning lyrics properly with notes are as follows. Words are 
separated by whitespace, with any number of spaces counting as one. Syllables
within a word that require just one note each are separated by a single hyphen. There are 
two ways to extend a syllable over two or more notes. If it is the last syllable in 
a word (like {\tt "now\_\hglue1pt\_ "}), follow it with consecutive underscores, one for each extra 
note, and finally a space. It will be printed with a continuous underscore. 
To extend a syllable within a word (like {\tt "lyr---ics"}), insert one extra hyphen
(with no spaces) for each 
extra note, and it will be printed with some number of hyphens filling the proper 
space between syllables. Conversely, a tilde ({\tt \char126}) between two words 
(with no spaces) prints a space between them while assigning the last syllable of the 
first and the first syllable of the second to a single note\footnote{This is just an 
example of using a standard \TeX\ feature within lyrics.}. So in the end, in a voice 
with lyrics, every note must be associated with a syllable, its extension, or two 
syllables joined with a tilde.

Although underscores within a word or consecutive hyphens at the end may not crash the 
code, they are not recommended for any foreseen useful purpose.

By default, lyrics will be placed below the staff where they are entered, half way between that 
and the next lower staff. You may want to 
alter the vertical position of a lyrics line, especially if both voices in 
a staff have lyrics. This is accomplished with the opfion {\tt @}, immediately
following the closing quote of the 
lyrics string with no space. That must be followed by either {\tt a} or {\tt b} for 
{\bf a}bove or {\bf b}elow the staff, then a signed integer for the number of 
\bs{\tt internote}s above or below the default height. This command is "sticky"; it
will remain in force for later lyircs in the same voice until altered.

It may also be necessary to allow extra vertical space where the lyrics are positioned. 
There is no \PMX command for this, but type 2 inline \TeX~can be used to insert extra
vertical space above any instrument. For example, if the voice is in instrument \#2 and
lyrics are below that staff, 
\bs\bs{\tt interinstrument=0\bs internote\bs\bs setinterinstrument1\{8\bs internote\}}\bs~ will
add \newline 8 \bs{\tt internote}s in the space for the lyrics.

Present limitations allow lyrics at upper and lower voices on the bottom two 
staves of instruments 1 to 4. Elsewhere they are quietly ignored.

Most scores with lyrics will benefit from the type 2 command \bs\bs{\tt sepbarrules}\bs, which
stops bar lines from crossing through the vertical space between instruments.
 
The notation {\tt "us-ing lyr---ics now\_\hglue1pt\_ "} is actually shorthand for the inline \TeX\  
string {\tt\bs pmxlyr\{us-ing lyr---ics now\_\hglue1pt\_ \}\bs}. All the rules given in 
section~\ref{LitTeX}~for 
Type~1 \TeX\ strings apply. To ensure that the length of all the Type 1 \TeX\  
strings belonging to a particular note combined does not exceed 128, remember 
to account for the nine characters in {\tt\bs pmxlyr\{\}}.

This way of entering lyrics is a convenient interface to a small subset of the 
facilities offered by {\tt musixlyr}. If more advanced features than those supported by
{\tt\bs pmxlyr} are needed, the necessary {\tt musixlyr} macros could be entered as 
in-line \TeX\ directly into the .pmx file - see the example file {\tt netsoos.pmx} for 
some of those.

If really advanced features are needed (such as having several verses of lyrics 
at once), most users would prefer the convenient interface to {\tt musixlyr} via 
the program {\bfx M-Tx} developed by Dirk Laurie. It is a pre-preprocessor which produces 
a {\tt .pmx} file containing the proper in-line \TeX\ commands. Its input language 
is similar (but not identical) to \PMX and includes most \PMX functionality as a subset.

\subsection{Commands That Affect All Voices}  \label{pmxcmds}

	Most commands that affect all the voices can only appear in the first 
(lowest) voice in the first (lowest) staff. Most such commands will 
automatically be 
transferred from score to parts when separate parts are generated by 
{\bfx scor2prt} (see section~\ref{scor2prt}). 

\subsubsection{Repeats, double bars, forced single bars}

	Repeat signs, double bars, and other bar-ending options are signaled 
by {\tt R} followed by 
{\tt l, r, lr, d, D, dl, b} or {\tt z} for 
{\bf l}eft repeat, {\bf r}ight repeat, {\bf l}eft-{\bf r}ight repeat, 
thin-thin {\bf d}ouble 
bar, thin-thick {\bf D}ouble bar, thin-thin {\bf d}ouble bar followed by
{\bf l}eft repeat, single {\bf b}ar, or blank (invisible) barline\NEW{2.4}. 
Some of these have peculiarities.
{\tt Rb} forces a single bar before a movement break (see section~\ref{movbrk}), 
where otherwise by default there is a double bar.  That can be useful for
example if you
change the number of instruments (via an option in the movement-break command)
in the middle of a movement.  {\tt Rz} will cause a blank barline at the end
of the current system, not necessarily the current bar. It can be used 
together with blind meter changes if you want to split a bar across a
system break.  
If {\tt Rlr} falls at a system break, \PMX will automatically split it in 
two.  The command {\tt Rdl} will likewise be split at a system break, but if
not at a system break, the {\tt d} will be ignored. 

These commands must be in the 
first voice.  It is best only to place them before the first note in an 
input block or if necessary after the last one; otherwise {\bfx scor2prt} 
may behave erratically.  
Using two separate {\tt R} commands in succession will cause 
unpredictable results.  


\subsubsection{Voltas (first and second endings)}

	Beginnings and ends of first and second endings are signaled by 
{\tt V} (for {\bfi v}{\it olta}).  
If it's the {\it end} of the volta, add the option {\tt b} (for 
{\bfi b}{\it ox}) or {\tt x} for {\it no bo}{\bfi x}.  
If it's the {\it start} of a volta, you can 
optionally enter any text at all that doesn't include a space and doesn't 
start with {\tt b} or {\tt x} (most 
commonly {\tt 1} or {\tt 2}).  A period will automatically be 
appended to the text.  If one volta ends and another starts right 
away, only a single {\tt V} is needed.  Voltas must only be entered in the 
first voice.  If separate parts are to be created from a score using 
{\bfx scor2prt}, then only a single volta is allowed in any given input 
block, and it must be at the beginning of the block.

\subsubsection{Meter changes}\label{MeterChange}

     Meter can only be changed at the beginning of an input block.  
A {\bfi m}{\it eter change} command starts with the letter {\tt m}.
There are two different ways to complete the command.

{\bfx Method 1.}  Enter 4 numbers 
with no intervening spaces.  The four numbers are {\tt mtrnuml}, 
{\tt mtrdenl}, {\tt mtrnmp}, {\tt mtrdnp} as defined in section~\ref{setupdata},
with the following exceptions for this method only:     
You must use {\tt o} to represent 
the number 1; if you enter the digit {\tt 1} then \PMX will interpret that 
digit and the next as a 2-digit integer, between 10 and 19 inclusive.
19 is the largest number that can be entered with this method. Note that 
{\tt mtrdenl=0} still represents a whole note.

{\bfx Method 2.}  \NEW{1.4} Enter the four numbers verbatim in the order just 
listed, but separate them with slashes ({\it /}).

\subsubsection{Fundamentals of key changes and transposition}\label{transpose}

As explained in section~\ref{setupdata}, the intial key signature, also called
the concert key, is specified in the setup data. In order to change the key
signature or to transpose (i.e. make the printed notes appear at a different 
level than where 
they were entered), use the {\tt K} command. The syntax is {\tt K}[{\it n}][{\it k}] 
where {\it n} and {\it k} are explicitly signed digits respectively giving the distance 
to transpose in \bs{\tt internotes}, and 
new key signature. When transposing, you should always use relative accidentals, activated by
the separate command {\tt Ar} at the start of the first input block (see section~\ref{ArDirective}). 
For example, to transpose a piece in C major to E major you would enter 
{\tt Ar~K+2+4} at the beginning of the first block. 

To transpose by a half step to a key with the same
letter name, use {\tt K-0}[{\it k}] where as before {\it k} is an explicitly signed integer giving
the new signature. 
(Using {\tt -0} instead of {\tt +0} eliminates confusion with a simple key 
change, see the next paragraph.)

A simple key change can be signalled at the start of any input block. Use
the command {\tt K} with {\it n}={\tt +0} as the first argument and the new key signature as the second.

If the signature changes from sharps to flats
or vice-versa, the default will be to include naturals in the first instance of the new
signature. To suppress this behavior, use the \NEW{2.7}option {\tt n} right after {\tt K} .
For example, to change from
2 flats to 3 sharps and suppress the naturals, enter {\tt Kn+0+3} .

The procedures described above will affect all instruments in the score. To change the key of or
transpose just a single instrument, use Ki[{\it m}][{\it n}][{\it k}] when {\it m} is an unsigned integer 
representing the instrument number, and {\it n} and {\it k} are as just described. 
For more than one instrument, you may immediately repeat everything after {\tt K} (including {\tt i}). 
This may come either at start of score (right after setup) or at the beginning of any later input
block. But if it's later, it must be preceded by a normal 
(full score) non-transposing key change command {\tt K+0}[{\it k}]. 
For example, to change the keys of the second and third instruments to one sharp and two sharps
respectively, use {\tt Ki2+0+1i3+0+2} .

\subsubsection{More on transposition; ``transposing'' instruments and example files}

In practice, two fundamentally different situations may arise: (1) (Full-score transposition) A 
score that has been entered in one key
is to be completely transposed to a different key and pitch level, usually to force the range to fit
different instruments than original; or (2) (``Transposing''
instruments) some of the instruments require a part printed in a different key and at a different
pitch level than it sounds.

To transpose
an entire score from the key specified in the setup data (Case TTA), simply use the 
{\tt K} command at the
beginning of the first input block, as outlined in the previous section. 

It gets more complicated when some transposing instruments are involved, 
because there are three different possibilities:
(Case~CTS)~The transposing instruments can be entered in concert key but printed
transposed in the score and in separate parts created with {\bfx scor2prt} (see 
section~\ref{scor2prt});
(Case~TTS)~They can be entered transposed and printed transposed in
both the score and in parts;
(Case~CCS)~They can be entered in concert key and printed in concert key in the score, but
printed transposed in parts. Matters are further complicated if there is a later key 
change. Finally, if a MIDI file is to be produced, then in cases CTS and TTS an additional 
step involving the transpose option to the MIDI command {\tt I} 
(see section~\ref{MIDI}) must be taken. 

All of the required commands for all four of these cases are summarized in the table
below. Following that, they are discussed a bit further and illustrated in 
four example files (named [Case]{\tt .pmx}) that are also included in the distribution.

\font\smaller=cmr10
{\smaller
\begin{center}
  \begin{tabular}{cllcll}
    \hline
    Case & PMX entry & Printed score & MIDI pitch & Initial commands & Later key change \\
    \hline
     TTA & All B flat major, & All transposed up & transposed & {\tt K+2+2} & {\tt K+0-5} \\
     ~ & later key change      & 2 steps to D     & ~       & {\tt I}     & ~           \\
     ~ & to B flat minor       & major, later to D & ~       & ~           & ~           \\ 
     ~ & ~                     & minor             & ~       & ~           & ~           \\ 
    \hline
     CTS & All B flat major,   & Trombone (1)      & concert & {\tt Ki2+5+1i3+1+0} & {\tt K+0-5} \\
     ~ & later key change      & concert; alto sax & ~       & {\tt IT+0-5-1}     & {\tt Ki2+5-2i3+1-3} \\
     ~ & to B flat minor       & (2) transposed up & ~       & ~           & ~           \\ 
     ~ & ~                     & 5 to G, later G   & ~       & ~           & ~           \\ 
     ~ & ~                     & minor; clarinet (3) & ~       & ~           & ~           \\ 
     ~ & ~                     & transposed up 1 to & ~       & ~           & ~           \\ 
     ~ & ~                     & C, later C minor. & ~       & ~           & ~           \\ 
    \hline
     TTS & Trombone (1)      & Trombone (1)      & concert & {\tt Ki2+0+1i3+0+0} & {\tt K+0-5} \\
     ~ & concert; alto sax     & concert; alto sax & ~       & {\tt IT+0-5-1}     & {\tt Ki2+0-2i3+0-3} \\
     ~ & (2) transposed up     & (2) transposed up & ~       & ~           & ~           \\ 
     ~ & 5 to G, later G       & 5 to G, later G   & ~       & ~           & ~           \\ 
     ~ & minor; clarinet (3)   & minor; clarinet (3) & ~       & ~           & ~           \\ 
     ~ & transposed up 1 to    & transposed up 1 to & ~       & ~           & ~           \\ 
     ~ & C, later C minor.     & C, later C minor. & ~       & ~           & ~           \\
    \hline
     CCS & All B flat major, & All B flat major, & concert & {\tt \%2K+5+2} & {\tt K+0-5} \\
     ~ & later key change      & later key change  & ~       & {\tt \%3K+1+0}     & ~           \\
     ~ & to B flat minor       & to B flat minor; & ~       & ~           & ~           \\ 
     ~ & ~                     & parts printed    & ~       & ~           & ~           \\ 
     ~ & ~                     & transposed        & ~       & ~           & ~           \\ 
    \hline
  \end{tabular}
\end{center}
\medskip
}

{\bfx Case TTA: Full score transposition.}
Here the entire score is to be transposed. In the setup data the signature is set to -2. Then
the command {\tt K+2+2} says to transpose up 2 steps from the initial key of B flat to D, and put 2
sharps in the key signature. No special attention is needed for the MIDI; it will come out in the
transposed key. A later (full-score) key change requires another {\tt K} command, but now the
transposition parameter is set to 0 and the new key is the concert key (I guarantee people will be
confused by this). In the example the command for the signature change is {\tt K+0-5} , making the
new concert key B flat minor with 5 flats, and, considering the initial transposition, causing the
score and MIDI to come out in D minor with 2 flats.

{\bfx Case CTS: Parts all entered in concert key, but some transposed in the printed score.}
Here, to produce the
printed score, parts are all entered in concert key, but instrument-wise transposition is used for
the transposed instruments. In the example the alto sax part is entered in B flat but will be
transposed up 5 steps in the printed score, to G major. This is brought about with {\tt Ki2+5+1} . Similar
logic applies to the clarinet part, while the trombone part is not transposed. If a MIDI file is
desired, it will come out in concert key, but only after using the transpose option in the MIDI
command to undo the transpositions caused by the K command. In the example the command
{\tt IT+0-5-1} does this, ``de''transposing each of the three instruments by the necessary number of
steps. For a later key change, first the full-score {\tt K} command changes the concert key, then the
instrument-wise {\tt Ki command}, with the same transpositions as the initial one, sets the new key
signatures for the transposing instruments. Here the signatures to be entered are the transposed
signatures, i.e., the ones that will be printed.

{\bfx Case TTS: Parts entered in respective transposed keys, and printed in those keys in the score.}
In this method of scoring transposing instruments, parts for transposing instruments 
are transposed ahead of time and 
entered exactly as they will appear in the score. So to produce the printed
score this way, the pitch does not have to be changed, but the key signatures must be set
separately for each transposing instrument using the {\tt Ki} command. In the example, the alto sax is
entered in the key of G so the instrument-wise option for it is {\tt Ki2+0+1} . Note that {\tt +0} means no
further transposition is needed before printing, because the part was transposed on entry. Once
again, if a MIDI file is desired, it will come out in concert key, but just as in the previous case,
you must use the transpose option in the MIDI command {\tt IT} to undo the transpositions caused
by the {\tt K} command. For a later key change, the same full-score {\tt K} command as in the previous
case is used to change the concert key. Then the instrument-wise {\tt Ki} command, now with {\tt +0} for
the transpositions, sets the new key signatures for the transposing instruments, again using the
transposed signatures.

{\bfx Case CCS: Parts entered in concert key, printed in score in concert key, but transposed in
separate printed parts.}
This is the easiest case of all. Nothing special needs to be done for the score, but part-only,
full-score transposition commands {\tt\%}[instrument number]{\tt K...} should be entered in the score. Then
{\bfx scor2prt} will generate a transposed part. Of course if a MIDI is made from the score it will
come out at concert pitch. For example, to transpose the alto sax part up 5 steps, initially to G
major, near the top of the score file enter {\tt\%2K+5+1} . Later, where the concert key changes to B
flat minor and the alto sax to G minor, enter simply {\tt K+0-5}, making the new concert key B flat
minor with 5 flats. When {\bfx scor2prt} is invoked to make separate parts, this will be transferred
verbatim into all parts, and then \PMX will internally adjust the signature for each transposed part
as required.

{\bfx Making separate parts.}
In all of the cases discussed, if the patterns of commands in the table are followed, then 
separate parts can be made as usual using {\bfx scor2prt}. They will
automatically come out transposed as desired.

\medskip
%\pagebreak
{\bfx Texts of the transposition sample files:}
% Note: when editing is done, figure out how to make scripts size work without page break.
\begin{scriptsize}
%\begin{tiny}
\begin{multicols}{4}
\begin{verbatim}
%TTA.pmx
3 2 4 4 4 4 0 -2
1 1 20 .13
Trombone II+III
Trombone I
bbb
.\bs
Tt
TTA
Apr
I
K+2+2
b42 d f b t b t gf df b /
b42 d f b t b t gf df b /
b42 d f b t b t gf df b /
K+0-5
b42 c d e f gs as b /
b42 c d e f gs as b /
b42 c d e f gs as b /



%CTS.pmx
3 3 4 4 4 4 0 -2
1 1 20 .1
Trombone
Alto Sax
Clarinet
btt
.\
Tt
CTS
Apr
Ki2+5+1i3+1+0
IT+0-5-1
b42 d f b t b t gf df b /
b43 d f b t b t gf df b /
b44 d f b t b t gf df b /
K+0-5
Ki2+5-2i3+1-3
b42 c d e f gs as b /
b43 c d e f gs as b /
b44 c d e f gs as b /

%TTS.pmx
3 3 4 4 4 4 0 -2
1 1 20 .1
Trombone
Alto Sax
Clarinet
btt
.\
Tt
TTS
Apr
Ki2+0+1i3+0+0
IT+0-5-1
b42 d f b t b t gf df b /
g44 b d g t g t ef bf g /
c45 e g c t c t af ef c /
K+0-5
Ki2+0-2i3+0-3
b42 c d e f gs as b /
g44 a b c d es fs g /
c45 d e f g as bs c /

%CCS.pmx
3 3 4 4 4 4 0 -2
1 1 20 .1
Trombone
Alto Sax
Clarinet
btt
.\
Tt
CCS
Apr
%2K+5+1
%3K+1+0
I
b42 d f b t b t gf df b /
b43 d f b t b t gf df b /
b44 d f b t b t gf df b /
K+0-5
b42 c d e f gs as b /
b43 c d e f gs as b /
b44 c d e f gs as b /
\end{verbatim}
\end{multicols}
\end{scriptsize}
%\end{tiny}

\subsubsection{Text}

	The commands {\tt h} or {\tt l}, when placed in the first 
column of an input line and followed by a blank or, for {\tt h} only, by 
a signed integer,  
stand for {\bfi h}{\it eader} and {\bfi l}{\it ower text}.  They will put a 
text string 
above or below the {\it top} staff in the {\it first} bar of the block where 
they are entered.  The text string must be on a line of its own, 
immediately following the command.  The integer is a vertical shift in
\bs{\tt internote}s.  

	A {\it title block} with up to three elements can be defined at the 
beginning of the first input block.  {\tt Tt} signals that the text 
{\it on the following line} is to be set as a {\bf t}itle for the whole piece, 
and it will be centered. {\tt Tc} similarly indicates a {\bf c}omposer's name, 
to be set below the title and right justified. {\tt Ti} likewise stands for 
an {\bf i}nstrument name, which will be set above the title, left-justified. 
The text for any of these commands can be split over two or more lines
by including \bs\bs~at the location of the line break.

{\tt Ti} will automatically be invoked by {\bfx scor2prt} when it generates 
parts from a score.  

Extra vertical space can be added between the title 
block and the top system by appending to {\tt Tt} a one- or two-digit 
number representing the space in \bs{\tt internote}s.  This only works if 
{\tt Tt} is the {\it final} title block element entered.

The {\tt D} command can be used to enter arbitrary text as described in
section~\ref{dynamics}. 

Lyrics may be entered as described in section~\ref{lyrics}.\NEW{2.73}

\subsubsection{Page numbering, centered header text}

	If you want pages to be numbered at the top left or right, place 
the command {\tt P} anywhere within the \PMX code that represents the first 
page to be numbered (usually the first or second page).  
{\tt P} can be followed optionally by the starting 
page number and/or by {\tt l} or {\tt r}, the latter overriding the default 
locations of odds on the right and evens on the left. \NEW{2.0}  
There is also a special option {\tt c} for {\bf c}entered header text.  
It must be the {\it last} 
option in the {\tt P} command.  It will define text to be printed at the top of
every page {\it after the first}.  If a blank follows {\tt c}, the default 
header text will
be the instrument name entered with the command {\tt Ti} .  If any non-blank
character except {\tt "} follows {\tt c}, the header text will start with that
character and end at the next blank.  If {\tt "} follows {\tt c}, the 
header text will be everything between that and the next {\tt "} (this
permits headers containing spaces).  The {\tt P} command and its options 
will be ignored when making parts from a score (since page numbering 
will usually be different in the score than in the parts), but page 
numbering (and centered headers) for parts can be still be initiated 
independently, for example with {\tt \%!P2} or {\tt \%1P2r} (see 
section~\ref{scor2prt}).

\subsubsection{Overriding certain defaults, or 
getting the most from \PMXX}\label{Acommands} 

Understanding this section is important if you want to get the most out 
of \PMXX. In many 
cases the switches described here represent subtle but significant 
improvements that have come along since \PMX was initially developed. Rather 
than changing the defaults, they are treated as optional in order not to 
upset the layout of older scores. For example, virtually every new score I 
create begins with at least {\tt Abple}.

As you may have guessed, it is the command {\tt A} that can be used to 
override a grab-bag of default settings. The available options affect a 
wide range of \PMX features: sizes 
and interpretation of accidentals,
dot positions, space before the first note of every bar, space between staves,
slur package selection, vertical positioning of Type K postscript 
slurs, line-breaking Type-K slurs, curvature of Type-K slurs, 
naming of parts, vertical positioning of rests in 2-voice staves\NEW{2.6}, 
brackets for non-beamed xtuplets, and inputting so-called 
{\it normal include} files.

{\bf Size of Accidentals.}
{\tt b} makes all accidentals 
{\bf b}ig, {\tt s} makes them all {\bf s}mall.  By default, big ones are used 
unless unaltered spacing doesn't provide enough space.  Thus the default 
behavior may cause a mixture of big and small accidentals, and in fact is not
recommended.

{\bf Relative accidentals.}\label{ArDirective}
If transposing, then the {\bf r}elative accidental convention must be used, 
indicated by {\tt r}.  This changes the way you enter accidentals. With 
relative accidentals, the note options {\tt s}, {\tt f}, {\tt n} take on 
unconventional meanings, now respectively signaling that a note should be raised 
a half step, lowered a half step, or left alone {\it relative to the pitch 
it would have according to the key signature}. So for example, with {\tt Ar}, 
in the key of B flat major the note command {\tt bs} would cause a B natural 
to be printed. By contrast, the default is 
the normal, absolute convention, where the indicated pitch alteration is
relative to what the pitch would be if there were no key signature.
 
{\bf Vertical position of dots.}
If there are staves with two voices, {\tt d} causes dots in the 
lower one to appear on or {\it below} center, in contrast with the default.

{\bf Gap at start of bar.}
Use {\tt a} followed by a 
decimal number to override the default setting for \bs{\tt afterruleskip},
the space before the first note in a bar.  The default in \PMX is  
{\tt 1}\bs{\tt elemskip}, 20 percent smaller than \MusiXTeX{}'s. 

{\bf Space between staves within a system.}
If \PMXX's vertical spacing between staves within a system is not pleasing, use {\tt I} or
{\tt i} , followed by a decimal number, to apply a scale factor to 
\bs{\tt interstaff} . {\tt I} 
affects all pages, {\tt i} only the current one.  Shrinking the space between
staves within each system will cause the space between systems to increase, and
conversely. These options have no effect if there is only one staff per system.

{\bf Equal space between systems.}
\label{AeDirective}\MusiXTeX~normally draws a virtual box around each system 
and inserts equal vertical space between boxes.  \NEW{2.3} 
When objects protrude above the top staff in a system or 
below the bottom one, this can lead to unequal spacing between the top staff
line in one system and the next.  If you prefer that the vertical spacing
between the staves of consecutive systems be constant for the whole page,
use the {\tt e} option of the {\tt A} command.  One side benefit of {\tt Ae} 
is that it will prevent systems from spilling over onto extra pages, 
regardless of how many systems are put on the page. When using this option, 
you may occasionally want to force more vertical space between certain systems.  
There is a \TeX~macro
{\tt \bs spread} that can be inserted anywhere in the system before the 
desired wider gap.  It has one argument, the desired extra space in
{\tt\bs internote}s. 

{\bf Stop grouping systems at top in sparse pages.}
Another \NEW{2.4}\ command affecting vertical spacing is the {\tt v} 
option of the {\tt A} command (for
{\bf v}ertical). \PMX normally spreads staves 
vertically over a full page, unless the white space becomes excessive,
in which case it groups all staves near the top of the page.  Entering
{\tt Av} will suppress this grouping near the top, and ensure that
systems will always be spread vertically regardless of how much white
space is left.  It is a toggle; the second time it is issued, the 
behavior reverts to the default.

{\bf Make some staves smaller.}
The {\tt S} 
option to the {\tt A} command\NEW{2.7} allows you to specify a 
different size for selected staves and their notes compared to the 
global value set in the setup data. It is followed by exactly {\tt noinst} 
characters, one for each instrument, selected from 
{\tt 0}, {\tt -}, {\tt s}, or {\tt t} for 
normal, small, small, or tiny sizes respectively. 

{\bf Postscript slurs.}
The \label{ApDirective}\NEW{2.4} command {\tt Ap} activates Type K 
{\bf p}ostscript slurs. To use this 
you must have {\tt musixps.tex} somewhere that \TeX~can find it, and 
{\tt psslurs.pro} somewhere that {\bfx dvips} can find it. 
If these files happen to be missing from your \TeX~distribution, they
can be found 
\href{http://www.icking-music-archive.org/software/musixtex/musixtex.zip}
{\underline{here}}.
Several suboptions affecting Type K 
postscript slurs are described here and in the following paragraphs. First, 
by default these slurs and ties will not have their vertical positioning tweaked
to avoid tangencies with staff lines.  To activate this type of adjustment,
use one of the suboptions {\tt +s} or {\tt +t} for
slurs or ties respectively.
(For example, {\tt Ap+s}). Be
warned that this may alter the endpoint positions from what one would normally
expect.  To deactivate the adjustment, use the same command but with {\tt -} .
Another suboption of {\tt Ap} affects line-breaking slurs. Normally a full tie 
is drawn at the start of the second line.  
However, the suboption {\tt Ap+h} causes the use of 
{\it{\bfi h}alfties} for the second part, which are flattened at their 
left-hand end, and require the 
special font {\tt mxsk} provided with the Type K postscript slur distribution. 
It may be cancelled with {\tt Ap-h} .

The \NEW{2.5} suboption {\tt l} (e.g. {\tt Apl}~) activates some other tweaks 
and tweaking capabilities for line-breaking Type K slurs and ties. It 
automatically tweaks the 
horizontal positions of the end point of the first segment and the start of the 
second, uses a normal tie character for both segments of a tie, and enables 
further tweaking of the horizontal and vertical positions of internal endpoints 
on a case-by-case basis, using options in the initial slur or tie command (see 
section~\ref{lbslurs}, and the end of the fourth system in the example file
{\tt barsant.pmx}).

Another pair of \NEW{2.5}suboptions to {\tt Ap} affects the default curvature of
Type-K postscript slurs. {\tt Ap+c} and {\tt Ap-c} will respectively increase or
decrease the default curvature of all slurs to the next level in the sequence 
{\tt f, n, h, H, HH} . (Here {\tt n} stands for {\bf n}ormal.)  Several levels 
may be traversed by repeating the suboption, e.g., {\tt Ap+c+c} increases the 
default curvature by two levels. If you try to 
go outside the allowable range, a warning will be issued, the curvature will be 
set to 
{\tt f} or {\tt HH} , and processing will continue. See section~\ref{slurs} for 
further details.

If \NEW{2.5} your score contains Type K slurs and if you use a program such as 
{\bf dviselec} to extract single pages 
from a {\tt .dvi} file, you should use the suboption {\tt h} (e.g. 
{\tt Aph}~) . This will cause the header file {\tt psslurs.pro} to be written 
into the postscript file at the top of of every page.

{\bf Vertical rest positioning in keyboard scores.}
The\NEW{2.6} option {\tt AK} activates special rules for vertical positioning of rests in
two-voice staves. By way of background, without this option, rests in two-voice
staves have default positions based on a simple rule that is not 
context-sensitive: those in the lower voice (the one before {\tt//}) are 
4\bs{\tt internote}s below their single-voice default positions, and those in
the upper line are 2\bs{\tt internote}s above the single-voice default. In contrast, the 
option {\tt AK} invokes a set of context-sensitive rules to set the default 
position. The baseline rule is to align the rest in a horizontal line with the
next following note in the same bar. If there is no following note in the bar,
then it is aligned with the next prior note. If there are simulataneous rests
in both voices, the old rule is applied. When the {\tt AK} option is in force,
it only affects places where there are two voices in a staff. It may be toggled
on and off at the beginning of any input block, using just {\tt AK}. When the
option is in effect, any user-defined tweaks on the height of a rest will
supersede the option for that particular rest, i.e., the tweak will be applied
relative to the single-voice default position. When {\tt AK} is in effect, the
option {\tt L} in a rest command will cause the vertical position of that rest
to be based on the {\it preceding} note, rather than the following one as is
the default. 

{\bf Names of \PMX files for parts.}
The \label{ANDirective}option {\tt N} to the {\tt A} command allows you to specify 
arbitrary names for the part files generated by 
{\bfx scor2prt}. Follow {\tt AN} with the part number and the new file base name in double 
quotes. Immediately follow this with any number of additional part numbers and 
alternate file base names in quotes. When part files are generated, {\tt .pmx} will be
appended to the requested base name. 

{\bf Gapped bracket for nonbeamed xtuplets.}
Non-beamed \label{ATDirective}\NEW{2.5}xtuplets will normally be printed with 
a bracket above or below, and 
a number above or below that. If you would like this number instead to be 
positioned within a gap in the bracket itself, enter {\tt AT} .You must have
{\tt tuplet.tex} available to your \TeX~processor. If missing, this file 
can be found 
\href{http://www.icking-music-archive.org/software/musixtex/musixtex.zip}
{\underline{here}}.

{\bf ``Include'' file.}
\PMX commands \NEW{2.5}in an external file can be included at the start of any input 
block by designating the file as a {\it normal include} file, using the 
command {\tt AR}[{\it filename}] . See section~\ref{ARDirective} for details.

{\bf Positioning printed pages.}
For \NEW{2.7} printing on {\bf l}etter or a{\bf 4} paper, the command {\tt Acl} or 
{\tt Ac4} will set the margins
of the printed area so it will be properly centered with no further
adjustments needed when running {\bfx dvips}.

\subsubsection{Extra hardspace, horizontal shifts} \label{hardspace}

	Despite the author's best intentions to relieve you of the chore 
of adjusting {\it any} horizontal spacing by hand, there may be some occasions 
where you 
will want to do it.  A command starting with {\tt X} initiates one of two 
types of horizontal adjustment: A {\it shift} moves one or more 
characters but does not affect any other spacing anywhere; a 
{\it hardspace} inserts a fixed amount of space at a particular time and
affects the horizontal positions of everything in all staves in the system. 
If the command includes {\tt S}, it is a {\bfi s}{\it ingle} shift and affects 
only the next note or rest.  If it includes a {\tt :} it either starts or 
terminates a {\it group} shift.  
All {\tt X} commands except group shift terminations 
must include a decimal number for the size of the offset in notehead widths. 
If the number is immediately followed by
{\tt p}, then the number represents points, otherwise, notehead widths.
If there is no such number but there is a {\tt :} the command 
signals a group shift termination.  
Group-shift commands must occur in 
start/terminate pairs, and group shifts cannot extend across a bar line.

An {\tt X} command containing neither {\tt S} nor {\tt :} is 
automatically a hardspace.  

Because horizontal spacing in parts will usually differ from that in the 
score, by default the hardspace command will {\it not} be copied into parts 
by {\bfx scor2prt}; however the shift commands will be copied.  
These behaviors can be overridden using the methods to be described in 
section~\ref{scor2prt},  Alternatively, \NEW{1.42} to help keep \PMX score 
files neat 
and readable, the character {\tt B} can be used within the {\tt X} command 
to signify that it applies to {\bf b}oth score and part, or {\tt P} for
{\bf p}art only.

\subsubsection{Minimum spacing between notes in crowded systems}

	\PMX does some special, complex analysis to adjust horizontal spacing 
in crowded systems.  By default, the minimum space between consecutive 
noteheads is 0.3 notehead widths.  In very special situations you may want to 
change 0.3 to some other fraction. To do so, enter {\tt W. }(decimal point is required)
 followed by {\tt 1}-{\tt 9} to represent the number 
of tenths of a notehead width to be used as the minimum spacing. Use of this option 
is demonstrated in the example file {\tt barsant.pmx}.

\subsubsection{Page size}

	The default page size is 740 by 524 pt (10.3 by 7.3 in).  To change 
the height or width, use the special commands {\tt h}[{\it n}][{\it u}] or 
{\tt w}[{\it n}][{\it u}] at 
the beginning of the first input block.  Here {\it n} is a decimal number 
for the new dimension and {\it u} defines the units; {\tt i} for inches, {\tt m} for 
millimeters, and {\tt p} or nothing for points.  This command can be used 
together with {\tt \%\%} or {\tt \%!} 
(see section~\ref{scor2prt}) to give the parts made by 
{\bfx scor2prt} different page sizes than the parent score.

\subsubsection{Line, page, and movement breaks} \label{movbrk}

	It is possible to force line, page, or movement breaks anywhere.  
For a line break, just enter {\tt L}[{\it n}] at 
the start of an input block (in the first voice only), and the {\it n}-th 
system will start there.  To start page {\it m} at line {\it n}, enter 
{\tt L}[{\it n}]{\tt P}[{\it m}].  You can't force a page break without 
first forcing a line break.

        To force a movement break, you must first force a line break as above,
then enter {\tt M}.  If a page break also occurs here, the {\tt P} must precede 
the {\tt M}.  Options following {\tt M} are {\tt +}[{\it integer}] to insert
vertical space in \bs{\tt internote}s before the break, 
{\tt i}[{\it decimal number}] to reset the first-line indentation as a fraction
of the line width, and {\tt c}\NEW{1.41} to {\bf c}ontinue bar numbering rather 
than resetting the bar number to 0. \NEW{1.4}Also, to change the {\bf n}umber 
of instruments, 
enter {\tt n}[{\it integer}], then the number of each instrument in their new
order, then a clef-designating character for each staff of each instrument.   
(An instrument's number is simply its position in the original sequence.)
There can never be more than the original number of instruments. In this 
instance, \NEW{2.5}two-digit instrument numbers must be preceded with 
{\tt :} (colon). If you want to start with some number of instruments and 
later increase it, you'll need to insert
a dummy page at the beginning with the full set of instruments, then start the 
second page with a movement break and decrease the number there. 

Another\NEW{1.4} option after {\tt M} is {\tt r+} or {\tt r-}, which either 
forces or 
suppresses {\bf r}eprinting the instrument names.  The default is to print 
them if the number of instruments changes, but otherwise not.

      Immediately after a movement break, any desired meter changes, 
key changes, or text can be entered in the normal way.

\subsubsection{Fractional bars}

	Often if a piece starts with a pickup, the last bar may not be 
complete.  In such cases, it is usually possible to 
place the last bar in an input block by itself, headed by a {\it blind} meter 
change.  
For example, if the meter had been 4/4 and there was a quarter note 
pickup, leaving 3 beats in the last bar, the last bar might be coded 
{\tt m3400 cd24 /}.

\subsubsection{Stem direction of bass notes}

	By default \PMX makes stems go up for middle-line D's in bass 
clef, but down for notes on the middle line of all other clefs.  If 
you want middle-line bass-clef notes also to have downward stems by default, 
enter a {\tt B} near the beginning of the file.

\subsection{Putting {\TeX} Commands into the {\PMX}File } \label{LitTeX}

        There are five ways to enter \TeX ~commands into the {\tt .pmx} file. 
Four of
them are {\it in-line}, where the commands are entered directly; the fifth
is by way of an external file.

	The four categories of in-line \TeX~strings 
differ mainly in where they will appear in the {\tt .tex} file.  
(A \TeX\ {\it string} consists of a starting character, a sequence of 
\TeX~commands, and a terminal character). 
In the {\tt .pmx} file, 
only type 4 \TeX~strings may wrap over line breaks.  All in-line \TeX\ must 
adhere to the 128-character limit per line, but each line can have more than 
one \TeX\ command.
Type 1 begins with a single \bs\ and will appear in the {\tt .tex} file 
right before the \TeX 
~command for the next note or rest in the {\tt .pmx} file. Multiple
type 1 strings associated with the same note or rest are allowed, although 
the total length may not exceed 128 characters (so there is generally no 
reason not to combine all \TeX\ commands for a single note into a single 
type 1 string). 

A type 2 string begins with \bs\bs\ 
and will appear near the top of the {\tt .tex} file, right before 
\bs{\tt startmuflex}, regardless of where it appears in the {\tt .pmx} file.  
A type 3 string starts with \bs\bs\bs\ and will appear right before the 
{\tt\bs xbar}
or {\tt \bs alaligne} at the beginning of the current input block, before the
first barline of the block.  While individual type 2 and 3 strings may not wrap 
over line breaks in the {\tt .pmx} file, strings of like type on consecutive 
lines will appear together in the {\tt .tex} file.   
Types 1, 2, and 3 strings must end with \bs\ (backslash-space). 
This means that they may not contain
the \TeX\ macro \bs\  (backslash-space).  Finally, each type 2 or 3 string
should be isolated on a line of its own, and should be started in column 1.

Type four permits multiple
lines of arbitrary text to be entered at the top of the {\tt .pmx} file;
they will be transferred verbatim to the top of the {\tt .tex} file.  Type
four is initiated with {\tt ---} alone as the top line of the {\tt .pmx}
file.  Then follows any text on any number of lines, until the next line
starting with {\tt ---} terminates the block to be transferred.  

The only other distinction among the types of in-line \TeX\ strings arises when 
{\bfx scor2prt} is used to make separate parts 
(see section~\ref{scor2prt}):
types 2-4 will be copied into all parts, while type 1 only goes into its 
original part. 

If you should want to enter a type-1 (note-based) string longer than 
128 characters, you could use a series of type-2 or -3 strings to define
a \TeX\ macro containing the desired commands.  

	\PMX provides one further option for entering an unlimited set of
\TeX ~commands 
just before \bs{\tt startmuflex}, and before any Type 2 in-line \TeX ~strings. 
Simply put the commands into a text file named [{\it basename}]{\tt .mod} 
in the texinput directory.  It will then automatically be 
entered with an \bs{\tt input} command.  This feature is retained mainly for 
backward compatibility; it has been essentially replaced by the various options
for in-line \TeX ~strings.

\subsection{Figured Bass}

	Figure commands are entered {\it after} their associated note commands.  
They only work in the first (lowest) voice, and in any one other voice\NEW{2.6}.
Enter the characters as 
they would appear from top to bottom, and as you might pronounce them, 
e.g., {\tt 64} or {\tt 73}.  Flats here are {\tt -} (minus), sharps are 
{\tt \#}, and 
naturals {\tt n}, {\it before} the number (if there is a number) (notice
the characters are different here than in notes).  
So for example {\it sharp third} is {\tt \#3}, just a sharp is {\tt \#}, {\it six (over) 
flat five} is {\tt 6-5}, and {\it sharp six (over) 4} is {\tt \#64}.  
In addition to the symbols just described, the following special symbols
are available: {\specfig 2}, {\specfig 4}, {\specfig 5}, {\specfig 6}, {\specfig 9} .
\NEW{2.6}To use them, you must have the font 
\href{http://www.icking-music-archive.org/software/musixtex/add-ons/figbas.zip}{\underline{\tt cmrj}}
in your \TeX~system, and then just put an {\tt s} after the number.

The program 
positions all the figures for each system below the lowest staff of that 
system, with their tops aligned, and just low enough to clear the 
lowest beam, notehead, or stem that could interfere. If you would like to 
change the vertical alignment for the remainder of the staff starting at a 
figure after the first, \NEW{2.71}append {\tt v}[{\it n}], where {\it n} is an
integer representing the vertical shift in \bs{\tt internote}s, which may
have a minus sign.   

If you want a figure to
align horizontally in the second tier, insert the placeholder figure
{\tt\_} (underscore) before the one you want lowered. This is equivalent to
lowering the figure stack by 4 \bs{\tt internote}s.
\NEW{2.6}If you want to {\it raise} the entire stack by an integral number of
\bs{\tt internote}s, append {\tt +} and the number. This can be combined with 
the placeholder figure {\tt\_} to provide full control over the vertical 
position of the stack.

	Sometimes you may need to enter a figure when there's no bass 
note sounding.  To do this, just after the most recent bass note enter 
{\tt x}, followed by a two single digits (the first is a repeat count; the 
second a time value, i.e., {\tt 2,4,8,1,} or {\tt 3}), immediately followed by a figure symbol 
as defined in the previous paragraph.  This will 
offset the figure from the associated note by the specified time 
value.  For example, if the lowest voice contained {\tt c03 x3465}, there 
would be a whole-note c, and 3 quarter notes later a figure 65 below 
the staff.

	There is also a {\it continuation} command, a zero followed immediately 
by another \NEW{2.4} 
unsigned number.  This produces a horizontal line under the bass note, starting 
just to the left and extending to the right by the given number of 
\bs{\tt noteskip}s.  The height and length of the line are set by the current 
note's level and \bs{\tt noteskip} respectively. These \NEW{2.4} can be mixed in with
other figures to produce vertical stacks.  If another figure follows in the
same command, use {\tt:} as a separator.  
If \bs{\tt noteskip} changes or a note drops 
below the starting level before the line ends, it is possible to trick 
\PMX by entering separate {\tt 0}[{\it n}] commands under each consecutive note; \PMX 
will automagically join them together at the same height 
(thanks to Werner Icking for this idea).  

	If there are figured bass commands in a {\tt .pmx} file but 
you want them to be ignored, then enter the command {\tt F} at the 
beginning of the body of the file.  This feature would most often be 
used in the form {\tt \%1F} 
(see section~\ref{scor2prt}), which makes a 
separate bass part with no figures.

        Figured bass commands will not be altered in any way under 
transposition.  There is no universal set of interpretations of figured bass 
symbols, so no automatic transposition is possible.

\subsection{Macros}

     A \PMX macro is a single command that stands literally for any 
any string of characters that may occur in the input file (sorry, no 
variables). It may be useful if you need to repeat the same string later.
There is no practical length limit.    

To 
{\bfi r}{\it ecord} a macro, type {\tt MR}{\it n} where {\it n} is between 
1 and 20.  
Everything you then type will be processed normally as well as stored, 
until you enter the command {\tt M}.  The next time you need to enter the same 
string, just type {\tt MP}{\it n} to {\bf p}lay back the macro.  
  
To just {\bf s}{\it ave} a macro without having \PMX process it as you
enter it, start it with {\tt MS}{\it n}.  

Macros can be redefined at will.  \PMX will print a warning whenever this
occurs.

If you use macros and want to make separate parts, some care is necessary.
{\bfx Scor2prt} will only transfer {\tt MR} macros into the part where they 
originated, but will transfer {\tt MS} macros into all parts.

\subsection{Include Files}\NEW{2.5}\label{ARDirective}
{\it Include} files are separate text files 
    containing arbitrary (but contextually appropriate) sequences of 
    valid \PMX commands. By using the techniques described in this section, 
    the commands in an include file can be inserted at any desired
    place in the virtual \PMX file that the code processes.  
    They will always be syntax-checked. 

There are two types of include files, {\it global} and 
    {\it normal}. There can only be one global include file and it must be named
    {\tt pmx.mod}. If activated, its contents will always be inserted right after 
    the setup data. 
    To activate it, two conditions must be met: (1) an environment variable
    {\tt PMXMODDIR} must be defined to contain a valid path, ending with {\tt /} or 
    \bs~; (2) a file named {\tt pmx.mod} must be present in the directory so defined.
    If {\tt PMXMODDIR} is not set, or if it is defined but there is no file 
    {\tt pmx.mod}, then processing will proceed as usual. 

    Normal include files 
    can have any name and do not require any environment variable to be set. 
    They are activated by the PMX command {\tt AR[{\it filename}]} , placed in the
    .pmx file
    at the location where the included lines are to go. It will generally 
    only make sense to place this command at the beginning of an input block. 
    \PMX will first check 
    for the file as pointed to by [{\it filename}], which may contain a complete 
    or partial pathname preceding the actual file name. If [{\it filename}] is not 
    found, then \PMX will look for {\tt \%PMXMODDIR[{\it filename}]}, i.e., it will check 
    the directory defined by {\tt PMXMODDIR} if {\tt PMXMODDIR} has been set. However, 
    it is not necessary to define {\tt PMXMODDIR} to use a 
    normal include file. There may be any number of normal include files. The same 
    file may be used multiple times. Include files cannot contain references to 
    other include files via the {\tt AR} command; if you try to do that 
    your computer will 
    explode. The following information regarding all activated include 
    files will be printed both to the screen and to the .pml file: notice of 
    opening or closing, echo of the contents, error messages pertaining to syntax 
    errors in the included \PMX commands, and an error message if \PMX cannot find 
    a referenced normal include file. In the latter two cases \PMX will stop. 

\subsection{Batch Processing}

Due \NEW{2.0} to the number of different programs that must be run in sequence 
to produce a printed sheet of music with the \MusiXTeX{} system, most users 
prefer to use a batch script to control the process.  Since batch commands are
platform-dependent we will not provide examples here, but will mention
several \PMX features that can facilitate batch processing. 

First, whenever {\bfx pmxab} terminates due to a syntax
error, the exit code is set to 1.  There are various ways of detecting this
with batch commands, then acting accordingly.  
\NEW{1.4} Second, {\bfx pmxab} always writes a file 
{\tt pmxaerr.dat} containing a single number: 0 if it exited normally, 
otherwise the line number in the {\tt .pmx} file where the syntax
error was.  With advanced batch programming techniques, this file can be 
opened and read, and if there was an input error, a text editor can be 
opened and the input point placed on the line with the error.  

There have been several requests to allow \PMX to keep running even 
after it detects an input error.  
This has not been done because in many cases any error messages after
the first one would be meaningless, or worse, uncorrected errors could 
cause crashes.  In any event, all the output from {\bfx pmxab} will be
stored in the log file [{\it jobname}]{\tt.pml}.

%\setcounter{secnumdepth}1
\section{Making Parts from a Score} \label{scor2prt}

	Separate parts can be made by running {\bfx scor2prt} and entering the 
basename when prompted. The program will create {\tt noinst} separate 
{\tt .pmx} files, one for each instrument. By default the files will be named
[{\it basename}][{\it n}]{\tt .pmx}, where [{\it n}] 
is the sequential position of the instrument. If desired, part file names can
be customized with {\tt AN} as described in section~\ref{ANDirective}.

	In this section we describe how to control the layout of the 
parts separately from that of the score, but by using commands 
that are placed in the {\tt .pmx} file for the score.  This eliminates the 
need for ever editing the {\tt .pmx} files for the parts separately.  You 
can make all corrections in the file for the score, and then re-run 
{\bfx scor2prt}.

	Normally all lines starting with {\tt \%} in the parent {\tt .pmx} are 
transferred into all the parts.  However, if a line has {\tt \%\%} in 
columns 1-2, both it {\it and the following line} will be ignored when 
making parts.  If the ignored line contains only {\tt h}~, {\tt l}~,
 {\tt Tc}~, {\tt Ti}~, or {\tt Tc} to start, 
then one additional line will be ignored.  

	Conversely, if a line begins with {\tt \%!} then it will be ignored as 
usual in creating the parent {\tt .tex} file, but after stripping the first 
2 characters the rest will be put in the {\tt .pmx} file for {\it all} the 
parts.  

To enter a line into the score file that is only to be transferred to one part,
begin the line with \NEW{2.6} {\tt\%}{\it h}, where {\it h} is an {\it extended
hexadecimal digit} representing the part number from 1 to 24 
({\tt1,2,...,9,a,b,c,...,n,o}).  The first 
two characters will then be stripped and the rest transferred to the desired part.
For example, to force a line break to system 15 and a page 
break to page 2 in part 11 only, enter {\tt \%bL15P2}. The use of the extended hex 
digits {\tt a-o} creates a potential incompatibility with prior versions.  
To minimize this, the
character after ``{\tt\%}" will {\it only} be interpreted as a part number if 
it represents a number less than or equal to {\tt noinst}; otherwise the entire
line will be treated as an ordinary comment and transferred to all parts as
a comment.  

	Although only permitted in the first voice in the score, the 
following commands with all their options will automatically be copied 
into all parts (unless the preceding line has {\tt \%\%}):
 {\tt m, V, R, A, h, w, K}.  Literal \TeX\ strings of types 2-4 will also be 
copied into all parts, while type 1 will only go into its original part.

User-defined hardspaces ({\tt X} without {\tt :}) are handled specially.  By
default they are not copied into parts.  There are two ways to circumvent this.
One way to insert hardspace {\it x} into part 
{\it n} is to place in the score, on a line of its own, the command 
{\tt\%}[{\it n}]{\tt X}[{\it x}] .  The \NEW{1.42} other way is with options 
in the {\tt X} command in the score: {\tt B} causes the hardspace to be
used in {\bf b}oth score and parts; {\tt P} puts it into the {\bf p}art but not
the score.

Instrument-wise \NEW{2.7} transposition commands (see section \ref{transpose})
are also handled specially. 
When {\bfx scor2prt} encounters {\tt Ki}[{\it n}] (for instrument {\it n}) in
the score, it transfers the transposition information (transposition amount and 
key signature) for that instrument into
the corresponding part, replacing {\tt Ki} by {\tt K} and keeping only the 
information for instrument {\tt n}.

Lateral shifts ({\tt X}[$\dots$]{\tt :}) will be handled normally,
staying with their original voice.

	By default the total number of systems in each part will be the 
same as in the score.  If you want to override this, there is a command 
{\tt S}[{\it n}] (where {\it n} is the desired number of systems), which 
can only appear at 
the beginning of the first input block.  This can be used after {\tt \%!} 
to affect all the parts, or after {\tt \%}[{\it h}] to affect just part {\it h}. 
 {\bfx Scor2prt} will also 
compute how many pages it thinks each part should have, and enter that 
in the startup data for that part.  If you wish to override that, then 
in the {\tt .pmx} file for the score, insert for example {\tt \%3S14P2} to 
force the third part to have 14 systems and 2 pages (you cannot override the 
number of pages without first overriding the number of systems).  

        A \NEW{2.0} musicsize of 20 is the default in all parts.  This may be 
overridden with the option {\tt m} in the command {\tt S}; e.g., 
{\tt \%2S15m16} .

	As already noted, a {\tt P} command for page numbering in the parent 
file is ignored when making parts.  To initiate page numbering in the 
parts, use for example {\tt \%!P} anywhere within the \PMX code representing 
the first page of the parts (from \TeX 's standpoint the command must occur 
between the beginning and end of the page on which the numbering is to begin). 
It \NEW{2.0} will often be useful in this case to use the option {\tt c} , 
which by default causes the instrument name to be centered in small type at 
the top of every page after the first.  

Note the distinctions among the various usages of {\tt P}: as an option with 
{\tt S}, it sets the total number of pages in a part; as an option with 
{\tt L}, it forces a page break; and as a command on its own, it controls page 
numbering and centered headings.

MIDI \NEW{2.2} commands, i.e., those starting with {\tt I}, will never be 
copied into parts, unless they are in a special comment line as just described.

	One function of {\bfx scor2prt} is to condense consecutive bars of rest 
into a single group of special printed characters with a number above it.    
The command {\tt rm} defines such a {\bf m}ulti-bar {\bf r}est as described 
in section~\ref{MultibarRest}. 
{\bfx Scor2prt} will automatically insert {\tt rm} commands into the 
{\tt .pmx} files 
for the parts where appropriate.  However, for this feature to work, 
the {\it first} full-bar rest in the sequence {\it must} have its duration 
explicitly defined in the parent {\tt .pmx} file, either with a digit or 
with {\tt p}.  I.e., the feature will not work if the first rest in the 
sequence inherits its duration from the previous note.

Using the special \PMX commands listed in this section, 
augmented where needed with literal \TeX ~commands, it is possible to store 
{\it all} the information for both the score and the parts in a single 
{\tt .pmx} file.  This greatly simplifies the editing process, since 
both the score and the part can be corrected at once, and parts need not be
re-edited each time they are regenerated from the score.

\section{Making MIDI Files}\label{MIDI}

\PMX has an elementary capability to create MIDI files. It is intended mainly 
to aid in editing scores, so it does not have advanced facilities one would 
want for making musically satisfying sound files.

As \NEW{2.6} of version 2.6, \PMX can only generate MIDI files for scores with 
15 or fewer voices. 

Entering the command {\tt I} before any notes have been entered 
will cause a MIDI file [{\it jobname}]{\tt.mid} to be 
generated in the current directory.  Options may follow, without spaces.  They
are defined in the following paragraphs.  Multiple 
options can be combined in one {\tt I} command.  
{\tt I} commands can appear later in the file as well, but only at the start 
of an input block.  Sometimes the order of the 
options matters, determining for example whether or not a user-defined pause 
is included inside a macro block.  

{\tt t}{\it x} sets the tempo to {\it x} quarter notes per minute. 
Default is 96.  You can change tempos as often as you like, but only at the
start of an input block (as with all MIDI commands).

{\tt i}{\it i1i2...in} assigns MIDI instruments {\it i1,i2,...,in} to the
respective \PMX instruments. The default is harpsichord, of course.  If
you use this option, you must specify {\it all} instruments.
Each {\it in} is either 
a 2-letter abbreviation or an integer between 1 and 255. Acceptable 
abbreviations are listed below.  Numbers and pairs of letters may be mixed, 
but consecutive pairs of numbers must be separated by {\tt :} (colon) .  
This option can only be exercised once per file. 
Also, the number of instruments cannot change during a piece.

The \NEW{2.7} number of arguments following suboption {\tt i}, as well as the next 
three described suboptions, must in fact equal the number of {\it instruments}. Before
version 2.7, it was the number of {\it staves} (despite the incorrect 
description in the manual!) These numbers may differ and this creates a
backward incompatibility. Hoping this won't cause too much distress, 
I've enhanced the real-time error messages. 

{\tt v}{\it i1}:{\it i2}:{\it...}:{\it in} assigns MIDI \NEW{2.3} velocities 
to each instrument.  The colons are required.  Values may range from 1 to 127. 
The default is 127.  

{\tt b}{\it i1}:{\it i2}:{\it...}:{\it in} assigns MIDI \NEW{2.3} balances to 
each instrument.  The colons are required.  Values may range from 1 to 128. 
The default value is 64, which represents the center.  Smaller numbers favor 
the left stereo channel; larger ones the right.

{\tt T} allows transposing any instrument by a selected number of steps \NEW{2.7}
 ({\tt\bs internote}s). 
It must be followed by exactly {\tt noinst} signed integers representing the
amount of transposition for each instrument in order. In practice it is useful 
in two situations (1) To transpose a MIDI output up or down by one octave 
(7 {\tt\bs internote}s); and (2) when a transposing instrument is printed 
in the transposed key in the score after having issued {\tt Ki}, to undo 
the transposition in the MIDI.

{\tt M} initiates a macro operation.  This is used for repeats, da capo's, etc.  
Macros must have ID numbers between 1 and 20.  Operations are start record
macro {\it i}:  {\tt MR}{\it i} ; end recording: {\tt M} ; and playback (insert)
macro {\it i}: {\tt MP}{\it i} .  Only one macro can be active at a time, 
recording or playing but not both.  If you try nesting or overlapping macros, 
your computer will become psychotic.

{\tt p}{\it x} inserts a pause of {\it x} quarter notes.  Decimals are 
allowed, but will be rounded to the nearest sixteenth note.

{\tt g}{\it i} sets the MIDI gap to {\it i} MIDI clock tics.  This is a silence 
inserted at the end of every note, while decreasing the sounding duration 
by the same amount.  The default is 10, which is 2/3 of a 64th note.

      The MIDI module does not recognize graces, ornaments, repeats, voltas, or 
segnos.  The only ties that are recognized are those using {\tt s} or {\tt (} 
alone, with no explicit ID number.  Key signatures,
time signatures (meter) and instrument names will be written into the MIDI file, 
the latter as track names.  This will have no effect whatsoever on audible 
output but will affect on-screen appearance of some MIDI file players 
and editors.  Location of the \PMX key-change and meter-change commands 
relative to MIDI macro delimiters in the source will affect (in the obvious
way) how these data are passed to such programs.

The MIDI file generator does not yet support changing the number of 
instruments in midstream.  Doing so will cause unpredictable results.

      The instruments are a subset of ``The General MIDI Instrument 
Specification." Of course how they sound depends on your hardware and software. 
Instruments not listed below can still be used but must be specified by number.  
The numbers listed here are from the 1-128 range; when passed to the MIDI file 
they are reduced by one.

%\def\toc#1#2{\hbox to 3.1in{{#2}\leaderfill{#1}}}
\def\tentry#1#2#3{\hbox to 2in{
\hbox to .24in{\tt #1\hfill}\hbox to 1.7in{#2 (#3)\hfill}\hss}} 

\null
\hbox to 6.5in{\vbox to 1.7in{
\tentry{pi}{Acoustic Grand Piano}{1}
\tentry{rh}{Rhodes Piano}{5}
\tentry{ha}{Harpsichord}{7}
\tentry{ct}{Clavinet}{8}
\tentry{ma}{Marimba}{13}
\tentry{or}{Church Organ}{20}
\tentry{gu}{Acoustic Nylon Guitar}{25}
\tentry{ab}{Acoustic Bass}{33}
\tentry{vl}{Violin}{41}
}\hss\vbox to 1.7in{
\tentry{va}{Viola}{42}
\tentry{vc}{Cello}{43}
\tentry{cb}{Contrabass}{44}
\tentry{vo}{Synth Voice}{55}
\tentry{tr}{Trumpet}{57}
\tentry{tb}{Trombone}{58}
\tentry{tu}{Tuba}{59}
\tentry{fr}{French Horn}{61}
\tentry{so}{Soprano Sax}{65}
}\hss\vbox to 1.7in{
\tentry{al}{Alto Sax}{66}
\tentry{te}{Tenor Sax}{67}
\tentry{bs}{Baritone Sax}{68}
\tentry{ob}{Oboe}{69}
\tentry{ba}{Bassoon}{71}
\tentry{cl}{Clarinet}{72}
\tentry{fl}{Flute}{74}
\tentry{re}{Recorder}{75}
}}

\section{Limits}

For simplicity in writing the program, \PMX has numerous variables with
fixed dimensions.  In most cases there are no checks against these limits
(hey, I've got more important things to program), so
occasionally there may be hangups due to exceeding a dimension.  
Any of these can potentially be increased by making a request via the 
mailing list.  However, before making such a
request, try working around the problem by 
breaking the input into smaller blocks.  

\subsection{Limits on quantities that a user can control}  

(The user can control the {\it number} of these items, but cannot control
the {\it limit on the maximum number} of them.)

%\ \ \ \ \ 128 characters per input line.
128 characters per input line.

24 \NEW{2.6} staves.

2 voices per staff.

24 \NEW{2.6} voices per system.

125 systems.

600 bars.

40 forced line breaks.

10 forced page breaks.

18 key changes.

20 pages.

600 \NEW{2.6} notes per input block.

15 bars per input block.

101 slurs per input block. 

74 figures (figured bass) per input block.

37 grace note groups per input block.

74 notes in grace note groups per input block.

52 literal \TeX\ strings per input block.

6 voltas per input block.

24 \NEW{2.6} trills per input block.

62 chordal notes (non-spacing) per input block.

8 beams per voice per bar.

40 \NEW{2.5}forced beams per voice per input block.

10 clef changes per voice per input block.

24 notes per beam.

24 notes per xtuplet.

41 text-dynamic strings per input block.\NEW{2.5}


\subsection{Limits not under immediate user control}

% Need all the spaces because this damn format insists on left-justifying
% first line of *first* paragraph in a section..
%
\ \ \ \ \ \kern-1pt2000 \bs{\tt notes} groups.

20 \bs{\tt notes} groups per bar.

20 inserted standard anti-collision spaces (not xtuplet or end-of-bar) per bar.

20 inserted anti-collision spaces within xtuplets per bar.
 
19 inserted anti-collision end-of-bar hardspaces per system.

83 inserted anti-collision end-of-bar hardspaces.

400 inserted standard anti-collision spaces per system.

100 inserted anti-collision spaces within xtuplets per system.

1000 inserted standard anti-collision spaces.

200 inserted anti-collision spaces within xtuplets.

24576 \NEW{2.2} bytes of MIDI output data per voice.

\section{Closing Notes}

\subsection{About the Example Files}

{\tt most.pmx} contains examples of most of the \PMX commands, and a few
programming tricks, including examples in the last line of beam groups whose
notes vary widely in pitch.  The printed
output displays the \PMX commands near to the resulting typeset characters.  
It is more
useful to look at the printed output rather than the source file, since the
file is littered with in-line \TeX ~needed to output the text strings 
representing the \PMX commands.
{\bfx WARNING:} Do not try to play this music; it could be hazardous.

{\tt barsant.pmx} contains the first movement of a recorder sonata by the
Italian Francesco Barsanti (1690-1772).  It demonstrates many of \PMXX 's
strong points in a ``battlefield'' situation:  figured
bass, complex beaming patterns, xtuplets, and  
automatically adjusted horizontal and vertical spacing in crowded scores.  
In fact, 
this single-page score pushes the limits of vertical and horizontal crowding. 
To get the final result, it makes subtle adjustments using various available options: 
{\tt Ae} for equal space between systems, {\tt AI1.1} to increase the vertical 
space between staves in a system, {\tt Apl} to activate postscript slurs and 
special treatment of line-breaking slurs/ties (note slur at end of fourth
system), and {\tt W.5} to increase minimum space between noteheads so the 64th
notes don't touch each other. This is also a 
good score to try making parts with {\bfx scor2prt}. A special command
{\tt \%2S9} is used to increase the number of systems in the recorder part. 

{\tt mwalmnd.pmx} is an Allemand for harpsichord by the German 
Matthias Weckmann 
(1616-1674).  It uses many techniques peculiar to keyboard scores, most notably
two voices per staff.

{\tt netsoos.pmx}\NEW{2.73} is an example with lyrics, including several inline \TeX\ 
commands to enhance the layout.

{\tt staffcrossall.pmx}\NEW{2.74} contains examples of staff-crossing chords. Some are 
single-stemmed, some are beamed non-xtuplets, and finally beamed xtuplets. 

\subsection{A Benign Bug} 

	When \TeX 'ing the output of \PMX you will usually get an {\tt Underfull 
\bs vbox} message at the end of each page.  This is due to my using 
\bs{\tt eject} at the end of every page, which automatically spaces the 
systems vertically without having to fiddle with \bs{\tt staffbotmarg}.  As far
as I know, the 
warning is benign, and may be ignored. 

\subsection{Where to Get Help} \label{where}

The main home of \PMX on the internet is the software section of the 
\href{http://icking-music-archive.org}{\underline{Werner Icking Music Archive}}. This
site also links to a mailing list devoted to \MusiXTeX\ and related programs including 
\PMX. The denizens of this list are always willing to answer questions about any 
aspect of the software. New users are strongly advised to take advantage of this
resource.

\subsection{Acknowledgments}

	To Daniel Taupin, Ross Mitchell, and Andreas Egler for creating 
\MusiXTeX{}; to Olivier Clary for suggesting a crucial modification in 
the note-entry scheme; 
to my colleague John DiPol (a non-musician!) for the idea of using binary masks 
to define beam groupings; 
to Joel Hunsberger for unraveling some deep \MusiXTeX~tangles;
to Dirk Laurie
for making \PMX accessible to vocal music by creating {\tt\bs pmxlyr} 
and {\bfx M-Tx};
to Stanislav Kneifl and Hiroaki Morimoto for developing the postscript
slur packages; to 
Christian Mondrup, Andre Van Ryckeghem, Christof Biebricher, Joerg Anders,
Olivier Vogel, and other denizens of the TeX-music mailing list
for first-class bug-finding and support in responding to queries about
\PMX on the mailing list; to Luigi Cataldi, Olivier Vogel, Christof 
Biebricher, and Cornelius Noack for producing translated and enhanced 
\PMX tutorials; and to Bob Tennent for maintaining the software section
of the web site.
Finally, I want to mention again the invaluable contributions by 
Werner Icking: his exhaustive beta testing, 
uncanny bug-finding, continuing encouragement, and promotion 
of \PMX right up until his sudden and premature departure from this
earthly realm. 

\end{document}