\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>} 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 }, {\tt } (e.g. roll, staccato marker or up/downbow), {\tt }, {\tt }, {\tt }, {\tt }, 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::} or {\tt abc2mtex -t:}. 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}