summaryrefslogtreecommitdiff
path: root/macros/generic/musixtex/doc/musixdoc/settingup.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/musixtex/doc/musixdoc/settingup.tex')
-rw-r--r--macros/generic/musixtex/doc/musixdoc/settingup.tex367
1 files changed, 367 insertions, 0 deletions
diff --git a/macros/generic/musixtex/doc/musixdoc/settingup.tex b/macros/generic/musixtex/doc/musixdoc/settingup.tex
new file mode 100644
index 0000000000..17b8697848
--- /dev/null
+++ b/macros/generic/musixtex/doc/musixdoc/settingup.tex
@@ -0,0 +1,367 @@
+\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}\index{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}\index{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}\index{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}\index{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}\index{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}\index{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}\index{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}
+
+
+
+