% pmx11b.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{}\\ \Large\sl Version 1.1~--~February 3, 1997\\ \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. Executables are available for DOS, Macintosh, and Linux, as are C and FORTRAN source code. 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, trills, mordents, slurs, and limited text strings. Every voice in every bar must have exactly the correct number of beats in the current meter. 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 using \PMXX's facility for handling 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 score. You can control the appearance of the parts with special commands in the main input file for the score. It is thus possible to include in a single input file all the information that defines the score and the individual parts. \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 barsanti.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. \subsection{Setup} This section describes the setup for the DOS version or for those compiling the FORTRAN source. Other versions will be accompanied by a readme that describes peculiarites for that platform. 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, {\tt pmx.tex, ref11.txt, pmx11doc.tex }(\TeX\ source for this file), {\tt pmxdoc.sty,} and {\tt pmx11doc.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 6th line of {\tt barsanti.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 barsanti}. 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 barsanti.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 barsanti.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 the basename when prompted. The program will create a new {\tt .pmx} file for each instrument in [{\it basename}]{\tt .pmx}, named [{\it basename}]{\tt 1.pmx}, etc. 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 barsanti.pmx}. For reference, here are the first 8 lines: \begin{verbatim} 2 2 4 4 0 6 0 0 1 7 20 0.07 Basso Recorder bt ./ %read(10,*)nv,noinst,mtrnuml,mtrdenl,mtrnump,mtrdenp,xmtrnum0,isig, % * npages,nsyst,musicsize,fracindent} \end{verbatim} The first 6 lines in this example are the {\it setup data}. The lines with {\tt \%} in column 1 are comments. You can only put comments {\it after} the setup data. Some special handling of comment lines will be discussed in the section on creating parts from a score. Starting in the first line of the example 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. Some rare meters may cause problems with the beam grouping algorithm, but all common ones should work. {\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 tell by watching the page numbers printed to the screen on the first pass through \TeX. The 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} voice. 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. Line 6 in this example is the last of the setup data, the path to the texinput directory, where you want the {\tt tex} file to go when \PMX creates it. It must terminate with {\tt /} or {\tt \bs}. \subsection{Structure of the Body of the Input File} 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, usually 4 to 8 (except possibly the first, which may include a pickup). It is good practice to separate the blocks with comment lines showing which bars they represent, as I've done in {\tt barsanti.pmx}. (You can't enter the whole piece as a single block because if any block is too big, the code will choke due to dimension limits). There is also the optional symbol {\tt |}, whose only functions are to separate measures visually in the input file, and to help isolate input errors. If it appears anywhere except at a bar-end, {\bfx pmxa} will stop and show you where it detected the timing error. Otherwise, {\tt |} has no effect. Its use is strictly optional. 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 file. Continue entering other lines of music, each with {\it exactly} the same number of bars, terminated by {\tt /} or {\tt //}, until the last (topmost in the system) line 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 line in each voice are a sequence of {\it symbols} of one or more adjacent characters, separated by spaces. The line- terminating symbols {\tt /} and {\tt //} should also 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 0, 2, 4, 8, 1, 3}, or {\tt 6} respectively for 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 +, -,} and {\tt x}, to be discussed below. After the first letter, except for {\tt x}, non-digits can be in any order with respect to each other and to the digits. 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} is an ascending quarter-note C scale. 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 use the fact the pitch is remembered from the corresponding line at the end of the prior block (duration is not). If the number of lines per voice 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 after the note name, even if the actual time value and octave are the same as the prior note. But the 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 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). Xtuplets can have from 2 to 24 notes; the notes must be of equal duration. The initial symbol for 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, comes an {\tt x} followed by a one- or two-digit integer for the number of notes in the xtuplet, then optionally an {\tt n} to suppress the printing of the number, then a space. The second through last notes 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 {\tt c44x3 d e f4x3 g a b4x3 c d \dots} \subsubsection{Rests} A {\it rest} symbol has one to three characters, starting 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 in keyboard music where 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 {\tt mwalmnd.pmx} for examples). over it. This symbol will generally only be used in separate parts after having been automatically generated by {\bfx scor2prt}. \PMX uses a default vertical position for rests which is different if the voice has one or two lines. For one line it is just the \MusiXTeX{} default (approximately centered on the middle line). On the other hand, in the lower line of a two-line staff 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 necessarily from the \PMX default). This completes the description of the basic scheme for entering notes and rests. It can become very intuitive, allowing you to enter a sequence of notes almost as you would read it. For example. as you are typing {\tt cd45 ef8 r} you can be saying to yourself ``{\bf c} {\bf d}otted 1/{\bf 4}-note in {\bf 5}th octave, {\bf e}-{\bf f}lat {\bf 8}th note, (8th) {\bf r}est.'' \subsubsection{Chords} Chordal notes, which 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 time value or {\tt d} is allowed. Any number of chordal notes can follow a single main note. \subsubsection{Grace notes} A grace note symbol starts with a {\tt G}. Next 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), {\tt x} for a slash (only for single graces), and {\tt l} or {\tt u} to force the direction of the stem(s). Next comes 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 be preceded by spaces and likewise must not include a time value. \subsubsection{Ornaments} Symbols for ornaments or slurs 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 or staccato ({\tt ou}), strong {\bf p}izzicato ({\tt op}), right parenthesis ({\tt o)}), se{\bf g}no ({\tt og}), arbitrary-length wavy-line {\bf t}rill with {\it tr} ({\tt oT}), and arbitrary-length wavy-line trill without {\it tr} ({\tt oTt}). All except the right parenthesis will appear above the staff; the right parenthesis appears to the right of the note head. 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. 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. \subsubsection{Slurs} To allow for overlapping slurs, there are two types, denoted by the symbols {\tt s} and {\tt t}, placed after the note. These are toggles, i.e., they start a slur if one of that type is not already turned on in the current voice, otherwise they terminate it. There is no distinction between ties and slurs. There are only two minor differences between {\tt s} and {\tt t} slurs. First, if one of each type starts or ends on the same note, then the {\tt t} slur will be moved vertically away from the note a little bit to avoid a collision. So it's best to use {\tt s} for most slurs, and save {\tt t} for slurs that surround {\tt s} slurs. Second, only {\tt s} slurs are permitted in xtuplets. The default direction or starting or ending level of a slur can be overridden by appending {\tt u} or {\tt d}, or {\tt +} or {\tt -} followed by an integer for the number of \bs{\tt internote}s to raise or lower the position. \PMX will automatically adjust the horizontal position of the start or end if necessary to avoid overlapping a stem, but there is currently no \PMX command which lets the user control or override this. However, the macros \bs{\tt isu} etc\.\ defined in {\tt pmx.tex} can be entered as in-line \TeX\ commands (see below) if such horizontal offsets are needed. When this becomes necessary, as for example in chords with all notes tied, begin numbering the manually entered slurs at 0 to avoid any possible conflicts with \PMXX's automatic slurs, which are numbered from 8 downward. \subsubsection{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 ]}. One may also 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 then optionally be followed immediately by several options: (1) {\tt u} or {\tt l} to override \PMXX 's selection of the direction of the beam; and (2) one, two, or three integers, each preceded with {\tt +} or {\tt -}. The first integer is an adjustment to the starting level (in \bs{\tt internote}s) and may range from -15 to 15; 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 common 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}. 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. \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}. \subsection{Commands That Affect All Parts} \label{pmxcmds} Commands that affect all the parts can only appear in the first (lowest) line of the first (lowest) voice. 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. If {\tt Rlr} falls at the end of a system, \PMX will automatically split it in two. The symbol {\tt Rdl} may {\it only} come at the beginning of system and will always be split, leaving a double bar at the end of the prior system and a left repeat to start the new one. \subsubsection{Voltas (first and second endings)} Beginnings and ends of first and second endings are signaled by {\tt V} (for {\it volta}). 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 {\it meter 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 above. 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 append the following digit to it to make a number between 10 and 19 (inclusive). \subsubsection{Transposition} 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 interligne}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 or E major you would enter {\tt Ar K+2+4} at the beginning of the first block. \subsubsection{Text} The symbols {\tt h} or {\tt l}, when placed alone in the first column of an input line, 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. 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 the {\tt Tt} is the 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, \bs afterruleskip} The symbol {\tt A} controls the default sizes and operation of accidentals, and the size of \bs{\tt afterruleskip} (the gap between a bar line and the first note). Its options are {\tt b} to make all accidentals {\bf b}ig, {\tt s} to make all accidentals {\bf s}mall, {\tt r} for {\bf r}elative accidentals (which should always be used if transposing), and {\tt a} followed by a decimal number to override the default setting for \bs{\tt afterruleskip} (which is 1\bs{\tt elemskip}, 20 percent smaller than \MusiXTeX{}'s default). If no specification is entered for accidentals, the defaults will be absolute (not relative), and the size will be big except in places where a big accidental won't fit without adding extra space; in the latter case \PMX\ will convert it to a small accidental and add extra space if necessary. \subsubsection{Minimum spacing between notes} \PMX does some 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 and page breaks} It is possible to force line breaks or page 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). \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 d's on the middle line of 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{Literal \TeX ~Strings (In-line \TeX ~Commands)} \label{LitTeX} \PMX will accept three types of literal TeX strings, differing only in where they will appear in the {\tt .tex} file. In the {\tt .pmx} file, type 1 begins with \bs\ and will appear in the {\tt .tex} file right before the \TeX ~command for the next note 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 start of the first \bs{\tt notes} group in the current input block. Literal \TeX strings may contain more than one \TeX command, but must not exceed 80 characters in length, and may not wrap from one input line to the next. They end with \bs\ (backslash-space). This means that they may not contain the \TeX\ macro \bs\ (backslash-space). If you should want to enter a type-1 (note-based) string longer than 80 characters, you could use a series of type-2 or -3 strings to define a \TeX\ macro containing the desired commands. Type-2 or -3 strings are also restricted to 80 characters, but you can enter several in a sequence on consecutive lines, and they will stay in the same sequence in the {\tt .tex} file. \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) (perversity or absentmindedness is why 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 prints 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. 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}. 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 for some reason 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 conjunction with {\tt \%1} (see section~\ref{scor2prt}, page~\pageref{scor2prt}) if you want to make a separate bass part with no figures. \subsection{Global \TeX ~Modifications} \PMX provides the option of entering an unlimited set of any legitimate \TeX ~commands just before \bs{\tt startmuflex}, and before any Type 2 literal \TeX ~strings. Simply create a text file named [{\it basename}]{\tt .mod} with the commands and place it 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 literal \TeX ~strings already described in section~\ref{LitTeX} on page~\pageref{LitTeX}. \setcounter{secnumdepth}1 \section{Making Parts from a Score} \label{scor2prt} This is accomplished by running {\bfx scor2prt} and entering the basename when prompted. {\bfx Scor2prt} will create {\tt noinst} separate {\tt .pmx} files, one for each instrument, with names [{\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 at line 15 and a page break at 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}. 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). One function of {\bfx scor2prt} is to condense consecutive bars of rest into a single symbol, a heavy horizontal bar with a number above it. The symbol {\tt rm} defines such a {\bf m}ulti-bar rest as described in section 2.2. {\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 judicious combinations of literal \TeX ~ commands and the special \PMX commands listed in this section, it is possible to store 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. \section{Closing Notes} \subsection{About the Example Files} {\tt mostpmx.pmx} contains examples of most of the \PMX commands. The printed output displays the \PMX commands next 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; it could be hazardous. {\tt barsanti.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 jhrtsg.pmx} is a trio sonata by Johan Helmich Roman (1694-1758), ``the Swedish Handel''. This score demonstrates some tricks used to transition between the first and second movement (perhaps soon to be incorporated in \PMX). It also has many examples of controlling the appearance of the parts with commands in the score. {\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 {\it 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} The main home of \PMX on the internet is {\tt ftp.gmd.de/music/musixtex/software/pmx}, or point a web browser to {\tt ftp://ftp.gmd.de} and follow the links. \PMX files on this server are supposed to propagate to the CTAN sites at {\tt ftp.tex.ac.uk} and {\tt ftp.dante.de}. The alleged American CTAN mirror at {\tt ftp.shsu.edu} seems to be very unreliable. The following site may be a useful alternative: {\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 ore not yet available. 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 \PMX into C and prepared a distribution which should be compatible with most UNIX systems. A beta version of \PMX 1.1 is located at\\ {\tt ftp://ftp.mathematik.uni-stuttgart.de/pub/software/pmx/}. Johan Tufvesson has posted binaries for Amiga, Sun Solaris, and Linux at\\ {\tt http://www.lysator.liu.se/~tuben/pmx/} \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, and to Eric Petersen, Johan Tufvesson, and Stephan Evert for beta-testing and for porting \PMX to other platforms. Special thanks and credit go to Werner Icking for exhaustive beta testing, uncanny bug-finding, and continuing encouragement. \end{document}