diff options
Diffstat (limited to 'macros/generic/musixtex/doc/musixdoc/settingup.tex')
-rw-r--r-- | macros/generic/musixtex/doc/musixdoc/settingup.tex | 367 |
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} + + + + |