User Manual

music - a troff preprocessor for printing music scores

User Manual

Eric Foxley

Departments of Mathematics and Computer Science

University of Nottingham
Nottingham NG7 2RD, UK
ef @


The music preprocessor provides a language for describing music scores, which can then be processed to produce output suitable for the troff typesetting system and its other preprocessors, which run under the .UX operating system. This document describes the basic facilities available in the music preprocessor, and gives examples of its use.


1. Introduction

The output

was created from an input file containing

The music system is another troff [ref 1] [content] [ref 2] [content] preprocessor. It passes most of its input through untouched, but translates data between lines ".MS" and ".ME" into commands suitable for the pic [ref 3] [content] [ref 4] [content] preprocessor, which can then draw the necessary pictures. Text outside and inside the music system can use the full features of the other troff preprocessors such as eqn [ref 5] [content] and tbl [ref 6] [content] if required. A typical .UX command would then be


if the facilities of eqn are required.

The particular rules for layout of the musical symbols are based on examples given in Stone [ref 7] [content] and in the Oxford Concise Dictionary of Music [ref 8] [content] subject to interpretation and variation. Suggestions for alternative rules would be appreciated, and could perhaps be built into the system as options. For a more general discussion in this area, the reader is referred to the paper by John Gourlay [ref 9] [content] for discussion of languages for representing music scores, and to the annual report from CCARH [ref 10] [content] for information on the current state of computer applications in music printing and in general musicology.

2. The input language

The basic input for the musical score is contained between lines ".MS" and ".ME", and consists of header information describing the output format required, and input defaults, followed by the score details. All text not within a ".MS" to ".ME" section is passed straight through unchanged.

2.1. Header information

The header sets up variables such as the piece title, output width, time signature and key, each of which is specified by an entry of the form

The header items are separated by semi-colons, and terminated by a full-stop. A typical header for a straightforward example might be

In all straightforward cases a short header is acceptable, since most items default to sensible values. However, the header items have to allow for many variations in output format, and examples of the major possibilities are shown in the following example:


Time signature



Number of bars



The header items are in any order, separated by semi-colons; the last is terminated by a full stop. The defaults are set in a file called "mus_default", of which details are given in section 5. All unspecified items default from any previous header. An empty header is indicated by a full stop. Further header items will be described later.

Note that all text from any "#" symbol to end-of-line is ignored, and that if the last character of a line is the escape character "\", then the next line is treated as a continuation of the current line.

2.2. Score details

The header is terminated by a full stop, and is followed by the score. The score consists of notes interspersed with bar-lines. There is a warning if the sum of the note lengths in any bar does not add up to the required bar length as deduced from the time signature, or if the total number of bars does not agree with that specified in the header. Both of these checks have been found to be useful.

The pitches of the notes are typed as lower-case letters relative to the current key, as in

Sharps and flats of the current key are omitted. Other required accidentals are typed at the first occurrence in the bar using "+" for sharp, "\-" for flat, and "=" for natural. For example, "g+" represents g-sharp, "e\-" represents e-flat, and "f=" represents f-natural in a key such as D. A "+" symbol against an already sharpened note is ignored; a "+" symbol against a note which is sharp in this key, but which occurred with a natural earlier in the bar, cancels the natural accidental. For double sharp, use two plus symbols, as in "g++", and for double flat two minus symbols as in "g\- \-". On output, the computer will print only the necessary accidentals, omitting, for example, accidental signs on all but the first occurrence of a given accidental within a bar. A cancelling accidental will be printed if the note is used in the following bar.

The length of a note defaults to the value indicated by the denominator of the time signature, and is thus a quaver if the denominator is 8, a crochet if it is 4, and so on. To specify other lengths, symbols ">" after the note double its length, symbols "<" halve it, "." increases it by 50%, and ".." increases it by 75%. Thus in 4/4 time, "c>." represents a dotted minim, and in 6/8 time "c<<" represents a demi-semi-quaver. As an example, the source

produces the output

The length of the default note for input may be changed by using these note duration symbols in association with the note given as the key in the header. Thus if the key is specified as "d>", the key is D, and the default note length is double that which would otherwise be expected. If the above example is repeated changing two header entries to halve both the bar-length and the default note-length, the file becomes

and the resulting output is

For this effect, the key must be set after the time signature in the header, since the "timesig" entry itself resets the default note-length. The full-stop cannot be used to increase the default note-length by 50%, the default can be changed only by factors of 2.

For each note in the source, the letter (and possible accidental) specifying the pitch can be followed by an indication of octave displacement. Symbols "\(ua" after the pitch indicate an octave upward, symbols "\(da" indicate an octave down*.

* At Nottingham the \(ua symbol is typed as the circumflex symbol "^", and the \(da symbol as the small letter "v". The particular character is a compile-time definition.
The default octave can be set in different ways. It can be set to that from middle C to the B above using the header entry

In this case "c\(ua\(ua" is two octaves above middle C, and "b\(da" is one note below middle C. Thus in the key of G, the score

produces the output

The octave symbols(s) must at present precede the note duration symbol(s). The default octave can be moved up or down an octave by appending "\(ua" or "\(da" symbols to the note in the key definition in the header. The previous example, if the default key is specified as

we obtain the output

The header entry

sets the default octave to that contained within the treble clef stave, from F above middle C to the E above that. The header entry

sets the default octave to that contained within the bass clef stave, from the A an octave and a half below middle C to the G below middle C. The header entry

sets the default octave to be that starting at the current key note. The entry

causes the default octave to be that starting from middle C. The entry

causes the octave of each note to be chosen to make its pitch as close as possible to that of the previous note. Thus in this mode the notes

would give a run up and down an octave scale. In this mode, the very first note is set according to the "octave = s" rule. Note that although this option in general minimises the typing of input, it has the unfortunate side effect that octave errors now propogate throughout the rest of the piece.


Bars are delimited by bar-lines. A limited variety of bar-lines is available, some indicated by an obvious construction, others by a letter following the bar symbol. A selection of these is indicated by

which produces

Note that the system is sufficiently intelligent to replace for example the ":|:" symbol if it occurs at the end of a stave by a ":|" symbol at the end of that stave, and a "|:" symbol at the beginning of the next stave.


Rests are indicated by the underscore symbol "_", with lengths specified as for notes using the symbols ">", "<" and ".". The default length is the same as the value set for notes. The input

gives the output

Full bar rest symbols are centred in the bar; part bar rests are positioned proportionally as for notes.


To cause notes shorter than crochets to be joined under a common beam, the notes to be joined are put within square brackets, as in

A beam will correctly fail if it includes any notes longer than or equal to a crochet; at the moment, it also fails if it includes any rests. The latter restriction should be removed soon. A beam cannot cross a bar-line. As an example of beams, the source

appears as

To simplify the typing of input in straightforward cases, a system for automatically inserting beams is available, and can be invoked by inserting the additional line

in the music heading. The automatic beaming uses rules from the Oxford Concise Dictionary of Music [ref 11] [content] which may not always be exactly what is required. The description given there has been interpreted as meaning that beams will not normally cross the divisions of a bar as given by the denominator of the time signature in simple time, and a quarter of that figure in compound time. Thus in 2/2 or 6/8 time, beams will not cross the midpoint of the bar, while in 3/4 or 9/8 they will not cross the one-third points.

Automatically generated beams will never over-ride beams inserted manually. Having been invoked, auto-beaming can be switched off by the header

As a further facility, the auto-beamer can be instructed never to let a beam cross for example a "2 times default note-length" interval using

to allow half-bars to be beamed in 4/4 time.

Different formulae for the slope of the beam are built into the program; formula number 2 can be accessed by the header entry

Details are the formulae are available from the author. Other formulae could easily be added; suggestions are welcome.


Ties are indicated by putting parentheses (round brackets) around the notes to be joined under the tie. Their production is through the use of splines in pic; an angular version is available if splines are not provided. The system decides on details of the exact position of the tie; improvements to allow more detailed user specification await decisions on a clean syntax. The input


See the appendix at the end of this document for further examples. The header entry

causes ties to be above the notes;

sets them below the notes.

Grouped notes

Notes to be joined together on a single stick are grouped by curly braces. If a number of groups are to be beamed, the sequence of symbols is as in

The input


There can be any number of notes in a group, and they can be given in any order; they must all be of the same length. If the lengths differ, the length of the first is taken as the length of all of them.


The title of the piece as (and if) given with the keyword title in the header information appears at the top left corner of the output. Other titles can be given to appear at the the centre and at the top right-hand corner of the output using the keywords ctitle and rtitle in the header.

Additional items of text can be given to be positioned relative to any note or bar. For text associated with notes, the text required is contained within quotes to indicate its positioning. Single quotes (\(fmModerato\(fm) indicate text to be positioned above the stave, left justified and starting at the horizontal co-ordinate of the note; text in double quotes ("Twinkle") indicates text to be positioned below the stave; and text between "@" signs (@3@) indicates text to be positioned close to the note. Text of the last form will be positioned just above the note if it has a downward stick, and vice versa. Thus the input

generates the output

The particular string @3@ is interpreted to imply a triplet, three notes in the time of two. The spacing of the notes on the score and the checking of bar-lengths takes this into account. Full treatment of general tuples appears later in this document.

Text can also be associated with a bar. It is given after the bar-line, and is printed lined up with the start of the bar; it will be above the stave if contained in single quotes, and below if in double quotes.

Text strings starting with the escape character "\" are treated specially. Any text string starting "\ b" appears in a box, any starting "\ c" appears in a circle. and text starting "\ 1" or "\ 2" above the stave is used for alternative bars on repeats. The second type, starting "\ c", will be expected to be single character strings. For example, the file

produces the output

Text starting "\ >" is assumed to be a diminuendo; its width will stretch over two notes if written "\ > 2n", over two bars if written "\ > 2b", and over 2 inches if written "\ > 2i".

Text between @ symbols starting "\ .", "\ \-", "\ <", "\ >" is interpreted as accent symbols and positioned accordingly; see the appendix for examples.

It is hoped that most recognised musical symbols (such as pause and segno) will eventually be included in the standard system; such additional characters are then accessed by the usual methods. They may be either symbols generated as pic macros, or as additional symbols in the font. In the latter case they are accessed by methods appropriate to troff, typically being indicated either by a 2-letter code preceded by the characters "\ (", or by a change to the music font using "\ f(MU" Users of the Sonata font can now access certain specific symbols directly by the strings "\ segno", "\ pause", "\ mordant", "\ invmord" (inverted mordant), "\ turn", "\ bowup", "\ bowdown" (violin bowing symbols), "\ ped" (Pedal), "\ dc" (D..C. or da capo), "\ ds", etc. The system recognises "\ +" anywhere in text to represent the sharp symbol, "\ \-" for flat, and "\ =" for natural.

If text is given as two strings, such as

the two text strings "1. G" and "2. Em" appear one above the other, vertically aligned at the left, as in

Duplicate copies of earlier bars

The notation

cause a duplicate of bar number 4*

* This bar number must already have been entered, i.e. we must be currently positioned at bar number 5 or beyond.
to be inserted at this point. The similar notation

causes bars 1 to 3 to be duplicated at this point. Numbering starts at bar 0 for the lead-in notes, and bar 1 for the first full bar. The notation

causes a duplicate of the previous bar to be inserted (current position minus one), and

inserts copies of the preceding four bars. The notation

duplicates source from the bar two beyond the most recent which contains the text \(fmLegato\(fm to the bar four beyond it. Such a bar must occur earlier in the current ".MS" to ".ME" section. Only complete bars can be copied.

It is unwise to use absolute bar numbers in cases where an extra bar could perhaps be added or deleted at a later stage. Relative bar references (using the -4 or \(fmLegato\(fm notations) are safer in such circumstances. References to bars not yet encountered are unacceptable.

Changes of signature

The notation

occurring at the start of a bar resets the time signature, default note length and bar length on the fly to a new value, causing the new value of the time signature to be printed on the stave. The input and/or output keys can be reset similarly using, for example

to reset both input and output key, or

to reset only the output key. If such a change alters the pitch of the output key, the new key signature will be printed on the stave at that point; if it is used to change only the default note length or octave on input, no key signature is printed.

The notation

moves the source to the start of bar 25; if the specified bar number is ahead of the current bar, any intervening bars are filled with rests. If the bar number given is less than the current bar, it is assumed that a further part is being added; see multi-part music below for details.

The notation

causes the sticks of all following notes to be forced upwards until cancelled by either

to send sticks downwards, or

to leave sticks free to move in either direction.

Any of the above items can be combined as in a normal header, separated by semi-colons and terminated by a full-stop, as in

With the exception of "\ sticks =", the above notations starting with the escape character "\" are not guaranteed except when used at the start of a bar.

Controlling the number of bars on a stave

The notation

sets the current "bars-per-stave" value to the given integer. The system will attempt to fit the given number of bars onto each stave. Within one stave, as far as is possible, the physical width of the bars will be proportional to their musical length. The "bps" facility can be used to lay out varying specified numbers of bars on each stave. This can however be achieved by a further facility; following any barline, the header item

can be added.

If a group of bars finishing with an endstave is being copied, but the copied section is not required to end the stave, the entry

overrides the copied endstave.

Controlling the width

If, say, music is being printed at 8 bars per stave, but there are 4 bars left over at the end, those bars would normally be spread to fit the full width of the page. To reduce their width, use the inserted header

to terminate the last full staff. This will decrease the width of the last staff to 4.5 inches. To reset back to the original width, use

Source from a separate file

The ".MS" line can be replaced by

causing music input to be taken from the named file. The file would normally start with a ".MS" line. This enables music source to be easily tested before insertion into the main text. The line can be extended by header items terminated by a full stop. For example

will cause the music in the named file to be printed in the key of B. Any header items given on the ".MS < file" line and following the filename are read after the first heading of the file which is being read. Thus if the named file contains a piece of music which is required to be printed in several keys, or in several different layouts, this can usually be done with extra header items in this way. The use of the escape character at the end of a line enables several header items to be given, as in

which specifies a new output key, right-hand title and bars-per-stave setting. The included file may start with any text before its first ".MS" line; this text is passed straight to the output by the preprocessor.

Output key

The facility to specify the output key independently of the input key takes account of the fact that a natural in one key may become a sharp in another. A piece may be printed in a key other than that in which it is entered by using the "keyout = ..." facility in the heading of the piece. To print a particular piece in two distinct keys, first in the key in which it was input, and then in a second key, store the input

in a file, then use

to produce the first copy, and

for a second copy. This then appears as







gives a grace note "e" preceding the "d".


The notation

within a score indicates that the next 7 notes are assumed to fill the musical duration of 6 equivalent notes. Thus the full notation for a standard triplet in 4/4 time is thus

Tuples of notes shorter than a crochet are beamed; otherwise they are tied. The system recognises for example that

in even metre implies a triplet; other defaults will be built in when the rules are confirmed. Since it occurs frequently in the author's work, the entry

has been built in. The input


Output time signature as a function of input time signature

The output time signature can be made different from the input time signature in single-part pieces by using the header keyword "timeout" before the "timesig" entry. An entry

causes output notes to be twice the length of input notes, and output bars to be half the length of input bars. There would be four times as many bars in the output. The entry

would cause the same division into bars, but both note lengths and bar lengths would be halved.

Time signatures are adjusted as appropriate; the entry

converts 4/4 time to 2/2 time. The results may not always be what was anticipated.

Text omission

The header line

causes text under the stave (in double quotes) to be suppressed, text over the stave printed. The line

causes the text over the stave (in single quotes) to be suppressed, while

causes both to be printed, and

causes both to be suppressed.

Adjusting the horizontal spacing

Notes are currently spaced as far as possible in proportion to their musical length. If a bar consists of only one note per part, the notes are all centred in the bar. To cause single notes to be left justified, use the header entry

If it is required to perform minor (or major!) adjustments to the horizontal spacing within a piece, "invisible" notes can be inserted in various ways using the pitch symbol "~". The usual note duration symbols can follow this note, to give it any length. If the "~" symbol is followed by a + or \- sign, followed by optional length modification symbols, the length of such a note will be taken into account in computing the horizontal spacing of the piece, but no note will not be printed. One might thus input

to cause a slightly greater gap between the second and third notes of a set of four, or

to cause a narrower gap. The length of these notes is ignored in bar length checks.

If the + or \- sign is omitted, the invisible note becomes part of the computed bar length. If there are two parts, one of which exists for only parts of the bar, its notes can be positioned correctly in this way. With the source

the g-notes in the second part will appear under the d-notes of the first part. In this case, the length of each part including the "~" notes must add up to a correct bar length.

Cancelled Accidentals

The header entry

causes an appropriate accidental to be placed against a note which was set with an accidental in the preceding bar. The entry

cancels the effect.

Indexing items

The keyword index is used in a header entry such as

to include indexing items. The entry is completely ignored by the program.

Inter-stave gap

To increase the vertical spacing between staves, use the header entry

for an inter-stave gap of 0.25 inches. To increase in addition the gap between the combined staves in multi-staff music, use

where the first number is the spacing between groups of stave, and the second between staves in a group.

Setting defaults

The program first reads a file called "mus_default" if such a file exists. It must be a file containing only a header, of the form

and sets all defaults for the program.

PIC commands

The output of the music preprocessor is fed into the pic preprocessor. Any text string starting "\ p...." is assumed to be a PIC command. The program moves to the appropriate position (above the stave if the string is within single quotes, for example) and plants the given PIC commands. In addition, the program reads a file named "pic_default" on start-up, to enable PIC-macros to be used.

6. Further enhancements under consideration

Possible further enhancements include the following.

Avoiding the use of pic

  • Since all positioning information is available, it would be possible to give output directly in a form suitable for troff input, thus avoiding the use of pic all together. This would also avoid some of the slight positioning inaccuracies which occur due to rounding in pic.
  • An attractive further extension, now that the main output device is the Apple LaserWriter, would be to produce Postscript output directly. This would enable the program to make use of a number of Postscript features (line thickness, area fill, rotation) which are not accessible under troff.

    Varying the height of the stave

  • The positioning of the various symbols is optimised to a particular stave height. Variations in the stave height produce slight misalignment, due to both rounding errors in pic/troff, and in the point sizes of the symbols. Typical output is as follows.


    [ref 12]


    Notes converted from troff to HTML by an Eric Foxley shell script, email errors to me!