File: usrguide.tex

package info (click to toggle)
abc2mtex 1.6.1-4
  • links: PTS
  • area: non-free
  • in suites: slink
  • size: 392 kB
  • ctags: 410
  • sloc: ansic: 4,052; makefile: 86; sh: 9
file content (1149 lines) | stat: -rw-r--r-- 48,005 bytes parent folder | download | duplicates (3)
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
\documentclass{article}
\usepackage{musictex}
%\usepackage{palatino}
%\headheight 0pt
\parskip 1ex
\parindent 0em
\oddsidemargin -10mm \evensidemargin -10mm
\marginparwidth 40pt \marginparsep 5mm
\topmargin -10mm
\textheight 9.2in
\textwidth 7.2in
\newcommand{\abc}{{\tt abc}}
\newcommand{\abctmtex}{{\tt ABC2M\TeX}}

\begin{document}
\pagenumbering{roman}
\title{{\huge \abctmtex} \\
{\Large An easy way of transcribing folk and traditional music} \\
{\it Version 1.6.1 -- January '97}}
\author{\Large Chris Walshaw \\
{\it School of Maths,} \\
{\it University of Greenwich,} \\
{\it London, U.K.} \\
email: {\tt C.Walshaw@gre.ac.uk}
}
\normalsize
\date{}

\maketitle

\tableofcontents
\newpage
\pagenumbering{arabic}

\section{Introduction}

Welcome to \abctmtex !

This is a package written to typeset tunes stored in an ascii format
or \abc\ notation. It was designed primarily for folk and
traditional tunes of Western European origin (such as Irish, English and
Scottish) which can be written on one stave in standard classical notation.
However, it can act as a fast preprocessor for multi-stave music
(see \S\ref{sec-multi}) and should be extendible to many other types of music.

The package is small, easy to use and features, amongst other
things, the ability to transpose both the music and the \abc\ notation. It will
also create an index of all the tunes you have transcribed.

The ability to write tunes in \abc\ notation means that they can be
easily and portably stored or transported electronically. This package allows
you to typeset them easily too. In addition the notation is not specifically
tied to Music\TeX\ and similar packages have been written to translate
to other formats such as postscript and MIDI.

This package has, however, been written on top of Music\TeX , Daniel Taupin's
music typesetting package, itself written on top of \TeX , Donald Knuth's
typesetting package. To run it you will need \TeX , Music\TeX\ (both freely
available by ftp from a number of sources -- see the {\tt README} file),
a C compiler (although executables are available for PCs and Macs) and
access to a postscript printer.

\subsection{Other \abc\ packages}

Since its introduction, \abc\ has become a popular method for notating,
playing and discussing music. There are several other packages available
including typesetters which don't require the installation of \TeX\ and
Music\TeX, players (to play \abc\ tunes through the speakers of most types of
computer) and translators (e.g. to convert \abc\ to MIDI and vice-versa). An
up to date list is maintained at \verb!http://www.gre.ac.uk/~c.walshaw/abc/!.

\subsection{The \abctmtex\ mailing list}

An abc users mailing list has just been set up -- subscribe by sending
the message {\tt subscribe abc-users} to {\tt majordomo@ecs.soton.ac.uk} .
In addition, I keep a list of anyone who has mailed me to
ask for a copy of the code and automatically notify them of new releases. If you
have got the code by {\tt ftp} and want to be added to the list just mail me
{\tt C.Walshaw@gre.ac.uk}. Traffic is {\em low} -- maybe one message every
couple of months, if that.

\subsection{Acknowledgements}

Thanks to everyone who has helped to improve this package: John Walsh,
Don Ward, Steve Allen, David West, Roger Negaret, Hugh Stewart, Rich Holmes,
Olivier Clary, Jeroen Nijhof (for the transposition of accidentals algorithm),
Paul Anderson (for the Mac version), Michael Methfessel and everyone else.

\subsection{Copyright disclaimer}

The author does not accept responsibility for any copyright
infringement which occurs through the use of this package. It is
the responsibility of the user to ensure that tunes and/or
arrangements typeset with the help of \abctmtex\ lie within the
public domain. Happily this is the case with most traditional music.

\section{Tune files}
\label{sec-files}

The music can either be stored one tune per file with a name that
reflects the contents, e.g. the tune `Paddy O'Rafferty' in the file
{\tt PaddyORafferty.abc}, or grouped together in files according to some
common theme, e.g. {\tt Reels.abc} contains Irish reels and
{\tt English.abc} has English tunes of all types. If the tunes are grouped
then an index is useful and indeed indexing facilities are provided here
(see the document {\tt index.tex}). The example files, in particular
{\tt English.abc}, demonstrate typical file structures.

%abc.txt begin

% This description of abc notation has been created for those who do
% not want to (or cannot) use the package ABC2MTeX but who wish to
% understand the notation. It has been generated semi-automatically
% from the ABC2MTeX userguide and so
% occasionally refers to other parts of the package. In particular, it
% mentions the document index.tex, a guide to using ABC2MTeX for
% archiving and indexing tunes, and to the example files
% English.abc, Strspys.abc and Reels.abc. It also refers to
% playabc, a separate package for playing abc tunes through the
% speaker of various machines. It is best read in conjunction with
% an introduction to abc notation available by anonymous ftp from
%
%         celtic.stanford.edu/pub/tunes/abc2mtex/INTRO.txt
%
% or, if you have WWW access,
%
%         http://celtic.stanford.edu/pub/tunes/abc2mtex/INTRO.html
%
% Note that if you are intending to use the notation solely for
% transcribing tunes, you can ignore most of description of the
% information fields as all you really need are the T (title), M
% (meter), K (key), and possibly L (default note length) fields. I
% have included a full description however, for those who wish to
% understand tunes transcribed by users of the package.
%
% Finally, the notation can easily be expanded to include other
% musical symbols. Please mail me with any suggestions.
%
%         Chris Walshaw
%         C.Walshaw@gre.ac.uk
%
% -----------------------------------------------------------------
%
%         The abc Notation System
%         =======================

Each tune consists of a header and a body. The header, which is composed of
information fields, should start with an {\tt X} (reference number) field
followed by a {\tt T} (title) field and finish with a {\tt K} (key)
field. The body of the tune in \abc\ notation should follow immediately
after. Tunes are separated by blank lines.

\subsection{Information fields}
%   ==================
\label{sec-info}

The information fields are used to notate things such as composer, meter,
etc. \ldots\ in fact anything that isn't music. Most of the information fields
are for use within a tune header but in addition some may
be used in the tune body, or elsewhere in the tune file. Those
which are allowed elsewhere can be used to set up a default
for the whole or part of a file. For example, in exactly the same
way that tunebooks are organised, a file might start
with {\tt M:6/8} and {\tt R:Jigs}, followed by some
jigs, followed by {\tt M:4/4} and {\tt R:Reels}, followed by
some reels. Tunes within each section then inherit the
{\tt M:} and {\tt R:} fields automatically, although they can be overridden
inside a tune header. Finally note that any line beginning with a letter in the
range {\tt A-Z} and immediately followed by a {\tt :} is interpreted as a field
(so that line like {\tt E:|}, which could be regarded as an {\tt E} followed by
a right repeat symbol, will cause an error).

By far the best way to find out how to use the fields is to look
at the example files (in particular {\tt English.abc}) and try out
some examples. Thus rather than describing them in detail, they are
summarised in the following table. The second, third and fourth columns
specify respectively how the field should be used in the header and whether
it may used in tune body or elsewhere in the file. Certain fields do not
affect the typeset music but are there for other reasons, and the fifth column
reflects this; index fields only affect the index (see {\tt index.tex}) while
archive fields do not affect the output at all, but are just provided
to put in information that one might find in, say, a conventional tunebook.

\begin{centering}

\vspace{1ex}
\begin{tabular}{l|c|c|c|l|l}
 & \multicolumn{3}{c|}{Can be used in:} \\ \cline{2-4}
Field name            & header   & tune&elsewhere&Used by&
	Examples and notes \\ \hline
{\tt A:area}               &  yes &     &     &         &
	{\tt A:Donegal}, {\tt A:Bampton} \\
{\tt B:book}               &  yes &     & yes & archive &
	{\tt B:O'Neill's} \\
{\tt C:composer}           &  yes &     &     &         &
	{\tt C:Trad.} \\
{\tt D:discography}        &  yes &     &     & archive &
	{\tt D:Chieftains IV} \\
{\tt E:elemskip}           &  yes & yes &     &         &
	see \S\ref{sec-elemskip} \\
{\tt F:file name}          &      &     & yes &         &
	see {\tt index.tex} \\
{\tt G:group}              &  yes &     & yes & archive &
	{\tt G:flute} \\
{\tt H:history}            &  yes &     & yes & archive &
	{\tt H:This tune is said to ...} \\
{\tt I:information}        &  yes & yes & yes & playabc &
	see the playabc user manual \\
{\tt K:key}                & last & yes &     &         &
	{\tt K:G}, {\tt K:Dm}, {\tt K:AMix} \\
{\tt L:default note length}&  yes & yes &     &         &
	{\tt L:1/4}, {\tt L:1/8} \\
{\tt M:meter}              &  yes & yes & yes &         &
	{\tt M:3/4}, {\tt M:4/4} \\
{\tt N:notes}              &  yes &     &     &         &
	{\tt N:see also O'Neill's - 234} \\
{\tt O:origin}             &  yes &     & yes & index   &
	{\tt O:I}, {\tt O:Irish}, {\tt O:English} \\
{\tt P:parts}              &  yes & yes &     &         &
	{\tt P:ABAC}, {\tt P:A}, {\tt P:B} \\
{\tt Q:tempo}              &  yes & yes &     &         &
	{\tt Q:200}, {\tt Q:C2=200} \\
{\tt R:rhythm}             &  yes &     & yes & index   &
	{\tt R:R}, {\tt R:reel} \\
{\tt S:source}             &  yes &     &     &         &
	{\tt S:collected in Brittany} \\
{\tt T:title}              &second& yes &     &         &
	{\tt T:Paddy O'Rafferty} \\
{\tt W:words}              &      & yes &     &         &
	{\tt W:Hey, the dusty miller} \\
{\tt X:reference number}   & first&     &     &         &
	{\tt X:1}, {\tt X:2} \\
{\tt Z:transcription note} &  yes &     &     &         &
	{\tt Z:transcribed from photocopy}
\end{tabular}

\end{centering}

Some additional notes on certain of the fields:--
\begin{itemize}

\item[{\tt T}] -- tune title. Some tunes have more than one title and so this
field can be used more than once per tune -- the first time will generate the
title whilst subsequent usage will generate the alternatives in small print.
%abc.txt end
The normal \TeX\ accents (such as in \verb!caf\'e!
for producing caf\'e or in \verb!makazi\u ce! for producing makazi\u ce) can
be used but will be stripped out of the index.
%abc.txt begin
The {\tt T:} field can also be used within a tune to name parts of a
tune -- in this case it should come before any key or meter changes.

\item[{\tt K}] -- key; the key signature should be specified with a
capital letter which may be followed by a \verb!#! or {\tt b} for sharp or
flat respectively. In addition, different scales or modes can be specified and,
for example, {\tt K:F lydian}, {\tt K:C}, {\tt K:C major}, {\tt K:C ionian},
{\tt K:G mixolydian}, {\tt K:D dorian}, {\tt K:A minor}, {\tt K:Am},
{\tt K:A aeolian}, {\tt K:E phrygian}
and {\tt K:B locrian} would all produce a staff with no sharps or flats.
The spaces can be left out, capitalisation is ignored for the modes and
in fact only the first three letters of each mode are parsed so that,
for example, \verb!K:F# mixolydian! is the same as \verb!K:F#Mix!
or even \verb!K:F#MIX!.
There are two additional
keys specifically for notating highland bagpipe tunes;
{\tt K:HP} doesn't put a key signature on the music, as is common with many
tune books of this music, while {\tt K:Hp} marks the stave with
F$\sharp$, C$\sharp$ and G$\natural$.
Both force all the beams and staffs to go downwards.

Finally, global accidentals can also be set in this field so that, for example,
{\tt K:D =c} would write the key signature as two sharps (key of D) but
then mark every c as natural (which is conceptually the same as D mixolydian).
Note that the there can be several global accidentals, separated by spaces
and each specified with an accidental, \verb!__!, \verb!_!, {\tt =},
\verb!^! or \verb!^^!, (see below) followed by a letter in
lower case. Global accidentals are overridden
by accidentals attached to notes within the body of the abc tune and are
reset by each change of signature.
%abc.txt end
See \S\ref{sec-extensions} for further notes on their use with \abctmtex.
%abc.txt begin

\item[{\tt L}] -- default note length; i.e. {\tt L:1/4} -- quarter note,
{\tt L:1/8} -- eighth note, {\tt L:1/16} -- sixteenth,
{\tt L:1/32} -- thirty-second. The default note length is also set
automatically by the meter field {\tt M:} (see \S\ref{sec-length}).

\item[{\tt M}] -- meter; apart from the normal meters, e.g.
{\tt M:6/8} or {\tt M:4/4}, the symbols {\tt M:C} and \verb!M:C|! give common
time and cut time respectively.

\item[{\tt P}] -- parts; can be used in the
header to state the order in which the tune parts are played, i.e.
{\tt P:ABABCDCD}, and then inside the tune to mark each part, i.e.
{\tt P:A} or {\tt P:B}.

\item[{\tt Q}] -- tempo; can be used to specify the notes per minute, e.g.
if the default note length is an eighth note then
{\tt Q:120} or {\tt Q:C=120} is 120 eighth notes per minute. Similarly
{\tt Q:C3=40} would be 40 dotted quarter notes per minute.
An absolute tempo may also be set, e.g. {\tt Q:1/8=120} is also
120 eighth notes per minute, irrespective of the default note length.
%abc.txt end
The tempo may also be changed relative to the previous
tempo; {\tt Q:$n$=$m$} means that, from now on, a note value of $n$
occupies the same time as a note value of $m$ did previously.
Both $m$ and $n$ must be prefixed by the pitch value {\tt C} (which is
ignored) to distinguish them from the earlier examples. For example,
{\tt Q:C4=C6} slows down the tempo by a factor of 3/2; a note of length
4 takes exactly the same time as did a note of length 6 previously.
When the meter changes from 4/4 (8 default notes per bar) to 6/8 (6 default
notes per bar) a tempo change of {\tt Q:C3=C4} is needed to keep the number of
bars per minute the same, i.e. to maintain the pulse of the music.
%abc.txt begin

\item[{\tt G}] -- group; to group together tunes for indexing purposes.

\item[{\tt H}] -- history; can be used for multi-line stories/anecdotes, all
of which will be ignored until the next field occurs.

\end{itemize}

\subsection{\abc\ tune notation}
%   =================

%abc.txt end
\subsubsection{Notes}

%abc.txt begin
The following letters are used to represent notes:--

%
%                                                       d' 
%                                                 -c'- ----
%                                              b
%                                         -a- --- ---- ----
%                                        g
%  ------------------------------------f-------------------
%                                    e
%  --------------------------------d-----------------------
%                                c
%  ----------------------------B---------------------------
%                            A
%  ------------------------G-------------------------------
%                        F
%  --------------------E-----------------------------------
%                    D
%  ---- ---- ---- -C-
%             B,
%  ---- -A,-
%   G,
\begin{music}
\def\freqbarno{99}
\def\nbinstruments{1}\relax
\def\Zu#1#2{\zcharnote{-9}{\tt #1}\qu#2}
\def\Zl#1#2{\zcharnote{-9}{\tt #1}\ql#2}
\generalsignature{0}\relax
\generalmeter{\meterfrac{}{}}\relax
\debutextrait
\normal\elemskip=15pt
\notes
\Zu{G,}{N}\Zu{A,}{a}\Zu{B,}{b}%
\Zu{C}{c}\Zu{D}{d}\Zu{E}{e}\Zu{F}{f}\Zu{G}{g}\Zu{A}{h}\Zu{B}{i}%
\Zl{c}{j}\Zl{d}{k}\Zl{e}{l}\Zl{f}{m}\Zl{g}{n}\Zl{a}{o}\Zl{b}{p}%
\Zl{c'}{q}\Zl{d'}{r}\Zl{e'}{s}\Zl{f'}{t}\Zl{g'}{u}%
\enotes
\finextrait
\end{music}

and by extension, the notes {\tt C,} {\tt D,} {\tt E,} {\tt F,}
{\tt a'} and {\tt b'} are available. Notes can be modified in length
(see \S\ref{sec-length}).

\subsubsection{Rests}
%   =====

Rests are generated with a {\tt z} and can be modified in length in
exactly the same way as notes can.

\subsubsection{Note lengths}
%   ============
\label{sec-length}

NB Throughout this document note lengths are referred as sixteenth, eighth, etc.
The commonly used equivalents are sixteenth note = semi-quaver, eighth = quaver,
quarter = crotchet and half = minim.

Each meter automatically sets a default note length and a single letter in the
range {\tt A-G}, {\tt a-g} will generate a note of this length. For example,
in 3/4 the default note length is an eighth note and so the input
{\tt DEF} represents 3 eighth notes. The default note length can be calculated
by computing the meter as a decimal; if it is less than 0.75 the default is a
sixteenth note, otherwise it is an eighth note. For example,
2/4 = 0.5, so the default note length is a sixteenth note, while 4/4 = 1.0 or
6/8 = 0.75, so the default is an eighth note. Common time and cut time
({\tt M:C} and {\tt M:C|}) have an eighth note as default.

Notes of differing lengths can be obtained by simply putting a multiplier
after the letter. Thus in 2/4, {\tt A} or {\tt A1} is a sixteenth
note, {\tt A2} an eighth note, {\tt A3} a dotted eighth note, {\tt A4} a
quarter note, {\tt A6} a dotted
quarter note, {\tt A7} a double dotted quarter note, {\tt A8} a half note,
{\tt A12} a dotted half note, {\tt A14} a double dotted half note,
{\tt A15} a triple dotted half note and so on, whilst in 3/4, {\tt A} is
an eighth note, {\tt A2} a quarter note, {\tt A3} a dotted
quarter note, {\tt A4} a half note, ...

To get shorter notes, either divide them -- e.g. in 3/4, {\tt A/2} is a
sixteenth note, {\tt A/4} is a thirty-second note -- or
change the default note length with the {\tt L:} field.
Alternatively, if the music has a broken rhythm, e.g. dotted eighth
note/sixteenth note pairs, use broken rhythm markers (see \S\ref{sec-broken}).
Note that {\tt A/} is shorthand for {\tt A/2}.

\subsubsection{Broken rhythms}
%   ==============
\label{sec-broken}

A common occurrence in traditional music is the use of a dotted or
broken rhythm. For example, hornpipes, strathspeys and certain
morris jigs all have dotted eighth notes followed by sixteenth notes as
well as vice-versa in the case of strathspeys. To support this
\abc\ notation uses a {\tt >} to mean `the previous note is dotted,
the next note halved' and {\tt <} to mean `the previous note is halved,
the next dotted'. Thus the following lines all mean the same
thing (the third version is recommended):

\begin{verbatim}
  L:1/16
  a3b cd3 a2b2c2d2

  L:1/8
  a3/2b/2 c/2d3/2 abcd

  L:1/8
  a>b c<d abcd
\end{verbatim}

As a logical extension, {\tt >>} means that the first note is double dotted
and the second quartered and {\tt >>>} means that the first note is triple
dotted and the length of the second divided by eight. Similarly for
{\tt <<} and {\tt <<<}.

\subsubsection{Duplets, triplets, quadruplets, etc.}
%   ====================================
\label{sec-triplets}

These can be simply coded with the notation {\tt (2ab} for a duplet,
{\tt (3abc} for a triplet or {\tt (4abcd} for a quadruplet, etc., up to
{\tt (9}. The musical meanings are:

\vspace{1ex}
\begin{tabular}{l l}
 {\tt (2} & 2 notes in the time of 3 \\
 {\tt (3} & 3 notes in the time of 2 \\
 {\tt (4} & 4 notes in the time of 3 \\
 {\tt (5} & 5 notes in the time of $n$ \\
 {\tt (6} & 6 notes in the time of 2 \\
 {\tt (7} & 7 notes in the time of $n$ \\
 {\tt (8} & 8 notes in the time of 3 \\
 {\tt (9} & 9 notes in the time of $n$
\end{tabular}

If the time signature is compound (3/8, 6/8, 9/8, 3/4, etc.) then $n$ is three,
otherwise $n$ is two.

More general tuplets can be specified using the syntax {\tt (p:q:r}
which means `put p notes into the time of q for the next r notes'.
If q is not given, it defaults as above. If r is not given, it defaults to p.
For example, {\tt (3:2:2} is equivalent to {\tt (3::2} and {\tt (3:2:3}
is equivalent to {\tt (3:2} , {\tt (3} or even {\tt (3::} .
This can be useful to include notes of different lengths within a tuplet, for
example {\tt (3:2:2G4c2} or {\tt (3:2:4G2A2Bc} and also describes more
precisely how the simple syntax works in cases like {\tt (3D2E2F2} or
even {\tt (3D3EF2}. The number written over the tuplet is p. 

\subsubsection{Beams}
%   =====

To group notes together under one beam they should be grouped together
without spaces. Thus in 2/4, {\tt A2BC} will produce an
eighth note followed by two sixteenth notes under one beam
whilst {\tt A2 B C} will produce the same notes
separated. The beam slopes and the choice of
upper or lower staffs are generated automatically.

\subsubsection{Repeat/bar symbols}
%   ==================

Bar line symbols are generated as follows:

\vspace{1ex}
\begin{tabular}{l l}
 {\tt |} & bar line \\
 {\tt |]} & thin-thick double bar line \\
 {\tt ||} & thin-thin double bar line \\
 {\tt [|} & thick-thin double bar line \\
 {\tt :|} & left repeat \\
 {\tt |:} & right repeat \\
 {\tt ::} & left-right repeat
\end{tabular}

%abc.txt end
Viz:--
%abc.txt begin

\begin{music}
\edef\catcodeat{\the\catcode`\@}\catcode`\@=11
%\newdimen\x@skip
\def\d@oubleRAB{\thickvrule\nobreak\hskip
0.6\Internote\global\advance\x@skip0.6\Internote
\nobreak\thinvrule}%
\def\setdoubleRAB{\def\barvrule{\d@oubleRAB}}%
\def\freqbarno{99}
\def\nbinstruments{1}\relax
\generalsignature{0}\relax
\generalmeter{\meterfrac{}{}}\relax
\debutextrait
\normal\elemskip=15pt
\barre
\setdoubleBAR
\barre
\setdoublebar
\barre
\setdoubleRAB
\barre
\rightrepeat
\leftrepeat
\leftrightrepeat
\finextrait
\end{music}

\subsubsection{First \& second repeats}
%   ========================
\label{sec-repeats}

First and second repeats can be generated with the symbols
{\tt [1} and {\tt [2}, e.g. {\tt faf gfe|[1 dfe dBA:|[2 d2e dcB|]}. When
adjacent to bar lines, these can be shortened to
{\tt |1} and {\tt :|2}, but with regard to spaces {\tt | [1} is legal,
{\tt | 1} is not.

\subsubsection{Accidentals}
%   ===========
\label{sec-accidentals}

The symbols \verb!^! \verb!=! and \verb!_! are used (before a note) to
generate respectively a sharp, natural or flat. Double sharps and flats
are available with \verb!^^! and \verb!__! respectively.

\subsubsection{Changing key, meter, and default note length mid-tune}
%   =====================================================
\label{sec-key}

To change key, meter, or default note length, simply put in a new line with a
{\tt K:} {\tt M:} or {\tt L:} field, e.g.
\begin{verbatim}
  ed|cecA B2ed|cAcA E2ed|cecA B2ed|c2A2 A2:|
  K:G
  AB|cdec BcdB|ABAF GFE2|cdec BcdB|c2A2 A2:|
\end{verbatim}

To do this without generating a new line of music, put a \verb!\! at the
end of the first line, i.e.
\begin{verbatim}
  E2E EFE|E2E EFG|\
  M:9/8
  A2G F2E D2|]
\end{verbatim}

\subsubsection{Ties and slurs}
%   ==============
\label{sec-ties}

You can tie two notes together either across or within a bar
with a {\tt -} symbol, e.g. \verb!abc-|cba! or \verb!abc-cba!.
More general slurs can be put in with {\tt ()} symbols.
Thus \verb!(DEFG)! puts a slur over the four notes.
Spaces within a slur are OK, e.g. \verb!(D E F G)!, but the
open bracket should come immediately before a note (and its
accents/accidentals, etc.) and the close bracket should come immediately
after a note (and its octave marker or length). Thus \verb!(=b c'2)! is
OK but \verb!( =b c'2 )! is not.
%abc.txt end

The old notation, e.g. \verb!sDEFsG!, can still be used by setting a user
switch -- see \S\ref{sec-settings}.
%abc.txt begin

\subsubsection{Gracings}
%   ========
\label{sec-grace}

Grace notes can be written by enclosing them in
curly braces, \verb!{}!. For example, a taorluath on the Highland pipes
would be written \verb!{GdGe}!. The tune `Athol Brose' (in the file
{\tt Strspys.abc}) has an example of complex Highland
pipe gracing in all its glory. Grace notes have no time value
and so expressions such as \verb!{a2}! or \verb!{a>b}! are not legal.

Alternatively, the tilde symbol \verb!~! represents the general gracing of a
note which, in the context of traditional music, can mean different things for
different instruments, for example a roll, cran or staccato triplet

\subsubsection{Accents}
%   =======

Staccato marks (a small dot above or below the note head) can be generated
by a dot before the note, i.e. a staccato triplet is written as
{\tt (3.a.b.c}

For fiddlers, the letters {\tt u} \& {\tt v} can be used to denote up-bow
\& down-bow, e.g. {\tt vAuBvA}

\subsubsection{Chords \& unisons}
%   ==================
\label{sec-chords}

Chords (i.e. more than one note head on a single stem) can be coded with
{\tt []} symbols around the notes, e.g. \verb![CEGc]! produces the chord of C
major. They can be grouped in beams, e.g. \verb![d2f2][ce][df]!
but there should be no spaces within a chord.
See the tune `Kitchen Girl' in the file {\tt Reels.abc} for a simple example.

If the chord contains
two notes both of the same length and pitch, such as \verb![DD]!, then it is a
unison (e.g. a note played on two strings of a violin simultaneously)
and is shown as note-head with both upward and downward stems.
%abc.txt end

The old notation, e.g. \verb!+CEGc+!, can still be used by setting a user
switch -- see \S\ref{sec-settings}.
%abc.txt begin

\subsubsection{Guitar chords}
%   =============
\label{sec-guitar}

Guitar chords can be put in under the melody line by enclosing the
chord in inverted commas, e.g. \verb!"Am7"A2D2! . See the
tune `William and Nancy' in {\tt English.abc} for an example.

\subsubsection{Order of symbols}
%   ================
\label{sec-order}

The order of symbols for one note is {\tt <guitar chords>},
{\tt <accents>} (e.g. roll, staccato marker or up/downbow),
{\tt <accidental>}, {\tt <note>}, {\tt <octave>}, {\tt <note length>},
i.e. \verb!~^c'3! or even \verb!"Gm7"v.=G,2!

Tie symbols, {\tt -}, should come immediately after a note group
but may be followed by a space, i.e. \verb!=G,2-! . Open and close
chord symbols, \verb![]!, should enclose entire note sequences (except
for guitar chords), i.e. \verb!"C"[CEGc]! or \verb!"Gm7"[.=G,^c']! and
open and close slur symbols, {\tt ()}, should do likewise, i.e.
\verb!"Gm7"(v.=G,2~^c'2)!


\subsubsection{Comments}
%   ========

A {\tt \%} symbol will cause the remainder of any input line to be ignored. The
file {\tt English.abc} contains plenty of examples.

\subsubsection{New notation}
%   ============

The letters {\tt H-Z} can be used to define your own new notation
within a tune. Currently the way they are implemented (if at all)
is extremely package dependent and so users are advised not to
rely too heavily on them to include new features. Instead, if there is
a feature or symbol that you need and which is not available it is
better to press for it to be included as a part of the language.
%abc.txt end
See \S\ref{sec-custom} for how to use these symbols with \abctmtex.
%abc.txt begin

\subsubsection{Line breaking \& justification}
%   ===============================
\label{sec-lines}

Generally one line of \abc\ notation will produce one line of music, although
if the music is too long it will overflow onto the next line. This can
look very effective, but it can also completely ruin ties
across bar lines, for example. You can counteract this by changing
either the note spacing with the {\tt E:} field (although currently this
is package dependent) or break
the line of \abc\ notation. If, however, you wish to use two lines of input
to generate one line of music (see, for example, the `Untitled Reel' in
{\tt Reels.abc}) then simply put a \verb!\! at the end of the first line.
This is also useful for changing meter or key in the middle of a line of music.

With most packages lines of music are right-justified. However,
where this is not the case (e.g. when using Music\TeX), a \verb!*! at the end
of each line of \abc\ notation will force a right-justified line-break.

%abc.txt end
\subsection{\abctmtex\ extensions}
\label{sec-extensions}

The global accidentals which can be specified in the {\tt K:} field are
somewhat basic in their application. Firstly every specified note is marked
with an accidental, rather than just the first of that note in each bar.
Secondly, although global accidentals are overwritten by an accidental
attached to a note this isn't done particularly intelligently. For example,
for the key specification {\tt K:G =f} every f is marked with a natural and
if it was required to override one of these with a sharp, i.e. a \verb!^f!
within the abc of the tune, it would make sense for the output to have
nothing by that f since the key signature automatically sharpens every f.
However, in the current implementation, a sharp will appear.

By default, when using Music\TeX, lines of music are left-justified but not
right-justified. There are two ways to overcome this; either with a \verb!*! at
the end of each line of \abc\ notation as described above (\S\ref{sec-lines})
or by using the setting {\tt justify} as described in \S\ref{sec-settings}.

Currently slurs and ties are only available with MusiX\TeX\ (see
\S\ref{sec-musix}).

The code which handles chords, e.g. \verb![ac]!, is a bit
sensitive and you may need to fiddle around a bit with the order of the notes
in the chord to get it looking right.

Within guitar chords \abctmtex\ only processes the first letter (and the
second if it is a \verb!#! or a \verb!b!) of the character string in between
the inverted commas and submits the rest to \TeX\ as is. This means that
in chords such as \verb!"F#m"! or \verb!"BbMaj7"! the sharp and flat symbols
will be handled correctly and will even come out transposed correctly.
Also, for chords with more than one or two letters, you may need to add some
extra spacing (see \S\ref{sec-tex}) in
the tune to prevent two chords from overlapping. Finally, by default the letters
appear below the staff; this can be changed with the user settings,
\S\ref{sec-settings}.

\subsubsection{User settings}
\label{sec-settings}

Various user defined switches can be set in the file {\tt settings}
to customise the behaviour of the output. To set a switch just put
the name of the switch on a line in {\tt settings}. The switches are:--
\begin{itemize}
\item[] {\bf justify} -- when using Music\TeX\ this switch
right-justifies every line of music.

\item[] {\bf gchords above} -- puts guitar chords above the staff rather than
below.

\item[] {\bf autobeam} -- for many common meters, the code can, if required,
try to ensure that beams
contain the `right' number of beats. For example, in 6/8 double jigs, each bar
normally contains two beams of three eighth notes, or equivalent and so
with autobeaming set, the input {\tt abcdef} will produce
exactly the same output as {\tt abc def}; two beams of 3 eighth notes.
By default, i.e. with autobeaming off, the
input {\tt abcdef} produces one beam of 6 eighth notes.

\item[] {\bf oldrepeats} (for backwards compatibility) -- gives the old
output from \verb![1! \& \verb![2! for both \verb![1!, \verb![2!, \verb!|1!
and \verb!:|2!.

\item[] {\bf oldchords} (for backwards compatibility) -- forces the code
to recognise the old notation \verb!++! for chords as well as the new
\verb![]! -- e.g. \verb!+CEGc+! will give the same output as \verb![CEGc]!.

\item[] {\bf oldslurs} (for backwards compatibility) -- forces the code
to recognise the old notation \verb!s.s! for slurs as well as the new
\verb!(.)! -- e.g. \verb!sDEFsG! will give the same output as \verb!(DEFG)!.

\end{itemize}

\subsubsection{New notation}
\label{sec-custom}

The new notation letters, {\tt H-Z}, have been provided
because of demand by users to add extra symbols
into the manuscript and each letter can generate
3 different commands, depending on how it is used.

In the simplest form, the input {\tt S} will produce a
\verb+\userS+ in the output; \verb+\userS+ should then be defined
by the user either in {\tt header.tex}
or even in the \abc\ file and could, say, be used to produce
a horizontal space by defining \verb+\def\userS{\qsk}+.
In a similar manner, if using MusiX\TeX, you could mark bars as
the final repeats (in the same way as \verb+|1+ marks
them as first repeats) by using \verb+L|+ and defining
\verb+\def\userL{\setvolta{last time}}+.

More complicated use occurs when the input letter is combined with
a note ({\tt ABCDEFGacbdefg}). In this case the letter {\tt P}, say,
produces either \verb+\userPu{.}+ or \verb+\userPl{.}+ depending on whether
the following note is in an upper or lower beam. The argument
\verb+{.}+ is the Music\TeX\ note pitch. An example use
could be to mark a note with some accent, e.g. a V above
the note head, and in this case the command would be defined
\begin{verbatim}
\def\userPl#1{\zcharnote#1{\raise5pt\hbox{$\vee$}}}%
\end{verbatim}

N.B. To use a \TeX\ command combined with a note, the command letter must
be in the same place as the other note attributes (i.e. after a guitar
chord and before an accidental -- see \S\ref{sec-order}). Thus, in the
input {\tt J A} or {\tt J"Am"A}, the {\tt J} will produce the output
\verb+\userJ+. Also it is possible to have more than one \TeX\ command
per note (e.g. {\tt HIA} will produce two user commands combined with
the note.

It is, of course, possible to write \TeX\ commands for anything, including
sequences of notes, but the author {\em strongly} recommends that they
are not used for this purpose and, in general, used sparingly. The
reasons for this are twofold; firstly one of the strengths of
\abc\ notation is that it can be fairly easily understood by humans
-- this may not be the case if it is peppered with extra letters.
Secondly, the user commands will be ignored by other packages such as
{\tt playabc}, so any notes
or other musical marks normally understood by {\tt playabc} will be present
in the printed output but missing from the sound output.

\subsubsection{Internote spacings}
\label{sec-elemskip}

The internote spacing is set by the information field {\tt E}. As the format
is currently set up, {\tt E:8} \& {\tt E:7} can be used to squeeze long tunes
up a bit and {\tt E:10} and above to stretch short tunes.
Using {\tt E:6} really looks a bit too cramped.

\subsubsection{\TeX\ input}
%   =========
\label{sec-tex}

If there is a line in a tune file beginning with a \verb!\!, it is put directly
into the output file ({\tt music.tex}).
%abc.txt end
For example, you can use \verb!\qsk! to get small horizontal space within
a tune and \verb!\bigskip! or \verb!\medskip! to get vertical space. This
is acceptable input anywhere except within tune headers.

\subsection{Examples}

Examples are provided for most of the possibilities above. They can be found
in:--

\begin{centering}

\vspace{1ex}
\begin{tabular}{l|l|l}
Example & File \& Number & Section \\ \hline
Information fields & {\tt English:3} & \ref{sec-info} \\
Broken Rhythm & {\tt Strspys:1} & \ref{sec-broken} \\
Triplets & {\tt Strspys:1} & \ref{sec-triplets} \\
First \& Second Repeats & {\tt Jigs:1} & \ref{sec-repeats} \\
Line Breaking & {\tt English:1} & \ref{sec-lines} \\
Changing key mid-tune & {\tt Reels:1} & \ref{sec-key} \\
Changing meter mid-tune & {\tt English:2} & \ref{sec-key} \\
Changing default note length mid-tune & {\tt English:3} & \ref{sec-key} \\
Gracings & {\tt Strspys:2} & \ref{sec-grace} \\
Chords & {\tt Reels:2} & \ref{sec-chords} \\
%\TeX\ Input & {\tt Reels:2} & \ref{sec-tex} \\
Guitar Chords & {\tt English:3} & \ref{sec-guitar} \\
Internote spacings & {\tt Strspys:2} & \ref{sec-elemskip} \\
\end{tabular}

\end{centering}

\section{Running {\tt abc2mtex}}

Run the program with the command {\tt abc2mtex}. You will be prompted
to choose tunes with the line
\begin{verbatim}
select tunes:
\end{verbatim}
Typically you might respond with {\tt English:1-3,5,9-} which will select
tunes numbered 1, 2, 3, 5 and 9 onwards from the file {\tt English}. Just
entering {\tt English} or {\tt English:-} will select all the all the tunes
from {\tt English}. Note that there should be no spaces anywhere in this
input.

Alternatively, all the input can go in the command line,
e.g. {\tt abc2mtex English:1-3,5,9- Jigs:-10} and the program will even
read from the standard input, e.g. {\tt abc2mtex -}, which is useful to pipe
in the results of a search (see {\tt index.tex}). Also, if the filename
extension is {\tt .abc} then you don't need to type that in -- e.g. the input
{\tt Reels:1-10} will open the file {\tt Reels.abc} (if the file
{\tt Reels} doesn't exist). When the program has finished formatting the
chosen tunes (a matter of seconds) it will prompt you again with a {\tt select
tunes}. To quit the program simply hit return (or {\tt q} or {\tt quit}) at
this prompt.

Finally, if you want to keep processing the same tunes over and over again
you can store a list of their files and reference numbers in another file
and run the code with this file as an input (to save typing it in again).
There is an example in the following section.

\subsection{\TeX\ input}

If at the prompt
\begin{verbatim}
select tunes:
\end{verbatim}
you enter a line beginning with a \verb!\!, it is put directly
into the output file ({\tt music.tex}). This is a good way of putting
things like page headings directly into the document, e.g. something like
\begin{verbatim}
\headline{ENGLISH TUNES \hfil \folio}
\end{verbatim}
will generate a header and page number for each page.

This sort of input can then be stored in a file to save the
format of particular documents. For example, you could store
\begin{verbatim}
\headline{FLUTE MUSIC \hfil \folio}
\centerline{REELS}
Reels:1-9
\vfill\eject
\centerline{JIGS}
Jigs:1-4
\end{verbatim}
in a file and then run
\begin{verbatim}
abc2mtex < file
\end{verbatim}
Note that the \verb!\vfill\eject! causes a page break and the \verb!\folio!
generates page numbers.

\subsection{Command line options}

By default, {\tt abc2mtex} outputs Music\TeX\ to the file {\tt music.tex}
but this can be changed with the use of command line options. Thus
{\tt abc2mtex -i} creates an index of all the files in the file
{\tt index} and can even include the first two bars of each tune in
\abc\ notation (see {\tt index.tex}), while {\tt abc2mtex -x} produces
MusiX\TeX\ output in {\tt music.tex} (see \S\ref{sec-musix}).
The option {\tt -t} will transpose some or all of the tunes,
\S\ref{sec-transpose}.
The output file can be set with the {\tt -o} option, e.g.
{\tt abc2mtex -o Jigs.tex Jigs.abc}. It also possible to use combinations
of options, e.g. {\tt abc2mtex -x -t} to produce transposed MusiX\TeX\
output, but they must all come before the first input filename.

\subsection{Transposing tunes}
\label{sec-transpose}

If you select the option {\tt -t}, you will be prompted at every tune by
\begin{verbatim}
  Transpose?
\end{verbatim}
You should enter here the change in the number of sharps and flats you wish
to make. For example, if the tune is in G (1 sharp) and you wish to transpose
it up to A (3 sharps) you would enter {\tt +2} or just {\tt 2}. Flats are
counted negatively so that to transpose from G to F (1 flat
or $-$1) you would enter {\tt -2}.

If you have chosen to transpose the tune, i.e. entered anything other than
{\tt 0} you will then be prompted by
\begin{verbatim}
  Note offset?
\end{verbatim}
which is just the number of line and spaces that each note must move. Thus
going from G to A is just moving every note up one and so you would enter
{\tt +1} or {\tt 1} whilst G to F would require {\tt -1}. Note that something
like changing from E$\flat$ (3 flats) to E (4 sharps) has note offset {\tt 0}.

Alternatively, at the {\tt Transpose?} prompt, you can enter the interval, e.g.
\verb!^5! means transpose up a fifth. Possible intervals are shown in the table
below.

\begin{centering}

\vspace{1ex}
\begin{tabular}{l|l|r|r}
& & change & note \\
input & transposition & in $\sharp/\flat$'s & offset \\ \hline
\verb!^2! & up tone     & $+2$ & $+1$ \\
\verb!^5! & up fifth    & $+1$ & $+4$ \\
\verb!_4! & down fourth & $+1$ & $-3$ \\
\verb!^8! & up octave   & $ 0$ & $+7$ \\
\verb!_8! & down octave & $ 0$ & $-7$ \\
\verb!^4! & up fourth   & $-1$ & $+3$ \\
\verb!_5! & down fifth  & $-1$ & $-4$ \\
\verb!_2! & down tone   & $-2$ & $-1$ \\
\end{tabular}

\end{centering}

As well as generating transposed Music\TeX\ output in the file {\tt music.tex},
the {\tt -t} option also puts transposed \abc\ notation in the file
{\tt transpose.abc}. This is useful if you want to save the transposed version
and {\tt abc2mtex} can be run on this file.

Finally to transpose all of the selected input tunes the transposition and
note offset can be entered on the command line with
{\tt abc2mtex -t:<transpose>:<note offset>} or
{\tt abc2mtex -t:<interval>}. For example, to transpose
everything down a fourth, use {\tt abc2mtex -t:\_4} or {\tt abc2mtex -t:1:-3}

%\subsection{Beam checking}
%\label{sec-beam}
%
%For many common meters, the code can, if required, try to ensure that beams
%contain the `right' number of beats. For example, in 6/8 double jigs, each bar
%normally contains two beams of three eighth notes, or equivalent and so
%if you run {\tt abc2mtex -c jigs.abc}, the input {\tt abcdef} will produce
%exactly the same output as {\tt abc def}; two beams of 3 eighth notes.
%By default, i.e. without the {\tt -c} option, this check is not made and the
%input {\tt abcdef} produces one beam of 6 eighth notes.

\subsection{Running Music\TeX}

Once you have created {\tt music.tex}, simply run {\tt tex music.tex}.
This will produce a file {\tt music.dvi} which can be viewed (e.g. with
{\tt xdvi}) or converted into postscript (e.g. with {\tt dvips}).
The viewing/printing will depend on your system.

\subsection{Customising the output}

The file {\tt header.tex} contains most of the parameters
which decide the way the printed music looks. If you want to
customise the music output this is the first place you should start.
Brief instructions are contained in this file and an example
of how it could be set up contained in {\tt header1.tex}.
To try this out copy {\tt header.tex} to somewhere
safe and then copy {\tt header1.tex} to {\tt header.tex}.
Experiment!

\subsection{Using make}

If you are on a system that has the {\tt make} command there are a number
of shortcuts available. For example, entering {\tt make English.ps}
will run {\tt abc2mtex}, \TeX\ and {\tt dvips} on {\tt English.abc}
and put the results in {\tt English.ps} (though you may need to modify
the Makefile to suit your system). To tidy up at the end of a session,
simply type {\tt make tidy}, although be warned that this will remove
the files {\tt music.tex}, {\tt transpose.abc} and {\tt index}.

\section{Extensions}

\subsection{MusiX\TeX}
\label{sec-musix}

MusiX\TeX\ is a recent enhancement to Music\TeX\ available at various
ftp sites (see the {\tt README} file).
Currently it is in beta test phase and there are two versions available;
see the file {\tt Changes} for compatibility of versions.
It is a three pass system -- you run {\tt tex music}, then {\tt musicflx music}
and then {\tt tex music} again -- and this extra processing allows some nice
features to be built in such as proper slurs. It also runs considerably
faster than Music\TeX. The \abc\ notation isn't affected
but the main changes in the output should be that:
\begin{itemize}
\item The music is automatically right-justified.
\item Tuplets will have a slur marker by them and other slurs (see
\S\ref{sec-ties}) are now possible.
\end{itemize}
To generate MusiX\TeX\ output simply run {\tt abc2mtex} with the command line
option {\tt -x}.

\subsection{Multi-stave output}
\label{sec-multi}

A simple amendment has been made to the code to allow the generation of
multi-stave music. Specifically, the character \verb!&! is carried straight
through to the \TeX\ output and the characters \verb!&&! produce a
\verb!\enotes\notes! pair. Thus the input \verb!DEFG & ABcd && A4 & e2 c2|!
produces:

\begin{music}
\def\freqbarno{99}
\generalsignature{0}\relax
\generalmeter{\meterC}\relax
\normal\elemskip=8.5pt
\def\nbinstruments{2}\relax
\debutextrait
\notes\Ibu0{d}{g}{3}\qh0{d}\qh0{e}\qh0{f}\tbu0\qh0{g}
& \Ibl0{h}{k}{3}\qb0{h}\qb0{i}\qb0{j}\tbl0\qb0{k}\enotes
\notes\hu{h} & \ql{l}\ql{j}\enotes
\finextrait
\end{music}

To explain this to those unfamiliar with Music\TeX, the \verb!DEFG! are put
on the lowest stave. The \verb!&! then tells Music\TeX to move up a stave,
where it puts the \verb!ABcd!. The first notes of each group are aligned.
The \verb!&&! (or a bar line) moves the output back down to the lowest stave
and resets the alignment, so that in this case, the \verb!A4! is on the lower
stave, and is aligned with the \verb!e2! on the upper stave.

The number of staves and whether or not they are bass or treble clefs is
specified by a simple amendment to the {\tt K:} field. Thus \verb!K:G 1&3!
means 4 staves with the bottom one in the bass clef; \verb!K:G 0&2! means 2
staves both in the treble clef. Notes on the bass clef are automatically shifted
down one octave. The \verb!i&j! part of the {\tt K:} field should come after
any mode/scale specification and before lists of global accidentals,
e.g. \verb!K:D aeolian 1&3 ^f!.

Note that this is regarded as an essentially unsupported feature put in to take
some of the pain out of coding Music\TeX. Several things may not work
properly, such as bar counting or slurs \& ties (although it would not be too
difficult to make them work if there was the demand) and it is likely that, for
all but the simplest melodies the raw \TeX\ output will need editing. Also,
because \abc\ notation in this form is both difficult to write and read, it is
probable that if multi-stave music becomes properly a part of \abctmtex\ it
will be in the form already available with {\tt playabc} (using {\tt I:part 1},
\ldots, {\tt I:part final}).

\section{Bugs and features}

Error handling is reasonably good; the code won't accept characters it doesn't
recognise and it also tries to give helpful
error messages. It exits if it finds the unescaped special characters
\verb!# &! in an information field since \TeX\ will choke on them.
They can, however, be used by escaping with a backslash (\verb!\!) --
e.g. use \verb!\#! rather than \verb!#!.

The code will also attempt to check the length of each bar. It ignores leading
notes and bars that finish with a repeat or double bar symbol, but for other
bars which are too long or too short it gives a warning indicating the bar and
line number. The bar numbering is a little quirky; the first {\bf complete}
bar of a line should be number 1 (so that leading notes are bar number 0). It
can correctly handle duplets, triplets and quadruplets but quietly ignores
bars with other tuplets.

%\section{Listening to \abc\ tunes}
%\label{sec-playabc}
%
%A complementary program, {\tt playabc}, which can `play' \abc\ notated tunes
%through the speaker of a Sun workstation has been written by Don Ward. It is
%available by anonymous ftp from {\tt celtic.stanford.edu} in the file
%{\tt /pub/tunes/playabc-1.1.tar.gz} or, if you have problems with ftp, from me.
%
%As it stands {\tt playabc} will just play all the tunes in a chosen file.
%However, it is possible to use the {\tt search} program to select tunes and
%pipe this in to {\tt playabc}. Thus the command
%{\tt search -i X:1-3,6,8- -abc Jigs.abc | playabc | tune | play} would play
%tunes 1 to 3, 6 and 8 onwards from the file {\tt Jigs.abc}.

\section{The future}

Sometime in the future it is hoped to provide:

\begin{itemize}
\item Alignment of music \& lyrics -- this may be {\bf difficult} and will
have to wait until MusiX\TeX\ has settled down.
\item A proper front end parser (probably using Don Ward's lex parser for
{\tt playabc}).
\end{itemize}

\end{document}