\documentclass[11pt]{article}
% mtxlatex and mtxdoc must be loaded before any font-defining packages
% like charter, bookman etc
\usepackage{color,mtxlatex,mtxdoc,multicol} 
\paperAfour
% You might like to put \paperUS here
\usepackage[T1]{fontenc}  %  for the acute accent in psalm42; RDT 2020-09-11
\usepackage{verbatim,charter}
% \renewcommand{\ttdefault}{cmtt}  
% Some such font packages override cmtt with wider fonts like 'courier', 
% and then 80-character lines don't fit
\newcommand{\delete}[1]{\relax}
\newcommand{\archiveSite}{
 \texttt{http://icking-music-archive.org}
}
\newcommand{\scoreSite}{
 \texttt{http://imslp.org}
}
\newcommand{\mailingList}{
\texttt{tex-music@tug.org}
}
\newcommand{\repository}{
\texttt{https://github.com/dlaurie/M-Tx}
}

\def\versionname{0.63c}
\def\version{0.63c}
\def\newfrom{0.61}
\date{15 January 2019}
\title{\Huge \textbf{\MTx: Music from Text \\ \LARGE Version\current} \\
  User's Guide \vfill}
\author{\LARGE Dirk Laurie\\ \texttt{dirk.laurie@gmail.com} }

\makeindex
\begin{document}


\vfill
\maketitle
\vfill
\begin{center}  
  \framebox[5in]{\parbox{3.6in}{
    \begin{mus} \input title.tex \bigskip \end{mus}
  }}        
\end{center}
\vfill\vfill\vfill
\thispagestyle{empty}

\pagebreak
\pagenumbering{roman}
\tableofcontents
\pagebreak
\pagenumbering{arabic}
\section{Music from Text}
  Written music has a distinctive appearance, very unlike written text.
But if we want to enlist the aid of the computer to print our scores, we 
either need a sophisticated graphical interface, or we must describe 
music in terms of what we are able to type.   Text input is not going to 
look much like printed music, but we would like it to resemble printed 
music closely enough that we can see the correspondence. 

\MTx~is a language for typed music aimed at people who are not experts.
Later in this document a full description of \MTx~is given, but to start 
with, here is a sample of what \MTx~input looks like.
\verbatiminput{mozart0.mtx}
Before showing you how it comes out, let's observe and discuss it.
There are two lines of input, which means that there are two voices 
of music, one for each line.  (Line boundaries are important in \MTx.)
The lines read from top to bottom as printed music reads from top to 
bottom.

Each voice contains a number of `words' separated by blanks.   In this 
example, each \ixem{word} stands for either a note or a bar line.  Bars are 
also important in \MTx, although the example is simple enough that I 
could have omitted them.  For greater readability, I have typed extra 
blanks so that notes and bars that are aligned in the printed version 
also line up here, but that is not necessary.  What is necessary, 
though, is that each line ends at the end of a complete bar.

The \ixem{notes} are written in the \PMX\ language designed by Don Simons.  
Each note starts with one of the letters \texttt{a} to \texttt{g}, which mean 
exactly what you think.  Lower case is easier than capitals, because it is 
quicker to type.  Some notes have suffixes after them.  A digit indicates the 
duration (1/\mark2, 1/\mark4, 1/\mark8, 1/\mark16, 1/\mark32, 1/\mark64).\footnote{Yes, it is more 
logical to think \texttt{1} should mean a whole note, but we don't want to 
type two digits for something so common as a semiquaver.  A whole
note is denoted by \ttxem{0}, which looks a bit like a printed semibreve.}  
When a note has 
no digit, it means that the \ixem{duration} is the same as that of the 
previous note in the same voice.  Some note names have a \ttxem{+} or 
\ttxem{-} after them, which means that it is not the nearest note of that 
name, but that there is a \ixem{jump} of at least a fifth up or down from the 
previous note.  One note is dotted, \index{notes!dotted} which is indicated 
with a \ttxem{d}.  It cannot be confused with a note name, because it is not 
the first letter of its word. A double-dotted note\NEW{0.51}
would have \texttt{dd}. 

The first note in each voice of the piece doesn't have a previous note.  
Since you haven't specified anything else, it is assumed that the top 
line is in the treble clef and its notes come in the \ixem{octave} running from 
middle C upwards; and the bottom line is in the bass clef and its notes 
come in the octave just below the one for the treble clef.  The first 
note of the top voice is the C above middle C, so we need a \texttt{+} 
for it.   \NEW{0.30}  If ever again you prefer the initial octave of a voice to wherever
the previous note puts you, use a \ttxem{=} after the note name. This
can be combined with \ttxem{+} or \ttxem{-}.

Here is the printed version of the above excerpt.

\vskip-5mm\hskip -18mm
\begin{mus}
\input mozart0.tex
\end{mus}

Do you think this looks good?  Much better than handwritten?  You are 
right, but look at the following version:

\begin{center}
\begin{mus}
\input mozart.tex
\end{mus}
\end{center}

There is a \ixem{heading}, the notes are not stretched out so much, and the two 
staves of the piano are grouped together.  To achieve this, the input looks
as follows:
\verbatiminput{mozart.mtx}
The notes are exactly the same as before, but there is an introductory 
paragraph, or \ixem{preamble}, that specifies what to do with them.  A 
\ixem{paragraph} in \MTx~is a group of consecutive lines set apart by 
one or more blank lines.  Most of the paragraphs contain notes, but the 
printed music will not necessarily be broken at the same places as 
the paragraphs. 

Only in the simplest cases (every music line in the paragraph starts with
what might be a note) are you allowed to omit the preamble.  The preamble 
lines in this example are self-explanatory, I hope. 

A few words on technical terms, to make sure that we know what we are 
talking about:
\begin{itemize}
  \item  A \ibxem{line} is a text line of typed music.
  \item  A \ibxem{word} is a string of consecutive non-blank characters,
separated by blanks from other words on the same line.
  \item  A \ibxem{stave} is the familiar group of five closely spaced 
parallel lines on which music is written.
  \item  A \ibxem{voice} is a melodic strand of music, of which there 
may be either one or two per stave.
  \item An \ibxem{instrument} corresponds either to a single stave or to a 
group of two or more adjacent staves linked together with a brace
\verb'{', usually representing a single instrument like a piano. 
  \item  A \ibxem{system} is a group of staves for the various 
voices that are heard at the same time.
\end{itemize}



\subsection{Lyrics}

I wrote the \MTx\ converter because \ixem{lyrics} are not part of the \PMX\ 
design.   It used to be\footnote{I.e.. before Rainer Dunker's \texttt{musixlyr} package, on which \MTx\ depends, became \PMX-aware.}
a major effort to obtain pretty output like the 
following:
\vskip 12pt \hskip -20mm
\begin{mus}
\small
\input netfirst.tex
\end{mus}

The lyrics are in \ixem{Afrikaans}, which maybe looks incomprehensible, but 
knowing as much as you do already, it 
should be quite easy to understand the following input:
\verbatiminput{netfirst.mtx}
There are a few new things: \ttxem{Style}\texttt{: }\ttxem{SATB} to 
indicate four-voice choral music on two staves, \ttxem{Sharps} for the key 
signature (of course there is \ttxem{Flats} available too), \ttxem{Meter} 
for the time signature, and \ttxem{Space}\texttt{:~9} to 
indicate that there should be nine interlines of extra space between the 
staves.\footnote{One \ixem{interline} is the distance between two lines in 
a stave.  The normal distance between staves is five interlines, but 
sometimes extra space on a page is distributed between the staves: you may 
need to experiment.}  If there are more than two staves, you can prescribe 
a different extra distance for each on the \texttt{Space} line.  This is 
the one preamble command that may also appear later in a music paragraph. 

Among the notes, you notice suffixes \ttxem{s} and \ttxem{n} for 
`\mark sharp' and `\mark natural', and \ttxem{r} for `displace 
notehead to the \mark right'. 

But the main novelty is the lines of lyrics.  The rule is: each lyrics 
line is identified by the \ixem{label} \ttxem{L:}, followed by lyrics of the 
verse in question.  Syllables are indicated by hyphens, and you don't 
use bar lines on lyrics lines.  If more than one note belongs to a 
\ixem{syllable}, you need not worry, as long as the notes in question have been 
slurred or beamed together ---  each lyrics line is synchronized to the
immediately preceding voice.  There may be a set of lyrics lines for 
each stave in the score: if a stave has two voices, only one of
them can have lyrics specified by \texttt{L:} --- see Section
\ref{More lyrics} for a feature that allows both voices to have lyrics.

Note the \ixem{verse numbers}.  The rule is: 
if you code a number followed by a point and a blank at the 
start of a lyrics line, this number will not be treated as a syllable but 
will be printed to the left of the first lyrics syllable: the position of that 
syllable will be the same as if the number was not there.  This may not be
just what you want: see the \musixlyr\ reference manual (Section
\ref{help}) for commands that can modify this behaviour.

\subsection{Bars and meter changes}

The notation for bars is taken from Chris Walshaw's \ABC\ music 
language, with one small modification.  
\vskip 1ex
\begin{tabular}{ll}
\ttxem{\|} & Normal bar line \\
\ttxem{\|]} & Thin-thick double bar line (as at the end of a piece) \\
\ttxem{\|\|} & Thin-thin double bar line (to separate sections) \\
\ttxem{:\|} & Left repeat \\
\ttxem{\|:} & Right repeat \\
\ttxem{:\|:} & Left-right repeat 
\end{tabular}
\vskip 1ex

Bar lines make life easier, but are normally optional.  Only the
normal bar line actually implies a bar separation: the double line and
\ixem{repeat} signs may appear in mid-bar.  The fancy bars must appear
in the bottom voice and are optional elsewhere.
  \begin{itemize}
    \item  If you do put them in, \MTx\ will check that there are no shorter 
bars than the currently defined one.   If a too-short bar occurs at the end of 
the final paragraph, \MTx\ assumes you know what you are doing, and 
automatically redefines the meter without printing a new time signature.  If 
it appears elsewhere, it is an error. 
    \item  If your piece starts with a \ixem{pickup}, it is defined by a bar 
line at the end of ``bar 0'', i.e.~the incomplete bar containing the pickup. 
Even when there is a repeat sign after the pickup, so that you don't actually 
see a bar line in the printed music, you still need a bar line before the 
repeat sign, otherwise \MTx\ cannot know where the pickup stops.  The bar line 
defining the pickup is compulsory in the first voice found, and optional but 
recommended in the others.      When there is a pickup, the meter is not 
redefined. 
    \item   If you do not explicitly end the piece with 
one of the other types of bar line, a thin-thick bar line is 
automatically provided: you don't need to code it. 
    \item  \PMX\ allows you to put two voices on a single stave by
giving the notes of the lower voice first, followed by \ttxem{//} and the 
notes of the upper voice.  This construct works in \MTx\ too when only
one voice for the stave was specified in the style, but for just 
one bar at a time; such a bar \emph{must} be terminated by a bar line. 
Use it only for very short stretches.  You will probably need to
set the octave in the first note using \verb"=".
  \item  If you are using \PMX\ features that are not recognized by \MTx\ but 
simply passed through, you may need a bar line to tell \MTx\ to which bar 
they belong.  
 \end{itemize} 

Apart from the final `blind' meter change that is automatically made if 
required, you can also define other meter changes.  \index{blind!meter~change}
The rules are:
  \begin{itemize}  
  \item  The \ixem{meter change} may only occur at the \emph{very} beginning 
of a bar after 
a full bar of the meter previously in effect, and must be made in all 
voices.  In particular, any key change, volta indication etc.\ must come
\emph{after} the meter change; also, the bar following the pickup may
not contain a meter change but must have the length specified in the
preamble.
  \item  The normal meter change word looks like a fraction, 
e.g.~\ttxem{3/4}.  This always gives a visible meter change.
  \item  If the printed meter symbol looks different from the logical one (you 
want a big `C' instead of `4 over 4', for instance), you may use a \PMX\ 
formatted meter change word. \NEW{0.30}  
E.g.~\ttxem{m3/4/0/0} gives a blind meter change 
--- one that takes effect but is not printed.  See the \PMX\ manual.
This is also legal in the preamble \ttxem{Meter:} command. 
   
  \end{itemize}

\subsection{Beams and \ixem{slurs}}  \label{beamslur}

Thanks to \PMX, \ixem{beams} in instrumental voices are automatic. \MTx~does, 
however recognize that it is customary in vocal music to use beams only 
when the notes in question are sung to the same single syllable.  So if you 
select a style like \ttxem{SATB} or \ttxem{Singer} that involves 
voices, notes will normally appear unbeamed, except those that appear 
under slurs. To override this, you need to use the \PMX\ ``forced beam'' 
feature, e.g. \verb"[ c d ]", or disable the 
\ttxem{unbeamVocal} feature (Section \ref{customize}).  \index{beam!forced}
See Section \ref{beam&slur} on how to 
fine-tune beams, and Appendix \ref{melisma} for some examples involving
lyrics.  

The slur notation is similar to forced beams, but uses parentheses.
Look at the second system of the same song: 

\hskip -20mm
\begin{mus}
\small
\input netsoos1.tex
\end{mus}
Omitting the preamble, this is coded 
as:\footnote{The coding is for this 
morsel only, not an extract out of the coding for the whole piece.  The 
octave of the first note here is the default, not deduced from a 
previous note.} 
\verbatiminput{netsoos1.mtb} 
Apart from \ttxem{f} for `\mark flat' you should notice the left 
parenthesis \ttxem{(} to start a slur and the right parenthesis 
\ttxem{)} to close it.  So 
\MTx\ knows that e.g.~the \texttt{c} in the top voice falls under the 
slur, and does not use up a syllable of lyrics.  The default direction
\index{slur!direction}
of a slur is up for the upper and down for the lower voice in a stave, 
but you can override that: see Section \ref{beam&slur}.

You are allowed to have a slur under another slur, \index{slur!nested} 
e.g.~\verb"( c8 d e ( f g ) f d b ) c2".

Occasionally a slur ends at a note and the next one starts 
immediately.  \NEW{0.30} For such a slur continuation \index{slur!continuation}
you code \ttxem{)(} as a single word after the note.   

If you want a tie rather than a slur, \NEW{0.55}
use braces \ixem{\LBR} \ixem{\RBR} instead of parentheses.  
A continuation tie is of course \ixem{\RBR\LBR}.

In obscure situations you may want absolute control over slur stops and
starts.  To do this, put an identifier, which must be a non-zero digit
or a capital letter, immediately after the slur parenthesis or brace,
before any adjustments.  Of course, any labelled slur of either kind
that you open must be closed again by its exact partner.  If you really
must have interlocking slurs,  \verb"(1 c8 d e (2 g g )1 f d b )2 c2"
is the way to get them.  \delete{Labelling slurs in this way is also the only way
of getting more than two levels of slurs.}

It may happen that you do not wish \MTx\ to put more than one note to a 
syllable even though the notes are under a beam or slur.  
For example, you 
may wish to use \ixem{phrase marks} that only look like slurs, or you may be 
writing music that has so many consecutive short notes that the beat 
becomes difficult to follow without beams.   \NEW{0.30}The way to do
this is to double the first symbol of the word starting the forced beam
or slur.  E.g.  \verb"{{+10" \index{\LBR\LBR} or \ttxem{((} may be used
to start a phrasing slur, and \ttxem{[[} may be used to start a forced
beam \index{beam!forced} that will still keep one note to a syllable.
The terminator for the beam or slur should not be doubled.  A variation
of this feature occurs mainly when you have multi-verse lyrics and
\NEW{0.43} there should be a slur in one verse but not in another.
Start the slur with \ttxem{(\dquote} or \ttxem{\LBR\dquote} to get 
the same effect as  
\verb'((' or \verb'{{', except that the slur symbol itself is no longer
solid, but broken like a dotted line.  \index{slur!broken}
\NEW{0.54} Synchronize lyrics by using void syllables and extension rules, e.g.

\bigskip
\example{dwoman}{mtb}{80mm}{\fill}{72mm}{-10mm}{c}{5mm}
\bigskip

The trailing underscore on ``heart'' takes the place of a
syllable of lyrics, and on a longer note would
produces a lyrics rule that extends to the end of the melisma.
You can use as many underscores as required; for very long melismas,
you can code e.g.\ \verb"Ah_6" instead of \verb"Ah______".
 
The converse of this situation is that you want \MTx\ to
make a melisma, but you don't want a visible slur.  \NEW{0.42}
Code
the slur beginning as \ttxem{(\snake} or \ttxem{\LBR\snake} and 
the slur end as \ttxem{)\snake}
or \ttxem{\RBR\snake}.  This gives a ``blind'' slur: invisible, but having the
same effect on lyrics as a normal slur.  \index{blind!slur} Blind slurs
should not have any other tuning marks.

\subsection{More complicated lyrics}  \label{More lyrics}

Lines of lyrics that start with \ttxem{L:} are set in the middle 
between two staves (or below the bottom stave) and are aligned with the 
notes of the voice under which they appear in the input file (in this 
case, the alto).   Such lines are referred to as \emph{normal} lyrics
lines.  \index{lyrics!normal}

Sometimes different words apply to different voices, as in the last line 
of the song: 

\hskip -20mm
\begin{mus}
\small
\input netsoos2.tex
\end{mus}
\vskip 12pt
This is coded as:
\verbatiminput{netsoos2.mtb}
Some interesting \PMX\ features in this piece are \ttxem{of} for 
`\mark ornament: \mark fermata' and \NEW{0.43}
\ttxem{rp+6} (\mark rest: 
\mark pause) for a full-bar rest moved up six interlines.  
For the meaning of the \verb'@...' words, see the next section. 

The label \ttxem{LT:} (\mark Lyrics: \mark Tenor) marks the line as 
belonging to a particular voice.  Such a line is referred to as an 
\emph{auxiliary} \index{lyrics!auxiliary}
lyrics line, and may only appear on a stave that
already has a normal lyrics line.  Labels for voices are defined in the 
\ttxem{Style}, or may simply be numbers: the voices are numbered 
1,2,\ldots\ from the top line downwards. Auxiliary lyrics for the top voice 
on a stave (soprano and tenor) will be set above the stave, and those 
for the bottom voice (alto and bass) below. Their input lines may appear 
anywhere in the paragraph, since the labels show where they go. 

You can also use voice \ixem{labels} without a leading \texttt{L} to identify 
the voice lines.  This is necessary if some voice is omitted from the 
paragraph (\MTx\ will fill its stave with rests) or if you prefer to 
have the voices in a different order (e.g.~bottom-up) than top-down.  
You need only label a voice line if it does not belong to the voice 
immediately following the previous one. 

\subsection{Preamble commands}

Here is a complete list of built-in \ixem{preamble} commands, with examples and 
explanations.  Case in preamble commands is immaterial: all command and 
style names are translated to uppercase internally.
\vskip 1ex  
\begin{tabular}{ll}
\verb"Part: Recorder" & Part name (set flush left above title) \\
\verb"Title: Clarinet Quintet" & Title of piece. \\
\verb"Composer: Mozart" & Name of composer (set flush right below title) \\
\verb"Poet: Rellstab" & Name of poet (set flush left below title)  \\
\verb"Meter: C/" & \textit{Alla breve} meter: another notation for \verb"2/2". \\
\verb"Flats: 3" & Key signature has three flats. \\
\verb"Sharps: 2" & Key signature has two sharps. \\
\verb"Space: 10; 6 0 3" & Extra interlines of space after title block (optional) and below staves. \\
\verb"PMX: Ar" & \PMX\ command in preamble.\\
\verb"Options: x" & Forces the \texttt x option to be in effect, despite the command line. \\
\verb"Enable: pedanticWarnings" & Enables the \texttt{pedanticWarnings} feature. \\
\verb"Disable: unbeamVocal" & Disables the \texttt{unbeamVocal} feature. \\
\verb"Pages: 2" & Set the piece over two pages. \\
\verb"Systems: 11" & Use a total of eleven systems. \\
\verb"Bars/line: 4" & Try to use on the average four bars to a line. \\
\verb"Size: 16" & Size of music in points: default is 20. \\
\verb"Width: 190mm" & Width of line in \texttt{mm} (or \texttt{in} or 
\texttt{pt}). Default is \texttt{190mm}.\\
\verb"Style: Singer Piano" & 
  The piece is for a singer with piano accompaniment. \\
\verb"Name: Dietrich Gerald" & Names of instruments, performers etc. \\
\verb"Indent: 0.10" & Indent first system by 10\% of the music width. \\
\verb"Start: @+1;@-3" & Put specified items at the start of voice lines\\
\verb"Octave: 4 4 3 3" & Specify \indexed{initial octaves} for each stave \\
\verb"TeX: \elevensf" & Type 2 TeX code (see Appendix \ref{expert})\\
\end{tabular}  \NEW{0.54}
\vskip 1ex
The \ttxem{Bars/line} command should only be used when you do not yet 
know what \ttxem{Pages} and \ttxem{Systems} should be.

The style line may contain several style elements (instruments etc.).
\index{style!elements}
At present, \MTx\ knows the following style elements:
\begin{verbatim}
SATB:    Voices S,A T,B; Choral; Clefs G F
SATB4:   Voices S A T B; Choral; Clefs G G G8 F
SINGER:  Voices S; Vocal; Clefs G
PIANO:   Voices RH LH; Continuo; Clefs G F
ORGAN:   Voices RH LH Ped; Continuo; Clefs G F F
SOLO:    Voices V; Clefs G
DUET:    Voices V1 Vc; Clefs G F
TRIO:    Voices V1 Va Vc; Clefs G C F
QUARTET: Voices V1 V2 Va Vc; Clefs G G C F
QUINTET: Voices V1 V2 Va Vc1 Vc2; Clefs G G C F F
SEXTET:  Voices V1 V2 Va1 Va2 Vc1 Vc2; Clefs G G C C F F
SEPTET:  Voices V1 V2 Va1 Va2 Vc1 Vc2 Cb; Clefs G G C C F F F
\end{verbatim}
\ttxem{Voices}  gives the labels of the voices, later used to identify 
lyrics lines and out-of-sequence music lines.  You should not use labels
like \texttt{L}, \texttt{U}, \texttt{C}, \texttt{1} or \texttt{L1} 
that conflict with \MTx's use of labelled lines for chords, lyrics etc.
Labels separated by
blanks belong to voices on different staves; labels separated by a comma, 
to voices on the same stave.  \ttxem{Clefs} define the clefs, one for each
stave.  You can use any PMX-supported clef symbol in addition to G and F
--- see Appendix \ref{ornaments}.
The symbol \verb'8' or \verb'G8' indicates music written in the treble clef 
\NEW{0.49} but sounding an octave lower, as is usual for the tenor voice in 
choral music.

\ttxem{Vocal} means that the voices will be treated as vocal for the 
purpose of beams and lyrics, and \ttxem{Continuo} means that the staves 
belong to 
a single instrument, and will be grouped together by a \ixem{brace}. 
You may not have too many voices or staves --- see Appendix \ref{limits}.

\ttxem{Choral} means that the voices form a choir.  This implies that each
voice is vocal, and their staves will be grouped together by a bracket.  
You can get the \ixem{bracket} for instrumental voices too, by using
\ttxem{Group} instead of \texttt{Choral}.

You may define your own style elements, \index{style!elements}
e.g.: \\

\texttt{Honky-Tonk: Voices R L; Clefs G F; Continuo} \\

The whole preamble is read, and new style elements saved, before any of the 
commands is interpreted.  So it does not matter in which order the commands 
come.  The preamble may be spread over more than one paragraph. \NEW{0.49}  
But if you issue a command more than once, only the last instance counts. 

The \ttxem{Start} command is mildly convenient when you are experimenting with 
fine-tuning, since it allows small additions affecting the beginning of 
each voice to be collected in one place.  It comes into its own when
combined with the multi-score option (see Section  \ref{multiscore}).
\NEW{0.42}  Items for each voice are separated by semicolons and may contain
blanks.  These are prepended to the corresponding line of the first
paragraph, so the \emph{combined} length of the starting item and the
line in question should not be too long (see Section \ref{limits}).

You don't normally need to specify \NEW{0.54} \ttxem{Octave}, 
\index{octave@octave!defining initial}
since most of the time the octave implied by the clef is correct.

\ttxem{TeX} \NEW{0.61} should be used for last-minute overrides
of commands that come from system \TeX\ files like \verb`mtx.tex`
and \verb`pmx.tex`.

\subsection{Customizing \MTx} \NEW{0.55} \label{customize}

You have a lot of control over how \MTx\ does its translation.  The old way
of customizing \MTx\ was by compiler options and the \ttxem{Options:}
preamble command.  That method uses one-character switches, which is
only slightly mnemonic and anyway the letters get used up.  
The new way is to use the \ttxem{Enable:} and \ttxem{Disable:} 
preamble commands to select the features you want.  

	Here is a list of switchable \MTx\ features that are 
enabled by default:

\begin{description}
  \ttxi{splitShortcut}  Separate 2:1 and 3:1 shortcuts into two words, and
   explicitly code their durations.
  \ttxi{newWordShortcut}  Allow 2:1 and 3:1 shortcuts to be entered as 
    separate words.
  \ttxi{multiFile}  Take \texttt{Include:} lines into account, otherwise
    ignore them.
  \ttxi{doChords} Take \texttt{C:} lines into account, otherwise ignore them.
  \ttxi{doUptext} Take \texttt{U:} lines into account, otherwise ignore them.
  \ttxi{doLyrics} Take \texttt{L:} lines and inline lyrics changes into
    account, otherwise ignore them.
  \ttxi{unbeamVocal} Unbeam non-melismatic notes in vocal lines.
  \ttxi{hideBlindSlurs} Hide \verb"{~" and \verb"(~" slurs.
  \ttxi{interpretSlurs} Translate slur signs to PMX \texttt{s} and \texttt{t}
    slurs.
  \ttxi{uptextOnRests} Synchronize uptext with notes and rests, not only with
    notes.
  \ttxi{checkAssertions} Interpret certain comments as assertions (see Section 
   \ref{debugging-aids}.
\end{description}

Here is a list of switchable \MTx\ features that are 
disabled by default:

\begin{description}
  \ttxi{solfaNoteNames} Use \ixem{tonic sol-fa} 
  note names \texttt{d r m f s l t} (for \emph{do, re, mi, fa, sol, la, ti}).
  This will be translated to the usual note names \texttt{c d e f g a b} 
  in C major.  Use the \PMX\ transposition feature to obtain the desired
  key.  Only the basic note names are supported: you should not use the 
  sol-fa chromatic note names (e.g.\ \emph{re, ma,}) but the basic sol-fa
  note names with \PMX\ accidentals (e.g.\ \texttt{ds}, \texttt{rf}).  

  This feature conflicts in some cases with other uses of these letters.
  To retain the standard meaning in sol-fa mode, precede the word with a 
  \verb'"', e.g.\ use \verb'"r' for a rest since \verb'r' translates to
  a \verb'd'.

  \ttxi{pedanticWarnings}  Suppress pedantic warnings, i.e.\ cases where
you omitted something but the default action is probably what you want.
  \ttxi{ignoreErrors} Do not stop on the first error.   
(Errors are messages clearly marked with \ttxem{ERROR} --- 
any other message printed is informative or a warning only.)

  \ttxi{instrumentNames}  Indent first system and print default 
   instrument names.
  \ttxi{beVerbose} Verbose progress report.  Default behaviour is 
to print out errors, warnings, and very little more.
  \ttxi{debugMode}  Give messages that may be helpful in finding bugs
in the \texttt{prepmx} program.
\end{description}

You can put as many features as you like on the \texttt{Enable:}
and \texttt{Disable:} lines, just separate them by spaces.  You can 
also have as many \texttt{Enable:} and \texttt{Disable:} lines as you want.
For example, to imitate the way \MTx\ 0.54c did things, put
\begin{verbatim}
Enable: interpretSlurs
Disable: newWordShortcut multiFile checkAssertions
\end{verbatim}

\section{Fine-tuning the printed output}

The decisions made by \PMX\ represent a good compromise in the majority 
of cases, but sometimes the first printout is disappointing.  You can 
influence the details of the layout in various ways.  You will probably 
need to look at the first draft, make fine-tuning changes, look at the 
second draft, \dots several times, if you are a real perfectionist.

\subsection{General vertical and horizontal spacing}

It is best to use \ttxem{Bars/line} in the preamble for the first draft.  
You can then decide how many systems in total are required for proper 
horizontal spacing, and over how many pages they need to be spread for 
proper vertical spacing.  On the later drafts you will therefore use 
\ttxem{Pages} and \ttxem{Systems} in the preamble. 

There are \PMX\ commands to put line and page breaks where you like --- 
see Appendix \ref{pmx}. 

You can use \ttxem{Space} to control the vertical space between the
staves.  There may be a number for every stave: the last number is
interpreted as extra space below the bottom stave.   You will probably
need to specify it if you have lyrics or very low notes down there.
This command can be issued in any music paragraph, not only in
the preamble. It will take effect at the start of the next system.
If issued in the preamble, however, you may optionally also give extra 
space to be inserted below the title block, separated from the other 
numbers by a semicolon.  \NEW{0.63} 
See Appendix \ref{voltas} for an example of how this command interacts
with lyrics adjustments.

You can specify different sizes for the instruments, 
e.g.\verb" "\ttxem{Size:}\verb" 13 16 "  \NEW{0.30}
might be appropriate for the main score
of a violin sonata, with the notes of the violin smaller than those
of the piano.  Valid sizes are 13, 16, 20, 24 and 29. 
Size is a delicate issue: see Appendix \ref{sizes}.   

You should be aware of what the \PMX\ manual calls a ``benign bug''.
Pages more than approximately half full get filled out by distributing
the vertical space among the staves.  This means that the appearance of
the score may drastically change when you add one more stave.  For this
reason it is best to leave space adjustments till last, when you already
know what values to give for \ttxem{Systems} and \ttxem{Pages}.

Occasionally \PMX\ underestimates
the total height of a page and you end up with one system less than
you wanted, which then appears by itself on a page of its own.  This
is particularly likely if you asked for extra space between the
staves, or are using different-sized staves.  A dirty 
trick that fixes this problem is to specify a little more height
directly to MusiX\TeX\ than you told \PMX: see Appendix \ref{pmx}.

\subsection{Lyrics placement}  \label{fine-tune-lyrics}

Sometimes the default position for placing lyrics causes ugly clashes 
with note stems, beams, slurs etc.  
You can move lyrics up or down by 
inserting a word starting with \ixem{\atsign} in the music line to which that
lyrics line is attached.   For example, \verb"@-2" (`at minus two') 
indicates that the lyrics should be moved down two internotes.  One 
\ixem{internote} is the vertical distance between e.g. a B and a C, i.e.~half 
of one interline.  The change takes effect at the start of the bar 
in which it appears, and remains in effect until further modified 
by another shift.  Each voice has its own associated shifts: one for
normal lyrics and a different one for auxiliary lyrics.  
\index{lyrics!auxiliary}

You can also say \verb'@^-2' (``put the lyrics above the stave at
two internotes below the default position'') or \verb'@v'  (``put the 
lyrics below the stave at the default position'').   These commands 
discard any shift that may have been in effect for that set of lyrics before.

Be warned that the default position itself is not fixed relative to the 
stave but depends on the general vertical layout.  So if you change a 
layout parameter after having placed the lyrics `perfectly', they may 
need a further adjustment. 

\NEW{0.30}Occasionally you need a syllable spanning two words.
You can code a \ixem{hard blank} to string the words together,
e.g.  \verb'Egit-to~ad I-si-de', but it also looks good to use an
underscore which will be translated to a link, \index{lyrics!link}
e.g. \verb'Egit-to_ad I-si-de' will become: Egit-to\lyrlink ad I-si-de.
If the link gets in the way of letters with descenders, you can lower
it,  e.g.  \verb'pretty\_and smart' becomes: pretty\lowlyrlink and smart.

\subsection{Beam and slur placement}  \label{beam&slur}

The decisions made by \PMX\ in choosing the height and direction of 
beams and slurs may differ from what you would like.  The slur start 
character may have the suffixes \mark up, \mark down or \mark lower (the 
last two mean the same) to control the direction of the slur, and a 
suffix \verb"+#" or \verb"-#" to raise or lower the start of the slur by 
\verb"#" internotes.  The slur end character may also have an adjustment 
suffix.  Remember to fine-tune both end points when you wish to move the 
whole slur up or down!  

It is also possible to fine-tune the horizontal position. The most common case 
occurs when two notes on the same pitch are linked by a\NEW{0.51} tie.  In 
that case \verb"{"\ldots\verb"}" give a neater result than \verb"("\ldots\verb")".  
See the \PMX\ user's manual for details on other horizontal adjustments. 

In the case of a slur continuation you should code the height adjustment 
\emph{between} the two parentheses, e.g.~\ttxem{)-3(}.  You must not have two 
adjustments. 

Fine-tuning beams is all done on the beam start character.  It may have
the suffixes \mark upper or \mark lower for direction, and up to 
three \verb"+#" or \verb"-#" suffixes.  The first raises or lowers the 
beam by so many internotes, the second makes the beam more or less 
steep, and the third also raises or lowers the beam, but this time in 
units of beam thickness.

\subsection{Instrument names} \NEW{0.40}  \label{stavename}

Some scores have indications like \textbf{Violin} to the left of the
first system.  The easiest way to do this is to enable the \ttxem{instrumentNames} feature, 
which uses the line labels as names, but you may not like the result.

To do it yourself, use the \ttxem{Name:} command in the preamble,
e.g. 
\verb"Name: Violin Piano".
The names can be any valid \TeX\ expressions that have no spaces, such as
\verb"{\it{French~Horn}}".
Remember, it's one name per instrument, not one name per stave.  If you
have too few names, the remaining instruments will not be named.
You can
also use a single hard space (\verb"~") when some instrument in the middle 
should not have a name.

You will probably also need the \ttxem{Indent:} command to specify the
indentation required to provide space for the names.  
E.g.\ \verb"Indent: 0.12" says the indentation should be 12\% of the music
width.  


\section{Shortcuts}

This section introduces \ixem{shortcuts} for things that are perfectly
possible in other ways, but a little clumsy.


\subsection{Chords}  \label{chords}

An isolated \ixem{chord} in the middle of a melodic line is best treated
by the \PMX\ construction of chordal notes with the \ttxem{z} prefix, e.g.
\verb"c ze zg zc" 
for a C major chord.  Sometimes a whole string of successive chords appears,
as in the introduction to Schubert's song \textit{Der Tod und das M\"adchen.}
You can see that the coding for this can become quite cumbersome.
Therefore \MTx\ allows you to put the chordal notes on a second line,
as shown below.  

\hskip -18mm
\begin{mus}
\input dertod.tex
\end{mus}
\vskip 12pt
\verbatiminput{dertod.mtx}
\begin{itemize}
  \item  There is a basic melodic line, with a separate line for the chordal
notes, labelled like a lyrics line, but with \ttxem{C} instead of \verb'L'.  
\index{line!melodic}
  \item  For each chord there is one word on the \indexed{chord line}.  
\index{line!chord} \index{chord} If the
chord contains more than one \indexed{chordal note}, \index{note!chordal} 
the notes follow with no spaces
in between.  The notation is the usual \PMX\ notation, with two changes: 
fla\mark t and notehead \mark left.  These changes are used only on chord 
lines, and are unavoidable because \ttxem{e} and \ttxem{f} are needed for 
note names.   
  \item  The note chosen as melodic note \index{note!melodic}
on the main music line must not
be a shifted note (i.e. one with displaced notehead): 
all shifted notes must be on the chord line.  
  \item  The stem direction of the chord is what that of the melodic
note would have been in the absence of chordal notes.
  \item  Pitch on the melodic line (i.e.~the choice of the closest note 
with the given name) is not affected by the chordal notes. Each chord has 
its own local frame of reference, starting anew from its melodic note. This 
differs from the \PMX\ \texttt{z\dots} notation, where the pitch of each 
note is determined by the previous note, whether chordal or not.
\index{pitch!of chordal note} 
  \item  Sometimes in the middle of a chordal passage there might be an 
isolated melodic note that does not have any chordal notes. To indicate this, 
the chord line must contain a \ixem{spacer}, which is a one-character word 
containing just a tilde (\ttxem{\snake}). 
  \item  Sometimes you only need a few isolated chords.  A one-character
word consisting of a bar symbol
\ttxem{\|} on a chord line indicates that no more chords appear in the
current bar even though one or more melodic notes are still left.  
In that case you do not need a \ttxem{\snake} for the `missing' chords.
Don't use bar symbols on a chord line just to separate bars when there
are no missing chords.

Two or more consecutive such words indicate one or more bars with no chords.
If the very first word on a chord line is a bar symbol, the first bar has no 
chords.  
  \item  You can get an \ixem{arpeggio} sign (wavy line) in front of the whole chord 
including the melodic note by starting the chord word with a question mark, 
e.g. \verb'?ad' instead of \verb'ad' in the first chord above would have put 
an arpeggio sign in front of all three notes.  For more complicated
arpeggio constructions, you need to put \ttxem{?} signs on the music lines 
themselves: consult the \PMX~manual.         

\item You can tie notes in chords.  \NEW{0.60}  The notation is more compact
than ties in the music line itself: put a \verb'{' before each note that should
be tied, no blanks, but don't put anything to close the tie.  It is an error
if you open a tie and there is no note at that pitch in the next chord.
All the notes in that chord that close ties should appear before
all the notes that open ties, e.g.\ \verb"{c c{e" is OK but
\verb"{c {ec" is not.


\hskip -18mm
\begin{mus}
\input chord.tex
\end{mus}
\vskip 12pt
\verbatiminput{chord.mtx}


\end{itemize}

\subsection{Expression marks and other annotations}

Annotations and interpretation marks ({\ppff p}, {\ppff f}, \textit{rit.}, 
\textit{cresc.} and so on) are inserted using lines like lyrics lines, but 
with \ttxem{U} (for \mark Uptext) instead of \verb'L'.   
Note, though, that uptext lines are synchronized with rests as well as
notes, whereas lyrics are synchronized with notes only.

The normal position 
for an \ixem{uptext} line is \emph{above} the music line to which it applies: 
if it appears anywhere else, the \ixem{label} must include the voice name or 
number. I'll speak of an \emph{uptext voice} \index{uptext!voice} to refer to 
the totality of uptext lines (no more than one per paragraph) 
associated with a particular voice. 
 \begin{itemize}
 \item Spacers \ttxem{\snake} and bar symbols \ttxem{\|} work for uptext in 
exactly the same way as for chords --- see Section \ref{chords}.  
\index{spacer} 
 \item Vertical adjustment signs starting with \ixem{\atsign}
like {\verb"@^"} \verb"@v" \verb"@=4" 
\verb"@+4" \verb"@-4" may appear 
in uptext lines, and have the same effect on the position of the uptext as in 
the fine-tuning of lyrics --- see Section \ref{fine-tune-lyrics}.  The only 
difference is that these signs appear in the uptext line itself, whereas the 
lyrics adjustments appear in the corresponding music line. A line starting 
\verb"U: @v " is actually a downtext line!  Each uptext voice retains its own 
adjustments which remain in effect even after the paragraph in which they 
appear.                                     

 \item Uptext lines may also have horizontal adjustment signs, namely 
\ixem{\atsign\less} and \ixem{\atsign\more}.  There are three possible 
positions for aligning uptext to a note: left, right and centre.  The 
default position is to align to the right, but the horizontal adjustment 
shifts the position in the indicated direction, e.g. one \verb"@<" causes 
centred uptext and another \verb"@<" causes uptext extending to the left of the 
note.  Yet a third \verb"@<" will be ignored.  Here, too, each uptext 
voice retains its own adjustments which remain in effect even after the 
paragraph in which they appear.                                

  \item Uptext lines are useful for indicating \ixem{guitar chords}.  
To make this
easier, the sharp character \ttxem{\#} may be used on an uptext line as a 
normal text character (usually in \TeX\ you need \verb'\#' to get it)
and the \ttxem{\%} character is used to indicate a 
\indexed{\mtxFlat}. \index{\Flat@\mtxFlat} 
  \item The preprocessor tries to guess whether the word is a dynamic 
indication like {\ppff mp}, {\ppff sf}, {\ppff rfz} etc.\ and will use the 
MusiX\TeX\ \keyindex{ppff} font for it.  The current algorithm is highly 
unsophisticated: if all the letters in a word come from the list 
\verb'fmprsz' it is diagnosed as a dynamic indication.
  \item A more permanent \indexed{font} \index{uptext!font} 
change is indicated by a word like \verb"!bf" or  \verb"!it" (no
backslash --- the \texttt{prepmx} program will put it in).  
Every word of that uptext voice (except \verb"\ppff" words) will be set in the 
indicated font.  Each uptext voice retains its own font which remains in 
effect even after the paragraph in which it appears. 
  \item  You can indicate \ixem{crescendo} and
\ixem{decrescendo} signs in uptext by two methods:
 \begin{enumerate} 
  \item Put \verb'<' or \verb'>'
where the sign starts, and \verb'<.' or \verb'>.' where it ends.
This feature gives unpredictable results when you try to use it
in more than one voice at the same time.  
  \item  
Put e.g.~\verb"<18" or \verb">7" where the sign starts.   
\NEW{0.42}  The number gives the length of the crescendo in elementary 
skip units or
``elemskips''.\footnote{It is quite technical to define precisely how
long an \ixem{elemskip} is.  The important thing about them is that they
stretch or shrink with spacing of the notes, so that if say a half-note
is followed by two elemskips in one place, it will be followed by two
elemskips everywhere.}
 \end{enumerate}
  
\end{itemize} 

\subsection{Lyrics paragraphs}

You may prefer to have all the lyrics for a particular voice together
in one paragraph.  To do this, the first line of the paragraph consists
of a name for the group of lyrics in braces, e.g.~\verb'{verse1}'.

When you later wish to use these lyrics, you put a list of names on a lyrics
line where you would normally have put the lyrics, e.g. 
\verb'L: {verse1,verse2}' replaces:
\begin{verbatim}
L: Lyr-ics for the first verse
L: Lyr-ics for the second verse
\end{verbatim}
You do not repeat this instruction in the next paragraph, but if the voice 
concerned no longer has lyrics attached to it, you should indicate that by a 
blank lyrics line, i.e.~\verb'L:' by itself. 

A particular lyrics paragraph name should not be used in more than one 
place.  If two voices have exactly the same lyrics, you need only one lyrics 
paragraph, but more than one name.  E.g.~\verb'{soprano}={bass}' makes two 
identical sets of lyrics, one to be used by \verb'L: {soprano}' and the 
other by \verb'L: {bass}'. 

One useful property of lyrics paragraphs is to allow you to
switch lyrics in the middle of a line instead of between music paragraphs.
\NEW{0.40}
This is only allowed if the voice in question already possesses lyrics:
it cannot be used to replace the \texttt{L:} line.  E.g.  
 \verb"a b {chorus} c d"  
means that starting at the note \texttt{c} lyrics will be taken
from the lyrics paragraph labelled \verb"{chorus}", and 
 \verb"a b {} c d" 
means that lyrics are switched off at that point.

\subsection{Long/short note combinations} \label{longshort}

Passages containing dotted notes \index{notes!dotted}
require duration changes for every note:

\verb"c8d g1 c8d g1 c8d g1 c8d g1 c4"  \\
There is a shorthand notation for this, namely:

\verb"c8.g c.d c.g c.d c" \\
The first note in a dotted group may have an explicit duration, which then 
becomes the default duration, but the second must not.  There is a similar
shortcut\NEW{0.51} \verb"c..d" for double-dotted notes.

When the dotted note appears not in a group but on its own, as in triple and 
compound time (3/4, 12/8 etc.), you must use a \ttxem{d} to indicate the 
dot, not a period. 

Similarly, in compound meter passages containing long and short notes
require frequent duration changes:
\verb"6/8 c8 g1 c8 d1 c8 g1 c8 d1 c8d"  
The shorthand notation for this reads:
\verb"6/8 c8,g c,d c,g c,d cd" 

\subsection{Barless music}   \NEW{0.40}

Many old hymn tunes do not fit into the modern pattern of regular bars.
You could get this effect by carefully counting the length of each music
line and issuing your own blind meter \index{blind!meter~change}
change instructions.

Instead, specify in the preamble that you have zero beats per bar.  
E.g.~\verb"Meter: 0/4" means that each paragraph of music
should be treated as a single bar, and that the basic counting unit is
a quarter-note.  You need not issue any other meter change instructions.
\MTx\ will check that each of the lines in the paragraph have the same total 
duration, which must a multiple of the specified counting unit.

\subsection{Sticky ornaments and suffixes}

You may need to mark a whole run of notes as staccato.  To do so,
put \verb'o.:' instead of \verb'o.' after the first staccato note and
\verb'o:' after the last one.  This method also works with tenuto
and all the other \ixem{ornaments} in \ref{ornaments}.  
The stickyness of ornaments lasts only till the end of the bar.

On notes and rests there are many possible suffixes, some of which you have 
already encountered and some of which are given in Appendix \ref{pmx}.  There 
are situations where you might wish to have several consecutive notes or rests 
with the same attribute.  The method is similar: put a colon (\texttt{:}) 
after the letter involved on the first note of such a sequence,  leave out the 
letter on all the notes except the last,\NEW{0.50} on which you again put the 
letter.  For example, in \verb'12/8' meter you might have a passage moving at 
four beats to the bar, normally coded \verb"c4d cd ed ed gd gd c2d", which 
becomes \verb"c4d: c e e g g c2d" when you use this shortcut.  The stickyness 
of note and rest suffixes lasts until cancelled. 

Each voice is treated on its own, and notes and rests are considered 
independently, so if you make the \verb'd' sticky on a note it will not affect 
rests.  My favourite application of this feature occurs in homophonic music 
with two voices per stave: I prefer to have only one rest per stave rather two 
rests, one on top of the other, and so I make all the rests in one of the 
voices blank by marking the first rest of that voice. 

\subsection{Multi-bar rests}   \label{rests}

\NEW{0.40}It may happen that all the instruments in your score
simultaneously have a rest of two or more bars.  In that case a succession
of empty bars may be difficult to count, and the conventional notation
is to put all the rests in a single bar, with the total number of
bars printed above them.  The word for a \mark multi-bar rest is e.g.\
\texttt{rm8} for a rest of eight bars.  You code this for one voice only,
and there may be no other notes or rests on that line, with one 
exception:\NEW{0.63} at the start of the piece, there may be a pickup 
consisting of rests.  The same rest will be printed on all staves.

Thanks to recent improvements to MusiXTeX and PMX \NEW{0.62} it is no
longer necessary to tune the appearance of the rest e.g.\ \texttt{rm19+18}.
Such adjustments are now ignored.

\subsection{Skipping and including portions of a score}   \label{multiscore} 

To read in another file at the start of a paragraph, \NEW{0.55}
use the \ttxem"Include:" directive, e.g.\ 

   \verb"Include: mylayout.mti"

The effect is exactly the same as if those lines had been part of the original
input file.  The file thus included may also contain "Include:"
directives; there is no restriction on the number of levels.  You may
re-include a file that was included before, but you may not include any
file that has already been included but has not yet been fully read. 

You may have various reasons for wanting \MTx\ to omit one or more lines of 
your score.  There are several ways to do so, of which the simplest is the 
comment symbol \verb'%' that you have met before, which skips that one line.  

A line starting with \ttxem{SUSPEND} all in capitals, at the start of a
paragraph, tells \MTx\ to discard all following paragraphs until a line 
starting with \ttxem{RESUME} all in capitals is found at the start of a
paragraph.  The material in between must still be organized into paragraphs
that are not too large (see Appendix \ref{limits}) but need not in any other
way conform to \MTx\ input rules.

A line starting with \ttxem{Only:} defines a subset of line numbers, 
e.g.~\verb"Only: 1,3-7,9" defines the set \{1,3,4,5,6,7,9\}. \NEW{0.43} Only 
the corresponding lines from all non-lyrics paragraphs after the paragraph 
containing the \texttt{Only} are processed until another \texttt{Only} is 
found.  Any paragraph containing an \texttt{Only} is always fully taken into 
account: it is not subjected to the masking action of any \texttt{Only}. 
\emph{WARNING: this feature is deprecated and may behave differently in 
or even be omitted from future versions.}

You can also conditionally ignore portions of the score depending on a 
compiler variable.  \NEW{0.42} The compiler options \texttt{0} to \texttt{9} 
identify ten special cases of a score.  Together with the basic unnumbered 
version of the score, you can therefore have up to eleven versions. A line 
starting with \ttxem{Case:} at the start of a paragraph gives a list of those 
cases that include the paragraph in question,  e.g. \verb"Case: 137" 
identifies a paragraph that is only included when one of the options 
\texttt{1}, \texttt{3} or \texttt{7} was selected, either as a command option 
or on and \texttt{Options:} line.  

All paragraphs headed by \texttt{Case:} occurring \emph{before} the first 
music paragraph are treated as extensions of the preamble.  The very first 
music paragraph may therefore not start with \texttt{Case:}. 

For example, the score \texttt{cervus.mtx} of Palestrina's four-part
setting of Psalm 42 (see the \texttt{source} directory in the \MTx\
distribution) is set up to give by default a score for the conductor with all 
voices in 16-point type.   When one of the \texttt{1}, \texttt{2}, \texttt{3} 
or \texttt{4} options is specified, you get a score with one voice in 20-point 
type and the others in 13-point.  When the \texttt{0} option is given, 
20-point is used throughout and the score is spread over three pages. 

%A combination of \texttt{Case} and \texttt{Only} allows you to make parts from 
%a score in a flexible way, e.g.~only the chorus parts, or both flutes 
%together, etc.  The \texttt{Case} command can never be masked out by a 
%previous \texttt{Only.} 

\subsection{Macros}  \NEW{0.60}

\MTx\ offers limited support for the \PMX\ macro feature, which is 
a shorthand notation for pieces of text that appear often in your input.
In \PMX, you define macro number $i$ by \texttt{MS}$i$ and end it by \texttt{M},
each a separate word, where $i$ is a number from 1 to 20.  
Everything in between (which may not contain
any word starting with \texttt{M}) is not acted on, but only stored, 
but when you later ``play'' the macro by the single word \texttt{MP}$i,$ 
the effect is the same as if you had typed the text you defined earlier.
In other words, a \PMX\ macro works as a purely literal text insertion.
You can also start a macro definition by \texttt{MR}$i:$ this has the effect
of immediately playing the macro, not just storing it.

The default behaviour in \MTx\ is to pass along such \texttt{M}-words
without looking at them, which in expert hands can be quite effective,
but for the rest of us is simply a disaster.
The problem is that in that case \MTx\ does not know that notes 
are being inserted, let alone what their duration is.  It is in the
position of a musician who has lost count.

\MTx\ offers two solutions to this problem, either of
which you can \texttt{Enable} in the preamble.  In both cases, macros 
may only appear on music lines.
\begin{description}
  \ttxi{expandMacro}  All macros are fully expanded at the \MTx\ level.
The \PMX\ file will not contain any macros.  If you use this feature,
you can have macros numbered from 1 to 99, and macro definitions
may contain plays of other macros.  Error messages apply to the expanded
text and may be difficult to understand.
  \ttxi{countMacro}  \texttt{M}-words are still passed along,
but when a macro is defined, \MTx\ determines its duration
and counts correctly when it is played.  
\end{description}

If you have enabled \texttt{countMacro}, there is one unavoidable
restriction:  a macro definition or play may not spill over into
the next bar.   Hence the total duration of a macro may not be more 
than what remains of the current bar.  

A word of caution: because you cannot see the macro 
definition when you play it, it is easy to lose track of duration and octave.  
It is therefore just sound common sense
to set duration and octave at the first note in the macro definition, 
and at the first note after the macro play, to avoid mistakes.

\hskip -18mm
\begin{mus}
\input macro.tex
\end{mus}
\vskip 12pt
\verbatiminput{macro.mtx}

If you used \texttt{expandMacro} instead, the first music line
could have read \\
\verb"     MS1 c8=+ za zf zc M MR2 [u MP1 MP1 MP1 MP1 ] M MP2" \\
in which case the first line of the second bar would only be \verb"MP2 MP2".
This is shorter for you to code, and in this case it works.
It is not always feasible to use macros within macros: 
\texttt{expandMacro} works
by actually inserting the strings into \MTx\ input lines, which
may not be longer than 255 characters.  Too many macro expansions,
and you hit your head against the ceiling.

\section{Debugging aids} \NEW{0.61} \label{debugging-aids}

The very compactness of \PMX\ music notation works against you
when debugging. One music paragraph looks very much like another.
Notes inherit pitch and duration from context, and when there is 
a mistake, it is not easy to see where in a long music line that 
context comes from. 

Octave mistakes have a way of accumulating, but only show up when 
you see a typeset score full of leger lines way above or below the 
stave.

Left to itself, \MTx\ can and does check that all music lines end 
at a bar ending, and that lines from the same paragraph have the 
same length. But it cannot tell that which of two lines is wrong, 
only that they are different.

Many programmers use comment lines \verb`% -- Bar 40 --` to help 
them keep track of where they are in a score. This practice has
now been formalized as a debugging aid.

Certain comments can be recognized by \MTx\ as assertions, allowing
additional correctness checks to be made. Apart from the comment
sign, they look like preamble commands, but are normally placed in
the music paragraph to which they apply.

\begin{tabular}{ll}

\verb"% Range: S=4d-5d, A=3b-4g" & Requests range checking for the specified voices. \\
\verb"% Bar: 30-31" & If only one bar, give just one number.

\end{tabular}

The format used here for \ttxem{Range} checking puts the octave
 before the note, e.g. \verb`4f`, to avoid confusion with \verb`f4`
in which the digit indicates duration. The error messages
use the same notation.

Either of these comments may also appear in a preamble paragraph,
in which case they apply to the entire score. 
% {-- Maybe later --} The first number in such a global \verb`Bar` 
% is used to initialize the printed bar count.

\subsection{Error messages}

Most error messages will give a line number and say approximately
where the error was found. In that case, the original line is printed
with a marker at that point. Also printed is what has happened to that
line in the meantime, mostly explicit duration indications on every
note.

If there is no line number (this mostly happens in the preamble)
the message in most cases deals with something that you should have
supplied.

Sometimes the actual error may be on another line, e.g.\ when it is 
found that music lines have a different duration, the first line 
processed may be the one that is wrong, but the discrepancy is only 
found later.

Error messages generated by assertions can be a lot more informative
than others, and you are urged to exploit these. To find out what life
would have been like without them, you can always issue 
`Disable: checkAssertions` in the preamble.

\section{Acknowledgments} 

% In DPL-DOS/huis.tgz

I still have the 
\texttt{.tex} and \texttt{.dvi} files of my first attempt (in October 1992)
at setting music (Bach, no less) with the \mutex\ package of Andrea Steinbach 
and Angelika Schofer.  The first phrase goes: 
\begin{verbatim} 
\4\,\F\~\B\.\c\|\2\A\.\|\4\B\,\E\E\| \2\group{\\\E\\\d}{\\0\\{-1}}\lslur12\go\| 
\end{verbatim} 
In \MTx\ that would be                        

\verb"f bd c8 | a2d | b4 e- e | ( e2 d4 )" \\
A tantalizing glimpse of a preprocessor appeared in the \mutex\ 
documentation, but the software for it was never released.  

None of this would have been possible without the late Daniel Taupin, 
who was the first to emphasize that printed music has a fundamentally 
two-dimensional layout, and whose MusiX\TeX\ package is the engine that 
actually performs the typesetting.

I made a previous attempt to implement something like \MTx\ as a direct 
preprocessor to Music\TeX\ (Daniel's first package).  My lack of 
expertise caused that project to die.  The appearance in January 1997 of 
\PMX\ 1.1 inspired me to resurrect the idea --- thanks to Don Simons. 
Don has also made some comments which helped me to improve the \MTx\ 
input language.  Some \MTx\ features that are implemented by using \TeX\ directly, make use of MusiXTeX code written by Don.

Since version 0.21, \MTx\ uses Rainer Dunker's \ttxem{musixlyr} package.  
This gives much neater horizontal spacing of lyrics than the manual system 
used in previous versions, and virtually eliminates the need for 
horizontal tuning. 

Chris Walshaw's \ABC\ provided the repeat notation.  

The layout of \MTx\ bears some resemblance to a language developed by 
Miguel Filgueiras, published in 1998 in \textit{Software Practice and
Experience}, although I did not consciously borrow his ideas. I have
been unable to find an implementation on the Internet.

I had some enlightening e-mail correspondence with the developers of 
MPP, Jan Nieuwenhuizen and Han-Wen Nienhuys. 
This package (no longer maintained, unfortunately) was the first 
music package which made me believe that one could write good-looking 
scores in a reasonable amount of time. 

Eric Petersen, Reenen Laurie, Kestell Laurie and Joel Hunsberger found
several bugs in earlier versions of \MTx.  Christian Mondrup did this for 
\MTx\ 0.50 and later.  

The subscribers to the discussion list \mailingList\ --- 
too many to name --- found many more and contributed to the development by 
requesting new features.  Details of these contribution are given in the
\ttxem{Corrections} file distributed with the \texttt{prepmx} code.

The success of public domain music publishing owes an incalculable debt
to the late Werner Icking.  He maintained an online archive for music
software and sheet music, set
standards for music typesetting, tested software packages, gave 
genuinely expert advice to would-be experts, and encouraged newbies
with patience and understanding.  When he died unexpectedly at a
comparatively young age, each of the small but globewide community of users
of MusiX\TeX\ lost a personal friend and mentor.  
% His music archive as it was at the time of his death can still 
% be accessed at \texttt{ftp://ftp.gmd.de/music} or 
% \texttt{http://www.gmd.de/Music}.

Werner's work is still being carried on: the software archive
and mailing list URLs are listed in Appendix A, while
the scores have been merged into the Petrucci Music Library (\scoreSite).
 
My wife, Trienke, had to suffer many effectively husbandless evenings
and weekends while I hammered the program and documentation into good 
enough shape to be able to offer it around.

\appendix
\setcounter{page}{1}
\renewcommand{\thepage}{A-\arabic{page}}

\section{Where to find help}  \label{help}

 \MTx\ is the tip of an iceberg.  Things can go wrong at many levels.
Fortunately, here are many ways to get information and help.
\begin{itemize}
  \item  Consult the Table of Contents and \emph{index} in search of
         a likely-looking topic.  
  \item  The annotated examples might be useful.
  \item  There is a file \texttt{FAQ} in the distribution that contains
         the sort of questions that new users often ask.
  \item  The packages on which \MTx\ relies all have their own reference
         manuals.  Look for the following files:
    \begin{description}
      \item{\PMX:~} \texttt{pmx270.pdf}, \texttt{ref270.pdf} 
           (these names will obviously be different
           if your \PMX\ is not Version 2.70); 
      \item{\musixlyr:~} \texttt{musixlyr.pdf};
      \item{MusiX\TeX:~} \texttt{musixdoc.dvi}. 
    \end{description}
  \item  The archive site at \begin{quote}\archiveSite \end{quote} 
  hosts not only the mailing list archive but also several tutorials 
  in various languages on MusiX\TeX\ and \PMX.
  \item  Join the \ixem{mailing list} by filling in the form
at \\
\texttt{http://tug.org/mailman/listinfo/tex-music}.
\end{itemize} 

\section{A short \PMX\ tutorial}  \label{pmx}

  This section describes the parts of \ibxem{PMX} that you are likely to need 
when coding scores in \MTx.  I have left out or simplified features 
that are not 
necessary or too advanced.  In most cases, you can still use them, as 
\MTx\ simply passes through anything that it does not recognize.  

  \PMX\ resembles English in that it is made up of \ixem{word}s, which are 
strings of non-blank characters separated by blanks.  Each word, though, 
has the character of an acronym, in that its letters each stand for 
something longer, and in fact Don Simons designed the notation so that 
you can actually say out loud what the acronym stands for.

  \textsl{In the following, the symbol \ttxem{\#} stands for some number.}

 \subsection{Words that contribute to the count}

  Each bar of music has a certain \ixem{duration}, which is is the total of the 
notes and rests in it.  The word for a note that contributes to the 
count starts with \texttt{a} to \texttt{g}, which indicates \ixem{pitch}; and 
the word for a \ixem{rest} starts with \ttxem{r}.  

  A note may have a number of \ixem{suffix}es, which may come in any order.  
The duration is indicated by a digit: from short to long, these are
6 (1/\mark64-th note), 3, 1, 8, 4, 2, 0, (whole note), 9 (double note, 
also known as `breve').   
Moving a 
note an \ixem{octave}\footnote{The \ttxem{=} suffix is not part of \PMX.
Instead, \PMX\ offers the ability to specify octaves by numbers. \emph{This
feature is not supported by \MTx.}}
 up or down is indicated by \ttxem{+} and \ttxem{-},
repeated if necessary.
The other suffixes are the following marked letters: \mark dotted,
\mark flat, \mark sharp, \mark natural, stem \mark upper, 
stem \mark lower, offset to the \mark right, offset to the 
l\mark eft, \mark apart (not attached to a beam).

You can fine-tune \index{dot!fine-tuning} dot position,\NEW{0.52} e.g.\
\verb"gd-2" puts the dot two internotes lower than it would normally go, 
and \verb"gd-0+1" puts it one notehead to the right.  

You can also fine-tune\NEW{0.52} accidental position in a similar way.  For
accidentals (but not for dots) you are allowed to write \verb"gs>1"
instead of \verb"gs-0+1".

  A rest may also have suffixes: duration and \mark dot as for notes,
\mark pause (duration is the whole bar), \mark blank (rest is 
counted but not printed).    
It can be moved up and down by \ttxem{+} and 
\ttxem{-} followed by a number, e.g. \texttt{r0-4} is a whole-note rest 
moved down four internotes.  The other rest suffixes mentioned
in Section \ref{rests} are not yet (version 1.3.8) part of \PMX, 
except \texttt{m}, which is allowed in a score for a single one-stave 
instrument.  \NEW{0.43}  Also the `blind' and adjustment suffixes on the pause 
\texttt{rp} are legal in \MTx, but not yet in \PMX.

 The duration of a note may be influenced in various ways by a previous
note: if unspecified, it is the same as the previous note; or the note 
may be part of a chord, a multiplet, or a grace note group.

 \subsection{Words excluded from the count} 

Except for the first note of a chord or multiplet, the following words 
for notes are excluded from the count, and should not have a duration 
suffix. 

\paragraph*{Chords:} Each note in a chord except the first has the 
prefix \ttxem{z}.  It is excluded from the count, and suffixes 
\ttxem{a} \ttxem{d} \ttxem{l} \ttxem{u} may only appear on the first, 
non-\texttt{z} note. 
The ``melodic note'' of Section \ref{chords} becomes the first note
of the chord when the \MTx\ code is translated to \PMX.

\paragraph*{Multiplets:} A normal note may have an extra suffix, after 
all the others, of the form \verb"x#" \index{\texttt{x}} 
or \verb"x#n", where \ttxem{\#} 
stands for a number.  This means that the note is the first of a 
multiplet (or $x$-tuplet) with \verb"#" equal notes in the time of one.  
Only the duration coded on this first note is included in the count. The 
appearance of the first note will not be the normal one for its 
specified duration: it will look like all the others.  
E.g.~\verb"g4x3 a b" defines a \ixem{triplet} of total duration a quarter-note 
looking like three eighth-notes. The \ttxem{n} means that the number 
\verb"#" is not to be printed. 

The other \verb"#"$-1$ notes in the multiplet are excluded from the count.
They need not all be of the same length: double-length notes are allowed. 
You can double the length using either \verb"D" or \verb"F". Either of 
these in a multiplet note makes that note count as two notes and 
changes the way it is printed. Consult the PMX documentation for 
the difference between \verb"D" and \verb"F" (or experiment and see 
for yourself).

\paragraph*{Grace notes:} A normal note may have a prefix group starting
with \verb"G#" or \ttxem{G}.  This indicates that the note is the first 
of a grace note \index{note!grace}
group with \verb"#" notes, to be set in a tiny font.   
All the notes in the group, even the first, are excluded from the 
count. 

\subsection{Words for other things than notes}  \label{ornaments}

Other things than notes go into a music score: ornaments, 
clefs,                                          
expression markings, changes in key and time signature, etc.  
\PMX\ contains support for many of these.  Here I mention only a small 
selection: see the \PMX\ manual for items you need but which are not 
described here.  A word for each such feature has its characteristic 
first letter followed by a selection of \ixem{suffix}es that qualify it.

\begin{description}
 \item{Ornament:}  An \ixem{ornament} is set off-stave in line with its note, 
and its word, starting with \ttxem{o}, comes directly after that of its 
note.   The more commonly needed suffixes are           
\texttt{u} (dot for 
pizzicato), \texttt{p} (\mark prime for sharp pizzicato), 
\mark fermata above, \textbf{fd} (\mark fermata \mark down). 
The suffixes \texttt{.} (staccato) and
\texttt{-} (tenuto) differ from the others by being set close to the
note, not off-stave.
There are several more in \PMX\ and many others in MusiX\TeX. 
 \item{Clef change:}  You get a small \ixem{clef} at the point where 
the clef change occurs and a big one at the start of the next line.
The clef change word begins with \ttxem{C}.  The suffix \verb"#" places 
middle C on line \verb"#" of the stave, where \ttxem{1} is the bottom 
line and \ttxem{5} the top.  An appropriate clef is selected 
automatically, e.g. \ttxem{C0} is the G-clef (treble) and \ttxem{C6} is 
the F-clef (bass). 
 \item{Voltas:}  \index{volta} These are the labels to mark sections of the score
that are not played at every repeat.  You put \ttxem{V}\textbf{1} to indicate
that a bracket containing the number 1 should appear above the bar
in question.  Since \PMX\ wants all such indications in the bottom
voice only, they are deleted by the \MTx\ preprocessor if found
elsewhere.   See Appendix \ref{voltas}.
 \item{Key change:} Put \verb'K+0-2' in a music line where a \ixem{key} change
to two flats should occur.  As with voltas, this indication is deleted
if not in the bottom voice.
\end{description}

\subsection{Useful things to put on \ttxem{\%\%} lines}
\label{usefulPMX}

You have three ways of passing information directly to PMX.

\begin{enumerate}
   \item The \ttxem{PMX} preamble command.
   \item A line starting with \ttxem{\%\%}. The rest of the line is
treated as \PMX.
   \item Inside music lines. Anything not recognized is passed through.
\end{enumerate}

Most of the following commands should appear in the first music paragraph
or on a \ttxem{PMX} preamble command line.
Some of them are actually raw \ixem{MusiX\TeX} ---
consult the MusiX\TeX\ manual for other interesting commands.
\verb"%%" lines in the preamble are treated a little differently -- see 
Appendix \ref{expert}.
\begin{description}
 \item{Line, page and movement breaks:} 
Put \ttxem{\%\%L}\texttt{6} above a paragraph
to make the 6th system start there, and \verb'%%L6P2'  to put that
paragraph at the top of page 2.  You can't ask for a \ixem{page break}
without a \ixem{line break}.  Use this feature only when necessary.  
Put \verb'L10M+10i0.1' to make a new movement start at the 6th system,
with 10 internotes of extra space between movements and an indentation
of $0.1=10\%$ of the width.
 \item{\verb"h260m"} Height is 260 millimetres.
 \item{\verb"w8i"} Width is 8 inches. Note that \PMX's height and width
have one-letter units, not two-letter like \TeX\ itself and \MTx.
 \item{\verb"\\vsize 270mm\"} Height given to MusiX\TeX\ is 270 millimetres. 
 \item{\verb"Ar"}  Use relative \ixem{accidentals}.  This requires a different 
  way of coding flats and sharps ---think of \verb's' as meaning 
  `sharpened' instead of `sharp'.  E.g.~if the key signature has one or 
  more flats, then \verb'bs' means a B natural, \verb'bn' a B flat, and 
  \verb'bf' a B double flat.   If you need to \ixem{transpose} music often, 
  it is a good idea to acquire the habit of using relative accidentals 
  always.  If you don't, only pieces in C major or A minor can be 
  transposed without trouble. 
 \item{\verb"As"}  Always use small \ixem{accidentals}.  Normally \PMX\
uses big accidentals and only switches to smaller ones if there is a
reason to do so.  You can also force all big accidentals by \verb"Ab."
 \item{\verb"Ar K+1-3"}  Use relative accidentals and transpose the 
  piece up one internote, to a key with three flats.  You can only 
  \ixem{transpose} correctly when using relative accidentals! 
 \item{\verb"\\stdbarrules\"}  This will cause bar lines to be 
  drawn solidly \index{bar lines!solid}
  from the top to the bottom of each system, maybe
  cutting through lyrics in the process. 
  \item{Midi commands}  \PMX\ can make MIDI files.  For example, if you put
\begin{verbatim}
PMX: Ii55:55t96b56:72v127:100
\end{verbatim}
in the preamble of \texttt`netsoos.mtx`, a MIDI file will be generated 
in which both instruments (Soprano/Alto and Tenor/Bass) are played on 
MIDI instrument number 54 (on my system this means `voices') at a tempo 
of 96 quarter-notes to a minute, with MIDI balances of 56 and 72 (centre 
is 64) and MIDI velocities of 127 and 100 respectively.  More details 
appear in the \PMX\ manual.  
\end{description}

One thing that you must only pass to PMX by the third method --- embedded
in a music line --- is a meter change, otherwise \MTx\ does not know about 
it and will continue to count bars by the old meter.

\section{How to get and use \MTx}

There are such excellent tutorials available at \archiveSite\ that 
this section is unnecessary. In every subsection, only a few random 
remarks are left. You can safely skip it all. Just visit the website.

\subsection{Installation and running} \label{Archive}

On a Debian system (which also includes Ubuntu) you can simply
install the \verb`m-tx` package with all its dependencies (which,
if you do not yet have \TeX, is staggeringly much).

If you need to compile from source, grab it from \repository\ and
look for a file whose name starts with \verb`README`. You will
need a Free Pascal compiler.
 
Once you have all the software, make an \MTx\ file with extension 
\dotxem{mtx} using your normal text editor.  It must be an \ixem{editor} that
respects the line boundaries and empty lines that you type in: in other 
words, something fairly primitive, not an upmarket word processor.

Thanks to Bob Tennent, all the intermediate steps that you used to
need are now unnecessary. There will be an executable file called
\verb`musixtex` on your system, a real Swiss army knife, so that 
simply invoking 
\begin{verbatim}
  musixtex -q jobname
\end{verbatim}
will take you all the way from \verb`jobname.mtx` to \verb`jobname.pdf`.
The \verb`-q` (for "quiet") suppresses the zillions of lines of screen
output which \verb`tex` normally provides for you edification.

You can do the steps manually. The program \verb`musixtex` writes a file 
\verb`musixtex.log` documenting everything it did. For example, there 
will be a line starting with `prepmx` for the step the converts
\verb`jobname.mtx` to \verb`jobname.pmx`. If you need only that, 
\begin{verbatim}
  musixtex -p jobname
\end{verbatim}
will do it, but you may want to exploit some of the many commandline 
options that \verb`prepmx` has. Run \verb`prepmx -h` to see them.

The \texttt{prepmx} program exits with \ixem{return code} 0 if no error 
was found, and return code $n$ if an error was found while processing 
line $n$ of the input, whereas the \texttt{musixtex} program returns
the number of input files that gave errors. There is more about
\verb`musixtex` in Appendix \ref{latex}.
 
\subsection{Bugs, restrictions and incompatibilities} \label{limits}

The status of bugs changes too quickly for this document.  Please 
consult the files supplied with the package, in particular 
\texttt{README.txt}, \texttt{Corrections} and \texttt{Bugs}.

In \MTx\current\ a paragraph may not be more than 100 lines long, 
an input line (including those in lyrics paragraphs) not more than 
255 characters, a lyrics line in a music paragraph not more than 
128 characters, and you may define a maximum of 12 extra style 
elements of your own, whether in the preamble or in the 
\ttxem{mtxstyle.txt} file.  It is possible to change these if you compile
from source: they are clearly recognizable in \texttt{globals.pas}.

\NEW{0.42} You can have up to 15 voices, using up to 15
staves.  For each two-voice stave, the number of staves you can have goes
down by 1. 

Other limitations are described in the \PMX\ documentation. 

\subsubsection{Compatibility}

\MTx\ 0.61 accepts all scores that were valid under \MTx\ 0.60.
Older scores may need tweaking.

\subsubsection{Unsupported features of Musix\TeX\ and \PMX}

Support or otherwise of Musix\TeX\ and \PMX\ features comes at three 
levels:
\begin{enumerate}
 \item  The most frequently used features are transparently 
incorporated into the basic \MTx\ language.
 \item  The default action of \MTx\ is to pass through unchanged 
anything it does not recognize.  Most \PMX\ and MusiX\TeX\ features 
still work in this case.  For example, you can use \verb"\PED\"\NEW{0.51}  
in front of a 
note to obtain a \ixem{pedal} annotation below the stave, and \verb"\DEP\" 
to get the big asterisk for pedal release.  This is an example of a ``Type 1
\TeX\ string'' \index{TeX string@{\TeX\ string}!Type 1} as 
described in the \PMX\ manual.  
 \item  When a new \PMX\ feature affects aspects like count
or pitch of which \MTx\ should be aware, it is likely to be
incompatible with the preceding release of \MTx, although I do try
to catch up later.
\end{enumerate}

Some pertinent aspects:
\begin{enumerate}
 \item \MTx\current\ does not recognize the macro features of \PMX.
You should therefore not use PMX macros for notes or anything else that 
affects the count, the duration, the current octave and other properties
that are inherited by a note from the next.  But there is no harm in
HIESA
using macros for things like extra space.
 \item \MTx\current\ is not aware of movement breaks and the possibility 
to change the number of voices.
 \end{enumerate}

\subsection{For \PMX- and MusiX\TeX-perts only}  \label{expert}

You can send commands directly to \ibxem{PMX}.  All lines starting with 
\ttxem{\%\%} in music paragraphs are collected, stripped of the leading 
\verb"%%" and passed otherwise uninterpreted to \PMX\ before anything 
else from that paragraph is translated.  \NEW{0.41} 

PMX has four mechanisms for incorporating raw \TeX. Apart from putting
them inside music lines as in \PMX, they are supported in \MTx\ as follows.

1. A Type 1 \TeX\ string appears on a music line, terminated 
by a backslash. It takes effect at the next note.

2. A Type 2 \TeX\ string appears in a \ttxem{TeX} command in the preamble.
The rest of the line will be taken to be \TeX\ and must not end in a
backslash. There may be several \ttxem{TeX} commands. They take effect
just before the real typesetting takes place, after all other definitions
have been processed, and can be used to override just about anything.

3. A Type 3 \TeX\ string appears on a \verb"%%" line in a paragraph, e.g.
\begin{verbatim}
%% \\\def\foo{bar}\
\end{verbatim}
It takes effect at the start of paragraph, irrespective of where in
the paragraph it appeared. Note the trailing backslash.

4. A Type 4 \TeX\ string appears on a \verb"%%" line in the preamble. 
\index{TeX string@{\TeX\ string}!Type 4}
It will eventually appear at the top of the \TeX\ file,
after \texttt{musixtex.tex} and \texttt{pmx.tex} have been read in.  
Such lines should \emph{not} end with \verb"\".
An example appears in Appendix \ref{dirty}.
As in \TeX, a line starting with only one \ttxem{\%} is treated as a 
\ixem{comment}: such lines do not appear in the \PMX\ file. 

If you ever need to pass through something involving stave or instrument 
numbers, remember that \PMX\ and MusiX\TeX\ number these from bottom to
top, not from top to bottom, and that the ``first voice'' in \PMX\ is the 
\emph{bottom stave} to \MTx.  

Apart from the conversion of lyrics and chord lines into \PMX\ commands 
(which is the main job of \MTx) the notes are modified in various ways.
\begin{itemize}
  \item Octave is inserted into the first note of each voice, depending 
on the \NEW{0.54} \texttt{Octave} command, or if none is supplied, 
on the clef.  
Absolute \ixem{octave} numbers are not recognized by \MTx\ and
may cause unexpected side effects.  You can get something like absolute 
octave numbers by combining \verb"=" with \verb"-" or \verb"-".  This
may cause an irritating but harmless error message about backward 
incompatibiliy at the PMX stage. 
  \item If a line is vocal, an \ttxem{a} is inserted into quavers and 
shorter notes when not under slurs, to protect them from being beamed. 
  \item Duration codes are inserted into all notes and rests before any 
serious processing is done.   
  \item  Long/short note groups are expanded into separate notes.
Although \PMX\ allows these shortcuts, lyrics
cannot be properly synchronized unless the groups are expanded. 
  \item  \PMX\ syntax allows great freedom in the order in which
different parts of a node are coded.  \MTx\ is not aware of
all the subtleties, but extracts only those parts of which it needs to
be aware, and reassembles the note afterwards.
    \item Labels in the range
    \texttt{I} to \texttt{T} are inserted into unlabelled slurs and ties.  \NEW{0.55}  
    You should therefore avoid those labels for slurs that you label yourself.
  \item  Chord lines are expanded into standard \PMX\ code and inserted
into the main line for each voice.
  \end{itemize} 

Other ways in which an \MTx\ score differs from a native \PMX\ score in 
more than layout are: a bar line is \emph{required} for a \ixem{pickup}; 
\ixem{repeat} bars 
are coded by the \ABC\ symbols instead of \ttxem{Rl} etc.; you don't 
need to insert a meter change for an incomplete \ixem{final bar}: 
\MTx\ does it.

All the ability of \PMX\ to pass through \TeX\ (including MusiX\TeX) 
commands is still there.   You might for example like to read the 
\ttxem{musixlyr} documentation for a large variety of ways to 
fine-tune horizontal lyrics placement, but I can promise that you hardly 
ever will need to do horizontal tuning except to align multi-verse lyrics as 
in Section \ref{fine-tune-lyrics}.


\pagebreak
\section{Annotated examples}
 \subsection{Voltas} \label{voltas}
 \hskip -12mm
\begin{mus}
 \input volta.tex
\end{mus}
\verbatiminput{volta.mtx}
The main rule is: put every \ttxem{V} command in the \emph{bottom} voice
at the start of a measure,
after the bar line (if any) but before the first note, and don't try
to use more than one at a time: the new volta automatically closes the
old one.  Volta signs in other voices are silently ignored.
When reading the \PMX\ manual, remember that \emph{your} last part will 
become the first part for \PMX. 

In the above example \texttt{V1} starts a volta box, 
but to get the first volta box to be closed at the end, you must later
say \texttt{Vb}.  Also, to get the text \texttt{2} into the ``second ending" 
box, you add the \texttt{2}
after the \texttt{Vb} to make \verb"Vb2".  Finally, to make the second 
box open ended, you must enter \texttt{Vx} at the point you want it to be 
done.  (If you forget to enter the \texttt{Vx} after your last volta box, you 
will get a strange unwanted volta box at the end of your piece.)  

This example also illustrates the interplay between \ttxem{Space}
and \ixem{\atsign} required for proper spacing of lyrics when there
is stuff above the staves.
\hfill --- \textsl{Contributed by Joel Hunsberger}

\subsection{Music size} \label{sizes}

\verbatiminput{title1.mtx}
\begin{center}
\begin{mus}
 \input title1.tex
\end{mus}
\end{center}

The above does not look quite right, for a complicated reason.
A piece as a whole has a basic music size, and then each stave can have its
own ``local'' size.  The local size affects everything on the stave itself,
but not the annotations, ornaments etc.  The range of legal basic sizes 
is quite small: \PMX\ allows only 16-point and 20-point.
In this example, the basic size is 20-point and the local size 29-point.

To get the perfectly matched annotations displayed on the title page of this
manual, the 
input looks like this:
\verbatiminput{title.mtx}
MusiX\TeX\ has four size commands relative the basic size (called 
\verb"\normalsize"). These commands affect all music fonts.  They are:

\hskip 15mm
\begin{tabular}{lrr}
\keyindex{smallmusicsize}  & 13pt  & 16pt \\
\keyindex{normalmusicsize} & 16pt  & 20pt \\
\keyindex{largemusicsize}  & 20pt  & 24pt \\
\keyindex{Largemusicsize}  & 24pt  & 29pt
\end{tabular}

There is no \verb"\tinymusicsize", although several of the music fonts are 
individually available in 11-point size.

\pagebreak \subsection{A psalm tune} 
\hskip -20mm \begin{mus} 
 \input psalm42.tex
\end{mus}
\vskip 12pt
\verbatiminput{psalm42.mtx}
\begin{itemize} 
  \item \verb"Meter: 0/2" indicates counting in half-notes, but no bar
lines.
  \item Line breaks in the \texttt{Title} are made by \verb"\\".
\end{itemize}

\pagebreak
\subsection{Beams, slurs and melismas}  \label{melisma}

%  Macros for music examples

\example{melisma1}{mtx}{60mm}{4mm}{90mm}{-5mm}{c}{5mm}

\example{melisma2}{mtb}{60mm}{4mm}{90mm}{-10mm}{b}{5mm}

\example{melisma3}{mtb}{60mm}{4mm}{90mm}{-10mm}{b}{5mm}

\example{melisma4}{mtb}{60mm}{4mm}{90mm}{-15mm}{b}{5mm}

\example{melisma5}{mtb}{60mm}{4mm}{90mm}{-10mm}{b}{5mm}

\example{melisma6}{mtb}{60mm}{4mm}{90mm}{-15mm}{b}{5mm}

\bigskip\bigskip

Some points to note: Example 1 uses a slur with default PMX beaming, 
Example 2 uses forced beaming to beam all notes, 
Example 3 does both.  Examples 4 and 5 violate the \MTx\ convention
that notes sung to a single syllable must be slurred or beamed together,
so we override this in either of two ways using \texttt{musixlyr}
commands.  Example 4 uses \verb"\beginmel" and \verb"\endmel"
to force melismas in a situation where \verb"[[" has suppressed them;
this method is good for long melismas
over several beamed components.  Example 5 suppresses lyrics where
the beaming would have put them.  
Example 6 uses \verb"\lyr" to force lyrics where the beaming
would have suppressed them, and shows the use of empty
syllables to synchronize lyrics and of broken slurs to indicate different
slurring in the two verses.
\hfill --- \textsl{Suggested by Stefan Haller}

\pagebreak
\subsection{Dirty Tricks} \label{dirty}  \NEW{0.41}

\verbatiminput{meter.mtx}
\begin{center}
\begin{mus}
 \input meter.tex
\end{mus}
\end{center}

These are bars 7--9 of the \emph{Credo} from \emph{Misa Criolla}
by Ariel Ram{\'\i}rez.  It is in the \emph{chacarera trunca} meter, which
mixes $\frac34$ and $\frac68$ time.  There is no \PMX\ construction for 
such \ixem{exotic meters}, so we need to be ingenious.  

We specify the meter as \verb"m3406"
which tells \PMX\ to use $\frac34$ meter but to print the C symbol for common
time.  Of course we do not actually want the C symbol, we want something
that looks like $\frac34(\frac68).$  Now all that \PMX\ knows about the C 
symbol is that it is called \verb"\meterC" in MusiX\TeX.  So we define
\verb"\chacarera" and assign it to
\verb"\meterC" in preamble \verb"%%" commands. These appear in the \TeX\
file after the command to read in \texttt{musixtex.tex} but before the 
commands that actually print something.   If later we need the original
\verb"\meterC" it can be restored by \verb"\let\meterC=\oldmeterC".

The excerpt illustrates some sophisticated \PMX\ features too.
Since the \verb">" ornament on the bottom stave 
goes above the stave by default, we
need to move it down explicitly.  The beamed eighths look better with
a horizontal beam, which is enforced by \verb"[h."  Finally, there is
a tie involving a melodic note with a note in a chord; to allow this, 
the chordal note must
come on a music line, not on a \texttt{C:} line.
\pagebreak

\subsection{Extra text after the piece} \label{extra}  \NEW{0.50}

\verbatiminput{borup.mtx}


When typesetting a vocal composition you may sometimes want to put only the
text of the initial stanza into your score and let the remaining part of the
lyrics be printed below the score. You might also want to add some notes or
comments.

Apparently this is not possible according to the set of commands available
for \MTx\ and \PMX. There is, however, a workaround to do things like
that. The trick is to look for a command \keyindex{Endpiece} or --- as in
this example --- \verb'\setrightrepeat\endpiece' near the bottom of the
MusiX\TeX\ file generated by the \PMX\ preprocessing. You may extend the
actions of \verb'\Endpiece' (or \keyindex{endpiece}) by saving the command
with another name (\verb'\endpiecesav') and redefine \verb'\Endpiece'
to first execute \verb'\endpiecesav' and then request the inclusion of
one or more files containg plain \TeX\ code. The text of the included
file(s) will be typeset on unutilized space on the last page or else on
a new page.

MusiX\TeX\ commands like these may --- as noted in Appendix \ref{usefulPMX}
--- be put directly into the mtx source file in \verb"%%"-lines at the
head of the first music paragraph.

In the current example two files have been included. \texttt{lyrics.tex}
contains the original Latin lyrics and an English translation. A \TeX\
table\footnote{See Michael Doob: A Gentle Introduction to \TeX, section
6.2. The book may be found as \texttt{gentle.tex} in the Documentation
subdirectory of the \TeX\ CTAN mirror archives.} consisting of a template
line followed by item lines for each lyrics line has been used to set
up the text in two columns - one for the lyrics and one in italics for
the translation. Notes on the song is included from \texttt{notes.tex}
and appended below the lyrics.
\hfill --- \textsl{Contributed by Christian Mondrup, following a hint by
Werner Icking}

\verbatiminput{notes.tex}
\pagebreak

\verbatiminput{lyrics.tex}

\hskip -20mm
\begin{mus}
 \input borup.tex
\end{mus}

\pagebreak

\section{\MTx\ and \LaTeX}  \NEW{0.54} \label{latex}

\textit{This section assumes that you have some knowledge of 
\LaTeX.}

The normal output from \PMX\ is a stand-alone plain \TeX\ file, which 
cannot without further ado succesfully be input into \LaTeX.  
The file \ttxem{mtxlatex.tex} allows you to prepare music scores using
\LaTeX\ rather than plain \TeX, which is particularly useful when you 
need the enhanced font handling features of \LaTeX, and to produce
books combining the outputs of several \PMX\ runs into a single
document, such as a collection of songs, or a mainly text document
 (like this one) with many small music excerpts.

\begin{quote} \emph{Order of inclusion of packages is important.
  \emph{\texttt{mtxlatex}}
    must be the first package included, before any font packages.}
\end{quote}

\subsection{Collections of complete pieces}

Suppose you need to make a document containing several complete
pieces, with
perhaps a title page, a foreword and an afterword, like a typical
published book of piano pieces or songs.  
\begin{enumerate}
  \item Write a \LaTeX\ file, say \texttt{halleluja.ltx}, 
looking something like this:
\verbatiminput{hallelujashort.ltx}
By the way, this code contains another dirty trick: vertical space
between systems is tweaked by embedding the bar number in a vertical box.
  \item Use the script \texttt{musixtex.lua} that, thanks to Bob Tennent,
forms part of modern \TeX\ distributions\footnote{You need at least Version 
0.15. If your distribution is not recent enough, download the latest version
from \texttt{http://icking-music-archive.org/software/musixtex/musixtex.lua}} 
to build everything in one go. In this case you need to say:
\begin{verbatim}
    musixtex kroonhom loofnou halleluja.ltx
\end{verbatim}
It is important to put the main file last, so that the \TeX\ files
are built before the main file is processed.
  \item If you make small changes in the \LaTeX\ part only, a single
\LaTeX\ pass is sufficient, unless the page numbering has changed.
You achieve this with the \texttt{-1} option of \texttt{musixtex.lua}.
\end{enumerate}
You can see the finished product in \texttt{halleluja.pdf}.
Some points to note: 
\begin{itemize}
  \item The file \texttt{mtxlatex.sty} is supplied with the \MTx\
documentation source. You may need to copy it to some other place
for \TeX\ to find it.
  \item The package \texttt{mathptmx} comes with standard distributions
and loads \texttt{Times} fonts, including fonts for mathematics.
You could use any suitable \LaTeXe\ font package here.  The \texttt{Times}
font is quite narrow and therefore useful when the lyrics are crowded. 
If you do use a font package, load it \emph{after} \texttt{mtxlatex}. 
  \item \verb"\pagestyle{headings}" puts page
numbers and running headings at the top of the page.
  \item To change fonts, you can use pure \LaTeXe\
\ixem{font change} commands, as above. 
Briefly, subject to what fonts you have installed,
you can independently change:
  \begin{description}
   \item[size]  \verb"\tiny",
      \verb"\scriptsize", \verb"\footnotesize", \verb"\small",
      \verb"\normalsize", \verb"\large", \verb"\Large", \verb"\LARGE",
      \verb"\huge", \verb"\Huge";
   \item[shape] \verb"\upshape", \verb"\itshape", \verb"\slshape", 
     \verb"\scshape"; 
    \item[family] \verb"\rmfamily", \verb"\sffamily", \verb"\ttfamily";
    \item[series] \verb"\mdseries", \verb"\bfseries",
  \end{description}
or corresponding \verb|\text..{...}| macros.
For a full description, see any good \LaTeXe\ manual.

Header
font commands (see Section~\ref{ChangingFonts}) are redefined in \verb|mtxlatex.sty| as follows:
\begin{verbatim}
  \renewcommand{\BIGtype}{\Huge\bfseries}
  \renewcommand{\BIgtype}{\huge\bfseries}
  \renewcommand{\Bigtype}{\LARGE\bfseries} 
  \renewcommand{\bigtype}{\Large\bfseries} 
\end{verbatim}
If \TeX-like commands such as \verb"\it", \verb"\bf"
etc.\  are used in a particular score, they can be redefined to work as in MusiX\TeX\ in
that environment as follows:  
\begin{verbatim}
  \renewcommand{\rm}{\upshape\mdseries}
  \renewcommand{\it}{\itshape\mdseries}
  \renewcommand{\bf}{\upshape\bfseries}
  \renewcommand{\bi}{\itshape\bfseries}
  \renewcommand{\sc}{\scshape\mdseries}
\end{verbatim}


  \item  The blank line after \verb"\pagebreak" is essential.
  \item  The environment \ttxem{Score} is used to include each piece.
It takes two arguments: the first will appear in the list of
contents and as a running page heading; the second is the name
of the \texttt{.tex} file.  As usual, the extension \texttt{.tex}
may be omitted.  There is also an environment \ttxem{score}
which is less convenient but more flexible: it has no arguments,
reads in nothing, puts nothing in the table of contents, and
does not change the running page heading.  Use it when you need
a special lyrics font, e.g.
\begin{verbatim}
\begin{score} \headingandcontents{Loof nou die Heer}
  \sffamily \input loofnou 
\end{score}
\end{verbatim}
\end{itemize}

\subsection{Collections of morsels}

The situation is a little different when the pieces are so short
that several of them fit on one page.  For these, use the
environment \ttxem{excerpts}, as in the following example:
\verbatiminput{kanons.ltx}
The rest of the procedure is the same as for collections of longer
pieces.
You can see the finished product in \texttt{kanons.pdf}.
Some points to note: 
\begin{itemize}
  \item The \texttt{excerpts} environment redefines the heading fonts
to more modest sizes.
  \item A page break should be made before quitting the environment.

  \item The pieces do not have bar numbers, but space should be reserved
for the numbers that show where the voices enter.  As above, this is done
by redefining the \keyindex{writebarno} command.
\end{itemize}

\subsection{Documents with small music excerpts}
   
This manual relies heavily on the \ttxem{mus} environment.  
For example, the 
musical emblem on the front page was set using the commands
\begin{verbatim}
\begin{center}  
  \framebox[5in]{\parbox{3.6in}{
    \begin{mus} \input title.tex \bigskip \end{mus}
  }}        
\end{center}
\end{verbatim}
Some points to note: 
\begin{itemize}
  \item  The excerpts vary in length and some experimentation is
required to get the dimensions and positioning just right. 
  \item  Putting the \texttt{mus} environment inside a \texttt{center}
environment only works when the music line is not longer than the text.
Otherwise, it is useful to use \verb"\hskip", as in the case of the
first example in the manual:
\begin{verbatim}
\hskip -18mm
\begin{mus}
\input mozart0.tex
\end{mus}
\end{verbatim}
For this technique to work properly, it is essential that the above four
lines form a paragraph of their own, i.e.\ they are preceded and
followed by blank lines.  
\end{itemize}

Appendix \ref{melisma} was produced using the command \keyindex{example}.
This is a rather complicated macro with eight parameters, which is
documented at the end of the file \ttxem{mtxlatex.sty}.
 
\section{Overriding predefined \TeX\ commands}  \NEW{0.54}

\textit{This section assumes that you are an experienced \TeX\
user. }

The logical structure of \TeX\ is such that most of the time, a command used
in a definition need not exist at the time that the definition is made,
as long as it is defined by the time that the definition is used.  This
behaviour is known to computer programmers as \emph{run-time binding}.

We have already met examples of how to exploit this feature in Sections
\ref{dirty} and \ref{extra}, where respectively \verb"\meterC" and
\verb"\Endpiece" were redefined. 
The macros of the previous section also work in that way, by locally
(i.e.\ inside the various environments) redefining commands that appear
in the \TeX\ file generated by \PMX.

The technique is an extremely powerful and flexible one, and in the
hands of an expert can achieve practically any desired result.  
Here we can only scratch the surface.  One point to note is that
good programming practice requires that you save the current meaning
of the command and restore it later, e.g.
\begin{verbatim}
  \let\commandsave\command\def\command{...}
  ...
  \let\command\commandsave
\end{verbatim}
In \LaTeX, if you redefine a command inside an environment, the saving and
restoring is automatic.

\subsection{\Large \texttt{mtx.tex}}  \label{mtxtex}

The \MTx\ preprocessor, as far as possible, issues commands starting
with \verb"\mtx" instead of direct \TeX\ commands.  The main purpose
for so doing is that the user can modify their effect by redefining
them in the source file.  These macros, together with a few others
that make life easier, are collected in the file \ttxem{mtx.tex}.

\subsection{Changing fonts}
\label{ChangingFonts}

The font used for lyrics is 
by default eleven-point roman.
It can be changed globally; for example, \verb"TeX: \twelverm" in the preamble will change the font to
twelve-point.  
The font families used by default for titles and other items in headers are respectively 
called \keyindex{BIgtype} and \keyindex{bigtype}.  
If you want larger or smaller fonts, you may use \verb|\BIGtype| or \verb|\Bigtype|
to prefix
the header text,
as in
\begin{verbatim}
  Title: \Bigtype Sanctus
\end{verbatim}
You may also use commands \verb|\rm|, \verb|\it|,
\verb|\bi|, and \verb|\sc| to get Roman, italic, bold-italic, or small-capital text
in header strings.
The macros \keyindex{mtxPalatino} and \keyindex{mtxTimes}, defined in
\texttt{mtx.tex}, replace 
Computer Modern in all the font definitions by Palatino or Times, respectively.

A command like \verb|\mtxelevensf| may be used in
a \verb|TeX:| header to get sans-serif lyrics.  
The macro \keyindex{mtxAllsf} sets \verb|\mtxelevensf| as the default
for lyrics and also redefines the \verb|\bigtype|,
\verb|\Bigtype|, \verb|\BIgtype| and \verb|\BIGtype| families
to use sans-serif fonts. 
Only \verb|\rm| and \verb|\it| styles are available in sans-serif header strings.
The macro \keyindex{mtxHelvetica} replaces the
Computer Modern Sans font definitions by Helvetica.

\pagebreak

\setcounter{page}{1}
\renewcommand{\thepage}{I-\arabic{page}}

\def\Flat{{\musixfont\char'062}}
\def\Sharp{{\musixfont\char'064}}    
\def\mtxSharp{\mbox{\raise1ex\hbox{\Sharp}}}
\def\mtxFlat{\mbox{\raise1ex\hbox{\Flat}}}  

If you can't find what you need here, also try the Table of Contents.
Other sources of help are listed in Appendix A. 

\printindex
\end{document}  

\endinput

so it is a good idea to use \texttt{musixlyr} commands 
for left-alignment (\keyindex{llyr}) and horizontal shift
(\keyindex{lyroffset}) on the corresponding music line, for example:
\begin{verbatim}
\llyr\lyroffset{-2}\ d | g g ( a8 b ) | g4 g ( b8 c ) | d4 d e | c2
L: 1. A-way in a man-ger, no crib for his bed,
L: 2. The stars in the bright sky looked down where He lay.
\end{verbatim}