                               PMTeX
                    A Preprocessor for MusicTeX
                by Don Simons (dsimons@logicon.com)

INTRODUCTION       
     PMTeX will generate MusicTeX code for multi-staff scores with up to 
five staves (or voices) per system.  Once it makes a .tex file for you, 
you will probably want or need to change a few things manually.  This is 
because (a) PMTeX only has a small subset of the capabilities of 
MusicTeX, and (b) PMTeX is not perfect.  But it can save a LOT of time 
with the grunge work involved in setting up notes...enotes groupings, 
defining beams, justifying lines, and spreading the entire piece evenly 
over a specified number of systems.
     PMTeX can deal with one and only one melody per staff (voice).  It 
won't let you change the time signature or key signature within a piece.  
Except the first bar, every bar in each staff must have exactly the 
number of beats specified by the input parameter mtrnum.  On the first 
pass pmtexa will choke if these timings or just about anything else is 
askew in the input.  The error messages are not especially pointed, so 
it is best to enter only a few bars at a time, run pmtexa, correct 
errors, rerun, etc.
     You can enter note values and rests from whole notes to 32nds, and 
trills and mordents.  Since I'm interested in baroque chamber music, I 
built in the ability to notate figured bass below the bottom staff in 
each system.

SETUP
     The distribution contains the files pmtexa.for, pmtexb.for, 
pmtex.inc, sample.inp, and pmtex.tex.  First compile the two FORTRAN 
programs (with the .inc file accessible to the compiler).  I used 
Microsoft FORTRAN to develop the code, and have checked that it works on 
an IBM RISC 6000 when compiled with xlf.  I hope the code is generic 
enough that it will work with other systems.  Put the executables either 
in your working directory or somewhere in the path.  Put pmtex.tex into 
the texinput directory.  Put sample.inp into your working directory (the 
one from which you will run PMTeX.  Edit the 7th line of sample.inp to 
contain the path to the texinput directory; the code will put the .tex 
file there. If you want this to be the same as the working directory, 
type '.\' for DOS, or './' for UNIX (don't type the quotes).  If you 
have a conventional PCTeX setup you would enter 'c:\pctex\texinput\', 
etc.  Next run the first pass by typing 'pmtexa'.  You will be prompted 
for a basename; for the sample it is 'sample'.  If pmtexa runs 
successfully it will generate two files in the working directory, 
pmtex.fig and pmtex.dat.  Next run pmtexb by typing 'pmtexb'.  This will 
put sample.tex and sample.fig into the texinput directory (.fig only if 
you have figured bass).  Now you are right where you would be after 
manually entering, debugging, and rough-editing any .tex file.  To see 
the results, 'tex' the file sample.tex.  You'll notice that two systems 
on each of the two pages are a little too long.  That's not your fault; 
I left things that way just to PROVE that PMTeX isn't perfect.  To fix 
them, manually increase the first autolines parameter for each of these 
lines by one.

WHAT GOES INTO AN INPUT FILE
     Let's just go through sample.inp.  It will take a while, but we'll 
cover practically all the possible inputs.  For reference, here are the 
first 9 lines of the file:  

3 3 4 4 6 1 3 
5 10 20 0.07 
Basso 
Violin II 
Violin I 
btt 
c:\pctex\texinput\
%     read(10,*)nv,noinst,mtrnum,mtrden,imeter,xmtrnum0,isig, 
%    *          lpp,nstaves,musicsize,fracindent       

These are the setup data.  The lines with % in column 1 are comments.  
You can only put comments AFTER the end of the initial data section.  
Starting in the first line,   

nv (integer<6) is the number of voices, or staves per system.    

noinst (integer<6) is number of 'instruments'.  All this does is choose
     whether you want a brace in front of each system (noinst=1) or not
     (noinst>1).    

mtrnum is the numerator of the time signature, mtrden the denominator.
     So far I've only tested 3/4, 6/8, 2/2, 2/4, and 4/4 but others may 
     work.  

imeter determines how the time signature looks:      
     0           Fraction
     2, 3, or 4  Just that number, between the 2nd and 4th lines
     5           Common time
     6           Cut time (alla breve)

xmtrnum0 is the number of beats in the first bar, but only if there's
     a pickup; otherwise set it to 0 .  I had intended fractions to work
     but they don't seem to, just integers.  The first bar is the ONLY
     bar that can have a different number of beats.   

isig is the key signature, positive integer for sharps, negative for
     flats.

lpp is the number of systems per page.

nstaves is a misnomer (I just realized): it's really the total number of
     systems in the whole piece.  Leftovers start at the front, so for
     example if lpp=3 and nstaves=5 there will 3 systems on the first
     page.  WARNING: if you are building an input file one gulp at a 
     time, you will have to adjust this parameter to roughly reflect the 
     CURRENT number of staves.  If nstaves is too big for the current 
     number of bars. the code will choke.

musicsize is 20 or 16 (height of a staff in points).

fracindent is the fraction of the total line width to indent the first
     line.

     Next come the names of the nv instruments as you want them to 
appear within the indentation in the first system, one per line, 
starting with the BOTTOM voice.  Then a string of nv letters for the 
clefs, again starting with the bottom voice: 'b' for bass, 'a' for alto, 
't' for treble.       
     Line 7 in sample.inp is the last of the setup data, the path to the 
.tex directory, where you want sample.tex to go when pmtex makes it.         
The rest of sample.inp is the body of the input.  You feed it music in 
gulps of an integral number of bars, usually 4 to 8.  If you give it too 
big a gulp, it will choke (due to dimension limits), and there aren't 
any internal dimension checks.  (I've been bitten by this one myself). 
Each gulp has some stuff for a few bars of the first (lowest) voice, 
then a '/', then the second voice for EXACTLY the same number of bars, 
another '/', and so on for nv voices.  When the last (top) voice 
finishes (with a '/') the gulp is ready for digestion.
     The stuff for each voice is a sequence of "symbols" of one or more 
adjacent characters, separated by spaces.  Separate the voice-
terminating '/' with spaces just to be safe.
     Note symbols always start with a letter and end at the first space. 
The letter has the obvious meaning (unlike another entry system we all 
know about, which unfortunately I could never get comfortable with and 
believe me I did try but I guess I'm getting too old).  Next is a digit 
for the octave...middle C is c4, the B just below is b3.  If a note is 
the same length and within a fourth of its predecessor, the symbol can 
be one letter only, provided it doesn't have an accidental.  This makes 
it really easy to enter long strings of scalewise or even arpeggiated 
notes of equal value: letter,space,letter,space...  If a note is the 
same length but more than a fourth away from its predecessor, and again 
no accidental, the note symbol can be just two characters long, the note 
name and the octave.  Next comes a digit for the length (if needed): 0 
for whole, 2 for half, 4 for quarter, 8 for eighth, 1 for sixteenth, and 
3 for thirty-second notes (with credit to Dr. T's Copyist Apprentice, my 
first foray into notation programs.  Actually it seems really cool to me 
that these digits don't bump into each other but still cover all normal 
possibilities.)  (Sorry, we don't do triplets.  If you just have a few 
triplets, enter something else and fix them by hand later.  If there are 
a lot of triplets you could try using a separate file for that section, 
faking out the code with a different time signature--say 6/8 instead of 
2/4--then manually merging the .tex files later.)  The next two 
characters (if needed) are letters to signal a dot ('d') and/or 
accidental ('f':flat, 'n':natural, 's':sharp).  If both are present they 
can be in either order.  If either is present then the first three 
characters--note, octave, duration--are required.  Don't enter an 
accidental if it's in the key signature.  Advanced users can change the 
behavior of the accidentals to 'smart' (transposable) from literal (the 
default) by editing pmtex.tex.  (With the baroque convention for 
accidentals, 'smart' ones don't work even if you're not transposing!)  
The code tries to put in extra horizontal space if needed to make room 
for accidentals.
     After a note symbol goes any associated ornament or figure.  The 
only ornaments are trill ('ot') and mordent ('om').  (Minimal 
programming could expand this list, but I haven't needed any others).  
All accidentals will come out just high enough above the staff not to 
crash into their notes.
     A rest symbol has two characters, just 'r' followed by a digit for 
its length, using the same code as for note values.

FIGURED BASS
     Figure symbols follow 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., '64' 
or '73'.  Flats here are '-' (minus), sharps are '#', and naturals 'n', 
BEFORE the number (if there is a number) (perversity or absentmindedness 
is why they're different here than in note symbols).  So six (over) flat 
five is  '6-5' as in the first line of the body of sample.inp, and sharp 
six (over) 4 is '#64'.  The program prints all the figures for each 
system below the lowest staff, with their tops aligned, and just low 
enough to clear the lowest beam, notehead, or stem that could interfere.  
(This was kind of tricky to program!)

A WORD ABOUT SLURS AND TIES
     There's no provision for them in PMTeX.  Why?  I handle them with 
another code that post-processes the postscript file.  That code will 
only run on a PC with VGA graphics.  If there is interest, I'll 
distribute it later.  But for now, sorry, you're on your own.  At worst, 
you can enter MusicTeX slur codes manually.

TH-TH-THAT'S ALL, FOLKS
     There's not much more to say about basic care and feeding of PMTeX.  
One suggestion worth repeating is to enter just a few bars at a time, 
and at least run them through pmtexa to get rid of typos.  If you wanted 
to type a lot at once, you could comment out all gulps but the first, 
then delete comment symbols a gulp at a time, letting PMTeX digest the 
gulps one-by-one.  Unless you never make mistakes.
     Please hit me with questions, bugs, and comments. I'll consider 
suggestions for additions as time and inclination permit.  I am thinking 
about improving the input checking in pmtexa.  There is one thing I hope 
I don't hear: that after trying the program you think my silly 
gastrointestinal metaphor should be carried to its logical "end" when 
describing PMTeX's output.
