From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Mon, 2 Sep 2019 13:46:59 +0900
Subject: Initial commit

---
 macros/musixtex/doc/musixdoc/introduction.tex | 823 ++++++++++++++++++++++++++
 1 file changed, 823 insertions(+)
 create mode 100644 macros/musixtex/doc/musixdoc/introduction.tex

(limited to 'macros/musixtex/doc/musixdoc/introduction.tex')

diff --git a/macros/musixtex/doc/musixdoc/introduction.tex b/macros/musixtex/doc/musixdoc/introduction.tex
new file mode 100644
index 0000000000..e396c200f7
--- /dev/null
+++ b/macros/musixtex/doc/musixdoc/introduction.tex
@@ -0,0 +1,823 @@
+\chapter{Introduction to \musixtex}
+
+This chapter is not a tutorial on the use of \musixtex, but instead serves as
+an overview of some of its capabilities, quirks, and history.
+
+\musixtex\ is a set of macros and fonts which enables music typesetting 
+within the \TeX\ system. It requires as a prerequisite a working
+installation of \TeX.
+\musixtex\ might be regarded as the digital equivalent of a box of type. It
+contains symbols for staves, notes, chords, beams, slurs and ornaments,
+ready to be arranged to form a sheet of music. But it must be told how to position
+those symbols on the page. This could be done by the typesetter
+himself, if he or she elects to proceed by entering \musixtex\ commands manually
+into an input file. However most users will find it far less taxing to let
+such decisions be made largely by the preprocessor
+\href{http://icking-music-archive.org/software/indexmt6.html#pmx}
+{\underline{\textbf{PMX}}}, which in addition uses a much simpler input
+language than \musixtex.
+
+Lyrics can also be handled by \musixtex. There is a set of primitive
+commands for this which are described later. But there is also a far
+more adaptable set of macros contained in the extension file
+\verb|musixlyr.tex|, and there is the preprocessor
+\href{http://icking-music-archive.org/software/indexmt6.html#mtx}
+{\underline{\mbox{\textbf{M-Tx}}}}\ which provides easy, transparent access to
+these macros.
+
+Most users of \TeX\ are familiar with \LaTeX, a set of \TeX\ macros
+which eases document layout. In fact many may only use \LaTeX.
+Until recently, \LaTeX\ and \musixtex\ coexisted only grudgingly, owing
+primarily to the limited availabily of storage registers. But with modern
+versions of \TeX\ and with the use of e\LaTeX, only a modest increase in
+complexity is incurred with the addition of musical excerpts to a \LaTeX\
+document. Still, fortunately, for typesetting a musical score there is
+rarely if ever any advantage to using \LaTeX. Only if one wanted to create a
+text document with embedded musical examples would there be much use for it.
+Even in that case there is a perfectly fine way to avoid using \musixtex\
+directly in the document file, namely, by using \musixtex\ to create
+\verb|pdf| or \verb|eps| files for
+each of the examples, and then embedding references to those in the file for
+the larger document. But for anyone who still wants to use both together, there is
+no better example than this manual, as generated with the files
+\verb|musixdoc.tex| and \verb|musixdoc.sty|. A few further details about such
+nonstandard applications are given in Section~\ref{excerpts}.
+
+\section{Primary features of \musixtex}
+ \subsection{Music typesetting is two-dimensional} Written music is not
+usually a linear sequence of symbols like a literary text. Rather,
+except for unaccompanied single-note instruments like clarinets,
+trumpets and human voices, it has the form of a two-dimensional matrix.
+ Thus, a logical way of coding music consists
+in horizontally accumulating a set of \ital{vertical combs} with
+\ital{horizontal teeth} as depicted in Table~\ref{readtable}.
+%\def\hboxit#1{\boxit{\rlap{#1}\hphantom{note sequence three}}}
+ \begin{table}
+ \begin{center}
+ \small
+ \renewcommand{\arraystretch}{1.4}
+ \setlength{\arrayrulewidth}{1.5pt}
+ \setlength{\tabcolsep}{2ex}
+ \begin{tabular}{|ll|ll|}\fbox{note sequence one}
+  &\fbox{note seq.\ four}
+  &\fbox{note seq.\ seven}
+  &\fbox{note seq.\ ten}\\\fbox{note sequence two}
+  &\fbox{note seq.\ five}
+  &\fbox{note seq.\ eight}
+  &\fbox{note seq.\ eleven}\\\fbox{note sequence three}
+  &\fbox{note seq.\ six}
+  &\fbox{note seq.\ nine}
+  &\fbox{note seq.\ twelve}\\
+ \end{tabular}
+ \end{center}
+ \caption{A logical way of coding music}\label{readtable}
+ \end{table}
+Accordingly, in \musixtex\ the fundamental macro used to represent
+one of those vertical combs (or one of the columns in Table~\ref{readtable})
+is of the form
+\begin{center}
+\verb|\notes ... & ... & ... \en|\footnote{The command
+\keyindex{en} is an abbreviation for the command \keyindex{enotes}, which may also be used.}
+\end{center}\index{"&@{\tt\char'046}}
+\noindent where the character \verb|&| is used to separate the notes to be
+typeset on respective staves of the various instruments, starting from the
+bottom.
+
+In the case of an instrument whose score has to be written with
+several staves, they are separated by the
+character \|\index{\tt\char'174@{\tt\char'174}}. 
+
+Thus, a score written for a keyboard instrument and
+a single-line instrument (e.g., piano and violin)
+will be coded as follows:
+\begin{center}
+\verb=\notes ... | ... & ...\en=
+\end{center}
+\noindent for each column of simultaneous \ital{groups of notes}.
+Each of those groups, represented by a single box in Table~\ref{readtable}\
+and by a sequence of three dots in the the two example macros above, may contain
+not only chord notes to be played simultaneously, but short sequences of
+consecutive
+notes or chords. As we'll soon see, this implies the need for two fundamentally different
+kinds of basic macros in \musixtex: those whose tokens are automatically followed
+by some amount of space (called \ital{spacing} macros), and those that are not.
+The former type, for example,
+would be used to produce the notes and rests in a single-line score;
+the latter would be used, for example, for chord notes and ornaments.
+
+\subsection{Horizontal spacing}
+Deciding upon the proper horizontal spacing of notes is a very complicated matter
+that we will not address in any detail here. Obviously short-duration notes
+should be closer together than longer ones. Almost as obviously, the spacing
+cannot be linearly proportional to the duration; otherwise  for example a whole
+note would occupy 32 times as much horizontal space as a thirty-second note. And
+in polyphonic scores the spacing in one staff is often influenced by the notes
+in another. This is a decision that the typesetter or preprocessor
+must make. Once the decision is made, \musixtex\ can provide the desired spacing.
+The main mechanism is through a set of macros described in
+Section~\ref{newspacings}. At this point we shall only mention that to control
+spacing, one of those
+macros will be selected to replace the symbol \verb|\notes| in the two examples
+above, and it will imply that whenever a spacing macro in encountered within
+a group of notes, a
+certain specific amount of horizontal space will be inserted.
+
+ \subsection{Music tokens}
+The tokens provided by \musixtex\ include
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item note symbols without stems;
+ \item note symbols with stems, and flags for eighth notes and
+shorter;
+ \item beam beginnings and endings;
+ \item beginnings and endings of ties and slurs;
+ \item accidentals;
+ \item ornaments: arpeggios, trills, mordents, turns, staccatos,
+pizzicatos, fermatas, etc.;
+ \item bar lines;
+ \item meters, key signatures, clefs.
+\end{itemize}
+For example, \verb|\wh a| produces a whole note at nominal frequency 222.5~Hz,
+\verb|\wh h| produces one an octave higher, \verb|\qu c|
+produces an up-stemmed quarter note C (250~Hz), and \verb|\cl J| produces a down-stemmed C
+eighth note an octave lower.
+
+ To generate chords with solid note heads, the non-spacing macro \keyindex{zq}
+can be used. It produces a solid note head at the specified pitch,
+the vertical position of which
+is memorized and recalled whenever the next stemmed note (possibly with a flag) is
+coded. The stem length is automatically adjusted to link all simultaneous notes. Thus, the
+\mbox{C-major} chord
+
+\begin{music}\nostartrule
+\startextract\NOtes\zq{ceg}\qu j\en\zendextract
+\end{music}
+ \noindent is coded \verb|\zq c\zq e\zq g\qu j| or more concisely,
+\verb|\zq{ceg}\qu j|; the \verb|u| in the spacing note macro
+\verb|\qu| is what generates the upstem.
+
+ \subsection{Beams}
+Each beam \index{beams} is generated by a pair of macros. The first defines
+the beginning horizontal position (implicitly the current position), altitude,
+direction (upper or lower), multiplicity (number of lateral bars), slope and
+reference number. This latter feature is needed so independent beams
+can overlap. The second macro of the pair specifies the termination
+location (again implicitly) and the reference number.
+
+ \subsection{Setting anything on the score}
+A general macro (\keyindex{zcharnote}) provides a means of
+putting any sequence of symbols (possibly contained in an \verb|\hbox{...}|) at any
+pitch of any staff of any instrument. This allows any symbol defined in a font
+(letters, math symbols, etc.) to be placed in the score at a position keyed
+to the music both in time (horizontally) and pitch (vertically) on the staff,
+\section{A simple example}
+ Before going into more detail, we give below an example of the two first
+bars of the sonata in \mbox{C-major} KV545 by {\sc Mozart}\index{Mozart, W.A.@{\sc
+Mozart, W.A.}}:
+
+\begin{music}
+\parindent11mm
+\setname1{Piano}
+\setstaffs12
+\generalmeter{\meterfrac44}
+\startextract
+\Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\hl j\en
+\Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\ql l\sk\ql n\en
+\bar
+\Notes\ibu0f0\qb0{dgf}|\qlp i\en
+\notes\tbu0\qb0g|\ibbl1j3\qb1j\tbl1\qb1k\en
+\Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\hl j\en
+\zendextract
+\end{music}
+ The coding is as follows:
+\begin{quote}\begin{verbatim}
+\begin{music}
+  \parindent10mm
+  \instrumentnumber{1}               % a single instrument
+  \setname1{Piano}                   % whose name is Piano
+  \setstaffs1{2}                     % with two staffs
+  \generalmeter{\meterfrac44}        % 4/4 meter chosen
+  \startextract                      % starting real score
+    \Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\hl j\en
+    \Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\ql l\sk\ql n\en
+    \bar
+    \Notes\ibu0f0\qb0{dgf}|\qlp i\en
+    \notes\tbu0\qb0g|\ibbl1j3\qb1j\tbl1\qb1k\en
+    \Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\hl j\en
+  \zendextract                       % terminate excerpt
+\end{music}
+ \end{verbatim}\end{quote}
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item \verb|\ibu0f0| begins an upper beam, aligned on the
+\ital{f}, reference number 0, slope 0
+ \item \verb|\tbu0| terminates this beam before writing
+the second \ital{g} by means of \verb|\qb0g|
+ \item \verb|\qb..| indicates a note belonging to a beam.
+ \item \verb|\sk| sets a space between the two quarters in the right
+hand, so that the second one is aligned with the third eighth in the left hand.
+ \item\verb|\qlp| is a dotted quarter note.
+ \item\verb|\ibbl1j3| begins a double beam, aligned on the \ital{C}
+(\verb|j| at this pitch) with slope 15\%.
+\end{itemize}
+
+\section{The three pass system}\label{threepass}
+\subsection{Introduction}
+\TeX's line-breaking procedure implicitly assumes
+that a normal line of text will contain many words, so that inter-word
+glue need not stretch or shrink too much to justify the line.
+One might at first consider extending this to music, treating each bar like a
+word with no stretchable internal space. But typically this would lead to unsightly
+gaps before each bar rule, simply because the number of bars per line
+is normally many fewer than the number of words in a line of text.
+\musixtex\ needs a more sophisticated horizontal spacing algorithm
+than is used in \TeX.
+
+To understand how \musixtex\ solves this problem, we have to
+recognize two different kinds of horizontal space, \ital{hard}\ and
+\ital{scalable}. Hard space is fixed and always represents the same
+physical distance.
+Examples of hard space are the widths of bar rules, clefs,
+and key signatures. Scalable space can be stretched as needed. It
+is what is normally used for the space after notes or rests. At the
+outset it is only defined in a relative sense. In other words,
+scalable spaces are defined as multiples of \verb|\elemskip|, an
+initially undefined basic spacing unit. For example, in \textbf{PMX}\
+all sixteenth notes
+are typically assigned a scalable width of \verb|1.41\elemskip|.
+One main job of \musixtex\ is to compute the physical value of
+\verb|\elemskip|, often expressed in points (72nds of an inch).
+The correct value is that which makes all the scalable space on
+a line just fill up what's not occupied by hard space. Obviously
+it may vary from line to line.
+
+To this end a three pass system was developed. To start the
+first pass on the file \verb|jobname.tex|, you would enter\footnote{
+In many cases it will suffice to run {\tt tex}, but with \musixtex~1.15,
+it is possible to create a file requiring the enhanced capacity of 
+{\tt etex}. Since {\tt etex} can handle any file {\tt tex} can, it's best
+always to use {\tt etex}.} 
+\verb|etex jobname|.
+Information about each bar is written to
+an external file named \verb|jobname.mx1|.
+This file begins with a header containing parameters
+such as line width and paragraph indentation. Then the hard and
+scalable space is listed for each bar.
+\index{scalable width}\index{hard width}
+
+The second pass, which is started with \verb|musixflx jobname|,
+determines optimal values of the basic spacing unit \verb|\elemskip|
+for each line, so as to properly fill each line, and to spread
+the piece nicely over an integral number of full lines. This routine was originally written
+in \textsc{fortran}  rather than \TeX, the main reason
+being the lack of an array handling capability in \TeX; the current version
+of \verb|musixflx| is a \textsc{lua} script, which may be executed without
+compilation in any standard \TeX\ system.
+
+\verb|musixflx| reads in the file \verb|jobname.mx1|, and writes its
+output to \verb|jobname.mx2|. The latter file contains a single entry for
+each line of music in the reformatted output. The key piece of information
+is the revised value of \keyindex{elemskip} for each line.
+
+Next, the file is \TeX-ed again, by entering \verb|etex jobname|. On this third pass,
+the \verb|jobname.mx2| file is read in, and the information
+is used to physically define the final score and embed the
+page descriptions into a \verb|dvi|\ file.
+
+You may wonder how the same command can
+cause something different to happen the second time it is issued. The explanation
+is that \musixtex\ checks for the presence of \verb|jobname.mx2|. If it's
+not present, the first pass is executed; if it is, the third pass. Obviously if
+you've made some corrections that affect any horizontal spacing, you must remember
+to delete the old \verb|jobname.mx2| and then rerun all three passes, or
+build or use a script that does so.
+
+\subsection{An example}
+
+Here's an example. Here, no value for \verb|\elemskip| is explicitly specified,
+so \musixtex\ assigns a single, default value. After the first pass you might get
+the following output:
+
+\begin{music}
+\hsize=100mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt
+\setsign1{-3}
+\nostartrule
+\startpiece\bigaccid
+\NOtes\qu{ce}\en
+\bar
+\NOtes\qu{gh}\en
+\bar
+\NOtes\qu{=b}\en
+\Notes\ds\cu g\en
+\bar
+\NOtes\qu{^f=f}\en
+\raggedstoppiece\contpiece% this is cheated, the problem was to get
+%                           pass 1 and pass 3 at the same time
+\NOtes\qu{=e}\itied0e\qu{_e}\en
+\bar
+\Notes\ttie0\Qqbu ed{_d}c\en
+\bar
+\Notes\ibu0b{-2}\qb0{=b}\en
+\notes\nbbu0\qb0{=a}\tqh0N\en
+\Notes\Dqbu cf\en
+\raggedstoppiece\contpiece
+\NOtes\uptext{\it tr}\qu e\uptext{\it tr}\qu d\en
+\bar
+\NOtes\qu c\qp\en
+\setdoubleBAR\raggedstoppiece
+\end{music}
+
+\noindent Note that the space after every quarter note is the same, and
+that lines are not justified.
+After running \verb|musixflx| and \TeX-ing the second time you'll
+get:
+
+\begin{music}
+\hsize=100mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt
+\generalsignature{-3}
+\nostartrule
+\startpiece\bigaccid
+\NOtes\qu{ce}\en
+\bar
+\NOtes\qu{gh}\en
+\bar
+\NOtes\qu{=b}\en
+\Notes\ds\cu g\en
+\bar
+\NOtes\qu{^f=f}\en
+\bar
+\NOtes\qu{=e}\itied0e\qu{_e}\en
+\bar
+\Notes\ttie0\Qqbu ed{_d}c\en
+\bar
+\Notes\ibu0b{-2}\qb0{=b}\en
+\notes\nbbu0\qb0{=a}\tqh0N\en
+\Notes\Dqbu cf\en
+\bar
+\NOtes\uptext{\it tr}\qu e\uptext{\it tr}\qu d\en
+\bar
+\NOtes\qu c\qp\en
+\Endpiece
+\end{music}
+
+\noindent Now \musixtex\ has determined a number of lines
+(which is different from the original number), the lines are justified,
+and if you look carefully you
+can see that the space after quarters in the first line
+is smaller than in the second. This example was coded as:
+\begin{verbatim}
+\hsize=100mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt
+\generalsignature{-3}
+\nostartrule
+\startpiece\bigaccid
+\NOtes\qu{ce}\en\bar
+\NOtes\qu{gh}\en\bar
+\NOtes\qu{=b}\en
+\Notes\ds\cu g\en\bar
+\NOtes\qu{^f=f}\en\bar
+\NOtes\qu{=e}\itied0e\qu{_e}\en\bar
+\Notes\ttie0\Qqbu ed{_d}c\en\bar
+\Notes\ibu0b{-2}\qb0{=b}\en
+\notes\nbbu0\qb0{=a}\tqh0N\en
+\Notes\Dqbu cf\en\bar
+\NOtes\uptext{\it tr}\qu e\uptext{\it tr}\qu d\en\bar
+\NOtes\qu c\qp\en\Endpiece
+\end{verbatim}
+
+\subsection{Adjusting the layout}
+
+One benefit of the 3-pass system is the quick and easy
+alteration to the layout which can be achieved
+by changing only one parameter, namely \keyindex{mulooseness}. This value
+acts analogously to \TeX's \verb|\looseness| command. For non-\TeX-perts: if you
+state \verb|\looseness=-1| somewhere inside any paragraph, then
+\TeX\ will try to make the paragraph one line shorter than it normally would.
+With \verb|\mulooseness|, \musixtex\ does the same, but for \ital{systems}
+and \ital{sections} rather than lines and paragraphs. A system is just a group of
+staves treated as a unit, and in this discussion is analogous to a line of text.
+What is a \ital{section}? It's any chunk of coding not containing a
+forced system break, System breaks can be forced with
+\keyindex{stoppiece}, \keyindex{endpiece}, \keyindex{zstoppiece},
+\keyindex{Stoppiece}, \keyindex{Endpiece}, \keyindex{alaligne}
+\keyindex{zalaligne}, \keyindex{alapage} or \keyindex{zalapage}. If none
+of these is present, the section comprises the whole piece.
+Somewhere\footnote{Advisably, at the beginning or
+at the end of the section, for the sake of clarity.}
+before the end of the section, you can change the value of
+\keyindex{mulooseness} to something different from the default of $0$, and
+\musixtex\ will typeset that section with a different number of systems.
+
+To give an easy example, changing the last line in the previous example to:
+\begin{verbatim}
+\NOtes\qu c\qp\en\mulooseness=1\Endpiece
+\end{verbatim}
+yields:
+
+\begin{music}
+\hsize=100mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt
+\generalsignature{-3}
+\nostartrule
+\startpiece\bigaccid
+\NOtes\qu{ce}\en
+\bar
+\NOtes\qu{gh}\en
+\bar
+\NOtes\qu{=b}\en
+\Notes\ds\cu g\en
+\bar
+\NOtes\qu{^f=f}\en
+\bar
+\NOtes\qu{=e}\itied0e\qu{_e}\en
+\bar
+\Notes\ttie0\Qqbu ed{_d}c\en
+\bar
+\Notes\ibu0b{-2}\qb0{=b}\en
+\notes\nbbu0\qb0{=a}\tqh0N\en
+\Notes\Dqbu cf\en
+\bar
+\NOtes\uptext{\it tr}\qu e\uptext{\it tr}\qu d\en
+\bar
+\NOtes\qu c\qp\en
+\mulooseness1\Endpiece
+\end{music}
+
+\noindent On the other hand,
+\begin{verbatim}
+\NOtes\qu c\qp\en\mulooseness=-1\Endpiece
+\end{verbatim}
+yields
+
+\begin{music}
+\hsize=100mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt
+\generalsignature{-3}
+\nostartrule
+\startpiece\bigaccid
+\NOtes\qu{ce}\en
+\bar
+\NOtes\qu{gh}\en
+\bar
+\NOtes\qu{=b}\en
+\Notes\ds\cu g\en
+\bar
+\NOtes\qu{^f=f}\en
+\bar
+\NOtes\qu{=e}\itied0e\qu{_e}\en
+\bar
+\Notes\ttie0\Qqbu ed{_d}c\en
+\bar
+\Notes\ibu0b{-2}\qb0{=b}\en
+\notes\nbbu0\qb0{=a}\tqh0N\en
+\Notes\Dqbu cf\en
+\bar
+\NOtes\uptext{\it tr}\qu e\uptext{\it tr}\qu d\en
+\bar
+\NOtes\qu c\qp\en
+\mulooseness-1\Endpiece
+\end{music}
+
+\noindent which is tighter than you would ever want, but serves to further
+demonstrate the use of \keyindex{mulooseness}.
+
+If you want to build up a \musixtex\ input file
+manually (which in fact very few users will ever need to do, considering the
+availability of \textbf{PMX}), here is a roadmap for one way to proceed:
+\begin{enumerate}
+ \item Enter the data one \verb|\notes| group at a time, taking care to select the
+relative horizontal spacing for each group (via the macros discussed in Section~\ref{newspacings})
+so as to maintain a consistent relationship between scalable space and note durations.
+This will be discussed in a great deal more detail in Chapter~\ref{preparing}.
+ \item \TeX~$\Longrightarrow$ {\tt musixflx} $\Longrightarrow$ \TeX.
+ \item Look at the output and decide if you want to have more or fewer
+systems, e.g.,~to fill the page or to get an even number of
+pages.\index{musixflx@{\tt musixflx}}
+ \item If you want to change the number of systems in a section, adjust
+\keyindex{mulooseness} accordingly. Keep in mind that each section cannot have fewer
+systems than bars.
+\item Delete \verb|jobname.mx2| and repeat the process\\
+\TeX~$\Longrightarrow$ \verb|musixflx| $\Longrightarrow$ \TeX.
+
+\end{enumerate}
+
+There is an alternate way to proceed if you know at the outset
+how many systems
+you want in a section. You can specify it directly by assigning a
+positive number to \keyindex{linegoal} somewhere within the
+section (\verb|\linegoal| requires
+version 0.83 or later of \verb|musixflx|).
+\keyindex{mulooseness} must be zero
+for \keyindex{linegoal} to work. Both are automatically reset to
+zero after processing the end of a section e.g., as defined by
+\keyindex{stoppiece}.
+
+Finally, for large scores (more than 4 pages or so), having
+only one section and an overall value of \verb|\mulooseness| becomes
+impractical since one wants not only to have nicely spaced systems, but also
+completely filled pages without empty top and
+bottom margins on the last page. It is then wise to force the total number of
+pages and possibly the line breaks in each page, which can be done using
+\keyindex{alapage} and/or \keyindex{alaligne}\footnote{This is the technique
+always used by \textbf{PMX} in constructing a \musixtex\ input file.}.
+%avrb
+%, or more automatically by
+%means of the \keyindex{autolines} command borrowed from \musictex\ and
+%implemented in the additional {\ttxem{musixcpt.tex}} file
+%avre
+
+There is another advantage to \musixtex's way of using scalable space and
+the three pass system. In
+\TeX nical terms it eliminates the need for \ital{glue}, and enables
+every horizontal position in a line to be computed. This in turn enables certain
+variable length symbols such as slurs to be specified by macros entered at
+their beginning and ending points, rather than having to estimate the
+length of the symbol and enter it at the starting point.
+
+ \subsection{Using \texttt{musixflx}}
+
+On most systems, \verb|musixflx|  can be invoked by typing the name of the program
+and the name of the file to be acted upon; i.e.,
+\begin{quote}
+\verb|musixflx jobname.mx1|
+\end{quote}
+Optionally, you can add a letter to indicate one of the debug modes, which are:
+\begin{quote}
+\verb|d | for debug information to screen\\
+\verb|f | for debug information to file \verb|jobname.mxl|\\
+\verb|s | to get the computed lines immediately on screen
+\end{quote}
+To allow for ease of use with scripts, \verb|musixflx| can be fed
+with either \verb|jobname.mx1|, \verb|jobname.tex| or only
+\verb|jobname|, any one of which will open \verb|jobname.mx1|.
+
+ \subsection{Unrecorded spaces: the novice's bugaboo}
+
+Because of the way \musixtex\ accounts for hard and scalable space and avoids
+using glue, it is absolutely essential that every horizontal space be
+properly entered into the input file. The most common error in this regard
+is including a blank space in the midst \ital{or at the end} of an input line.
+Such a blank space, or for that matter any stray character not entered with
+an appropriate \musixtex\ macro, will not be properly
+recognized and recorded by \musixtex, but it will still be treated like
+ordinary text by \TeX. The symptoms of such a transgression will be an
+{\bf Overfull hbox} warning during the third pass, and the appearance of
+either excessive blank horizontal space or thick black vertical lines in
+the page image.
+
+\medskip
+\centerline{\fbox{Considerable discipline is needed to avoid this problem!}}
+\smallskip
+
+The best technique for avoiding such unpleasantness is to avoid entering
+any nonessential blanks within input lines, and to end every
+input line with either \verb|%|\index{%@{\tt\char37}} or
+\keyindex{relax}, unless it already ends with a control sequence
+ending in a letter.
+
+There are other ways to enter unrecorded space which should be
+avoided. Between \verb|\startpiece| and \verb|\stoppiece| or
+\verb|\endpiece|, never use \verb|\hskip| or \verb|\kern| except
+within \ital{zero}-boxes like \verb|\rlap|, \verb|\llap|,
+\verb|\zcharnote|, \verb|\uptext|, etc., and never assign hard
+values to scalable dimensions like \verb|\noteskip|,
+\verb|\elemskip|, \verb|\afterruleskip| and \verb|\beforeruleskip|\footnote{Note that {\Bslash hardspace} does not fall in this
+category; it is specifically designed to enter hard space in a way
+that \musixtex\ can properly record it}.
+
+Here is a checklist of tips related to spacing issues. Because the
+foregoing several paragraphs are so important, some of their content
+is repeated in the list.
+
+\begin{enumerate}
+ \item
+Between \verb|\startpiece| and \verb|\stoppiece| or \verb|\endpiece|,
+end every input line with a either \verb|%| or a command with no arguments
+(including \verb|\relax| and \verb|\en|).
+ \item \verb|\off| must only be used with scalable values, e.g.,
+\verb|\noteskip|, \verb|\elemskip|, \verb|\afterruleskip|, and
+ \verb|\beforeruleskip|.
+ \item Remember that \verb|\qqsk|, \verb|\qsk| and \verb|\hqsk| are scalable, i.e., \verb|\qsk|
+  doesn't necessarily mean exactly one note head width (it depends on \verb|\elemskip|).
+ \item Lyrics and any other non-\musixtex\ text must be put in zero-width boxes
+such as
+  \verb|\zcharnote|, \verb|\zchar|, \verb|\rlap|, \verb|\lrlap|, \verb|\llap|,
+\verb|\uptext|, or \verb|\zsong|. Additional specific capabilities for entering
+lyrics are provided by
+ \verb|\hardlyrics|, \verb|\hsong|, and---most significantly---the
+text-placement macros defined in \verb|musixlyr.tex| (see Chapter~\ref{lyrics},
+p.~\pageref{lyrics}).
+ \item
+Between \verb|\startpiece| and \verb|\stoppiece| or \verb|\endpiece|,
+don't assign hard values to \verb|\noteskip|, \verb|\beforeruleskip|,
+or \verb|\afterruleskip|.
+\end{enumerate}
+
+
+\section{Further highlights}
+ %\check
+ \subsection{Key signatures}
+\begin{sloppypar}
+A single key signature can be assigned~to~all~instruments,~for~example~by 
+\keyindex{generalsignature}\verb|{-2}|
+which sets two flats on each staff. \keyindex{generalsignature}
+can be overridden for selected instruments, for example by
+\keyindex{setsign}\verb|2{1}| which puts one sharp on each staff
+of instrument number 2. Of course, the current signature as well
+as meters and clefs may change at any time.\end{sloppypar}
+\subsection{Transposition}
+With some extra attention, a score can be input in such a way that it is
+fairly easily transposed. There is an internal register
+called \keyindex{transpose}, the default value of which is zero, but which may be
+set to any reasonable positive or negative value. It defines a number of pitch
+steps (lines or spaces on a staff) by which all pitched symbols with be offset, provided
+they have been entered with letter values to represent their pitch.
+However,
+it will neither change the local accidentals nor the key signature.
+
+For
+example, suppose a piece were originally input in F major, and it contained a
+B natural, and you wanted to transpose it to G. If you simply set
+\verb|\transpose| to 1 with no other special considerations, then
+the key signature would not change, and
+the B~natural would appear as a C~natural, whereas it should be a C~sharp.
+So first you must explicitly change the key signature. Then, to
+solve the problem with accidentals, you should declare
+\verb|\relativeaccid|, which will cause the actual appearance of any
+accidental to depend on the pitch of
+the accidental as well as the current key signature. But the use of this
+facility requires the typesetter to have entered the original set of accidentals
+according to a nonstandard convention wherein an accidental does not
+specifically refer to the black or white keys on a piano, but to the
+amount by which the pitch is altered up or down from what it would naturally
+have been, taking the key signature into account.\index{relative accidentals} This
+is discussed in more detail in Section~\ref{transposeaccids}. Now, finally, you
+can enter \verb|\transpose=1| with more or less the desired effect.
+
+More or less, because there is also an issue with stem
+and beam directions. Normally a typesetter would want full control over them,
+and would exercise that control by entering them with macros that explicitly
+assign the direction. Naturally the assigned directions would persist
+even after changing \verb|\transpose|. With respect to stems of unbeamed notes,
+this matter can also be addressed at
+the input level, by using special macros for notes that leave the
+decision about stem directions up to \musixtex. These macros do the right
+thing in the face of transposition. They are discussed in
+Chapter~\ref{autostemdirections}. Unfortunately there is no corresponding
+such facility for beams, so the typesetter will have to edit the transposed
+score to adjust beam directions as required\footnote{\textbf{PMX}
+will automatically adjust both stem and beam directions when transposing, which
+is yet another reason to use it. However
+if a piece is to be transposed, the typesetter must still explicitly activate relative accidentals
+and enter accidentals according to the relative-accidental convention.}.
+
+ %\check
+ \subsection{Extracting parts from a score} 
+It is possible to extract separate scores for
+each individual instrument of a multi-instrument score.
+If you use \textbf{PMX}, it is very easy;
+see the documentation for \textbf{PMX}.
+If you use \musixtex\ without a preprocessor, 
+see Chapter~\ref{parts}.
+
+%After assigning symbolic numbers to instruments,
+%there are macros (see \ref{instrum-inhibit}) that permit
+% \begin{itemize}\setlength{\itemsep}{0ex}
+% \item choosing which instrument the following source code is attached to,
+% \item choosing which staff of an instrument the following source code is
+%attached to,
+% \item hiding one or several instruments by zeroing out their staff sizes and staff
+%numbers.
+% \end{itemize}
+
+ %\check
+ \subsection{Staff and note sizes}
+ Although the standard staff size is 20pt, \musixtex\ allows scores with
+sizes of 16, 24, or 29pt. Furthermore, any instrument may be assigned its own special staff
+size (usually smaller than the overall staff size), and there are special macros
+(e.g., \verb|\smallnotesize|, \verb|\tinynotesize|) that cause notes, beams, and
+accidentals all to take a different size.
+
+\subsection{Add-in macro libraries}
+During the early stages of \musixtex's development, common versions of \TeX\ itself were
+very limited in capacity, especially in terms of the numbers of registers that could
+be defined for use in macros. For this historical reason, many important enhancements
+to \musixtex\ are available only via add-in libraries. The user can thus pick and choose
+which to include for any particular compilation. Most of these are included in
+a \musixtex\ distribution, and their uses are discussed in this manual. The
+libraries have names like \verb|blabla.tex|, and are activated by including a line
+like \verb|\input blabla|\ within the the input file. The most common such files
+are \ttxem{musixadd.tex} and \ttxem{musixmad.tex} which respectively increase the
+number of instruments from the default 6 to 9 or 12 as well as increasing available numbers
+of other features; \verb|musixps.tex| which enables Type~K Postscript slurs; and
+\verb|musixlyr.tex| which greatly eases typesetting lyrics. In fact the latter two,
+while now included in \musixtex\ distributions, are not documented in this manual but
+in separate files, namely \verb|musixps.tex| itself and
+\verb|mxlyrdoc.pdf| respectively.
+
+
+\section{Installing and Using \musixtex}\label{using}
+
+As stated in the preface, 
+the \href{http://icking-music-archive.org/software/indexmt6.html}
+{\underline{Werner Icking Music Archive}}\ (WIMA) contains excellent and detailed
+instructions for installing \TeX, \musixtex{} and the strongly recommended
+preprocessors \textbf{PMX}
+(for instrumental music) and \mbox{\textbf{M-Tx}} (for vocal music) under
+\href{http://icking-music-archive.org/software/htdocs/Getting_Started_Four_Scenar.html#SECTION00022000000000000000}
+{\underline{Linux/\unix}}, 
+\href{http://icking-music-archive.org/software/htdocs/Getting_Started_Four_Scenar.html#SECTION00021000000000000000}
+{\underline{Windows}} and 
+\href{http://icking-music-archive.org/software/htdocs/Getting_Started_Four_Scenar.html#SECTION00023000000000000000}
+{\underline{Mac OS}}. 
+
+As stated in Section~\ref{threepass}, to compile a \musixtex-formatted score, you must run 
+in sequence \verb|etex|, \verb|musixflx|,
+and \verb|etex| again. This will produce a \verb|.dvi| file. From this point
+forward, this file can be processed like the device-independent output file
+for any \TeX\ document. The most common approach and the only one to 
+be discussed here is to next generate a Postscript file. This is accomplished
+by running \verb|dvips|, which is included in every \TeX\ system. To view the 
+Postscript, most users run {\tt GSview} or {\tt gv}, a front-end to {\tt ghostscript}, which must
+be separately downloaded and installed. Finally, you may produce a PDF file 
+using \verb|ps2pdf| or GSview, and view that with any PDF viewer, such as
+the Adobe Reader or {\tt GSview}. 
+
+You also can view the \verb|.dvi| file directly using a DVI viewer such as Yap or \verb|xdvi|, 
+but, if you are using type K Postscript slurs, some DVI viewers will not display them.
+
+Rather than executing all the foregoing programs separately, most users will 
+find it more convenient to use the \verb|musixtex| script that comes in most
+distributions of \musixtex. For example,
+
+\verb|musixtex jobname|
+
+\noindent will run the three passes described in Section~\ref{threepass},
+convert the result to PDF and delete intermediate files.  
+There are many options available to
+change the behavior; run
+
+\verb|musixtex -h|
+
+\noindent to get a summary.
+
+
+\section{Where to get help using \musixtex}
+
+The home base for all matters related to \musixtex\ is the
+Werner Icking Music Archive, at
+\href{http://icking-music-archive.org}{\underline{http://icking-music-archive.org}}.
+There is a  
+\href{http://tug.org/mailman/listinfo/tex-music}{\underline{mailing list}}, 
+hosted by TUG, the \TeX\ Users Group, where you will always find
+someone willing to answer questions and help solve problems.
+
+  \section{A very brief history of \musixtex}
+The idea of using \TeX\ to typeset music appears to have originated
+around 1987 with the master's thesis of Andrea
+{\sc Steinbach} and Angelika {\sc Schofer}\footnote{Steinbach A. \& Schofer
+A., \ital{Automatisierter Notensatz mit \TeX}, master's thesis,
+Rheinische Friedrich-Wilhelms Universit\"at,
+Bonn, Germany, 1987}. They called their package
+\mutex\index{mutex@\protect\mutex}. It was limited to a single staff.
+It introduced two key concepts: (1) using
+a large number of font characters to construct beams and slurs, and (2) using
+\TeX\ glue to help control horizontal spacing and justification.
+
+The next major step came around 1991 when Daniel {\sc Taupin} created \musictex.
+Its major enhancement was to allow multiple staves. But this came at a
+price: some flexibility was lost in controlling horizontal spacing and
+a great deal of trial and error became necessary to avoid excessive or
+insufficient gaps before and after bar lines.
+
+\musictex\ was a single-pass system. To remedy its shortcomings it became clear
+that a multi-pass system would be required. Around 1997 Dr.~Taupin along with Ross {\sc Mitchell}
+and Andreas {\sc Egler} created the first version of \musixtex. At last a fully
+automatic procedure was coded so as to provide pleasing horizontal spacing in
+multi-staff scores.
+
+Significant enhancements to \musixtex, which have already been mentioned, have been provided
+by Stanislav {\sc Kneifl} (Type~K Postscript slurs) and
+Rainer {\sc Dunker} (Lyrics handling via \verb|musixlyr.tex|).
+
+Since Dr.~Taupin passed away in 2003, \musixtex\ has been maintained by a 
+varying cast including Olivier {\sc Vogel}, Hiroaki {\sc Morimoto}, 
+Bob {\sc Tennent}, Andre {\sc Van Ryckeghem}, 
+Cornelius {\sc Noack}, and Don {\sc Simons}.
+
+No discussion of the history of \musixtex\ would be complete without mentioning
+the contributions of Werner {\sc Icking}. From the early days of \mutex\ until
+his untimely death in 2001, he served this line of software as its most prominent
+proponent, beta tester, web site and mailing list editor, consultant,
+problem solver, and inspiration for
+many third-party enhancements including \textbf{PMX}. In fact he founded the
+mailing list and the archive that now is named in his honor. The web site is
+currently edited by Christian {\sc Mondrup}, the software page by Bob {\sc Tennent},
+and the mailing list by Maurizio {\sc Codogno}.
+
+
-- 
cgit v1.2.3

