% pmx134.tex   LaTeX 2.09-*-
\documentstyle[11pt]{article}

\def\MusiXTeX{MusiX\TeX}
\def\bs{{\tt\char'134}}
\def\PMXX{{\bfx PMX}}
\def\PMX{{\PMXX~}}
% Use \bfx for program names only.  Use \bf for single embedded letters 
\font\bfx=cmb10 scaled\magstephalf
\font\bfi=cmbxti10 scaled\magstephalf 
\setcounter{secnumdepth}1
\setcounter{tocdepth}3
\def\Bslash{\tt\char'134}
\def\|{{\tt\char'174}}
\def\LBR{{\tt\char'173}}
\def\RBR{{\tt\char'175}}
\textheight= 9.5in \voffset-.8in%
\textwidth= 6.5in \hoffset-1.0in

\begin{document}

\title{
  \Huge\bf
  PMX~--~a Preprocessor for \MusiXTeX{}\\
  \null\vskip-15pt
  \Large\sl
  Version 1.3.4~--~March 1998\\ 
  \author{\Large\rm Don \sc Simons\\
  \large\sl
  Dr. Don's PC and Harpsichord Emporium\\
  \normalsize\sl
  Redondo Beach, California, USA.\\
  dsimons@logicon.com}}
\date{}

\maketitle

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

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

        \PMX can help you typeset a musical score if (a) you have \MusiXTeX{}
version 0.396T or later installed and (b) your score has from one to
seven staves (or voices) per system.  
The goal
of \PMX is to facilitate the efficient production of scores and parts
that have an almost professional appearance.  It can do {\it all} the work
involved in setting up {\tt \bs notes-\bs enotes} groupings, 
selecting groups of
notes to be beamed, defining beam heights and slopes, spreading the
entire piece evenly over a specified number of systems, and inserting
extra spaces where needed to make room for accidentals, flags, dots,
and new clefs.    The input language for \PMX is much simpler than
\MusiXTeX.  You can enter note values and rests from dotted whole notes
to 64ths, ornaments, slurs, and limited text strings.  Every
voice in every bar must have exactly the correct number of beats in
the current meter, but you may change the meter at the beginning of any
measure, with or without printing the new time signature.  On the
first pass, {\bfx pmxa}  checks these timings and other aspects of the input.
\PMX has special features for dealing with baroque chamber music, including
the ability
to notate figured bass below the bottom staff in each system.  If \PMX hasn't
yet learned to do something you want to do, you can usually work around the 
problem by inserting literal TeX strings in the \PMX input file.

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

The native language of \PMX is FORTRAN and its home port is DOS; the basic
distribution contains the corresponding source and binaries.  Thanks to 
some very helpful individuals, ports are available for Macintosh and UNIX (see
section~\ref{where} on page~\pageref{where}).  

\subsection{Conventions for This Manual}

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

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

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

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

        Speaking of jargon, there are several special words that have very 
specific meanings here: A {\it staff} is one set of 5 lines (plural 
{\it staves}), a {\it system} is a group of staves, {\it voice} is the same as
{\it staff}, and  {\it line of music} refers to one of the one or two 
simultaneous allowable sequences of notes in a voice. Note that this  
definition of voice is a little unconventional, since a single voice may have
more than one line of music.

\subsection{Setup}

	This section describes the setup for the DOS version or for those 
compiling the FORTRAN source.  Other versions should be accompanied by their
own setup instructions.  

	After decompressing the distribution file if necessary, 
you should have these 
files: {\tt pmxa.for, pmxb.for, scor2prt.for}, three corresponding 
DOS executables, several sample {\tt .pmx} files,\break 
{\tt pmx.tex, ref134.tex} (\TeX\ source for a command summary),
{\tt pmx134.tex }(\TeX\ source for this file), 
and Postscript images of the latter two files, {\tt ref134.ps} and 
{\tt pmx134.ps}.  
If necessary, compile the
FORTRAN programs.  I used Microsoft FORTRAN vintage 1987 to develop 
the code, and have checked that it works on an IBM RISC 6000 when 
compiled with {\bfx xlf}.  I have tried to keep the code generic enough that 
it will work with any reasonable FORTRAN compiler, although I can't say for
certain whether it adheres to any particular standard.  

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

\subsection{Quick Start}

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

Execute the first pass by running {\bfx pmxa}.  You will be prompted for 
a {\it basename}, which is the name of the input ({\tt .pmx}) file without the 
extension, in this case {\tt barsant}.  If {\bfx pmxa} runs successfully 
it will 
generate two temporary files in the working directory, {\tt pmxtex.fig} and 
{\tt pmxtex.dat}.  Then run {\bfx pmxb}.  This will create {\tt barsant.tex} 
in the texinput directory.  Now you are right where you would be after 
entering, debugging, and rough-editing the {\tt .tex} file manually.  To see 
the results, process {\tt barsant.tex} just as you would for any \MusiXTeX{} 
file, running all three passes, and view the {\tt .dvi} file.  To make 
separate parts, run {\bfx scor2prt} and enter {\tt barsant} when prompted.  
The program will create a new {\tt .pmx} file for each instrument, in this
case {\tt barsant1.pmx} and {\tt barsant2.pmx}.
You may then process these 
files like you did the original one to create separate parts.

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

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

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

	Starting in the first non-comment line above,   

{\tt nv} (integer$<$8) is the total number of voices, or staves per system.  
(We will use the terms {\it voice} and {\it staff} interchangeably).  Each 
voice or staff may contain either one or two lines of music.

{\tt noinst} (integer$<$8) is number of {\it instruments}.  Usually 
{\tt noinst=nv}.  
Only the first instrument -- the lowest in each system -- can have more 
than one voice. If {\tt nv$>$noinst}, then the lowest instrument will have 
{\tt nv-noinst+1} voices (staves), 
and they will be set off with a curly bracket at 
the left.  If {\tt nv$>$1} and {\tt noinst=1}, then all voices will be 
bracketed together.  For a typical example of keyboard music, see 
{\tt mwalmnd.pmx}, in which {\tt nv=2} and {\tt noinst=1}, producing two 
staves per system with a curly bracket at the left.  

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

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

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

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

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

If {\tt npages}$>$0, it is the number of pages and {\tt nsyst} is the total 
number of systems in the entire piece.  \PMX will spread the entire 
piece horizontally over this number of systems, and vertically over 
{\tt npages} pages.  For proper vertical spacing there should be from 
about 9 to 16 staves per page.  If you specify too many staves for the number
pages,  one or more staves will spill over onto an extra sheet.  If this 
happens it will only become obvious when you preview the {\tt .dvi} file.  
However, with
practice, you can spot the problem by watching the page numbers printed 
to the screen on the
first pass through \TeX. The most common 
solution is either to increase {\tt npages} or 
decrease {\tt nsyst}.  

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

{\tt musicsize} is either 20 or 16, the height of a staff in points.

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

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

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

	The rest of the {\tt .pmx} file is the {\it body} of the input.  
The basic unit of input from here on is called an {\it input block} or 
just {\it block}, each one 
representing an integral number of bars except 
possibly the first, which may include a pickup.  There will usually be 
4 to 8 bars in a block.  15 is the most allowed.  It is good practice 
to separate the blocks with comment lines showing which bars they 
represent, as I've done in {\tt barsant.pmx}.  
It is also advisable, although not required, to separate the bars with
the symbol {\tt |}, whose main functions 
are to provide visual separation in the input file, and to help isolate input
errors: if you inadvertantly put one anywhere except 
at a bar-end, {\bfx pmxa} will stop and show you where it detected the 
timing error. Otherwise, with one minor exception (user-defined hardspace 
at the end of a bar), 
{\tt |} has no effect.  

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

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

\subsubsection{Notes}

	Symbols for notes always start with a lower-case letter and end at 
the first space. The first letter is the note name ({\tt a-g}).  The 
rest of the characters can be in any order with only a few 
restrictions.  The first digit defines the {\it basic time value} of the 
note: {\tt 9, 0, 2, 4, 8, 1, 3} or {\tt 6} respectively for double-whole,
whole, half, quarter, 
eighth, sixteenth, thirty-second, and sixty-fourth notes.  The second 
digit sets the octave (for reference, octave 4 runs from middle C to 
the B above).  Certain letters may appear after the initial one: {\tt d} 
for {\bf d}ot; {\tt f, n,} or {\tt s} for {\bf f}lat, {\bf n}atural, 
or {\bf s}harp (repeat the letter  
immediately for a double); {\tt u} or {\tt l}, which  force the stem 
direction of any un-beamed note; {\tt e} or {\tt r} to shift the notehead 
l{\bf e}ft 
or {\bf r}ight by its own width; and {\tt a} (for {\bf a}lone) which inhibits 
beaming for this note.  The only other characters allowed in note 
symbols are {\tt +}, {\tt -}, {\tt .}(period), {\tt ,}(comma), {\tt x}, and 
several special characters following {\tt x}, all to be described below.  
Between the first letter and the end or {\tt x} if present,
non-digits can be in any order with respect to each other and to the digits, 
with one minor exception involving shifting dots.  To move
a dot from its default location, simply follow the {\tt d}
with one or two decimal numbers, each predeced by {\tt +} or {\tt -}.  
The first is the 
vertical shift in \bs{\tt internote}s, the second, the horizontal shift in 
notehead widths.  

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

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

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

The first note symbol of each line of music in a block must 
contain at a minimum the note name and a basic time value.  An option in 
setting the 
pitch level of the first note in a line in any block except the first, is to 
rely on the fact the pitch is remembered from the corresponding line at the
end of the prior block (duration is not).  However, 
if the number of lines of music in
a staff  
has changed from the prior block, it is safest to re-enter the octave at the
start of a new block.

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

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

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

	Xtuplets can have from 2 to 24 notes of equal 
duration.  The symbol for the first note of an xtuplet begins exactly like a 
note symbol with the name of the first note in the xtuplet.  However, 
the actual time value (including a dot if present) now represents the 
total duration of the xtuplet.  After this (with no space, as always) comes 
{\tt x} followed by a one- or two-digit integer for the number of notes in 
the xtuplet, then optionally an {\tt n} to control the printing of the 
{\bf n}umber. A blank following {\tt n} signals that the number should not be
printed. On the other hand, if one or 
two decimal numbers follow {\tt n}, 
each preceded by {\tt +} or {\tt -}, the first 
is a vertical shift in {\tt \bs internote}s, and the second, a horizontal shift 
in notehead widths.  A final option after {\tt n} is {\tt f}, to {\bf f}lip
the number vertically from its default position. 

The second through last notes of the xtuplet are each then 
represented by a separate symbol containing a subset of the characters 
permitted for ordinary notes: note name (the only required character), 
octave change character ({\tt +} or {\tt -}), and accidental.  No time values 
or dots are permitted, nor are numbers permitted as octave indicators.

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

\subsubsection{Rests}

	The symbol for a rest stars with {\tt r}.  
Then for a normal rest, in either order come a digit for the basic time value 
(using same codes as for notes, optional if unchanged from previous value) 
and a {\tt d} if the rest is dotted.  The basic time value of a rest 
affects future notes and rests the same as if it had come from a note, 
i.e., it applies until another value is entered with a subsequent note 
or rest in the same line of music.  The symbol {\tt rp} represents a 
full-bar rest notated with a {\it pause} character (whole rest) regardless of 
the time signature; in this case no other duration information is 
needed or allowed.  {\tt rb}, followed if necessary by a duration 
specifier, denotes a {\bfi b}{\it lank} rest, one that occupies space and time 
but is invisible. This is most often used when there are
two lines of music in a staff and one drops out for some of the duration
of the current input block.  (See {\tt mwalmnd.pmx} for examples).
   {\tt rm} followed immediately by an integer will generate a 
{\bfi m}{\it ulti-bar} 
rest, a special combination of symbols between two bar lines with an integer 
above representing two or more bars of rest.   
This symbol will generally only be used in separate parts 
after having been automatically generated by {\bfx scor2prt}.

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

\subsubsection{Chords}

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

    When chordal notes are beamed together, the default height and angle of 
the beam will be determined by the main note on each stem (the one without 
{\tt z}).  If
a beam joining chordal notes looks bad, you can often 
fix it either by reordering
the notes on one or more stems, or by fine-tuning the beam parameters as
described later.

\subsubsection{Grace notes}

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

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

\subsubsection{Ornaments}

	Symbols for ornaments are entered {\it after} their associated 
note symbol.  The ornaments now available are shake ({\tt ot}), {\bf m}ordent 
({\tt om}), ``x"- or ``+"-shaped ornament symbols ({\tt ox, o+}), pizzicato 
({\tt ou}), strong {\bf p}izzicato ({\tt op}), right parenthesis ({\tt o)}), 
upper {\bf f}ermata ({\tt of}), {\bf d}own {\bf f}ermata ({\tt ofd}), 
staccato ({\tt o.}), tenuto ({\tt o\_}), se{\bf g}no 
({\tt og}), arbitrary-length wavy-line {\bf t}rill with {\it tr} ({\tt oT}), 
arbitrary-length wavy-line
trill without {\it tr} ({\tt oTt}), sforzando ({\tt o>}), and 
duncecap ({\tt o}\hbox to 6pt{\tt\^~}).
All except the right parenthesis, staccato,
tenuto, and down fermata will 
appear above the staff; the right parenthesis appears to the right of 
the note head, and staccato and tenuto just above or below depending on the 
stem direction.  (The only difference between staccato and 
pizzicato is the vertical positioning of the dot.)
The trill and segno symbol may have additional optional
characters.  Either trill symbol may include a decimal number 
to specify the length of the printed symbol in current \bs{\tt noteskip}s; the 
default is 1. Thus {\tt oT0} represents {\it tr} with no wavy line.  
A segno can only appear in the first (lowest) voice.  It 
may be immediately followed by a positive or negative 
integer, which indicates a number of points that it will be offset 
horizontally; and it will appear above every system.

	Once the ornament type has been specified, most of them can be raised 
or lowered from their default position by appending
a signed integer to the symbol, representing the vertical offset
in \bs{\tt internote}s. 

     If an ornament is to be repeated on a series of consecutive notes, end 
the first ornament symbol with {\tt :} .  The every note in that line of music 
will then 
have the same ornament until a note is followed by the repeat terminator
{\tt o:} .

\subsubsection{Editorial accidentals}

     To place a small sharp, flat, or natural symbol above the staff, after the
affected note enter {\tt oe} followed by {\tt s, f,} or {\tt n}.

\subsubsection{Slurs}

	The normal symbols for slurs are {\tt (} placed with a space 
before a note, and {\tt )} placed after.  The symbol {\tt s} is equivalent to
{\it both} of them (!), except that it always follows the affected note.
A fourth symbol {\tt t} is also equivalent to {\tt s} and {\tt )} but 
with one minor difference to be explained later.  
In truth there are all {\it toggles}, turning
a slur off if it's already on and starting one otherwise.    

   The first character is optionally followed by
a single-character ID code ({\tt 0-9} or {\tt A-Z} , then by other
options described below.  ID codes are only needed if two or more beams are 
open at the same time within one line of music, such as when several chord 
notes are tied.  Using ID codes in such cases tells \PMX which open slur to
close.  
 
The rules for finding the default direction and position of the a slur
are complex; many factors enter into defining visually pleasing values.  But 
there's no need for gory details here; the result will usually satisfy, and if 
not, all can easily be tweaked.  Default direction can be 
overridden with {\tt u} ({\bf u}pper), {\tt l} ({\bf l}ower),
or equivalently {\tt d} ({\bf d}own).  
Starting or ending position can be shifted from its default by
entering one or two explicitly signed numbers.  The first, which must be
an integer, represents the vertical shift in \bs{\tt internote}s; the second,  
which may be decimal, the horizontal offset in notehead widths.

Slurs work on all chordal notes.  

Slurs involving grace notes are specified within the symbol for the grace.

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

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

\subsubsection{Ties}

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

\subsubsection{Beams} \label{beams}

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

{\tt u} or {\tt l} will override 
\PMXX 's selection of the direction of the beam. 

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

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

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

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

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

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

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

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

       Beams cannot normally jump staves.  But if that is desired, start
the beam normally in one voice, and terminate the part of the beam in that
voice with {\tt ...~]j} .  Then resume the beam in the new voice with 
{\tt [j~...} . For staff-jumping beams, there may be just a single note 
inside one or both of the members.  Some adjustment of the beam height and
slope may be required.  Sometimes the ending section's up-downness must be 
overridden; you will know this is so if the ending is shifted horizontally 
from its proper position.  These are currently limited to single 
(eighth note) beams.  Each line of music must still have the right number
of beats, so you will probably need to fill time with blank rests after the 
first member of the beam and before the second.  
Finally, if the beam runs from a higher staff to a lower one, the \TeX\  
command starting the beam may come after the one ending it.  To patch up
this problem, you can usually convert either 
the first or second member to an xtuplet.  This works because \PMX basically
gives each xtuplet its own \bs{\tt notes} group. 

\subsubsection{Clefs}

	A clef change is signaled by {\tt C} followed by a single lower-case 
letter using the code specified at the end of section~\ref{setupdata} on 
page~\pageref{setupdata}.  Numbers may also be used as 
defined in the \MusiXTeX{} documentation.  If clefs come out at the wrong 
vertical position, refer to the note in {\tt pmx.tex}.

\subsubsection{Arpeggios}

To set an arpeggio (a vertical wavy line), simply place the symbol {\tt ?} 
after the symbols for both the first and last note.  

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

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

\subsubsection{Repeats and double bars}

	Repeat signs and double bars are signaled by {\tt R} followed by 
{\tt l, r, lr, d, D,} or {\tt dl} for 
{\bf l}eft repeat, {\bf r}ight repeat, {\bf l}eft-{\bf r}ight repeat, 
thin-thin {\bf d}ouble 
bar, thin-thick {\bf D}ouble bar, or thin-thin {\bf d}ouble bar followed by
{\bf l}eft repeat.  
These symbols must be in the 
first voice, and must be followed in the same block by at least one 
note or rest, except at the very end of the piece.  Unfortunately, 
this requirement can cause a little confusion for right repeats, since 
they have to appear at the start of the next bar, which is usually in 
the next input block. 

Using two separate {\tt R..} symbols in succession will cause 
unpredictable results.  

If {\tt Rlr} falls at a system break, \PMX will automatically split it in 
two.  The symbol {\tt Rdl} will likewise be split at a system break, but if
not at a system break, the {\tt d} will be ignored. 

\subsubsection{Voltas (first and second endings)}

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

\subsubsection{Meter changes}

	A {\bfi m}{\it eter change} symbol is a letter {\tt m} followed by 
4 numbers 
with no intervening spaces.  The four numbers are {\tt mtrnuml}, 
{\tt mtrdenl}, 
{\tt mtrnmp}, {\tt mtrdnp} as defined in section 2.1.  
Meter can only be changed at the 
beginning of a block.  When changing meters, you must use {\tt o} to represent 
the number 1; if you enter the digit {\tt 1} then \PMX will interpret that 
digit and the next as a 2-digit integer, between 10 and 19 inclusive.

\subsubsection{Transposition and key changes}

	To transpose an entire score, at the beginning of the first block 
enter {\tt K} (for {\bfi K}{\it ey}) followed by two explicitly signed digits.  
The 
first is the distance to transpose (in \bs{\tt internote}s); the second is the 
new key signature.  When transposing, you should always use relative 
accidentals, signaled by the separate symbol {\tt Ar} (see below).  For example,
 to transpose a piece in C major to E major you would enter 
{\tt Ar K+2+4} at the beginning of the first block. 

	A key change can be signalled at any time in the first voice, and will
affect all voices.  Use the command {\tt K} with {\tt +0} as the first
argument and the new key signature as the second.

\subsubsection{Text}

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

	A {\it title block} with up to three elements can be defined at the 
beginning of the first input block.  {\tt Tt} signals that the text 
{\it on the following line} is to be set as a {\bf t}itle for the whole piece, 
and it will be centered. {\tt Tc} similarly indicates a {\bf c}omposer's name, 
to be set below the title and right justified. {\tt Ti} likewise stands for 
an {\bf i}nstrument name, which will be set above the title, left-justified. 
{\tt Ti} will automatically be invoked by {\bfx scor2prt} when it generates 
parts from a score.  Extra vertical space can be added between the title 
block and the top system by appending to {\tt Tt} a one- or two-digit 
number representing the space in \bs{\tt internote}s.  This only works if 
{\tt Tt} is the {\it final} title block element entered.

\subsubsection{Page numbering}

	If you want pages to be numbered at the top left or right, place 
the symbol {\tt P} anywhere within the \PMX code that represents the first 
page to be numbered (usually the first or second).  
{\tt P} can be followed optionally by the starting 
page number and/or by {\tt l} or {\tt r}, the latter overriding the default 
locations of odds on the right and evens on the left.  This command 
will be ignored when making parts from a score (since page numbering 
will usually be different in the score than in the parts), but page 
numbering for parts can be still be initiated independently, for 
example with {\tt \%!P2} or {\tt \%1P2r} (see section~\ref{scor2prt}, page~\pageref{scor2prt}).

\subsubsection{Overriding defaults for accidentals, 
dot positions, 
spaces at start of bar and between staves}

	The symbol {\tt A} can be used to override a grab-bag of 
default settings:  

{\tt b} makes all accidentals 
{\bf b}ig, {\tt s} makes them all {\bf s}mall.  By default, big ones are used 
unless unaltered spacing doesn't provide enough space.  

If transposing, then the {\it relative} accidental convention should be used, 
indicated by {\tt r}.  The default is the normal, absolute convention.
 
In staves with two lines of music, {\tt d} causes dots in the lower line 
to appear on or {\it below} center, in contrast with the default. 

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

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

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

	Despite the author's best intentions to relieve you of the chore 
of adjusting {\it any} horizontal spacing by hand, there may be some occasions 
where you 
will want to do it.  A symbol starting with {\tt X} initiates one of two 
types of horizontal adjustment.  The {\tt X} must always be followed by 
a decimal number. If 
then comes a {\tt p} the number is in points, otherwise, notehead widths.
If the next character is a blank. hardspace will be inserted in all voices.  
The symbol may appear in any staff but will affect all voices in a score, 
and everything
in that system will be moved proportionally.  On the other hand,   
if the next character after the number (or {\tt p}) is {\tt S} or {\tt :}~, a
shift is initiated in the current line of music only.  
If the character is {\tt S}
then only the next note/rest is shifted.  If it's {\tt :}~, all following
notes in
the current line of music will be shifted, until the shift is terminated with
{\tt X:}~.  Neither type of shift affects notes in other lines or notes
past the end of the shift.  A shift cannot extend across a bar line.  

Since spacing in parts will usually differ from that in the 
score, the hardspace command will not be copied into parts by {\bfx scor2prt}.  
If you want to insert hardspace into a part, use the syntax 
{\tt\%}[{\it n}]{\tt X}[{\it x}] on a separate line, as described in 
section~\ref{scor2prt}.

\subsubsection{Minimum spacing between notes in crowded systems}

	\PMX does some special, complex analysis to adjust horizontal spacing 
in crowded systems.  By default, the minimum space between consecutive 
noteheads is 0.3 notehead widths.  If you want to change 0.3 to some 
other fraction, enter {\tt W. }(decimal point is required) followed by 
{\tt 1}-{\tt 9} to represent the number 
of tenths of a notehead width to be used as the minimum spacing.

\subsubsection{Page size}

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

\subsubsection{Line, page, and movement breaks}

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

        To force a movement break, you must first force a line break as above,
then enter {\tt M}.  If a page break also occurs here, the {\tt P} must precede the
{\tt M}.  The options following {\tt M} are {\tt +}({\it integer}) to insert
vertical space in \bs{\tt internote}s before the break, and 
{\tt i}({\it decimal number}) to reset the first-line indentation as a fraction
of the line width.  Immediately after the break, any desired meter changes, 
key changes, or text can be entered in the normal way.


\subsubsection{Fractional bars}

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

\subsubsection{Stem direction of bass notes}

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

\subsection{Putting \TeX ~Commands into the {\tt .pmx} File } \label{LitTeX}

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

	The four categories of in-line TeX strings, 
differ mainly in where they will appear in the {\tt .tex} file.  
In the {\tt .pmx} file, 
all except type 4 can occupy only one line, and it must have fewer than 
128~characters, although each line can have more than one \TeX\ command.
Type 1 begins with a single \bs\ and will appear in the {\tt .tex} file 
right before the \TeX 
~command for the next note or rest in the {\tt .pmx} file.  
{\it Each note or rest may have only 
one type 1 literal \TeX ~string.} Type 2 begins with \bs\bs\ 
and will appear at the top of the {\tt .tex} file, right before 
\bs{\tt startmuflex}, regardless of where it appears in the {\tt .pmx} file.  
Type 3 starts with \bs\bs\bs\ and will appear right before the {\tt \bs xbar}
or {\tt \bs alaligne} at the beginning of the current input block, before the
first barline of the block.  While types 2 and 3 are restricted to a 
single line, if more than one of either type are entered consecutively, they
will appear together in the {\tt .tex} file.   
Types 1, 2, and 3 must end with \bs\ (backslash-space). 
This means that they may not contain
the \TeX\ macro \bs\  (backslash-space). 

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

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

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

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

\subsection{Figured Bass}

	Figure symbols are entered {\it after} their associated note symbols.  
They only work in the first (lowest) voice.  Enter the characters as 
they would appear from top to bottom, and as you might pronounce them, 
e.g., {\tt 64} or {\tt 73}.  Flats here are {\tt -} (minus), sharps are 
{\tt \#}, and 
naturals {\tt n}, {\it before} the number (if there is a number) (notice
they're different here than in note symbols).  
So for example {\it sharp third} is {\tt \#3}, just a sharp is {\tt \#}, {\it six (over) 
flat five} is {\tt 6-5}, and {\it sharp six (over) 4} is {\tt \#64}.  
The program 
positions all the figures for each system below the lowest staff of that 
system, with their tops aligned, and just low enough to clear the 
lowest beam, notehead, or stem that could interfere.  If you want a figure to
align horizontally in the second tier, insert the placeholder figure
{\tt\_} (underscore) before the one you want lowered. 

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

	There is also a {\it continuation} symbol, a zero followed by another 
digit.  This produces a horizontal line under the bass note, starting 
just to the left and extending to the right by the given number of 
\bs{\tt noteskip}s.  The height and length of the line are set by the current 
note's level and \bs{\tt noteskip} respectively.  
If \bs{\tt noteskip} changes or a note drops 
below the starting level before the line ends, it is possible to trick 
\PMX by entering separate {\tt 0}[{\it n}] symbols under each consecutive note; \PMX 
will automagically join them together at the same height 
(thanks to Werner Icking for this idea).  \PMX 
can't directly handle continuation symbols above or below other 
figures.  If you want to do that you could look for the macros 
{\tt \bs Figu} 
and {\tt \bs Cont} in {\tt pmx.tex} and work out how to use them manually 
as in-line \TeX ~commands.

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

\subsection{Macros}

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

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

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

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

\subsection{Lyrics}

	\PMX has no special provisions for lyrics.  One possible way to include
them would be with manually inserted in-line \TeX .  
A much better way would be to use the
program {\bfx M-Tx} developed by Dirk Laurie.  It is a pre-preprocessor which
produces a {\tt .pmx} file containing the proper in-line \TeX\ commands.  
Its input language includes all of the \PMX symbols as a subset.  It
is available on {\tt ftp.gmd.de} (see section~\ref{where}), or at
{\tt ftp://calvyn.puk.ac.za/dirk/mtx/} .

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

	Separate parts can be made by running {\bfx scor2prt} and entering the 
basename when prompted. The program 
will create {\tt noinst} separate 
{\tt .pmx} files, one for each instrument. The files will be named
\break [{\it basename}][{\it n}]{\tt .pmx}, where [{\it n}] 
is the number of the voice.  

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

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

	Conversely, if a line begins with {\tt \%!} then it will be ignored as 
usual in creating the parent {\tt .tex} file, but after stripping the first 
2 characters the rest will be put in the {\tt .pmx} file for {\it all} the parts.  
Lines beginning with {\tt \%}[{\it n}] will be transferred into the 
{\tt .pmx} file for 
part {\it n} only.  For example, to force a line break to system 15 and a page 
break to page 2 in part 3 only, enter {\tt \%3L15P2}.

	Although only permitted in the first voice in the score, the 
following symbols with all their options will automatically be copied 
into all parts (unless the preceding line has {\tt \%\%}):
 {\tt m, V, R, A, h, w, K}.  
Types 2 and 3 literal \TeX\ strings will also be 
copied into all parts.
Conversely, user define hardspaces ({\tt X} 
without {\tt :}) will never be copied into parts.  
If you need to insert hardspace {\it x} into part 
{\it n} , then in the score, on a line of its own, you may use 
{\tt\%}[{\it n}]{\tt X}[{\it x}] .
Lateral shifts 
({\tt X}[$\dots$]{\tt :}) 
will be handled normally,
staying with their original line of music.

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

	As already noted, a {\tt P} symbol for page numbering in the parent 
file is ignored when making parts.  To initiate page numbering in the 
parts, use for example {\tt \%!P} anywhere within the \PMX code representing the first page of the parts 
(from \TeX 's standpoint the command must occur between 
the beginning and end of the page on which the numbering is to begin).

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

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

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

\section{Limits}

For simplicity in writing the program, \PMX has numerous variables with
fixed dimensions.  In most cases there are no checks against these limits
(hey, I've got more important things to program), so
occasionally there may be hangups due to exceeding a dimension.  
Any of these can be increased on request.  However, before making such a
request, it will usually be possible to work within existing limits by 
breaking the input into smaller blocks.  

\subsection{Limits under direct user control}  

\ \ \ \ \ 128 characters per input line.

7 voices (staves).

2 lines of music per staff.

7 lines of music.

125 systems.

500 bars.

40 forced line breaks.

10 forced page breaks.

14 key changes.

20 pages.

200 notes per input block.

15 bars per input block.

101 slurs per input block. 

74 figures (figured bass) per input block.

37 grace note groups per input block.

74 notes in grace note groups per input block.

36 literal \TeX\ strings per input block.

6 voltas per input block.

18 trills per input block.

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

8 beams per line of music per bar.

20 forced beams per line of music per input block.

10 clef changes per line of music per input block.

24 notes per beam.

24 notes per xtuplet.


\subsection{Limits not under immediate user control}

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

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

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

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

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

400 inserted standard anti-collision spaces per system.

100 inserted anti-collision spaces within xtuplets per system.

1000 inserted standard anti-collision spaces.

200 inserted anti-collision spaces within xtuplets.

\section{Closing Notes}

\subsection{About the Example Files}

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

{\tt barsant.pmx} contains the first movement of a recorder sonata by the
Italian Francesco Barsanti (1705-1765).  It demonstrates many of \PMXX 's
strong points in a ``battlefield'' situation:  figured
bass, complex beaming patterns, xtuplets, and  
automatically adjusted horizontal and vertical spacing in crowded scores.  
In fact, 
this single-page score is at the limit of vertical crowding.
If you added anything that occupied additional vertical space, e.g., by putting
a header on the first system or inserting a title, there would not be enough
vertical space available on the page and the last system would spill over.  
Some vertical space could be freed up by switching to 16-pt staves.

{\tt rtsg.pmx} is a trio sonata by Johan Helmich Roman (1694-1758), 
``the Swedish Handel''.  It demonstrates how to set movement
breaks for the score, and how to use this command and some others to 
control the appearance of the parts independently.

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

\subsection{A Benign Bug} 

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

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

The main home of \PMX on the internet is 
{\tt http://www.gmd.de/Misc/Music/} , 
or if you prefer ftp, 
{\tt /ftp.gmd.de/music/} .
\PMX files on this server are
supposed to propagate to the CTAN sites at 
{\tt ftp.tex.ac.uk} and {\tt ftp.dante.de} .  
A useful American mirror is \\ 
{\tt ftp://ftp.cdrom.com/pub/tex/ctan/support/pmx/} .

As of the date of this writing, the Macintosh and UNIX ports of this version 
of \PMX are not yet available, but they may appear soon at the following
sites or at {\tt ftp.gmd.de} .  

The previous Macintosh port by Eric Petersen 
is available at {\tt ftp.gmd.de} and at Eric's web site 
{\tt http://www.aem.umn.edu/people/students/epeterse/PMX/} .

Stefan Evert has translated the previous version of \PMX into C and prepared 
a distribution which should be compatible with most UNIX systems.  It is 
located at \\
{\tt ftp://ftp.mathematik.uni-stuttgart.de/pub/software/pmx/} .

Dirk Laurie has posted his lyrics pre-preprocessor {\bfx M-Tx} as well as 
UNIX-friendly versions of the \PMX source at
{\tt ftp://calvyn.puk.ac.za/dirk/mtx/} .

\subsection{Acknowledgments}

	To Daniel Taupin, Ross Mitchell, and Andreas Egler for creating 
\MusiXTeX{}, to Olivier Clary for suggesting a crucial modification in 
the note-entry scheme, to Robin Fairbairns and Werner Icking for 
including \PMX in their archives, to my colleague John DiPol (a non-
musician!) for the idea of using binary masks to define beam 
groupings, to Dirk Laurie, Eric Petersen, Johan Tufvesson, and Stephan Evert 
for beta-testing and for porting \PMX to other platforms, and to Dirk Laurie
for making \PMX accessible to vocal music by creating {\bfx M-Tx}.  Special 
thanks and credit go to Werner Icking for exhaustive beta testing, 
uncanny bug-finding, and continuing encouragement.

\end{document}