%%
%% mxserdoc.tex:  Manual for the MusiXTeX serial voices package musixser
%%
%% Copyright (C) 1999-2003  Rainer Dunker
%%
%% This document is free software; you can redistribute it and/or modify
%% it under the terms of the GNU General Public License as published by
%% the Free Software Foundation; either version 2 of the License, or
%% any later version.
%%
%% This document is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%% GNU General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with this document; if not, write to the Free Software
%% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%%
%% Author:
%%  Rainer Dunker
%%  Wachtelweg 31
%%  85591 Vaterstetten
%%  Germany
%%
%%  E-mail:  rainer.dunker@web.de
%%
\documentclass[twoside]{article}
\usepackage{musixtex}
\input musixlit
\input musixser

\textwidth210mm \advance\textwidth-2in               % These format settings
\textheight297mm \advance\textheight-2in             % can be freely changed!
\advance\textheight-\headheight \advance\textheight-\headsep
\footskip0pt \topmargin0pt \evensidemargin0pt \oddsidemargin0pt

\pagestyle{headings}
\parskip0.5ex plus 0.25ex minus 0.25ex
\parindent0pt
\sloppy

\nobarnumbers
\smallmusicsize
\startmuflex
\advance\stafftopmarg0.8em
\advance\staffbotmarg1.2em

\def\musixser{{\tt musixser}}
\def\excerptskip{\advance\stafftopmarg0.8em \advance\staffbotmarg1.2em}
\def\nonterm#1{\leavevmode\hbox{$\langle$#1$\rangle$}}
\def\spacebox{{\tt\char`\ }}

\newcounter{myenumcount}
\newenvironment{myenumlist}
  {\begin{list}
     {\hss(\arabic{myenumcount})}
     {\usecounter{myenumcount}}}
  {\end{list}}
\newenvironment{code}{\begin{quote}\makeplusother}{\end{quote}}

% a trick to fool MusiXTeX into setting a curly brace left to a number
% of staves belonging to differen instruments --- according to a
% suggestion of Mthimkhulu Molekwa:
\makeatletter
 \let\origin@lwrit@staffs\writ@staffs
 \def\writ@staffs{%
   \origin@lwrit@staffs
   \ifx\br@cks\empty\else\expandafter\@bracks\br@cks\@end\fi}
 \let\br@cks\empty
 \def\curlybrackets#1{\def\br@cks{#1}}
 \def\@bracks#1#2#3\@end{%
   \noinstrum@nt=#1\s@l@ctinstr\b@zi\altitude
   \noinstrum@nt=#2\s@l@ctinstr\b@zii\altitude
   \advance\b@zii-\b@zi
   \advance\b@zii-\Interligne
   \C@Inter
   \advance\b@zii\stem@skip
   \n@v\b@zii \sp@pt\tw@ \advance\n@v\@cxxviii
   \divide\b@zii\tw@
   \advance\b@zi\b@zii
   \raise\b@zi\rlap{\kern -\instrum@in@group
		    \mxsps\char\n@v
		    \kern\instrum@in@group}%
   \ifx\empty#3\else\@bracks#3\@end\fi}
\makeatother


\begin{document}

\title{\musixser\ --- a \musixtex\ extension package for voice-wise music
       coding (version 1.2)}
\author{\copyright\ Rainer Dunker 1999--2003\\
	{\tt rainer.dunker@web.de}}
\maketitle
\thispagestyle{empty}

{\small\sl (The page layout of this document is tailored to A4 paper
 format, but the text width and height can be freely changed in order
 to meet other paper sizes; no part of the layout relies on a
 particlular size.)\/}

{\parskip0pt\tableofcontents}


\section{Introduction}


\subsection{Basic concept}

\musixser\ (``\musixtex\ SERial voices'') is a set of \TeX\ macros to be
used with Taupin \musixtex\ (version T.90 or later). It changes
\musixtex's coding style from chord or ``column'' oriented to voice
oriented. Each voice of a score (which nevertheless is allowed to
contain chords) is entered as a separate ``thread'' of musical events,
thus imposing a polyphonic flavour on music coding.

Unlike PMX or M-Tx, \musixser\ is no \musixtex\ preprocessor. It does not
make any layout decisions; it merely rearranges the input and passes
everything over to \musixtex. The main
benefits of using it --- apart from the more intuitive, polyphonic
coding --- are:
\begin{itemize}
 \item Repeated music structures (like voice-wise ostinato patterns)
   can be entered in a code-sharing manner (i.\,e.~coded once, called
   multiple times).
 \item Much easier editing: voice-wise copying and pasting,
   rearranging and excluding of single or multiple staves and voices.
 \item There's no built-in limit on the number of voices per staff;
   the polyphony of arrangements can be arbitrarily complicated.
\end{itemize}


\subsection{Who should use \musixser?}

Unlike \musixtex\ preprocessors, \musixser\ does not
save you from learning the \musixtex\ input language; it's opposite
--- being familiar with using \musixtex\ is a precondition for
starting with \musixser. You should in no way expect \musixser\ to
provide an ``easy start'' into music typesetting with \musixtex.

\musixtex\ novices will thus not benefit from \musixser; it is
intended for experienced \musixtex\ users who desire to see the
polyphonic structure of their music reflected in their music
coding language.


\subsection{New in this version}

\begin{itemize}
 \item Abbreviated coding of various types of repeated material using
   ``for each'' loops; see sections~\ref{foreachloops}
   and~\ref{looppatterns}.
 \item Patterns can be called using a shorthand syntax
   (\verb|+p|~header; see section~\ref{fixpatterns}).
 \item The \verb|\processbar| command helps typesetting bar-related
   material (like full-bar rests) within the last bar of a piece or
   section; see section~\ref{fullbarrests}).
 \item The plus sign is no longer an active character; it can now be
   used literally in voice material (see
   section~\ref{setupavoicesection}).
 \item The \musixser\ version is identified by the predefined macro
   \verb|\musixserversion|, enabling other \TeX\ code to check for
   version compatibility (according to a suggestion by Dirk Laurie).
\end{itemize}

The following topics are still to be done:
\begin{itemize}
 \item Support of multi-staff instruments.
\end{itemize}

Suggestions for other useful things are welcome.


\subsection{Restrictions and limitations}

\begin{itemize}
 \item \musixser\ allocates one of \TeX's token list registers per
   voice. If you use other packages which heavily use those registers,
   the possible number of voices may get seriously limited;
   nevertheless, I do not consider this to be likely during practical
   use.
 \item \musixser\ does not support multi-staff instruments, i.\,e.~all
   staves of such an instrument must be handled as (in \musixtex\ terms)
   separate one-staff instruments.
\end{itemize}


\section{Installation}

Put the {\tt musixser.tex} file into a directory that is included in
your TEXINPUTS search path --- that's all. (Refer to your local \TeX\
documentation for details on this.)


\section{Entering music}

Before using \musixser\ macros, state
\begin{code}\verb|\input musixser|\end{code}
near the beginning of your source file but {\bf after} the
\verb|\input musixtex| (\LaTeX: \verb|\usepackage{musixtex}|)
command.

If you are combining \musixser\ with the lyrics macro package {\tt
musixlyr}, the \verb|\input musixser| statement must precede the
\verb|\input musixlyr| statement!


\subsection{Voices as ``threads'' of music events}

A {\it voice\/} in the sense of \musixser\ has the following properties:

\begin{myenumlist}
 \item It is restricted to be notated within only one staff, i.\,e.~it
  must not jump between staves.
 \item It may contain chords.
 \item\label{homophonicprop} It is inherently homophonic, i.\,e.~it
  consists of one unique rhythmic sequence; no multiple notes with
  different starting points and/or durations are allowed to occur
  simultaneously.
 \item\label{partemptyprop} It does not need to be filled completely
   with notes or rests, but may be partially empty.
\end{myenumlist}

According to these rules, the following example (taken from a
well-known french Christmas song) consists of three voices:

\begin{music}
 \excerptskip
 \instrumentnumber2
 \songtop2 \songbottom1
 \generalsignature1
 \generalmeter\meterC
 %
 \setvoice21
   {% bars 1-3
    +b \wh n+b \wh k+b \wh k%
    % bar 4
    +2 \itieu2k\hl k+8 \ttie2\ibl2k{-1}\qb2k+8 \qb2j+8 \qb2i+8 \tqb2h}
 \setvoice12
   {% bar 1
    +2 \zh i\hu k%
    +8 \ibu1j{-1}\zq j\qb1l+8 \zq i\qb1k+8 \zq h\qb1j+8 \zq g\tqh1i%
    % bar 2
    +2 \zh h\hu j%
    +8 \ibu1i{-1}\zq i\qb1k+8 \zq h\qb1j+8 \zq g\qb1i+8 \zq f\tqh1h%
    % bar 3
    +2 \zh g\hu i%
    +8 \ibu1h{-1}\zq h\qb1j+8 \zq g\qb1i+8 \zq f\qb1h+8 \zq e\tqh1g%
    % bar 4
    +3/8 \zqp f\qup h+8 \cu f+2 \hu d}
 \setvoice11
   {% bar 1
    +4 \lower6\internote\qp+4 \itied1g\ql g+2 \ttie1\itied1g\hl g%
    % bar 2
    +4 \roff{\ttie1\ql g}+3/4 \itied1d\hlp d%
    % bar 3
    +4 \ttie1\ql d+3/4 \hlp N%
    % bar 4
    +3/8 \qlp d+8 \cl d+2 \hl d}
 \barduration{4/4}
 %
 \startextract \processvoices \endextract
\end{music}

Property~(\ref{homophonicprop}) stated above implies that, in bar~2 of
the following example, two voices must be used:

\begin{music}
 \excerptskip
 \barnumbers
 \barduration1
 \generalsignature{-1}
 \generalmeter\meterC
 \setvoice11{+2 \zh f\hu h+2 \zh f\hu h+3/4 \hup g+4 \qu f+1 \wh f}
 \setvoice12{+b +2 \roff{\hl f}+2 \hl e}
 \startextract \processvoices \endextract
\end{music}

However, according to property~(\ref{partemptyprop}) mentioned above,
the second voice does not need to be filled with anything like
``invisible rests'' in the other bars.

Note that the number of voices does not depend on the number
of staves: Any number of voices (including none) can be set
on each staff.


\subsection{Setting up a voice}
\label{setupavoicesection}

A voice is set up with the command:
\begin{code}
 \verb|\setvoice|\nonterm{staff no}\nonterm{voice no}%
 \verb|{|\nonterm{material}\verb|}|
\end{code}

\nonterm{staff no} is the number of the staff (or, in \musixtex\
terminology, the instrument) the voice will be typeset
in. \nonterm{voice no} is the number of the voice within the staff;
all voices of a staff must be enumerated beginning from~1. (The order
of voice definitions, however, does not matter, but after having
defined all voices, the sequence of voice numbers must be contiguous
for each staff.) If \nonterm{staff no} or \nonterm{voice no} consists
of more than one digit, you have to enclose it in
braces~(\verb|{|\nonterm{voice no}\verb|}|).

\nonterm{material} consists of a sequence of ``musical events'', each of
them of the following syntax:
\begin{code}
 \verb|+|\,\nonterm{duration}\spacebox\nonterm{contents}
\end{code}

The plus sign must be entered literally; it is simply a separator which
marks the beginning of an event. \nonterm{duration} is explained below;
it must be followed by a literal space character or, alternatively, by
a line break. \nonterm{contents} is exactly what you would type within a
\verb|\notes|\dots\verb|\enotes| construct of plain \musixtex\ --- but
with an important restiction: You may not specify multiple spacing
notes or pauses or whatever; i.\,e.~it is impossible to give a whole
sequence of spacing notes in a single command, e.\,g.~\verb|\qu{cdefg}|
(for the purpose of abbreviation, \musixser\ provides several
alternative, powerful constructs; see
section~\ref{recurringstructures} for more information).

Another, minor restriction about the \nonterm{contents}: It must not
contain a literal `+' sign, since \musixser\ would interpret it as the
beginning of the next event. If you need to include a literal plus
sign in the \nonterm{contents}, hide it from \musixser's event parsing
by enclosing it in braces:~\verb|{+}|.

The \nonterm{duration} element determines the time consumption of the event,
i.\,e.~the time elapsing until the voice's next event will happen. It
may have one of several formats:

\begin{myenumlist}
 \item\label{NumerDenom}
   \begin{code}\nonterm{numer}\verb|/|\nonterm{denom}\end{code}
   This format represents a fraction of a whole note, as usual; for
   example, \verb|3/4|~means the duration of a dotted half note.
 \item
   \begin{code}\nonterm{denom}\end{code}
   As an abbreviation of~(\ref{NumerDenom}), omitting the numerator
   means setting it to one; i.\,e.~\verb|4|~just means the duration of a
   quarter note.
 \item\label{barsB}
   \begin{code}\nonterm{bars}\verb|b|\end{code}
   This means that the following event shall occur after \nonterm{bars}
   completed bars. In combination with the full bar rests feature
   (see below), this is a convenient way to express long ``tacet''s
   of a voice. The \nonterm{bars} amount, however, is not interpreted as a
   multiple of the bar duration (which would imply that if the
   current event occurs, say, on the 2$^{\rm nd}$~beat of a bar, the
   following event would do also). Instead, it is the number of
   barlines that have to be ``crossed'' --- independent from the
   current event's position within the current bar. The following
   event will then occur on the first beat after the specified
   number of bars.
 \item
   \begin{code}\verb|b|\end{code}
   Corresponding to format~(\ref{barsB}), omitting \nonterm{bars}
   means setting it to one, i.\,e.~the following event will occur on the
   first beat of the immediately following bar.
 \item
   \begin{code}
     \nonterm{bars}\verb|b|\nonterm{numer}\verb|/|\nonterm{denom}
   \end{code}
   \dots\ which means: Wait for the completion of \nonterm{bars} bars as
   in~(\ref{barsB}), then count the specified fraction as
   in~(\ref{NumerDenom}). You can again omit \nonterm{bars} and/or
   \nonterm{numer}\verb|/|\,.
\end{myenumlist}


\subsection{Processing voice material}

The \verb|\setvoice| command introduced in~\ref{setupavoicesection}
only collects and buffers musical material; it does not perform the
typesetting process. Instead, this is done by the command
\begin{code}\verb|\processvoices|\end{code}
which assembles all material given in previous \verb|\setvoice| calls
to a \musixtex\ input stream. However, it does not add any kind
of preamble or postamble elements; everything it outputs is valid only
within some \verb|\startpiece...\endpiece| or similar command
pair. Thus, a typical embedding of \verb|\setvoice| and
\verb|\processvoices| in a \musixtex\ source file is:
\begin{code}
 \nonterm{preamble commands, such as
   {\tt\char92 instrumentnumber}{\it n\/}}\\[1ex]
 \verb|\setvoice11{|\nonterm{material for instrument 1, voice 1}\verb|}|\\
 \verb|...|\\
 \verb|\setvoice|$nm$\verb|{|\nonterm{material for instrument {\it n\/}, voice {\it m\/}}\verb|}|\\[1ex]
 \verb|\startpiece \processvoices \Endpiece|\\
 \verb|\end|
\end{code}


\subsection{Full bar rests}
\label{fullbarrests}

Corresponding to \musixtex's \verb|\atnextbar| feature, \musixser\
provides a means to issue material which has to be processed at the
next barline. Before this can be used, it has to be switched on with
the
\begin{code}\verb|\barproctrue|\end{code}
command in the score preamble (just for performance reasons in case you
don't need it). After that, there are several possibilities:

\begin{code}\verb|\onebarproc{|\dots\verb|}|\end{code}
means that the issued material will be applied only once at the next
barline (exactly as
\verb|\def\atnextbar{\znotes|\dots\verb|\en}| would do).

\begin{code}\verb|\barproc{|\dots\verb|}|\end{code}
establishes the processing of the specified material at all following
barlines until explicitly cancelled by a new \verb|\barproc| definition,
e.\,g.~\verb|\barproc{}|.

Now there are abbreviations for the most common purposes:
\begin{code}
 \begin{tabular}{@{}l@{\qquad}l@{}}
   \verb|\onepause| & just one full bar rest \\
   \verb|\pauseon|  & turn on full bar rests for all following bars \\
   \verb|\pauseoff| & switch off full bar rests again
 \end{tabular}
\end{code}

As an example, here's how to typeset a single raised full bar rest:
\begin{code}
  \verb|\onebarproc{\centerbar{\raise2\internote\pause}}|
\end{code}

If the last bar of the material feeded to a \verb|\processvoices| call
happens to contain some of the mentioned bar-related stuff
(e.\,g.~\verb|\onepause|), you will not see it in the output because
\verb|\processvoices| will {\it not\/} close this last bar by invoking
\verb|\bar| or any related command (to avoid complications when a
bar-setting command like \verb|\endpiece| follows immediately). In
this case, append the \musixser\ command
\begin{code}
 \verb|\processbar|
\end{code}
to \verb|\processvoices|; this will make the pending bar-related
material appear when the next barline is processed by \musixtex.


\subsection{Specifying bars}
\label{barssection}

Bars are set automatically. You only have to specify the bar duration
as a fraction of a whole note (see above) with the \verb|\barduration|
command; for example

\begin{code}\verb|\barduration{3/4}|\end{code}

does exactly what you would expect.

Voice events (notes or rests) need not fit in a single bar with their
whole duration; instead, they are allowed to extend across bars. This
may seem to be a missed chance for a rhythm consistency check, but it
enables typesetting notes tied across bars in a baroque flavour:

\begin{music}
 \excerptskip
 \instrumentnumber2 \songtop2 \songbottom1
 \interbarrules
 \generalmeter\allabreve
 \barduration{2/2}
 \setvoice21{+2 \ha g+1 \wh g+2 \ha g}
 \setvoice11{+2 \ha c+2 \ha c+2 \ha c+2 \ha c}
 \startextract \processvoices \endextract
\end{music}

This example has been set up using:
\begin{code}
 \verb|\barduration{2/2}|\\
 \verb|\setvoice21{+2 \ha g+1 \wh g+2 \ha g}|\\
 \verb|\setvoice11{+2 \ha c+2 \ha c+2 \ha c+2 \ha c}|
\end{code}

You can perform meter changes by re-issuing the command within the
master track; see~\ref{mastertracksection}. For barless music, just
omit any \verb|\barduration| command. To switch back to barless music
after having chosen some bar duration, set the bar duration to zero,
e.\,g.~with \verb|\barduration{0/1}|.

You can influence what happens when a new bar is about to be set with
the \verb|\barlinecmd| parameter. This is set by default to equal
\verb|\bar|, but you can specify arbitrary \TeX\ code instead. For
example, if you want to force a system break after every third bar,
you may specify:
\begin{code}
 \begin{verbatim}
  \newcount\mybarcount
  \barlinecmd={\advance\mybarcount by 1
               \ifnum \mybarcount = 3 \alaligne \mybarcount = 0
               \else \bar \fi}\end{verbatim}
\end{code}

For similar purposes, you may also evaluate \musixtex's \verb|\barno|
counter.


\subsection{Specifying the duration-to-space mapping}
\label{durationspacemapping}

\musixser\ has to translate event durations into horizontal
spacing. To accomplish this, it first converts the fractional
representation of time values into kind of atomic
``tics''. Corresponding to the MIDI file format, a tic is the underlying
duration unit, and all representable durations are multiples of a
tic. In \musixser, a whole note is defined to equal 192~tics. Thus, a
half note equals 96~tics, a quarter note 48~tics, and so on.

As a second step, numbers of tics are mapped onto the \musixtex\
\verb|\notes| commands, i.\,e.~\verb|\notes|, \verb|\Notes|,
\verb|\NOtes|,~etc. This mapping has to be established by means of the
\verb|\setticsskip| command. For example,

\begin{code}\verb|\setticsskip{48}\NOtes|\end{code}
defines that an event duration of 48~tics (i.\,e.~a~quarter note) shall
correspond to a horizontal space expressed by the \verb|\NOtes| command.

\musixser\ itself predefines a small number of such relations,
following the recommendation of the \musixtex\ manual concerning the
use of the various \verb|\notes| commands. However, if your piece
contains unusual note durations, you'll have to add your own
mappings. This is indicated by the \TeX\ error message:
\begin{code}
 \verb|! No column skip for <number> tics defined; using default spacing.|
\end{code}

If you encounter this during \TeX ing your source, you'll have to
provide a \verb|\setticsskip| call concerning the given
\verb|<number>| of tics within your piece's preamble.

You may also use \verb|\setticsskip| to redefine the standard mapping of
\musixser. 


\subsection{The master track}
\label{mastertracksection}

All material you provide as an argument to \verb|\setvoice| will be
poured into some \verb|\notes...\enotes| construct during
processing. Everything that has to be given outside of a \verb|\notes|
group (e.\,g.~\verb|\hardspace| or \verb|\scale|) has to be placed on a
{\it master track\/} (in analogy to the standard MIDI file format) by
means of the command:
\begin{code}\verb|\setmaster{|\nonterm{material}\verb|}|\end{code}

While the context of evaluating \nonterm{material} differs, the
\nonterm{material} syntax is exactly the same as for the
\verb|\setvoice| command (see~\ref{setupavoicesection}). For example:
If the third bar should be typeset double as wide as the others, you
may use:
\begin{code}\verb|\setmaster{+2b +b \scale{2}+b \scale{1}}|\end{code}

Explanation: The first event is empty and has the effect of just
skipping over the first two bars. The \verb|\scale{2}| event has the
``duration'' of one bar which in this context means that the following
event \verb|\scale{1}| occurs at the beginning of the first following
bar. The duration of the very last event of the master track never has
any significance; it is safe to set it to~\verb|b|.


\subsubsection{Synchronization of master track and voices}

If a master track event and one or more voice events occur together on
the same beat, the master track event becomes processed first. Layout
changes issued on the master track thus are effective already for the
notes occurring on the same beat.

An example for the tight relationship between a master track event and
a specific note event is hard space inserted before a note in order to
make room for accidentals:

\begin{music}
 \excerptskip
 \barduration{0/1}
 \generalsignature{-1}
 \setvoice11
  {+8 \ibu0j0\zq f\rq g\zq i\qb0k%
   +8 \zq f\rq g\zq i\qb0k%
   +8 \loff{\na i}\loffset2{\sh f}\loffset3{\sh g}\zq f\rq g\zq i\qb0{^k}%
   +8 \zq f\rq g\zq i\tqh0k%
  }
 \setmaster{+2/8 \relax            % skip over first two chords
	    +8 \hardspace{6.5mm}}  % add space before third chord
 \startextract \processvoices \endextract
\end{music}

Here, the master track was set up as follows:
\begin{code}
 \verb|\setmaster{+2/8 \relax            % skip over first two chords|\\
 \verb|           +8 \hardspace{6.5mm}}  % add space before third chord|
\end{code}


\subsubsection{Synchronization of master track and bars}

If a master track event is scheduled to occur on the first beat of a
bar (especially if the preceding event has duration~\verb|b| or~{\it
n\/}\verb|b| --- see~\ref{setupavoicesection}), the event material
becomes processed {\em before\/} the barline is set. This is
reasonable because \musixtex\ requires all modifications to the bar or
barline (meter and signature changes, voltas, repeats,~\dots) to be
issued before the \verb|\bar| (or similar) command. You can thus enter
such bar modifications on the master track and synchronize them with
the first beat of the bar to be affected. Example:

\begin{music}
 \excerptskip
 \barduration2
 \setvoice11{+4 \qa c+4 \qa d+4 \qa e+4 \qa f+4 \qa e+4 \qa d}
 \setmaster{+b \relax                     % skip over first bar
	    +b \setvolta{1.+2}%           % set volta atop second bar
	    +b \setendvoltabox\setvolta{3}% set volta atop third bar
	    +b \setendvoltabox}           % end volta atop third bar
 \startextract \processvoices \endextract
\end{music}

This is the master track setup:
\begin{code}
 \verb| \setmaster{+b \relax                     % skip over first bar|\\
 \verb|            +b \setvolta{1.+2}%           % set volta atop second bar|\\
 \verb|            +b \setendvoltabox\setvolta{3}% set volta atop third bar|\\
 \verb|            +b \setendvoltabox}           % end volta atop third bar|
\end{code}

If, instead, you want a master track event (or parts of
it) --- occurring on a bar's first beat --- to be effective {\em after\/}
the bar has been set, enclose the event material in
\verb|\afterbar{...}|. Example:

\begin{music}
 \excerptskip
 \barduration{2/8}
 \generalsignature{-1}
 \generalmeter{\meterfrac28}
 \setvoice11
  {+8 \ds+32 \hs
   +3/32 \roff{\pt f\pt g\pt i\pt k}\zq f\rq g\zq i\cccu k%
   +4 \loff{\na i}\loffset2{\sh f}\loffset3{\sh g}\zq f\rq g\zq i\qu{^k}%
  }
 \setmaster{+b \relax                        % skip over first bar
	    +8 \hardspace{1.5mm}%            % add space before barline
	       \afterbar{\hardspace{5.5mm}}} % add space behind barline
 \startextract \processvoices \endextract
\end{music}

Hard space has been inserted before and behind the barline between the
two chords:
\begin{code}
 \verb|\setmaster{+b \relax                        % skip over first bar|\\
 \verb|           +8 \hardspace{1.5mm}%            % add space before barline|\\
 \verb|              \afterbar{\hardspace{5.5mm}}} % add space behind barline|
\end{code}

Finally, you may need to affect the barline setting process itself via a
master track event; exampes include signature and meter changes where
the \verb|\bar| command must be replaced by \verb|\changecontext| (or a
related command). This can be accomplished by enclosing the material
in \verb|\thisbarcmd{...}|; material issued this way replaces the
default bar command \verb|\bar| or whichever is specified with
\verb|\barlinecmd| (see~\ref{barssection}). Example:

\begin{music}
 \excerptskip
 \barduration{2/4}
 \generalsignature{-1}
 \generalmeter{\meterfrac24}
 \setvoice11{+4 \qa c+4 \qa d%
	     +4 \qa e+4 \qa f+4 \qa g%
	     +4 \qa f+4 \qa e+4 \qa d}
 \setmaster{+b \relax                                 % skip over first bar
	    +b \thisbarcmd{\generalmeter{\meterfrac34}% set new meter
			   \barduration{3/4}%         % inform musixser about
						      % meter change
			   \changecontext}}           % print out meter change
 \startextract \processvoices \endextract
\end{music}

The master track is:
\begin{code}
 \verb|\setmaster{+b \relax                                 % skip over first bar|\\
 \verb|           +b \thisbarcmd{\generalmeter{\meterfrac34}% set new meter|\\
 \verb|                          \barduration{3/4}%         % inform musixser about|\\
 \verb|                                                     % meter change|\\
 \verb|                          \changecontext}            % print out meter change|
\end{code}

An example that combines material to be processed before, at, and
behind the barline:

\begin{music}
 \excerptskip
 \barduration{2/8}
 \generalsignature{-1}
 \generalmeter{\meterfrac28}
 \setvoice11
  {+8 \ds+32 \hs
   +3/32 \roff{\pt f\pt g\pt i\pt k}\zq f\rq g\zq i\cccu k%
   +4 \loff{\na i}\loffset2{\sh f}\loffset3{\sh g}\zh f\rh g\zh i\hu{^k}%
  }
 \setmaster{+b \relax                       % skip over first bar
	    +8 \hardspace{1.5mm}%           % add space before barline
	       \thisbarcmd{\barduration{2/4}% meter change at barline
	                   \generalmeter{\meterfrac24}%
			   \changecontext}%
	       \afterbar{\hardspace{5.5mm}}}% add space behind barline
 \startextract \processvoices \endextract
\end{music}

The master track is:
\begin{code}
 \verb|\setmaster{+b \relax                       % skip over first bar|\\
 \verb|           +8 \hardspace{1.5mm}%           % add space before barline|\\
 \verb|              \thisbarcmd{\barduration{2/4}% meter change at barline|\\
 \verb|                          \generalmeter{\meterfrac24}%|\\
 \verb|                          \changecontext}%|\\
 \verb|              \afterbar{\hardspace{5.5mm}}}% add space behind barline|
\end{code}


\subsection{Abbreviations for recurring structures}
\label{recurringstructures}

A special property of nearly all music styles is the recurrence of
musical elements (fugue themes, ostinati, accompaniment patterns ---
just to give a few examples). In polyphonic music, such recurrences
mostly happen per voice, i.\,e.~other voices may do completely
different things while a recurrence takes place.

Since \musixser's input language is voice-oriented, \musixser\ offers
a number of possibilities to abbreviate the coding of recurring
structures that occur voice-wise. (This would be impossible with plain
\musixtex\ because elements of all voices are inseparably interwoven
there.) The features provided for this are loops, patterns, and
pattern loops. The following sections provide the details for all of
them.


\subsubsection{Single-event structures}

Structure elements based on a single event (e.\,g.~chords) do not need
special \musixser\ features; they can be expressed as normal \TeX\
macros which are then used as an event's \nonterm{contents} (in the
sense of section~\ref{setupavoicesection}). Example:

\begin{music}
 \excerptskip
 \barduration{0/1}
 \def\mychord#1#2#3{\zq#1\zq#2\qu#3}
 \setvoice11{+4 \mychord ceg%
	     +4 \mychord cfh%
	     +4 \mychord dfh%
	     +4 \mychord dfi%
	     +4 \mychord egj}
 \startextract \processvoices \endextract
\end{music}

Code excerpt:
\begin{code}\begin{verbatim}
 \def\mychord#1#2#3{\zq#1\zq#2\qu#3}
 \setvoice11{+4 \mychord ceg%
             +4 \mychord cfh%
             +4 \mychord dfh%
             +4 \mychord dfi%
             +4 \mychord egj}\end{verbatim}
\end{code}


\subsubsection{``For each'' loops}
\label{foreachloops}
\label{singleeventloops}

For contiguous repetitions of similar single-event elements (notes,
chords, or rests) with the same duration, \musixser\ provides an
abbreviation syntax that establishes for-each loops over a variable
property, mostly the pitch of each note of the repetition sequence.

Consider the following melody example, taken from a German protestant hymn:

\begin{music}
 \excerptskip
 \generalsignature{-1}
 \generalmeter\meterC
 \startpiece\addspace\afterruleskip
%  \NOtes\qa{fg}\en\bar
%  \NOtes\qa{hjih}\en\bar
%  \NOtes\qa{gghg}\en\bar
%  \NOtes\qa{fgfe}\en\bar
%  \NOtes\ha{f}\en
  \barduration{1/2}%
  \setvoice11{+f4 \qa fghjihgghgfgfe+2 \ha f}%
  \setmaster{+b \relax +b \barduration{1}}%
  \processvoices
 \endpiece
\end{music}

Using ``plain'' \musixtex, you would group such sequences of notes
with equal duration in note command arguments; in the example, the
second bar would read \verb|\qa{hjih}| rather than
\verb|\qa h\qa j\qa i\qa h|. However, this abbreviation syntax cannot
be used directly together with \musixser:

\begin{code}
 \begin{verbatim}
\setvoice11{...+4 \qa{hjih}...}% This won't work!\end{verbatim}
\end{code}

Since \musixser\ believes that this event has a duration of a quarter
note, its duration tracking would be messed up by the given sequence
of four quarter notes. Correctly, you would have to code:

\begin{code}
 \begin{verbatim}
\setvoice11{...+4 \qa h+4 \qa j+4 \qa i+4 \qa h...}% This is okay\end{verbatim}
\end{code}

As a means of abbreviation, \musixser\ lets you express this sequence
of quarter notes in a {\em ``for each'' loop\/}:

\begin{code}
 \begin{verbatim}
\setvoice11{...+f4 \qa hjih...}\end{verbatim}
\end{code}

This is interpreted as: Apply the given command \verb|\qa| to each of
the pitch values \verb|h|,  \verb|i|, \verb|j|, and \verb|h|, and make
each of the resulting notes an event of duration \verb|4|.

The general syntax of this construct is:

\begin{code}
  \verb|+f|\,\nonterm{duration}\spacebox\nonterm{foreach command}\nonterm{argument 1}\nonterm{argument 2}\dots
\end{code}

The result is the same as if you would have written:

\begin{code}\verb|+|\nonterm{duration}\spacebox\nonterm{foreach command}\nonterm{argument 1}\,\verb|+|\nonterm{duration}\spacebox\nonterm{foreach command}\nonterm{argument 2}\dots\end{code}

The \nonterm{foreach command} is always executed on a single one of
the given \nonterm{argument}s, i.\,e. it should be a macro that
expects exactly one argument. Furthermore, if an \nonterm{argument}
consists of more than a single \TeX\ token, it has to be enclosed in
braces. Example:

\leavevmode\hfill
\verb|\setvoice11{+f4 \qa fgh{_i}j}|
\hfill
\begin{tabular}{l}
 \begin{music}
  %\excerptskip
  \let\extractline\empty
  \startextract
   \setvoice11{+f4 \qa fgh{_i}j}
   \processvoices
  \endextract
 \end{music}
\end{tabular}
\hfill\strut

The \nonterm{foreach command} itself may consist of more than just a
single token (mostly a macro call); if so, its elements must be
enclosed in braces, and the loop argument is always passed to the last
command element. Example:

\leavevmode\hfill
\verb|\setvoice11{+f4 {\fermataup m\qa}fghj}|
\hfill
\begin{tabular}{l}
 \begin{music}
  %\excerptskip
  \let\extractline\empty
  \startextract
   \setvoice11{+f4 {\fermataup m\qa}fghj}
   \processvoices
  \endextract
 \end{music}
\end{tabular}
\hfill\strut

In other situations, you may have to combine several \musixtex\
commands each of which requires the loop argument as its own argument.
This will mostly be the case for notes with ornaments where the
vertical ornament position follows the note pitch. In this case you
will have to write your own macro which you then use as the loop
command; this macro must take a single argument that it may pass to
the macro calls within its body. The following example demostrates
this with staccato notes; it is a bit more advanced since it makes use
of the internal \musixtex\ feature \verb|\getn@i|, needed to determine
the staccato position (above or below the note head) dependent on the
vertical position of the note head within the staff:

\vskip0.8em
\leavevmode\hfill
{\small
 \begin{tabular}{l}
  \verb|\makeatletter|\\
  \verb|\def\qast#1{\getn@i#1\relax|\\
  \verb|            \ifnum\n@i>\thr@@\upz{#1}\else\lpz{#1}\fi|\\
  \verb|            \qa{#1}}|\\
  \verb|\makeatother|\\
  \verb|...|\\
  \verb|\setvoice11{+f4 \qast fghj}|
 \end{tabular}}
\hfill
\begin{tabular}{l}
 \begin{music}
  \makeatletter
  \def\qast#1{\getn@i#1\relax
	      \ifnum\n@i>3 \upz{#1}\else\lpz{#1}\fi
	      \qa{#1}}
  \makeatother
  \let\extractline\empty
  \startextract
   \setvoice11{+f4 \qast fghj}%
   \processvoices
  \endextract
 \end{music}
\end{tabular}
\hfill\strut
\vskip1.2em

Looping over note events this way is even more powerful than
\musixtex's note sequencing feature (\`a~la~\verb|\qa{hjih}|) in that
a loop may easily span across bars. Using a loop, the hymn melody
example at the beginning of this section can be coded as a single
sequence of quarter notes:

\begin{code}\verb|\setvoice11{+f4 \qa fghjihgghgfgfe+2 \ha f}|\end{code}


\subsubsection{Patterns for multi-event structures}
\label{fixpatterns}

If the same structural element (e.\,g.~an ostinato pattern) occurs
frequently in one or several voices of your score, you can reflect
this structure property by defining a \musixser\ ``pattern'' as a
template and then calling this template wherever it occurs in a
voice.

Consider the following example of an ostinato pattern as part of a
polyphonic arrangement (taken from {\it Der schwarze Mond\/} by {\sc
Harald Genzmer}):

\begin{music}
 \excerptskip
 \instrumentnumber2 \songtop2 \songbottom1
 \setclef1\bass
 \barduration{7/4}
 \setvoice21
  {+1 \zwh{_bd}\wh f+2 \zh{bd}\hu f+4 \loffset{0.2}{\fl a}\zq{ac}\qu{_e}%
   +1 \zwh{_bd}\wh f+2 \zh{c=e}\hu g+4 \loffset{0.2}{\fl d}\zq{df}\qu{_h}%
   +2 \loffset{0.2}{\fl e}\zh{eg}\hu{_i}%
     +2 \itied0f\itied1h\itieu2j\zh{f=h}\hu j%
     +3/4 \ttie0\ttie1\ttie2\zhp{fh}\hup j}
 \defpattern\bassostinato
  {+4 \qa{_I}+4 \qa{_K}+4 \qa M+4 \qa N+4 \qa{_a}+4 \qa M+4 \qa K}
 %\setvoice11{+p\bassostinato+p\bassostinato+p\bassostinato}
 \setvoice11{+p\bassostinato,,}
 \startpiece\addspace\afterruleskip \processvoices \endpiece
\end{music}

Setting up a template for this seven-notes ostinato would require
including not only the event contents but whole event specifications
(including the event header
{\makeplusother\verb|+|\nonterm{duration}\spacebox}) of all notes in a
macro --- but this would not work. (The \verb|\setvoice| command parses
the structure of the voice material by scanning its argument for
occurrences of exactly this event header, thus it relies on event
headers being issued literally in the voice material and not buried
inside any macros.) Therefore, \musixser\ provides its own mechanism
for defining such multi-event patterns. A pattern is defined as follows:
\begin{code}
 \verb|\defpattern\|\nonterm{pattern name}\verb|{|\nonterm{material}\verb|}|
\end{code}
\verb|\|\nonterm{pattern name} is a unique name for the pattern to be
defined. \nonterm{material} can be anything that is also valid as an
argument to the \verb|\setvoice| command; it can also be a material
fragment, but should preferrably consist of a sequence of complete
event specifications.

Within a \verb|\setvoice| call, a previously defined pattern is
referenced as follows:
\begin{code}
 \verb|\setvoice|$nm$\verb|{...\pat\|\nonterm{pattern name}\verb|...}|
\end{code}
The control sequence \verb|\pat| must be entered literally and tells
\verb|\setvoice| to replace \verb|\|\nonterm{pattern name} by the material
given in the pattern's definition.

There is also a shorthand notation for calling a pattern, which is
closer to the regular event syntax:
\begin{code}
 \verb|\setvoice|$nm$\verb|{...+p\|\nonterm{pattern name}\verb|...}|
\end{code}
Please note that, as opposed to a ``normal'' event header
\verb|+|\nonterm{duration}\spacebox, neither a
\nonterm{duration} nor a space character follow the header \verb|+p|;
instead, the \verb|\|\nonterm{pattern name} must follow directly.

(Using this pattern calling syntax, the pattern is bound to contain
complete events; it is not allowed to contain incomplete event
fragments. However, since patterns should always be defined that way,
this is no real restriction in practice.)

To continue the above example from {\it Der schwarze Mond\/} --- here is
how the ostinato pattern is defined and referenced:
\begin{code}\begin{verbatim}
 \defpattern\bassostinato
     {+4 \qa{_I}+4 \qa{_K}+4 \qa M+4 \qa N+4 \qa{_a}+4 \qa M+4 \qa K}
 \setvoice11{\pat\bassostinato
             \pat\bassostinato
             \pat\bassostinato}\end{verbatim}
\end{code}

Using the \verb|+p| syntax, the voice can as well be defined as:
\begin{code}
 \verb|\setvoice11{+p\bassostinato+p\bassostinato+p\bassostinato}|
\end{code}

In such a case of repeated calls to the same pattern, further
abbreviation is possible by using a pattern loop; see
section~\ref{looppatterns} for more information.


Patterns can be nested. It is well possible to define structures like:
\begin{code}
 \verb|\defpattern\a{...}|\\
 \verb|\defpattern\b{...\pat\a...}|\\
 \verb|\setvoice|$nm$\verb|{...\pat\a...\pat\b...}|
\end{code}

A pattern is not restricted to occur in only one voice at a time;
calls to it in different voices may overlay each other. This makes it
possible to typeset canons, parts of fugues, and similar structures by
defining the melody or main theme(s) only once as a pattern. Example:

\begin{music}
 \excerptskip
 \instrumentnumber3 \songtop3 \songbottom1
 \smallmusicsize
 \barduration{1}
 \barproctrue
 \defpattern\canon{+3/8 \qup c+8 \ca d+f4 \qa efgf+3/8 \qup e+8 \ca d}
 \setvoice11{+1 \onepause+p\canon+1 \wh c}
 \setvoice21{+2 \hp+p\canon+2 \itied1c\ha c+1 \ttie1\wh c}
 \setvoice31{+p\canon+1 \itied0c\wh c+1 \ttie0\wh c}
 \startextract \processvoices \endextract
\end{music}

The voices are set up as:
\begin{code}
 \verb|\defpattern\canon{+3/8 \qup c+8 \ca d+f4 \qa efgf+3/8 \qup e+8 \ca d}|\\
 \verb|\setvoice11{+1 \onepause+p\canon+1 \wh c}|\\
 \verb|\setvoice21{+2 \hp+p\canon+2 \itied1c\ha c+1 \ttie1\wh c}|\\
 \verb|\setvoice31{+p\canon+1 \itied0c\wh c+1 \ttie0\wh c}|
\end{code}


\subsubsection{Parameterized patterns for multi-event structures}
\label{parameterizedpatterns}

As discussed in section~\ref{fixpatterns}, patterns can express only
musical fragments that recur always exactly equal. A much more
interesting case, however, are recurring structures that follow a
common scheme but do {\em not\/} exactly match each other. Consider the
left-hand part of the following example (taken from {\it Suite
bergamasque\/}, 4${\rm th}$~movement ``Passepied'', by {\sc Claude
Debussy}):

\begin{music}
 \excerptskip
 \instrumentnumber2
 \setclef1\bass
 \curlybrackets{12}
 \generalsignature3
 \barduration1
 \setvoice21
  {% 1
   +4 \ust l\zq{hj}\ql l%
   +8 \ibu1i0\lpz e\zq{eh}\qb1j+8 \lpz e\zq{eh}\tqh1j%
   +4 \lpz e\zq{eh}\qu j%
   +4 \ust l\zq{hj}\ql l%
   % 2
   +4 \ust m\zq{hj}\ql m%
   +8 \ibl1i0\upz m\zq{hj}\qb1m+8 \upz n\lq i\zq j\tqb1n%
   +8 \ibl1i0\upz m\zq{hj}\qb1m+8 \upz n\lq i\zq j\tqb1n%
   +4 \ust m\zq{hj}\ql m%
   % 3
   +4 \ust l\zq{hj}\ql l%
   +8 \ibu1i0\lpz g\zq g\rq h\qb1j+8 \lpz g\zq g\rq h\tqh1j%
   +4 \lpz f\zq{fh}\qu j%
   +4 \lpz e\zq e\rq f\qu h%
   % 4
   +1 \lsf d\zwh{dfh}\wh j%
  }
 \defpattern
   {\lefthand #1#2#3#4#5#6#7#8}
   % Arguments:
   % #1:   beam position ('u' or 'l')
   % #2:   1st beam's start pitch
   % #3:   2nd beam's start pitch
   % #4-7: note pitches
   {+8 \if #1u\ibu0#22\else\ibl0#22\fi \qb0{#4}%
    +8 \csong{#8}\qb0{#5}%
    +8 \qb0{#6}%
    +8 \if #1u\tbu0\else\tbl0\fi \qb0{#7}%
    +8 \if #1u\ibu0#3{-2}\else\ibl0#3{-2}\fi \qb0{#7}%
    +8 \qb0{#6}%
    +8 \qb0{#5}%
    +8 \if #1u\tbu0\else\tbl0\fi \qb0{#4}%
   }
% \setvoice11
%   {\pat{\lefthand lJLHLac}%
%    \pat{\lefthand lHJFJMc}%
%    \pat{\lefthand lJLHLac}%
%    \pat{\lefthand uJLDHKM}%
%   }
% \setvoice11
%   {+p\lefthand lJLHLac+p\lefthand lHJFJMc%
%    +p\lefthand lJLHLac+p\lefthand uJLDHKM%
%   }
 \setvoice11
   {+p\lefthand lJLHLac,lHJFJMc,lJLHLac,uJLDHKM}
 \setvoice22               % mid-system dynamic signs
   {+2b4 \csong\mp
    +5/8 \zsong\icresc
    +8 \roff{\csong\tcresc}%
    +1 \csong{\lower\internote\hbox{\sF}}}
 \advance\interinstrument4\internote
 \barproctrue
 \startpiece\addspace\afterruleskip \processvoices \endpiece
\end{music}

The form element underlying all four bars can easily be recognized
although the concrete note pitches differ from one bar to the
other. \musixser's solution for this kind of structure abstraction are
parameterized patterns: The common structure is defined once as a
pattern, the differences between the structure ``instances'' are given
as arguments to individual pattern calls.

The syntax of a parameterized pattern definition resembles the one of
a \TeX\ macro definition with arguments:
\begin{code}
 \verb|\defpattern{\|\nonterm{pattern name}\nonterm{parameter text}%
 \verb|}{|\nonterm{material}\verb|}|
\end{code}

\nonterm{parameter text} is meant here exactly as in {\sl The \TeX
book\/}, i.\,e.~a formal description of the arguments that the pattern
expects to find when it is called; this is usually an enumeration of the
number of parameters --- i.\,e.~\verb|#1#2...| --- but can as well be
arbitrarily sophisticated (as described in {\sl The \TeX
book\/}). \nonterm{material} is again the replacement text for
\verb|\|\nonterm{pattern name}, but in this case it is allowed to
contain references to the parameters mentioned in \nonterm{parameter
text}, i.\,e.~\verb|#1|, \verb|#2|, and so on.

The syntax for a parameterized pattern call is:
\begin{code}
 \verb|\setvoice|$nm$\verb|{...\pat{\|\nonterm{pattern name}%
 \nonterm{arguments}\verb|}...}|
\end{code}

The \verb|+p| syntax can also be used, and it is even more convenient
because the \verb|\|\nonterm{pattern name} and the \nonterm{arguments}
need not be enclosed in braces:
\begin{code}
 \verb|\setvoice|$nm$\verb|{...+p\|\nonterm{pattern name}%
 \nonterm{arguments}\verb|...}|
\end{code}

%Note that the \verb|\|\nonterm{pattern name}\nonterm{arguments}
%construct must be enclosed in braces.
In both cases, \nonterm{arguments} must of course match the
\nonterm{parameter text} of the \verb|\|\nonterm{pattern name}
definition. Furthermore, the \nonterm{arguments} must not contain
literal commas (the reason will be explained in
section~\ref{looppatterns}); if you have to use a comma as a
pattern call argument, enclose it in braces:~\verb|{,}|.

Back to the above example: The structure common to all four bars of
the left-hand part is two groups of four beamed eighth notes each, the
notes pitches mirroring each other, and fixed beam slopes of 1 or $-1$,
respectively. The variable elements are the four different notes
pitches, the starting pitches of the two beams, and the beam position
(upper or lower). This leads to the following definition of a one-bar
pattern:
\begin{code}
 \begin{verbatim}
\defpattern{\lefthand #1#2#3#4#5#6#7}
  % Arguments:
  % #1:   beam position ('u' or 'l')
  % #2:   1st beam's start pitch
  % #3:   2nd beam's start pitch
  % #4-7: note pitches
  {+8 \if #1u\ibu0#22\else\ibl0#22\fi \qb0{#4}%       1st beam group
   +8 \qb0{#5}%
   +8 \qb0{#6}%
   +8 \if #1u\tbu0\else\tbl0\fi \qb0{#7}%
   +8 \if #1u\ibu0#3{-2}\else\ibl0#3{-2}\fi \qb0{#7}% 2nd beam group
   +8 \qb0{#6}%
   +8 \qb0{#5}%
   +8 \if #1u\tbu0\else\tbl0\fi \qb0{#4}%
  }\end{verbatim}
\end{code}

After this, the setup of the left-hand voice merely consists of four
pattern calls:
\begin{code}
 \begin{verbatim}
\setvoice11{\pat{\lefthand lJLHLac}%
            \pat{\lefthand lHJFJMc}%
            \pat{\lefthand lJLHLac}%
            \pat{\lefthand uJLDHKM}}\end{verbatim}
\end{code}

For comparison, here is the same voice setup using the \verb|+p|
pattern calling syntax:
\begin{code}
 \begin{verbatim}
\setvoice11{+p\lefthand lJLHLac+p\lefthand lHJFJMc%
            +p\lefthand lJLHLac+p\lefthand uJLDHKM}\end{verbatim}
\end{code}

Looping over repeated pattern calls --- as mentioned in
section~\ref{fixpatterns} --- is also possible for parameterized
patterns like in the previous example; see again
section~\ref{looppatterns} for more information.



\subsubsection{Looping over pattern calls}
\label{looppatterns}

In addition to for-each looping over single events (see
section~\ref{singleeventloops}), \musixser\ allows to loop over
multi-event patterns as well. This is useful where patterns recur in a
contiguous sequence within a voice.

The syntax for pattern call loops is only a little generalization of
the \verb|+p| pattern call --- just provide the argument sets that
shall be looped over in a comma-separated list:
\begin{code}
 \verb|+p\|\nonterm{pattern name}\nonterm{argument set 1}\verb|,|\nonterm{argument set 2}\verb|,...,|\nonterm{argument set $n$}
\end{code}
A single pattern call is therefore nothing else than the special case
of a one-element pattern loop.

(As has already been mentioned in section~\ref{parameterizedpatterns},
literal commas can only be part of an \nonterm{argument set} if they
are enclosed in braces; otherwise, \musixser\ would interpret them as
argument set delimiters.)

For the last time, here is again how the left-hand part of the
{\it Suite bergamasque\/} example
(section~\ref{parameterizedpatterns}) can be set up, assumed that a
pattern named \verb|\lefthand| has been defined before:
\begin{code}
  \verb|\setvoice11{+p\lefthand lJLHLac,lHJFJMc,lJLHLac,uJLDHKM}|
\end{code}

Patterns without arguments can also be looped over. Although it looks
a bit peculiar, it is nothing else than specifying the number of
repetitions by giving a comma-separated list of empty argument
sets. While the bass ostinato of the {\it Der schwarze Mond\/} example
(section~\ref{fixpatterns}) consists of three pattern
calls~\dots
\begin{code}
  \verb|\setvoice11{+p\bassostinato+p\bassostinato+p\bassostinato}|
\end{code}
\dots~it can be expressed as a pattern loop with empty argument sets:
\begin{code}
  \verb|\setvoice11{+p\bassostinato,,}|
\end{code}
(It is no mistake that there are only two commas for three pattern
invocations --- the number of separators is always the number of
separated argument sets minus one.)



\subsection{Automatic slur and beam number allocation}
\label{slurandbeamnumbers}

Patterns --- as introduced in sections~\ref{fixpatterns}
and~\ref{parameterizedpatterns} --- are not restricted to being used
in one specific voice. Instead, their definitions are ``global'' and
can be referenced from any voice and even simultaneously, e.\,g.~in
order to set up unisono phrases from a single melody source. Consider
the following example (taken from {\it Carmina burana\/} by {\sc Carl
Orff}):

\begin{music}
 \excerptskip
 \instrumentnumber2
 \songtop2 \songbottom1
 \sepbarrules
 \barduration{12/4}
 \advance\interinstrument 2\internote
 \defpattern\unisono
   {% bar 1
    +4 \Isl1\ibsluru h%          % initiate "long" upper slur with
                                 % explicit relative number 1
       \isl\issluru h%           % initiate 1st "short" slur with
                                 % implicit relative number 0
       \qu h%                    % set first note
    +4 \tsl\tslur i\ql i%        % terminate 1st "short" slur; set 2nd note
    +4 \ql j+2 \hl i+4 \qu h%
    +4 \isl\isluru i\ql i%
    +4 \tsl\tslur h\qu h%
    +4 \qu g+3/4 \hup h%
    % bar 2
    +4 \isl\issluru h\qu h%
    +4 \tsl\tslur i\ql i%
    +4 \ql j+4 \ql i+4 \qu h%
    +4 \isl\isluru i\Isl2\itieu i\ql i%
    +4 \Tsl2\ttie\ql i%
    +4 \tsl\tslur h\qu h%
    +4 \isl\islurd g\qu g%       % initiate last "short" slur
    +3/4 \Tsl1\tbsluru h%        % terminate last "short" slur
         \tsl\tslur h%           % terminate "long" upper slur
	 \hup h%                 % set last note
   }
 \setvoice11{\pat\unisono}
 \setvoice21{\pat\unisono}
 \startpiece\addspace\afterruleskip \processvoices \endpiece
\end{music}

In this context, the slurs cannot be specified the ``normal''
way. If you would say something like
\begin{code}
 \verb|\defpattern\unisono{...\isluru0h...}   % This|\\[1ex]
 \verb|\setvoice11{\pat\unisono}              % won't|\\
 \verb|\setvoice21{\pat\unisono}              % work!|
\end{code}
\musixser\ would include the initiation of slur number~0 in both
voices simultaneously which would result in a slur number clash; the
same applies to beam numbers.

\musixser\ helps to cope with this situation by providing ``per
voice'' slur and beam number ranges, i.\,e.~each slur/beam number
reference is relative to the voice that it has been issued in;
references to the same number issued in different voices do not
interfere with each other. Behind the scenes, \musixser\ maps those
relative slur/beam numbers onto \musixtex's absolute numbers by
automatically allocating as many numbers as are needed at each point
of time.

The syntax for slur/beam commands using automatic numbers is a bit
complicated to explain. Let's start considering the general structure of
a \musixtex\ slur command:
\begin{code}
 \nonterm{slur command}\nonterm{slur number}\nonterm{further arguments}
\end{code}
An example:
\begin{code}
 \verb|\isluru0h|
\end{code}
\dots\ where $\hbox{\nonterm{slur command}}=\verb|\isluru|$,
$\hbox{\nonterm{slur number}}=0$, and $\hbox{\nonterm{further
arguments}}=\verb|h|$.

Using automatic slur numbers, this has to be replaced by (general structure):
\begin{code}
 \nonterm{slur header}\nonterm{slur command}\nonterm{further arguments}
\end{code}
Example:
\begin{code}
 \verb|\isl\isluru h|
\end{code}
\dots\ where $\hbox{\nonterm{slur header}}=\verb|\isl|$,
$\hbox{\nonterm{slur command}}=\verb|\isluru|$, and
$\hbox{\nonterm{further arguments}}=\verb|h|$. The underlying idea is
to replace the explicit absolute slur number by the \nonterm{slur
header} which instructs \musixser\ to maintain a voice-related
reference to a slur number.

There are basically three different slur headers:
\begin{description}
 \item[\tt\char92 isl] allocates a free slur number; to be used in
   conjunction with \musixtex\ slur initiation commands. Example:
   \verb|\isl\isluru c|
 \item[\tt\char92 rsl] references an allocated slur number. Example:
   \verb|\rsl\invertslur|
 \item[\tt\char92 tsl] frees an allocated slur number; to be used in
   conjunction with \musixtex\ slur termination commands. Example:
   \verb|\tsl\tslur c|
\end{description}

These slur headers totally omit mentioning any slur number; they are
convenient and appropriate if you have at most one slur per voice at
the same time. If you have more than one slur per voice
simultaneously, you must be able to distinguish between them when
issuing slur commands; in this case, replace the \nonterm{slur
header}~\verb|\isl| by \verb|\Isl|\nonterm{number} where
\nonterm{number} is a voice-related ``handle'' to a specific
slur. Also replace \verb|\rsl| by \verb|\Rsl|\nonterm{number} and
\verb|\tsl| by \verb|\Tsl|\nonterm{number}. Of course each
\verb|\Isl|\nonterm{number} must be followed by a matching
\verb|\Tsl|\nonterm{number}, and each \verb|\Rsl|\nonterm{number} must
be preceded by a matching \verb|\Isl|\nonterm{number}. (\verb|\isl|,
\verb|\rsl|, and \verb|\tsl| actually are abbreviations for \verb|\Isl0|,
\verb|\Rsl0|, and \verb|\Tsl0|, respectively.)

As a comprehensive example, here is a code excerpt from the above {\it
Carmina burana\/} phrase:
\begin{code}\begin{verbatim}
\defpattern\unisono
  {% bar 1
   +4 \Isl1\ibsluru h%          % initiate "long" upper slur with
                                % explicit relative number 1
      \isl\issluru h%           % initiate 1st "short" slur with
                                % implicit relative number 0
      \qu h%                    % set first note
   +4 \tsl\tslur i\ql i%        % terminate 1st "short" slur; set 2nd note
   +4 \ql j+2 \hl i+4 \qu h%
   +4 \isl\isluru i\ql i%
   +4 \tsl\tslur h\qu h%
   +4 \qu g+3/4 \hup h%
   % bar 2
   +4 \isl\issluru h\qu h%
   +4 \tsl\tslur i\ql i%
   +4 \ql j+4 \ql i+4 \qu h%
   +4 \isl\isluru i\Isl2\itieu i\ql i%
   +4 \Tsl2\ttie\ql i%
   +4 \tsl\tslur h\qu h%
   +4 \isl\islurd g\qu g%       % initiate last "short" slur
   +3/4 \Tsl1\tbsluru h%        % terminate last "short" slur
        \tsl\tslur h%           % terminate "long" upper slur
        \hup h}                 % set last note
\setvoice11{\pat\unisono}
\setvoice21{\pat\unisono}\end{verbatim}
\end{code}

Everything said so far also applies to beam numbers. For these,
\musixser\ supplies the beam headers \verb|\ibm|, \verb|\rbm|,
\verb|\tbm|, \verb|\Ibm|\nonterm{number}, \verb|\Rbm|\nonterm{number},
and \verb|\Tbm|\nonterm{number}. The \verb|\rbm| and
\verb|\Rbm|\nonterm{number} beam headers are mainly used to attach
note heads to beams and for beam multiplicity changes. Example:
\begin{code}\begin{verbatim}
\setvoice11
 {+16 \ibm\ibbu g0\rbm\qb g%
  +16 \rbm\tbbu\rbm\qb g%
  +8 \tbm\tqh g}\end{verbatim}
\end{code}

Which yields:\par\nopagebreak
\begin{music}
 \excerptskip
 \barduration{0/1}
 \setvoice11
  {+16 \ibm\ibbu g0\rbm\qb g%
   +16 \rbm\tbbu\rbm\qb g%
   +8 \tbm\tqh g}
 \startextract \processvoices \endextract
\end{music}

\musixser's slur/beam number management encapsulates each slur/beam in
the voice that it belongs to. However, beams spanning over
multiple voices are sometimes needed. Example:
\par\nopagebreak
\begin{music}
 \excerptskip
 \instrumentnumber2
 \curlybrackets{12}
 \advance\interinstrument \internote
 \setclef1\bass
 \barduration{0/1}
 \setvoice11
  {+8 \genibm0\ibu L1%
      \genrbm0\qb J%
   +8 \genrbm0\qb L%
   +8 \genrbm0\qb N}
 \setvoice21
  {+3/8
   +8 \genrbm0\qb c%
   +8 \genrbm0\qb e%
   +8 \gentbm0\tqb g}
 \startextract \processvoices \endextract
\end{music}

To accomplish this, a further set of beam headers is offered:
\verb|\genibm|\nonterm{number}, \verb|\genrbm|\nonterm{number}, and
\verb|\gentbm|\nonterm{number} (meaning ``generic~\dots''). A
beam~\nonterm{number} issued this way can be referenced from within
any voice, similar to \musixtex's absolute beam numbers.

Here is a code excerpt from the above example:
\begin{code}\begin{verbatim}
\setvoice11{+8 \genibm0\ibu L1%
               \genrbm0\qb J%
            +8 \genrbm0\qb L%
            +8 \genrbm0\qb N}
\setvoice21{+3/8
            +8 \genrbm0\qb c%
            +8 \genrbm0\qb e%
            +8 \gentbm0\tqb g}\end{verbatim}
\end{code}

(For the sake of completeness, \musixser\ also provides equivalent slur
headers \verb|\genisl|\nonterm{number},
\verb|\genrsl|\nonterm{number}, and
\verb|\gentsl|\nonterm{number} --- but you will not need to use them
since cross-voice slurs are accomplished by \musixtex\ in a different
way.)

Note that you cannot simply replace, say, \verb|\genibm0\ibu L1| by
\verb|\ibu0L1|. The latter will allocate absolute beam number~0
whereas the former instructs \musixser\ to allocate a free beam number
and to map relative number~0 onto it. The latter will clash with
\musixser's automatic beam number management, the former will cooperate.

Even if you do not use patterns, automatic slur/beam numbers are a
convenient means to avoid keeping track of already used numbers when
typesetting multi-voice scores.


\subsection{Typesetting long scores}

\musixser\ has to keep in memory all voices' material simultaneously;
therefore, it's impossible to set up an arbitrarily long score within
a single \verb|\setvoice| per voice without exceeding \TeX's memory. The
solution is to split the score into multiple ``blocks'' of material
which are processed by \TeX\ sequentially. The general pattern for this
is:

\begin{code}
 \verb|\startpiece|\\
 \verb|  \setvoice11{|\nonterm{material for block 1, instrument 1, voice 1}\verb|}%|\\
 \verb|  ...|\\
 \verb|  \setvoice|$nm$\verb|{|\nonterm{material for block 1, instrument {\it n\/}, voice {\it m\/}}\verb|}%|\\
 \verb|  \setmaster{...}%|\\
 \verb|  \processvoices|\\
 \verb|  ...|\\
 \verb|  |\nonterm{arbitrarily many blocks}\\
 \verb|  ...|\\
 \verb|  \setvoice11{|\nonterm{material for block {\it x\/}, instrument 1, voice 1}\verb|}%|\\
 \verb|  ...|\\
 \verb|  \setvoice|$nm$\verb|{|\nonterm{material for block {\it x\/}, instrument {\it n\/}, voice {\it m\/}}\verb|}%|\\
 \verb|  \setmaster{...}%|\\
 \verb|  \processvoices|\\
 \verb|\endpiece|
\end{code}

For choosing appropriate ``breakpoints'' for this division into
blocks, it is reasonable to follow rather ``natural'' divisions like
movements, verses, instrument number changes,~etc. On the other hand,
splitting material into blocks has no influence on the resulting music
layout (e.\,g.~line breaks).

\musixser\ keeps track of the bar progress even across subsequent
\verb|\processvoices| calls, i.\,e.~if one block ends with an
incomplete bar, the following one will start with another incomplete
one forming just the ``complement'' of the ending bar before. This
makes it possible to split a piece into two blocks even in the middle
of a bar (which may be reasonable when using pickup bars). However, if
you want to force the second block to begin with a complete bar, issue
the command
\begin{code}\verb|\resetbarticscount|\end{code}
somewhere before the next \verb|\processvoices| call.


%\subsection{Typesetting plus signs}
%
% Since '+' is no longer an active character, this section is obsolete
% and therefore removed.


\section{Score arrangement and part extraction}

\musixser\ has no dedicated part extraction feature, but the explicit
assignment of voice material to staff numbers makes it easy to
rearrange the voices-to-staves distribution in a more general
way. Simply permuting the \nonterm{staff no} entries of the
\verb|\setvoice|\nonterm{staff no}\dots\ constructs straightforwardly
redestributes voices to staves.

Since \musixser\ processes only those voices with a \nonterm{staff no}
that is valid with regard to the current \verb|\instrumentnumber|,
voices can easily be hidden by giving them a \nonterm{staff no}
greater than the current \verb|\instrumentnumber|. (Do not set
\nonterm{staff no} to zero --- this would lead to problems.) In this
respect, extracting an instrument part from a score is accomplished by
setting \verb|\instrumentnumber| and the \nonterm{staff no} of the
voice(s) to be extracted to one and giving all other voices a greater
\nonterm{staff no}. (Okay, this method admittedly does not convert
multiple subsequent full bar rests into a single multi-bar rest, but
appropriate use of the pattern expansion
feature --- see~\ref{fixpatterns} --- should make it easy to switch
between the two rest layout styles manually.)

You can enhance dealing with the voices-to-staves distribution by
defining macros for staff numbers so that maintenance of staff numbers
happens at one single place of your source (i.\,e.~in the macro
definition). This works because most \musixtex\ commands dealing with
staff properties accept a macro instead of a literal instrument number.

Consider as an example a score of three instruments. Begin with the
following definitions:
\begin{code}
 \verb|\def\violin{3} \def\viola{2} \def\basso{1}|
\end{code}

Then you can continue setting up the score referring to these symbolic
staff number names:
\begin{code}
 \verb|\instrumentnumber3|\\
 \verb|\setclef\basso\bass|\\
 \verb|\setclef\viola\alto|\\[1ex]
 \verb|\setvoice\violin1{+4 \qa e+4 \qa f+4 \qa g+4 \qa e}|\\
 \verb|\setvoice\viola 1{+4 \qa c+4 \qa d+4 \qa e+4 \qa c}|\\
 \verb|\setvoice\basso 1{+2 \ha J+2 \ha J}|
\end{code}

Which yields something like:
\begin{music}
 \def\violin{3} \def\viola{2} \def\basso{1}
 
 \instrumentnumber3
 \setclef\basso\bass
 \setclef\viola\alto
 
 \setvoice\violin1{+4 \qa e+4 \qa f+4 \qa g+4 \qa e}
 \setvoice\viola 1{+4 \qa c+4 \qa d+4 \qa e+4 \qa c}
 \setvoice\basso 1{+2 \ha J+2 \ha J}
 
 \barduration{0/1}
 \startextract \processvoices \endextract
\end{music}

To extract the viola part, simply change the following two lines of
the score header to:
\begin{code}
 \verb|\def\violin{4} \def\viola{1} \def\basso{4}|\\[1ex]
 \verb|\instrumentnumber1|
\end{code}

Which yields:
\begin{music}
 \def\violin{4} \def\viola{1} \def\basso{4}
 
 \instrumentnumber1
 \setclef\basso\bass
 \setclef\viola\alto
 
 \setvoice\violin1{+4 \qa e+4 \qa f+4 \qa g+4 \qa e}
 \setvoice\viola 1{+4 \qa c+4 \qa d+4 \qa e+4 \qa d}
 \setvoice\basso 1{+2 \ha J+2 \ha J}
 
 \barduration{0/1}
 \startextract \processvoices \endextract
\end{music}


\section{Error handling}

\subsection{Finding error sources}
\label{findingerrorsources}

The whole processing of the material given within \verb|\setvoice|
commands takes place within the \verb|\processvoices| macro which has
to be called within a \verb|\startpiece...\endpiece| pair. Therefore,
if a syntax error occurs within some \nonterm{material}, the line number
given by \TeX\ along with the error message won't point to the true
location of the error; instead, it will always refer to the line of
the \verb|\processvoices| call. In order to locate the exact error
source in your source file, you can utilize two kinds of information:
\begin{myenumlist}
 \item The bar number trace that \musixtex\ outputs on the console
   while running; the last bar number printed before the error
   message refers to the last completed bar before \TeX\ has run into
   the error. In order to be able to utilize this information, it's
   good style to include bar numbers as comments in your \nonterm{material}.
 \item \musixser's voice trace. If you issue the command
   \verb|\tracingvoicestrue| somewhere in your source file preamble,
   \musixser\ --- before processing any \nonterm{material} --- prints out
   the staff number and number of the voice that this \nonterm{material}
   belongs to. Thus the numbers of staff and voice printed immediately
   befor the error message point to the voice containing the defective
   code.
\end{myenumlist}

Some typical error messages and interpretations:

\begin{code}\verb|! Missing number, treated as zero.|\end{code}
Possibly an error within the \nonterm{duration} syntax, or a forgotten
space character between \nonterm{duration} and \nonterm{contents}.

% nicht mehr, seit + kein active character mehr ist
%\begin{code}
%  \verb|Runaway argument? ...|\\
%  \verb|! Forbidden control sequence found while scanning use of +.|
%\end{code}
%Most probably a forgotten space character between \nonterm{duration} and
%\nonterm{contents}.

\begin{code}
 \verb|! No column skip for ... tics defined; using default spacing.|
\end{code}
You have to provide a duration-to-space mapping as explained
in~\ref{durationspacemapping}.


\subsection{Tracing options}

If \TeX ing your source ends without error but you feel that
something's gone wrong with the synchronization of the voices, you may
try to issue the command
\begin{code}\verb|\tracingticstrue|\end{code}
somewhere in your piece's preamble. \musixtex\ will then print below each
``column'' (i.\,e.~each beat where something musical happens) the number
of tics it has determined as the time value of this column. This
provides some help for tracing the synchronization decisions 
\musixser\ has made when assembling the score from the distinct
voices.

Other tracing options --- mainly useful if you get a \TeX\ error
message --- include:
\begin{description}
 \item[\tt\char92 tracingvoicestrue] logs for each \nonterm{material}
   currently being processed to which voice it belongs;
   see~\ref{findingerrorsources}.
 \item[\tt\char92 tracingslurnumberstrue] logs slur number allocations
   and deallocations; helps finding \verb|\isl| and \verb|\tsl|
   mismatches (see~\ref{slurandbeamnumbers}).
 \item[\tt\char92 tracingbeamnumberstrue] similar to
   \verb|\tracingslurnumberstrue|.
 \item[\tt\char92 tracingcolumnstrue] prints out details about
   \musixser's analysis of event durations and score assembly; rather
   useful for \musixser\ debugging than for source error detection.
 \item[\tt\char92 tracingpatternstrue] prints out details about
   pattern expansion (see~\ref{fixpatterns}
   and~\ref{parameterizedpatterns}); also mainly for \musixser\ debugging.
\end{description}

All mentioned tracing functions can be activated anywhere in your
source; if the activation shall take place somewhere within a
\verb|\processvoices| run, the respective command must be given within
the master track. Tracing may be switched off by issuing
\verb|\tracing...false| instead of \verb|\tracing...true|.


\section{Software license}

\musixser\ (including this manual) is free software; you can
redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation; either
version 2 of the License, or any later version.

\musixser\ is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with \musixser; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

\medskip
Author:
\begin{tabular}[t]{l}
 Rainer Dunker\\
 Wachtelweg 31\\
 85\,591 Vaterstetten\\[0.5ex]
 Germany\\[1ex]
 E-mail: \tt rainer.dunker@web.de
\end{tabular}

\end{document}
