path: root/Master/texmf-dist/doc/generic/musixtex/musixdoc/settingup.tex

\chapter{Setting up the Input File}
\section{What makes a \TeX\ file a \musixtex\ file?}
A \musixtex\ input file is a special kind of \TeX\ input file. What makes it
special is that it must contain the command
\verb|\input musixtex|
before any reference to \musixtex\ macros. After that might follow
\verb|\input musixadd| or \verb|\input musixmad| if you want to have
respectively up to nine or twelve instruments or simultaneous beams,
ties, or slurs.\ixtt{musixtex.tex}\ixtt{musixadd.tex}\ixtt{musixmad.tex}
If you want to have greater numbers of these elements, you can assign them 
directly by including one or more of these commands: 
\verb|\setmaxinstruments|, 
\verb|\setmaxcxxviiibeams|, 
\verb|\setmaxcclvibeams|, 
\verb|\setmaxgroups|, 
\verb|\setmaxslurs|, 
\verb|\setmaxtrills|, 
\verb|\setmaxoctlines|.

Since it is still a \TeX\ file, after that, if you wished to,
you could write a whole non-musical book
using normal \TeX\ commands provided that you did not
use \verb|&| as a tab character like in plain \TeX; in \TeX\ lingo,
its \keyindex{catcode} has been changed.

 \section{Cautions for the non \TeX pert}
When \TeX\ reads anything, it inputs one \ital{token} at a time. A token
may be either a \ital{command} or a character. A command (or \ital{macro},
or \ital{control sequence}) is a
\ital{backslash} (``{\Bslash}'') immediately followed by sequence of
letters with no intervening spaces. For practical purposes, any single symbol (letter, digit,
special character, or space) that is not part of a command counts as a character
and therefore as a token.

Each command expects a specific number of parameters.
The tokens ``\verb|{|'' and ``\verb|}|'' are very special, in that (1) they
must occur in matched pairs, and (2) any matched pair together with
the stuff inside counts as a single parameter.
If the first
parameter expected is a single letter, it must either be
separated from the command by a space or
enclosed in braces (otherwise it would be interpreted as part of the command).
For example the command \verb|\ibu| expects three parameters, so the
following are all OK: \verb|\ibu123|, \verb|\ibu1A3|, \verb|\ibu1{`A}3|,
\verb|\ibu{1}{2}{3}|, \verb|\ibu1{-2}3|, or \verb|\ibu1{23}4|, but
\verb|\ibu1234| is not OK; the first three digits are taken as parameters,
leaving the ``4'' with no purpose other than to cause some of the dreaded
unrecorded space that we have already mentioned.

In the rest of this manual, when describing commands we will write
things like \verb|\qb{|$n$\verb|}{|$p$\verb|}|. It should be understood that
when $n$ and $p$ are replaced by their literal values, the braces may
or may not be necessary. In particular, if both are single digits, no
braces are needed; but if $n$ has two digits, or if $p$ has more than
one character, they must be surrounded by braces.

Spaces (blank characters) in the input file must be handled very carefully.
They are ignored at the beginning of a line, enabling logical
indentation schemes to help make the file human-readable. There are also a few
other places within lines where blank spaces are OK (such as mentioned in the prior paragraph),
but in general is it safest to avoid
any unnecessary blanks between the beginning and end of an input line.
At the end of a line, the truth is that a command with no parameters, such as
\verb|\bar| or \verb|\en| will cause no trouble. However if a command with
one or more parameters is the last item in an input line, it will cause
unrecorded space. The way around this is to end the line with either ``\verb|%|''
or \verb|\relax|.

 \section{Usual setup commands}\label{whatspecify}

\subsection{Music size}

 The first decision is what size type to use. \musixtex\ offers four sizes:
``small'' \mbox{(\texttt{16pt}-high staves),} ``normal'' (\texttt{20pt}),\index{sizes} ``large''
(\texttt{24pt}), and ``Large'' (\texttt{29pt}). The default is
\keyindex{normalmusicsize}. If you want a different size, then you have to
enter \keyindex{smallmusicsize}, \keyindex{largemusicsize}, or
\keyindex{Largemusicsize}. Each of these commands defines not only the
desired staff size but many other related sizes such as note heads, ornaments,
stem lengths, etc.

\subsection{Number of instruments}

 The command \keyindex{instrumentnumber}\onen~defines the
number of instruments to be $n$. If not entered, the default is $1$. This number is used in loops
that build staves,
set key signatures, set meters, etc., so if it differs from $1$ it must be explicitly
defined before any further commands.  The default maximum number of instruments is $6$
but this can be increased by using \keyindex{setmaxinstruments}\onen.

\subsection{Number of staves per instrument}

An instrument may have one or more staves (e.g.,~a piano would normally have 2 staves).
The differences between one
instrument of several staves and several instruments with one staff each are as follows:
\begin{itemize}\setlength{\itemsep}{0ex}
 \item Different instruments may have different \itxem{key signatures}, while different
staves of an instrument will all have the same key signature.
 \item A \itxem{beam} may include notes in different
staves of the same instrument.
 \item A \itxem{chord} may extend across several staves of the same
instrument.
 \item If an instrument has more than one staff, they will be linked together
with a big, curly brace at the beginning of each line.
\end{itemize}
The default number of staves per instrument is $1$. If it is different, then it
must be specified by \keyindex{setstaffs}\verb|{|$n$\verb|}{|$p$\verb|}|
where $p$ is the number of staves and $n$ is the
number of the instrument. In \musixtex, instruments are numbered
\ital{starting with the lowest}.
So for example \verb|setstaffs32|
assigns two staves to the third instrument from the bottom.

\subsection{Clefs for each staff}

 The default clef for every staff is the \ital{treble} clef. To assign
any other clef, the command is
\keyindex{setclef}\verb|{|$n$\verb|}{|$s_1s_2s_3s_4$\verb|}|
where $n$ is the number of the instrument, $s_1$ is a digit specifying the
clef for the first (lowest) staff, $s_2$ for the second staff, and so forth.
Note that like
instruments, staves of a given instrument are numbered starting with
the lowest. The parameters $s_2$, $s_3$ and $s_4$ can be omitted, in which case
any unspecified staves will be assigned a treble clef.

The digits $s$ can range from $0$ to $9$, with the following meanings:
$s=0$ signifies treble or G clef.
$s=1$ to $4$ mean C-clef, respectively on the first (lowest) through fourth staff line.
$1$ is also called \ital{soprano}, $3$ \ital{alto} and $4$ \ital{tenor}.
$s=5$ to $s=7$ mean F-clef, respectively on the third through fifth staff line. $5$ is
also called \ital{baritone} and $6$ is the normal \ital{bass}.
 $s=8$ is used to specify an ``empty'' clef.
$s=9$ represents a G clef on the first line, also called \ital{French violin} clef.

The three tokens \verb|\treble|, \verb|\alto|, and \verb|\bass| can be used instead
of a digit for $s$, but only if there would have been but one digit in the string.
So for example the clefs for a standard piano score
could be specified by
\keyindex{setclef}\verb|1{\bass}|.

Treble and bass clefs with the digit $8$ above or below are also possible; see 
Section~\ref{treblelowoct}.

\subsection{Key signatures}

To set a common key signature for all instruments, use
 \keyindex{generalsignature}\verb|{|$s$\verb|}|,
where $s>0$ is the number of \itxem{sharps} in the
signature and $s<0$ the number of \itxem{flats}\footnote{We once saw a
score in G-minor where the signature consisted of two flats (B and E) plus
one sharp (F). This is not directly supported by \musixtex.}. To override
the common key signature for instrument $n$, use
\keyindex{setsign}\verb|{|$n$\verb|}{|$s$\verb|}|. Note that differing
key signatures cannot be assigned to different staves of the same instrument.

\subsection{Meters}

A common \itxem{meter} for all staves can be specified by
 \keyindex{generalmeter}\verb|{|$m$\verb|}|,\label{generalmeter}
where $m$ describes the appearance of the meter indication, and can take several
different forms. If the meter is a \ital{fraction} (e.g.,~$3/4$) the command is
 \verb|\generalmeter{|\keyindex{meterfrac}\verb|{3}{4}}|.
Other possible tokens~$m$ are \keyindex{meterC},
\keyindex{allabreve}, \keyindex{reverseC}, \keyindex{reverseallabreve}, \keyindex{meterN} and
\keyindex{meterplus}. 
To insert extra space before the meter is
written, use \keyindex{meterskip}$d$ where $d$ is any hard \TeX\
%dimension\footnote{{\Bslash\tt meterskip} is not a macro but a
dimension\footnote{{\tt\Bslash meterskip} is not a macro but a
dimension register. Whatever follows it
must be a \TeX\ dimension and {\it it must not be enclosed in braces}.}.
The assignment must occur outside \verb|\startpiece...\endpiece| and will be
reset to zero after first meter is posted.

These are illustrated in the following example:

 %\check
\begin{music}
\generalmeter\meterC
\nostartrule
\parindent0pt\startpiece
\NOtes\qa{cegj}\en
\generalmeter\allabreve\changecontext
\NOTes\ha{ce}\en
\generalmeter\reverseC\changecontext
\NOTEs\zbreve g\en
\generalmeter\reverseallabreve\changecontext
\NOTEs\zwq g\en
\generalmeter{\meterfrac{3\meterplus2\meterplus3}8}\changecontext
\notesp\Tqbu ceg\Dqbl jg\Tqbu gec\en
\generalmeter{\meterN3}\meterskip4pt\changecontext
\Notes\qa{ceg}\en\setemptybar
\endpiece
\end{music}
\noindent which was coded as:
\begin{quote}\begin{verbatim}
\generalmeter\meterC
\nostartrule
\parindent0pt\startpiece
\NOtes\qa{cegj}\en
\generalmeter\allabreve\changecontext
\NOTes\ha{ce}\en
\generalmeter\reverseC\changecontext
\NOTEs\zbreve g\en
\generalmeter\reverseallabreve\changecontext
\NOTEs\zwq g\en
\generalmeter{\meterfrac{3\meterplus2\meterplus3}8}\changecontext
\notesp\Tqbu ceg\Dqbl jg\Tqbu gec\en
\generalmeter{\meterN3}\meterskip4pt\changecontext
\Notes\qa{ceg}\en\setemptybar
\endpiece
\end{verbatim}\end{quote}

To override the common meter for any  staff, use
\keyindex{setmeter}\verb|{|$n$\verb|}{{|$m_1$\verb|}{|$m_2$\verb|}{|$m_3$\verb|}{|$m_4$\verb|}}|.\linebreak
This works just like \verb|\setclef|. For example,
\verb|setmeter3{{\meterfrac{12}8}\allabreve}|
sets the meter to 12/8 for the first staff of the third instrument, and
\ital{alla breve} for the second staff.


\subsection{Instrument names}

To set an \itxem{instrument name}, use
\keyindex{setname}\verb|{|$n$\verb|}{|\ital{name of the instrument}\verb|}|.
This will place the name in the space to the left of the
first staff or group of staves for instrument $n$. To specify the amount of space
available, use \verb|\parindent|$d$ where $d$ is any hard \TeX\ dimension.
For multi-line instrument names, use \TeX\ commands as in the following:
\begin{verbatim}
  \setname1{\vbox{%
    \hbox to\parindent{\hss Bass\hss}%
    \hbox to\parindent{\hss Recorder\hss}}}
\end{verbatim}

 \section{Groupings of instruments}\label{curlybrackets}
By default, all staves in a system will be joined
at the left by a thin, vertical rule. In addition, if an instrument has more than
one staff, they will be joined by a big, curly brace. Now we introduce a way
to delineate groups of instruments or choirs with a square brace containing two parallel
vertical rules, the left one thick and the right one thin. This is commonly used
to group together the voices in a choir.

If there is only one choir, this can be done with
 \begin{quote}
\keyindex{songtop}\onen\\
\keyindex{songbottom}\verb|{|$m$\verb|}|
\end{quote}
\noindent where $m$ and $n$ are the instrument numbers of the first
and last voices. An example is shown in Section~\ref{song}.

If there is more than one choir to be set off with
square braces, each one can be specified with
 \begin{quote}
\keyindex{grouptop}\verb|{|$g$\verb|}{|$n$\verb|}|\\
\keyindex{groupbottom}\verb|{|$g$\verb|}{|$m$\verb|}|
\end{quote}
\noindent where $m$ and $n$ are the instrument numbers of the first
and last voices of group number~$g$. \musixtex{} allows up to three
groups, numbered from $1$ to $3$. The command \verb|\songtop| is equivalent
to \verb|\grouptop 1|; \verb|\songbottom| is equivalent to
\verb|\groupbottom 1|.

With \ttxem{musixadd.tex} or \ttxem{musixmad.tex}, the allowable number of 
groups is increased to four.
Alternatively, you can specify the allowable number of groups to $m$ by 
\keyindex{setmaxgroups}\verb|{|$m$\verb|}|%
\footnote{Using $m>4$ may require e-\TeX.}.
\label{musixmad_setmaxgroups}

If any of the instruments grouped this way has more than one staff, the
heavy curly brace will be shifted to the left of the square brace.

Previously defined square braces can be removed by declaring
\verb|\songtop| less than \verb|\songbottom|. The same applies to
\verb|\grouptop| and \verb|\groupbottom| for the same group number.

 An alternate command allows you to specify all choirs at once:
\begin{quote}
 \keyindex{akkoladen}\verb|{{|{\it lower\_1\/}\verb|}{|{\it upper\_1\/}%
   \verb|}{|{\it lower\_2\/}\verb|}{|{\it upper\_2\/}\verb|}{|%
   {\it lower\_3\/}\verb|}{|{\it upper\_3\/}\verb|}}|
\end{quote}
\noindent where {\it lower\_n\/} and {\it upper\_n\/} are instrument
numbers that denote the span of bracket number $n$. For
setting fewer than three brackets, just omit all unneeded
\verb|{|{\it lower\_n\/}\verb|}{|{\it upper\_n\/}\verb|}|~pairs.

For example,
 \verb|\instrumentnumber{5}\akkoladen{{1}{2}{3}{5}}|
\noindent yields the first example below, with five single-staff instruments
divided into two groups.
The second example has two instruments, the first (lower) with two staves and the
second with three. Each instrument is set off by default with a curly bracket.

If for some reason you want more than one \ital{instrument}\ grouped
within a curly
bracket, then you can use the 
command

 \keyindex{curlybrackets}\verb|{{|{\it lower\_1\/}\verb|}{|{\it upper\_1\/}%
   \verb|}{|{\it lower\_2\/}\verb|}{|{\it upper\_2\/}\verb|}...|

\noindent to be used as illustrated in the third example below.\\
\begin{small}
\begin{minipage}[t]{29ex}
\begin{music}
 % just to avoid wasting space ...
 \sepbarrules
 \smallmusicsize
 \instrumentnumber{5} \akkoladen{{1}{2}{3}{5}}
 \startextract\notes\en\bar\notes\en\zendextract
\end{music}
\begin{quote}is coded as:
\begin{verbatim}
 \sepbarrules
 \smallmusicsize
 \instrumentnumber{5}
 \akkoladen{{1}{2}{3}{5}}
 \startextract
 \notes\en\bar\notes\en
 \zendextract
\end{verbatim}\end{quote}
\end{minipage}
\begin{minipage}[t]{27ex}
\begin{music}
  \sepbarrules
  \smallmusicsize
  \instrumentnumber2 \setstaffs12\setstaffs23
  \startextract \notes\en\bar\notes\en\zendextract
\end{music}
\begin{quote}is coded as:
\begin{verbatim}
 \sepbarrules
 \smallmusicsize
 \instrumentnumber2
 \setstaffs12
 \setstaffs23
 \startextract
 \notes\en\bar\notes\en
 \zendextract
\end{verbatim}\end{quote}
\end{minipage}
\begin{minipage}[t]{27ex}
\begin{music}
 \sepbarrules
 \smallmusicsize
 \instrumentnumber5 %\setstaffs12\setstaffs23
 \curlybrackets{1235}
 \startextract \notes\en\bar\notes\en\zendextract
\end{music}
\begin{quote}is coded as:
\begin{verbatim}
 \sepbarrules
 \instrumentnumber5
 \smallmusicsize
 \curlybrackets{1235}
 \startextract
 \notes\en\bar\notes\en
 \zendextract
\end{verbatim}\end{quote}
\end{minipage}
\end{small}