musixtex (30oct10)

git-svn-id: svn://tug.org/texlive/trunk@20275 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 5917 insertions, 4815 deletions

diff --git a/Master/texmf-dist/doc/generic/musixtex/musixdoc.tex b/Master/texmf-dist/doc/generic/musixtex/musixdoc.tex
index 68d837a6ae5..17cafecb4c9 100644
--- a/Master/texmf-dist/doc/generic/musixtex/musixdoc.tex
+++ b/Master/texmf-dist/doc/generic/musixtex/musixdoc.tex
@@ -1,4 +1,8 @@
 %
+%  mxdoc111d.tex (formerly file 110d, internally called 109d1)
+%    Different from version posted in that it has the extra paragraph
+%    "You may wonder ..." in section 1.3
+%
 %   This file is part of MusiXTeX
 %
 %   MusiXTeX is free software; you can redistribute it and/or modify
@@ -16,18 +20,49 @@
 %   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 %   Boston, MA 02111-1307, USA.
 %
+%  This version 109d1 postdates the one posted to the site.
+%
 
 \ifx\documentclass\undefined
   \documentstyle[twoside,11pt,musixdoc,multicol,backgrnd]{report}
 \else
-  \documentclass[twoside,11pt]{report}
+  \documentclass[twoside,11pt,a4paper]{report}
   \usepackage{multicol}
   \usepackage{musixdoc}
-  \usepackage{backgrnd}
-%  \usepackage{amsmath}
-%  \usepackage[emtex]{changebar}
+  \usepackage{etex}
+  \usepackage[dvips,bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,colorlinks=true,pdfborder={0 0 0}]{hyperref}
+  \usepackage{url}
+  \usepackage{indentfirst}
+  \usepackage[ansinew]{inputenc}
+\makeatletter
+\def\notesintext#1{% no staff lines, no clefs
+  {\let\extractline\relax
+   \setlines10\smallmusicsize \nobarnumbers \nostartrule
+   \staffbotmarg0pt \setclefsymbol1\empty \global\clef@skip0pt
+   \startextract\addspace{-\afterruleskip}#1\zendextract}}
+\makeatother
+\def\musicintext#1#2{% normal
+  {\let\extractline\relax
+   \smallmusicsize \nobarnumbers
+   \staffbotmarg0pt \setclef1{#1}
+   \startextract\addspace{-\afterruleskip}#2\endextract}}
+% macro adapted to insert music without clef:
+\def\musicintextnoclef#1{% no clef small
+  {\let\extractline\relax
+   \smallmusicsize \nobarnumbers
+   \staffbotmarg0pt \setclefsymbol1\empty
+   \startextract\addspace{-\afterruleskip}#1\endextract}}
+\def\musicintextnoclefn#1{%  no clef normal
+  {\let\extractline\relax
+   \nobarnumbers
+   \staffbotmarg0pt \setclefsymbol1\empty
+   \startextract\addspace{-\afterruleskip}#1\endextract}}
 \fi
 \def\musictex{Music\TeX{}}
+\def\onen{{\tt\char123}$n${\tt\char125}}
+\def\pitchp{{\tt\char123}$p${\tt\char125}}
+\def\itbrace#1{{\tt\char123}$#1${\tt\char125}}
+\def\nochange{(\ital{NOT to be changed})}
 
 \ifx\setendvolta\undefined\def\setendvolta{\endvolta}\fi
 \ifx\setendvoltabox\undefined\def\setendvoltabox{\endvoltabox}\fi
@@ -39,29 +74,32 @@
 %\changebarsep 10 pt
 \title{\Huge\bf\musixtex\raise1.5ex\hbox{\large\copyright}\\[\bigskipamount]
 \LARGE\bf Using \TeX{} to write polyphonic\\or
-instrumental music\\\Large\sl Version T.104~-- \today}
+instrumental music\\\Large\sl Version T.114~-- June, 2006}
 \author{\Large\rm Daniel \sc Taupin\\\large\sl
  Laboratoire de Physique des Solides\\\normalsize\sl
  (associ\'e au CNRS)\\\normalsize\sl
- b\^atiment 510, Centre Universitaire, F-91405 ORSAY Cedex\\ E-mail : {\tt
-taupin@lps.u-psud.fr}\\\medskip
+% b\^atiment 510, Centre Universitaire, F-91405 ORSAY Cedex\\ E-mail : {\tt
+%taupin@lps.u-psud.fr}\\\medskip
+ b\^atiment 510, Centre Universitaire, F-91405 ORSAY Cedex\\\medskip
  \\\Large\rm Ross \sc Mitchell\\\large\sl
  CSIRO Division of Atmospheric Research,\\\normalsize\sl
  Private Bag No.1, Mordialloc, Victoria 3195,\\ Australia \\\medskip
-   \\\Large\rm Andreas \sc Egler\ddag\\\large\sl
+%   \\\Large\rm Andreas \sc Egler\ddag\\\large\sl
+   \\\Large\rm Andreas \sc Egler\\\large\sl
    (Ruhr--Uni--Bochum)\\ Ursulastr. 32\\ D-44793 Bochum}
 \date{}
-%\show\maketitle
-\let\endtitleORI\endtitlepage
- \def\endtitlepage{\vfill\noindent $^\ddag$ {\it For personal reasons, Andreas
-Egler decided to retire from authorship of this work. Nevertherless, he has
-done an important work about that, and I decided to keep his name on this
-first page. {\sc D. Taupin}}\endtitleORI}
+%\let\endtitleORI\endtitlepage
+% \def\endtitlepage{\vfill\noindent $^\ddag$ {\it For personal reasons, Andreas
+%Egler decided to retire from authorship of this work. Nevertherless, he has
+%done an important work about that, and I decided to keep his name on this
+%first page. {\sc D. Taupin}}\endtitleORI}
  \maketitle
 \clearpage
  %\check
 
-\thispagestyle{empty}
+\pagenumbering{roman}\setcounter{page}{2}
+
+%\thispagestyle{empty}
 
 \null
 \vfill
@@ -81,15 +119,14 @@ on your machine and mastering it\\
 is an awesome job which gobbles up\\
 a lot of your time and disk space.\\[\medskipamount]
 But, once you master it...\\[\smallskipamount]
-{\sc Hans Kuykens}
+Hans {\sc Kuykens}
 \end{flushright}
 
 \begin{center}
- Although one of the authors contested that point once the common work had
-begun, \musixtex{} may be freely copied, duplicated and used in conformance to
+\musixtex{} may be freely copied, duplicated and used in conformance to
 the GNU General Public License (Version 2, 1991, see included file {\tt
 copying})\footnote{Thanks to Free Software Foundation for advising us. See
-{\tt http://www.gnu.org}}.
+\href{http://www.gnu.org}{\underline{\tt http://www.gnu.org}}}.
 
 You may take it or parts of it to include in other packages, but no packages
 called \musixtex{} without specific suffix may be distributed under the name
@@ -97,104 +134,176 @@ called \musixtex{} without specific suffix may be distributed under the name
 corrections).
 
  Adaptations for specific implementations (e.g. fonts) should be provided as
-separate additional TeX or LaTeX files which override original definition.
-
+separate additional \TeX\ or \LaTeX\ files which override original definitions.
  \end{center}
 
 \clearpage
 
-\setcounter{page}1
-\tableofcontents
-\setcounter{secnumdepth}3
-\pagestyle{headings}
-
-\chapter{What is \musixtex{} ?}
-
-\hrule\smallskip
-\section*{Preface}
-
-\noindent Dear user,
-
-This is still an imperfect version, which means that some features will be
-added or corrected. However our intent is to avoid removing existing commands,
-in order to spare your own adaptation problems or your typing time correcting
-scores you already have in your archive.
-
+\chapter*{Preface to Version T.113}
+%\thispagestyle{empty}
+
+The main author of \musixtex{}, Daniel Taupin, died all too early in a 2003
+climbing accident. The \musixtex\ community was shocked by this tragic and unexpected
+event. You may read some tributes to Daniel Taupin which are archived at the
+\href{http://icking-music-archive.org}{\underline{Werner Icking Music Archive}}.
+
+Now, almost two years after his death, we would like to help keep his excellent
+work alive and current by assembling a new release. This new version corrects various
+minor bugs without adding any new functionality. At the same time it incorporates directly
+into the distribution some additional packages:
+\begin{itemize}\setlength{\itemsep}{0ex}
+\item Type 1 (postscript) versions of all the \musixtex{} fonts, created by
+Takanori Uchiyama;
+\item Postscript Slur Package K (Ver 0.92, 12~May~02) by Stanislav Kneifl;
+\item musixlyr (Ver 2.1c, 12 June 03) a \musixtex{} extension package for lyrics
+handling, by Rainer Dunker.
+\end{itemize}
+We would like to thank the authors of these packages for generously agreeing to allow their
+contributions to be included in the main \musixtex{} package.
+
+We have left the remainder of this manual largely as Daniel Taupin left it,
+except we have updated various references and provided dynamic links to
+archived versions where possible.
+
+This documentation is rather technical and is probably not the best way to
+begin typesetting music. If you are a beginner, you should visit the
+software section of the
+\href{http://icking-music-archive.org/software/indexmt6.html}
+{\underline{Werner Icking Music Archive}}.
+In particular, we recommend
+\href{http://icking-music-archive.org/software/pmx/pmxccn.pdf}
+{\underline{Cornelius Noack's tutorial}}. It contains helpful information for
+getting started with \musixtex, as well as a tutorial for \textbf{PMX}, a
+preprocessor for \musixtex\ with a much simpler input language, and a brief
+introduction to \textbf{M-Tx}, a preprocessor for \textbf{PMX}~which eases
+the inclusion of lyrics.
+
+\bigskip
+
+\begin{flushright}
+In the name of the community, Olivier Vogel
+(\href{mailto:oliviervogel@freesurf.ch}{\url{oliviervogel@freesurf.ch}}),
+July 30, 2005
+\end{flushright}
 
-Sections marked with a star, or paragraphs marked ``???'' or ``.!.'', indicate
-either  that text is partly missing, or that something might change at a
-next release.
+%\clearpage
+
+\chapter*{Preface to Version T.114}
+%\thispagestyle{empty}
+
+In order to expedite the release of version T.113 of \musixtex, only the most
+essential modifications were made to the manual. With version T.114 the manual
+has been extensively edited from cover to cover. Some material has been
+rearranged, and references to \musictex, the immediate predecessor to
+\musixtex, have been removed. The software itself remains
+very stable. Only the slightest changes have been made since version T.113.
+
+It remains true that this is the definitive reference to all features of
+\musixtex, but also that it is not the best place for a novice user to start.
+The \href{http://icking-music-archive.org/software/indexmt6.html}
+{\underline{Werner Icking Music Archive}}\ contains excellent and detailed
+instructions for installing \musixtex{} and the strongly recommended
+preprocessors \textbf{PMX}
+(for instrumental music) and \textbf{M-Tx} (for vocal) under
+\href{http://icking-music-archive.org/software/musixtex/musixtex-for-unix.html}
+{\underline{Linux/\unix}} or
+\href{http://icking-music-archive.org/software/musixtex/musixwinstall.pdf}
+{\underline{Windows 2000}}. Once the software is installed, most common
+music typesetting tasks can be accomplished entirely by using one of these
+preprocessors to generate the \musixtex\ input file, relieving the user of
+learning any of the commands or syntax of \musixtex\ itself. It is only
+for out-of-the-ordinary constructions that one must learn these details, so he
+may insert the necessary \musixtex\ commands into the preprocessor's input file
+as so called inline \TeX.
+\href{http://icking-music-archive.org/software/pmx/pmxccn.pdf}
+{\underline{Cornelius Noack's tutorial}} is an important resource which,
+in addition to gently introducing the
+novice to \textbf{PMX} and \textbf{M-Tx}, gives further details on installing
+Postscript slur facilities.
+
+\begin{flushright}
+Don Simons, Andre van Ryckeghem, Cornelius Noack, August 30, 2005
+\end{flushright}
 
- \smallskip
- \noindent{\bf Remarque, Bemerkung, Cuidado, etc.:} If you have problems
-understanding technical musical terms in english, please look at:
+\clearpage
 
-\begin{center} ftp://ftp.gmd.de/music/lists/glossary/glossary.ps \end{center}
-which gives the translation of most terms into French, German, Dutch, Danish
-and Swedish. This file {\tt glossary.eps.gz} is also included in the
-distribution.
-\index{glossary}\index{glossaire}\index{lexique}\index{traduction}\index{dictionnaire}
+%\pagenumbering{roman}
+\renewcommand{\baselinestretch}{.8}\footnotesize\normalsize
+\tableofcontents \setcounter{secnumdepth}3
+\renewcommand{\baselinestretch}{1}\footnotesize\normalsize
 
- \smallskip\hrule\medskip
+%avrb page 4 was on top
+\clearpage
+%avre
 
- \musixtex\ is a set of \TeX\ macros to typeset polyphonic, orchestral or
-polyphonic music. Therefore, it is mainly supposed to be used to type wide
-scores -- just because true musicians seldom like to have to frequently turn
-pages -- and this is not really compatible with \LaTeX's standard page
-formats. Even with \verb|A4.sty|, the \verb|\textheight| and \verb|\textwidth|
-are too small for musician needs.
+\setcounter{page}{1}
+\pagenumbering{arabic}
+\renewcommand{\thepage}{\arabic{page}}
 
+\pagestyle{headings}
 
-However, a \LaTeX\ style has also been provided (and it is used for the
-typing of the present paper) but this \verb|musixtex| style is fit for
-musicographic books rather than for normal scores to be actually played.
 
- It should be emphasized that \musixtex\ is not intended to be a
-compiler which would translate some \ixem{standard musical
-notation}s into \TeX\, nor to decide by itself about aesthetic problems in music typing.
-\musixtex\ only typesets staves, notes, chords, beams, slurs and ornaments as
-requested by the composer. Since it makes very few typesetting decisions,
-\musixtex\ appears to be a versatile and rather powerful tool. However, due
-to the important amount of information to be provided to the typesetting
-process, coding \musixtex\ might appear to be as awfully complicated as
-the real keyboard or orchestral music. It should therefore be interfaced by
-some pre-compiler in the case of the composer/typesetter wanting aesthetic
-decisions to be automatically made by somebody (or something) else.
-%
-%\footnote{A short description to all known compilers for \musixtex\ can be
-%found on page \pageref{compiler}f.}.
 
-\section{\musixtex\ principal features}
- %\check
- \subsection{Music typesetting is two-dimensional} Most people who have just
-learned a bit of music at college, probably think that music is a linear
-sequence of symbols, similar to literary texts to be \TeX-ed. On the contrary,
-with the exception of strictly monodic instruments like most orchestral wind
-instruments and solo voices, one should be aware that
-reading music is actually a matricial operation: the non-soloist musician
-successively reads \ital{columns} of simultaneous notes which he
-plays if he is a pianist, clavichordist or organist, which he reads
-and watches if he
-conducts an orchestra, and which he is supposed to check and partially play
-when he is a soloist who wants to play in time with the accompanying
-instrument or choir.
-
- In fact, our personal experience of playing piano and organ as well as
-sometimes helping as an alternate Kapellmeister leads us to think that music
-reading and composing is actually a slightly more complicated intellectual
-process: music reading, music composing and music thinking seem to be a three
-layer process. The musician usually reads or thinks several consecutive notes
-(typically a long \ital{beat} or a group of logically connected notes), then
-he goes down to the next instrument or voice and finally assembles the whole
-to build a sequence of music lasting roughly a few seconds.  He then proceeds
-to the next \ital{beat} or \ital{bar} of his score.
-
- Thus, it appears that the humanly logical way of coding music consists
+\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 \TeX\ macros which enables the typesetting of music with
+systems of up to twelve staves. It requires as a prerequisite a working
+installation of \TeX\footnote{See section \ref{installation}~for guidance on
+installing \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 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{\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|eps| files for
+each of the examples, then embedding references to those in the file for
+the book. 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 described in Table \ref{readtable}.
+\ital{horizontal teeth} as depicted in Table~\ref{readtable}.
 \def\hboxit#1{\boxit{\rlap{#1}\hphantom{note sequence three}}}
  \begin{table}
  \begin{center}
+%avrb
+ \small
+ %avre
  \begin{tabular}{|ll|ll|}\hboxit{note sequence one}
   &\hboxit{note seq.\ four}
   &\hboxit{note seq.\ seven}
@@ -207,116 +316,114 @@ in horizontally accumulating a set of \ital{vertical combs} with
   &\hboxit{note seq.\ twelve}\\
  \end{tabular}
  \end{center}
- \caption{The order in which a musician reads music}\label{readtable}
+ \caption{A logical way of coding music}\label{readtable}
  \end{table}
-This is the reason
-why, in \musixtex\ the fundamental \ital{macro} is of the form
+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 ... & ... & ... \enotes|\footnote{Also
-available for \keyindex{enotes} is the abbreviation \keyindex{en}.}
+\verb|\notes ... & ... & ... \enotes|\footnote{The abbreviation
+\keyindex{en} can be used in place of \keyindex{enotes}.}
 \end{center}\index{\&}
 \noindent where the character \verb|&| is used to separate the notes to be
-typeset on respective staffs of the various instruments, starting from the
+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 staffs, these staffs are separated by the
+several staves, they are separated by the
 character \|. \index{"|@{\tt\char'174}}
 Thus, a score written for a keyboard instrument and
-a monodic instrument (for example piano and violin)
+a single-line instrument (e.g., piano and violin)
 will be coded as follows:
 \begin{center}
 \verb=\notes ... | ... & ...\enotes=
 \end{center}
 \noindent for each column of simultaneous \ital{groups of notes}.
-It is worth emphasizing that we actually said \ital{``groups of notes''}:
-this means that in each section of the previous macro, the music typesetter is
-welcome to insert, not only chord notes to be played at once, but small
-sequences of consecutive notes which build something he understands as a
-musical phrase. This is why note typing macros are of two kinds in \musixtex,
-namely the note macros which are not followed by spacing afterwards, and those
-which induce horizontal spacing afterwards.
- \subsection{The spacing of the notes} It seems that many books have dealt
-with this problem. Although it can lead to interesting algorithms, we think it
-is not an important point in practice.
-
-In fact, each column of notes has not necessarily the same spacing
-and, in principle, this \itxem{spacing} should depend on the shortest
-duration of the simultaneous notes. But this cannot be established as a rule,
-for at least two reasons:
-\begin{enumerate}
- \item spacing does not depend only on the local notes,
-but also on the context, at least in the same bar.
- \item in the case of polyphonic music, exceptions can easily be found.
-Here is an example:
-
-\begin{music}
-\generalmeter{\meterfrac44}
-\startextract\NOtes\zhu j\ql h\hl g\hu k\ql f\enotes\endextract
-\end{music}
-\noindent where it can be clearly seen that the half notes at beats 2 and 3
-must be spaced as if they were quarter notes since they overlap, which is
-obvious only because of the presence of the indication of the
-\itxem{meter} 4/4.
-\end{enumerate}
-So the typesetter has to take care of good readable spacings on his own.
-Therefore, we preferred to provide the composer/typesetter with a
-set of macros which can be found in \ref{newspacings}.
- \subsection{Music tokens, rather than a ready-made generator}
-The tokens provided by \musixtex\ are:
-\begin{itemize}
- \item the note symbols \ital{without stem};
- \item the note symbols \ital{with stems, and hooks for eighth notes and
-shorter};
- \item the indication of beam beginnings and beam ends;
- \item the indication of beginnings and ends of ties and slurs;
- \item the indication of accidentals;
- \item the ornaments: arpeggios, trills, mordents, pinc\'es, turns, staccatos
-and pizzicatos, fermatas, etc.;
- \item the bars, the meter and signature changes, etc.
+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 elemental macros in \musixtex, those that 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 represent all 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}
- Thus, \verb|\wh a| produces an \ital{A (of nominal frequency 222.5~Hz,
-unless transposed)} of duration being a
-\ital{whole note}. In the same way, \verb|\wh h| produces an \ital{A
-(445~Hz)} of duration represented by a \ital{whole note}, \verb|\qu c|
-produces a \ital{C (250~Hz approx.)} whose value is a \ital{quarter note with
-stem up}, \verb|\cl J| produces a \ital{C (125~Hz approx.)} of
-duration equal to an \ital{eighth note with stem down}, etc.
-
- To generate quarter, eighth, sixteenth, etc. chords, the macro \keyindex{zq}
-can be used: it produces a quarter note head, the vertical position of which
-is memorized and recalled when another stemmed note (possibly with a hook) is
-coded; then the stem is adjusted to link all simultaneous notes. Thus, the
-perfect C-major chord, i.e.
 
-\begin{music}
-\startextract\NOtes\zq{ceg}\qu j\en\endextract
+\smallskip
+
+ Thus 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 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
+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, in a more concise way,
-\verb|\zq{ceg}\qu j| (stem up): in fact, single notes are treated\dots\ like
-one-note chords.
- %\check
+ \noindent is coded \verb|\zq c\zq e\zq g\qu j| or more concisely,
+\verb|\zq{ceg}\qu j|. Here the \verb|u| in the spacing note macro
+\verb|\qu| is what causes the upstem.
 
  \subsection{Beams}
-\ital{Beams}\index{beams} are generated using macros which define their
-beginning (at the current horizontal position), together with their altitude,
-their direction (upper or lower), their multiplicity, their slope and their
-reference number. This latter feature -- the reference number -- appears to
-be necessary, since one may want to write beams whose horizontal extents
-overlap: therefore, it is necessary to specify which beam the notes belong to
-and which beam is terminated at a given position.
+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 (in fact, some \verb|\hbox{...}|) at any
-pitch of any staff of any instrument. Thus, any symbol defined in a font
-(letters, math symbols, etc.) can be used to typeset music.
+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 giving more details, we give below an example of the two first
+ Before going into more detail, we give below an example of the two first
 bars of the sonata in C-major KV545 by {\sc Mozart}\index{Mozart, W.A.@{\sc
 Mozart, W.A.}}:
 
 \begin{music}
-\parindent10mm
+\parindent11mm
 \setname1{Piano}
 \setstaffs12
 \generalmeter{\meterfrac44}
@@ -327,11 +434,11 @@ Mozart, W.A.}}:
 \Notes\ibu0f0\qb0{dgf}|\qlp i\en
 \notes\tbu0\qb0g|\ibbl1j3\qb1j\tbl1\qb1k\en
 \Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\hl j\en
-\endextract
+\zendextract
 \end{music}
- The \ital{coding} is set as follows:
+ The coding is as follows:
 \begin{quote}\begin{verbatim}
-\begin{music}
+\begin{music}\nostartrule
 \parindent10mm
 \instrumentnumber{1}       % a single instrument
 \setname1{Piano}           % whose name is Piano
@@ -344,63 +451,88 @@ Mozart, W.A.}}:
 \Notes\ibu0f0\qb0{dgf}|\qlp i\en
 \notes\tbu0\qb0g|\ibbl1j3\qb1j\tbl1\qb1k\en
 \Notes\ibu0f0\qb0{cge}\tbu0\qb0g|\hl j\en
-\endextract                 % terminate excerpt
+\zendextract                 % terminate excerpt
 \end{music}
  \end{verbatim}\end{quote}
-\begin{itemize}
+\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 is aligned with the third eighth of the left hand.
- \item\verb|\qlp| is a quarter with a point.
+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) of slope 15\%.
+(\verb|j| at this pitch) with slope 15\%.
 \end{itemize}
 
 \section{The three pass system}
 \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.
-This strategy does not work very well for music. If each bar of music
-is treated as a word, in the sense that inter-bar glue is placed
-at the end of each bar, then the usual result is the appearance of
-unsightly gaps before each bar rule. This follows naturally from the
-fact that the number of bars per line is normally many fewer
-than the number of words in a line of text.
-
-To address the above aim, a three pass system was developed.
-On the first pass, information about each bar is written to
-an external file, by default \verb|jobname.mx1|.
-This file begins with a header listing parameters
-such as line width, paragraph indentation, clef, sign and meter widths,
-and the first-pass elemental spacing \keyindex{elemskip}.
-Width information within the bars is classified either as ``soft'' or ``hard'':
-``soft'' widths are those amenable to subsequent rescaling (e.g. a note box),
-while ``hard'' widths represent unscalable material such as clef symbols,
-key signatures and bar rules.\index{soft width}\index{hard width}
-
-After the first pass, an external routine is run to
-determine optimal values of the elemental spacing (\verb|\elemskip|)
-for each line, so as to properly fill each line, and to lead to
-the piece filling an integral number of lines. This routine was written
+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 elemental spacing unit. For example, in \textbf{PMX}\
+all sixteenth notes
+are typically assigned a scalable width of 1.41\verb|\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 \verb|tex 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 elemental 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 written
 in FORTRAN and now converted to C rather than \TeX, the main reason
-being the lack of an array
-handling capability in \TeX, and the concern that if such a routine
-were added to \musixtex, storage problems might be exacerbated.
+being the lack of an array handling capability in \TeX.
 
-The resulting routine reads in the file \verb|jobname.mx1|, and writes its
+\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 re-\TeX-ed. On this third pass,
+Next, the file is \TeX-ed again, by entering \verb|tex jobname|. On this third pass,
 the \verb|jobname.mx2| file is read in, and the information
-used as described above.
+is used to physically define the final score and embed the
+page descriptions into a \verb|dvi|\ file.
 
-To give an easy example: after pass 1 you get the following output:
+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 batch script that does so.
+
+Here's an example. Here, no value for \verb|\elemskip| is explicitly specified,
+so \musixtex\ assign a single, default value. After the first pass you might get
+the following output:
 
 \begin{music}
 \hsize=100mm
@@ -431,7 +563,11 @@ To give an easy example: after pass 1 you get the following output:
 \NOtes\qu c\qp\enotes
 \setdoubleBAR\raggedstoppiece
 \end{music}
-After running \verb|musixflx| and \TeX-ing the second time you'll get:
+
+\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
@@ -461,7 +597,12 @@ After running \verb|musixflx| and \TeX-ing the second time you'll get:
 \NOtes\qu c\qp\enotes
 \Endpiece
 \end{music}
-which was coded as:
+
+\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}%
@@ -481,23 +622,27 @@ which was coded as:
 \NOtes\uptext{\it tr}\qu e\uptext{\it tr}\qu d\en\bar
 \NOtes\qu c\qp\en\Endpiece
 \end{verbatim}
-The biggest advantage of using a 3-pass system is the very easy and fast
-alteration to the layout which is possible, especially of a long masterpiece,
-by changing only one parameter, namely \keyindex{mulooseness}. This value
-acts analogous to \TeX's \verb|\looseness| command. For non-\TeX-perts: if you
-end a paragraph and state \verb|\looseness=-1| somewhere inside, then
-\TeX\ will try to make this paragraph one line shorter than it normally would.
 
-\musixtex\ does the same, but instead for paragraphs, for \ital{sections}.
-What is a \ital{section}? As long as you don't force a line break, this means
-the whole piece. When you force a line break with either
+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} you start a
-new \ital{section}. Somewhere\footnote{Advisably, at the beginning or
+\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 \ital{section}, you can change the value of
-\keyindex{mulooseness} to something different from the default of 0.
+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}
@@ -533,12 +678,12 @@ yields:
 \NOtes\qu c\qp\enotes
 \mulooseness1\Endpiece
 \end{music}
-or:
+
+\noindent On the other hand,
 \begin{verbatim}
 \NOtes\qu c\qp\en\mulooseness=-1\Endpiece
 \end{verbatim}
-yields (a little bit tight, but only for the sake of
-demonstration of \keyindex{mulooseness}):
+yields
 
 \begin{music}
 \hsize=100mm
@@ -568,56 +713,72 @@ demonstration of \keyindex{mulooseness}):
 \NOtes\qu c\qp\enotes
 \mulooseness-1\Endpiece
 \end{music}
-Here is the fastest way to get a satisfactory output:
+
+\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 build up the piece bar\footnote{Or two or three,
-whatever you prefer.} by bar. Pay much attention to correct spacings, and go
-on only when you are really satisfied with them.
+ \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 2.
  \item \TeX~$\Longrightarrow$ {\tt musixflx} $\Longrightarrow$ \TeX.
  \item Look at the output and decide if you want to have more or fewer
-systems lines, e.g.~to fill the page or to get an even number of
+systems, e.g.~to fill the page or to get an even number of
 pages.\index{musixflx@{\tt musixflx}}
- \item Adjust \keyindex{mulooseness}. However, {\large\bf beware~:}
-\verb|\mulooseness| increases the target number of lines by its value. This is
-of no serious trouble for large pieces, but if you say \verb|\mulooseness=3|
-in a piece or in a section which only has 3 bars (three in the musical sense,
-i.e. two \verb|\bar| in the text), then {\tt musixflx} will not be able to split
-3 bars into 4 lines... and it will hopefully result in a diagnostic by {\tt
-musixflx}, but possibly also in an arithmetic fault...
- \item Delete the \verb|jobname.mx2| and again\\
-\TeX~$\Longrightarrow$ \verb|musixflx| $\Longrightarrow$ \TeX
-\quad\ital{(For hackers: watch the difference in {\tt jobname.mx1}!)}
-\end{enumerate}
-
-\begin{remark}
-Instead of looking at the output of the previous run and modifying the
-number of systems using \keyindex{mulooseness} one can directly specify
-the number of lines in a section by assigning a positive number to
-\keyindex{linegoal}. Use \keyindex{linegoal} in the same way as 
-\keyindex{mulooseness} somewhere in a section, preferable at start
-or end. \keyindex{mulooseness} must be zero for \keyindex{linegoal} 
-to work. Both are automatically set to zero after processing the end 
-of a section e.g. by \keyindex{stoppiece}. \keyindex{linegoal} 
-requires the latest version of musixflx (0.83).
-\end{remark}
-
- \noindent If you have really followed this step by step, then your whole
-layout will be ready and you will not have to generate \verb|jobname.mx2|
-again. This only holds as long as you don't change any spacings.
-
-If you get the warning: \verb|You can't use \raise ...|, than read the upper
-paragraph again and follow the instruction of point 5.
-
-There are some more advantages. Without using \ital{glue},
-every horizontal position in a line can be computed. This enables using,
-e.g.~octave lines, without specifying a dimension, but by saying
-\verb|\i...| and \verb|\t...|.
+ \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}
 
- \subsection{External executable {\tt musixflx}}
-One drawback affecting portability between computers is the executable
-{\tt musixflx}\index{musixflx@{\tt musixflx}}. We are still searching for
-people who are able to compile the C-source and maintain it.
+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{External executable \texttt{musixflx}}
+One issue that compromises portability between computers is the
+need for the executable {\tt musixflx}\index{musixflx@{\tt
+musixflx}}.
+%avrb
+To address this, the C source and compiled versions for various OS's are included in
+\verb|musixtex.zip| and are available from the
+\href{http://icking-music-archive.org}{\underline{Werner Icking Music Archive}}.
+%avre
 
 On most computers, the executable is invoked by typing the name of the program
 and the name of the file to be acted upon. \ital{i.e.}
@@ -632,443 +793,375 @@ Optionally, you can add a letter to indicate one of the debug modes, which are:
 \end{quote}
 To allow for ease of use with a batch file, \verb|musixflx| can either be fed
 with \verb|jobname.mx1|, \verb|jobname.tex| or only
-\verb|jobname|, all of which opens \verb|jobname.mx1|.
-
- \medskip For large scores (more than 4 pages approximately), having
-only one section and an overall value of \verb|\mulooseness| becomes
-impractical since one wants not only to have nicely spaced systems, but one
-also usually wants to have completely filled pages to avoid empty top and
-bottom margins on the last page. It is then wise to force the total number of
-pages and maybe the line breaks in each page, which can be done by either using
-explicit \keyindex{alapage} and \keyindex{alaligne}, or more automatically by
-means of the \keyindex{autolines} command borrowed from \musictex\ and
-implemented in the additional {\ttxem{musixcpt.tex}} file.
- \subsection{Restrictions and warnings} If you have worked with \musictex\
-before, you must be aware that two main things have changed, namely the
-spacing (and spacing commands) and the line breaking, see section~\ref{spacing},
-p.~\pageref{spacing} and section~\ref{linebreak} p.~\pageref{linebreak}.
-
- %\check
- A serious practical problem concerns the effect of unrecorded spaces, such as
-those created by source lines not ended by \verb|%| \index{%@{\tt\char37}} or
-\keyindex{relax} or another control sequence ending in a letter. These will
-result in the dreadful {\bf Overfull hbox} messages appearing during pass 3.
+\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{\boxit{Considerable discipline is needed to avoid this problem!}}
 
-When you start using this software package, you will spend a lot of time
-searching for the cause of over/underfull-hbox warnings, which will appear during
-pass 3. You may ignore them during pass 1,
-but \ital{you must} find their cause when they
-appear during pass 3.
-
-In \musixtex\ there is no glue (only $\pm$ 1pt behind \verb|\writesignatures|),
-so it works only if every space is recorded in the correct way. As a result,
-never use
-\verb|\hskip| or \verb|\kern| with the exception of \ital{zero}-boxes, like
-\verb|\rlap|, \verb|\llap|, \verb|\zcharnote|, \verb|\uptext|, etc., or
-(apparently) fixed length boxes like \verb|\hsong|. But that is not all---all
-spacing commands\footnote{Except {\Bslash hardspace} which is an exception and has
-the opposite purpose.} must be fed with scalable values
-(\ital{e.g.} \verb|\noteskip|, \verb|\elemskip|, \verb|\afterruleskip| and
-\verb|\beforeruleskip|, optionally preceded by an integer or decimal number).
-
-\verb|musixflx| can't work if the values of \verb|\noteskip|,
-\verb|\afterruleskip|, \verb|\beforeruleskip|, are directly assigned
-``hard''\footnote{Hard values are all values  which are not scalable}
-values in between
-\verb|\startpiece| and \verb|\stoppiece|\footnote{{\Bslash endpiece} has the
-same meaning}.\index{hard spacing}
-
-These restrictions make it hardly compatible with most sources designed for
-\musictex\footnote{Most examples provided by D. {\sc Taupin} in
-\musictex's distribution can be run with \musixtex\ without serious
-problems... However, they will eventually have to be corrected for the sake of
-compatibility.}. Most of them have to be adjusted to get things going.
-
-Some values are much more important than in \musictex,
-namely \verb|\elemskip|, \verb|\afterruleskip| and \verb|\beforeruleskip|.
-The ratio between them is especially very important if you use
-\keyindex{mulooseness} often to adjust the number of lines:
-all of them are multiplied by the same factor in each section.
- %\check
- \subsection{\musixtex's laws}
-\begin{enumerate}
- \item Never have a line that doesn't finish either with a control sequence
-or with a \verb|%|
-inside of \verb|\startpiece...\stoppiece|
+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
+the \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{center}
-\Large\bf  !!! \musixtex\ forgives NOTHING !!!
-\end{center}
-   (a space in the default font (using plain-\TeX) causes 3.33pt of unrecorded space,
-     but there is only $\pm$ 1pt of glue in \musixtex)
- \item \verb|\off| must be used with relative values, like
-  \verb|\noteskip|, \verb|\elemskip|, \verb|\after[before]ruleskip|
- \item \verb|\qsk| and \verb|\hqsk| are now scalable, e.g. \verb|\qsk|
-  doesn't mean exactly one note head width (it depends on \verb|\elemskip|
-   and \verb|flex_factor|)
- \item Text of songs and any non-\musixtex\ text must be put in zero boxes, like
-  \verb|\zcharnote|, \verb|zchar|, \verb|rlap|, \verb|lrlap|, \verb|llap|,
-\verb|uptext|, \verb|zsong...|. However, specific features are now provided,
-namely \verb|\hardlyrics| and \verb|\hsong| (see \ref{lyrics},
+\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|).
+ \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|\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 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-emplacement macros defined in \verb|musixlyr.tex| (see \ref{lyrics},
 p.~\pageref{lyrics}).
- \item Don't touch either \verb|\noteskip| with hard values,
-  or \verb|\after[before]ruleskip| at all inside of
-  \verb|\startpiece (\debutmorceau) ... \stop[end]piece (\susp[fin]morceau)|
+ \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{Some highlights}
- %\check
- \subsection{Signatures}
-Signatures can be stated either for all instruments, for example by
-\keyindex{generalsignature}\verb|{-2}| which sets two flats on each staff, or
-separately for each instrument.
-
-Thus, the \keyindex{generalsignature}
-can be partly overridden by
-\keyindex{setsign}\verb|2{1}| which puts one
-sharp on the staffs of \itxem{instrument number} 2. Of course, the
-current signature may change at any time as well as the meters and clefs.
- \subsection{Transposition}
- An important question is: \ital{``can \musixtex\ transpose a score~?''}.
-The answer is now 99.5~\% \ital{yes}. If fact, there is an internal register
-named \keyindex{transpose} the default value of which is zero, but it may be
-set to any reasonable positive or negative value. In that case, it offsets all
-symbols pitched with letter symbols by that number of pitch steps. However,
-it will neither change the signature nor the local accidentals, and if -- for
-example -- you transpose a piece written in $C$ by 1 pitch, \musixtex\ will
-not know whether you want it in $D\flat$, in $D$ or in $D\sharp$. This might
-become tricky if accidentals occur within the piece, which might have to be
-converted into flats, naturals, sharps or double sharps, depending on the new
-chosen signature. To avoid this trouble, \ital{relative} accidentals
-have been implemented, the actual output of which depends on the pitch of
-this accidental and on the current signature.\index{relative accidentals}
- %\check
- \subsection{Selecting special instrument scores}
-Another question is: \ital{``can I write an orchestral score and extract the
-separate scores for individual instruments~?''} The answer is 95~\%
-\ital{yes}: in fact, you can define your own macros
-\verb|\mynotes...\enotes|, \verb|\myNotes...\enotes| with as many
-arguments as there are in the orchestral score (hopefully this
-is less than, or equal to
-9, but \TeX perts know how to work around) and change its definition
-depending on the selected instrument (or insert a test dependent
-on the value of some
-selection register). But the limitation is that the numbering of instruments
-may change, so that \verb|\setsign3| may have to become \verb|\setsign1| if
-instrument 3 is alone. But, in turn, this is not a serious problem for
-average \TeX\ wizard apprentices.
- %\check
- \subsection{Variable staff and note sizes}
- Although the standard staff size is 20pt, \musixtex\ allows scores of 16pt
-and 24pt staff sizes. In addition, any instrument may have a special staff
-size (usually smaller than the overall staff size) and special commands
-\verb|\smallnotesize| or \verb|\tinynotesize| enable notes (and also beams or
-accidentals) to be of a smaller size, in order to quote optional notes or
-\ital{cadenzas}.
- %\check
-\section{How to get it}
-Primary site is {\tt hprib.lps.u-psud.fr} (anonymous {\tt ftp}); say:
-
- \verb|cd pub/musixtex|
-
- \verb|mget musix*.tex| (to get the macros)
-
- \verb|cd /pub/musixtex/mf|
-
- \verb|mget *.mf| (to get the source of the fonts)
-
- \verb|cd /pub/musixtex/tfm|
-
- \verb|binary|
-
- \verb|mget *.tfm| (to get the font metrics)
-
-\noindent or:
-
- \verb|cd /pub/music\_zips|
-
- \verb|binary|
 
- \verb|mget musix*.zip| (to get the zipped packages specific to \musixtex)
- 
-\medskip\noindent Official mirrors are
-the CTAN servers. To get it you have tou say:
-
- \verb|cd ctan| (to go to the CTAN server)
-
- \verb|cd macros/musixtex/taupin|
-
- \verb|binary|
-
- \verb|mget *.zip| (to get the zipped packages)
-
-\medskip The whole \itxem{distribution} can fit into a single 1.2Mbyte or
-1.44Mbyte diskette. All sources (including fonts) are provided,
-either separately or ``zipped''.
-
-{\sl REMARK: normally, the {\tt musixtex.zip} file expands into binary files
-valid for any system, and text files (the \TeX{} and \MF{} sources) in the
-\unix{} representation, namely with a ``LF'' character between each record. PC
-users might complain that their own coding is ``CR+LF'' (``CR'' usually
-appears as a ``{\tt \^{}M}''), but we checked that:
- \begin{itemize}
- \item the \ixem{MS-DOS} editor handles both denotations,
- \item the ``emacs'' and ``microemacs'' also do,
- \item the \TeX{} and \MF{} executable routines (et least the emTeX ones)
-also accept both representations.
- \end{itemize}
- However, for the sake of compatibility, we now provide two routines for PC's,
-namely {\tt dtou.exe} and {\tt utod.exe}, which convert text/source files
-from/to the MS-DOS denotation to/from the \unix{} denotation.
-}
-
- %\check
-\section{Enhancements}
- \subsection{Recent easy enhancements} Many enhancements have been asked for,
-to the ``father'' of \musixtex, namely \musictex, and this is a proof that it
-is considered as useful by many people. Some of these enhancements which
-seemed hard were in fact rather easy to implement, for example small notes to
-represent grace notes and cadenzas, or gregorian chant features.
-
- Some of them were more difficult, such as handling of lyrics now provided
-since version T.40.
- %\check
- \subsection{Enhancement limitations}
-Many requested improvements have not been
-\ital{yet} implemented for several reasons:
- \begin{itemize}
-   \item The authors' natural laziness (!)
-   \item More seriously: many of them would require using some more
-registers; unfortunately, \TeX\ registers are not numerous (256 of each
-kind and the limit of \keyindex{dimen} registers is nearly reached
-(especially using \LaTeX), but we do our best).
-   \item We do not think it is wise to introduce in \musixtex\ itself a great
-number of macros which would be poorly used by most users: the reason is that
-\TeX\ memory and --- moreover --- \TeX\ registers are severely limited and that
-unused macros may occupy many of these, leading to things crashing
-because of \verb|TeX capacity exceeded|.
-
- Therefore, many additional library files are now provided, which may be
-invoked or not, depending on the user's specific needs. Most of them are used
-to compile this \LaTeXe\ manual... except the {\tt musixadd.tex} and {\tt
-musixmad.tex}.
- \end{itemize}
+\section{Further highlights}
  %\check
-  \section{Acknowledgements} The idea of implementing the present package is
-due to the previous work (\mutex)\index{mutex@\protect\mutex} of \mbox{Andrea
-{\sc Steinbach}} and Angelika {\sc Schofer}\footnote{Steinbach A. \& Schofer
-A., \ital{Theses} (1987, 1988), Rheinische Friedrich-Wilhelms Universit\"at,
-Bonn, Germany.}. This work provided the basis of the Metafont codes which are
-still used here... with 100\% corrections and updates.\index{Schofer, A.@{\sc
-Schofer, A.}}\index{Steinbach, A.@{\sc Steinbach, A.}}
-
-
- English language is progressively checked thanks to Cecil {\sc Churms} from
-National Accelerator Center (South Africa).
+ \subsection{Key signatures}
+A single key signature can be assigned to all \nolinebreak3
+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.
+\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
+section~\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
-\chapter{Practical use}
-\section{Heading statements}
-Before any reference to \musixtex\ macros:
-
-\verb|\input musixtex|\footnote{It is highly recommended to build up a format.
-If you don't know how to do, you can refer to the same instruction you
-perhaps heard or read before: ``Ask you local \TeX-wizard.''. Otherwise
-it might be a good idea to look at chapter \ref{installation}
-(``Installation'') where some hints are given to build a \musixtex\ format
-(ref{formatbuild}).}
+ \subsection{Extracting parts from a score} Another question is:
+\ital{``Can I write a full score and then extract separate scores for
+each individual instrument?''}
+
+The answer is yes, but only with a great deal of special attention---so much,
+in fact, that we shall strongly recommend that if you want
+to do this, you should use \textbf{PMX}, which makes the process
+very easy. If for some reason you choose to ignore this advice, you may
+refer to the details that were provided in the prior version of this manual,
+\href{http://icking-music-archive.org/software/musixtex/mxdoc112.pdf}
+{\underline{mxdoc112.pdf}}.
+
+%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
- \noindent which may be followed by \verb|\input musixadd| in the case you
-have more than six instruments or more than 6 simultaneous beams
-or ties or slurs.\index{musixtex.tex@{\tt musixtex.tex}}
-\index{musixadd.tex@{\tt musixadd.tex}}
+ \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
+\verb|musixtex.zip|, 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 \verb|musixtex.zip|, are not documented in this manual but
+in separate files inside \verb|musixtex.zip|, namely \verb|musixps.tex| itself and
+\verb|mxlyrdoc.pdf| respectively.
+
+\section{Where to get the software and help using it}
+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}}.
+The most up-to-date versions of \musixtex\ and friends are located in the
+\href{http://icking-music-archive.org/software/indexmt6.html}{\underline{software}}
+section of the archive. Assuming you already have \TeX\ and only want to install
+\musixtex, the file you need to download will be named
+\href{http://icking-music-archive.org/software/musixtex/musixtex.zip}
+{\underline{\texttt{musixtex.zip}}} . Further details about
+the installation process are given in section \ref{installation}.
+
+The Werner Icking Archive also hosts the
+\href{http://icking-music-archive.org/mailman/listinfo/tex-music}
+{\underline{\TeX-music mailing list}}, 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, the primary maintainer of \musixtex\ has been
+Olivier {\sc Vogel}, with substantial assistance from 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 Don {\sc Simons},
+and the mailing list by Maurizio {\sc Codogno}.
 
- %\check
- After that, you may write a complete book of \TeX\ provided that you do not
-use \verb|&| as a tabulation character (its \keyindex{catcode} has been
-changed) inside the music score and that you do not overwrite \musixtex's
-definitions. This means that no special macros have been designed to help you
-write titles, author names, comments, literature excerpts, etc., unless you
-use \LaTeX\ with the \verb|musixtex| style.\index{\&}
- %\check
- \section{Before you
-begin to write notes}
- \subsection{Warnings for the non \TeX pert}
-\begin{quote}
 
  %\check
-When \TeX\ reads a parameter, it inputs one \ital{token}. This means
-\ital{one} figure or \ital{one} character or \ital{one}
-command\footnote{Syntactically, a \ital{command} is made of a
+\chapter{Elements of \musixtex}
+\section{Setting up the input file}
+\subsection{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 more than six or nine instruments or simultaneous beams,
+ties, or slurs.\ixtt{musixtex.tex}\ixtt{musixadd.tex}\ixtt{musixmad.tex}
+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).
+
+ \subsection{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
-\ital{letters}.}. If you want to give more than one char or e.g. a negative
-number(`-' is one token and a digit is one) or a command which reads another
-parameter, then you have to use braces to transfer the parameter correctly.
-For example, the command \verb|\meterfrac| reads two parameters; if you want
-to declare a $\frac{8}{12}$ timing and you code: \verb|\meterfrac812|, then
-you will get a $\frac{8}{1}$ timing and a misplaced ``\verb|2|''. The correct
-coding is \verb|\meterfrac{8}{12}| or \verb|\meterfrac8{12}|.
-
-
- %\check
- The next problem is due to spaces. Spaces are ignored at the
-beginning of a line. Spaces are ignored immediately behind a \TeX-command
-(they indicate the end of that command unless \TeX\ finds characters which are
-not \ital{letters}). All other spaces insert \ital{unexpected} space and
-they will cause a lot of trouble during third pass. Same remark holds for end
-of lines. Thus \verb|\bar| or \verb|\enotes| as last statement in current line
-cause no trouble, because an end of line indicates to \TeX\ the end of a
-command.
-
- %\check
- If you state \verb|\qu g| and start a new line, then you get into trouble, but
-if you say \hbox{\verb|\qu g%|\relax
- $<new line><spaces>$}, you have no more problem
-and this is better readable.
-
-If this sounds complicated, remember that \TeX\ was designed to typeset
-text and not music...
-
- \end{quote}
- %\check
- \subsection{What you have to specify}\label{whatspecify}
- \leavevmode
- You should first specify whether you want to typeset music in ``normal'' size
-(20pt\index{sizes} per staff) or ``small'' size (16pt) or ``large'' size
-(24pt). This is only optional, the default setting is
-\keyindex{normalmusicsize}. If you want the smaller size, then you have to
-say\footnote{This sets up not only the size of staff, but also the elementary
-spacing and the space behind the bar rule.}  \keyindex{smallmusicsize},
-\keyindex{largemusicsize}, and \keyindex{Largemusicsize} to have the larger
-sizes of 24pt and 28.8pt.
-
-
-
- Then, the first compulsory declaration is:
-
- \keyindex{instrumentnumber}\verb|{|$n$\verb|}|
-
- \noindent where $n$ is the number of instruments, used by
-\musixtex\ to performs loops building staffs, setting signatures, meters,
-etc. Therefore, it must be defined before any other statements.
-If not then default value is one. An instrument
-may consist of several staffs, e.g.~the piano. The difference between one
-instrument of several staffs and several instruments is as follows:
-\begin{itemize}
- \item distinct instruments may have distinct \itxem{signatures}, distinct
-staffs of a unique instrument share the same signature.
- \item \itxem{stems} may be hung to \itxem{beams} belonging to differents
-staffs of the same instrument.
- \item \itxem{chords} may extend across several staffs of the same
+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|\enotes| 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|.
+
+ \subsection{Usual setup commands}\label{whatspecify}
+
+ The first decision is what size type to use. \musixtex\ offers four sizes:
+``small'' (16-pt-high staves), ``normal'' (20pt),\index{sizes} ``large''
+(24pt), and ``Large'' (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.
+
+ 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.
+
+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 staffs of a unique \itxem{instrument} are tied together
-with a big brace at the beginning of each line.
+ \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}
- If the number of staffs is not
-equal to one, this number must be specified by:
-
- \keyindex{setstaffs} $n$\verb|{|$p$\verb|}|
-
- \noindent where $p$ is the number of staffs, and where $n$ is the
-number of the instrument considered (e.g.~\verb|setstaffs3|
-for the 3rd instrument, starting from the bottom).
-
- %\check
- Unless all your instruments only use the \ital{violin} clef, you
-have to specify all the clefs used for all the instruments. This is done by
-coding:
-
-\keyindex{setclef}\verb|{|$n$\verb|}{|$s_1s_2s_3s_4$\verb|}%|
-
-\noindent where $n$ is the number of the instrument, $s_1$ is one figure
-specifying the clef of the lower staff, $s_2$ the clef of the second staff,
-etc.
-
- The value $s_1=0$ means the \ital{violin} clef (G clef or \itxem{clef de
-sol} in French) for the lower staff, $s_2=0$ means the violin clef for the
-second staff, etc. If $s_2$, $s_3$ or $s_4$ are omitted in the second argument
-of the \verb|\setclef|, these staffs have de default clef, namely 0, i.e. the
-violin clef.
-
- The values $s_1=1$ through $s_1=4$
-mean the \ital{alto} clef (\itxem{clef d'ut} in French) set on first (lower)
-through fourth (next to upper) line of the staff.
-
- The value $s_1=5$ means the \ital{bass} clef at third (middle) line,
-$s_1=6$ means the usual \ital{bass} clef (F clef or \itxem{clef de fa} in
-French) at the usual fourth line, and $s_1=7$ means the \ital{bass}
-(\itxem{subbass}) clef (F clef or \itxem{clef de fa} in
-French) at the fifth line.
-
- The value  $s_1=8$ is not used.
-
- The value  $s_1=9$ means the \itxem{french violin clef}, an ancient feature
-which sets the G clef (\ital{clef de sol} in French) at the fist line of the
-staff.
-
- If remembering the digits associated with usual clefs seems too difficult,
-one can also say 
-
- \verb|\setclef{|$n$\verb|}{|\keyindex{treble}\verb|}|
-
-\noindent to get the \ixem{violin clef} on all staffs of the specified
-instrument. In the same way the most used \itxem{alto clef} (alto clef on 3rd
-line) can also be called with
-
-
- \verb|\setclef{|$n$\verb|}{|\keyindex{alto}\verb|}|
-
-\noindent which sets the lower staff of thet instrument to the alto clef, but
-sets other staffs above to the violin clef.
-The usual \itxem{bass clef} on fourth line
-can also be called with
-
- \verb|\setclef{|$n$\verb|}{|\keyindex{bass}\verb|}|
-
-\noindent {\sl IMPORTANT: the commands \verb|\alto| and \verb|\bass| only set
-these clefs at the first staff. Other staffs still have the default value of
-violin clef.}
-As an example, a standard piano score
-should include:
-
- \keyindex{setclef}\verb|1{\bass}%| \quad or\quad
- \keyindex{setclef}\verb|1\bass|
-
-\noindent taking account of the fact that the bass clef is set on the lower
-staff, but the upper one has the default value of violin clef.
-If the signature is not void, one should code:
-
- \keyindex{generalsignature}\verb|{|$s$\verb|}|
-
-\noindent where $s>0$ indicates the number of \itxem{sharps} in the
-signature and $s<0$ the number of \itxem{flats}\footnote{We have seen once a
+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.
+
+ 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 not used.
+$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}|.
+
+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.}
-
- If a \itxem{meter} indication is to be posted, it should be
-specified using the macro
-
- \keyindex{generalmeter}\verb|{|$m$\verb|}%|
-
- %\check
- \noindent where $m$ is the description of the meter indication which should
-appear on each staff. If it is a \ital{fraction} (e.g.~3/4) on should code
-
- \verb|\generalmeter{\meterfrac{3}{4}}%|
-
-\noindent or, in a simpler way (if the numbers are less than 10):
-
- \verb|\generalmeter{\meterfrac34}%|
-
-You can suppress the beginning vertical rule with saying \keyindex{nostartrule}
-and restore the default with \keyindex{startrule} after that.
-
- Special denotations can be used, such as \keyindex{meterC},
+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.
+
+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} and
-\keyindex{meterplus}.
+\keyindex{meterplus}. These are illustrated in the following example:
 
  %\check
 \begin{music}
@@ -1083,10 +1176,10 @@ and restore the default with \keyindex{startrule} after that.
 \generalmeter\reverseallabreve\changecontext
 \NOTEs\zwq g\enotes
 \generalmeter{\meterfrac{3\meterplus2\meterplus3}8}\changecontext
-\Notes\Tqbu ceg\Dqbl jg\Tqbu gec\enotes
+\Notes\Tqbu ceg\Dqbl jg\Tqbu gec\enotes\setemptybar
 \endpiece
 \end{music}
-which was coded as:
+\noindent which was coded as:
 \begin{quote}\begin{verbatim}
 \generalmeter\meterC
 \nostartrule
@@ -1099,82 +1192,69 @@ which was coded as:
 \generalmeter\reverseallabreve\changecontext
 \NOTEs\zwq g\enotes
 \generalmeter{\meterfrac{3\meterplus2\meterplus3}8}\changecontext
-\Notes\Tqbu ceg\Dqbl jg\Tqbu gec\enotes
+\Notes\Tqbu ceg\Dqbl jg\Tqbu gec\enotes\setemptybar
 \endpiece
 \end{verbatim}\end{quote}
- However, not all music scores have the same meter in each staff.
-Especially, some staffs may have \ital{ternary} meters while others have
-\ital{binary}. This can be specified by using the \keyindex{generalmeter} macro
-to set the meter for most of the scores and overriding it by:
-
-\keyindex{setmeter}\verb|2{{\meterfrac{12}8}\allabreve}%|
-
- \noindent which sets the meter to 12/8 for the first (lower)
-staff, and \ital{alla breve} for the second staff of the instrument number 2.
-
-Sometimes it might be useful to insert additional space before the meter is
-written. This is possible by assigning a value to \keyindex{meterskip} in the
-preamble. It is reset to zero after first meter indication.
- \subsection{Instrument names} If you want the \itxem{name of the instrument}s
-(or the \itxem{name of the voice}s) to be displayed in front of their
-respective staffs at the beginning, you may code:
 
-\keyindex{setname} $n$\verb|{|\ital{name of the instrument}\verb|}%|
-
- %\check
- \noindent where $n$ is the number of the instrument
-considered. In this case, you should also adjust the \keyindex{parindent}
-dimension so that the long name of an instrument does not spill too far into
-the left margin.
- \subsection{Polyphonic songs}
-Except staffs of a unique instrument tied together with a big brace, staffs
-normally begin on the left with a thin vertical rule. However, it is usual to
-tie all human voices together with a left heavy and right thin vertical rule.
-
- \subsubsection{Case of only one choir}
- In the usual case where you have only one choir, this can be specified
-by:
+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.
+
+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.
+
+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.
+ \subsection{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}\verb|{|$n$\verb|}|\\
+\keyindex{songtop}\onen\\
 \keyindex{songbottom}\verb|{|$m$\verb|}|
 \end{quote}
 \noindent where $m$ and $n$ are the instrument numbers of the first
-and last choral voices. Example is shown in \ref{song}.
+and last voices. An example is shown in section~\ref{song}.
 
- No heavy square brace is produced when the bottom instrument has a number
-greater than the top one. This feature can be used to remove choir heavy
-braces between distinct parts of the same score.
-
- \subsubsection{Case of several choirs or several orchestras}
- Your may divide your instruments into up to three groups linked together with
-a left square brace. Each of these groups is specified with:
+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 choral voices of group number $g$. \musixtex{} allows up to three
-groups, numbered from 1 to 3, plus the ``zero'' group consisting of the voices
-or instruments which belong to no declared group. \verb|\songtop| is equivalent
-to \verb|\grouptop 1| and \verb|\songbottom| is equivalent to
+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 {\tt musixadd.tex}, this number of groups is raised to four.
-
- This grouping feature can also be used to collect not only voices but also
-instruments with one or several staffs. In that case the normal brace is
-shifted left of the square havy brace.
+With \ttxem{musixadd.tex}, the allowable number of groups is increased to four.
 
- \subsection{Removing square choir braces}
+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 choir braces can be removed by stating a
-\verb|\songtop| less than the \verb|\songbottom|. The same applies to
-\verb|\grouptop| and \verb|\groupbottom| of the same group number.
+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.
 
- \subsection{Specifying all brackets together}
-
- Alternatively, you can use the following command for specifying all
-required brackets together:
+ 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|}{|%
@@ -1183,63 +1263,135 @@ required brackets together:
 \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;
-\verb|\akkoladen{}| cancels all brackets.
-
-Example:
-\begin{quote}
- \verb|\instrumentnumber{5} \akkoladen{{1}{2}{3}{5}}|
-\end{quote}
-yields:\par\nopagebreak
+\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 2 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 extension file
+%\ttxem{curly.tex}\footnote{Submitted
+\href{http://icking-music-archive.org/software/musixtex/add-ons/curly.tex}
+{\underline{\ttxem{curly.tex}}}\footnote{Submitted
+by Mthimkhulu {\sc Molekwa} to the mutex list}, which defines 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{minipage}[t]{50mm}
 \begin{music}
  % just to avoid wasting space ...
- \smallmusicsize\setsize1\smallvalue\setsize2\smallvalue
- \setsize3\smallvalue\setsize4\smallvalue\setsize5\smallvalue
+ \sepbarrules
+ \smallmusicsize
+\setsize1\smallvalue\setsize2\smallvalue
+\setsize3\smallvalue\setsize4\smallvalue\setsize5\smallvalue
  \instrumentnumber{5} \akkoladen{{1}{2}{3}{5}}
- \startextract \hardspace{2cm}\zendextract
+ \startextract\notes\en\bar\notes\en\zendextract
 \end{music}
-which was coded as:
-
+\begin{quote}is coded as:
+\begin{verbatim}
+ \sepbarrules
+ \smallmusicsize
+ \setsize1\smallvalue
+ \setsize2\smallvalue
+ \setsize3\smallvalue
+ \setsize4\smallvalue
+ \setsize5\smallvalue
+ \instrumentnumber{5}
+ \akkoladen{{1}{2}{3}{5}}
+ \startextract
+ \notes\en\bar\notes\en
+ \zendextract
+\end{verbatim}\end{quote}
+\end{minipage}
+\begin{minipage}[t]{50mm}
+\begin{music}
+  \sepbarrules
+  \smallmusicsize
+\setsize1\smallvalue\setsize2\smallvalue
+  \instrumentnumber2 \setstaffs12\setstaffs23
+  \startextract \notes\en\bar\notes\en\zendextract
+\end{music}
+\begin{quote}is coded as:
 \begin{verbatim}
- \smallmusicsize\setsize1\smallvalue\setsize2\smallvalue
+ \sepbarrules
+ \smallmusicsize
+ \setsize1\smallvalue
+ \setsize2\smallvalue
+ \instrumentnumber2
+ \setstaffs12
+ \setstaffs23
+ \startextract
+ \notes\en\bar\notes\en
+ \zendextract
+\end{verbatim}\end{quote}
+\end{minipage}
+\begin{minipage}[t]{50mm}
+\begin{music}
+ \input curly
+ \sepbarrules
+ \smallmusicsize
+ \setsize1\smallvalue\setsize2\smallvalue
+ \smallmusicsize
  \setsize3\smallvalue\setsize4\smallvalue\setsize5\smallvalue
- \instrumentnumber{5} \akkoladen{{1}{2}{3}{5}}
- \startextract \hardspace{2cm}\zendextract
-\end{verbatim}
+ \instrumentnumber5 %\setstaffs12\setstaffs23
+ \curlybrackets{1235}
+ \startextract \notes\en\bar\notes\en\zendextract
+\end{music}
+\begin{quote}is coded as:
+\begin{verbatim}
+ \input curly
+ \sepbarrules
+ \instrumentnumber5
+ \smallmusicsize
+ \setsize1\smallvalue
+ \setsize2\smallvalue
+ \setsize3\smallvalue
+ \setsize4\smallvalue
+ \setsize5\smallvalue
+ \curlybrackets{1235}
+ \startextract
+ \notes\en\bar\notes\en
+ \zendextract
+\end{verbatim}\end{quote}
+\end{minipage}
 
 
 
- %\check
-\section{Starting your masterpiece}
- \subsection{Typing the first system}
-Just code
-\keyindex{startmuflex}
-
-\noindent which opens the \ital{jobname}{\tt .mx1} during \TeX ing the first
-time your masterpiece. All informations are now written to it. During pass 3
-it will be open for read in and all computed values are used to set the
-lines\footnote{The files must be closed before leaving \TeX, preferably before
+
+\section{Preparing to enter notes}
+ \subsection{After the setup, what next?}
+
+The command \keyindex{startmuflex} initiates the serious business of
+\musixtex. On the first \TeX\ pass it
+opens \ital{jobname}{\tt .mx1} for writing bar-by-bar tabulations of all
+hard and scalable space to be fed to \verb|musixflx| on the second pass.
+\verb|musixflx| generates \ital{jobname}{\tt .mx2} which defines the
+number of bars in each system and the factors relating scalable space
+to hard space in each system. On the third pass both files will be opened
+and read to define the final spacing. These files should be closed before
+leaving \TeX, preferably before
 \keyindex{bye} or \keyindex{end}, with \keyindex{endmuflex}. Normally \TeX\
-closes all open files on his own when terminating the program, but it is still
-wiser to do this explicitly.}.
+closes all open files on its own when terminating the program, but it is still
+cleaner to do this explicitly.
 
-\begin{remark} do not worry too much if you forget \verb|\startmuflex|; in
-most cases --- since version T.39 --- the \verb|\startpiece| command will do
-it, if necessary. Conversely, only the first \verb|\startmuflex| is effective,
-the others are inefficient... for safety. \end{remark}
+After \verb|\startmuflex|, the command \keyindex{startpiece} will initiate
+the first system, containing all instruments you have previously defined.
+The indentation will be \keyindex{parindent}, so if you want nonzero
+indentation, this register should be set to the desired hard dimension
+before issuing \verb|\startpiece|.
 
-Then code
+ \subsection{Horizontal spacing commands}\label{newspacings}
+\subsubsection{Basic note spacing}
+\musixtex\ provides a set of macros each of which defines a particular
+increment of scalable spacing. The default set is tabulated below:
 
- %\check
-\keyindex{startpiece}
-
-\noindent which will initiate (with indentation \keyindex{parindent})
-the first set of staffs for all instruments you have previously defined. But
-that is not sufficient to begin writing notes and silences. In fact, you
-must also choose the spacing of the notes.
- \subsection{Easy selecting note spacing}\label{newspacings}
-Therefore, we preferred to provide the composer/typesetter with a
-set of macros (incidentally, this can be adjusted):
 \begin{center}
 \tinynotesize
 \renewcommand{\arraystretch}{1.5}% I hate LaTeX
@@ -1252,89 +1404,138 @@ set of macros (incidentally, this can be adjusted):
 \keyindex{notes}\verb|  ... & ... & ... \enotes|&\verb=2=\keyindex{elemskip}
   &\ccu1&16th\\
 \keyindex{notesp}\verb| ... & ... & ... \enotes|&\verb=2.5\elemskip=
-  &\pt1\ccu1&16th pointed, 8th triplet\\
+  &\pt1\ccu1&dotted 16th, 8th triplet\\
 \keyindex{Notes}\verb|  ... & ... & ... \enotes|&\verb=3\elemskip=
   &\cu1&8th\\
 \keyindex{Notesp}\verb| ... & ... & ... \enotes|&\verb=3.5\elemskip=
-  &\cup1&8th pointed, 4th triplet\\
+  &\cup1&dotted 8th, quarter triplet\\
 \keyindex{NOtes}\verb|  ... & ... & ... \enotes|&\verb=4\elemskip=
-  &\qu1&4th\\
+  &\qu1&quarter\\
 \keyindex{NOtesp}\verb| ... & ... & ... \enotes|&\verb=4.5\elemskip=
-  &\qup1&4th pointed, 2th triplet\\
+  &\qup1&dotted quarter, half triplet\\
 \keyindex{NOTes}\verb|  ... & ... & ... \enotes|&\verb=5\elemskip=
-  &\hu1&2th\\
+  &\hu1&half\\
 \keyindex{NOTesp}\verb| ... & ... & ... \enotes|&\verb=5.5\elemskip=
-  &\hup1&2th pointed\\
+  &\hup1&dotted half\\
 \keyindex{NOTEs}\verb|  ... & ... & ... \enotes|&\verb=6\elemskip=
-  &\wh1&1th\\\hline
+  &\wh1&whole\\\hline
 \end{tabular}\end{center}
-\noindent
-If you don't like them, define your own using e.g.:
-
-\verb|\def\NOtes{\vnotes5.34\elemskip}|
-
- %\check
-\noindent
-which means, when you use this \keyindex{NOtes} definition, that all
-\ital{spacing} notes and commands, results a spacing of 5.34 $\times$
-\keyindex{elemskip}.
-The size of the spatial unit (\keyindex{elemskip}) can be freely
-adjusted (it shows only effect outside \verb|\startpiece...\endpiece|).
-
- In practice, the choice of the macro \verb|\notes|, \verb|\Notes|,
-\verb|\NOtes|, etc., to initiate of column of notes sets an
-internal dimension register, named \keyindex{noteskip} to the given multiple
-of \keyindex{elemskip}. Thus, each \itxem{spacing note} (\keyindex{qu},
-\keyindex{qb}, \keyindex{hl}, etc.) will be followed by a spacing of
-\keyindex{noteskip}. Then, the advantage of the definition of \verb|\elemskip|
-is that, whenever it is changed, all subsequent \verb|\noteskip|s
-will be updated proportionally so that a simple change of \verb|\elemskip|
-can expand or shrink all consecutive note spacings as a whole.
-
-\medskip
-{\bf All said above counts only for first pass.}
-
-\medskip If the arthmetic progression of note spacings does not meet your
-wishes, your may force a geometric progression, where {\Bslash Notes} is
-$\sqrt{2}$ times wider as {\Bslash notes},  {\Bslash NOtes} is $\sqrt{2}$
-times wider as {\Bslash Notes}, etc. In that case, {\Bslash Notesp} is
-approximately $\sqrt{\sqrt{2}}=1.189$ times wider as {\Bslash Notes} and so
-on. The geometric progression if forced by the command
-\keyindex{geometricskipscale}, and the original arithmetic progression is
+\smallskip
+
+\noindent What each of these macros actually does is to set an
+internal dimension register \keyindex{noteskip} to the given multiple
+of the fundamental spacing unit \keyindex{elemskip}
+(which has dimensions of length, usually given in points).
+Normally, every \itxem{spacing note} (e.g.,
+\keyindex{qu},
+\keyindex{qb}, \keyindex{hl}) will then be followed by a spacing of
+width \keyindex{noteskip}.  By selecting a particular note spacing macro
+from the above table, the typesetter can thus control the relative spacing
+between notes.
+
+The actual spacing will therefore be determined by the value of
+\verb|\elemskip|. On the first pass, \TeX\ will set a default value for
+\verb|\elemskip| based on the declared music size, or the user can
+set it to any hard dimension he chooses. However, the value on the
+first pass doesn't matter as much as you might think (more about that later).
+On the second pass,
+\verb|musixflx| determines where the system breaks will come,
+and then computes the final value of \verb|\elemskip| for each system.
+
+If the arthmetic progression of note spacings in the above table does not
+meet your wishes, you may activate an alternate set with
+the command \keyindex{geometricskipscale}. As implied by the name, this
+is a geometric progression, where {\Bslash Notes} is
+$\sqrt{2}$ times wider than {\Bslash notes},  {\Bslash NOtes} is $\sqrt{2}$
+times wider than {\Bslash Notes}, and so forth.
+Then the factors in the middle column
+of the above table will be replaced by the sequence
+2.00, 2.38, 2.83, 3.36, 4.00, 4.76, 5.66, 6.72, and 8.00. Two additional
+macros, \verb|\NOTEsp| and \verb|\NOTES|, will be defined corresponding to
+factors 9.52 and 11.32. The original arithmetic progression can be
 restored by \keyindex{arithmeticskipscale}.
 
- Inside the pair \verb|\notes...\enotes| you may freely change the value of
-\verb|\noteskip| (not \verb|\elemskip|) provided you keep it scalable in the
-normal situation\footnote{But: provided you keep it \ital{not scalable} if
-you use the {\Bslash hardnotes} or {\Bslash hardlyrics} features (see
-\ref{lyrics}).}. \verb|\noteskip| can be changed with a command like
-
-\verb|\noteskip=2.4\noteskip|
-
-\noindent which obviously keeps it scalable, or by means of
-
-\keyindex{multnoteskip}\verb|{2.4}|
-
-\noindent which performs the same multiplication in a smarter way. You can
-also force all \verb|\noteskip|s to be re-scaled by a factor of 3.1415 using
-
-\keyindex{scale}\verb|{2.4}|
-
-\noindent or \verb|\def|\keyindex{scalenoteskip}\verb|{2.4}| which is more
-dangerous and not advises although compatible with \musictex.
-
-\medskip
-
-To fill the music line (system) without glue, the values of \verb|\elemskip|,
-\verb|\afterruleskip| and \verb|\beforeruleskip| are adjusted from the
-external program {\tt musixflx}\index{musixflx@{\tt musixflx}}. So what
-spacing you really get, depends on the internal line-breaking routine.
-
-Spacings for advanced \musixtex'ers: a `normal' bar (slightly~!) magnified:
-\medskip
+If neither of the predefined progressions satisfies you, you may define
+your own, using the more general macro \verb|\vnotes| in the same manner
+that \musixtex\ uses it for the predefined progressions. So for example
+\verb|\def\NOtes{\vnotes5.34\elemskip}| will redefine \verb|\NOtes| in
+the obvious way, and the extension to the other spacing macros should
+likewise be obvious.
+
+In addition, inside any pair \verb|\notes...\enotes| there are two
+equivalent ways to
+locally redefine \verb|\noteskip| to another scalable value, namely by
+issuing a command like
+\verb|\noteskip=2.4\noteskip| or \keyindex{multnoteskip}\verb|{2.4}|, which
+have the expected effect until the notes group is terminated or
+\verb|\noteskip| is further redefined.
+
+Finally, by issuing a command like
+\keyindex{scale}\verb|{2.4}| outside any notes group, you can scale all subsequent
+\verb|\noteskip|s by any desired factor.
+
+These facilities may be useful, for example,
+to control spacing when there are three equal duration notes in one staff against two
+ in another.
+
+%\subsubsection{\Bslash{\tt elemskip}, \Bslash{\tt beforeruleskip} and
+%\Bslash{\tt afterruleskip}}
+%
+% avr wants to call these "commands", but das doesn't.
+%\subsubsection{Commands {\Bslash\texttt{elemskip}},
+%{\Bslash\texttt{beforeruleskip}}
+%and {\Bslash\texttt{afterruleskip}}}
+\subsubsection{{\Bslash\texttt{elemskip}},
+{\Bslash\texttt{beforeruleskip}}
+and {\Bslash\texttt{afterruleskip}}}
+
+We've just seen how \verb|\elemskip| is used to scale the spacings between notes.
+There are two other spacing units that share some behavior with \verb|\elemskip|.
+\verb|\beforeruleskip| is the horizontal space that is automatically inserted
+\ital{before} every bar line, while \verb|\afterruleskip| goes \ital{after}
+every bar line. (In
+practice \verb|\beforeruleskip| is almost aways set to \verb|0pt| because there
+will typically already be a space of \verb|1\noteskip| before every barline.)
+On the first pass, just as with \verb|\elemskip|, \musixtex\ assigns them default
+values according to the following table:
+
+%\begin{quote}\begin{tabular}{lrrr}\hline
+%\ital{using}&\keyindex{elemskip}&\keyindex{afterruleskip}
+%  &\keyindex{beforeruleskip}\\\hline
+%\keyindex{normalmusicsize}&6pt&8pt&0pt\\
+%\keyindex{smallmusicsize}&4.8pt&6pt&0pt\\\hline
+%\end{tabular}\end{quote}
+
+\begin{center}\begin{tabular}{lrrr}\hline
+\ital{using}&\keyindex{elemskip}&\keyindex{afterruleskip}
+  &\keyindex{beforeruleskip}\\\hline
+\keyindex{normalmusicsize}&6pt&8pt&0pt\\
+\keyindex{smallmusicsize}&4.8pt&6pt&0pt\\\hline
+\end{tabular}\end{center}
 
+\noindent In the second pass, \verb|musixflx| assigns new values to each
+of these dimensions, a different set for each line or system. It does this
+in such a way that available scalable horizontal space in each system is
+exactly filled up.
+
+The values that are assigned to these dimensions on the first pass, whether by
+default or explicitly by the user or in some combination, only matter insofar
+as their relative sizes. That's why we earlier stated that the first-pass value
+of \verb|\elemskip| didn't matter as much as you might think. For both music sizes
+in the table above, it appears that by default \verb|\afterruleskip| is
+\verb|1.3333\elemskip|\footnote{Editor's note: It is a mystery why the authors
+%of \musixtex\ didn't simply define \Bslash{\tt beforeruleskip} and \Bslash{\tt afterruleskip} as
+%specific multiples of \Bslash{\tt elemskip}}.
+of \musixtex\ didn't simply define \Bslash\texttt{beforeruleskip} and \Bslash\texttt{afterruleskip} as
+specific multiples of \Bslash\texttt{elemskip}}.
+
+Note that if you do want to change any of these
+values, you have to do so \ital{after} setting the
+music size and before \verb|\startpiece|.
+
+Here is an example that illustrates the various dimensions under discussion:\\
  %\check
-\begin{music}
+\begin{music}\nostartrule
 \afterruleskip7pt
 \beforeruleskip2pt
 \parindent0pt
@@ -1361,7 +1562,7 @@ Spacings for advanced \musixtex'ers: a `normal' bar (slightly~!) magnified:
 \znotes\en
 \zchar{16}{\hbox to\beforeruleskip{\downbracefill}}%
 \zchar{19}{\hbox to\beforeruleskip{\hss d\hss}}%
-\endpiece
+\setemptybar\endpiece
 \end{music}
 \begin{quote}\begin{tabular}{l@{~$\rightarrow$~}l}
 a&\keyindex{afterruleskip}\\
@@ -1370,227 +1571,236 @@ c&\keyindex{NOtes}\verb| = \vnotes 4\elemskip|\\
 d&\keyindex{beforeruleskip}\\
 e&\keyindex{elemskip}
 \end{tabular}\end{quote}
-As default the values are set up as follows:
-\begin{quote}\begin{tabular}{lrrr}\hline
-\ital{using}&\keyindex{elemskip}&\keyindex{afterruleskip}
-  &\keyindex{beforeruleskip}\\\hline
-\keyindex{normalmusicsize}&6pt&8pt&0pt\\
-\keyindex{smallmusicsize}&4.8pt&6pt&0pt\\\hline
-\end{tabular}\end{quote}
-\begin{quote}
-If you want to change upper values, you have to do that behind
-\verb|\normalmusicsize| or \verb|\smallmusicsize| and before
-\verb|\startpiece|.
-\end{quote}
+
+\subsection{Moving from one staff or instrument to another}
+ \label{movingtostaffs}
+
+When entering notes inside \verb|\notes ... \enotes|, the usual way to suspend
+input for one instrument and start the next (higher) is with  the character
+``\verb|&|''\index{"&@{\tt\char'046}}. If the instrument has more than one
+staff, to switch to the next (higher) one you can use the character
+``\verb+|+''\index{"|@{\tt\char'174}}.
+
+There are some alternate navigation commands that may be useful in
+ special situations. Due to ``catcode
+problems'' (see section~\ref{catcodeprobs}) it may sometimes be necessary
+to use the more explicit commands
+\keyindex{nextinstrument} and \keyindex{nextstaff}, which have the same
+meanings as ``\verb|&|'' and ``\verb+|+'' respectively. To switch to the previous
+(next lower) staff of the same instrument, use \keyindex{prevstaff}. This might
+be useful if a beam starts in a higher staff than where it ends. More
+generally, to switch to an arbitrary instrument $n$, use
+\keyindex{selectinstrument}\onen, and to switch to an arbitrary staff $n$
+of the current instrument, use \keyindex{selectstaff}\verb|{|$n$\verb|}|. In the
+latter case if $n$ exceeds the number of staves defined for the instrument, you
+will receive an error message. You can enter part of a successive voice on
+\ital{same} staff by using \verb|\selectstaff{|$n$\verb|}| with $n$ for
+the \ital{current} staff.
+
 
  %\check
-\section{Note pitch specification}
- Note pitches are usually specified by letters ranging from \verb|a| to
-\verb|z| for those which are usually written under the G-clef (\verb|a|
-corresponds to the $A$ of nominal frequency 222.5~Hz; the \ital{G} of the
-G-clef is denoted \verb|g|). Lower pitch notes are specified using upper
-case letters ranging from \verb|A| to \verb|N| (the \ital{F} of the F-clef
-is denoted \verb|M|, and \verb|F| is one octave below).
-
- If necessary, a numeric symbol can be used to place a symbol
-independently of the active clef, which has the drawback not to be
-transposable.
-
- Besides, notes below \verb|A| (i.e. the $A$ of nominal frequency 55.625~Hz),
-namely the lowest octave of the modern pianos, can only be coded using the
-transposition features (see below: \ital{transposition} and
-\ital{octaviation}) or in absolute vertical position using numbers.
- \section{Writing notes}
-There are two major kinds of note macros: \begin{enumerate} \item those
-which terminate a note/chord stem and are followed by a horizontal spacing of
-value \keyindex{noteskip},
- \item those which initiate or extend a note/chord stem and do not cause
-horizontal spacing.
-\end{enumerate}
- The first kind is used to type a melody, the second kind is used to
-type chords.
- \subsection{Single spacing notes}
-\begin{quote}\begin{description}
- \item[\keyindex{breve}~$p$ :]breve note (\hbox to 8pt{\zbreve1\hss}) at pitch $p$.
- \item[\keyindex{longa}~$p$ :]longa note
-  (\hbox to8pt{\zlonga1\hss}) at pitch $p$.
- \item[\keyindex{longaa}~$p$ :]same as \verb|\longa|, with an ``automatic''
-stem up or down.
- \item[\keyindex{zmaxima}~$p$ :]maxima note
-  (\hbox to16pt{\zmaxima1\hss}) at pitch $p$.
- \item[\keyindex{wq}~$p$ :]arbitrary duration note (also used as alternate
-representation of \ital{breve} note)
-  (\hbox to8pt{\zwq1\hss}) at pitch $p$.
- \item[\keyindex{wqq}~$p$ :]long arbitrary duration note (also used as alternate
-representation of \ital{longa} note)
-  (\hbox to8pt{\zwqq1\hss}) at pitch $p$.
- \item[\keyindex{wh}~$p$ :]whole note at pitch $p$.
- \item[\keyindex{hu}~$p$ :]half note at pitch $p$ with stem up.
- \item[\keyindex{hl}~$p$ :]half note at pitch $p$ with stem down.
- \item[\keyindex{ha}~$p$ :]half note at pitch $p$ with automatic
-stem\footnote{This
-means all stems belonging to notes below the third line are stemmed up,
-the other down, they work with every clef, but only for single notes.} choice.
- \item[\keyindex{qu}~$p$ :]quarter note at pitch $p$ with stem up.
- \item[\keyindex{ql}~$p$ :]quarter note at pitch $p$ with stem down.
- \item[\keyindex{qa}~$p$ :]quarter note at pitch $p$ with ``automatic'' stem.
- \item[\keyindex{cu}~$p$ :]eighth note\footnote{The {\Bslash c} of this macro
- name is taken from the French word ``croche'' which is by the way one
- half of the english ``crotchet''; {\Bslash cc...}, {\Bslash ccc...}
- are standing for ``double croche'', ``triple croche'', etc.}
- at pitch $p$ with stem up.
- \item[\keyindex{cl}~$p$ :]eighth note at pitch $p$ with stem down.
- \item[\keyindex{ca}~$p$ :]eighth note at pitch $p$ with ``automatic'' stem.
- \item[\keyindex{ccu}~$p$ :]sixteenth note at pitch $p$ with stem up.
- \item[\keyindex{ccl}~$p$ :]sixteenth note at pitch $p$ with stem down.
- \item[\keyindex{cca}~$p$ :]sixteenth note at pitch $p$ with ``automatic'' stem.
- \item[\keyindex{cccu}~$p$ :]32-th note at pitch $p$ with stem up.
- \item[\keyindex{cccl}~$p$ :]32-th note at pitch $p$ with stem down.
- \item[\keyindex{ccca}~$p$ :]32-th note at pitch $p$ with ``automatic'' stem.
- \item[\keyindex{ccccu}~$p$ :]64-th note at pitch $p$ with stem up.
- \item[\keyindex{ccccl}~$p$ :]64-th note at pitch $p$ with stem down.
- \item[\keyindex{ccccl}~$p$ :]64-th note at pitch $p$ with ``automatic'' stem.
+\section{Note pitch specification}\label{pitchspec}
+Note pitches can be specified either by letters or numbers. If no transposition
+or octaviation is in effect, letters ranging
+from \verb|a| to \verb|z| represent notes starting with the A below
+middle C. Upper case letters from \verb|A| to \verb|N| represent pitches
+two octaves lower than their lower case counterparts. Any letter can be used in
+any clef, but some users may
+prefer to use the lower case letters in treble clef, and the upper case ones
+in bass clef.
+
+Alternatively, a one- or two-digit, positive or negative integer can always be used.
+The number represents
+the vertical position on the staff, with \verb|0| for the lowest line and
+\verb|1| for the space right above, \ital{regardless of the clef}.
+Unlike with letters, the
+associated pitch will depend on the clef, and notes entered this way are
+immune to transposition and octaviation.
+
+Notes lower than \verb|A| and higher than \verb|z| can be entered, with
+either numbers as just described, or with octaviation as will be explained in
+section~\ref{octaviation}.
+
+ \section{Writing notes}\label{autostemdirections}
+There are two major kinds of note macros, those that include a space (of
+length \keyindex{noteskip}) after
+the printed symbol, and those that don't cause any space. A single-line melody would be
+written using the first type. All notes of a chord except the last would
+use the second.
+
+Another distinction concerns stemmed notes. Some macros explicitly set the
+stem direction with either ``\verb|u|'' or ``\verb|l|'' contained in the name of
+the macro. On the other hand, an ``\verb|a|'' in the macro's name usually signifies
+\ital{automatic} stem direction selection. In this case notes below the middle
+staff line will get up stems, otherwise down.
+
+ \subsection{Normal (unbeamed) spacing notes}\label{NormalNotes}
+In the following, \verb|{|$p$\verb|}| signifies a pitch specification as
+described in sections~\ref{pitchspec} and \ref{octaviation}. However it
+is understood that if the pitch is a single character, the brackets are
+not neecessary, provided that if it is a letter, a space separates the
+macro from the letter.
+
+
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+ \item[\keyindex{breve}{\tt\char123}$p${\tt\char125} :]breve (\hbox to 8pt{\zbreve1\hss}) .
+ \item[\keyindex{longa}{\tt\char123}$p${\tt\char125} :]longa (\hbox to8pt{\zlonga1\hss}) .
+ \item[\keyindex{longaa}{\tt\char123}$p${\tt\char125} :]longa with automatic stem
+direction\footnote{Editor's note: Evidently there is no explicit up-stemmed longa} .
+ \item[\keyindex{zmaxima}{\tt\char123}$p${\tt\char125} :]maxima(\hbox to16pt{\zmaxima1\hss}) .
+ \item[\keyindex{wq}{\tt\char123}$p${\tt\char125} :]arbitrary duration note (\hbox to8pt{\zwq1\hss})
+(also used as alternate representation of a \ital{breve}).
+ \item[\keyindex{wqq}{\tt\char123}$p${\tt\char125} :]long arbitrary duration note
+(\hbox to8pt{\zwqq1\hss}) (also used as alternate
+representation of a \ital{longa}).
+ \item[\keyindex{wh}{\tt\char123}$p${\tt\char125} :]whole note.
+ \item[\keyindex{hu}{\tt\char123}$p${\tt\char125} :]half note with stem up.
+ \item[\keyindex{hl}{\tt\char123}$p${\tt\char125} :]half note with stem down.
+ \item[\keyindex{ha}{\tt\char123}$p${\tt\char125} :]half note with automatic stem direction
+ \item[\keyindex{qu}{\tt\char123}$p${\tt\char125} :]quarter note with stem up.
+ \item[\keyindex{ql}{\tt\char123}$p${\tt\char125} :]quarter note with stem down.
+ \item[\keyindex{qa}{\tt\char123}$p${\tt\char125} :]quarter note with automatic stem direction.
+ \item[\keyindex{cu}{\tt\char123}$p${\tt\char125} :]eighth note\footnote{The ``{\tt c}''
+within this macro name stands for the equivalent British term ``crotchet''} with stem up.
+ \item[\keyindex{cl}{\tt\char123}$p${\tt\char125} :]eighth note with stem down.
+ \item[\keyindex{ca}{\tt\char123}$p${\tt\char125} :]eighth note with automatic stem direction.
+ \item[\keyindex{ccu}{\tt\char123}$p${\tt\char125} :]sixteenth note with stem up.
+ \item[\keyindex{ccl}{\tt\char123}$p${\tt\char125} :]sixteenth note with stem down.
+ \item[\keyindex{cca}{\tt\char123}$p${\tt\char125} :]sixteenth note with automatic stem direction.
+ \item[\keyindex{cccu}{\tt\char123}$p${\tt\char125} :]32nd note with stem up.
+ \item[\keyindex{cccl}{\tt\char123}$p${\tt\char125} :]32nd note with stem down.
+ \item[\keyindex{ccca}{\tt\char123}$p${\tt\char125} :]32nd note with automatic stem direction.
+ \item[\keyindex{ccccu}{\tt\char123}$p${\tt\char125} :]64nd note with stem up.
+ \item[\keyindex{ccccl}{\tt\char123}$p${\tt\char125} :]64nd note with stem down.
+ \item[\keyindex{ccccl}{\tt\char123}$p${\tt\char125} :]64nd note with automatic stem direction.
 \end{description}\end{quote}
- As an example, the sequence:
+ As an example, the sequence
 
  %\check
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\cu c\cl j\enotes\bar
 \Notes\ccu c\ccl j\enotes\bar
 \Notes\cccu c\cccl j\enotes\bar
 \Notes\ccccu c\ccccl j\enotes
-\endextract
+\zendextract
 \end{music}
- \noindent was coded as:
+ \noindent was coded as
 \begin{quote}\begin{verbatim}
 \Notes\cu c\cl j\enotes\bar
 \Notes\ccu c\ccl j\enotes\bar
 \Notes\cccu c\cccl j\enotes\bar
 \Notes\ccccu c\ccccl j\enotes
 \end{verbatim}\end{quote}
- If these notes are preceded by \ital{non-spacing} notes (i.e.
-macros \keyindex{zq} or \keyindex{zh}) their stem is extended up or down so
-as to join all notes into a single chord.
- \subsection{Non-spacing (chord) notes}
-\begin{quote}\begin{description}
- \item[\keyindex{zq}~$p$ :]quarter (or shorter) note head at pitch $p$ with no
-spacing after.
- \item[\keyindex{zh}~$p$ :]half note head at pitch $p$ with no spacing after.
-\end{description}\end{quote}
- It must be pointed out that the pitch $p$ of these notes is
-memorized so that the stem of the further spacing note will join them into
-a chord. This stem top and bottom pitch is \ital{reset} at each spacing
-note.
-
- \begin{remark} Notes of duration longer than whole notes are
-always non-spacing. This saves one useless definition, since these notes are
-always longer than other simultaneous ones. If needed they can be followed by
-\keyindex{sk} to force spacing.
-\end{remark}
 
- \subsection{Shifted non-spacing (chord) heads} These symbols are used mainly
-in chords where \ital{second} intervals are present. It is the
-responsibility of the typist to choose which heads should be shifted left or
-right.
-
-\begin{quote}\begin{description}
-\item[\keyindex{rw}~$p$ :]whole note head shifted right by one note
-width ($\approx$ 6pt), no spacing.
-\item[\keyindex{lw}~$p$ :]whole note head shifted left by one note
-width ($\approx$ 6pt), no spacing.
-\item[\keyindex{rh}~$p$ :]half note head shifted right by one note
-width ($\approx$ 6pt), no spacing.
-\item[\keyindex{lh}~$p$ :]half note head shifted left by one note
-width ($\approx$ 6pt), no spacing.
-\item[\keyindex{rq}~$p$ :]quarter note head shifted right by one note
-width ($\approx$ 6pt), no spacing.
-\item[\keyindex{lq}~$p$ :]quarter note head shifted left by
-one note width ($\approx$ 6pt), no spacing.
+ \subsection{Non-spacing note heads}
+These macros are used to create chords. Any number of them can be entered
+in sequence, followed by a spacing note. All of the note heads will be
+joined to the spacing note and the stem length will automatically be adjusted
+as needed.
+
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+ \item[\keyindex{zq}{\tt\char123}$p${\tt\char125} :]quarter (or shorter) note head.
+ \item[\keyindex{zh}{\tt\char123}$p${\tt\char125} :]half note head.
+\end{description}\end{quote}
+%das ???
+% \begin{remark} Notes of duration longer than whole notes are
+%always non-spacing. This saves one useless definition, since these notes are
+%always longer than other simultaneous ones. If needed they can be followed by
+%\keyindex{sk} to force spacing.
+%\end{remark}
+
+ \subsection{Shifted non-spacing note heads}
+These symbols are used mainly
+in chords containing an interval of a \ital{second}. They provide note
+heads shifted either to the left or right of the default position by
+the width of one note head.
+
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+\item[\keyindex{rw}{\tt\char123}$p${\tt\char125} :]whole note head shifted right.
+\item[\keyindex{lw}{\tt\char123}$p${\tt\char125} :]whole note head shifted left.
+\item[\keyindex{rh}{\tt\char123}$p${\tt\char125} :]half note head shifted right\footnote{Some may not
+have realized that half and whole note heads have different shapes}.
+\item[\keyindex{lh}{\tt\char123}$p${\tt\char125} :]half note head shifted left.
+\item[\keyindex{rq}{\tt\char123}$p${\tt\char125} :]quarter note head shifted right.
+\item[\keyindex{lq}{\tt\char123}$p${\tt\char125} :]quarter note head shifted left.
 \end{description}\end{quote}
- %\check
 
- Except that they are shifted left of right, these macros act like
-\verb|\z...| macros for stem building.
- \subsection{Single non-spacing notes}
-\begin{quote}\begin{description}
- \item[\keyindex{zhu} :]half note with stem up but no spacing. It acts like
-\verb|\hu| for stem building.
- \item[\keyindex{zhl} :]half note with stem down but no spacing. It acts like
-\keyindex{hl} for stem building.
- \item[\keyindex{zqu} :]quarter note with stem up but no spacing. It acts like
-\verb|\qu| for stem building.
- \item[\keyindex{zql} :]quarter note with stem down but no spacing. It acts
-like \verb|\ql| for stem building.
- \item[\keyindex{zcu}, \keyindex{zccu}, \keyindex{zcccu}, \keyindex{zccccu}
-:]eighth, ..., note with stem up but no spacing. It acts like
-\verb|\cu| for stem building.
- \item[\keyindex{zcl}, \keyindex{zccl}, \keyindex{zcccl}, \keyindex{zccccl}
-:]eighth, ..., note with stem down but no spacing. It acts
-like \verb|\cl| for stem building.
- \item[\keyindex{zqb} :]note belonging to a beam but no spacing.
- \item[\keyindex{rhu}, \keyindex{rhl}, \keyindex{rqu}, \keyindex{rql},
+ \subsection{Non-spacing notes}
+These macros provide normal notes, with stems if applicable, but without any
+following space.
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+ \item[\keyindex{zhu}\pitchp~:]half note with stem up but no spacing. It acts like
+\verb|\hu| for chord building, i.e., it will join together any immediately
+preceding non-spacing note heads.
+ \item[\keyindex{zhl}\pitchp~:]half note with stem down but no spacing. It acts like
+\keyindex{hl} for chord building.
+ \item[\keyindex{zqu}\pitchp~:]quarter note with stem up but no spacing. It acts like
+\verb|\qu| for chord building.
+ \item[\keyindex{zql}\pitchp~:]quarter note with stem down but no spacing. It acts
+like \verb|\ql| for chord building.
+ \item[\keyindex{zcu}\pitchp, \keyindex{zccu}, \keyindex{zcccu}, \keyindex{zccccu}
+:]eighth, ..., note with stem up but no spacing. They act like
+\verb|\cu| for chord building.
+ \item[\keyindex{zcl}\pitchp, \keyindex{zccl}, \keyindex{zcccl}, \keyindex{zccccl}
+:]eighth, ..., note with stem down but no spacing. They act
+like \verb|\cl| for chord building.
+ \item[\keyindex{zqb}\pitchp~:]note belonging to a beam but no spacing. (DAS: put this later!)
+ \item[\keyindex{rhu}\pitchp, \keyindex{rhl}, \keyindex{rqu}, \keyindex{rql},
   \keyindex{rcu}, \keyindex{rcl} :] \verb|\rhu| acts like \verb|\zhu|,
-  but the note is shifted one note width on the right, other analogous.
- \item[\keyindex{lhu}, \keyindex{lhl}, \keyindex{lqu}, \keyindex{lql},
+  but the note is shifted one note width to the right; others analogous.
+ \item[\keyindex{lhu}\pitchp, \keyindex{lhl}, \keyindex{lqu}, \keyindex{lql},
   \keyindex{lcu}, \keyindex{lcl} :]same
-  as above, but the whole of the note is shifted one note width on the left.
- \item[\keyindex{zw}~$p$ :]whole note at pitch $p$ with no spacing after.
- \item[\keyindex{zwq}~$p$ :]arbitrary duration note
-  (\hbox to8pt{\zwq1\hss}) at pitch $p$ with no spacing after.
- \item[\keyindex{zbreve}~$p$ :]breve note
-  (\hbox to8pt{\zbreve1\hss}) at pitch $p$ with no spacing after.
- \item[\keyindex{zlonga}~$p$ :]longa note
-  (\hbox to8pt{\zlonga1\hss}) at pitch $p$ with no spacing after.
- \item[\keyindex{zmaxima}~$p$ :]maxima note
-  (\hbox to16pt{\zmaxima1\hss}) at pitch $p$ with no spacing after.
+  as above, but the note is shifted one note width to the left.
+ \item[\keyindex{zw}\pitchp~:]whole note with no following space.
+ \item[\keyindex{zwq}\pitchp~:]arbitrary duration note
+  (\hbox to8pt{\zwq1\hss}) with no following space.
+ \item[\keyindex{zbreve}\pitchp~:]breve
+  (\hbox to8pt{\zbreve1\hss}) with no following space.
+ \item[\keyindex{zlonga}\pitchp~:]longa
+  (\hbox to8pt{\zlonga1\hss}) with no following space.
+ \item[\keyindex{zmaxima}\pitchp~:]maxima
+  (\hbox to16pt{\zmaxima1\hss}) with no following space.
 \end{description}\end{quote}
  %\check
 
+\subsection{Spacing note heads}
 
-\subsection{Single (spacing) stemless notes}
-
- Although not standard in real music scores, one may need to have stemless
-quarter and half note heads posted in the same way as whole notes. This can be
-done with the following commands:
+Although not needed in normal music scores, these may be useful in
+very special cases.
 
-\begin{quote}\begin{description}
-\item[\keyindex{nh}~$p$ :]half note head at pitch $p$.
-\item[\keyindex{nq}~$p$ :]quarter note head at pitch $p$.
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+\item[\keyindex{nh}{\tt\char123}$p${\tt\char125} :]spacing half note head.
+\item[\keyindex{nq}{\tt\char123}$p${\tt\char125} :]spacing quarter note head.
 \end{description}\end{quote}
 
-\medskip As an example, the sequence:
+\noindent As an example, the sequence
 
-\begin{music}
+\begin{music}\nostartrule
  \startextract
 \notes\nq c\nq j\enotes\barre
 \Notes\nh c\nh j\enotes\barre
 \notes\nq {cdef}\enotes
-\endextract
+\zendextract
 \end{music}
 
-\medskip \noindent was coded as:
+\noindent was coded as
 
-%\check
 \begin{quote}\begin{verbatim}
 \notes\nq c\nq j\enotes\barre
 \Notes\nh c\nh j\enotes\barre
 \notes\nq {cdef}\enotes
 \end{verbatim}\end{quote}
 
- In case of special need, non spacing variants have been provided, namely
+Non spacing variants are also provided, namely
 \keyindex{znh} and \keyindex{znq}.
+% DAS: why???
 
+ \subsection{Dotted notes}\label{dots}
 
- \subsection{Pointed notes}
-One simple way of doing consists in putting \keyindex{pt
-$p$} to get a \ital{dot} after the normal note head at pitch $p$. Thus a
-quarter note with one point can be coded \verb|\pt h\qu h|, with two points
-as \keyindex{ppt}\verb|\qu h| and with three points as
-\keyindex{pppt}\verb|\qu h|.
-
- A simpler way of doing consists in using compact macros, namely:
-\keyindex{whp}, \keyindex{whpp},
+By appending one or two \verb|p|'s (for ``pointed'') to the name, many of the
+macros just introduced provide one or two dots after the notehead:
+\keyindex{whp}\pitchp, \keyindex{whpp},
 \keyindex{zwp}, \keyindex{zwpp},
 \keyindex{hup}, \keyindex{hupp},
 \keyindex{hlp}, \keyindex{hlpp},
@@ -1601,188 +1811,250 @@ as \keyindex{ppt}\verb|\qu h| and with three points as
 \keyindex{cup}, \keyindex{cupp},
 \keyindex{clp}, \keyindex{clpp},
 \keyindex{qbp} and \keyindex{qbpp}.
-Where all \verb|\z...p| are useful in chords.
-
- You may also introduce pointed notes, especially in groups by coding
-a \ital{period} before (not after) the letter representing the pitch:
-\verb|\qu{.a.^b.c}| which is equivalent to:
-\begin{quote}\begin{verbatim}
-\pt{a}\qu{a}\pt{b}\sh{b}\qu{b}\pt{c}\qu{c}
-\end{verbatim}\end{quote}
-Finally, pointed notes can also be produced without spacing after, using
+Naturally, the ones that start with ``\verb|z|'' are used in chords.
+The dot(s) will be raised if the note is on a line.
+
+A more explicit way uses one of the macros \keyindex{pt}{\tt\char123}$p${\tt\char125},
+\keyindex{ppt}, or \keyindex{pppt} right
+before any note macro to place one to three dots after the normal note
+head at pitch $p$. Again they will be raised if on a line. In fact this is the only
+way to get a triple-dotted note.
+For example a
+quarter note with one dot could be coded \verb|\pt h\qu h|, with two dots
+as \keyindex{ppt}\verb| h\qu h| and with three as
+\keyindex{pppt}\verb| h\qu h|.
+
+Yet another method for posting a dot is to insert a \ital{period} before
+the letter representing the pitch. Thus \verb|\qu{.a}| is equivalent to
+either \verb|\pt a\qu a| or \verb|\qup a| . This may be useful when
+using \ital{collective coding}, which will be discussed in the next
+section.
+
+Non-spacing dotted notes can be produced using
 \keyindex{zhup}, \keyindex{zhlp}, \keyindex{zqup}, \keyindex{zqlp},
 \keyindex{zcup}, \keyindex{zclp}, \keyindex{zqbp},
-and the same with two \verb|p|'s for
-double-pointed notes, like \keyindex{zhupp}, \keyindex{zhlpp},
-\keyindex{zqupp}, \keyindex{zqlpp},
-\keyindex{zcupp}, \keyindex{zclpp} and \keyindex{zqbpp}.
-
-If two voices share one staff, the points of the lower voice are lowered,
-if the note is on a note line. Therefore you can use \keyindex{lpt}~$p$ and
-\keyindex{lppt}~$p$.
+and similarly with two \verb|p|'s for
+double-dotted notes.
+
+As a matter of style, if two voices share one staff, the dots in
+the lower voice should be lowered if the note is on a line. For
+this you can use \keyindex{lpt}{\tt\char123}$p${\tt\char125} and
+\keyindex{lppt}{\tt\char123}$p${\tt\char125}.
+
+\subsection{Sequences of equally spaced notes; collective coding}
+\label{CollectiveCoding}
+
+It isn't necessary to write a separate macro
+sequence \verb|\notes...\enotes| for every individual column of notes.
+Rather, a single such macro can contain all the notes in all staves
+over an extended horizontal range, as long as all spacings are equal or
+multiples of a unique value of \keyindex{noteskip}.
+The notes in each staff could be entered one after another as normal
+spacing notes as already described in section~\ref{NormalNotes}. Then
+each spacing note will cause the insertion point to advance horizontally by the
+operative value of \verb|\noteskip| defined by the choice of
+\verb|\notes|, \verb|\Notes|, \verb|\NOtes|, etc. Of course in such sequences
+non-spacing chord notes can be entered right before their associated
+spacing note. If you need to skip forward by one \verb|\noteskip|, for
+example after a quarter note when there are two eighth notes in
+another staff, you can use \keyindex{sk}.
+
+If there are only spacing notes in such a sequence, a further
+simplification is available, called \ital{collective coding}. For instance
+\verb|\qu{cdefghij}| writes the C major scale in quarters with
+up stems. Similarly \verb|\cl{abcdef^gh}| writes the
+\ital{A-minor} scale in non-beamed eighths. (Here ``\verb|^|'' represents
+a sharp). If necessary a void can be inserted in a collective coding sequence
+by using~\verb|*|\index{*}. Not all note generating macros can be
+used to perform collective coding, but most of them can.
 
- %\check
 \section{Beams}
-
- Beams are not automatically handled, but they must be declared explicitely,
-\ital{before} the first spacing note involving them is coded. Two kinds of
-macros are provided:
-
-\begin{enumerate}
-
- \item fixed slope beams have an arbitrary slope chosen by the user in
-the range -45\% to +45\% (by multiples of 5\%);
-
- \item semi-automatic beams have their slope computed knowing the number
-of \keyindex{noteskip} over which they are supposed to extend, and knowing the
-initial and final pitch of the notes they are supposed to link.
-\end{enumerate}
- %\check
- \subsection{Fixed slope beams}
- \subsubsection{Beam initiation}
-\begin{quote}\begin{description}
- \item[\keyindex{ibu}~$nps$ :]initiates an \ital{upper beam} 3 horizontal
-line spacings above the pitch $p$~; $n$ is its reference number, which must be
-in the range [0-5] ([0-8] if \verb|musixadd| file has been \verb|\input|);
-$s$ is the slope of the beam.
-\end{description}\end{quote}
- $s$ is an integer in the range [-9,9].
-$s=1$ means a slope of 5\%, $s=9$ means a slope of 45\%,
-$s=-3$ means a slope of -15\%, etc.
-With usual spacings a slope of 2 or 3 is fit for ascending scales. A slope of
-6 to 9 is fit for ascending arpeggios.
-
-\begin{quote}\begin{description}
-
- \item[\keyindex{ibl}~$nps$ :]initiates a \ital{lower beam} 3 horizontal line
-spacings below the pitch $p$. Other parameters as above.
-
- \item[\keyindex{ibbu}~$nps$ :]initiates a \ital{double upper beam} (same
-parameter meaning).
- \item[\keyindex{ibbl}~$nps$ :]initiates a \ital{double lower beam} (same
-parameter meaning).
- \item[\keyindex{ibbbu}~$nps$ :]initiates a \ital{triple upper beam} (same
-parameter meaning).
- \item[\keyindex{ibbbl}~$nps$ :]initiates a \ital{triple lower beam} (same
-parameter meaning).
- \item[\keyindex{ibbbbu}~$nps$ :]initiates a \ital{quadruple upper beam} (same
-parameter meaning).
- \item[\keyindex{ibbbbl}~$nps$ :]initiates a \ital{quadruple lower beam} (same
-parameter meaning).
+\subsection{Starting a beam}
+
+Each beam must be declared with a macro issued before the first spacing
+note under the beam is coded. Two distinct kinds of macros are provided
+for this. The first kind initiates a ``fixed-slope'' beam, with an arbitrary
+slope and starting height chosen by the user, while the second kind, a
+``semi-automatic'' beam,
+\ital{computes}~the slope and, in addition, adjusts the starting height in some
+cases.
+
+\def\nps{{\tt\char123}$n${\tt\char125}\pitchp{\tt\char123}$s${\tt\char125}}
+
+The basic form of the macros for starting fixed-slope beams is exemplified
+by the one for a single upper beam, \keyindex{ibu}\nps. Here
+$n$ is the reference number of the beam, $p$ the starting ``pitch'', and
+$s$ the slope. The reference number is assigned by the user. By default it must be
+in the range [0-5], but the maximum can be increased to 8 or 11 respectively
+if \verb|musixadd| or \verb|musixmad| has been \verb|\input|. The beam number is
+needed because more than one beam may be open at a time, and it
+tells \musixtex\ to which beam subsequent beamed notes and other beam specification
+commands are assigned. The ``pitch'' parameter is a pitch that is three
+staff spaces \ital{below} the bottom of the heavy connecting bar (\ital{above}
+the bar for a lower beam); in many (but not all)
+cases it should be input as the actual pitch of the first note. The slope $s$
+is an integer in the range [-9,9]. When multipled
+by 5\%~it gives the actual slope of the heavy bar. Typically a slope of 2 or 3
+is OK for ascending scales, and 6 to 9 for ascending arpeggios.
+
+The full set of fixed-slope beam initiation macros is as follows:
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+
+ \item[\keyindex{ibu}\nps~:]initiates an \ital{upper beam}.
+ \item[\keyindex{ibl}\nps~:]initiates a \ital{lower beam}.
+ \item[\keyindex{ibbu}\nps~:]initiates a \ital{double upper beam}.
+ \item[\keyindex{ibbl}\nps~:]initiates a \ital{double lower beam}.
+ \item[\keyindex{ibbbu}\nps~:]initiates a \ital{triple upper beam}.
+ \item[\keyindex{ibbbl}\nps~:]initiates a \ital{triple lower beam}.
+ \item[\keyindex{ibbbbu}\nps~:]initiates a \ital{quadruple upper beam}.
+ \item[\keyindex{ibbbbl}\nps~:]initiates a \ital{quadruple lower beam}.
 \end{description}\end{quote}
 
-Notes belonging to beams are coded in the form \keyindex{qb}~$np$ where $n$ is
-the beam number and $p$ the pitch of the note head. \musixtex\ adjusts the
-length of the note stem to link the bottom of the chord to a beam.
-
- \subsubsection{Beam termination}
- Beam termination is also not automatic. The termination of a given
-beam must be explicitely declared \ital{before} coding the last spacing note
-connected to that beam.
-\begin{quote}\begin{description}
- \item[\keyindex{tbu}~$n$ :]terminates upper beam number $n$ at current
-position. \item[\keyindex{tbl}~$n$ :]terminates lower beam number $n$ at
-current position.
-\end{description}\end{quote}
-\keyindex{tbu} and \keyindex{tbl} terminate beams of any
-multiplicity. Therefore 32-th notes hanging on a triple beam are initiated by
-\keyindex{ibbbu}~$nps$ and terminated by \keyindex{tbu}~$n$.
-
- Since beams usualy finish with a \verb|\qb| to link the last note, shorter
-macros have been provided:
-
- \begin{itemize}
-
- \item \keyindex{tqb} $np$ is equivalent to \verb|\tbl| $n$\verb|\qb| $np$
+A semi-automatic beam is initiated with a command that has \ital{four}
+parameters, the beam number, the first and last pitches, and the total
+horizontal extent in
+\verb|\noteskip|s, based on the value in effect at the start. For example,
+if you input \verb|\Ibu2gj3|, \musixtex\ will understand that you want to
+build an upper beam (beam number 2) horizontally extending \verb|3\noteskip|,
+the first note of which is a \verb|g| and the last note a \verb|j|.
+Knowing these parameters it will choose the highest slope number that
+corresponds to a slope not more than $(\hbox{\tt j}-\hbox{\tt
+g})/(3\keyindex{noteskip})$. The nominal height of the heavy bar is offset the same as
+for fixed-slope beams. However, if there is no sufficiently steep beam
+slope available, then \musixtex\ will raise (or lower) the starting point.
 
- \item \keyindex{tqh} $np$ is equivalent to \verb|\tbu| $n$\verb|\qb| $np$
+ Eight such macros are available: \keyindex{Ibu}, \keyindex{Ibbu},
+\keyindex{Ibbbu}, \keyindex{Ibbbbu}, \keyindex{Ibl}, \keyindex{Ibbl},
+\keyindex{Ibbbl} and \keyindex{Ibbbbl}.
 
- \item \keyindex{ztqb} $np$ is equivalent to \verb|\tbl| $n$\verb|\zqb| $np$
-(no spacing after)
+\subsection{Adding notes to a beam}
 
- \item \keyindex{ztqh} $np$ is equivalent to \verb|\tbu| $n$\verb|\zqb| $np$
-(no spacing after)
+Spacing notes belonging to beams are coded with the macro
+\keyindex{qb}\verb|{|$n$\verb|}|\pitchp~where $n$ is
+the beam number and $p$ the pitch of the note. \musixtex\ adjusts the
+length of the note stem to link to the beam.
 
- \end{itemize}
+Chord notes within a beam are entered before the main note with the
+non-spacing macro \keyindex{zqb}\verb|{|$n$\verb|}|\pitchp. Again,
+the stem length will be automatically adjusted as required.
 
- \subsubsection{Beams of increasing multiplicity}
- It is also possible to code beams whose multiplicity is not the same
-at the beginning. The multiplicity can be increased at any position. For
-instance, \keyindex{nbbu}~$n$ which sets the multiplicity of upper beam
-number $n$ to 2 starting at the current position, \keyindex{nbbbu}~$n$ sets
-its multiplicity to 3 and \keyindex{nbbbbu}~$n$ sets its multiplicity to 4.
-\keyindex{nbbl}~$n$ \dots
-\keyindex{nbbbbl}~$n$ perform the same functions for lower beams.
+There are also special macros for semi-automatic beams with
+two, three, or four notes:
+\keyindex{Dqbu}, \keyindex{Dqbl}, \keyindex{Dqbbu}, \keyindex{Dqbbl},
+\keyindex{Tqbu}, \keyindex{Tqbl}, \keyindex{Tqbbu}, \keyindex{Tqbbl},
+\keyindex{Qqbu}, \keyindex{Qqbl}, \keyindex{Qqbbu} and \keyindex{Qqbbl}.
+  %\check
+For example \verb|\Dqbu gh| is equivalent to \verb|Iqbu1gh\qb1 g\tbu1\qb1 h|,
+except that the special macros don't require a beam number.
+Their use is illustrated in the following example:
 
+\medskip
+\begin{music}\nostartrule
+\parindent0pt\startpiece
+\Notes\Dqbu gh\Dqbl jh\en
+\notes\Dqbbu fg\Dqbbl hk\en\bar
+\Notes\Tqbu ghi\Tqbl mmj\en
+\notes\Tqbbu fgj\Tqbbl njh\en\bar
+\Notes\Qqbu ghjh\Qqbl jifh\en
+\notes\Qqbbu fgge\Qqbbl jhgi\en\setemptybar\endpiece
+\end{music}
+\noindent This was coded as\footnote{Editor's note: Most music
+typesetting books recommend beam slopes that are \ital{less} than
+the slope between the starting and ending note; these macros cannot
+provide that.}:
+\begin{quote}\begin{verbatim}
+\Notes\Dqbu gh\Dqbl jh\en
+\notes\Dqbbu fg\Dqbbl hk\en\bar
+\Notes\Tqbu ghi\Tqbl mmj\en
+\notes\Tqbbu fgj\Tqbbl njh\en\bar
+\Notes\Qqbu ghjh\Qqbl jifh\en
+\notes\Qqbbu fgge\Qqbbl jhgi\en
+\end{verbatim}\end{quote}
+ %\check
 
- Note that the difference between upper and lower beams does not
-mainly consist in the beam being above or below the note heads; rather, it
-specifies whether the abscissa of the beginning and the end of this beam is
-aligned on the right (upper beam) or on the left (lower) beam. Thus, the
-sequence:
+ \subsection{Ending a beam}
+ The termination of a given
+beam must be declared \ital{before} coding the last spacing note
+connected to that beam. The macros for doing that are
+\keyindex{tbu}\verb|{|$n$\verb|}| for an upper beam and
+\keyindex{tbl}\verb|{|$n$\verb|}| for a lower one. These work for
+beams of any
+multiplicity. So for example an upper triple beam with
+32nd notes is initiated by
+\verb|\ibbbu|\nps\ but terminated by \verb|\tbu{|$n$\verb|}|.
+
+ Since beams usually finish with a \verb|\qb| for the last note, the
+following shortcut macros have been provided:
+
+\def\enpee{{\tt{\char123$n$\char125\char123$p$\char125}}}
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
+ \item \keyindex{tqb}\enpee~is equivalent to \verb|\tbl{|$n$\verb|}\qb|\enpee~.
+ \item \keyindex{tqh}\enpee~is equivalent to \verb|\tbu{|$n$\verb|}\qb|\enpee~.
+ \item \keyindex{ztqb}\enpee~is equivalent to \verb|\tbl{|$n$\verb|}\zqb|\enpee~,
+i.e., no spacing afterwards.
+ \item \keyindex{ztqh}\enpee~is equivalent to \verb|\tbu{|$n$\verb|}\zqb|\enpee~,
+i.e., no spacing afterwards.
+\end{description}\end{quote}
 
-\begin{music}
+\subsection{Changing multiplicity after the beam starts}
+Multiplicity (the number of heavy bars) can be increased at any position after
+the beam starts. The commands are \keyindex{nbbu}\onen~which increases the multiplicity of
+upper beam
+number $n$ to two starting at the current position, \keyindex{nbbbu}\onen~to
+increase it to three, and \keyindex{nbbbbu}\onen~to increase to four. The
+commands \keyindex{nbbl}\onen\dots\keyindex{nbbbbl}\onen~do the same
+for lower beams.
+Thus, the
+sequence
+
+\begin{music}\nostartrule
 \startextract
 \Notes\ibu0h0\qb0e\nbbu0\qb0e\nbbbu0\qb0e\nbbbbu0\qb0e\tbu0\qb0e\enotes
-\endextract
+\zendextract
 \end{music}
 \noindent has been coded as
 \begin{quote}\begin{verbatim}
 \Notes\ibu0h0\qb0e\nbbu0\qb0e\nbbbu0\qb0e\nbbbbu0\qb0e\tbu0\qb0e\enotes
 \end{verbatim}\end{quote}
 
- It is quite possible to terminate with \keyindex{tbu} a beam initiated
-with \keyindex{ibl}. This may give:
-
-\begin{music}
-\startextract
-\Notes\ibl0p0\qb0p\nbbl0\qb0p\nbbbl0\qb0p\tbu0\qb0e\enotes
-\endextract
-\end{music}
-\noindent which has been coded as
-\begin{quote}\begin{verbatim}
-\Notes\ibl0p0\qb0p\nbbl0\qb0p\nbbbl0\qb0p\tbu0\qb0e\enotes
-\end{verbatim}\end{quote}
- \subsubsection{Beams of decreasing multiplicity}
- Partial termination of beams is also possible, by using \keyindex{tbbu}
-or \keyindex{tbbl}~: these macros terminate the current beam except that of
-order 1 (eighths). \keyindex{tbbbu} or \keyindex{tbbbl} terminate the current
-beam except those of order 1 and 2, etc.
+To decrease multiplicity to one, use \keyindex{tbbu}\onen~or
+\keyindex{tbbl}\onen. To decrease to two or three use
+\keyindex{tbbbu}\onen\dots\keyindex{tbbbbl}\onen. For example,
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\ibbbu0h0\qb0e\tbbbu0\qb0e\tbbu0\qb0e\tbu0\qb0e\enotes
-\endextract
+\zendextract
 \end{music}
 \noindent has been coded as
 
 \begin{quote}\begin{verbatim}
 \startextract
 \Notes\ibbbu0h0\qb0e\tbbbu0\qb0e\tbbu0\qb0e\tbu0\qb0e\enotes
-\endextract
+\zendextract
 \end{verbatim}\end{quote}
 
-The macros \keyindex{tbbu} and \keyindex{tbbl} and higher order
-may also be invoked when only
-a single beam is active. Then, a second beam or third or ...
-(upper or lower according
-the initiating procedure) is opened \ital{one note width before
-the current position, and closed immediately}. Thus the following sequences
+Although at first it may seem counterintuitive,
+the macros \keyindex{tbbu} and \keyindex{tbbl} and higher order counterparts
+may also be invoked when the multiplicity is one. In this case
+a second, third, or fourth heavy bar will be opened one note width \ital{before}
+the current stem, and immediately closed \ital{at} the stem.
+Thus the following sequences
 
-\begin{music}
+\begin{music}\nostartrule
 \let\extractline\hbox
 \hbox to \hsize{%
 \hss
   \startextract
   \Notes\ibu0e0\qbp0e\tbbu0\tbu0\qb0e\en
-  \endextract
+  \zendextract
 \hss\hss
   \startextract
   \Notes\ibu0e0\qbpp0e\tbbbu0\tbbu0\tbu0\qb0e\en
-  \endextract
+  \zendextract
 \hss}
 \end{music}
-\noindent are coded:
+\noindent are coded
 \hspace*{\fill}\begin{minipage}{.4\textwidth}\begin{verbatim}
 \Notes\ibu0e0\qbp0e%
   \tbbu0\tbu0\qb0e\en
@@ -1792,34 +2064,42 @@ the current position, and closed immediately}. Thus the following sequences
   \tbbbu0\tbbu0\tbu0\qb0e\en
 \end{verbatim}\end{minipage}\hfill
 
-\noindent The same behaviour occurs in the case of \keyindex{tbbbu},
-\keyindex{tbbbl}, \keyindex{tbbbbu} and \keyindex{tbbbbl}.
- The symmetrical pattern is also possible. For example:
+\medskip
 
-\begin{music}
+
+The symmetrical pattern is also possible. For example:
+
+\begin{music}\nostartrule
 \startextract
 \Notes\ibbl0j0\roff{\tbbl0}\qb0j\tbl0\qbp0j\enotes
-\endextract
+\zendextract
 \end{music}
 \noindent has been coded as:
 \begin{quote}\begin{verbatim}
 \Notes\ibbl0j0\roff{\tbbl0}\qb0j\tbl0\qbp0j\enotes
 \end{verbatim}\end{quote}
- \begin{remark} these codings may seem complicated. In fact,
-it is the responsibility of the user to define macros which perform the most
-common sequences in his masterpiece. For example, one could define sets of
-four sixteenths by the macro:
-
-\verb|\def\qqh#1#2#3#4#5{\ibbl0#2#1\qb#2\qb#3\qb#4\tbl0\qb#5}|
-
-\noindent where the first argument is the slope and the other four
-arguments are the pitches of the four consecutive sixteenths wanted.
-\end{remark}
-
-
-\noindent A slightly more complicated example is:
 
-\begin{music}
+The constructions in this section illustrate some general
+properties of
+beam initiation and termination commands: To mate properly with the
+expected stems, the starting position of the heavy bar(s) (for initiation commands)
+and the ending position (for terminations) will be at
+different horizontal locations
+depending on whether they are for upper or lower beams: The position for
+upper beam commands is one note head width to the right of those for
+lower beams. In fact this is the \ital{only} difference between upper
+and lower termination commands. Both types will operate on whatever kind of
+beam is open and has the same beam number.
+
+Recognizing this principle, in the example just given it was necessary to
+shift the double termination to the right by one note head width, using the
+command \keyindex{roff}\verb|{|\dots\verb|}|, which does precisely that for
+any \musixtex\ macro.
+
+Here is another, slightly more complicated example which also uses
+\verb|\roff|:
+
+\begin{music}\nostartrule
 \startextract
 \notes\ibbbu0e0\roff{\tbbbu0}\qb0f\en
 \notesp\tbbu0\qbp0f\en
@@ -1827,7 +2107,7 @@ arguments are the pitches of the four consecutive sixteenths wanted.
 \notesp\ibbu0f0\roff{\tbbu0}\qbp0f\en
 \Notes\qb0f\en
 \notes\tbbbu0\tbbu0\tbu0\qb0f\en
-\endextract
+\zendextract
 \end{music}
 \noindent has been coded as:
 \begin{quote}\begin{verbatim}
@@ -1838,59 +2118,86 @@ arguments are the pitches of the four consecutive sixteenths wanted.
 \Notes\qb0f\en
 \notes\tbbbu0\tbbu0\tbu0\qb0f\en
 \end{verbatim}\end{quote}
+
+\noindent Note that the first beam opening command used a pitch one step
+below the note. This makes the stem shorter by one pitch unit, since it is always
+the \ital{closest} heavy bar that is separated from the given pitch by
+three staff spaces.
+
+We close this section with an example showing how to
+open a beam of one sense, increase multiplicity, then terminate with
+opposite sense:
+
+\begin{music}\nostartrule
+\startextract
+\Notes\ibl0p0\qb0p\nbbl0\qb0p\nbbbl0\qb0p\tbu0\qb0e\enotes
+\zendextract
+\end{music}
+\noindent which has been coded as
+\begin{quote}\begin{verbatim}
+\Notes\ibl0p0\qb0p\nbbl0\qb0p\nbbbl0\qb0p\tbu0\qb0e\enotes
+\end{verbatim}\end{quote}
+
+ \begin{remark} One may save some typing by defining personalized
+\TeX\ macros to
+perform any oft repeated sequence of commands. For example,
+one could define a set of four sixteenths by the macro:
+
+\verb|\def\qqh#1#2#3#4#5{\ibbl0#2#1\qb#2\qb#3\qb#4\tbl0\qb#5}|
+
+\noindent where the first argument is the slope and the other four
+arguments are the pitches of the four successive sixteenths.
+\end{remark}
+
  %\check
- \subsection{Repeated pattern beams}\index{repeated patterns}
-Note heads hanging on beams are not necessarily quarter (or higher order)
-note heads. It is possible to hang half note heads on beams
-using \keyindex{hb} macro, e.g.:
+ \subsection{Shorthand beam notations for repeated notes}\index{repeated patterns}
+Sometimes you may want to indicate repeated short notes with open note heads joined
+by a beam. Here's an example of how to do that
+using the \keyindex{hb} macro:
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\ibbl0j0\hb0j\tbl0\hb0j\enotes
 \Notes\ibbu0g0\hb0g\tbu0\hb0g\enotes
-\endextract
+\zendextract
 \end{music}
-\noindent has been coded as:
+\noindent which has been coded as:
 \begin{quote}\begin{verbatim}
 \Notes\ibbl0j0\hb0j\tbl0\hb0j\enotes
 \Notes\ibbu0g0\hb0g\tbu0\hb0g\enotes
 \end{verbatim}\end{quote}
 
+It is also possible to dispense with the stems:
 
-It is also possible to write
-
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\ibbl0j3\wh j\tbl0\wh l\enotes
 \Notes\ibbu0g3\wh g\tbu0\wh i\enotes
-\endextract
+\zendextract
 \end{music}
-\noindent which was coded as:
+\noindent which was coded as
 \begin{quote}\begin{verbatim}
 \Notes\ibbl0j3\wh j\tbl0\wh l\enotes
 \Notes\ibbu0g3\wh g\tbu0\wh i\enotes
 \end{verbatim}\end{quote}
-\noindent However, a better look could be obtained in a more sophisticated
-way\footnote{You are suggested to make your own macro if you have to type many
-of these, or better: use a pre-compiler.}:
+\noindent A different look could be obtained as follows:
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\loff{\zw j}\ibbl0j3\sk\tbl0\wh l\enotes
 \Notes\ibbu0g3\wh g\tbu0\roff{\wh i}\enotes\qspace
-\endextract
+\zendextract
 \end{music}
-\noindent which was simply coded as:
+\noindent which was coded as:
 \begin{quote}\begin{verbatim}
 \Notes\loff{\zw j}\ibbl0j3\sk\tbl0\wh l\enotes
 \Notes\ibbu0g3\wh g\tbu0\roff{\wh i}\enotes\qspace
 \end{verbatim}\end{quote}
 
- Single repeated notes can also be made --- in a much more sophisticated
-way\footnote{But you can write your own macro, thinking of using
-{\tt\char92transpose} to lift the oblique beams.}, for example:
+Yet another way to indicate repeated notes is given in the
+following example:
 
- \begin{music}
+ \begin{music}\nostartrule
 \startextract
 \Notes\ibl0h0\qb0{hhh}\tbl0\qb0h\bsk\bsk\bsk\bsk
       \ibu0j0\qb0{jjj}\tbu0\qb0j\en
@@ -1902,9 +2209,9 @@ way\footnote{But you can write your own macro, thinking of using
       \ibbu0i0\qb0{jjj}\tbu0\qb0j\en
 \NOTes\loffset{0.5}{\ibbl0k9}\roffset{0.5}{\tbl0}\zhl h%
       \loffset{0.5}{\ibbu0f9}\roffset{0.5}{\tbu0}\hu j\en
-\endextract
+\zendextract
  \end{music}
- \noindent whose coding (due to W. {\sc Icking}) is;
+ \noindent whose coding (due to Werner {\sc Icking}) is
 
 \begin{quote}\begin{verbatim}
 \Notes\ibl0h0\qb0{hhh}\tbl0\qb0h\bsk\bsk\bsk\bsk
@@ -1919,58 +2226,15 @@ way\footnote{But you can write your own macro, thinking of using
       \loffset{0.5}{\ibbu0f9}\roffset{0.5}{\tbu0}\hu j\en
 \end{verbatim}\end{quote}
 
- \subsection{Beams across bars}
-The usual way most composers wrote their scores was beams inside bars,
-at least until the beginning of the XIX-th
-century. Unfortunately, later composers ({\sc Brahms}, {\sc Scriabin},
-{\sc Grieg}, etc.) wanted to write beams jumping across bars.
-This is possible without any problems.
-We give an example from {\sc Brahms}'s Intermezzo op.~118,1 provided by
-Miguel {\sc Filgueiras}:\index{Brahms, J.@{\sc Brahms, J.}}\medskip
+ \subsection{Beams that cross line breaks}
 
-\begin{music}
-\interstaff{12}
-\setstaffs1{2}
-\setclef1\bass
-\generalmeter\allabreve
-\startextract
-\NOtes\qp\nextstaff\isluru0q\zq{q}\ql{j}\enotes
-\bar
-\nspace
-\Notes\ibu0L2\qb0{CEJLcL}%
-  \nextstaff\roff{\zw{l}}\pt{p}\zh{_p}\pt{i}\hl{_i}\enotes
-\Notes\qb0J\itied1a\qb0a\nextstaff\tslur0o\zq{o}\ql{h}\enotes
-\bar
-\Notes\ttie1\zh{.L.a}\hl{.e}%
-  \nextstaff\qb0{chj}\tbl0\qb0l\cl{q}\ds\enotes
-\NOtes\qp\nextstaff\zq{q}\ql{j}\enotes
-\endextract
-\end{music}
- %\check
-\noindent whose coding is:
-\begin{verbatim}
-\interstaff{13}
-\instrumentnumber{1}
-\setstaffs1{2}
-\setclef1\bass
-\generalmeter\allabreve
-\startextract
-\NOtes\qp\nextstaff\isluru0q\zq{q}\ql{j}\enotes
-\bar
-\nspace
-\Notes\ibu0a1\qb0{CEJLcL}%
-  \nextstaff\roff{\zw{l}}\pt{p}\zh{_p}\pt{i}\hl{_i}\enotes
-\Notes\qb0J\itied1a\qb0a\nextstaff\tslur0o\zq{o}\ql{h}\enotes
-\bar
-\Notes\ttie1\zh{.L.a}\hl{.e}%
-  \nextstaff\qb0{chj}\tbl0\qb0l\cl{q}\ds\enotes
-\NOtes\qp\nextstaff\zq{q}\ql{j}\enotes
-\endextract
-\end{verbatim}
-Still to be done manually is the cut and prolongation across line breaks, which
-can be easily be done with shifting using \keyindex{roff} and/or
-\keyindex{loff}, or with insert of a spacing command (here done with
-\keyindex{hsk}). We give an example from {\sc Grieg}'s ``Hochzeit auf
+Although careful typesetting can usually avoid it, occasionally
+a beam may need to cross a line break. If so, it must be manually terminated at
+the end of one line and continued in the next. This
+can be done by shifting beam terminations and initiations
+using \keyindex{roff} and/or
+\keyindex{loff}, or by inserting a spacing command such as
+\keyindex{hsk}. We give an example from {\sc Grieg}'s ``Hochzeit auf
 Troldhaugen'':\index{Grieg, E.@{\sc Grieg, E.}}\medskip
 
 \begin{music}
@@ -2019,89 +2283,187 @@ Troldhaugen'':\index{Grieg, E.@{\sc Grieg, E.}}\medskip
 \notes\rlap\qs\hsk\tbu0|\rq e\zq d\zqb1N\hsk\tbu1\en
 \endpiece
 \end{music}
-\noindent where the prolongation was coded as:
-\begin{verbatim}
+\noindent The prolongation of the two upper beam at the end is
+illustrated in the code fragment
+\begin{quote}\begin{verbatim}
 \notes\rlap{\qs}\hsk\tbu0|\rq e\zq d\zqb1N\hsk\tbu1\en
-\end{verbatim}
+\end{verbatim}\end{quote}
  %\check
- \subsection{Semi-automatic beams}
-In order to avoid tedious checks to adjust the slope (and even the starting
-pitch) of beams in music with a lot of steep beams, a set of automatically
-slope computing has recently been implemented. If
-you say \verb|\Ibu2gj3| \musixtex\ will understand that`you want to
-build an upper beam (beam number 2) horizontally extending \verb|3\noteskip|,
-the first note of which is a \verb|g| and the last note is a \verb|j|.
-Knowing these parameters it will choose the highest slope number which
-corresponds to a slope not more than $(\hbox{\tt j}-\hbox{\tt
-g})/(3\keyindex{noteskip})$. Moreover, if there is no sufficiently steep beam
-slope available, then it will raise the starting point.
 
- Eight such macros are available: \keyindex{Ibu}, \keyindex{Ibbu},
-\keyindex{Ibbbu}, \keyindex{Ibbbbu}, \keyindex{Ibl}, \keyindex{Ibbl},
-\keyindex{Ibbbl} and \keyindex{Ibbbbl}.
-
-Also available are ready definitions for often needed sets of double,
-triple and quadruple notes with computed slopes. These are:
-\keyindex{Dqbu}, \keyindex{Dqbl}, \keyindex{Dqbbu}, \keyindex{Dqbbl},
-\keyindex{Tqbu}, \keyindex{Tqbl}, \keyindex{Tqbbu}, \keyindex{Tqbbl},
-\keyindex{Qqbu}, \keyindex{Qqbl}, \keyindex{Qqbbu} and \keyindex{Qqbbl}.
-  %\check
+ \subsection{Beams with notes on several different staves}
 
+Here's a simple example from {\sc Brahms}'s
+Intermezzo op.~118,1 provided by
+Miguel {\sc Filgueiras}:\index{Brahms, J.@{\sc Brahms, J.}}\medskip
 
-\medskip
 \begin{music}
-\parindent0pt\startpiece
-\Notes\Dqbu gh\Dqbl jh\en
-\notes\Dqbbu fg\Dqbbl hk\en\bar
-\Notes\Tqbu ghi\Tqbl mmj\en
-\notes\Tqbbu fgj\Tqbbl njh\en\bar
-\Notes\Qqbu ghjh\Qqbl jifh\en
-\notes\Qqbbu fgge\Qqbbl jhgi\en\endpiece
+\interstaff{12}
+\setstaffs1{2}
+\setclef1\bass
+\generalmeter\allabreve
+\startextract
+\NOtes\qp\nextstaff\isluru0q\zq{q}\ql{j}\enotes
+\bar
+\nspace
+\Notes\ibu0L2\qb0{CEJLcL}%
+  \nextstaff\roff{\zw{l}}\pt{p}\zh{_p}\pt{i}\hl{_i}\enotes
+\Notes\qb0J\itied1a\qb0a\nextstaff\tslur0o\zq{o}\ql{h}\enotes
+\bar
+\Notes\ttie1\zh{.L.a}\hl{.e}%
+  \nextstaff\qb0{chj}\tbl0\qb0l\cl{q}\ds\enotes
+\NOtes\qp\nextstaff\zq{q}\ql{j}\enotes
+\endextract
 \end{music}
-\noindent which was simply coded as:
-\begin{quote}\begin{verbatim}
-\Notes\Dqbu gh\Dqbl jh\en
-\notes\Dqbbu fg\Dqbbl hk\en\bar
-\Notes\Tqbu ghi\Tqbl mmj\en
-\notes\Tqbbu fgj\Tqbbl njh\en\bar
-\Notes\Qqbu ghjh\Qqbl jifh\en
-\notes\Qqbbu fgge\Qqbbl jhgi\en
-\end{verbatim}\end{quote}
  %\check
+\noindent The coding is
+\begin{verbatim}
+\interstaff{13}
+\instrumentnumber{1}
+\setstaffs1{2}
+\setclef1\bass
+\generalmeter\allabreve
+\startextract
+\NOtes\qp\nextstaff\isluru0q\zq{q}\ql{j}\enotes
+\bar
+\nspace
+\Notes\ibu0a1\qb0{CEJLcL}%
+  \nextstaff\roff{\zw{l}}\pt{p}\zh{_p}\pt{i}\hl{_i}\enotes
+\Notes\qb0J\itied1a\qb0a\nextstaff\tslur0o\zq{o}\ql{h}\enotes
+\bar
+\Notes\ttie1\zh{.L.a}\hl{.e}%
+  \nextstaff\qb0{chj}\tbl0\qb0l\cl{q}\ds\enotes
+\NOtes\qp\nextstaff\zq{q}\ql{j}\enotes
+\endextract
+\end{verbatim}
+
+\noindent (This example also shows that there is no problem in extending
+a beam across a bar line.)
+
+The general features that enable this type of coding as well as the
+more complex example to follow are
+ \begin{itemize}\setlength{\itemsep}{0ex}
+%  \item Commands like \Bslash{\tt ibu}, \Bslash{\tt ibl},
+%\Bslash{\tt Ibu}, and \Bslash{\tt Ibl} \rm
+%define beams whose initial vertical position and slope are fixed
+%relative
+%to the staff where they begin, but notes in other staves can still be
+%connected to them using \Bslash{\tt qb}\onen.
+%
+%  \item The commands \keyindex{tbu}\onen\rm~or \keyindex{tbl}\onen\rm~terminate
+%beam $n$ at the specified position, but \musixtex\ remembers the beam
+%parameters until a new beam with the same number is defined.
+%Therefore, even after beam $n$ has been ``finished'' by a \verb|\tbu| or
+%\verb|\tbl| command, commands like \Bslash{\tt qb}\enpee\rm~will still
+%generate notes connected to the phantom extension of this beam,
+%\ital{provided they are issued in a different staff}. If the command
+%\verb|\qb|\enpee\rm~were issued on the same staff as the beam after
+% the beam had ended, an error would result.
+%
+  \item Commands like {\Bslash\texttt{ibu}}, {\Bslash\texttt{ibl}},
+{\Bslash\texttt{Ibu}}, and {\Bslash\texttt{Ibl}}
+define beams whose initial vertical position and slope are fixed
+relative
+to the staff where they begin, but notes in other staves can still be
+connected to them using {\Bslash\texttt{qb}\onen}.
+
+  \item The commands {\keyindex{tbu}\onen}  or {\keyindex{tbl}\onen}
+terminate
+beam $n$ at the specified position, but \musixtex\ remembers the beam
+parameters until a new beam with the same number is defined.
+Therefore, even after beam $n$ has been ``finished'' by a \verb|\tbu| or
+\verb|\tbl| command, commands like {\Bslash{\tt qb}\enpee} will still
+generate notes connected to the phantom extension of this beam,
+\ital{provided they are issued in a different staff}. If the command
+\verb|\qb|\enpee\rm~were issued on the same staff as the beam after
+ the beam had ended, an error would result.
+
+
+
+
+
+ \item If the beam is initiated on one staff,
+notes in a lower staff can be connected to it, but only \ital{after} the beam
+has been defined. This may require using the command \keyindex{prevstaff}
+to go back one staff, as described in section
+\ref{movingtostaffs}.
+
+ \end{itemize}
+
+ Here is an example:
+
+ \begin{music}
+ \setstaffs13
+ \setclef1{6000}
+ \startextract
+ \notes
+ \nextstaff\Ibbbu0Ae7\prevstaff
+ \qb0{AEH^JLa}\relax\nextstaff
+ \qb0{******^c}\tqh0e\relax
+ |\zq{h^jl}\ql o\enotes
+ \notes
+ \nextstaff
+ \Ibbbu0hH6\qb0{hec}\prevstaff
+ \qb0{***aLJ}\tqh0H\relax\nextstaff
+ |\zq{h^jl}\ql o\enotes \nspace
+ \zendextract
+ \end{music}
+
+ \noindent which is coded as:
+
+ \begin{quote}
+ \begin{verbatim}
+ \setstaffs13
+ \setclef1{6000}
+ \startextract
+ \notes
+ \nextstaff\Ibbbu0Ae7\prevstaff
+ \qb0{AEH^JLa}\relax\nextstaff
+ \qb0{******^c}\tqh0e\relax
+ |\zq{h^jl}\ql o\enotes
+ \notes
+ \nextstaff
+ \Ibbbu0hH6\qb0{hec}\prevstaff
+ \qb0{***aLJ}\tqh0H\relax\nextstaff
+ |\zq{h^jl}\ql o\enotes \nspace
+ \zendextract
+ \end{verbatim}
+ \end{quote}
+
+In this example we not only see multiple uses of \keyindex{nextstaff} and
+\keyindex{prevstaff}, but also the character \verb|*| to make virtual beam notes
+(see section \ref{CollectiveCoding}).
 
 \section{Rests}
- Except that difference that they have no specific pitch, rests are coded in a
-very simple way.
  \subsection{Ordinary rests}
- Full bar rests (also called ``pauses'') are coded as
-\keyindex{pause}, with a point behind as \keyindex{pausep};
-smaller rests are
-\keyindex{hpause} (of duration equal to a \ital{half note}),
-with a point behind as \keyindex{hpausep},
-\keyindex{qp} (duration equal to a \ital{quarter note},
-  also \keyindex{soupir}),
-\keyindex{ds} (duration equal to an \ital{eighth note}),
-\keyindex{qs} (duration equal to an \ital{sixteenth note}),
-\keyindex{hs} (duration equal to an \ital{thirty second note}),
-\keyindex{qqs} (duration equal to an \ital{sixty fourth note}).
-
- Long rests (lasting several bars) can be coded as \keyindex{PAuse}
-and \keyindex{PAUSe}, which respectively yield:
-
-\begin{music}
+ A separate macro is defined for each kind of ordinary rest. They cause
+a space after the symbol, just like spacing note commands, but they have
+no parameters. A whole rest is coded as
+\keyindex{pause}, dotted whole rest \keyindex{pausep},
+half rest \keyindex{hpause}, dotted half rest \keyindex{hpausep},
+quarter rest \keyindex{qp} or \keyindex{soupir},
+eighth rest \keyindex{ds}, sixteenth rest \keyindex{qs},
+32nd rest \keyindex{hs}, and 64th rest \keyindex{qqs}.
+
+ Longer rests, normally interpreted as lasting
+two or four bars respectively, can be coded as \keyindex{PAuse}
+and \keyindex{PAUSe}, which yield:
+
+\begin{music}\nostartrule
 \generalmeter{\meterfrac44}
 \startextract
 \def\atnextbar{\znotes\centerbar\PAuse\en}%
 \NOTEs\en\bar
 \def\atnextbar{\znotes\centerbar\PAUSe\en}%
-\NOTEs\en\endextract
+\NOTEs\en\zendextract
 \end{music}
  %\check
 
- \subsection{Lifted rests}\index{lifting rests}\index{rest lifting} All the
-previous rests with exception of \keyindex{pausep} (pause with a point) and
-\keyindex{hpausep} (half rest with a point) are \ital{hboxes}; this means that
-they can be vertically offset to meet polyphonic music requirements using the
+
+ \subsection{Raising rests}\index{raising rests}
+All the
+previous rests except \keyindex{pausep} and
+\keyindex{hpausep} are \ital{hboxes}, which means that
+they can be vertically offset if needed using the
 standard \TeX\ command \keyindex{raise}. For example:
 
  \begin{quote}
@@ -2111,45 +2473,39 @@ standard \TeX\ command \keyindex{raise}. For example:
  \end{verbatim}
  \end{quote}
 
- \noindent{\sl{\bfseries CAUTION:} do not try to lift rests (or notes but this
-looks so silly that...) using codings like
-\verb|\raise2mm|\keyindex{hbox}\verb|{\qp}|. The reason is that the rest
-symbol (e.g. \verb|\qp|) is embedded in braces, so that local counting of
-spaces (register \verb|\loc@skip|) will be lost, resulting in turn in
-overfull/undfull boxes, beam errors, erratic slurring, etc. In general, all
-rests and all notes should be coded at the brace level of the \verb|\notes|
-command, unless they are deliberately embedded in \keyindex{rlap} or
-\keyindex{llap} which actually overlook spacing counting but finally force no
-horizontal spacing, a behaviour which compensates the forgotten spacing count.}
-
- In addition, two symbols have been provided to put a \itxem{full rest} or a
-\itxem{half rest} above or below the staff. Then the ordinary \verb|\pause| or
-\verb|\hpause| cannot be used since there is a need for small horizontal line
-to distinguish between the full and the half rest. They are:
- \begin{itemize}
- \item \keyindex{liftpause}~$n$ (non spacing) to get a
+\noindent where \keyindex{Interligne} is the distance from one staff line to the
+next.
+
+In addition, two macros are available to put a whole or
+half rest above or below the staff. The ordinary \verb|\pause| or
+\verb|\hpause| cannot be used outside the staff because a short horizontal line
+must be added to distinguish between the whole and the half rest. The commands,
+which are non-spacing\footnote{Editor's note: The reason for having defined these
+as non-spacing is not obvious}, are
+ \begin{itemize}\setlength{\itemsep}{0ex}
+ \item \keyindex{liftpause}~$n$ to get a
   \hbox to10pt{\liftpause{-2}\hss}
   raised from original position by $n$ staff line intervals,
- \item \keyindex{lifthpause}~$n$ (non spacing) to get
+ \item \keyindex{lifthpause}~$n$ to get
   \hbox to10pt{\lifthpause{-1}\hss} raised the same way.
- \item \keyindex{liftpausep}~$n$ (non spacing) to get a
+ \item \keyindex{liftpausep}~$n$ to get a
   \hbox to10pt{\liftpausep{-2}\hss}
   raised from original position by $n$ staff line intervals,
- \item \keyindex{lifthpausep}~$n$ (non spacing) to get
+ \item \keyindex{lifthpausep}~$n$ to get
   \hbox to10pt{\lifthpausep{-1}\hss} raised the same way.
  \end{itemize}
  %\check
 
  \subsection{Bar centered rests}\label{barcentered}
-Sometimes it is necessary to place a rest (or other) exactly in the middle
-of a bar. This can be done with more sophisticated commands:
-%\keyindex{atnextbar}
+Sometimes it is necessary to place a rest (or any other symbol) exactly in the middle
+of a bar. This can be done with combinations of the commands
+\keyindex{atnextbar},
 \keyindex{centerbar},
 \keyindex{centerPAUSe},
 \keyindex{centerPAuse},
 \keyindex{centerpause},
-\keyindex{centerhpause}.
-For example:
+\keyindex{centerhpause},
+as demonstrated in the following example:
 
 \begin{music}
 \generalmeter\meterC
@@ -2168,6 +2524,7 @@ For example:
 \addspace{10\elemskip}%
 \def\atnextbar{\znotes\centerbar\duevolte|\centerbar\duevolte\en}\endpiece
 \end{music}
+\noindent with the coding
 \begin{verbatim}
 \generalmeter\meterC
 \setclef1\bass
@@ -2187,36 +2544,79 @@ For example:
 \end{verbatim}
  %\check
 
-\section{Phantom notes and spacing commands}\label{spacing}
-It may be interesting, when coding a sequence of notes within a unique pair
-\verb|\notes...\enotes|, to skip one note place in order -- for
-example -- to set the third note of one staff at the same abscissa as that of
-the second note of another staff. This can be done by inserting \keyindex{sk}
-which causes a spacing of one \keyindex{noteskip}\footnote{Never use
-\keyindex{kern} nor \keyindex{hskip}~: in fact \keyindex{sk} not only causes
-a space but also records that space for correct handling of beams, slurs,
-trills, octaviation dashed lines, line-breaking, etc.}. Sometimes it is useful
-to \ital{skip back} one noteskip, this can be done with \keyindex{bsk}. The
-spacing of a half \verb|\noteskip| can be yielded with \keyindex{hsk}.
-
- %\check
+\section{Skipping spaces and shifting symbols}\label{spacing}
+We've already mentioned that when coding a sequence of notes inside a
+particular pair \verb|\notes...\enotes|, the command \keyindex{sk} can
+be used to skip horizontally by one \keyindex{noteskip}. This would be
+used for example to align the third note in one staff with the second note
+in another. Skipping in this manner is logically equivalent to inserting
+blank space; as such, the space must be recorded by \musixtex. This command
+and the others discussed here will
+do just that, so that \verb|musixflx| can properly account for
+the added space.
+
+To skip by one \verb|noteskip| while in a collective coding sequence,
+you may simply insert an asterisk (``\verb|*|''\index{*}). This would have
+the same effect as stopping the sequence, entering {\Bslash sk}, then
+restarting. For example,
 
- If you just want to shift a note or a symbol by one note head width,
-you may write \keyindex{roff}\verb|{|\ital{note/symbol}\verb|}| (shift right)
-or \keyindex{loff}\verb|{|\ital{note/symbol}\verb|}| (shift left).
- If you just want to shift a note or a symbol by one half note head width,
-you may write \keyindex{hroff}\verb|{|\ital{note/symbol}\verb|}| (shift right)
-or \keyindex{hloff}\verb|{|\ital{note/symbol}\verb|}| (shift left).
+\begin{music}
+\setstaffs12
+\startextract
+\Notes\hu{e*f*g}|\qu{gghhii}\en
+\zendextract
+\end{music}
+\noindent was coded as
+\verb|\Notes\hu{e*f*g}|{\tt |}\verb|\qu{gghhii}\en|
+
+To skip forward
+by one half of a \verb|\noteskip|, use \keyindex{hsk}.
+To insert spacing of approximately one note head width, you can use
+\keyindex{qsk}, or for half of that, \keyindex{hqsk}. To skip backward
+by one \verb|\noteskip|, use \keyindex{bsk}. More generally,
+to skip an arbitrary distance, use \keyindex{off}\verb|{|$D$\verb|}|
+where $D$ is any \itxem{scalable dimension}, e.g.~\verb|\noteskip| or
+\verb|\elemskip|. Indeed, if you look in the
+\musixtex\ source, you will see that \verb|\off| is the basic control
+sequence used to define all the other skip commands.
+
+The foregoing commands only work \ital{inside} a \verb|\notes...\enotes| group.
+A different set of commands must be used to insert space \ital{outside}
+such a group. \keyindex{nspace} produces an
+additional spacing of half a note head width;
+\keyindex{qspace}, one note head width. These are ``hard'' spacings. To
+insert an arbitrary amount of hard space outside a \verb|\notes...\enotes|
+group, use \keyindex{hardspace}\verb|{|$d$\verb|}{|\dots\verb|}| where
+$d$ is any fixed dimension\label{hardspace}. The foregoing three commands are the only
+space-generating commands that insert hard space; all the others insert
+scalable spacing: \keyindex{elemskip},
+\keyindex{beforeruleskip}, \keyindex{afterruleskip}, \keyindex{noteskip} and
+their multiples. Finally, to insert
+scalable spacing outside
+a \verb|\notes...\enotes| group, use
+\keyindex{addspace}\verb|{|$D$\verb|}|. The argument may be negative, in
+which case the normal spacing will be reduced. For example, after
+\keyindex{changecontext}, many users prefer to reduce the space with
+a command like
+\verb|addspace{-|\keyindex{afterruleskip}\verb|}|.
+
+There is yet another set of commands for simply shifting a note, symbol, or sequence
+inside \verb|\notes...\enotes|
+without adding or subtracting any space. To shift by one note head width,
+you may write \keyindex{roff}\verb|{|\ital{any macro}\verb|}|
+or \keyindex{loff}\verb|{|\dots\verb|}| for a right or left shift respectively.
+ To shift by half of a note head width, use
+\keyindex{hroff}\verb|{|\dots\verb|}| or
+\keyindex{hloff}\verb|{|\dots\verb|}|.
 For example, to get
  %\check
 
-
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\roff{\zwh g}\qu g\qu h\qu i\enotes
-\endextract
+\zendextract
 \end{music}
-you code:
+\noindent you would code:
 
  %\check
 
@@ -2224,290 +2624,271 @@ you code:
 \Notes\roff{\zwh g}\qu g\qu h\qu i\enotes
 \end{verbatim}\end{quote}
 
-If you want to shift notes or symbols right by more or less than one note head
-width, then you can use \keyindex{roffset} (or \keyindex{loffset} in the other
-direction) which has an additional first argument which is the number of note
-head widths the second argument should be shifted by. For example
+\noindent To shift notes or symbols by an arbitrary amount, use
+\keyindex{roffset}\verb|{|$N$\verb|}{|\dots\verb|}| or
+\keyindex{loffset}\verb|{|$N$\verb|}{|\dots\verb|}|, where
+$N$ is the distance to be shifted in note head widths. For example
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\roffset{1.5}{\zwh g}\qu g\qu h\qu i\enotes
-\endextract
+\zendextract
 \end{music}
-was coded:
+\noindent was coded as
 
 \begin{quote}\begin{verbatim}
 \Notes\roffset{1.5}{\zwh g}\qu g\qu h\qu i\enotes
 \end{verbatim}\end{quote}
 
-\begin{important} the offset specified or implicitly specified in
-\verb|\roff|, \verb|\loff|, \verb|\roffset| and \verb|loffset| does not add to
-the total spacing amount; in other words this is just an offset, not a
-spacing. Conversely, the possible spacing of commands included in the argument
-of \verb|\roff|/\verb|\loff| and in the second argument
-of \verb|\roffset|/\verb|\loffset| actually adds to the total spacing in that
-bar of the current staff. Therefore, the symbol/note argument of these offset
-commands should usually produce no spacing, i.e. begin with \verb|\z|.
-
- Besides, it is not advised to insert several consecutive spacing notes in
-the \verb|\roff|/\verb|\loff| or \verb|\roffset|/\verb|\loffset| arguments,
-since it could mess up the global spacing accounting.
- \end{important}
-
- %\check
-
-
-To insert spacing of \ital{nearly} one \ital{note head width}, you can use
-\keyindex{qsk}(which has the drawback, that it is scalable, so what spacing
-you really get depends on the computed \verb|\elemskip| from \verb|musixflx|
-and the user chosen value of \verb|\elemskip|). The half of this spacing can
-be forced with \keyindex{hqsk}. Note that these two latter macros must be used
-inside a pair \verb|\notes...\enotes|.
-
- If you want to insert additional spacing before a group of notes, especially
-to avoid a collision with an accidental, you can write \keyindex{nspace} ---
-outside the \verb|\notes...\enotes| group --- and this will produces an
-additional spacing of a half note head width; in the same way,
-\keyindex{qspace} will yield a spacing of a note head width. Note that
-\verb|\nspace| and \verb|\qspace| are ``hard'' spacings, whose general
-feature is \verb|\hardspace|, described below.
-
-Sometimes the additional space behind \keyindex{changecontext}
-disturbs the eye of a typesetter, but this ugly spacing can be reduced with:
-
-\keyindex{addspace}\verb|{-|\keyindex{afterruleskip}\verb|}%|
-
-It should be emphasized that all these spacing commands work correctly, only
-when their dimension arguments are \itxem{scalable values} and not fixed
-dimensions; the scalable dimensions are \keyindex{elemskip},
-\keyindex{beforeruleskip}, \keyindex{afterruleskip}, \keyindex{noteskip} and
-their multiples.
-
-The only spacing command which can work with ``normal'' (that is,
-\ital{not scalable}) dimensions is:\label{hardspace}\index{hard spacing}
-
-
-\keyindex{hardspace}\verb|{|\ital{any \TeX~dimension}\verb|}%|
-
-\noindent but both \verb|\addspace| and \verb|\hardspace| can only be used
-outside of \verb|\notes...\enotes|.
-
-Conversely, a more general spacing is allowed within the
-\verb|\notes...\enotes| pairs, namely:
+An important feature of these shift commands is that the offset,
+whether implicit or explicit, is \ital{not} added to
+the total spacing amount, but any spacing due to the included commands is.
 
-\keyindex{off}\verb|{|$D$\verb|}%|
-
-\noindent where $D$ is a \itxem{scalable dimension}, for example
-\verb|\noteskip| or \verb|\elemskip|. In fact, if you look to the
-\musixtex\ source, you will find that \verb|\off| is the basic control
-sequence used to define \keyindex{sk}, \keyindex{qsk}, etc.
-
- %\check
-
-\section{Collective coding: sequences of notes}
-
-As seen in the {\sc Mozart} example, it is not necessary to write a macro
-sequence \verb|\notes...\enotes| for each column\footnote{Although
-the compiler compiles it faster.}. If, on all
-staffs of all instruments, spacings are equal or multiple of a unique value,
-the notes may be concatenated in each staff: each note in each staff makes
-the current position horizontally advance by the elementary spacing specified
-by the choice of \verb|\notes|, \verb|\Notes|, \verb|\NOtes|, etc.
-
- The major interest of this feature resides in that fact that
-the note macros are able to write several items; for instance
-\verb|\qu{cdefghij}| writes the \ital{C-major} scale in quarters with
-stem up. In the same way \verb|\cl{abcdef^gh}| writes the
-\ital{A-minor} scale in eighths. Not all note generating macros can be
-used to perform collective coding, but most of them can.
-
- If necessary a void space\footnote{same behaviour as {\Bslash sk}}
-can be inserted in a collective coding by using \verb|*|\index{*}.
-
- %\check
 
 \section{Accidentals}
 
 Accidentals can be introduced in two ways.
 
- The first way, the \ital{manual} way of coding them, consists for
-example in coding \keyindex{fl}\verb|a| to put a \ital{flat} at the
-pitch $a$, supposedly before the further note of that pitch.
-There is no control upon the fact that a note will be put at this position
-and at this pitch.
-Naturals, sharps, double flats and double sharps are coded \keyindex{na}~$p$,
-\keyindex{sh}~$p$, \keyindex{dfl}~$p$ and \keyindex{dsh}~$p$ respectively.
+ The first way, using explicit macros, consists for
+example in coding \keyindex{fl}\pitchp~to put a \ital{flat} at the
+pitch $p$, presumably right before a note at the same pitch. This is a
+non-spacing command and will automatically place the accidental an
+appropriate distance to the left of the anticipated note head.
+Naturals, sharps, double flats and double sharps are coded \keyindex{na}\pitchp,
+\keyindex{sh}\pitchp, \keyindex{dfl}\pitchp~and \keyindex{dsh}\pitchp~respectively.
 
-Alternate procedures \keyindex{lfl}, \keyindex{lna}, \keyindex{lsh},
+The alternate macros \keyindex{lfl}, \keyindex{lna}, \keyindex{lsh},
 \keyindex{ldfl} and \keyindex{ldsh}
-place the same accidentals, but their abscissa is shifted one note head width
-on the left. The purpose of this is to avoid collision of accidentals
-in a chord with narrow intervals.
-
- The second way of coding accidentals consists in putting the symbol
-\verb|^| (sharp), the symbol \verb|_| (flat), the symbol \verb|=| (natural), the
-symbol \verb|>| (double sharp), or the symbol \verb|<| (double
-flat) within the coding of the note, e.g.: \verb|\qb{^g}| yields a
-$G\sharp$. This may very well be combined with collective coding, e.g.:
+place the same accidentals, but shifted one note head width
+to the left. These can be used if a note head has been shifted to the left, or
+to avoid collision with other accidentals
+in a chord. If you want to shift an accidental by some other amount for
+more precise positioning, you could use \keyindex{loffset} with the normal
+accidental macro as the second parameter.
+
+ The second way of coding accidentals is to modify the parameter of a
+note command. Just put the symbol
+\verb|^| for a sharp, \verb|_| for a flat, \verb|=|~for a natural,
+\verb|>| for a double sharp, or \verb|<| for a double
+flat, right before the letter or number representing the pitch.
+For example, \verb|\qb{^g}| yields a
+$G\sharp$. This may be used effectively in collective coding, e.g.
 \verb|\qu{ac^d}|.
 
- Two sizes are available for accidentals. They revert to the small
-version when notes are supposed to be too close to each other. These two
-sizes can be forced by coding \keyindex{bigfl}, \keyindex{bigsh}, etc., or
-\keyindex{smallfl}, \keyindex{smallsh}, etc. If one does not want to have any
-small accidentals, then one can declare \keyindex{bigaccid} (conversely
-\keyindex{smallaccid} or \keyindex{varaccid} -- the latter restoring variable
-sizes).
+ There are two sizes of accidentals. By default they will be large unless there
+is not enough space between notes, in which case they will be made small. Either
+size can be forced locally by coding \keyindex{bigfl}, \keyindex{bigsh}, etc., or
+\keyindex{smallfl}, \keyindex{smallsh}, etc. If you want all accidentals to
+be large, then declare \keyindex{bigaccid} near the top of the input file. For
+exclusively small ones use \keyindex{smallaccid}. \keyindex{varaccid} will restore
+variable sizes.
 
- Small accidentals can also be put \ital{above} the note
-heads. This is done using \keyindex{uppersh}~$p$, \keyindex{upperna}~$p$ or
-\keyindex{upperfl}~$p$:
+ For editorial purposes, small accidentals can be placed \ital{above} note
+heads. This is done using \keyindex{uppersh}\pitchp, \keyindex{upperna}\pitchp, or
+\keyindex{upperfl}\pitchp:
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOtes\uppersh l\qa l\enotes
 \NOtes\upperna m\qa m\enotes
 \NOtes\upperfl l\qa l\enotes
-\endextract
+\zendextract
 \end{music}
- It also possible to introduce \ital{\ixem{cautionary accidental}s} on a
-score, i.e.\ small size accidentals between parentheses. This done by preceding
-the name of the accidental keyword by a \verb|c|,\label{cautionary}
- e.g.~by coding \keyindex{cfl}~$p$ to get a cautionary flat.
- Available cautionary accidentals are \keyindex{csh}, \keyindex{cfl}, \keyindex{cna},
-\keyindex{cdfl} and \keyindex{cdsh}, which give:
-
-\begin{music}
+ It also possible to introduce \ital{\ixem{cautionary accidental}s},
+i.e.\ small accidentals enclosed in parentheses. This done by preceding
+the name of the accidental keyword with ``\verb|c|'',\label{cautionary}
+ e.g.~\keyindex{cfl}\pitchp~for a cautionary flat.
+ Available cautionary accidentals are \keyindex{csh}, \keyindex{cfl},
+\keyindex{cna},
+\keyindex{cdfl} and \keyindex{cdsh}, which give
+
+\begin{music}\nostartrule
 \startextract
 \NOtes\csh g\qa g\enotes
 \NOtes\cfl h\qa h\enotes
 \NOtes\cna i\qa i\enotes
 \NOtes\cdfl j\qa j\enotes
 \NOtes\cdsh k\qa k\enotes
-\endextract
+\zendextract
 \end{music}
 \noindent
-Besides, the distance between note and accidental is influenced by
 
-\keyindex{accshift}\verb|=|\ital{any \TeX\ dimension}
+The distance between all notes and accidentals is controlled by
+\keyindex{accshift}\verb|=|\ital{any \TeX\ dimension}, where
+positive values shift to the left and negative to right, with a
+default value of \verb|0pt|.
+
+ \section{Transposition and octaviation}\label{octaviation}
+Two different subjects are discussed in this section. First, there
+are commands that cause notes to be printed at different pitches than
+entered. We shall refer to this as \ital{logical} transposition.
+Second, there are notations for octaviation that do
+not otherwise alter the appearance of the score, which we'll call
+\ital{octaviation lines}.
+
+\subsection{Logical transposition and octaviation}
+
+Logical transposition is controlled by an integer-valued \TeX\ register
+\keyindex{transpose}. Its default value is 0. If you enter
+\verb|\transpose=|$n$, then all subsequent pitches specified by
+letters will be transposed by $n$ positions. Normally this method would be
+used to transpose an entire piece. Pitches specified with
+numbers will not be affected, so if you think you will ever want to
+transpose a piece, you should enter all note pitches with letters.
+
+One way to transpose up or down by one octave would be to set
+\keyindex{transpose} to 7 or $-7$. For example, to make a quarter note
+octave as a chord, you could define a macro as
+\verb|\def\soqu#1{\zq{#1}{\transpose=7 \qu{#1}}}|.
+Note that because \verb|\transpose| is altered inside a pair of braces, the
+effect of the alteration is only local and does not reach outside the braces.
+
+ Another more convenient way to transpose locally up or down by one octave
+makes use respectively of the characters
+\verb|'| (\itxem{acute accent}) and \verb|`| (\itxem{grave accent}),
+placed immediately before the letter specifying the pitch. So
+for example \verb|\qu{'ab}| is equivalent to \verb|\qu{hi}| and
+\verb|\qu{`kl}| is equivalent to \verb|\qu{de}|. These characters have
+cumulative effects but in a somewhat restricted sense. They will alter the value of
+\verb|\transpose|, but only until changing to a different staff or
+instrument or encountering \verb|\enotes|, at which time it will be reset to the
+value it had before the accents were used. (That value is stored in
+another register called \keyindex{normaltranspose}). Thus for example
+\verb|\qu{''A'A}| and \verb|\qu{''A}\qu{'A}|
+are both equivalent to \verb|\qu{ah}|.
+
+At any point it is possible to reset the \verb|\transpose| register
+explicitly to the value it had
+when entering \verb|\notes|, by prefacing a pitch indication with
+``\verb|!|''. Thus \verb|\qu{!a'a}| always
+gives the note \verb|a| and its upper octave \verb|h|, shifted by the
+value of {\Bslash transpose} at the beginning of the current
+\verb|\notes...\enotes| group, regardless of the number of grave and
+acute accents occurring previously within that group.
+
+ \subsection{Behavior of accidentals under logical transposition}\label{transposeaccids}
+ The above processes indeed change the vertical position of the note heads
+and associated symbols (e.g.~stems and beams), but they don't take
+care of the necessary changes of accidentals when transposing. For example,
+suppose an F$\sharp$ occurs in the key of C major. If the piece is
+transposed up three steps to the key of F, the F$\sharp$ should logically
+become a
+B$\natural$. But if all you do is set \verb|\transpose=3|, the note will
+be typeset as a B$\sharp$. In other words, \musixtex\ will interpret the~\verb|\sh|
+or~\verb|^| to mean ``print a $\sharp$''.
+
+Naturally there is a solution, but it requires the typesetter to plan
+ahead: To force accidentals to behave well under transposition, they
+must be entered according to the \ital{relative
+accidental convention}. To alert \musixtex\ that you are using this
+convention to enter notes, you must issue the command
+\keyindex{relativeaccid}. Once you have done this, the meaning of
+accidental macros and characters (accents) in the input file is changed.
+Under the convention, when for example a
+\verb|\sh| is entered, it indicates a note that is supposed to sound
+\ital{one half step higher than what it would normally be under the
+current key signature}. Flats and naturals on entry similarly indicate
+notes one half step lower or at the same pitch as what the key signature
+dictates. \musixtex\ will take account of the key signature, and print
+the correct symbol according to the modern notational convention,
+provided you have explicitly entered the transposed key signature using
+for example \verb|\generalsignature|.
+
+Many people have a difficult time understanding how this works, so
+here are two simple examples in great detail. Consider the case already mentioned
+of the F$\sharp$ in the key of C major. With
+\verb|\relativeaccid| in effect, it should still be entered as \verb|\sh f|, and
+with no transposition it will still appear as F$\sharp$. With
+\verb|\transpose=3| and \verb|\generalsignature{-1}| it will appear
+(correctly) as B$\natural$. Conversely, suppose you want to enter a
+B$\natural$ when originally in the key of F. With \verb|\relativeaccid| in effect, it
+should be entered as \verb|\sh i|. (That's the part that people
+have the most trouble with: ``If I want a natural, why do I have to enter a sharp?'' Answer:
+``Go back and re-read the previous paragraph very carefully.'') With no transposition, it will be
+printed as B$\natural$. Now to transpose this to C major, set
+\verb|\transpose=-3| and \verb|\generalsignature0|, and it will appear
+as F$\sharp$.
+
+If you have invoked \verb|\relativeaccid| and then
+later for some reason wish to revert to the ordinary convention,
+enter \keyindex{absoluteaccid}.
+
+\subsection{Octaviation lines}
+The first kind of notation for octave transposition covers a
+horizontal range that must be specified at the outset. The sequence
 
-\noindent
-positive values shift to left, negative to right, default is \verb|0pt|.
- \section{Transposition and octaviation}
-An important feature is the existence of a special register
-\keyindex{transpose} the normal value of which is 0. If you say
-
-\verb|\transpose=3|
-
-\noindent all subsequent pitches specified by
-upper or lower case letters\footnote{Pitches specified with figures are
-absolute and not transposed.} will be transposed 3 positions. If you set
-\keyindex{transpose} to 7 you may write your music one octave below its final
-pitch. Thus, you can define \ital{octaviation} macros like
-
-\verb|\def\soqu#1{\zq{#1}{\transpose=7 \qu{#1}}}|
-
-\noindent to build quarter note octaves in a single call. Note
-that the octaviated note is coded within braces so that the transposition
-is only local.
-
- \ital{Octaviation}\index{octaviation} can also be performed in another
-way, namely using special codes to transpose by multiples of 7 intervals.
-For example \verb|\qu{'ab}| is equivalent to \verb|\qu{hi}| and
-\verb|\qu{`kl}| is equivalent to \verb|\qu{de}|. It should be
-emphasized here that the \verb|'| (\itxem{acute accent}) and the \verb|`|
-(\itxem{grave accent}) have cumulative effects, so that \verb|\qu{''A'A}|
-is equivalent to \verb|\qu{ah}| and that the \verb|\transpose|
-parameter is only reset to its initial value (not necessarily zero) when
-changing staff or instrument (i.e. \| or \verb|&|) or at \verb|\enotes|.
- Since this may be confusing, it is useful to use the \verb|!| prefix
-to reset the \verb|\transpose| register explicitely to the value it had
-when entering \verb|\notes|\footnote{This value is saved in another
-register named \keyindex{normaltranspose}.}. Thus \verb|\qu{!a'a}| always
-gives the note \verb|a| and its upper octave \verb|h| \ital{shifted by the
-value of {\Bslash transpose} at the beginning of the current} \noindent
-\verb|\notes...\enotes| group (or \verb|\Notes...\enotes|,
-etc.) whatever the number of previous grave and acute accents occurring
-inbetween.
- \subsection{Typical piano octave transposition}
- \subsubsection{Local octave transposition of fixed length}
-\begin{music}
+\medskip
+\begin{music}\nostartrule
 \startextract
-\NOTEs\octfinup{10}{3.5}\qu a\qu b\qu c\qu d\en
-\endextract
+\NOTEs\octfinup{10}{3.5}\ql{!'a}\ql b\ql c\ql d\en
+\zendextract
 \end{music}
 \noindent can be coded as
-\begin{quote}\begin{verbatim}
-\startextract
-\NOTEs\octfinup{10}{3.5}\qu a\qu b\qu c\qu d\en
-\endextract
-\end{verbatim}\end{quote}\zkeyindex{octfinup}
-\noindent that is, the dashed line extends 3.5$\times${\Bslash noteskip}.
-Conversely, lower octaviation can also be coded, for example:
+\verb|\NOTEs\octfinup{10}{3.5}\qu a\qu b\qu c\qu d\en|.
+\zkeyindex{octfinup}
+Here, the dashed line is at staff level 10 and extends 3.5\verb|\noteskip|.
+Conversely, lower octaviation can be coded. For example
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOTEs\octfindown{-5}{2.6}\ql j\ql i\ql h\en
-\endextract
+\zendextract
 \end{music}
-\noindent which is coded as
-\begin{quote}\begin{verbatim}
+\noindent is coded as
+\verb|\NOTEs\octfindown{-5}{2.6}\ql j\ql i\ql h\en|.
+\zkeyindex{octfindown}
+ To change the text that is part of these notations, redefine one of
+the macros \keyindex{octnumberup} or \keyindex{octnumberdown}. The reason for
+the distinction between up and down is that, traditionally, upper octaviation
+only uses the figure
+``8'' to denote its beginning, while lower octaviation uses a more
+elaborate indication such as \hbox{\ppffsixteen8$^{va}$ \it bassa}. Thus
+
+\bigskip
+\begin{music}\nostartrule
 \startextract
-\NOTEs\octfindown{-5}{2.6}\ql j\ql i\ql h\en
-\endextract
-\end{verbatim}\end{quote}\zkeyindex{octfindown}
-If a more sophisticated posting is wanted, this can be achieved refefining
-the macro \keyindex{octnumber}, e.g.:
-
-\begin{music}
-\startextract
-\NOTEs\def\octnumber{\ppffsixteen8$^{va}$}\octfinup{10}3\qu c\qu d\qu e\en
-\endextract
+\NOTEs\def\octnumberup{\ppffsixteen8$^{va}$}\octfinup{10}{2.5}\qu c\qu d\qu e\en
+\zendextract
 \end{music}
-\noindent whose coding is
-\begin{quote}\begin{verbatim}
-\startextract
-\NOTEs\def\octnumber{\ppffsixteen8$^{va}$}\octfinup{10}3\qu c\qu d\qu e\en
-\endextract
-\end{verbatim}\end{quote}
-\noindent or
+\noindent is coded
+
+\noindent\verb|\NOTEs\def\octnumberup{\ppffsixteen8$^{va}$}\octfinup{10}{2.5}\qu c\qu d\qu e\en|
+
+\noindent while
 
 \begin{music}
 \startextract
-\NOTEs\def\octnumber{\ppffsixteen8$^{va\,bassa}$}\octfindown{-5}4\ql l\ql k\ql j\en
+\NOTEs\def\octnumberdown{\ppffsixteen8$_{ba}$}\octfindown{-5}{2.5}\ql l\ql
+k\ql j\en
 \endextract
 \end{music}
-\noindent coded as:
+\noindent is coded as
 \begin{quote}\begin{verbatim}
-\startextract
-\NOTEs\def\octnumber{\ppffsixteen8$^{va\,bassa}$}%
-  \octfindown{-5}4\ql l\ql k\ql j\en
-\endextract
+\NOTEs\def\octnumberdown{\ppffsixteen8$_{ba}$}%
+  \octfindown{-5}{2.5}\ql l\ql k\ql j\en
 \end{verbatim}\end{quote}
 
-\subsubsection{Long or variable range octave transposition}
-Long range octave transpositions are better handled using
-\keyindex{Ioctfinup},
+The foregoing constructions have the drawbacks that (a) the span must be
+indicated ahead of time and (b) they cannot extend across a line break.
+Both restrictions are removed with the use of the alternate macros \keyindex{Ioctfinup},
 \keyindex{Ioctfindown} and
-\keyindex{Toctfin} whose effect extends over line breaks.
+\keyindex{Toctfin}.
 
-{\Bslash Ioctfinup}~$np$ starts an octave transposition of reference number
-$n$ (with $0\le n<6\equiv$\keyindex{maxoctlines}) dashed line at pitch $p$
-(usually $p>10$ but it can also be an alphabetic pitch specification),
-{\Bslash Ioctfindown}~$np$ starts a lower octave transposition at pitch $p$
-(usually $p<-2$), and both extend until terminated with {\Bslash toctfin}. The
+{\Bslash Ioctfinup}~$np$ indicate an upward octave transposition line with reference number
+$n$ ($0\le n<6$) and with dashed line at pitch $p$. Usually $p$ will be numeric and $>9$,
+but it can also be a letter.
+{\Bslash Ioctfindown}~$np$ starts a lower octave transposition line at pitch $p$
+(usually $p<-1$). Both extend until terminated with {\Bslash Toctfin}. The
 difference between {\Bslash Ioctfinup}~$n$ and {\Bslash Ioctfindown}~$n$ is
-the relative position of the ``8'' figure with respect to the dashed line, and
-the sense of the terminating hook (note that {\Bslash Ioctfinup} has a hook
-under the dashed line, and conversely).
-
-For the sake of backward compatibility, \keyindex{ioctfinup} is equivalent to
+the relative position of the figure ``8'' with respect to the dashed line, and
+the sense of the terminating hook As shorthand, \keyindex{ioctfinup} is equivalent to
 \verb|\Ioctfinup 0| and \keyindex{ioctfindown} is equivalent to
 \verb|\Ioctfindown 0|.
-For example:
+
+For example,
 
 \medskip
- \begin{music}
+ \begin{music}\nostartrule
 \instrumentnumber{1}
 \setstaffs12
 \setclef1{6000}
@@ -2520,11 +2901,11 @@ For example:
 \Notes\wh{NMLKJI}|\wh{nmlkji}\Toctfin1\enotes
 \bar
 \Notes\wh{HGFED}\Toctfin2\wh C|\wh{hgfedc}\enotes
-\endextract
+\zendextract
 \end{music}
-whose coding is
+\noindent is coded as
 \begin{quote}\begin{verbatim}
-\begin{music}
+\begin{music}\nostartrule
 \instrumentnumber{1}
 \setstaffs12
 \setclef1{6000}
@@ -2537,112 +2918,88 @@ whose coding is
 \Notes\wh{NMLKJI}|\wh{nmlkji}\Toctfin1\enotes
 \bar
 \Notes\wh{HGFED}\Toctfin2\wh C|\wh{hgfedc}\enotes
-\endextract
+\zendextract
 \end{music}
 \end{verbatim}\end{quote}
  %\check
 
+ The elevation of octaviation lines may be changed in midstream using
+\keyindex{Liftoctline}~$n$$p$, where $n$ is the reference number of the
+ octave line, and $p$ a (possibly negative) number of
+\keyindex{internote}s (staff pitch positions) by which elevation of the dashed line should be changed.
+This may be useful when octaviation lines extend over several systems and the
+elevation needs to be changed in a systems after the one where it was initiated.
 
-%\begin{changebar}
-
- The elevation of octaviation lines may be raised/lowered using
-\keyindex{Liftoctline}~$n$~$p$ where $n$ is the reference number of the
- wanted ocave line, and $n$ a number (possibly negative) number of
-\verb|\internote| by which the dashed line should be lifted. This is
-particularly useful when octaviation lines last several systems and need to be
-lifted in the systems occuring farther than the initiation.
-
-%\end{changebar}
-
- \subsection{Transposition of accidentals}
- The above processes indeed change the vertical position of the note heads
-and associated symbols (note stems, accents and beams) but they do not take
-care of the necessary changes of accidentals when transposing, i.e. the fact
-that an $F\sharp$ occurring with a zero signature should become a $B\natural$
-when transposing from the tonality of $C$ major to $F$ major where the normal
-$B$ is the $B\flat$. Since the intent of the composer is not obvious -- he
-may want to shift a group of notes within the same tonality or conversely to
-transpose it in another tonality -- this is not done automatically. Thus the
-\keyindex{sh}, \keyindex{fl}, \keyindex{na}, \keyindex{dsh} and
-\keyindex{dfl} symbols \ital{are not affected} by a change of the
-\keyindex{transpose} register.
-
- But the composer/typesetter may ask \musixtex\ to do that work. In this
-case, he should code \keyindex{relativeaccid}. In that case, a \verb|\sh|
-command means that the corresponding pitch\footnote{The musical output note,
-not the typesetting position.} has to be raised by \ital{one half pitch}
-with respect to its normal value \ital{according to the current signature}.
-Thus \verb|\sh b| (using \keyindex{relativeaccid}) means a $B\sharp$ if the
-signature is zero or positive, and a $B\natural$ if it is negative. The same
-logic applies for all accidentals using \keyindex{relativeaccid}.
-
-In the same way, the compact codes \verb|^|, \verb|_|, \verb|=| are normally
-not affected by transposition and signatures, but their behaviour will be
-changed by saying \keyindex{relativeaccid} and reset by
-\keyindex{absoluteaccid} (the default situation)\footnote{Note that the
-behaviour of {\Bslash sh}, {\Bslash na} and {\Bslash fl} with \musixtex\
-corresponds to the behaviour of  {\Bslash Sh}, {\Bslash Na} and {\Bslash Fl}
-with \musictex+{musictrp.tex}. But the {\tt musixcpt.tex} file forces the same
-behaviour as \musixtex\ in that respect, see page \pageref{compatibility}.}.
-
- Although \ital{relative accidental coding} is an easy and safe way of
-coding \ital{transposable} scores, care should be exercised in getting rid
-of the habit of saying \verb|\na b| to raise the pitch of a $B$ when the
-tonality is $F$ major (i.e. with \keyindex{setsign$n$}\verb|=-1| or
-\keyindex{generalsignature}\verb|{-1}|). An example of sophisticated
-transposition is given in the score \verb|souvenir.tex| (which \verb|\input|s
-\verb|souvenix.tex|).
-
- %\check
 
 \section{Slurs and ties}
-The slurs and ties provided by \musixtex\ can be divided into two categories:
+Two fundamentally different implementations of slurs, ties, and hairpins are
+available. (The hairpins ``go along for the ride'' with slurs and ties.) First, there are the
+original \ital{font-based} versions. These are constructed with traditional
+\TeX\ font characters that were created with \MF\ and stored in \TeX\ font files.
+Second, it is now possible
+to generate these shapes directly with postscript, dispensing altogether with
+the font characters\footnote{Please do not be confused by the availability of
+postscript versions of the font-based slur fonts (along with all other \musixtex\ fonts).
+Once installed in a \TeX\ system,
+their function and use are 100\% transparently identical with bitmapped versions
+of the slur fonts. On the other
+hand, postscript slurs are functionally distinct from font-based slurs, and only
+ share some of the same syntax.}. We shall first describe the font-based versions,
+then Type K postscript slurs, which are one of two available postscript slur
+options\footnote{An
+alternate approach to postscript slurs, called {\it Type M} after its developer
+Hiroaki {\sc Morimoto}, is available from the
+\href{http://icking-music-archive.org/software/indexmt6.html}
+{\underline{Icking Music Archive}}.}. If you plan to use Type K postscript slurs,
+you may skip directly to section~\ref{PostscriptSlurs}.
+
+ \subsection{Font-based slurs}
+
+Font-based slurs and ties provided by \musixtex\ can be divided into two categories:
 \label{simpleslur}
-\begin{itemize}
+\begin{itemize}\setlength{\itemsep}{0ex}
    \item Those where the complete slur symbol is composed of a single
    character from one of the slur fonts, and
-   \item those where the slur symbol is composed three discrete
+   \item those where the slur symbol is composed of three distinct
    characters, to form the beginning, middle and end of the slur.
 \end{itemize}
-The former are called \ital{simple slurs} and the latter are called
-\ital{compound slurs}. To some extent the division between the two is
-invisible to the user, in that a number of the macros described below will
-select between the two types automatically. However, other macros are
-provided to
-enable simple slurs to be specified. Note that slurs of both types must be
-coded within the pair \verb|\notes...\enotes|.
- \subsection{General slur coding}
-This section describes the usual method of slur coding, where the
-choice between simple or compound slurs is made automatically.
-In this case, slurs are initiated and terminated by separate macros,
-as is the case for beams.
- \subsubsection{Slur initiation}
-The slur must be initiated {\em before}
-the spacing note at which the slur begins, and terminated {\em before} the
-note at which the slur ends. The simplest slur initiation macro is
 
+The former are called \ital{simple slurs} and the latter,
+\ital{compound slurs}. In many cases the distinction between the two is
+invisible to the user, in that many of the macros described below will
+automatically select between the two types. However, there are other macros
+that allow simple slurs to be forced.
 
-\keyindex{isluru}~$np$
-
-\noindent which initiates an upper slur, with reference
-number $n$, beginning at pitch $p$. The starting point of the slur is
-centred above an imaginary quarter note head at pitch $p$.
-As for beams, the reference number $n$ takes values from 0 to 5, or
-0 to 8 if \ttxem{musixadd.tex} is included.
-Similarly, \keyindex{islurd}~$np$ initiates a lower slur.
+The next few subsections describe the usual method of slur coding, where the
+choice between simple or compound slurs is made automatically.
+In this case, slurs are initiated and terminated by separate macros,
+similar to beams.
+
+ \subsubsection{Font-based slur initiation}
+A slur must be initiated \ital{before}
+the spacing note on which the slur begins, and terminated \ital{before} the
+note on which it ends. The basic slur initiation macro is
+\keyindex{isluru}\enpee, which initiates an upper slur, with reference
+number $n$, beginning on a note at pitch $p$. The starting point of the slur is
+centered above a virtual quarter note head at pitch
+$p$\footnote{The slur will start in the same place regardless of whether there is
+{\it actually} a note at pitch $p$.}.
+As with beams, the reference number $n$ can take values from 0 to 5, or
+up to 8 or 11 respectively if \ttxem{musixadd.tex} or \ttxem{musixmad.tex} is included.
+Similarly, \keyindex{islurd}\enpee\ initiates a lower slur.
 These slurs are terminated by coding
-\keyindex{tslur}~$np$ where $n$ is the reference number and $p$ is the
-termination pitch. To illustrate with a simple example, the following
+\keyindex{tslur}\enpee\ where $n$ is the reference number and $p$ is the
+termination pitch. To illustrate with an elementary example, the following
 passage
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOtes\islurd0g\qu g\tslur0{'c}\qu c\en
 \Notes\isluru0{'e}\ibl0e{-2}\qb0{edc}\tslur0b\tqb0b\en
 \bar
 \NOtes\islurd0{'a}\qu a\tslur0{`f}\qu f\en
 \NOTes\hu g\en
-\endextract
+\zendextract
 \end{music}
 
 \noindent was coded as:
@@ -2655,24 +3012,26 @@ passage
 \end{verbatim}\end{quote}
 
 Other macros are provided to change the starting and ending point of the slur
-in relation to the initial and final notes. Thus, \keyindex{issluru}~$np$
-initiates a ``short'' upper slur suitable for linking notes involved in chords. The
+in relation to the initial and final notes. Thus, \keyindex{issluru}\enpee\
+initiates a ``short'' upper slur suitable for linking notes involved in chords.
+The
 starting point is shifted to the right, and is vertically aligned with the
-centre of an imaginary quarter note head at pitch $p$. If a lower short slur
-is wanted, one should use \keyindex{isslurd}~$np$.
-
+center of a virtual quarter note head at pitch $p$. If a lower short slur
+is wanted, one should use \keyindex{isslurd}\enpee.
 
 Sometimes, busy scores call for slurs which are vertically aligned with the
-ends of note stems rather than note heads. These ``beam'' slurs --- so called
-because the slur is written at usual beam height --- are provided by the
-macros \keyindex{ibsluru}~$np$ and \keyindex{ibslurd}~$np$. These macros
+ends of note stems rather than note heads. These ``beam'' slurs---so called
+because the slur is written at usual beam height---are provided by the
+macros \keyindex{ibsluru}\enpee\ and \keyindex{ibslurd}\enpee. These macros
 initiate slurs raised or lowered by the current stem height to accommodate
 stems or beams above or below.
  %\check
 
- \subsubsection{Slur termination}\label {slurtermin}
-Termination of slurs can be achieved in two ways. First, macros matching
-each of the initialization macros are provided, as shown below.\\
+ \subsubsection{Font-based slur termination}
+Font-based slurs that are not forced to be simple must be terminated by an explicit
+command right before the last note under the slur. There are termination
+commands analogous to each of the initiation commands alread presented. They
+are summarized in the following table:
 \begin{center}
   \begin{tabular}{ll}
     Initiation                             &   Termination \\
@@ -2682,123 +3041,87 @@ each of the initialization macros are provided, as shown below.\\
     \keyindex{ibsluru}                     & \keyindex{tbsluru}\\
     \keyindex{ibslurd}                     & \keyindex{tbslurd}\\
     \hline
-  \end{tabular} \end{center} These specific termination macros enable slurs
-started in one way to be terminated in another. For example, a slur beginning
+  \end{tabular} \end{center}
+
+\noindent All of these command have two parameters, $n$ and $p$.
+
+These specific termination macros are not restricted to being used with their
+initiation counterpart. A slur
+started in one sense can be terminated in another. For example, a slur beginning
 as a ``beam'' slur may be terminated as a normal slur. This would be achieved
 using the macro pair \verb|\ibslur...\tslur|.
- \subsubsection{Ties} The coding of \itxem{ties} follows from the above
-discussion as a special case of slurs, i.e. when there is no pitch change.
-Upper ties are initiated by \keyindex{itieu}~$np$ which starts an upper tie of
-reference number $n$ at pitch $p$.
-Lower ties are initiated by \keyindex{itied}~$np$ which starts an lower tie of
-reference number $n$ at pitch $p$.
 
-The starting position of the tie is the same as \verb|\issluru| and
+ \subsubsection{Font-based ties} Font-based ties will have the same shapes as
+ordinary font-based slurs of the same length between notes of equal pitch,
+but there are two important distinctions:
+(1) There cannot be any pitch difference between start and end, and (2) the
+positions of both the beginning and end of a tie relative to the note heads
+are slightly different from those of an ordinary slur\footnote{Editor's note: In
+fact, it appears that the default positioning of the ends of ties is exactly
+the same as that of short slurs.}.
+Upper ties are initiated by \keyindex{itieu}\enpee, which starts an upper tie of
+reference number $n$ at pitch $p$.
+Lower ties are initiated by \keyindex{itied}\enpee, which starts an lower tie of
+reference number $n$ at pitch $p$. The starting position of the tie is the same
+as \verb|\issluru| and
 \verb|\isslurd| respectively. The tie is terminated by coding
-\keyindex{ttie}~$n$.
+\keyindex{ttie}\onen. Note that no pitch parameter is required.
 
-Some simple examples of slurs and ties are illustrated below.
+There are also \ital{short ties}, which bear the same relation to ordinary
+ties as short slurs to ordinary slurs. They are intended to be used between chords.
+They are initiated with
+\keyindex{itenu}\enpee~or \keyindex{itenl}\enpee\footnote{Editor's note: It is
+not clear why this command uses ``{\tt l}'' when all other similar ones use
+``{\tt d}''.}, and terminated with \keyindex{tten}\onen.
 
-\begin{music}
+The following example illustrates the differences in positioning of the various
+slur and tie options:
+
+\begin{music}\nostartrule
+\startextract
+\NOTes\islurd0g\qu g\tslur0g\qu g\isslurd0g\qu g\tsslur0g\qu g%
+\ibsluru0g\qu g\tbsluru0g\qu g\itied0g\qu g\ttie0\qu g%
+\itenl0g\qu g\tten0\qu g\en
+\zendextract
+\end{music}
+\noindent It was coded as
+\begin{quote}\begin{verbatim}
+\NOTes\islurd0g\qu g\tslur0g\qu g\isslurd0g\qu g\tsslur0g\qu g%
+\ibsluru0g\qu g\tbsluru0g\qu g\itied0g\qu g\ttie0\qu g%
+\itenl0g\qu g\tten0\qu g\en
+\end{verbatim}\end{quote}
+
+\noindent Here are some more general examples of font-based slurs and ties
+discussed so far:
+
+\begin{music}\nostartrule
 \startextract
 \NOTes\isluru0g\hl g\tslur0h\hl h\en
 \NOTes\islurd0c\issluru1g\zh{ce}\hu g\tslur0d\tsslur1h\zh{df}\hu h\en
 \NOTes\ibsluru0g\islurd1g\hu g\tubslur0h\hu h\en
 \NOTes\itieu0k\hl k\ttie0\tdbslur1f\hl k\en
-\endextract
+\zendextract
 \end{music}
 \noindent This was coded as:
 \begin{quote}\begin{verbatim}
-\begin{music}
-\startextract
 \NOTes\isluru0g\hl g\tslur0h\hl h\en
 \NOTes\islurd0c\issluru1g\zh{ce}\hu g\tslur0d\tsslur1h\zh{df}\hu h\en
 \NOTes\ibsluru0g\islurd1g\hu g\tubslur0h\hu h\en
 \NOTes\itieu0k\hl k\ttie0\tdbslur1f\hl k\en
-\endextract
-\end{music}
 \end{verbatim}\end{quote}
- \subsubsection{Short ties} Usual music coding makes ties not different of
-slurs, i.e. a tie is typed exactly like a slur linking two notes of same pitch.
-However, this traditional way of doing has two the drawback:
- \begin{itemize}
-  \item in some special cases, a slur might be confused with a tie and
-conversely,
-  \item chord ties cannot be implemented with the slur starting above or below
-the note, but only starting just right of the noetead and finishing just left
-of the other note head.
- \end{itemize}
-  This can be done using \verb|\issluru| (\ref{slurtermin}, p.
-\pageref{slurtermin}) or \keyindex{itenu}~$np$, \keyindex{itenl}~$np$ for tie
-initiation, and \keyindex{tten}~$n$ to terminate it. As an example:
-
- \begin{music}
- \startextract
- \NOTes\itenl0d\itenl1e\itenu2g\itenu3j\zh{ceg}\hu j\enotes
- \bar
- \NOTes\tten0\tten1\tten2\tten3\zh{ceg}\hu j\enotes
- \endextract
- \end{music}
- \noindent was coded as:
- \begin{quote}\begin{verbatim}
- \begin{music}
- \startextract
- \NOTes\itenl0d\itenl1e\itenu2g\itenu3j\zh{ceg}\hu j\enotes
- \bar
- \NOTes\tten0\tten1\tten2\tten3\zh{ceg}\hu j\enotes
- \endextract
- \end{music}
- \end{verbatim}\end{quote}
- %\check
-
-
- \subsubsection{Slur limitations}
-  The vertical gap between slur initiation and slur termination is limited to
-16\verb|\Internote|. Thus exceedingly ascending slurs lead to unfortunate
-results, such as~:
-
- \begin{music}
-\instrumentnumber{1}
-\generalmeter{\meterfrac34}
-\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0j\ql j\enotes
-  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0n\ql n\enotes\endextract
 
-\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0s\ql s\enotes
-  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0z\ql z\enotes\endextract
- \end{music}
- whose coding was:
- \begin{quote}\begin{verbatim}
-\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0j\ql j\enotes
-  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0n\ql n\enotes\endextract
+\subsubsection{Dotted slurs}
 
-\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0s\ql s\enotes
-  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0z\ql z\enotes\endextract
- \end{music}
- \end{verbatim}\end{quote}
+Any font-based slur may be made dotted by specifying \keyindex{dotted}
+just before it is initiated:
 
- Besides, tentative slurs of excessive slope may also yield unexpected shapes,
-such as:
- \begin{music}
-\instrumentnumber{1}
-\generalmeter{\meterfrac34}
-\startextract\NOTes\isluru0c\ql c\enotes\notes\tslur0j\ql j\enotes
-  \bar\NOTes\isluru0c\ql c\enotes\notes\tslur0n\ql n\enotes
- \NOTes\isluru0c\ql c\enotes\notes\tslur0s\ql s\enotes
- \bar\NOTes\isluru0c\ql c\enotes\notes\tslur0z\ql z\enotes
- \endextract
- \end{music}
-
- \subsection{Dotted slurs} Compound and simple slurs (\ref{simpleslur},
-p.\pageref{simpleslur}) may be drawn dotted\footnote{Thanks to Werner {\sc
-Icking}.} specifying \keyindex{dotted} just before slur  initiation.
-
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOtes\dotted\islurd0g\qu g\tslur0{'c}\qu c\en
 \Notes\dotted\isluru0{'e}\ibl0e{-2}\qb0{edc}\tslur0b\tqb0b\en\bar
 \NOtes\dotted\slur{'a}{`f}d1\qu{'a`f}\en
 \NOTes\hu g\en
-\endextract
+\zendextract
 \end{music}
 
 \noindent This was coded as:
@@ -2809,181 +3132,190 @@ Icking}.} specifying \keyindex{dotted} just before slur  initiation.
 \NOTes\hu g\en
 \end{verbatim}\end{quote}
 
- \subsection{*Modifying slur properties}
+ \subsubsection{Modifying font-based slur properties}
 Several macros are provided to modify the shape of slurs already initiated.
-These macros must be coded before the slur termination. Note that only
-compound slurs can be modified. Hence, calling any modification macro forces
-the slur type to be compound.
- \subsubsection{*Changing the rise or fall}
- By default, the arch of a slur rises and falls from its original height by
-three times the vertical note spacing. This can be changed using the macro
+These macros must be coded right before the slur \ital{termination}. Invoking
+any of the macros described in this section will force the slur to be compound.
+
+By default, the midpoint of a font-based slur is three \verb|\internote|s
+above or below a line between its ends. This can be changed using the macro
 \keyindex{midslur}~$h$ where $h$ is the revised vertical displacement. For
-example, \verb|\midslur{6}| coded before \verb|\tslur| causes an upper slur to
+example, \verb|\midslur6| coded right before \verb|\tslur| causes an upper slur to
 rise to a maximum height of \verb|6\internote| above the starting position.
-Note that \verb|\midslur| must be coded {\em immediately} before the slur
-termination (eg, \verb|\tslur|). Coding \verb|\midslur| before setting a
-simple slur causes problems and should be avoided.\\[20pt]
+For example,
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOtes\multnoteskip8\isluru0g\ql g\en
 \notes\tslur0g\ql g\en
-\endextract
+\zendextract
 \startextract
 \NOtes\multnoteskip8\isluru0g\ql g\en
 \notes\midslur7\tslur0g\ql g\en
-\endextract
+\zendextract
 \startextract
 \NOtes\multnoteskip8\isluru2g\ql g\en
 \notes\midslur{11}\tslur2g\ql g\en
-\endextract
+\zendextract
 \end{music}
-This was coded as:
+\noindent was coded as
 \begin{quote}\begin{verbatim}
-\startextract
 \NOtes\multnoteskip8\isluru0g\ql g\en
 \notes\tslur0g\ql g\en
-\endextract
-\startextract
 \NOtes\multnoteskip8\isluru0g\ql g\en
 \notes\midslur7\tslur0g\ql g\en
-\endextract
-\startextract
 \NOtes\multnoteskip8\isluru2g\ql g\en
 \notes\midslur{11}\tslur2g\ql g\en
-\endextract
 \end{verbatim}\end{quote}
- \subsubsection{*Changing the curvature}
-The degree of curvature depends primarily on the initial and terminal
-gradient of the slur, relative to its mean slope. The macro
-\keyindex{curve}~$hij$ allows these to be modified. The first parameter $h$
-is the vertical deviation as for \verb|\midslur| described above. The second
-parameter $i$ sets the initial gradient, while the third parameter $j$ sets
-the
-final gradient. The latter parameters are defined as the horizontal distance
-required to attain maximum vertical deviation. Thus smaller numbers for $i$
+
+The macro \keyindex{curve}$hij$ allows more precise control over the shape
+of a slur or tie. The first parameter $h$
+is the vertical deviation and it works exactly like the sole parameter of
+\verb|\midslur| described above. The second and
+third parameters $i$ and $j$ set the initial and final gradient respectively.
+They are defined as the horizontal distance required to attain maximum
+vertical deviation. Thus smaller numbers for $i$
 and $j$ lead to more extreme gradients.
 The default setting is \verb|\curve344|. Hence, coding \verb|\curve322|
 doubles the initial and final gradient relative to the default.
 As with \verb|\midslur|, \verb|\curve| must be coded {\em immediately} before
-the slur termination.
-Likewise, coding \verb|\curve| before
-a simple slur causes problems and should be avoided.
-
-The example below illustrates the use of \verb|\curve| more clearly.
-
-
+the slur termination. The example below illustrates the use of \verb|\curve|.
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOtes\multnoteskip8\itieu0g\ql g\en
 \notes\ttie0\ql g\en
-\endextract
+\zendextract
 \startextract
 \NOtes\multnoteskip8\itieu1g\ql g\en
 \notes\curve 322\ttie1\ql g\en
-\endextract
+\zendextract
 \startextract
 \NOtes\multnoteskip8\itieu2g\ql g\en
 \notes\curve 111\ttie2\ql g\en
-\endextract
+\zendextract
 \end{music}
-This was coded as:
+\noindent This was coded as
 \begin{quote}\begin{verbatim}
-\startextract
 \NOtes\multnoteskip8\itieu0g\ql g\en
 \notes\ttie0\ql g\en
-\endextract
+\zendextract
 \startextract
 \NOtes\multnoteskip8\itieu1g\ql g\en
 \notes\curve 322\ttie1\ql g\en
-\endextract
+\zendextract
 \startextract
 \NOtes\multnoteskip8\itieu2g\ql g\en
 \notes\curve 111\ttie2\ql g\en
-\endextract
 \end{verbatim}\end{quote}
- %\check
-
 
-
- \subsubsection{*Breaking slurs across a line}
 Two macros are provided to control the behaviour of slurs which extend across
 line breaks. Normally, the part of the slur before the line break is
-treated as a tie.  This can be changed using \keyindex{breakslur}~$np$,
+treated as a tie.  This can be changed using \keyindex{breakslur}\enpee,
 which sets the termination height of
-the broken slur at the line break to pitch $p$, for slur reference number $n$.
+the broken slur at the line break to pitch $p$, for slur number $n$.
 
 After the line break, the slur is normally resumed at the initial pitch
-reference, the one coded in \verb|\islur|. To change this, the macro
-\keyindex{Liftslur}~$np$ may be used. Here $n$ is again the slur reference
-number and $p$ is the change in height relative to the initialization height.
+reference, i.e., the one coded in \verb|\islur|. To change this, the macro
+\keyindex{Liftslur}\verb|{|$n$\verb|}{|$h$\verb|}| may be used.
+Here $n$ is again the slur reference
+number and $h$ is the change in height relative to the initialization height.
 This macro is normally used following line breaks, in which case it is best
 coded using the \verb|\atnextline| macro. For example, coding
 \verb|\def\atnextline{\Liftslur06}| raises the continuation of slur zero
 by \verb|6\internote| relative to its initialization height.
 
-These macros are illustrated by the following example.
-%%
-% Example
-%%
- %\check
+The following example illustrates the use of the macros for broken slurs:
+
+\begin{minipage}[t]{75mm}
+Default, without adjustments:\\
+\begin{music}
+\hsize=50mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt\staffbotmarg0pt%
+%
+%\interstaff{14\internote}%
+%
+\startpiece\bigaccid
+\Notes\ibsluru1b\qu b\qu g\en\bar
+\Notes\qu{'c!}\tslur1f\qu f\en
+\mulooseness1\Endpiece
+\end{music}
+\begin{verbatim}
+\Notes\ibsluru1b\qu b\qu g\en\bar
+\Notes\qu{'c!}\tslur1f\qu f\en
+\end{verbatim}
+\end{minipage}%
+\begin{minipage}[t]{75mm}
+With~\verb|\Liftslur|~and~\verb|\breakslur|~:\\
+\begin{music}
+\hsize=50mm
+\generalmeter{\meterfrac24}%
+\parindent 0pt\staffbotmarg0pt%
+%
+%\interstaff{14\internote}%
+%
+\startpiece\bigaccid
+\def\atnextline{\Liftslur17}%
+\Notes\ibsluru1b\qu b\qu g\breakslur1g\en\bar
+\Notes\qu{'c!}\tslur1f\qu f\en
+\mulooseness1\Endpiece
+\end{music}
+\begin{verbatim}
+\def\atnextline{\Liftslur17}%
+\Notes\ibsluru1b\qu b\qu g%
+\breakslur1g\en\bar
+\Notes\qu{'c!}\tslur1f\qu f\en
+\end{verbatim}
+\end{minipage}\medskip
 
- \subsubsection{*Inverting slur termination}
 Occasionally in keyboard works one needs to begin a slur in one
-stave but end it in another. This can be done using the macro
-\keyindex{invertslur}~$n$ which is best described by reference to the example
+staff but end it in another. This can be done using the macro
+\keyindex{invertslur}\onen\ which is best described by
+reference to the example
 shown below.
 
 % Finding the final pitch is try and error, sorry, no way out.
 
 \begin{music}
 \setstaffs1{2}
-\setclef1\bass
+\setclef1\bass\interstaff{10.5}
 \startextract
 \NOtes\multnoteskip5\isluru0a\ql a\en
-\notes\invertslur0\curve311\tslur0g|\qu d\en
+\notes\invertslur0\curve311\tslur0j|\qu d\en
 \NOtes\multnoteskip{10}\isluru0a\ql a\en
-\notes\invertslur0\curve333\tslur0g|\qu d\en
-\endextract
+\notes\invertslur0\curve333\tslur0j|\qu d\en
+\zendextract
 \end{music}
-This was coded as:
+\noindent This was coded as
 \begin{quote}\begin{verbatim}
-\setstaffs1{2}
-\setclef1{\bass}
-\startextract
 \NOtes\multnoteskip5\isluru0a\ql a\en
 \notes\invertslur0\curve311\tslur0g|\qu d\en
 \NOtes\multnoteskip{10}\isluru0a\ql a\en
 \notes\invertslur0\curve333\tslur0g|\qu d\en
-\endextract
 \end{verbatim}\end{quote}
 
- \begin{remark}
- Slur inversion is achieved at a place where its slope ise zero~; therefore it
-only works with ascending slurs started with \verb|\isluru|, and with
+\noindent Slur inversion as just described takes effect where the slope is zero; therefore it
+only works with ascending slurs that were started with \verb|\isluru|, and with
 descending slurs started with \verb|\islurd|. Otherwise no horizontal place
 can be found and the result is erratic.
 
- This second situation can be solved manually, stopping the slur at a
-reasonable place with \verb|\tslur| and restarting in the other sense at the
-same place. Stopping and restarting obviously refer to virtual note pitches (a
-vertical position without actual note) which should be adjusted to have the
-minimum discontinuity.
- \end{remark}
-
- To make this drawing easier, three commands have been provided:
- \begin{itemize}
- \item \keyindex{Tslurbreak}$np$ stops slur number $n$ exactly at pitch $p$,
+A different approach removes this restriction. The idea is to stop the slur at a
+the desired inversion point and restart it in the other sense at the
+same place. The commands to do this are as follows:
+ \begin{itemize}\setlength{\itemsep}{0ex}
+ \item \keyindex{Tslurbreak}\enpee~stops slur number $n$ \ital{exactly} at pitch $p$,
 not above or below the virtual note head.
- \item \keyindex{Islurubreak}$np$ restarts an upper slur at the same position,
+ \item \keyindex{Islurubreak}\enpee~restarts an upper slur at the same position,
 not above a virtual note head.
- \item \keyindex{Islurdbreak}$np$ restarts an lower slur at the same position,
+ \item \keyindex{Islurdbreak}\enpee~restarts a lower slur at the same position,
 not below a virtual note head.
  \end{itemize}
- Thus, the following pattern
 
- \begin{music}
+\noindent The vertical position may have to be adjusted to minimize any discontinuity
+in the slope. For example, the following pattern
+
+ \begin{music}\nostartrule
 \setclef1\treble
 \startextract
 \NOTes\multnoteskip 3\isluru0a\ql a\en
@@ -2992,43 +3324,37 @@ not below a virtual note head.
 \NOTes\multnoteskip 3\islurd0a\ql a\en
 \NOTes\multnoteskip 3\Tslurbreak0d\Islurubreak0d\sk\en
 \Notes\tslur0h\qu h\en
-\endextract
+\zendextract
 \end{music}
-was coded as
+\noindent was coded as
 \begin{quote}\begin{verbatim}
- \begin{music}
-\setclef1\treble
-\startextract
+\begin{music}\nostartrule
 \NOTes\multnoteskip 3\isluru0a\ql a\en
 \NOTes\multnoteskip 3\Tslurbreak0d\Islurdbreak0d\sk\en
 \Notes\tslur0h\qu h\en
 \NOTes\multnoteskip 3\islurd0a\ql a\en
 \NOTes\multnoteskip 3\Tslurbreak0d\Islurubreak0d\sk\en
 \Notes\tslur0h\qu h\en
-\endextract
 \end{music}
-\end{verbatim}\end{quote} 
-
- 
+\end{verbatim}\end{quote}
 
- 
- \subsection{Simple slurs}
-Simple slurs and ties have the advantage
-of optimal aesthetics and simple coding, but are limited in length to 68pt
+\ital{Simple} slurs and ties have advantages in some cases: (1) They will
+always have the best possible shape, and (2) if \verb|\noteskip| doesn't
+change from start to finish, they are easier to code. But they have drawbacks
+as well: (1) They are limited in length to 68pt
 for slurs and 220pt for
-ties. Also, the maximum vertical extent of simple slurs is 8 times the
-internote spacing, and the slurs may not extend across a line break.
+ties, (2) their maximum vertical extent is \verb|8\internote|, and (3) they
+may not extend across a line break.
 Despite all these limitations, simple slurs are extremely useful in many
 applications where the slurs are short and contained within a bar.
 
-Simple slurs extend to the right of the note immediately following.
-Hence they must be coded {\em before} the note at which the slur begins.
-The primary macro call is
-\keyindex{slur}~$p_1p_2sl$
+Simple slurs must be coded {\em before} the note on which the slur begins.
+The primary macro is
+\keyindex{slur}\verb|{|$p_1$\verb|}{|$p_2$\verb|}|$sl$
 where $p_1$ and $p_2$ are respectively the initial and final pitches,
-$s$ is the sense, either {\tt u} or {\tt d}, and $l$ is the length,
-in units of the current value of {\tt noteskip}.
-Thus, thirds slured in pairs can be coded:
+$s$ is the sense (either ``{\tt u}'' or ``{\tt d}''), and $l$ is the length,
+in {\tt noteskip}s.
+Thus, thirds slured in pairs can be coded
 
  %\check
 
@@ -3040,9 +3366,9 @@ Thus, thirds slured in pairs can be coded:
 \NOtes\slur{'d}bu1\ql{db}\en
 \NOtes\slur{'c}au1\ql{ca}\en
 \end{verbatim}\end{quote}
-which yields:
+which yields
 
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \NOtes\slur ced1\qu{ce}\en
 \NOtes\slur dfd1\qu{df}\en
@@ -3050,241 +3376,435 @@ which yields:
 \NOtes\slur{'e}cu1\ql{ec}\en
 \NOtes\slur{'d}bu1\ql{db}\en
 \NOtes\slur{'c}au1\ql{ca}\en
-\endextract
+\zendextract
 \end{music}
 %%
-Similarly, ties may be set using
-\keyindex{tie}~$psl$ where $p$ is the (single) pitch, and the other
-parameters are as described above.
-
-Variants on these macros are provided to change the slur length
-and vertical offset relative to the starting note, as follows.
-\begin{itemize}
-  \item \keyindex{sslur}~$p_1p_2sl$, which sets a `short' slur,
-        designed for the case when a slur is required to link notes which
-        form part of a chord (see \verb|\isslur| above).
-        The macro \keyindex{stie}~$psl$ sets analagous ties.
-%!  \item \keyindex{bslur}~$p_1p_2sl$, which sets a `beam' slur, raised or
-%!        lowered so that the slur links the ends of note stems rather than
-%!        note heads.
-\end{itemize}
- %\check
-
- \subsection{Restrictions}
-Generation of some of the slur fonts is problematic for \MF.
-In particular, the long ties tend to exceed \MF's
-maximum dimension for high resolution printers. However, for normal 300 dpi
-printers there is no problem. A solution to this limitation is planned
-for Postscript\raise1.5ex\hbox{\small\copyright} printers using
-DVIPS \verb|\special| commands.
-
-\section{Bars}
- \subsection{Bars and spacing}
- Ordinary \ital{bars} are coded using the macro \keyindex{bar}. Its drawback
-is that it does not differ from \verb|\bar| which is already defined in
-\TeX's mathematical mode. \index{bar (original meaning)@{\Bslash bar}
-\ital{(original meaning)}} Therefore, inside \verb|\startpiece...\endpiece|
-\ital{our} \verb|\bar| means a musician \ital{bar}\footnote{\ital{Mesure} in
-French, \ital{Takt} in German.} and outside, it keeps its original meaning.
-If you \ital{really} need the original \verb|\bar| inside, you can say
-\verb|\endcatcodesmusic...\bar...\catcodesmusic|.
- %\check
 
- \subsection{Bar numbering}
-Unless otherwise specified, \index{bar numbering}bars are
-numbered. This is a good means of finding errors provided that the \musixtex\
-user has put comments in his source text recording the (expected) bar number.
-However, this can look unpleasant for final outputs, since the habit is to
-number bars only each other five or ten bars. This is not a serious problem
-since the frequency of bar numbering is defined as:
+There are similar commands to force simple versions of the other
+variants of font-based slurs and ties. Simple ties may be set using
+\keyindex{tie}\verb|{|$p$\verb|}|$sl$ (only one pitch is needed).
+Simple short slurs and short ties can be forced with the macros
+\keyindex{sslur}\verb|{|$p_1$\verb|}{|$p_2$\verb|}|$sl$ and
+\keyindex{stie}\verb|{|$p$\verb|}|$sl$ respectively. Finally,
+simple beam slurs can be forced with
+\keyindex{bslur}$s$\verb|{|$p_1$\verb|}{|$p_2$\verb|}|$l$.
 
- \verb|\def|\keyindex{freqbarno}\verb|{1}|
+ \subsubsection{Limitations of font-based slurs}
+  The change in altitude between slur initiation and slur termination is limited to
+16\verb|\Internote|. Thus unexpected vertical gaps can appear, as seen in
 
-If you replace the {\tt1} by {\tt5}, bar numbering will occur each other five
-bars. You can also inhibit any bar number\footnote{default inside this manual}
-printing by telling:
+ \begin{music}\nostartrule
+\instrumentnumber{1}
+\generalmeter{\meterfrac34}
+\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0j\ql j\enotes
+  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0n\ql n\enotes\zendextract
 
-\keyindex{nobarnumbers}
+\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0s\ql s\enotes
+  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0z\ql z\enotes\zendextract
+ \end{music}
+ \noindent whose coding was
+ \begin{quote}\begin{verbatim}
+\NOTes\multnoteskip3\isluru0c\ql c\tslur0j\ql j\enotes
+  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0n\ql n\enotes
+\NOTes\multnoteskip3\isluru0c\ql c\tslur0s\ql s\enotes
+  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0z\ql z\enotes
+ \end{music}
+ \end{verbatim}\end{quote}
 
-\noindent If you want to restore bar numbering after \verb|\nobarnumbers|,
-you can say
+Furthermore, if the slope becomes too steep, even worse results can occur, such as
 
-\keyindex{barnumbers}
+ \begin{music}\nostartrule
+\instrumentnumber{1}
+\generalmeter{\meterfrac34}
+\startextract\NOTes\isluru0c\ql c\enotes\notes\tslur0j\ql j\enotes
+  \bar\NOTes\isluru0c\ql c\enotes\notes\tslur0n\ql n\enotes
+ \NOTes\isluru0c\ql c\enotes\notes\tslur0s\ql s\enotes
+ \bar\NOTes\isluru0c\ql c\enotes\notes\tslur0z\ql z\enotes
+ \zendextract
+ \end{music}
 
- The bar counter is also accessible, its name is \keyindex{barno}.
-You can change it without any dramatic consequence.
+Another limitation of font-based slurs crops up when one attempts to
+generate bitmapped versions for high-resolution printers: the characters
+for long ties can exceed \MF's maximum capacity.
+
+ \subsection{Type K postscript slurs}\label{PostscriptSlurs}
+All of the aforementioned limitations of font-based slurs can be circumvented
+by using Type~K postscript slurs\footnote{``K'' stands for Stanislav Kneifl,
+the developer of the Type K postscript slur package.}. As well as slurs, the package includes
+ties and crescendos (see section \ref{sec:crescnd}).
+Its use is very similar to font-based slurs, and in fact identical if only
+the elementary slur and tie initiation and termination macros are used.
+
+In order to use Type K postscript slurs, you must first place \texttt{musixps.tex}
+anywhere \TeX\ can find it. You must also place \texttt{psslurs.pro}
+somewhere that \texttt{dvips} can find it.
+
+The \index{mxsk font}\texttt{mxsk} font is required for ``half ties,'' which
+are special symbols that are used by default for the second portion of a tie
+that crosses a line break. If you like
+this treatment you must install the font in your \TeX\ system. However, perfectly
+acceptable line-breaking ties will appear if you invoke \keyindex{nohalfties},
+and then you will not have to install this font.
+
+Once the software mentioned in the prior two paragraphs is emplaced and the
+\TeX\ filename database is refreshed, the Type K package can be
+invoked by including the command \verb|\input musixps|
+near the beginning of your source file.
+The resulting dvi file should then be converted into postscript using \textbf{dvips}.
+If desired, a PDF file can then be generated with \textbf{ps2pdf}, \textbf{ghostscript},
+\textbf{Adobe Acrobat} (see chapter \ref{installation} for more information on this).
+
+Two minor inconveniences with Type K postscript slurs are that (1) they won't appear
+in any standard dvi previewer, and (2) they won't appear in PDF files generated with
+\textbf{pdftex}. The former limitation can be circumvented by using a postscript
+viewer such as \textbf{GSview}. The latter simply requires that you create an intermediate
+postscript file with \textbf{dvips}, then make the PDF with any of the software
+mentioned above.
+
+\subsubsection{Initiating and terminating type K postscript slurs}
+
+Basic usage of type K slurs is the same as for font-based slurs. To initiate one,
+use for example \verb|\isluru0g| to start an upper slur with ID 0 above a virtual note
+at pitch level {\tt g}. To terminate one, use a command like
+\verb|\tslur0i| which terminates the slur with ID 0 on a
+virtual note at pitch level {\tt i}.
+Both types of commands are non-spacing and must precede the first or last
+note under the slur.
+
+You can shift the starting or ending point slightly to the left
+or right by substituting one of the commands \keyindex{ilsluru},
+\keyindex{ilslurd}, \keyindex{irsluru},
+\keyindex{irslurd}, \keyindex{trslur} or \keyindex{tlslur}.
+
+You can control the shape of Type K slurs with variants of
+the termination command. To make the slur a bit flatter than default use
+\keyindex{tfslur}0f; a bit higher, \keyindex{thslur}0f; higher still,
+\keyindex{tHslur}0f;  or
+even higher, \keyindex{tHHslur}0f.  These commands have an effect like
+\keyindex{midslur} does for font-based slurs.
+
+All combinations of the shifting and curvature variants are allowed,
+e.g.\ \verb|\trHHslur|.
+
+The following examples demonstrate how much better the type K slurs perform
+in the extreme situations of the prior two typeset examples. The coding is
+exactly the same as above except that \verb|\input musixps| has been added:
+\begin{quote}\begin{verbatim}
+\begin{music}\nostartrule
+\input musixps
+\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0s\ql s\enotes
+....
+\end{verbatim}\end{quote}
 
-Sometimes there is need for to start with a \verb|\barno| value which differs
-from 1. Perhaps the piece starts with an \ital{upbeat}, then you can code
+%\begin{center}
+%\includegraphics[scale=1]{./mxdexamples/pslurvgap.eps}
+%\end{center}
 
-\keyindex{startbarno}\verb|=0|
+\begin{music}\nostartrule
+\input musixps
+\instrumentnumber{1}
+\generalmeter{\meterfrac34}
+\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0j\ql j\enotes
+  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0n\ql n\enotes\zendextract
 
-\noindent in front of \verb|\startpiece|; or you may want to typeset only an
-excerpt starting for example with bar number
-198, then you can code \verb|\startbarno=198|. Pay attention because
-saying \verb|\startbarno=|$n$ has a global meaning. So if you want to
-\verb|\input| several pieces whose starting bar numbers differ, you have to
-adjust the value of \verb|\startbarno| each time.\label{startbarno}
+\startextract\NOTes\multnoteskip3\isluru0c\ql c\tslur0s\ql s\enotes
+  \bar\NOTes\multnoteskip3\isluru0c\ql c\tslur0z\ql z\enotes\zendextract
+% \end{music}
 
- %\check
+%\begin{music}\nostartrule
+%\input smallmusixpsx
+%\instrumentnumber{1}
+%\generalmeter{\meterfrac34}
+\startextract
+\NOTes\isluru0c\ql c\enotes\notes\tslur0j\ql j\enotes\bar
+\NOTes\isluru0c\ql c\enotes\notes\tslur0n\ql n\enotes
+\NOTes\isluru0c\ql c\enotes\notes\tslur0s\ql s\enotes\bar
+\NOTes\isluru0c\ql c\enotes\notes\tslur0z\ql z\enotes
+\zendextract
+ \end{music}
 
-The best compromise between information of the bar number and a pleasant
-lookout is the command \keyindex{systemnumbers} which draws the bar numbers
-only at the left top of every system (or staff? then the command will
-be renamed to \verb|\staffnumbers| or \verb|\staffbarnumbers|).
 
-You can influence the height of the system numbers by coding
+For maximal control over type K slurs, you can use one of the commands
+\keyindex{iSlur}~$npvh$ and
+\keyindex{tSlur}~$npvhca$, where the characters in
+$npvhca$ respectively stand for ID number, height, vertical offset, horizontal offset,
+curvature, and angularity.
+All offsets are in \verb|internote|, and the slur direction is determined
+by the sign of the vertical offset. See the comments in \verb|musixps.tex|
+for precise definitions of the other parameters. Examples of permissible forms for
+these commands are
+\verb|iSlur0c11| and \verb|tSlur0{!d}11{.2}0|.
 
-\verb|\def|\keyindex{raisebarno}\verb|{|\ital{any \TeX~dimension}\verb|}|
+The next example shows how you can use \verb|iSlur| in difficult
+circumstances:
 
-\noindent whose default is set to \verb|4\internote| to fit above
-a violin clef. You can influence its horizontal position with
+\begin{music}\nostartrule
+\input musixps
+\nobarnumbers
+\generalsignature1%
+\generalmeter{\meterfrac{2}{4}}%
+\nostartrule
+\startextract
+\NOtes\zchar{-8}{\Bslash irslur...\Bslash tlslur}\irslurd0{'b}\zhl b\sk\zq{!e}\qu{'c}\en\bar
+\NOtes\zh{'d}\zhu{`f}\off{7.2pt}\tlslur0{'b}\ql b\ql b\en\bar
+%
+\NOtes\zchar{-8}{\Bslash irslur...\Bslash tlfslur}\irslurd0{'b}\zhl b\sk\zq{!e}\qu{'c}\en\bar
+\NOtes\zh{'d}\zhu{`f}\off{7.2pt}\tlfslur0{'b}\ql b\ql b\en\bar
+%
+\NOtes\zchar{-8}{\Bslash iSlur...\Bslash tSlur}\iSlur0{'b}{-.5}3\zhl b\sk\zq{!e}\qu{'c}\en\bar
+\NOtes\zh{'d}\zhu{`f}\off{7.2pt}\tSlur0{'b}{.5}{-1}{.3}0\ql b\ql b\en
+\zendextract
+ \end{music}
+\noindent with this coding:
 
-\verb|\def|\keyindex{shiftbarno}\verb|{|\ital{any \TeX~dimension}\verb|}|
+\begin{quote}\begin{verbatim}
+\NOtes\irslurd0{'b}\zhl b\sk\zq{!e}\qu{'c}\en\bar
+\NOtes\zh{'d}\zhu{`f}\off{7.2pt}\tlslur0{'b}\ql b\ql b\en\bar
+%
+\NOtes\irslurd0{'b}\zhl b\sk\zq{!e}\qu{'c}\en\bar
+\NOtes\zh{'d}\zhu{`f}\off{7.2pt}\tlfslur0{'b}\ql b\ql b\en\bar
+%
+\NOtes\iSlur0{'b}{-.5}3\zhl b\sk\zq{!e}\qu{'c}\en\bar
+\NOtes\zh{'d}\zhu{`f}\off{7.2pt}\tSlur0{'b}{.5}{-1}{.3}0\ql b\ql b\en
+\end{verbatim}\end{quote}
 
-\noindent which default value is \verb|0pt|. If you don't like the box around
-the bar number or its font, you can redefine the macro which sets the system
-bar number; its default is
 
-\verb|\def|\keyindex{writebarno}%
-  \verb|{\boxit{\eightbf\the\barno\barnoadd}}|
+The ID number for a slur, tie or crescendo should
+normally range from 0 to 9. If it is bigger
+than nine but less than 15,
+the object can cross a line break but not a page break. If bigger than
+14 but less than $2^{31}$, it can't be broken at all,
+        nor can a slur termination be positioned at a beam with
+        e.g.~\verb|\tbsluru{17684}{16}|; however \verb|\ibsluru{152867}{16}| is OK.
 
- \noindent where \keyindex{boxit} is a utility macro provided by \musixtex{}
-whose purpose is to enclose its argument in a \raise-\boxitsep\hbox{\boxit{box}}.
+It's also OK to have opened simultaneously a slur, tie and crescendo all
+with the same ID, or a slur, tie and decrescendo, but not a crescendo and
+decrescendo.
 
+\def\emen{{\tt\char123}$n${\tt\char125\char123}$m${\tt\char125}}
 
-\medskip
-\begin{music}
-\let\extractline\hbox
-\startbarno=36
-\hbox to \hsize{%
-\hss
-  \raise20pt\hbox{(a) }%
-  \systemnumbers\startextract
-    \Notes\wh g\en
-  \zendextract
-\hss
-  \def\writebarno{\tenrm\the\barno\barnoadd}%
-  \def\raisebarno{2\internote}%
-  \def\shiftbarno{2.5\Interligne}%
-  \raise20pt\hbox{(b) }%
-  \systemnumbers\startextract
-    \Notes\wh g\en
-  \zendextract
-\hss
-  \def\writebarno{\llap{\tenbf\the\barno\barnoadd}}%
-  \def\raisebarno{2\internote}%
-  \def\shiftbarno{1.3\Interligne}%
-  \raise20pt\hbox{(c) }%
-  \systemnumbers\startextract
-    \Notes\wh g\en
-  \zendextract
-\hss}
-\end{music}
-which was coded as
-\begin{itemize}
- \item[(a)] (default)
- \item[(b)]
-  \begin{verbatim}
-\def\writebarno{\tenrm\the\barno\barnoadd}%
-\def\raisebarno{2\internote}%
-\def\shiftbarno{2.5\Interligne}%
-  \end{verbatim}
- \item[(c)]
-  \begin{verbatim}
-\def\writebarno{\llap{\tenbf\the\barno\barnoadd}}%
-\def\raisebarno{2\internote}%
-\def\shiftbarno{1.3\Interligne}%
-  \end{verbatim}
-\end{itemize}
-If the previous line does not stop with a bar rule to the next system bar number
-is added the \keyindex{writezbarno} whose default setting is the lower
-character {\tt'a'}. If you want a {\tt'+}' instead, you can say
+\subsubsection{Type K postscript beam slurs}
+Type K beam slurs are defined differently than the font-based ones:
+They require as parameters both a slur ID number $n$ and a beam ID number $m$,
+but that's all. The commands are
+\keyindex{iBsluru}\emen, \keyindex{iBslurd}\emen, and
+\keyindex{tBslur}\emen.
+They must be placed \ital{after} the beam initiation or termination command.
+Type K slurs may start on one beam and end on another.
+For example,
 
-\verb|\def|\keyindex{writezbarno}\verb|{+}|
+\begin{quote}\begin{verbatim}
+\Notes\ibu0i0\iBsluru00\qb0{eh}\tbu0\qb0i\ibu0j0\qb0{jl}\tbu0%
+ \slurtext{6}\tBslur00\qb0e\en
+\end{verbatim}\end{quote}
 
- Besides, you can change the font and anything in the format of current bar
-numbers by changing the original definition of the macro
-\keyindex{writethebarno} or the font in \keyindex{fontbarno}, where the
-defaults are:
+\noindent produces
+%\begin{center}
+%\includegraphics[scale=1]{./mxdexamples/psbeamslur.eps}
+%\end{center}
+
+\begin{music}\nostartrule\input musixps\startextract
+\Notes\ibu0i0\iBsluru00\qb0{eh}\tbu0\qb0i\ibu0j0\qb0{jl}\tbu0%
+ \slurtext{6}\tBslur00\qb0e\en
+\zendextract\end{music}
+
+The above example also illustrates the use of the macro
+\keyindex{slurtext}. It has just one parameter---some text to be
+printed---and it centers it just above or below the midpoint of
+the next slur that is closed.
+This works only for non-breaking slurs; if the slur is broken,
+the text
+disappears\footnote{If you insist on viewing files with a dvi viewer despite the
+fact that Type K slurs will not be visible, you may also find that
+figures emplaced with \keyindex{slurtext} will appear at the end of the
+slur rather than the middle.}.
+%The placing of the slur text is done with a very dirty postscript
+%hack, so I am not really sure that everything you want to typeset
+%will be placed at the correct position (if you are interested, see
+%the end of psslurs.pro for details). If you find something that won't
+%work, let me know.
+
+% DAS: why do we need this ???
+%\paragraph{General coding for postscript slurs and ties of type K.}
+%This can be done by:
+%\begin{quote}\begin{verbatim}
+%\i[h.shift]slur[u|d]{slur ID}{note height}
+%\t[h.shift][slur height]slur{slur ID}{note height}
+%\iBslur[u|d]{slur ID}{beam ID}
+%\tB[slur.height]slur{slur ID}{beam ID}
+%\end{verbatim}\end{quote}
+%\noindent where h.shift can be 'l', 'r' or nothing
+%and slur.height can be 'f', nothing, 'h', 'H' or 'HH'
+%
+%Example: \keyindex{tlfslur} means 'terminate left flat slur'.
+%
+%
+%There are also simple slurs with same invocation and parameters as the
+%original ones.
+
+\subsubsection{Type K postscript ties}
+All of the foregoing Type K slur commands have counterparts for ties. Simply
+replace ``\verb|slur|'' with ``\verb|tie|'', and for terminations omit
+the pitch parameter. Type K ties not only are positioned differently by
+default, but they also have different shapes than slurs.
+
+\subsubsection{Dotted type K slurs and ties.}%please check the capital D(otted)
+A slur or tie can be made dotted simply by entering \keyindex{dotted} anywhere before
+the beginning of the slur or tie. Only the first slur or tie following this
+command will be affected. On the other hand, if you enter \keyindex{Dotted}, then ALL
+slurs and ties from this point forward will be dotted until you say
+\keyindex{Solid}. Furthermore, inside \verb|\Dotted...\Solid| you can make any individual
+slur or tie solid saying \verb|\solid| before its beginning.
+
+\subsubsection{Avoiding collisions of Type K slurs and ties with staff lines.}
+In postscript it is possible to do some computations which would be very hard
+to implement directly in TeX. Type K slurs can use this facility to check whether
+the curve of a slur or tie is anywhere nearly tangent to any staff line, and if
+so, to adjust
+the altitude of the curve to avoid the collision. By default this feature is turned
+on.
+You can disable it either
+globally (\keyindex{Nosluradjust}, \keyindex{Notieadjust}) or locally
+(\keyindex{nosluradjust}, \keyindex{notieadjust}), and you can also turn it
+back on globally (\keyindex{Sluradjust},
+\keyindex{Tieadjust}) or locally (\keyindex{sluradjust}, \keyindex{tieadjust}).
+Here ``locally''
+means that the command will only affect the next slur or tie to be opened.
+
+
+\subsubsection{Line breaking slurs and ties}
+Tyle K slurs and ties (and crescendos) going across line breaks are handled
+automatically. In fact they can go over more lines than two (this is
+true also for ties, though it would be somewhat strange).
+
+There is a switch \verb|\ifslopebrkslurs| that controls the default
+height of the end point
+of the first segment of all broken slurs. By default the height will be
+the same as the beginning. To have it raised by \verb|3\internote|, simply
+issue the command \keyindex{slopebrkslurstrue}. To revert to the default,
+use \keyindex{slopebrkslursfalse}.
+
+To locally override the default height of the end of the first segment,
+use the command \keyindex{breakslur}\enpee,
+which sets the height for slur number $n$ to pitch $p$, just like with
+font-based slurs.
+
+You can raise or lower the starting point of the second segment of a broken slur
+with the command \keyindex{liftslur}\verb|{|$n$\verb|}{|$h$\verb|}|, with
+parameters slur ID and relative offset in
+\verb|\internote|s measured from the slur beginning. Its effect is
+the same as \keyindex{Liftslur} for font-based slurs, except it is not
+necessary to code
+it within \verb|\atnextstaff{}|, just anywhere inside the slur.
+
+As already mentioned, anything with ID$<$10 is broken fully automatically, but
+you should be careful about slurs, ties and crescendos with 10$\le$ID$<$15.
+These cannot cross page breaks, although they can cross line breaks.
+
+If the second segment of a broken tie is less than 15pt long, then by
+default it will have a special shape which begins horizontally. These shapes are
+called \ital{half ties} and are contained in the font \index{mxsk font}\verb|mxsk|.
+Of course if they are to be used, the font files must be integrated into the
+\TeX\ installation. Their use can be turned off with \keyindex{nohalfties}
+and back on with \keyindex{halfties}.
+
+%\paragraph{Backwards compatibility.}
+%There are several ``aliases'' which allow to use the old, bitmapped slur
+%commands for PS slurs without any change. There are however a few differences:
+%the \keyindex{invertslur} is not implemented yet and
+%the \keyindex{curve} and \keyindex{midslur} macros have no effect.
+
+%\paragraph{Memory requirements.}
+\subsubsection{A few final technical details}
+Each \verb|\i...| and \verb|\t...|
+produces a \verb|\special| command, which must be stored in TeX's main memory.
+Therefore, if too many slurs occur in one page, some memory problems could
+occur. The only solutions are to use Big\TeX\ (if you aren't already), or to use
+font-based slurs.
+
+Type K slurs need the postscript header file
+\index{psslurs.pro}\texttt{psslurs.pro} to be included in the
+output postscript file. This is made to happen by the \TeX\ command
+\verb|\special{header=psslurs.pro}|, which is automatically
+included when you \verb|\input musixps|. So normally this is not
+of concern. However if you wish to extract a subset of pages from
+the master \verb|dvi| file using \index{dvidvi}\texttt{dvidvi}, then
+you have three options: (1)~include the first page in the subset,
+(2)~manually issue the
+\verb|\special| command in the \TeX\ source for the first page of the subset, or
+(3)~use the option \texttt{-h psslurs.pro} when you run \texttt{dvips}.
+
+
+\section{Bar Lines}
+ \subsection{Single, double, and invisible bar lines}\label{doublebars}
+The usual macro to typeset a single bar line is \keyindex{bar}.
+There is a possibility of
+confusion with a command in \TeX's math mode that has exactly the same name.
+However, there will generally be no problem, because inside
+\verb|\startpiece...\endpiece|,
+\verb|\bar| will take the musical meaning, while outside, it will have the
+mathematical one.
+If for some reason you need the math \verb|\bar| inside, you can use
+\verb|\endcatcodesmusic...\bar...\catcodesmusic|.
 
-  \verb|\def\writethebarno{\fontbarno\the\barno\kernm\qn@width}|
-  
-  \verb|\def\fontbarno{\it}|
+To typeset a double bar line with two thin rules, use \keyindex{doublebar}. You could
+also issue \keyindex{setdoublebar} to cause the next \verb|\bar| (or
+\keyindex{stoppiece}, \keyindex{alaligne}, or \keyindex{alapage}) to be replaced
+by a double bar.
 
+There is no specific command to print a thin-thick double bar line, but
+\keyindex{setdoubleBAR} will cause one in the same cases where
+\verb|\setdoublebar| would cause a thin-thin double bar line.
 
-  \noindent For example:
+To make the next bar line invisible, use \keyindex{setemptybar} before
+\verb|\bar|.
 
-  \medskip
-\begin{music}\barnumbers
-\parindent0pt\startpiece
-\Notes\Dqbu gh\Dqbl jh\en
-\notes\Dqbbu fg\Dqbbl hk\en\bar
-\Notes\Tqbu ghi\Tqbl mmj\en
-\def\fontbarno{\bf}%
-\notes\Tqbbu fgj\Tqbbl njh\en\bar
-\Notes\Qqbu ghjh\Qqbl jifh\en\bar
-\notes\Qqbbu fgge\Qqbbl jhgi\en\endpiece
-\end{music}
-\noindent which was simply coded as:
-\begin{quote}\begin{verbatim}\barnumbers
-\Notes\Dqbu gh\Dqbl jh\en
-\notes\Dqbbu fg\Dqbbl hk\en\bar
-\Notes\Tqbu ghi\Tqbl mmj\en
-\def\fontbarno{\bf}%
-\notes\Tqbbu fgj\Tqbbl njh\en\bar
-\Notes\Qqbu ghjh\Qqbl jifh\en\bar
-\notes\Qqbbu fgge\Qqbbl jhgi\en
-\end{verbatim}\end{quote}
- %\check
+You can suppress the beginning vertical rule with saying \keyindex{nostartrule}
+and restore the default with \keyindex{startrule} after that.
 
+\subsection{Simple discoutinuous bar lines}
+Normally, bars (as well as double bars, final bars and repeat bars) are
+drawn continuously from the bottom of the lowest staff of the
+lowest instrument to the top of the highest staff of the uppermost
+instrument. However, if desired, they can be made discontinuous between
+instruments by saying \keyindex{sepbarrules}. An example of this is given in
+%avrb
+%{\tt ANGESCAO} (or {\tt ANGESCAM}) example; it has also been used in the
+%avre
+\texttt{avemaria.tex} in section \ref{avemaria}\label{avemaria2}.
+
+Continuous bar lines can be restored with \keyindex{stdbarrules}. In
+the extension library are some more types of bar rules, mainly for very old
+music, see section \ref{otherbars}.
 
+% DAS. Andre, are there some other kinds of bars in an addon?
 
- %\check
+\subsection{Elementary asynchronous bar lines}
 
-\noindent Besides, you can suppress the messages of bar numbers on
-\verb|stdout| (normally screen) with \keyindex{nobarmessage}. In the same way,
-you can suppress the messages abour new lines (new systems) with
-\keyindex{nolinemessages}.
- %\check
+ Situations may arise where the bar lines in different instruments are not
+aligned with one another.  To set this up, first say \verb|\sepbarrules|.
+Then use a combination of the following five commands:
 
- \subsection{Full and instrument divided bars}
-Normally, bars (as well as double bars, final bars and repeat bars) are
-drawn as a continuous line, starting for the bottom of the lower staff of the
-lower instrument, and ending at the top of the upper staff of the upper
-instrument. However, one may want to have discontinuous bars, that is, one
-continuous bar for all the staffs of a unique instrument. This is done by
-issuing the command \keyindex{sepbarrules}. An example of this is given in the
-{\tt ANGESCAO} (or {\tt ANGESCAM}) example; it has also been used in the
-example of section \ref{avemaria}.
-
- The initial situation can be forced or restored by \keyindex{stdbarrules}. In
-the extension library are some more types of bar rules, mainly for very old
-music, see \ref{otherbars}.
-
- \subsection{Instruments with no coherent bar division}
-
- In some special scores with several instruments, it may happen that distinc
-instruments, not only have different meters (e.g. 2/4 and 6/8 to avoid
-printing triolet codes for some instrument), but also have bar lines not
-synchronized. Obviously, this can be implemented \ital{{\bfseries only if}}
-\keyindex{sepbarrules} has been stated. Then, five specific commands can be issued~:
-
-\begin{itemize}
-\item\keyindex{hidebarrule} $n$ hides the bar rule for instrument $n$, until
-this is changed by \verb|\showbarrule|~$n$.
-\item\keyindex{showbarrule} $n$ stops hiding the bar rule for instrument $n$, until
-this is changed by \verb|\hidebarrule|~$n$.
-\item\keyindex{Hidebarrule} $n$ hides the bar rule for instrument $n$, only
+\begin{itemize}\setlength{\itemsep}{0ex}
+\item\keyindex{hidebarrule}\onen~hides the bar rule for instrument $n$, until
+this is changed by \verb|\showbarrule|\onen.
+\item\keyindex{showbarrule}\onen~stops hiding the bar rule for instrument $n$,
+until this is changed by \verb|\hidebarrule|\onen.
+\item\keyindex{Hidebarrule}\onen~hides the bar rule for instrument $n$, only
 for the next bar.
-\item\keyindex{Showbarrule} $n$ exceptionally shows the bar rule for instrument $n$,
-and then resets intrument $n$ to \verb|Hidebarrule|.
+\item\keyindex{Showbarrule}\onen~shows the bar rule for instrument
+$n$ once only,
+and then resets it \verb|Hidebarrule|.
+%
+% DAS ???
+%  and then resets it to \verb|hidebarrule|.
+%
 \item\keyindex{showallbarrules} resets all defined instruments to
-\verb|showbarrule|~$n$. This command is automatically inserted with double
+\verb|\showbarrule|\onen. This command is automatically inserted with double
 bars, final bars and repeats.
 \end{itemize}
 
-Thus, the following example~:
+Thus, this example
 
 \begin{music}
 \instrumentnumber3
@@ -3324,7 +3844,7 @@ Thus, the following example~:
 \endextract
 \end{music}
 
-\noindent was obtained with the following coding
+\noindent was obtained with the following coding:
 \begin{quote}\begin{verbatim}
 \instrumentnumber3
 \setmeter3{{\meterfrac{3}{4}}}
@@ -3360,301 +3880,860 @@ Thus, the following example~:
 \Hidebarrule2\bar
 \NOtes\multnoteskip{.333}\Tqbu fff&\qa f&\qa f\en
 \setrightrepeat
-\endextract
+\zendextract
 \end{verbatim}\end{quote}
 
+\subsection{Dotted, dashed, and more general asynchronous and discontinuous bar lines}\label{musixdbr}
 
-\section{Managing the layout of your score}
-\subsection{Line and page breaking}\label{linebreak}
+The extension
+package \href{http://icking-music-archive.org/software/musixtex/add-ons/musixdbr.tex}
+{\underline{\ttxem{musixdbr.tex}}} by Rainer {\sc Dunker} provides commands for
+dashed, dotted, and arbitrarily discontinuous bar lines. It supports
+individual bar line settings for each instrument, multi-staff instruments,
+different sizes of staves, and even different numbers of lines per staff,
 
-Those who usually worked with \musictex\ before must be aware that this has
-been deeply changed in \musixtex. All line-breaking decisions\footnote{With
-exception of the \musictex\ command {\Bslash autolines}, which is provided in
-the file {\tt musixcpt.tex}, see page \pageref{compatibility}.} are done by
-the external program \verb|musixflx|. Then you get the most even results when
-you insert the fewest \ital{manual} line breaks possible. But sometimes
-there is really need for them, e.g. page break should preferably occur when
-the musician has one hand free to turn the sheet.
+To use the package, you must \verb|\input musixdbr| after \verb|musixtex|, and
+execute the macro \keyindex{indivbarrules} which activates individual bar line
+processing. Then the following commands are available:
 
-You can force a line break with \keyindex{alaligne} instead of \keyindex{bar}.
-In the same way, you can code \keyindex{alapage} to force an \keyindex{eject}
-with proper reinitialization of staffs, clefs and signatures.
+\begin{itemize}\setlength{\itemsep}{0ex}
 
- %\check
+\item  \keyindex{sepbarrule}\onen~separates bar lines of instrument $n$ from those of instrument $n-1$
 
- On the other hand, you may want to forbid line-breaking at a bar,
-then you should replace \verb|\bar| with \keyindex{xbar}.
-
- Conversely, you may want to break a line \ital{not at a bar}\footnote{For
-example, you may prefer to turn the page at a place where the pianist has one
-hand free, in the middle of a bar.}. This is allowed by \keyindex{zbar}
-(optional line break) or forced by \keyindex{zalaligne} or
-\keyindex{zalapage}.
-
-The heavy final double bar of a piece is provided by \keyindex{Endpiece} or
-\keyindex{Stoppiece}. If you just want to terminate the text with a simple
-bar, you say \keyindex{stoppiece} or \keyindex{endpiece}. If you want to
-terminate it without a bar, you code \keyindex{zstoppiece}.
-
- Once you have stopped the score by any of these means, you can restart it
-using \keyindex{contpiece}. If you want to restart indenting the next line
-(system) by the dimension \keyindex{parindent}, then you should rather use
-\keyindex{Contpiece}, which is recommended when changing the
-the number of instruments within a single piece.
-
- However, neither \verb|\contpiece| nor \verb|\Contpiece| can be used if you
-change the signature (i.e. using \keyindex{generalsignature}) between
-\verb|stoppiece| and \verb|\contpiece|), since the space used by signatures is
-not constant and it has to be taken in account, e.g. by some
-\keyindex{changecontext}. In that case, you have to restart your score using
-\keyindex{startpiece}, which in turn requires you to save \verb|\barno| to its
-furtner starting value \verb|\startbarno| if you do not want it reset at 1,
-and to manage the instrument names and/or the \verb|\parindent| if necessary.
-
- If you want the next vertical bar to be a double bar, you have to
-declare \keyindex{doublebar} or \keyindex{setdoublebar} before the
-\keyindex{bar} (or the \keyindex{stoppiece} or \keyindex{alaligne} or
-\keyindex{alapage}) to be marked with a double thin bar. In the same way you
-can declare \keyindex{setdoubleBAR} if you want to have a heavy double bar
-(the same as \verb|\Stoppiece|) and even \keyindex{setemptybar} to make the
-next \verb|\bar| invisible\footnote{These latter features are given for your
-information, but they should be used only in case of emergency.}.
+\item \keyindex{condashbarrule}\onen~connects bar lines of instrument $n$ to those of instrument $n-1$
+   with a dashed line
 
- %\check
+\item \keyindex{condotbarrule}\onen~connects bar lines of instrument $n$ to those of instrument $n-1$
+   with a dotted line
+
+\item \keyindex{conbarrule}\onen~connects bar lines of instrument $n$ to those of instrument $n-1$
+
+\item \keyindex{hidebarrule}\onen~hides bar lines of instrument $n$
+
+\item \keyindex{showdashbarrule}\onen~dashes bar lines of instrument $n$
+
+\item \keyindex{showdotbarrule}\onen~dots bar lines of instrument $n$
+
+\item \keyindex{showbarrule}\onen~shows bar lines of instrument $n$
+
+\item \keyindex{sepmultibarrule}\onen~separates bar lines within multistaff instrument $n$
+
+\item \keyindex{condashmultibarrule}\onen~dashes bar lines between staves of multistaff instrument $n$
+
+\item \keyindex{condotmultibarrule}\onen~dots bar lines between staves of multistaff instrument $n$
+
+\item \keyindex{conmultibarrule}\onen~ shows bar lines between staves of multistaff instrument $n$
+
+\item \keyindex{allbarrules}[\ital{any of the above commands, without numerical parameter}] sets bar
+line style for all instruments together.
+
+\end{itemize}
+
+Dashing and dotting style may be changed by redefining the macros
+\verb|\barlinedash| or \verb|\barlinedots| respectively (see original definitions in \verb|musixdbr.tex|).
+
+Here is an example of the use of these macros:
+
+\begin{music}
+\input musixdbr
+
+\instrumentnumber4 \setstaffs23 \setstaffs32 \setlines14\setsize2\tinyvalue
+\indivbarrules
+\parindent0pt\startextract
+%\startpiece
+%\scale{2}
+  % normal barlines
+  \bar
+  % separate instrument 2 from 1
+  \sepbarrule2
+  \notes\en\bar
+  % barlines on staves
+  \allbarrules\sepbarrule
+  \allbarrules\sepmultibarrule
+  \allbarrules\showbarrule
+  \NOTes\en\bar
+  % barlines between staves
+  \allbarrules\conbarrule
+  \allbarrules\conmultibarrule
+  \allbarrules\hidebarrule
+  \NOTes\en\bar
+  % dashed barlines on staves
+  \allbarrules\sepbarrule
+  \allbarrules\sepmultibarrule
+  \allbarrules\showdashbarrule
+  \NOTes\en\bar
+  % dashed barlines between staves
+  \allbarrules\condashbarrule
+  \allbarrules\condashmultibarrule
+  \allbarrules\hidebarrule
+  \NOTes\en\bar
+  % dotted barlines on staves
+  \allbarrules\sepbarrule
+  \allbarrules\sepmultibarrule
+  \allbarrules\showdotbarrule
+  \NOTes\en\bar
+  % dotted barlines between staves
+  \allbarrules\condotbarrule
+  \allbarrules\condotmultibarrule
+  \allbarrules\hidebarrule
+  \NOTes\en\bar
+  % a wild mixture of all
+  \showdotbarrule1\hidebarrule2\showdashbarrule3\showbarrule4%
+  \condashbarrule2\conbarrule3\condotbarrule4%
+  \condashmultibarrule2\sepmultibarrule3%
+  \NOTes\en\bar
+  % conventional ending
+  \allbarrules\showbarrule
+  \allbarrules\conbarrule
+  \allbarrules\conmultibarrule
+  \NOTes\en\setdoubleBAR\endextract
+\end{music}
+
+This is the code:
 
-\subsection{How to manage individual page layout}
-\begin{enumerate}
- \item You write your own output routine, which centers the contents in the
-middle of the page. Most important are then the values of
-\keyindex{stafftopmarg} and \keyindex{staffbotmarg}, because they decide of
-the amount of margin between successive systems.
- \item If you say \keyindex{raggedbottom}, the vertical glue is removed and
-the score is rather compacted at the top of page.
- \item You change the value of \keyindex{parskip} and say
-\keyindex{normalbottom} (which behaves like \LaTeX's \keyindex{flushbottom}
-and which is done by default working with \verb|plain.tex|). Then the
-vertical space between the staffs is changed to get the first staff on page
-on top and the last staff on page to bottom (depends on \keyindex{vsize}).
-It might be clever to insert a \keyindex{eject} before the \keyindex{bye}.
-\keyindex{musicparskip} set between two systems no extra distance, but the
-possibility to increase the distance up to \verb|5\Interligne|.
-\end{enumerate}
-\noindent
-Besides, following values of e.g.~paper size are changed
-(only if you \ital{do not} work with \LaTeX) to:
 \begin{quote}\begin{verbatim}
-\parindent= 0pt
-\hoffset= -15.4mm
-\voffset= -10mm
-\hsize= 190mm
-\vsize= 260mm
+\input musixdbr
+\instrumentnumber4\setstaffs23\setstaffs32\setlines14\setsize2\tinyvalue
+\indivbarrules\parindent0pt\startextract
+  % normal barlines
+  \bar
+  % separate instrument 2 from 1
+  \sepbarrule2
+  \notes\en\bar
+  % barlines on staves
+  \allbarrules\sepbarrule
+  \allbarrules\sepmultibarrule
+  \allbarrules\showbarrule
+  \NOTes\en\bar
+  % barlines between staves
+  \allbarrules\conbarrule
+  \allbarrules\conmultibarrule
+  \allbarrules\hidebarrule
+  \NOTes\en\bar
+  % dashed barlines on staves
+  \allbarrules\sepbarrule
+  \allbarrules\sepmultibarrule
+  \allbarrules\showdashbarrule
+  \NOTes\en\bar
+  % dashed barlines between staves
+  \allbarrules\condashbarrule
+  \allbarrules\condashmultibarrule
+  \allbarrules\hidebarrule
+  \NOTes\en\bar
+  % dotted barlines on staves
+  \allbarrules\sepbarrule
+  \allbarrules\sepmultibarrule
+  \allbarrules\showdotbarrule
+  \NOTes\en\bar
+  % dotted barlines between staves
+  \allbarrules\condotbarrule
+  \allbarrules\condotmultibarrule
+  \allbarrules\hidebarrule
+  \NOTes\en\bar
+  % a wild mixture of all
+  \showdotbarrule1\hidebarrule2\showdashbarrule3\showbarrule4%
+  \condashbarrule2\conbarrule3\condotbarrule4%
+  \condashmultibarrule2\sepmultibarrule3%
+  \NOTes\en\bar
+  % conventional ending
+  \allbarrules\showbarrule
+  \allbarrules\conbarrule
+  \allbarrules\conmultibarrule
+  \NOTes\en\setdoubleBAR\zendextract
+\end{verbatim}\end{quote}
+
+\section{Bar numbering}
+The current bar number is stored in a count register call \keyindex{barno}.
+When \verb|\startpiece| is encountered, \verb|\barno| is set equal to
+another count register called \verb|\startbarno|, whose default value is one.
+Therefore, if you want the first bar to have a number $n$ different from 1, you
+may either say \verb|\startbarno=|$n$ before \verb|\startpiece|, or say
+\verb|\barno=|$n$ afterwards, but before the first bar line. You may also alter the bar
+number at any time, either by explicitly resetting \verb|\barno|, or by
+incrementing it with a command like \verb|\advance\barno-1|.
+
+\musixtex\ supports two distinct modes for printing bar numbers. In \ital{periodic}
+bar numbering, the bar number is
+placed above the top staff with a user-selectable frequency. In
+\ital{system} bar numbering, the
+number will appear at the beginning of each system.
+
+\subsection{Periodic bar numbering}
+In a normal piece, periodic bar number printing is turned on by default, with a frequency
+of one. In an extract, the default is to not print bar numbers.
+To turn off bar numbering say \keyindex{nobarnumbers}. To reinstate periodic
+bar numbering, or to initiate it in an extract, say \keyindex{barnumbers}.
+To change to a
+different frequency $n$, say \verb|\def|\keyindex{freqbarno}\verb|{|$n$\verb|}|.
+
+The appearance and positioning of the bar number is controlled by the
+token \keyindex{writethebarno}, which by default is defined as\\
+\verb|\def\writethebarno{\fontbarno\the\barno\kernm\qn@width}|
+where the font is defined as \verb|\def\fontbarno{\it}|. You can change
+either of these as desired, for example
+
+  \medskip
+\begin{music}\barnumbers
+\parindent0pt\startpiece
+\Notes\Dqbu gh\Dqbl jh\en
+\notes\Dqbbu fg\Dqbbl hk\en\bar
+\Notes\Tqbu ghi\Tqbl mmj\en
+\def\fontbarno{\bf}%
+\notes\Tqbbu fgj\Tqbbl njh\en\bar
+\Notes\Qqbu ghjh\Qqbl jifh\en\bar
+\notes\Qqbbu fgge\Qqbbl jhgi\en\endpiece
+\end{music}
+\noindent which was coded as
+\begin{quote}\begin{verbatim}\barnumbers
+\Notes\Dqbu gh\Dqbl jh\en
+\notes\Dqbbu fg\Dqbbl hk\en\bar
+\Notes\Tqbu ghi\Tqbl mmj\en
+\def\fontbarno{\bf}%
+\notes\Tqbbu fgj\Tqbbl njh\en\bar
+\Notes\Qqbu ghjh\Qqbl jifh\en\bar
+\notes\Qqbbu fgge\Qqbbl jhgi\en
 \end{verbatim}\end{quote}
+
+\subsection{System bar numbering}
+To have a bar number printed just above the beginning of each system, use
+\keyindex{systemnumbers}. The distance above the staff is controlled
+by \verb|\raisebarno|, which by default is \verb|4\internote| (to fit
+above a treble clef). This can be redefined with the command\\
+\verb|\def|\keyindex{raisebarno}\verb|{|\ital{any \TeX~dimension}\verb|}|.
+The horizontal position similarly is defined by \keyindex{shiftbarno}
+which by default is \verb|0pt|.
+
+The number normally is enclosed in a
+box. If you don't like that, you may redefine the macro \verb|\writebarno|
+which by default is defined as\\
+\verb|\def|\keyindex{writebarno}\verb|{\boxit{\eightbf\the\barno\barnoadd}}|.\\
+This uses the utility \musixtex\ macro \keyindex{boxit} which will enclose
+any text string in a box.
+
+Here are some possible alternate formats for system bar numbers:
+
+\medskip
+\begin{music}\nostartrule
+\def\fontbarno{\it}%
+\let\extractline\hbox
+\startbarno=36
+\hbox to \hsize{%
+\hss
+  \raise20pt\hbox{(a) }%
+  \systemnumbers\startextract
+    \Notes\wh g\en
+  \zendextract
+\hss
+  \def\writebarno{\tenrm\the\barno\barnoadd}%
+  \def\raisebarno{2\internote}%
+  \def\shiftbarno{2.5\Interligne}%
+  \raise20pt\hbox{(b) }%
+  \systemnumbers\startextract
+    \Notes\wh g\en
+  \zendextract
+\hss
+  \def\writebarno{\llap{\tenbf\the\barno\barnoadd}}%
+  \def\raisebarno{2\internote}%
+  \def\shiftbarno{1.3\Interligne}%
+  \raise20pt\hbox{(c) }%
+  \systemnumbers\startextract
+    \Notes\wh g\en
+  \zendextract
+\hss}
+\end{music}
+\noindent This was coded as
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item[(a)] (default)
+ \item[(b)]
+  \begin{verbatim}
+\def\writebarno{\tenrm\the\barno\barnoadd}%
+\def\raisebarno{2\internote}%
+\def\shiftbarno{2.5\Interligne}%
+  \end{verbatim}
+ \item[(c)]
+  \begin{verbatim}
+\def\writebarno{\llap{\tenbf\the\barno\barnoadd}}%
+\def\raisebarno{2\internote}%
+\def\shiftbarno{1.3\Interligne}%
+  \end{verbatim}
+\end{itemize}
+
+If the previous line does not stop with a bar rule, then the next
+printed system bar number will immediately be followed by the contents
+of the token \keyindex{writezbarno}, whose
+default setting is the lower case character `\verb|a|'. You might want to
+change this to `\verb|+|', in which case you should say
+\verb|\def\writezbarno{+}|.
+
+%DAS: Who cares ???
+%\noindent Besides, you can suppress the messages of bar numbers on
+%\verb|stdout| (normally screen) with \keyindex{nobarmessage}. In the same way,
+%you can suppress the messages abour new lines (new systems) with
+%\keyindex{nolinemessages}.
+ %\check
+
+\section{Managing the layout of your score}
+\subsection{Line and page breaking}\label{linebreak}
+If every bar ends with \verb|\bar| and no other line- or page-breaking commands
+are used, then the external program \verb|musixflx| will decide where to insert
+line and page breaks. Line breaks will only come at bar lines. The total
+number of lines will depend on the initial value of \verb|\elemskip|, which by
+default is 6 pt in \verb|\normalmusicsize|.
+
+You can force a line or page break by replacing \keyindex{bar} with
+\keyindex{alaligne} or \keyindex{alapage} respectively. On the other hand,
+to forbid line-breaking at a particular bar, replace \verb|\bar|
+with \keyindex{xbar}. To force a line or page break where there is
+no bar line, use \keyindex{zalaligne} or \keyindex{zalapage}. To mark any
+mid-bar location as an optional line-breaking point, use \keyindex{zbar}.
+
+The heavy final double bar of a piece is one of the consequences of
+\keyindex{Endpiece} or \keyindex{Stoppiece}. If you just want to terminate
+the text with a simple bar, say \keyindex{stoppiece} or \keyindex{endpiece}.
+To terminate it with no bar line at all, code \keyindex{zstoppiece}.
+
+Once you have stopped the score by any of these means, you may want to restart
+it, and there are several ways to do so. If you don't need to change the key
+signature, meter, or clef,
+you can use \keyindex{contpiece} for no indentation, or \keyindex{Contpiece}
+to indent by \keyindex{parindent}. If you do want to change some score
+attribute that takes up space, for example
+with \keyindex{generalsignature} after \verb|\stoppiece|, then to restart you
+must use \keyindex{startpiece}. However, if you don't want \verb|\barno| reset
+to 1, you must save its new starting value to \verb|\startbarno|. You may also
+wish to modify instrument names or \verb|\parindent| before restarting.
+
+Recall that thin-thin or thin-thick double bars or blank bar lines can be
+inserted without stopping by using the commands described in section
+\ref{doublebars}. Those commands can also be used before \verb|\stoppiece|,
+\verb|\alaligne|, or \verb|\alapage|
+
+\subsection{Page layout}
+Blank space above and below each staff is controlled by the dimension
+registers \keyindex{stafftopmarg} and \keyindex{staffbotmarg}. For more
+info see section \ref{LayoutParameters}.
+
+The macro \keyindex{raggedbottom} will remove all vertical glue and
+compact everything toward the top of page.
+In contrast, the macro \keyindex{normalbottom} will restore default
+behavior, in which vertical space between the systems is distributed
+so that the first staff
+on the page is all the way at the top and the last staff all the way at
+the bottom.
+
+The macro \keyindex{musicparskip} will allow the existing space between
+systems to increase by up to \verb|5\Interligne|.
+
+The following values of page layout parameters will allow the maximum material
+to fit on each page, provided the printer allows the margins that are implied.
+
+\begin{center}
+\begin{tabular}{|l|l|l|}\hline
+\multicolumn{1}{|c|}{A4}&\multicolumn{1}{|c|}{letter}&\multicolumn{1}{|c|}{A4 or letter}\\\hline
+\multicolumn{3}{|c|}{\tt\Bslash parindent= 0pt}\\\hline
+\multicolumn{3}{|c|}{\tt\Bslash hoffset= -15.4mm}\\\hline
+\multicolumn{3}{|c|}{\tt\Bslash voffset= -10mm}\\\hline
+\verb+\hsize= 190mm+&\verb+\hsize= 196mm+&\verb+\hsize= 190mm+\\\hline
+\verb+\vsize= 260mm+&\verb+\vsize= 247mm+&\verb+\vsize= 247mm+\\\hline
+\end{tabular}
+\end{center}
+%avre
 \zkeyindex{parindent}\zkeyindex{hoffset}\zkeyindex{voffset}
 \zkeyindex{hsize}\zkeyindex{vsize}
 
- %\check
 
-\subsection{How to adjust the global line and page layout}\index{page and line
-layout (global)}
+\subsection{Page numbering, headers and footers}\index{page
+number}\index{footnote}
 
- Once you have made your whole score, you will probably find out that all
-systems (all ``lines'') have a correct layout with nice beams, nice slurs, and
-others. But it is likely that:
- \begin{itemize}
- \item The result takes too many or too few pages and you estimate a more or
-less compact score would be suitable.
- \item The results takes a convenient number of pages, but the last page
-exhibits a widow line or an ugly blank space at the end.
- \end{itemize}
+There are no special page numbering facilities in \musixtex; you must rely on
+macros from plain \TeX. There is a count register in \TeX\ called
+\verb|\pageno|. It is always initialized to \verb|1| and incremented by one
+at every page break. By saying \keyindex{pageno}$=n$, it can be reset to any
+value at any time, and will continue to be incremented from the new value.
 
- To solve this, you may revert to two strategies:
- \begin{enumerate}
-  \item Explicitely force line and page breaking at the very places you like;
-  this can be done using \verb|\alaligne|, \verb|\alapage|, \verb|\zalaligne|
-or \verb|\zalapage| commands. This can also be done using the
-\verb|\autolines| command imported from \musictex\ and provided in the {\tt
-musixcpt.tex} additional file. But this way of doing may result in
-unfortunately uneven distribution of the notes in the score, which is therefore
-not very smart.
-  \item Adapt both the \keyindex{mulooseness} and the global value of
-\keyindex{elemskip}: increasing \verb|\mulooseness| (whose default is 0)
-increases the total number of systems, and if you are clever you may be able
-to fill an integer number of pages. Besides, increasing the stated
-\verb|\elemskip| (use \verb|\showthe\elemskip| to find its default value) also
-makes note spacing wider, and its advantage is that you can tune it by half a
-percent if needed.
-
-\begin{remark} \verb|\elemskip| can be retrieved in both the first and the third
-pass (second \TeX-ing pass), but any assignment of a value (a dimension value)
-to \verb|\elemskip| will be of no effect at third pass, since it is taken from
-the {\tt *.mx2} file yielded by {\tt musixflx}. On the contrary, assigning a
-value to \keyindex{noteskip} within \verb|\notes...\enotes| is efficient in
-both passes, and cause some weird errors if you mix up scalable and not
-scalable dimensions.
- \end{remark}
- \end{enumerate}
- %\check
+By default, \TeX\ will place a page number on
+every page, centered at the bottom. Unfortunately, this is not the preferred
+location according to any standard practice. To suppress this default
+behavior, say \keyindex{nopagenumbers}.
 
-\section{Changing score attributes}
+One way to initiate page numbering in a more acceptable location is to take
+advantage of the facts that (a) \TeX\ prints the contents of the control sequences
+\keyindex{headline} and \keyindex{footline} at the top and bottom
+respectively of every page, and (b) the value of \verb|\pageno| can be printed by
+saying \keyindex{folio}. Therefore, for example, the following sequence of
+commands, issued anywhere before the end of the first page, will cause page
+numbers and any desired text to be printed at the top of every page,
+alternating between placement of the number at the left and right margins, and
+alternating between the two different text strings (the capitalized text in
+the example):
 
- As seen before, you can change the signature of the whole set of instruments
-by \keyindex{generalsignature}~$n$ where $n>0$ means a number of sharps, $n<0$
-means a number of flats. Or, you may prefer to change the signature of only
-one or two instruments by the statement:
+\begin{quote}\begin{verbatim}
+\nopagenumbers
+\headline={\ifodd\pageno\rightheadline\else\leftheadline\fi}%
+\def\rightheadline{\tenrm\hfil RIGHT RUNNING HEAD\hfil\folio}%
+\def\leftheadline{\tenrm\folio\hfil LEFT RUNNING HEAD\hfil}%
+\voffset=2\baselineskip
+\end{verbatim}\end{quote}
 
-\keyindex{setsign} $n$\verb|{|$s$\verb|}|
+\subsection{Controlling the total number of systems and pages}\index{page and line
+layout (global)}
 
+Once all the notes are entered into a \musixtex\ score, it would be convenient
+if there were a simple sequence of commands to
+cause a specified number of systems to be uniformly distributed over a
+specified number of pages. Unfortunately that's not directly
+possible\footnote{It \textit{is} possible in \textbf{PMX}.}.
+Rather, some trial and error will usually be required to achieve the desired final
+layout. To this end, some combination of the following strategies may be used:
+
+ \begin{enumerate}\setlength{\itemsep}{0ex}
+  \item Assign a value to the count register \keyindex{linegoal} representing
+the total number of systems. The count register \keyindex{mulooseness} must be 0 if using
+\verb|\linegoal|.
+  \item Explicitly force line and page breaking as desired, using
+the macros \verb|\alaligne|, \verb|\alapage|, \verb|\zalaligne|
+or \verb|\zalapage|.
+  \item Adjust both \keyindex{mulooseness} and the initial value of
+\keyindex{elemskip}: increasing \verb|\mulooseness| from its default of 0 will
+increase the total number of systems, while changing the initial value of
+\verb|\elemskip| (use \verb|\showthe\elemskip| to find its default value) may change the
+total number of systems accordingly.
+ \end{enumerate}
  %\check
 
-\noindent
- where $n$ is the number of the instrument considered, and $s$ its
-specific signature. Since you may change simultaneously (with respect to the
-score) but consecutively (with respect to your code) the signatures of
-several instruments, this change takes place only when you say
-\keyindex{changesignature} (within a bar) or \keyindex{changecontext} (after
-a single vertical rule) or \keyindex{Changecontext} (after a double vertical
-rule) or \keyindex{zchangecontext} (without a bar rule\footnote{Old composers
-uses the bar rules very rarely}).
+\section{Changing clefs, key signatures, and meters}
+
+\subsection{Introduction}\label{contextintro}
+
+To define clefs, key signatures, or meters at the start of a piece,
+or to change one or more of these attributes\footnote{In this section,
+\ital{attribute} will refer to any clef, key signature, or meter.}~anywhere
+else in a score,
+\musixtex\ requires two steps. The first step is to \ital{set} the new values of
+the attributes.
+Most of the commands for this have the form \verb|\set|...~. They will be
+described in the following subsections.
+
+But this alone will
+not cause anything to be changed or printed. The second step is to activate the
+change. This is done by issuing one of the
+following commands (outside \verb|\notes|$\dots$\verb|\en|):
+\verb|\startpiece|, \verb|\startextract|, \verb|\contpiece|,
+\verb|\Contpiece|,
+\verb|\alaligne|, \verb|\alapage|, \verb|\zalaligne|, \verb|\zalapage|,
+\verb|\changecontext|,
+\verb|\Changecontext|, \verb|\zchangecontext|, \verb|\changesignature|,
+\verb|\changeclefs|, or \verb|\zchangeclefs|. Most of these perform
+other functions as well, and some may be used even when no attributes
+change. Features unrelated to changing attributes are detailed elsewhere.
+The first 11 will activate all pending new attributes.
+If more than one type is activated by a single command in this manner,
+then regardless of the order
+they were set, they will always appear in the following order: clef, key signature,
+meter.
+The last three commands in the above list obviously activate only
+the specific type of attribute referred to in the name of the command.
+
+The macros \verb|\changecontext|, \verb|\Changecontext|, \verb|\zchangecontext|
+will respectively insert a single, double, or invisible bar
+line before printing the attributes.
+
+\subsection{Key Signatures}
+
+We've already seen in section \ref{whatspecify} how to set key
+signatures for all instruments with \keyindex{generalsignature}, or for
+specific instruments with \keyindex{setsign}. As just noted, these commands only
+prepare for the insertion of the signatures into the score; it is
+really \verb|\startpiece| that puts them in place at the beginning of the
+score.
+
+The commands \verb|\generalsignature| and \verb|\setsign| also serve to set
+new key signature(s) anywhere in score. The change can then be activated with one of
+the 11 general commands listed above, or with \keyindex{changesignature} if
+in the middle of a bar.
+While neither \verb|\changesignature| nor \verb|\zchangecontext| prints a bar
+line, the differences are that the latter increments the bar number counter and
+inserts a horizontal space of \verb|\afterruleskip| after the new signature(s).
+All of these options will repost signatures that have not been changed.
+
+Normally, changing a signature from flats to sharps or vice-versa, or
+reducing the number of sharps or flats, will produce the appropriate set of
+naturals to indicate what has been suppressed. This standard feature can be
+temporarily inhibited by the command \keyindex{ignorenats} issued right before
+the change-activating command.
+
+Here is an example showing various possibilities for changing key signatures.
+Note the comments between the code lines.
 
- Normally, changing a signature from flats to sharps or sharps to flats or
-reducing the number of sharps/flats will produce the convenient set of
-naturals to emphasise what is suppressed. This standard feature can be
-temporarily inhibited by the command \keyindex{ignorenats} to be issued before
-the next {\Bslash changecontext} or {\Bslash changesignature}.
+\begin{quote}\begin{verbatim}
+\instrumentnumber2\setstaffs22%
+\setclef1{\bass}\generalsignature2%
+\startextract
+\Notes\qu K&\qu d|\qu e\en
+% Signature change in a single instrument with two staves.
+% Naturals appear by default, indicating cancelled sharps.
+\setsign20\changesignature
+\Notes\qu J&\qu d|\qu e\en
+% When changing signature in the middle of a bar and no naturals
+% are posted, the new signature can be confused with a simple accidental.
+\setsign11\ignorenats\changesignature
+\Notes\qu M&\qu d|\qu e\en
+% New signatures after a double bar line
+\generalsignature{-2}\Changecontext%
+\Notes\qu K&\qu d|\qu e\en%
+\Notes\qu K&\qu d|\qu e\en%
+% New signatures after an invisible bar line. Note the
+% difference in spacing compared with beat 3 of the prior measure
+\generalsignature{1}\zchangecontext%
+\Notes\qu K&\qu d|\qu e\en%
+\end{verbatim}\end{quote}
 
+\begin{music}
+\instrumentnumber2\setstaffs22%
+\setclef1{\bass}\generalsignature2%
+\startextract
+\Notes\qu K&\qu d|\qu e\en
+% Signature changing in a single instrument with 2 staves
+% Naturals are allowed to shown there are no more sharps
+\setsign20\changesignature
+\Notes\qu J&\qu d|\qu e\en
+% Signature changing in a single staff without naturals
+% if there is no bar line, the signatures are confusing:
+% it is not clear if they are for a single note or not
+\setsign11\ignorenats\changesignature
+\Notes\qu M&\qu d|\qu e\en
+% New signatures after a double bar line
+\generalsignature{-2}\Changecontext%
+\Notes\qu K&\qu d|\qu e\en%
+\Notes\qu K&\qu d|\qu e\en%
+% New signatures after an invisible bar line
+% see the difference in space comparing beat 2
+\generalsignature{1}\zchangecontext%
+\Notes\qu K&\qu d|\qu e\en%
+\endextract
+\end{music}
 
- In the same way, you may want to change the active clefs.
-This is done by
 
-\keyindex{setclef}\verb|{|$n$\verb|}{|$s_1s_2s_3s_4$\verb|}%|
+\subsection{Clefs}\label{treblelowoct}
+
+Macros that define clefs have already been discussed in section
+\ref{whatspecify}. By way of review, here are all of the possible clefs
+(applied to the lowest staff):
+%avrb
+\newcommand{\musicintextsign}[1]{\musicintext#1{\notes\en}}
+
+\begin{center}\vskip-1ex\footnotesize%\small
+\begin{tabular}{||c|c|c|c|c||}\hline\hline
+&&&&\\
+\verb+\setclef1\treble+&&&\verb+\setclef1\alto+&\\
+\verb+\setclef10+&\verb+\setclef11+&\verb+\setclef12+
+&\verb+\setclef13+&\verb+\setclef14+\\[-2ex]%\hline
+\musicintextsign{\treble}&\musicintextsign1&\musicintextsign2
+&\musicintextsign{\alto}&\musicintextsign4\\[3ex]\hline
+%\end{tabular}
+&&&&\\
+%\begin{tabular}{ccccc}
+&\verb+\setclef1\bass+&&\verb+\setclefsymbol1\empty+\footnotemark&\\
+\verb+\setclef15+&\verb+\setclef16+&\verb+\setclef17+
+&\verb+\setclef18+&\verb+\setclef19+\\[-2ex]%\hline
+\musicintextsign5&\musicintextsign{\bass}&\musicintextsign7
+&\musicintextsign8&\musicintextsign9\\[3ex]\hline\hline
+%This one uses \setclefsymbol1\empty :
+%&\musicintextnoclef{\notes\qu h\en}&\musicintextsign9\\[3ex]\hline\hline
+\end{tabular}
+\footnotetext{Details of the macro {\tt\Bslash setclefsymbol} will be discussed later}
+\end{center}
+%avre
+
+Just as with key signatures, these commands only \ital{prepare} for clef changes.
+To \ital{activate} them, any of the first 11 commands listed in section
+\ref{contextintro} could be used. However, one should keep in mind that
+according to modern conventions, a clef change at a bar line is posted
+before the bar line, while for example \verb|\changecontext| would post it
+after the bar line. In part for this reason, we have the special command
+\keyindex{changeclefs}. It can be used anywhere outside
+\verb+\notes...\enotes+ to activate a clef change and insert an amount of
+horizontal space to accommodate the new clef symbol(s), without printing a
+bar line. Sometimes no added
+space is required, in which case \keyindex{zchangeclefs} should be used.
+
+Here are some examples of clef changes:
 
- %\check
+\begin{quote}\begin{verbatim}
+\instrumentnumber2\setstaffs22%
+\setclef1{\bass}\generalsignature2%
+\startextract
+% Change in one staff only, with added space
+\setclef1\treble\changeclefs%
+\Notes\qu k&\qu e|\cu{.d}\ccu{e}\en%
+% Combined with signature change, also no extra space needed
+% twice the same clef in staff 2 - with the help of a blank clef
+\setclef28\zchangeclefs\setclef2\treble%
+\setclef1\bass\zchangeclefs\setsign1{-2}\setsign2{-2}%
+\ignorenats\changesignature%
+\Notes\qu K&\cu{de}|\qu e\en%
+% clef change before barline
+\setclef1\treble\zchangeclefs\bar%
+\Notes\qu k&\cu{de}|\qu e\en%
+% clef change after barline
+\setclef1\bass\bar\changeclefs%
+\Notes\qu K&\cu{de}|\qu e\en%
+% clef change after barline with changecontext
+\setclef1\treble\changecontext%
+\Notes\cu k&\cu d|\qu e\en%
+% twice the same clef
+\setclef18\zchangeclefs\setclef1\treble\changeclefs%
+\Notes\cu k&\cu e |\en%
+\zendextract
+\end{verbatim}\end{quote}
+\begin{music}
+\instrumentnumber2\setstaffs22%
+\setclef1{\bass}\generalsignature2%
+\startextract
+% Change in one staff only, with added space
+\setclef1\treble\changeclefs%
+\Notes\qu k&\qu e|\cu{.d}\ccu{e}\en%
+% Combined with signature change, also no extra space needed
+% twice the same clef in staff 2 - with the help of a blank clef
+\setclef28\zchangeclefs\setclef2\treble%
+\setclef1\bass\zchangeclefs\setsign1{-2}\setsign2{-2}%
+\ignorenats\changesignature%
+\Notes\qu K&\cu{de}|\qu e\en%
+% clef change before barline
+\setclef1\treble\zchangeclefs\bar%
+\Notes\qu k&\cu{de}|\qu e\en%
+% clef change after barline
+\setclef1\bass\bar\changeclefs%
+\Notes\qu K&\cu{de}|\qu e\en%
+% clef change after barline with changecontext
+\setclef1\treble\changecontext%
+\Notes\cu k&\cu d|\qu e\en%
+% twice the same clef
+\setclef18\zchangeclefs\setclef1\treble\changeclefs%
+\Notes\cu k&\cu e |\en%
+\endextract
+\end{music}
 
-\noindent where $r$ is the number of the instrument, $s_1$ specifies the clef
-of the lower staff, $s_2$ the clef of the second staff, etc. $s_1=6$ means the
-\ital{bass} clef (\ixem{clef de fa} in French), $s_1=0$ means the \ital{violin}
-clef (\ixem{clef de sol} in French), $s_1=1$ through $s_1=4$ mean the
-\ital{alto} clef (\ixem{clef d'ut} in French) set on first (lower) through
-fourth (next to upper line of the staff), $s_1=5$ or $s_1=6$ mean the bass clef
-on the third or fourth line respectively.\index{violin clef}\index{bass
-clef}\index{alto clef}
-
- As seen above in the case of signatures, several clefs may be changed at the
-same time; thus all the clef changes become operational only when the macro
-\keyindex{changeclefs} is coded. Normal usage consists in issuing this
-command before the bar, not after (this helps the music player when the
-change happens across a line break).
- %\check
+\noindent Of course the examples in the last two bars are contrary
+to accepted practice.
+
+Clef changes initiated with the \verb|\setclef| command have several features
+in common. When activated after the beginning of the piece, the printed symbol
+is smaller than the normal one used at the beginning of the piece. Also,
+\musixtex\ automatically adjusts vertical positions of noteheads consistent
+with the new clef.
+
+There is an additional group of macros for setting new clefs which does not share
+either of these features. In other words, they will always print full sized symbols, and they
+won't change the vertical positions of noteheads from what they would have been
+before the new symbol was printed. We could call this process ``clef symbol substitution'',
+because all it does is print a different symbol (or no symbol at all) in place of
+the underlying clef which was set in the normal way.
+
+You'll need to use clef symbol substitution if you want to have a so-called
+\index{octave clefs}\label{octclef}octave treble clef or octave bass
+clef, i.e., one containing a numeral 8 above or
+below the normal symbol. The syntax for setting upper
+octaviation
+is \keyindex{setbassclefsymbol}\onen\keyindex{bassoct}\\
+or \keyindex{settrebleclefsymbol}\onen\keyindex{trebleoct}; for lower octaviation
+it is\\ \keyindex{setbassclefsymbol}\onen\keyindex{basslowoct} or
+\keyindex{settrebleclefsymbol}\onen\keyindex{treblelowoct}. Because these sequences act to
+\ital{replace} normal bass or treble clefs with a different symbol, they
+require that the normal clefs be set first. For example
+
+\noindent\begin{minipage}{80mm}
+\begin{music}\nostartrule
+ \parindent 19mm
+ \instrumentnumber{4}
+ \generalmeter{\empty}
+ \setclef1\bass \setclef2\bass \setclef3\treble \setclef4\treble
+ \setbassclefsymbol1\basslowoct
+ \setbassclefsymbol2\bassoct
+ \settrebleclefsymbol3\treblelowoct
+ \settrebleclefsymbol4\trebleoct
+\startextract
+\Notes\qu{`abcdefghi}&\qu{`abcdefghi}&\qu{abcdefghi}&\qu{abcdefghi}&\enotes
+\zendextract
+\end{music}
+\end{minipage}
+\begin{minipage}{50mm}
+\begin{verbatim}
+\parindent 19mm
+\instrumentnumber{4}
+\generalmeter{\empty}
+\setclef1\bass \setclef2\bass
+\setclef3\treble \setclef4\treble
+\setbassclefsymbol1\basslowoct
+\setbassclefsymbol2\bassoct
+\settrebleclefsymbol3\treblelowoct
+\settrebleclefsymbol4\trebleoct
+\startextract
+\Notes\qu{`abcdefghi}&\qu{`abcdefghi}%
+&\qu{abcdefghi}&\qu{abcdefghi}&\enotes
+\zendextract
+\end{verbatim}
+\end{minipage}
 
- The \verb|\changeclefs| command normally takes some horizontal space to put
-one of more clef symbols, but it may happen that you have no notes
-immediately before on the staff whose clef is changed. In that case, you can
-use \keyindex{zchangeclefs} which performs the same posting, overwritten left on
-the last part of the score in that staff. Of course it is your responsibility
-to ensure that no notes will collide with the clef change symbols.
- %\check
+\index{clefs (empty)}
+Another application of clef symbol substitution is to cause no clef to be
+printed, as for example might be desired in percussion music, This
+can be accomplished with \keyindex{setclefsymbol}\onen\verb|\empty|, which
+once activated would replace \ital{all} clef symbols in the first (lowest)
+staff of instrument $n$ with blanks.
+
+Normal symbols for those clefs that have been substituted can be restored by
+\keyindex{resetclefsymbols}.
 
-The \musictex\ problem if a clef change is coded while one or several beams
-are pending has been removed in \musixtex. As an enhanced example, we provide
-an excerpt of {\sc Brahms}'s Intermezzo op.~117,1 initially coded by Miguel
-{\sc Filgueiras}:\index{Brahms, J.@{\sc Brahms, J.}}\medskip
+The various clef symbol substitution commands can only be used to substitute for
+\texttt{treble}, \texttt{alto}, or \texttt{bass} clefs.
+
+In the following example, (1) is two normal clef changes. At (2) the clef is first changed
+back to treble and then the \verb|\treblelowoct| symbol is substituted by using
+\verb|\settrebleclefsymbol|.
+When changing the clef away from treble and then back as at (3), the substitution
+symbol is still in force. At (4), \verb|\resetclefsymbols| cancels the symbol substitution.
+If using \verb|\setclefsymbol| all available clefs are changed to the same symbol, as you can see
+in the two clefs after (5) in comparison with (2). Obviously the second clef after (5) is
+nonsense; \verb|\resetclefsymbols| puts matters in order at (6) and (7).
 
 \begin{music}
-\setstaffs1{2}
-\interstaff{11}
-\setclef1\bass % F- and G-clefs
-\generalsignature{-3}% 3 flats
-\parindent-4mm
-\advance\hsize8mm
+\instrumentnumber1\setclef1\bass
 \startpiece
-\qspace\nspace
-\Notes\arpeggio E5\ibslurd0o\zq{EI}\qu N%
-  \nextstaff\ibl0e{-2}\zq{eg}\qb0l\zq d\qb0k\enotes
-\setclef1\treble\zchangeclefs
-\nspace
-\Notes\tbu0\zq{ce}\qb0j\nextstaff\zq{sn}\cl l\enotes
-\notes\curve{-4}22\invertslur0\tslur0t\zq{be}\qu i\nextstaff\zq{sn}\ql l\enotes
-\setclef1\bass\changeclefs
-\notes\islurd0k\zq E\cu I\nextstaff
-  \ibbu1h{-3}\zq{ae}\qb1h\tbu1\zq N\qb1g\enotes
-\bar
-\Notes\ibu0L{-2}\zq{EI}\qb0M\zqb0L%
-  \nextstaff{\stemlength4\zql N}\ibu1f{-2}\qb1f\tbu1\zqb1e\hsk\enotes
-\setclef1\treble\changeclefs
-\nspace
-\Notes\tbu0\zq{Me}\qb0g\nextstaff\zq{ln}\cl s\en
-\notes\curve{-4}22\invertslur0\tslur0q\zq{be}\qu i\nextstaff\zq{ln}\ql s\en
-\setclef1\bass\changeclefs
-\notes\islurd0m\zq G\cu L\nextstaff
-  \ibbu1j3\zq c\qb1j\tbu1\zq d\qb1k\enotes
-\bar
-\Notes\zq G\qu L%
-  \nextstaff\ibl0e{-2}\zq{ei}\qb0l\zq d\zqb0k\enotes
-\setclef1\treble\changeclefs
-\nspace
-\Notes\tbu0\zq{ce}\qb0j\nextstaff\zq{sn}\cl l\enotes
-\notes\curve{-5}22\invertslur0\tslur0o\zq{be}\qu i\nextstaff\zq{sn}\ql l\enotes
-\setclef1\bass \changeclefs
-\notes\zq B\cu I\nextstaff\ibsluru0j%
-  \ibbu1h{-3}\zq{ae}\qb1h\tbu1\zq N\qb1g\enotes
-\bar
-\Notes\zq{IL}\ql N\nextstaff\zql b\ibu0i{-2}\qb0i\enotes
-\scale{.5}%
-\Notes\nextstaff\qb0e\enotes
-\Notes\nextstaff\tinynotesize\isluru1f\grcu g\enotes
-\scale\normalvalue
-\Notes\zq B\cu I\nextstaff\zcl a\tslur1f\tbu0\zq d\qb0f\enotes
-\Notesp\zq E\qu I\nextstaff\tslur0e\zq N\zql e\ibu0g6\qbp0e\enotes
-\notes\sk\icresc\cu E\sk\zmidstaff\tcresc\nextstaff
-  \ibsluru0i\nbbu0\qb0g\zq i\zcl g\qb0i\tbu0\qb0n\tubslur0k\enotes
+\notes\zchar{-5}{1}\qu H\en\setclef1\treble\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{2}\qu J\en
+\setclef1\treble\settrebleclefsymbol1\treblelowoct\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{3}\qu I\en\setclef1\treble\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{4}\qu J\en\resetclefsymbols\setclef1\treble\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\doublebar
+\notes\zchar{-5}{5}\qu J\en
+\setclef1\treble\setclefsymbol1\treblelowoct\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{6}\qu I\en\setclef1\treble\changeclefs
+\notes\qu i\en\resetclefsymbols\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{7}\qu J\en\setclef1\treble\changeclefs
+\notes\qu i\en
 \endpiece
 \end{music}
 
+\noindent This is the code:
 
-\noindent The first bar of this excerpt was coded as:
-
- \begin{verbatim}
-\begin{music}
-\instrumentnumber{1}
-\setstaffs1{2}
-\interstaff{11}
-\setclef1\bass % F- and G-clefs
-\generalsignature{-3}% 3 flats
-\parindent0pt
+\begin{quote}\begin{verbatim}
+\begin{music}\nostartrule
+\instrumentnumber1\setclef1\bass
 \startpiece
-\qspace\nspace
-\Notes\arpeggio E5\ibslurd0o\zq{EI}\qu N%
-  \nextstaff\ibl0e{-2}\zq{eg}\qb0l\zq d\qb0k\enotes
-\setclef1\treble\zchangeclefs
-\nspace
-\Notes\tbu0\zq{ce}\qb0j\nextstaff\zq{sn}\cl l\enotes
-\notes\invertslur0\tslur0t\zq{be}\qu i\nextstaff\zq{sn}\ql l\enotes
-\setclef1\bass \changeclefs
-\notes\islurd0k\zq E\cu I\nextstaff
-  \ibbu1h{-3}\zq{ae}\qb1h\tbu1\zq N\qb1g\enotes
-\end{music}\end{verbatim}%
-\ital{Meter} changes are implemented in following way:
+\notes\zchar{-5}{1}\qu H\en\setclef1\treble\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{2}\qu J\en
+\setclef1\treble\settrebleclefsymbol1\treblelowoct\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{3}\qu I\en\setclef1\treble\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{4}\qu J\en\resetclefsymbols\setclef1\treble\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\doublebar
+\notes\zchar{-5}{5}\qu J\en
+\setclef1\treble\setclefsymbol1\treblelowoct\changeclefs
+\notes\qu i\en\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{6}\qu I\en\setclef1\treble\changeclefs
+\notes\qu i\en\resetclefsymbols\setclef1\bass\changeclefs\bar
+\notes\zchar{-5}{7}\qu J\en\setclef1\treble\changeclefs
+\notes\qu i\en
+\endpiece
+\end{verbatim}\end{quote}
 
-\keyindex{setmeter} $n$%
-  \verb|{{|$m1$\verb|}{|$m2$\verb|}{|$m3$\verb|}{|$m4$\verb|}}%|
+\subsection{Meter changes}
 
-\noindent
- where $n$ is the number of the instrument, $m1$ specifies the meter
-of the lower staff, $m2$ the meter of the second staff, etc. (if necessary!).
+As mentioned in section \ref{generalmeter}, a common \itxem{meter} for all
+staves can be specified by \keyindex{generalmeter}\verb|{|$m$\verb|}|,
+where $m$ denotes the meter. On the other hand, meter changes in specific
+staves are implemented with
+\keyindex{setmeter}\onen\verb|{{|$m1$\verb|}{|$m2$\verb|}{|$m3$\verb|}{|$m4$\verb|}}|,
+where $n$ is the number of the instrument, $m1$ specifies the meter
+of the first (lowest) staff, $m2$ the second staff, and so forth. (Only enter
+as many $m$'s as necessary.)
+
+Since meter changes are meaningful only across bars, there is no special command to
+activate a new meter; rather, they are activated with the general commands
+\keyindex{changecontext}, etc., listed in section \ref{contextintro}.
 
-Since meter changes
-are meaningful only across bars, they are actually taken in account with
-\keyindex{changecontext} or \keyindex{Changecontext} or
-\keyindex{zchangecontext} or \keyindex{alaligne} or \keyindex{alapage}.
+The next example shows a few methods to get a meter change, in all staves or
+in a single staff.
+
+\begin{quote}\begin{verbatim}
+\instrumentnumber2\setstaffs22%
+\generalmeter{\meterfrac{4}{4}\meterfrac{2}{4}\meterfrac{1}{4}}%
+\setclef1{\bass}\generalsignature2%
+\startextract
+\setmeter1{{\meterfrac{2}{4}}}%
+\setmeter2{{\lower2pt\hbox{\meterfrac{\Bigtype 2}{}}}%
+{\meterfrac{3}{4}}}\changecontext
+\Notes\qu K&\cu{de}|\qu e\en
+% bar 11
+% Meters, clefs, and key signatures.
+% All 3 clefs after bar (probably bad form) if no changeclefs
+\setmeter1{{\meterfrac{2}{8}}}%
+\setmeter2{{\meterfrac{3}{6}}{\meterfrac{3}{8}}}%
+\setsign2{-1}%
+% How to force showing the bass clef?
+\setclef1\bass\setclef2{23}%
+\Changecontext
+\Notes\qu K&\cu{de}|\qu e\en
+% bar 12
+% Meters, clefs, and key signatures, with clef before the bar.
+% Maybe not best form if signatures are involved
+\setmeter1{{\meterfrac{2}{4}}}%
+\setmeter2{{\meterfrac{3}{8}}{\meterfrac{3}{6}}}%
+\setsign2{-1}%
+\setclef1\treble\zchangeclefs\changecontext
+\Notes\qu k&\cu{de}|\qu e\en
+\end{verbatim}\end{quote}
+\begin{music}
+\instrumentnumber2\setstaffs22%
+\generalmeter{\meterfrac{4}{4}\meterfrac{2}{4}\meterfrac{1}{4}}%
+\setclef1{\bass}\generalsignature2%
+\startextract
+\setmeter1{{\meterfrac{2}{4}}}%
+% How big the '2' must be?
+\setmeter2{{\lower2pt\hbox{\meterfrac{\Bigtype 2}{}}}%
+{\meterfrac{3}{4}}}\changecontext
+\Notes\qu K&\cu{de}|\qu e\en
+% bar 11
+% Meter Clefs and Key Signatures
+% all 3 clefs after bar if no changeclefs
+\setmeter1{{\meterfrac{2}{8}}}%
+\setmeter2{{\meterfrac{3}{6}}{\meterfrac{3}{8}}}%
+\setsign2{-1}%
+% How to force showing the bass clef?
+\setclef1\bass\setclef2{23}%
+\Changecontext
+\Notes\qu K&\cu{de}|\qu e\en
+% bar 12
+% Meter Clefs Keys Signatures all 3 with clef before the bar
+% probably not if signatures are involved
+\setmeter1{{\meterfrac{2}{4}}}%
+\setmeter2{{\meterfrac{3}{8}}{\meterfrac{3}{6}}}%
+\setsign2{-1}%
+\setclef1\treble\zchangeclefs\changecontext
+\Notes\qu k&\cu{de}|\qu e\en
+\endextract
+\end{music}
 
 \section{Repeats}
 
-To insert a \ital{repeat bar} you can use following sets of procedures,
-namely \keyindex{leftrepeat}, \keyindex{rightrepeat} and
-\keyindex{leftrightrepeat}, which are substitute the \keyindex{bar}.
-For example:
+To replace a bar line with a left, right, or left-right repeat, use one of the
+commands \keyindex{leftrepeat}, \keyindex{rightrepeat} or
+\keyindex{leftrightrepeat} in place of \verb|\bar|. If a \verb|\leftrepeat|
+happens to come at the end of a system, it will automatically be moved to the
+start of the next system. If a \verb|\leftrightrepeat| happens to come at the
+end if a system, \musixtex\ will automatically post a right repeat at the end
+of the system and a left repeat at the beginning of the next.
 
-\begin{music}
+For example,
+
+\begin{music}\nostartrule
 \startextract
 \NOTes\ha g\enotes
 \leftrepeat
@@ -3663,7 +4742,7 @@ For example:
 \NOTes\ha i\enotes
 \rightrepeat
 \NOTEs\wh j\enotes
-\endextract
+\zendextract
 \end{music}
  \noindent has been coded as:
 \begin{quote}\begin{verbatim}
@@ -3675,71 +4754,33 @@ For example:
 \rightrepeat
 \NOTEs\wh j\enotes
 \end{verbatim}\end{quote}
-Special cases are forced line breaks:
-if you want to force a new line at a repeat, you should code
-respectively:
-
-\begin{quote}
-\noindent\keyindex{setrightrepeat}\keyindex{alaligne}\\
-\keyindex{setrightrepeat}\keyindex{endpiece}\\
-\keyindex{alaligne}\keyindex{leftrepeat}\\
-\keyindex{contpiece}\keyindex{leftrepeat}\\
-\keyindex{startpiece}\keyindex{leftrepeat}
-\end{quote}
 
-\noindent or the combination of two of these in the case of a left/right
-repeat.
-
- A second way of coding consists in saying \keyindex{setleftrepeat},
-\keyindex{setrightrepeat} or \keyindex{setleftrightrepeat} before a bar
-(\keyindex{bar}), \keyindex{stoppiece} or \keyindex{changecontext}). In
-this case, the next single vertical bar will be replaced with the selected
-repeat bar. This meets the traditional music typesetting conventions in the
-only case of the \ital{right repeat} but, unfortunately, left and left/right
-repeats use to behave in a different manner when in the middle of a line and
-at a line break.
-
- \subsection{Specific first and second pass scoring}
-
-\RuleOn
-A frequent situation consists in a long part of score repeated two or several
-times, but its last few bars are different at first pass and at second pass.
-This can be specified by saying
-\keyindex{setvolta}\verb|{|\ital{text}\verb|}| before the \keyindex{bar}
-beginning the part specific to that first or second part\footnote{The word
-``volta'' comes from Italian, it means ``time'' in the sense of ``first
-time'', ``second time'' or ``pass'' in that case.}.
-
- Then, only one bar has a horizontal rule above. No termination command is
-needed since termination is implied by the following \verb|\bar| or repeat
-symbol. For example:
-
-\medskip \begin{music}
- \parindent0pt \startpiece \addspace\afterruleskip
- \NOTEs\wh a\en\bar
- \NOTEs\wh b\en\setvolta{1.-3}\bar \NOTEs\wh c\en\setvolta4\rightrepeat
- \NOTEs\wh d\en\bar
- \NOTEs\wh e\en\Endpiece
-\end{music}
-which was coded as:
- \begin{quote}\begin{verbatim}
- \parindent0pt \startpiece \addspace\afterruleskip
- \NOTEs\wh a\en\bar
- \NOTEs\wh b\en\setvolta{1.-3}\bar \NOTEs\wh c\en\setvolta4\rightrepeat
- \NOTEs\wh d\en\bar
- \NOTEs\wh e\en\Endpiece
-\end{verbatim}\end{quote}
-
- 
-
- If the music typesetter wants to include more than one bar in the first
-pass[es] section and he wants all these to have a continuous line above, then
-he can code \keyindex{Setvolta}\verb|{|\ital{text}\verb|}| before the bar he
-wants the ``volta'' to begin, and put \keyindex{setendvolta} or
-\keyindex{setendvoltabox} before the bar they should end.
-\keyindex{setendvoltabox} makes the upper line to be terminated with a
-descending hook, symmetrical to the opening small vertical bar.
- 
+To insert a right repeat at a forced line break or at the end of a piece, use
+\verb|\setrightrepeat| \textit{before}\ \verb|\alaligne| or \verb|\endpiece|.
+In contrast, to insert a left repeat at a forced line break or at the
+beginning of a piece, simply use \verb|\leftrepeat| immediately \textit{after}
+\verb|\startpiece| or \verb|\alaligne|. To insert a left-right repeat at a
+forced line break, use \verb|\setrightrepeat\alaligne\leftrepeat|.
+
+In fact it is possible to use \keyindex{setleftrepeat},
+\keyindex{setrightrepeat} or \keyindex{setleftrightrepeat} before any
+\keyindex{bar}, \keyindex{stoppiece} or \keyindex{changecontext}. But
+be aware that while \verb|\setleftrepeat| behaves properly if the
+bar is at the end of a system, \verb|\setleftrightrepeat| does not, placing
+the symbol only at the end of the system.
+
+ \subsection{First and second endings (Voltas)}\index{volta}
+
+All volta commands must be entered right before the bar line command
+(or repeat, etc.) where they are to take effect. There are three
+commands that suffice to set all voltas. To start one, use
+\keyindex{Setvolta}\verb|{|\textit{text}\verb|}|; to terminate it
+with or without a vertical line, use \keyindex{endvolta} or
+\keyindex{endvoltabox} respectively. The text by default will be followed
+by a period. There are also various alternate
+commands (e.g., \verb|\setendvoltabox| is equivalent to \verb|endvoltabox|).
+Some such alternate forms are used in the following example, but the first three
+mentioned above are all that are required:
 
 \medskip \begin{music}
  \parindent0pt
@@ -3759,8 +4800,7 @@ descending hook, symmetrical to the opening small vertical bar.
  \NOTEs\wh h\en\setendvoltabox
  \Endpiece
  \end{music}
- \noindent has been
-coded as:
+ \noindent This was coded as
  \begin{quote}\begin{verbatim}
  \startpiece \addspace\afterruleskip
  \NOTEs\wh a\en\bar
@@ -3777,52 +4817,44 @@ coded as:
  \NOTEs\wh h\en\setendvoltabox
  \Endpiece
 \end{verbatim}\end{quote}
- \zkeyindex{leftrepeat}\zkeyindex{rightrepeat} The
-``volta'' symbols are normally set at \verb|4\internote| above the upper line
-of the staff and one bar(length?) wide.
-
- The final down hook is stated, either by \keyindex{setendvoltabox} at the end,
-or \keyindex{setvoltabox} at the beginning.
-
-\begin{important}
- You are no more allowed to open \verb|\Setvolta| or \verb|\setvoltabox| whan
-another of these multi-bar volta is pending. To re-open a \verb|\Setvolta| at
-the ens of another one, you must explicitly order the first one to be closed
-at the end of the bar where the second one is opened. Given examples had to be
-corrected in order to meet this new safety requirement.
-
-\end{important}
-
- For the sake of portability, \keyindex{endvolta} is identical ti
-\verb|\setendvolta|, and \keyindex{endvoltabox} is identical to
-\verb|\setendvoltabox|. Theses changes in the names ar intended to recall that
-these commant take effect only at the next bar, repeat or line break.
-
-
-\RuleOff
+ \zkeyindex{leftrepeat}\zkeyindex{rightrepeat}
 
- The altitude of the ``volta'' above the upper staff can
-be changed, redefining \keyindex{raisevolta}, e.g.:
+If the volta only spans one measure and ends without a vertical segment,
+it can be specified simply by saying
+\keyindex{setvolta}\verb|{|\textit{text}\verb|}| before the bar line command
+that starts it, and it will automatically terminate at the
+second bar line command:
 
- \verb|\def\raisevolta{7\internote}|
-
- \noindent or define it to be any other valid dimension.
-
- \medskip\noindent{\sl REMARK: the dot after "volta" numbering can be removed,
-simply by saying:}
-
- \verb|\def|\keyindex{voltadot}\verb| {}|
+\medskip \begin{music}
+ \parindent0pt \startpiece \addspace\afterruleskip
+ \NOTEs\wh a\en\bar
+ \NOTEs\wh b\en\setvolta{1.-3}\bar \NOTEs\wh c\en\setvolta4\rightrepeat
+ \NOTEs\wh d\en\bar
+ \NOTEs\wh e\en\Endpiece
+\end{music}
+\noindent which was coded as:
+ \begin{quote}\begin{verbatim}
+ \parindent0pt \startpiece \addspace\afterruleskip
+ \NOTEs\wh a\en\bar
+ \NOTEs\wh b\en\setvolta{1.-3}\bar \NOTEs\wh c\en\setvolta4\rightrepeat
+ \NOTEs\wh d\en\bar
+ \NOTEs\wh e\en\Endpiece
+\end{verbatim}\end{quote}
 
-\noindent {\sl and reset by:}
+The height above the top staff line of the horizontal line in a volta symbol
+is determined by the token \keyindex{raisevolta} which is 4\verb|\internote| by
+default. You can change this to any desired dimension.
 
- \verb|\def|\keyindex{voltadot}\verb| {.}|
+The period after the text can be
+removed by saying \verb|\def|\keyindex{voltadot}\verb|{}|
+and restored by \verb|\def|\keyindex{voltadot}\verb|{.}|\ .
 
- \subsection{Large scope repeats and orientation marks}
+ \subsection{Special symbols for repeating long sections}
 
-Large scope repeats have also been provided
-with special symbols, namely \keyindex{coda}~$p$, \keyindex{Coda}~$p$,
-\keyindex{segno}~$p$, where $p$ specifies the pitch. A bigger symbol is
-\keyindex{Segno} with no argument. For example, the following figure
+Four special symbols and corresponding macros are available, namely
+\keyindex{coda}~$p$, \keyindex{Coda}~$p$,
+and \keyindex{segno}~$p$, where $p$ specifies the pitch; and \keyindex{Segno}
+with no argument. Their behavior is illustrated in this example:
 
 \begin{music}
 \startextract
@@ -3834,227 +4866,320 @@ with special symbols, namely \keyindex{coda}~$p$, \keyindex{Coda}~$p$,
 \NOtes\Coda n\enotes
 \endextract
 \end{music}
-\noindent has been coded:
+\noindent which has been coded:
 \begin{quote}\begin{verbatim}
 \NOtes\segno m\enotes\bar
 \NOtes\coda m\enotes
 \NOtes\Segno\enotes\bar
 \NOtes\Coda m\enotes
 \end{verbatim}\end{quote}
-Orientation marks are set more often above larger orchestral pieces for
-easy come together of all instruments for exercise reasons. Often used are
-circled or boxed uppercase characters or digits. This can be done with
-
-\keyindex{boxit}\verb|{|\ital{text}\verb|}|~~~or\\
-\indent\keyindex{circleit}\verb|{|\ital{text}\verb|}|
 
-\noindent The distance between the box and the including text is influenced by
-
-\keyindex{boxitsep}\verb|=|\ital{any \TeX\ dimension}
-
-\noindent which is setup by default to \verb|3pt|. The usage is recommended
-with \keyindex{Uptext}, \keyindex{zcharnote}, \keyindex{zchar} or
-\keyindex{ccharnote}.
-
-\subsection{Repeating the last bar}
- This can be done using the symbol \keyindex{duevolte} (often used with
-\verb|\centerbar|, see example in \ref{barcentered}, p.
-\pageref{barcentered}), e.g.:
+\subsection{Repeating a single bar}
+ The special symbol for a single bar repeat is generated by \keyindex{duevolte}, as shown
+in the following example:
 
 \begin{music}
 \generalmeter\meterC
 \setclef1\bass\setstaffs1{2}
 \startextract
 \NOtes\sk\sk\pause|\qa{cegj}\en
-\bar\NOtes\qa{cdef}|\sk\sk\duevolte\en
+\bar\NOtes\qa{cdef}|\sk\hsk\duevolte\en
 \endextract
 \end{music}
-whose coding is:
+\noindent whose coding is:
 \begin{quote}\begin{verbatim}
 \generalmeter\meterC
 \setclef1\bass\setstaffs1{2}
 \startextract
 \NOtes\sk\sk\pause|\qa{cegj}\en
-\bar\NOtes\qa{cdef}|\sk\sk\duevolte\en
+\bar\NOtes\qa{cdef}|\sk\hsk\duevolte\en
 \endextract
 \end{verbatim}\end{quote}
 
- %\check
-
-\section{Miscellaneous}
- \subsection{Putting anything anywhere}
-\noindent Special macros are provided to help the composer to set any \TeX\
-text on the staffs. The macro
-
-\keyindex{zcharnote}~$p$\verb|{|text\verb|}|
-
-\noindent
-sets the given text with its base line at pitch $p$ of the current staff
-(this means it must be coded inside \verb|\notes...\enotes|).
-Whatever the length of the text, no spacing occurs.
-If you want the possible spilling text to expand on the left rather than
-on the right, then you can use \keyindex{lcharnote}.
-If you want the possible spilling text centered to current position,
-then you can use \keyindex{ccharnote} which causes no space.
-
-The macro \keyindex{zcharnote} is fit for coding special notations like
-accents above or below the notes. Also available are \keyindex{zchar},
-\keyindex{lchar} and \keyindex{cchar}, which
-allows only numbers for pitch, but enables the use of floats too.
-
-To place some text at the mid-position between the two staffs of
-a keyboard instrument, you may code:
-\begin{quote}
-\keyindex{zmidstaff}\verb|{|{\it text}\verb|}%| (to right)\\
-\keyindex{lmidstaff}\verb|{|{\it text}\verb|}%| (to left)\\
-\keyindex{cmidstaff}\verb|{|{\it text}\verb|}%| (centred)
-\end{quote}
-\noindent being however
-careful, a) to put it inside \verb|\notes...\enotes|, b) to code it in the
-text of the lower staff.
-
- A text to be put above the current staff is introduced by
-\keyindex{uptext}\verb|{...}|.
-This may however cause some collision with bar
-numbering or notes above the staff; it is then wise to use
-\keyindex{Uptext}\verb|{...}|
-which puts the text two note line distances higher (recommended to post
-the tempo).
- \subsection{Fonts} The text fonts loaded by \musixtex\ come in six different
-type sizes and three styles. The type sizes are 8\,pt, 10\,pt, 12\,pt, 14\,pt,
-17\,pt and 25\,pt, while the three styles are roman, bold and italic. The
-three smaller type sizes are available in all three styles, while the larger
-three sizes, which are intended for titles, are available only in bold style.
-The size selection macros are respectively \keyindex{smalltype},
+\noindent This is often used with \verb|\centerbar| to more easily center the
+symbol between bar lines, as shown in the example in section \ref{barcentered}.
+
+\section{Font selection and text placement}
+
+\subsection{Predefined text fonts}
+While any \TeX\ font can be used by \musixtex, there are certain styles and
+sizes that can be selected using shortcut commands.
+For ordinary text the shortcuts cover fonts of eight different
+sizes and three styles. The sizes in points are 8, 9, 10, 12, 14, 17, 20, and 25;
+the styles are from the standard Computer Modern family: Roman, bold and italic. The
+four smallest sizes are each available in all three styles, while the larger
+sizes, which are intended for titles, are available only in bold style.
+The size selection macros from smallest to biggest are \keyindex{smalltype},
+\keyindex{Smalltype},
 \keyindex{normtype}, \keyindex{medtype}, \keyindex{bigtype},
 \keyindex{Bigtype} ,
-\keyindex{BIgtype} and \keyindex{BIGtype}. Following the size selection, the
-style may be selected or changed using \keyindex{rm} (roman), \keyindex{bf}
-(bold) or \keyindex{it} (italic). If no style selection is made, roman style
-will result for the sizes smaller than \verb|\medtype|. For the larger sizes,
-style selection is not required since only bold style is provided. Thus,
-selection of eight point italic is done using \verb|\smalltype\it|, while
-twelve point roman is selected using \verb|\medtype\rm| or simply
+\keyindex{BIgtype} and \keyindex{BIGtype}. Following size selection, the
+style may be selected or changed using \keyindex{rm} (Roman), \keyindex{bf}
+(bold) or \keyindex{it} (italic). If no style is explicitly selected, Roman style
+will be used for the sizes \verb|\medtype| or smaller. For the larger sizes,
+only bold style is provided and no style selection is required. Thus, for example,
+eight point italic is selected with \verb|\smalltype\it|, while
+twelve point Roman is selected using \verb|\medtype\rm| or simply
 \verb|\medtype|. To change between styles while maintaining the same size,
-code \verb|\rm|, \verb|\it| or \verb|\bf| as in Plain \TeX. This information
-is summarized in the following table.
+code \verb|\rm|, \verb|\it| or \verb|\bf| as in Plain \TeX.
+When \musixtex\ is started, the default font for ordinary text is
+ten point Roman, equivalent to \verb|\normtype\rm|.
+
+Another group of fonts, in bold extended italic style, is predefined in point sizes
+10, 12, 14, and 17 for dynamic markings. The appropriate font for the current
+staff size may be selected simply by using \keyindex{ppff} as a
+font specification. Macros \verb|\smalldyn|, \verb|\normdyn|, or \verb|\meddyn| may be
+used to redefine \verb|\ppff| to represent one of the smallest three.
+
+All predefined fonts are summarized in the following table. The second column gives an
+explicit control sequence that can alternatively be used locally as a font specification.
 
 \begin{center}
-  \begin{tabular}{clc}
+  \begin{tabular}{lll}
     \hline
-    Size, pt & Size selection    &  Style selection \\
+    Size and style  &  Font specification & Example \\
     \hline
-     8       & \verb|\smalltype| & \verb|\rm, \bf, \it| \\
-    10       & \verb|\normtype|  & \verb|\rm, \bf, \it| \\
-    12       & \verb|\medtype|   & \verb|\rm, \bf, \it| \\
-    14       & \verb|\bigtype|   & \verb|    (\bf)    | \\
-    17       & \verb|\Bigtype|   & \verb|    (\bf)    | \\
-    20       & \verb|\BIgtype|   & \verb|    (\bf)    | \\
-    25       & \verb|\BIGtype|   & \verb|    (\bf)    | \\
+    \verb|\smalltype|    & \verb|\eightrm| & {\smalltype    small Roman}  \\
+    \verb|\smalltype\bf| & \verb|\eightbf| & {\smalltype\bf small bold}   \\
+    \verb|\smalltype\it| & \verb|\eightit| & {\smalltype\it small italic} \\
+    \verb|\Smalltype|    & \verb|\ninerm| & {\Smalltype    Small Roman}  \\
+    \verb|\Smalltype\bf| & \verb|\ninebf| & {\Smalltype\bf Small bold}   \\
+    \verb|\Smalltype\it| & \verb|\nineit| & {\Smalltype\it Small italic} \\
+    \verb|\normtype|     & \verb|\tenrm| & {\normtype     normal Roman} \\
+    \verb|\normtype\bf|  & \verb|\tenbf| & {\normtype\bf  normal bold}  \\
+    \verb|\normtype\it|  & \verb|\tenit| & {\normtype\it  normal italic}\\
+    \verb|\medtype|      & \verb|\twelverm| & {\medtype      medium Roman} \\
+    \verb|\medtype\bf|   & \verb|\twelvebf| & {\medtype\bf   medium bold}  \\
+    \verb|\medtype\it|   & \verb|\twelveit| & {\medtype\it   medium italic}\\
+    \verb|\bigtype|      & \verb|\bigfont| & {\bigtype      big bold}     \\
+    \verb|\Bigtype|      & \verb|\Bigfont| & {\Bigtype      Big bold}     \\
+    \verb|\BIgtype|      & \verb|\BIgfont| & {\BIgtype      BIg bold}     \\
+    \verb|\BIGtype|      & \verb|\BIGfont| & {\BIGtype      BIG bold}     \\
+    \verb|\smalldyn|  & \verb|\ppffsixteen| & {\ppffsixteen  pp ff diminuendo}\\
+    \verb|\normdyn|   & \verb|\ppfftwenty| & {\ppfftwenty   pp ff crescendo}\\
+    \verb|\meddyn|   & \verb|\ppfftwentyfour| & {\ppfftwentyfour   pp ff crescendo}\\[.4ex]
+    ~                & \verb|\ppfftwentynine| & {\ppfftwentynine   pp ff diminuendo}\\[.4ex]
     \hline
-  \end{tabular} \end{center} Two other text fonts are provided for dynamic
-markings. These are \keyindex{ppffsixteen}, \keyindex{ppfftwenty} and
-\keyindex{ppfftwentyfour}, suitable for dynamic markings with staff sizes of
-16\,pt, 20\,pt and 24\,pt respectively. The appropriate font for the current
-staff size may be selected by coding \keyindex{ppff}.
-
-Naturally other fonts may be loaded by the user if required.
-When \musixtex\ is started, the default text font is
-ten point roman, equivalent to \verb|\normtype\rm|.
- \subsubsection{Examples}
+  \end{tabular}
+\end{center}
+
+\subsection{User-defined text fonts}
+
+Since \musixtex\ is a superset of \TeX, you are free to use the standard \TeX\
+machinery for defining and using any special font you desire. You must first
+of course ensure that (a) all the necessary font files (e.g., \verb|bla10.tfm|,
+\verb|bla10.pfb|, or equivalents) are installed in the right places in your system, (b) all
+configuration files (e.g., \verb|config.ps| or equivalent) have been updated, and
+(c) the \TeX\ system has been ``rehashed''. Then you can use the font just as
+in any \TeX\ document, e.g. by coding \verb|\font blafont=bla10| and then
+\verb|\zchar{10}{\blafont Text in user-defined font}|.
+
+You might also wish to replace once and for all the typefaces invoked by the
+commands described in the previous section. Again, before doing this, you must
+follow steps (a-c) of the previous paragraph for all fonts in questions.
+\label{musixtmr}
+You can use the standard bitmapped fonts which are converted to
+postscript by e.g.\ \verb|dvips|, but you also may replace them
+by native postscript fonts.
+
+As an example, you can replace the standard \verb|musixtex| fonts by
+the Times series of fonts as follows:
+
+\begin{verbatim}
+% 8pt roman, bold, and italic
+\font\eightrm=ptmr7t at 8pt
+\font\eightbf=ptmb7t at 8pt
+\font\eightit=ptmri7t at 8pt
+% 9pt
+\font\ninerm=ptmr7t at 9pt
+\font\ninebf=ptmb7t at 9pt
+\font\nineit=ptmri7t at 9pt
+% 10pt
+\font\tenrm=ptmr7t
+\font\tenbf=ptmb7t
+\font\tenit=ptmri7t
+% 12pt
+\font\twelverm=ptmr7t scaled \magstep 1
+\font\twelvebf=ptmb7t scaled \magstep 1
+\font\twelveit=ptmri7t scaled \magstep 1
+% Large fonts for titles : normal shaped Times-Roman fonts are applied
+\font\bigfont=ptmr7t scaled \magstep2 % 14pt
+\font\Bigfont=ptmr7t scaled \magstep3 % 17pt
+\font\BIgfont=ptmr7t scaled \magstep4 % 20pt
+\font\BIGfont=ptmr7t scaled \magstep5 % 25pt
+%
+\normtype
+\end{verbatim}
+The above definitions are made available in a file
+\verb|musixtmr.tex|\footnote{by Hiroaki {\sc Morimoto}}, to be used as
+\begin{quote}\begin{verbatim}
+\input musixtex
+\input musixps
+\input musixtmr
+...
+\end{verbatim}\end{quote}
+
+\font\tnormtype=ptmr7t
+\font\tnormtypebf=ptmb7t
+\font\tnormtypeit=ptmri7t
+\font\tbigtype=ptmr7t scaled \magstep2
+\font\tBIgtype=ptmr7t scaled \magstep4
+
+\noindent Here's a comparison of some of the Computer Modern Roman and Times Roman fonts:
 \begin{center}
   \begin{tabular}{ll}
     \hline
-    Size and style  &  Example \\
-    \hline
-    \verb|\smalltype|    & {\smalltype    small roman}  \\
-    \verb|\smalltype\bf| & {\smalltype\bf small bold}   \\
-    \verb|\smalltype\it| & {\smalltype\it small italic} \\
-    \verb|\normtype|     & {\normtype     normal roman} \\
-    \verb|\normtype\bf|  & {\normtype\bf  normal bold}  \\
-    \verb|\normtype\it|  & {\normtype\it  normal italic}\\
-    \verb|\medtype|      & {\medtype      medium roman} \\
-    \verb|\medtype\bf|   & {\medtype\bf   medium bold}  \\
-    \verb|\medtype\it|   & {\medtype\it   medium italic}\\
-    \verb|\bigtype|      & {\bigtype      big bold}     \\
-    \verb|\Bigtype|      & {\Bigtype      Big bold}     \\
-    \verb|\BIgtype|      & {\BIgtype      BIg bold}     \\
-    \verb|\BIGtype|      & {\BIGtype      BIG bold}     \\
-    \verb|\ppffsixteen|  & {\ppffsixteen  pp ff diminuendo}\\
-    \verb|\ppfftwenty|   & {\ppfftwenty   pp ff crescendo}\\
-    \verb|\ppfftwentyfour|   & {\ppfftwentyfour   pp ff crescendo}\\
+    {\normtype     normal (10pt) cm Roman} &  {\tnormtype  normal Times Roman} \\
+    {\normtype\bf  normal cm bold}         &  {\tnormtypebf  normal Times bold}  \\
+    {\normtype\it  normal cm italic}       &  {\tnormtypeit  normal Times italic}\\
+    {\bigtype      cm big}                 &  {\tbigtype      Times big}     \\
+    {\BIgtype      cm BIg }                &  {\tBIgtype      Times BIg bold}     \\
     \hline
   \end{tabular}
 \end{center}
+
+\subsection{Text placement}\label{textplacement}
+Special macros are provided to allow precise placement of any \TeX\ text, vertically
+relative to the staff, and horizontally relative to any note in
+the staff.
+
+The macros in the first group will vertically position the text with the
+baseline at any specified pitch or staff line. They must be used
+inside \verb|\notes...\enotes|. They will not insert any additional
+horizontal space. They have the forms
+\keyindex{zcharnote}\pitchp\verb|{|\ital{text}\verb|}|, \keyindex{lcharnote}\pitchp\verb|{|\ital{text}\verb|}|,
+and \keyindex{ccharnote}\pitchp\verb|{|\ital{text}\verb|}|,
+where \ital{p} is the pitch. With the first one, text will spill to the right
+from the current insertion point, with the second it will spill to the left, and with the
+third it will be centered horizontally.
+
+There are similar macros \keyindex{zchar}\pitchp\verb|{|\ital{text}\verb|}|,
+\keyindex{lchar}\pitchp\verb|{|\ital{text}\verb|}|, and \keyindex{cchar}\pitchp\verb|{|\ital{text}\verb|}|,
+which differ from the previous three in that the pitch \ital{must} be given with
+a number (representing the number of staff positions up from the lowest line),
+and that the number need not be an integer.
+
+To vertically position any text midway between two consecutive staves, use
+\keyindex{zmidstaff}\verb|{|{\it text}\verb|}|, \keyindex{lmidstaff}\verb|{|{\it text}\verb|}|,
+or \keyindex{cmidstaff}\verb|{|{\it text}\verb|}| at the appropriate point in the lower staff.
+
+The macros \keyindex{uptext}\verb|{|\ital{text}\verb|}| and
+\keyindex{Uptext}\verb|{|\ital{text}\verb|}| are simply shorthands for
+\verb|\zchar{10}{|\ital{text}\verb|}| and \verb|\zchar{14}{|\ital{text}\verb|}| respectively.
+
+The text items handled by all of the above macros can include any appropriate
+string of \TeX\
+control sequences, including font definitions, \verb|\hbox|'es, etc.
+
+Material posted with any of the macros described in this section will not
+create any additional horizontal or vertical space within the current system,
+and will overwrite anything in the current system that gets in the way. It is
+the typesetter's responsibility to ensure there is adequate white space
+within the current system to accommodate any text emplaced with
+these macros. On the other hand, if text is emplaced far above or below a
+system, \musixtex\ will usually insert additional vertical space if needed.
+
+\subsection{Rehearsal marks}
+
+Rehearsal marks are usually
+boxed or circled uppercase letters or digits. They can be defined using the macros
+\keyindex{boxit}\verb|{|\ital{text}\verb|}| or
+\keyindex{circleit}\verb|{|\ital{text}\verb|}|. For boxed text,
+the margin between the text and box is controlled by the dimension
+register \keyindex{boxitsep}, which can be reset to any \TeX\ dimension if the
+default value of \verb|3pt| is unsatisfactory. To emplace the mark, use \verb|\Uptext| or
+any of the other macros defined in the previous section.
+
+
+\section{Miscellaneous other notations}
+%avre
  \subsection{Metronomic indications}
-Metronomic indication deserves a special macro. The mention:
+%Metronomic indication deserves a special macro. The mention:
+%
+%\medskip
+%\centerline{\def\nbinstruments{0}\metron{\hup}{60}}
+%
+%\smallskip\noindent
+%is coded by \keyindex{metron}\verb|{\hup}{60}| (normally embedded in
+%\keyindex{Uptext} which is in turn embedded within \verb|\notes...\enotes|).
+%
+% On the other hand, music writers sometimes want to specify that the duration
+%of a previous note is equal to a distinct furthernote. Thus
+%
+% \smallskip
+%\centerline{\def\nbinstruments{0}\metronequiv{\qup}{\qu}}
+%
+%\smallskip\noindent
+%is coded by \keyindex{metronequiv}\verb|{\qup}{\qu}|.
+
+By way of example, the notations~~~{\def\nbinstruments{0}
+\metron{\hup}{60}}~~~and~~~{\def\nbinstruments{0}\metronequiv{\qup}{\qu}}~~~are
+respectively coded as
+\keyindex{metron}\verb|{\hup}{60}| and \keyindex{metronequiv}\verb|{\qup}{\qu}|,
+which are normally emplaced using \keyindex{Uptext}.
 
-\medskip
-\centerline{\def\nbinstruments{0}\metron{\hup}{60}}\smallskip\noindent
-is coded by \keyindex{metron}\verb|{\hup}{60}| (normally embedded in
-\keyindex{Uptext} which is in turn embedded within \verb|\notes...\enotes|).
  \subsection{Accents}
-\begin{itemize}
- \item \keyindex{upz}~$p$ (upper \ital{pizzicato}) to put a dot above a note
+
+You may use\footnote{Note from the editor: the reason the names of some of
+these macros don't seem to be constructed to suggest the terms used in the
+descriptions is that whoever originally defined the macros had in mind terms
+that did not agree with normal English usage.}
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item \keyindex{upz}\pitchp~(upper \itxem{staccato}) to put a dot above a note
 head at pitch $p$,
- \item \keyindex{lpz}~$p$ (lower \ital{pizzicato}) to put a dot below a note
+ \item \keyindex{lpz}\pitchp~(lower \ital{staccato}) to put a dot below a note
 head at pitch $p$,
- \item \keyindex{usf}~$p$ (upper \itxem{sforzando}) to put a $>$ accent above
+ \item \keyindex{usf}\pitchp~(upper \itxem{sforzando}) to put a $>$ accent above
 a note head at pitch $p$,
- \item \keyindex{lsf}~$p$ (lower \itxem{sforzando}) to put a $>$ accent below
+ \item \keyindex{lsf}\pitchp~(lower \itxem{sforzando}) to put a $>$ accent below
 a note head at pitch $p$,
- \item \keyindex{ust}~$p$ (upper \itxem{staccato} or \itxem{portato}) to put a
+ \item \keyindex{ust}\pitchp~(upper \itxem{tenuto}) to put a
 hyphen above a note head at pitch $p$,
- \item \keyindex{lst}~$p$ (lower \ital{staccato} or \ital{portato}) to put a
+ \item \keyindex{lst}\pitchp~(lower \ital{tenuto}) to put a
 hyphen below a note head at pitch $p$,
- \item \keyindex{uppz}~$p$ (upper strong \ital{pizzicato}) to put an
-apostrophe above a note head at pitch $p$,
- \item \keyindex{lppz}~$p$ (lower strong \ital{pizzicato}) to put a reversed
-apostrophe below a note head at pitch $p$.
- \item \keyindex{usfz}~$p$ (upper \ital{sforzato}) to put a
-`roof' above a note head at pitch $p$,
- \item \keyindex{lsfz}~$p$ (lower \ital{sforzato}) to put a reversed
-`roof' below a note head at pitch $p$.
- \item \keyindex{upzst}~$p$ (upper \ital{portato/staccato}) to put a
-combined portato/staccato sign above a note head at pitch $p$,
- \item \keyindex{lpzst}~$p$ (lower \ital{portato/staccato}) to put a
-combined portato/staccato sign below a note head at pitch $p$.
- \item \keyindex{flageolett}~$p$ to put a
-thin circle above a note head at pitch $p$.
- \item \keyindex{upbow} to indicate a bowing for strings in upper direction.
- \item \keyindex{downbow} opposite to {\Bslash upbow}.
+ \item \keyindex{uppz}\pitchp~(upper \itxem{staccatissimo}) to put a solid vertical
+wedge above a note head at pitch $p$,
+ \item \keyindex{lppz}\pitchp~(lower \ital{staccatissimo}) to put an inverted
+solid vertical wedge below a note head at pitch $p$,
+ \item \keyindex{usfz}\pitchp~(upper \itxem{forzato}) to put a
+``dunce cap'' above a note head at pitch $p$,
+ \item \keyindex{lsfz}\pitchp~(lower \ital{forzato}) to put an inverted
+``dunce cap'' below a note head at pitch $p$,
+ \item \keyindex{upzst}\pitchp~(upper \itxem{staccato/tenuto}) to put a
+dot and a hyphen above a note head at pitch $p$,
+ \item \keyindex{lpzst}\pitchp~(lower \ital{staccato/tenuto}) to put a
+dot and a hyphen below a note head at pitch $p$,
+ \item \keyindex{flageolett}\pitchp~to put a
+small circle above a note head at pitch $p$.
 \end{itemize}
-Because whole notes (breve, arbitrary, ...) have a different note head width
-the accents appear not centered above them. Therefore you can use
-\keyindex{wholeshift}\verb|{|\ital{text}\verb|}| which centers accents
-and others
-which are centered above a quarter note head to appear centered above
-a whole note. This is used for e.g.~\verb|\Fermataup|.
-
-Also available are the variants\footnote{Thanks to Klaus {\sc Bechert}'s
-corrections.} of the most used accents which will be automatically positioned
-above or below a beam. Therefore the known accents are preceeded with the
-letter `b' and, instead of the pitch, the beam reference number is appended as
-an argument. Thus
+These marks are horizontally centered relative to solid note heads. To
+compensate for the fact that whole notes are wider, you should use
+\keyindex{wholeshift}\verb|{|\ital{Any nonspacing macro}\verb|}| to center accents
+and other items (e.g.~\verb|\Fermataup|) above a whole note.
+
+There are also variants of the most common accents\footnote{Thanks to Klaus
+{\sc Bechert}'s corrections.} which will be automatically positioned
+above or below a beam. They are spelled like the corresponding normal
+accent, but preceded with the letter \verb|b|, and their argument, instead of
+the pitch, is the beam reference number . Thus
 
 \medskip
-\begin{music}
+\begin{music}\nostartrule
 \startextract
 \Notes\ibu0f3\busfz0\qb0f\bupz0\qb0g\bust0\qb0h%
   \buppz0\qb0i\busf0\qb0j\butext0\tqh0k\en
 \Notes\Ibl0lg5\blsfz0\qb0l\blpz0\qb0k\blst0\qb0j%
   \blppz0\qb0i\blsf0\qb0h\bltext0\tqb0g\en
-\endextract
+\zendextract
 \end{music}
-\noindent was coded as:
-\begin{verbatim}
-\startextract
+\noindent was coded as
+\begin{quote}\begin{verbatim} \startextract
 \Notes\ibu0f3\busfz0\qb0f\bupz0\qb0g\bust0\qb0h%
   \buppz0\qb0i\busf0\qb0j\butext0\tqh0k\en
 \Notes\Ibl0lg5\blsfz0\qb0l\blpz0\qb0k\blst0\qb0j%
   \blppz0\qb0i\blsf0\qb0h\bltext0\tqb0g\en
-\endextract
-\end{verbatim}
+\zendextract
+\end{verbatim}\end{quote}
 \zkeyindex{busfz}
 \zkeyindex{bupz}
 \zkeyindex{bust}
@@ -4067,26 +5192,49 @@ an argument. Thus
 \zkeyindex{blppz}
 \zkeyindex{blsf}
 \zkeyindex{bltext}
- \subsection{*Indication of \ital{x}-tuplets}
 
- Triplets and other $x$-tuplets --- in practice the italic numbers \ital{3},
-\ital{4}, \ital{5}, etc. can be set at the right horizontal/vertical position
-invoking the  \keyindex{triolet} or \keyindex{xtuplet} macros at the leftmost
-position of the group, i.e. before the first note is coded.
+The macros \verb|\bltext| and \verb|\butext| are detailed in the next section,
+where the mystery of why they produce the number 3 is resolved.
 
- {\Bslash triolet} has only one argument, the pitch of the bottom of the
-figure 3, {\Bslash xtuplet} has two arguments: the figure and its pitch.
 
-If the figure has to be put above an upper beam or below a lower beam, using
-the macros \keyindex{butext} (above) and \keyindex{bltext} (below) is advisable
-to post the figure above or below the given beam. {\Bslash butext}
-and {\Bslash bltext} have one argument, namely the beam number (namely the
-same as the first argument of commands such as {\Bslash ibu} or {\Bslash
-Ibu}). If the group of notes is not a triolet, the actual figure has to be
-changed, redefining the macro \keyindex{txt} which is set up by default to:
+\subsection{Numbers and brackets for xtuplets}\label{tuplet}
 
-\verb|\def\txt{\eightit 3}%|
+The following table lists all the special macros that place a number indicating
+an xtuplet. Some also place a bracket above or below the notes, and are
+intended for use with unbeamed notes.
+In the table, $p$ is a pitch, $k$ is a number, $n$ is a beam number,
+$w$ is a bracket width in \verb|\internote|s, and $s$ is the bracket slope as
+a multiple of 1.125 degrees. The macro \verb|\txt| contains a default number
+and its font, which will be emplaced by the first and third through sixth macros,
+and is initially defined as \verb|\def\txt{\eightit 3}|. The macro
+\verb|\tuplettxt| serves the same role for the last two macros. The first four
+are to be used with beamed xtuplets. As indicated in the
+last column, the last four produce a sloping bracket and are to be used with
+unbeamed xtuplets. The last two require the extension file
+\verb|tuplet.tex| to be input right after \verb|\input musixtex|.
+
+
+\begin{center}
+  \begin{tabular}{lclcc}
+    \hline
+    ~ & Number & ~ & Needs & ~ \\
+    Macro and arguments & printed & Where invoked & \verb|tuplet.tex|? & Bracket \\
+    \hline
+    \verb|\triolet|\pitchp & \verb|\txt| & before beam & no & none \\
+    \verb|\xtuplet|\itbrace{k}\pitchp & $k$ & before beam & no & none \\
+    \verb|\butext|\itbrace{n} & \verb|\txt| & before note at number & no & none \\
+    \verb|\bltext|\itbrace{n} & \verb|\txt| & before note at number & no & none \\
+    \verb|\uptrio|\pitchp\itbrace{w}\itbrace{s} & \verb|\txt| & before first note & no & solid \\
+    \verb|\downtrio|\pitchp\itbrace{w}\itbrace{s} & \verb|\txt| & before first note & no &  solid \\
+    \verb|\uptuplet|\pitchp\itbrace{w}\itbrace{s} & \verb|\tuplettxt| & before first note & yes & with gap \\
+    \verb|\downtuplet|\pitchp\itbrace{w}\itbrace{s} & \verb|\tuplettxt| & before first note & yes & with gap \\
+    \hline
+  \end{tabular}
+\end{center}
+\medskip
 
+Here are some examples of the first six macros in the table:\\
+\vskip-3pt
 \begin{music}
 \parindent0mm
 \generalmeter{\meterfrac24}
@@ -4097,61 +5245,114 @@ changed, redefining the macro \keyindex{txt} which is set up by default to:
 \notesp\ibslurd0k\Ibl0km2\qb0k\bltext0\qb0l\tdbslur0m\tqb0m\en\bar
 \Notesp\triolet o\isluru0l\ql{lm}\tslur0n\ql n\en\bar
 \Notesp\uptrio o16\ql l\en\notesp\cl n\en
-\Notesp\uptrio p16\ql m\en\notesp\cl o\en
+%avrb
+\Notesp\downtrio O16\qu e\en\notesp\cu g\en
+%avre
 \endpiece
+whose coding is
 \begin{quote}\begin{verbatim}
 \notesp\xtuplet6n\isluru0l\ibl0l0\qb0{lllll}\tslur0l\tqb0l\en\bar
 \notesp\triolet n\isluru0l\Ibl0ln2\qb0{lm}\tslur0n\tqb0n\en
 \notesp\ibslurd0k\Ibl0km2\qb0k\bltext0\qb0l\tdbslur0m\tqb0m\en\bar
 \Notesp\triolet o\isluru0l\ql{lm}\tslur0n\ql n\en\bar
 \Notesp\uptrio o16\ql l\en\notesp\cl n\en
-\Notesp\uptrio p16\ql m\en\notesp\cl o\en
+\Notesp\downtrio O16\qu e\en\notesp\cu g\en
 \end{verbatim}\end{quote}
 \end{music}
 \zkeyindex{xtuplet}\zkeyindex{triolet}
-%\xtuplet{text}{pitch}
-%  centers text(3 on second note, 4 between second and thirdnote,
-%  5 on third note) on notes (-> \triolet{pitch})
- \subsection{*Usual ornaments}
 
- \subsubsection{Arpeggios}
-\ital{Arpeggios} (i.e.~~~\arpeggio{-2}3) can be coded with the macro
+\medskip
+Next are examples using the macros from \verb|\tuplet.tex|. Comparison of the
+coding with the printed result reveals that (a) a redefinition of
+\verb|\tuplettxt| inside a notes group only applies inside that group and
+leaves the default definition intact (bar 2),
+(b) the default definition is
+\verb|\def\tuplettxt{\ppffsixteen3}|, a 10-pt bold extended italic numeral 3
+which may be larger and heavier than desired (first set, bar 3) (c) to get the
+number properly centered in the gap, you must include some extra spaces after
+the number in the definition of \verb|\tuplettxt|, and (d) as you can see in
+the last bar, if the span becomes to small, the macros still won't provide
+enough room for the number in the gap; in this case it would be better to
+use to the macros without gaps.
+
+%   Examples:
+%
+%       Draw a triplet bracket over the notes, starting at pitch "p",
+%       1.25\noteskip wide, with a slope up of 3-3/8 degrees:
+%
+%           \uptuplet p{1.25}3
+%
+%       Draw a sextuplet bracket under the notes, starting at pitch "a",
+%       2.5\noteskip wide, with a slope down of 4-1/2 degrees:
+%
+%           \def\tuplettxt{\smallppff 6\/\/}
+%           \downtuplet{a}{2.5}{-4}
 
-\keyindex{arpeggio} $pm$
-
-\noindent where $p$ is the pitch of
-the base of the arpeggio symbol and $m$ is its multiplicity (one period is
-equal to one space between staff lines, i.e. 5 points). This macro causes
-no spacing. If should be issued before the concerned
-chords. Its variant \keyindex{larpeggio} sets the arpeggio symbol nearly
-one note head width on the left, in order to avoid collision with accidentals
-in front of the chords.
-
- \subsubsection{Trills}
- Trills\index{trills} can be coded in several ways.
-\keyindex{trille}~$pl$ (where $p$ is the pitch and $l$ is a number of current
-\ital{noteskip}) yields \hbox to 1cm{\noteskip1cm\trille11\hss} while
-\keyindex{Trille}~$pl$ yields \hbox to 2cm{\noteskip1cm\Trille12\hss}.
-
- For longer trills expanding over bars and line breaks, a better way consists
-in specifying the beginning with \keyindex{Itrille}~$np$ where $n$ is the
-trill reference number ($0\le n<6=$\keyindex{maxtrills}) and terminate it with
-the command \keyindex{Ttrille}~$n$. If one wants the {\it tr} mention at the
-beginning, then one should use \keyindex{ITrille}~$np$. The ancient commands
-\keyindex{itrille}, \keyindex{ttrille}~$p$ and \keyindex{tTrille}~$p$ still
-work but beware that their syntax is different, that the opening and the
-closing must be in the same bar and that the use the same registers as
-\verb|\Itrille 0|.
+\begin{music}
+\input tuplet
+\parindent0mm
+\generalmeter{\meterfrac24}
+%\startpiece
+\startextract
+\addspace\afterruleskip
+\notesp\triolet o\Ibl0ln2\qb0{lm}\tqb0n\en
+\notesp\Ibl0km2\qb0k\bltext0\qb0l\tqb0m\en\bar
+\notesp\def\tuplettxt{\eightit 5\/\/}\uptuplet o{4.1}2\cl{jklmn}\en\bar
+\Notesp\uptuplet o16\ql l\en\notesp\cl n\en
+\def\tuplettxt{\eightit 3\/\/}
+\Notesp\downtuplet O16\qu e\en\notesp\cu g\en\bar
+\notesp\uptuplet o16\ccl l\en\notesp\cccl n\en
+\notesp\downtuplet O16\ccu e\en\notesp\cccu g\en
+%\endpiece
+\endextract
+\end{music}
 
-\medskip
-\begin{remark} \verb|trille| and \verb|Trille| also exist in \musictex.
-Unfortunately, the same macro names do not have the same syntax and the same
-semantic in both packages and {\ttxem{musixcpt.tex}} forces the behaviour and
-the syntax of \musictex. A solution to this problem consists in using
-\keyindex{trilleC} and \keyindex{TrilleC} to have the \musictex{} behaviour,
-and \keyindex{trilleX} and \keyindex{TrilleX} to have the \musixtex{}
-behaviour, even when {\tt musixcpt} is invoked.
-\end{remark}
+\noindent with coding
+
+\begin{quote}\begin{verbatim}
+\input tuplet
+\parindent0mm\generalmeter{\meterfrac24}
+\startextract\addspace\afterruleskip
+\notesp\triolet o\Ibl0ln2\qb0{lm}\tqb0n\en
+\notesp\Ibl0km2\qb0k\bltext0\qb0l\tqb0m\en\bar
+\notesp\def\tuplettxt{\eightit 5\/\/}\uptuplet o{4.1}2\cl{jklmn}\en\bar
+\Notesp\uptuplet o16\ql l\en\notesp\cl n\en
+\def\tuplettxt{\eightit 3\/\/}
+\Notesp\downtuplet O16\qu e\en\notesp\cu g\en\bar
+\notesp\uptuplet o16\ccl l\en\notesp\cccl n\en
+\notesp\downtuplet O16\ccu e\en\notesp\cccu g\en
+\endextract
+\end{verbatim}\end{quote}
+
+ \subsection{Ornaments}
+
+ \subsubsection{Arpeggios}
+\ital{Arpeggios} (i.e.~~~\arpeggio{-2}3) can be coded with the macro
+\keyindex{arpeggio}\pitchp\itbrace{m}
+where $p$ is the pitch of
+the base of the arpeggio symbol and $m$ is its height in units of
+\verb|\interligne|, the distance from one staff line to the next. It should be
+issued before the affected chord. It is
+automatically positioned to the left of the chord, but inserts no spacing.
+Its variant \keyindex{larpeggio} sets the arpeggio symbol roughly
+one note head width to the left of the default position, and is intended to
+avoid collision with single accidentals on chord notes.
+
+ \subsubsection{Arbitrary length trills}
+ There are two styles of arbitrary length trills\index{trills}, each with two
+variants.
+For a trill with preassigned length, use \keyindex{trille}\pitchp\itbrace{l}
+for \hbox to 1cm{\noteskip1cm\trille11\hss} or
+\keyindex{Trille}\pitchp\itbrace{l} for~~\hbox to
+2cm{\noteskip1cm\Trille12\hss}, where $p$ is the pitch and $l$ the length in
+current \verb|\noteskips|.
+
+To let \musixtex\ compute the length of the trill, or if it extends across a
+system break, you can use \keyindex{Itrille}$n$\pitchp\ to start a plain
+trill, where $n$ is a trill reference number between 0 and 6; then
+\keyindex{Ttrille}$n$ to terminate it. To get the {\it tr} at the
+beginning, use \keyindex{ITrille}$n$\pitchp\ to start the trill and
+\verb|\Ttrille|$n$ to close it.
 
 For example:
 
@@ -4173,7 +5374,7 @@ For example:
 \end{music}
 whose coding is
 \begin{quote}\begin{verbatim}
-\begin{music}
+\begin{music}\nostartrule
 \instrumentnumber{1}
 \setstaffs12
 \setclef1{6000}
@@ -4190,10 +5391,10 @@ whose coding is
 \end{verbatim}\end{quote}
 
  \subsubsection{Piano pedal commands}
- \keyindex{PED} inserts the piano pedal command below the staff; pedal release
-is specified by \keyindex{DEP}; also available are shorter variants of the
-pedal signs which are invoked with \keyindex{sPED} and \keyindex{sDEP}; thus
-the following example
+The macro \keyindex{PED} inserts a piano pedal command below the staff;
+\keyindex{DEP}, a pedal release. Alternate symbols, the first of which
+occupies less space, are invoked with \keyindex{sPED} and \keyindex{sDEP}.
+For example,
 
 \begin{music}
 \setclef1\bass
@@ -4210,9 +5411,8 @@ the following example
 \Notes\sDEP\enotes
 \endextract
 \end{music}
- \noindent was coded as: \begin{quote}\begin{verbatim}
- \NOtes\PED\wh J|\qu
-h\enotes
+ \noindent was coded as \begin{quote}\begin{verbatim}
+ \NOtes\PED\wh J|\qu h\enotes
  \NOtes|\qu g\enotes
  \NOtes|\hu k\enotes
  \Notes\DEP\enotes \bar
@@ -4224,74 +5424,120 @@ h\enotes
 
  The vertical position of
 \keyindex{PED}, \keyindex{sPED}, \keyindex{DEP} and \keyindex{sDEP} can be
-globally changed by redefining its elevation, which is setup by default to
-
-\verb|\def|\keyindex{raiseped}\verb|{-5}%|
-
-If you only want to change a few of them, you can use the more fundamental
+globally changed by redefining its elevation, which has the default
+definition \verb|\def|\keyindex{raiseped}\verb|{-5}|.
+To locally change the vertical position of a pedal symbol, use one of the more
+fundamental
 macros \keyindex{Ped}, \keyindex{sPed}, \keyindex{Dep} and \keyindex{sDep}
 in combination with \keyindex{zchar} or \keyindex{zcharnote}.
-
- Since the \hbox to 1cm{ \Ped\hss} symbol is rather wide, it might collide
-with bass notes in an ugly way. Then a solution consists in shifting if to the
-left, by coding \verb|\loff{\PED}|.
+Since the \hbox to .7cm{ \Ped\hss} symbol is rather wide, it might collide
+with adjacent bass notes. To shift it horizontally, you could use \verb|\loff{\PED}|.
 
  \subsubsection{Other ornaments}\index{ornaments}
 
- \begin{itemize}
- \item \keyindex{mordent}~$p$ for \hbox to .75em{\mordent 0\hss},
- \item \keyindex{Mordent}~$p$ for \hbox to 1.5em{\kern 0.6em\Mordent 0\hss},
- \item \keyindex{shake}~$p$ for \hbox to .75em{\shake 0\hss},
- \item \keyindex{Shake}~$p$ for \hbox to 1.5em{\kern 0.6em\Shake 0\hss},
- \item \keyindex{Shakel}~$p$ for \hbox to 1.5em{\kern 0.6em\Shakel 0\hss},
- \item \keyindex{Shakesw}~$p$ for \hbox to 1.5em{\kern 0.6em\Shakesw 0\hss},
- \item \keyindex{Shakene}~$p$ for \hbox to 1.5em{\kern 0.6em\Shakene 0\hss},
- \item \keyindex{Shakenw}~$p$ for \hbox to 1.5em{\kern 0.6em\Shakenw 0\hss},
- \item \keyindex{turn}~$p$ for \hbox to 1.5em{\kern 0.6em\turn 0\hss},
- \item \keyindex{backturn}~$p$ for \hbox to 1.5em{\kern 0.6em\backturn 0\hss},
- \item \keyindex{fermataup}~$p$ puts a \itxem{fermata} at pitch $p$.
-No spacing occurs.
- \item \keyindex{fermatadown}~$p$ puts a reverse \ital{fermata} at the same
-place.
- \item \keyindex{Fermataup}~$p$ puts a \itxem{fermata} at pitch $p$ centered
-above a whole note. No spacing occurs.
- \item \keyindex{Fermatadown}~$p$ puts a reverse \ital{fermata} at the same
-place.
- \item A big \itxem{breathing} comma can be put above the staff --- to
-indicate where the singer is welcome to breath, or to indicate a short rest
---- using \keyindex{zbreath} (no spacing) or \keyindex{cbreath} (centred in a
-\verb|\noteskip| space). The \musictex\ \keyindex{breath} is no more available
-since it involved a ``hard'' spacing of the width of that character, which
-resulted in troubles with \musixtex.
-
- \item The \keyindex{caesura} command can also be used to insert a small
-slash, such as
+The argument $p$ in the following macros for ordinary ornaments is the
+pitch at which the ornament itself appears. They are all nonspacing macros.
+You may use
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item \keyindex{mordent}\pitchp\ for \hbox to .75em{\mordent 0\hss},
+ \item \keyindex{Mordent}\pitchp\ for \hbox to 1.5em{\kern 0.6em\Mordent 0\hss},
+ \item \keyindex{shake}\pitchp\ for \hbox to .75em{\shake 0\hss},
+ \item \keyindex{Shake}\pitchp\ for \hbox to 1.5em{\kern 0.6em\Shake 0\hss},
+ \item \keyindex{Shakel}\pitchp\ for \hbox to 1.5em{\kern 0.6em\Shakel 0\hss},
+ \item \keyindex{Shakesw}\pitchp\ for \hbox to 1.5em{\kern 0.6em\Shakesw 0\hss},
+ \item \keyindex{Shakene}\pitchp\ for \hbox to 1.5em{\kern 0.6em\Shakene 0\hss},
+ \item \keyindex{Shakenw}\pitchp\ for \hbox to 1.5em{\kern 0.6em\Shakenw 0\hss},
+ \item \keyindex{turn}\pitchp\ for \hbox to 1.5em{\kern 0.6em\turn 0\hss},
+ \item \keyindex{backturn}\pitchp\ for \hbox to 1.5em{\kern 0.6em\backturn 0\hss}.
+ \end{itemize}
 
-\begin{music}
+In the following macros for fermatas, the argument $p$ is the pitch of the
+notehead on which the fermata rests, assuming no additional vertical
+adjustments are needed for stems or intervening staff lines. They are all
+nonspacing macros. You may use
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item \keyindex{fermataup}\pitchp\ for
+\raisebox{0ex}[0ex][0ex]{\notesintext{\notes\fermataup1\en}},
+\end{itemize}
+\begin{itemize}\setlength{\itemsep}{3ex}
+ \item \keyindex{fermatadown}\pitchp\ for
+\raisebox{0ex}[0ex][0ex]{\notesintext{\notes\fermatadown2\en}},
+ \item \keyindex{Fermataup}\pitchp\ for
+\raisebox{-1ex}[-1ex][0ex]{\musicintextnoclef{\notes\Fermataup 7\zwh{'c}\en}}~,
+centered over a whole note,
+ \item \keyindex{Fermatadown}\pitchp\ for
+\raisebox{-1ex}[0ex][0ex]{\musicintextnoclef{\notes\Fermatadown1\zwh{'c}\en}}~,
+centered under a whole note.
+ \end{itemize}
+\bigskip
+
+A \itxem{breath} mark
+\raisebox{-5ex}[0ex][0ex]{\notesintext{\notes\zbreath\en}}
+can be put just above the staff with \keyindex{zbreath}. This is a nonspacing
+macro. On the other hand, \keyindex{cbreath} will cause a space of one
+\verb|\noteskip| and place the comma midway through the space.
+
+The \keyindex{caesura} command inserts a slash \verb|0.5\noteskip| before
+the place it is entered, while adding no space:
+
+\begin{music}\nostartrule
 \startextract
 \NOTes\zhu j\hl{^e}\caesura\en
 \Notes\zcu j\cl e\en
-\endextract
+\zendextract
 \end{music}
 
- \end{itemize}
-
- \subsection{Dynamic signs} Various
-dynamic signs can be posted with
-\keyindex{crescendo}\verb|{|$l$\verb|}| or
-\keyindex{decrescendo}\verb|{|$l$\verb|}|, to be used as arguments to
-\verb|\zcharnote|, \verb|\zchar|, \verb|\uptext|, \verb|\zmidstaff|, etc.
-
-Note: The biggest sign is $\simeq$ 68 mm long.
-
-Alternately they can be produced using the pair of \keyindex{icresc} and
-\keyindex{tcresc} or \keyindex{tdecresc}. Saying one time \verb|\icresc| you
-can force several \verb|\tcresc| or \verb|\tdecresc| with the same starting
-abscissa. Tha altitude of the [de]crescendo symbol is specified, not by the
-\verb|\icresc| macro which only defines the stating abscissa, but by the
-\verb|\tcresc| or \verb|\tdecresc| which is normally lifted up or down by
-means of a \verb|\zmidstaff| or a \verb|\zcharnote| command whose first
-argument has to be adjusted according to your visual needs.
+\subsection{Alphabetic dynamic marks}
+ Conventional dynamic symbols
+\pppp, \ppp, \pp,
+\p,
+\mezzopiano,
+\mf,
+\f,
+\fp,
+\sF,
+\ff,
+\fff\ and
+\ffff\ can be posted using the macros
+\keyindex{pppp},
+\keyindex{ppp},
+\keyindex{pp},
+\keyindex{p},
+\keyindex{mp},
+\keyindex{mf},
+\keyindex{f},
+\keyindex{fp},
+\keyindex{sF},
+\keyindex{ff},
+\keyindex{fff},
+\keyindex{ffff} respectively as the second argument of \verb|\zcharnote| or
+\verb|\ccharnote|.
+
+\subsection{Hairpins (crescendos and decrescendos)}\label{sec:crescnd}
+
+The syntax and properties of hairpins will differ depending on whether or not you
+have input \verb|musixps.tex|, which activates not only type K postscript slurs and
+ties but hairpins as well. The font-based variety are always horizontal,
+are limited in length, and cannot span system breaks. Using the postscript variety
+removes all these restrictions, but they will not be visible in DVI previewers.
+
+\subsubsection{Font-based hairpins}
+
+There are two categories of font-based hairpins. The first type requires only
+one command, \keyindex{crescendo}\verb|{|$\ell$\verb|}| or
+\keyindex{decrescendo}\verb|{|$\ell$\verb|}|, where $\ell$ is any \TeX{}
+dimension, either a fixed one---for example in points---or a scalable one
+expressed either explicitly or implicitly as some number of
+\verb|\noteskip|s. These should be used as arguments to
+\verb|\zcharnote|, \verb|\zchar|, \verb|\uptext|, \verb|\zmidstaff|, etc., to
+post them at the desired altitude. The longest such symbol is $\simeq$ 68 mm.
+
+The second type of font-based hairpin requires two commands, one to start it
+and another to end it. The starting macro is \keyindex{icresc}. It has no
+arguments. Only one invocation suffices to start any number and combination of
+crescendos and diminuendos. The ending macros are \keyindex{tcresc} or
+\keyindex{tdecresc}. They should be used as arguments of \verb|\zcharnote| etc,
+which will set the altitude. For example,
 
 \begin{music}
 \parindent0pt
@@ -4303,13 +5549,13 @@ argument has to be adjusted according to your visual needs.
 \Notes\zmidstaff{\loff\tcresc}\cmidstaff\fff|\ca{'f}\en
 \endextract
 \end{music}
-\noindent which was coded as:
-\begin{verbatim}
+\noindent which was coded as
+\begin{quote}\begin{verbatim}
 \Notes\cmidstaff\ppp|\ca c\en
 \Notes\icresc|\ca{defgh'abcde}\en
 \Notes\zmidstaff{\loff\tcresc}\cmidstaff\fff|\ca{'f}\en
-\end{verbatim}
-
+\end{verbatim}\end{quote}
+\medskip\noindent while
 \begin{music}
 \parindent0pt
 \generalmeter{\meterfrac{12}8}
@@ -4320,106 +5566,138 @@ argument has to be adjusted according to your visual needs.
 \Notes\zcharnote N{\tcresc}\cmidstaff\fff|\zcharnote q{\tcresc}\ca{'f}\en
 \endextract
 \end{music}
-\noindent which was coded as:
-\begin{verbatim}
+\noindent was coded as
+\begin{quote}\begin{verbatim}
 \Notes\cmidstaff\ppp|\ca c\en
 \Notes\icresc|\ca{defgh'abcde}\en
 \Notes\zcharnote N{\tcresc}\cmidstaff\fff|\zcharnote q{\tcresc}\ca{'f}\en
-\end{verbatim}
-
-
- Intensity conventional signs are: \keyindex{ppp},
-\keyindex{pppp},
-\keyindex{ppp},
-\keyindex{pp},
-\keyindex{p},
-\keyindex{mp},
-\keyindex{mf},
-\keyindex{f},
-\keyindex{fp},
-\keyindex{sF},
-\keyindex{ff},
-\keyindex{fff},
-\keyindex{ffff}, resulting in \pppp, \ppp, \pp,
-\p,
-\mezzopiano,
-\mf,
-\f,
-\fp,
-\sF,
-\ff,
-\fff\ and
-\ffff.
+\end{verbatim}\end{quote}
 
+\subsubsection{Postscript hairpins}
+As already noted, these require that you have input \verb|musixps.tex|.
+Once having done that, you should not try to use font-based hairpins
+because the syntax is incompatible.
+
+Again,
+there are two different types. The first type is normally initiated with either
+\keyindex{icresc}\onen~or \keyindex{idecresc}\onen, and terminated with
+\keyindex{tcresc}\onen, where $n$ is a hairpin index,
+which is virtually unlimited but certain restrictions apply if it exceeds 14.
+The altitude is set by the value of \keyindex{setcrescheight}, which by default
+is -5 and which must be expressed numerically. Note that
+\keyindex{tcresc}~is the same as \keyindex{tdecresc}.
+
+You can shift the starting or ending point horizontally by replacing the
+foregoing macros with
+\keyindex{ilcresc},    \keyindex{ildecresc},
+\keyindex{ircresc},    \keyindex{irdecresc},
+\keyindex{tlcresc},    \keyindex{tldecresc},
+\keyindex{trcresc},    \keyindex{trdecresc},
+for example to make space for an alphabetic dynamic mark.
+
+The second form of postscript hairpin macros allows individual and arbitrary
+specification of the altitude and horizontal offset. The syntax is
+\keyindex{Icresc}\itbrace{n}\itbrace{h}\itbrace{s}, where $h$ is the
+altitude---which must be numerical---and $s$ is the horizontal offset
+in \verb|\internote|. Similar syntax obtains for \keyindex{Idecresc}\
+and \keyindex{Tcresc}.
+
+These hairpins may span several lines. If one of them spans three systems
+then the height of the middle section can be adjusted with
+\keyindex{liftcresc}\itbrace{n}\itbrace{h}. The height of the first and last
+parts of a broken crescendo will be defined by the height parameter in
+\keyindex{Icresc}~or \keyindex{Tcresc}.
+
+There are numerous other nuances and shorthand macros that are described
+in the comments in \verb|musixps.tex|.
+
+As an example of a postscript hairpin,
+\begin{music}\nostartrule
+%\input smallmusixpsx
+\input musixps
+\generalmeter{\meterfrac{12}8}
+\startextract
+\Notes\ccharnote{-8}{\ppp}\Icresc0{-7}6\ca{bdegh'bde}\en
+\Notes\Tcresc0{-4}{-2}\zcharnote{-5}{\fff}\ca{'f}\en
+\zendextract
+\end{music}
+\noindent  was coded as
+\begin{quote}\begin{verbatim}
+\input musixps
+\generalmeter{\meterfrac{12}8}
+\startextract
+\Notes\ccharnote{-8}{\ppp}\Icresc0{-7}6\ca{bdegh'bde}\en
+\Notes\Tcresc0{-4}{-2}\zcharnote{-5}{\fff}\ca{'f}\en
+\zendextract
+\end{verbatim}\end{quote}
 
  \subsection{Length of note stems}
 
-%\begin{changebar}
+The default length of note stems is the distance of one octave, i.e.
+\verb|7\internote| or 4.66 \keyindex{interbeam}. The default may be changed
+with the macro \keyindex{stemlength}\itbrace{b}\ where $b$ is the length in
+\verb|\interbeam|s.
 
-Normally, the length of note  stems is the distance of one octave, i.e.
-\verb|7\internote|. This is equivalent to 4.66 \keyindex{interbeam}. The
-length of the stems may be changed using the macro \keyindex{stemlength}, e.g.:
-
-  \verb|\stemlength{5.2}|
-
-  \noindent which will set the stemlength to 5.2 \verb|\interbeam|. The default
- is
-\keyindex{stemlength}\verb|{4.66}|.
-
-Choral music with four voices is often typeset into two staffs. Thus, each
-staff holds two voices, one being typeset with stems up, the other with stems
-down. If the command \keyindex{stemcut} has been previously issued, stems that
-are outside the staff are cut depending on the pitch of the notes. If this is
-not wanted, this feature may be suppressed with the command
-\keyindex{nostemcut}. The default behaviour is \keyindex{stemcut} in plain
-\musixtex, and \keyindex{nostemcut} when {\ttxem{musixcpt.tex}} is invoked.
+The command \keyindex{stemcut} causes stems that extend outside the staff
+to be shortened depending on the pitch of the notes. It is the default
+behavior. To suppress this adjustment, issue the command
+\keyindex{nostemcut}.
 
 Normally, down stems never end above the middle line of the staff and up stems
-never below that line. This extension of the stems may be inhibited for the
-next generated stem using the command \keyindex{stdstemfalse}.  There is no
-\keyindex{stdstemtrue} since \keyindex{stdstemfalse} is reset after
-generating each new stem.
-
-%\end{changebar}
+never below that line. The command \keyindex{stdstemfalse} will inhibit this
+adjustment, but only for the next stem generated.  There is no command to globally
+suppress this behavior.
 
+ \subsection{Brackets, parentheses, and oblique lines}\label{brapar}
 
- \subsection{*Brackets and parentheses}
-
-
-Several brackets and parentheses have been provided for musical typesetting
-needs. These are:
- \begin{itemize}
+Several varieties of brackets, parentheses and oblique lines are provided for
+use within a score.
+ \begin{itemize}\setlength{\itemsep}{0ex}
  \item \keyindex{lpar}\verb|{|$p$\verb|}| and
-\keyindex{rpar}\verb|{|$p$\verb|}| which yield small
-parenthesis to enclose notes. These are used for \ital{cautionary} accidentals
-but more comprehensive macros fulfill that specific purpose (see \ref{cautionary})
- \item \keyindex{bracket}\verb|{|$p$\verb|}{|$n$\verb|}| to post square
-brackets of width $n$-internotes at left of a chord. Usually these brackets
-are used on keyboard instruments to specify, either two neighbouring notes
-played with a single finger, or some chord notes to be played with the
-alternate hand.
- \item \keyindex{doublethumb}\verb|{|$p$\verb|}|, to indicate a bracket of
-height 2\verb|\internote|.
+\keyindex{rpar}\verb|{|$p$\verb|}| yield left and right
+parentheses at pitch $p$. They could be used to enclose notes or to build
+\ital{cautionary} accidentals, although the latter are more easily
+obtained with predefined macros (see \ref{cautionary}).
+
+%avrb
+For example,
+
+\begin{tabular}{ll}
+\raisebox{-1.5ex}[0ex][0ex]{\musicintextnoclefn{\notes\bsk\lpar{g}\rpar{g}\hu{g}\sk%
+\loffset{1.5}{\lpar{g}}\loffset{1.5}{\rpar{g}}\loffset{.4}{\sh g}\hu{g}\en}}
+&\begin{tabular}{ll}
+&\verb+\notes\lpar{g}\rpar{g}\hu{g}\sk%+\\
+is coded as&\verb+\loffset{1.5}{\lpar{g}}\loffset{1.5}{\rpar{g}}%+\\
+&\verb+\loffset{.4}{\sh g}\hu{g}\en}+
+\end{tabular}
+\end{tabular}
+%avre
+
+ \item \keyindex{bracket}\verb|{|$p$\verb|}{|$n$\verb|}| posts a
+square bracket to the left of a chord, vertically spanning $n$
+\verb|internote|s.
+ \item \keyindex{doublethumb}\verb|{|$p$\verb|}| indicates a bracket as
+above spanning 2\verb|\internote|s.
  \item \keyindex{ovbkt}\verb|{|$p$\verb|}{|$n$\verb|}{|$s$\verb|}| and
 \keyindex{unbkt}\verb|{|$p$\verb|}{|$n$\verb|}{|$s$\verb|}|
-draw a bracket over the music starting at the current position at pitch $p$,
-width $n\times$\verb|noteskip| and slope $s$ (1 $\sim$ 1.125[degree]).
-causing no space.
+draw a sloped bracket starting at the current position at pitch $p$,
+with horizontal extent $n$ \verb|noteskip|s and slope $s$ in multiples of
+1-1/8 degree.
  \item \keyindex{uptrio}\verb|{|$p$\verb|}{|$n$\verb|}{|$s$\verb|}| and
-\keyindex{downtrio}\verb|{|$p$\verb|}{|$n$\verb|}{|$s$\verb|}|, which are like
-\verb|\ovbkt| but with free definable \keyindex{txt} centers in the middle.
+\keyindex{downtrio}\verb|{|$p$\verb|}{|$n$\verb|}{|$s$\verb|}| are like
+\verb|\ovbkt| but with freely definable \keyindex{txt} centered inside.
 
- \item \keyindex{varline} $h$ $\ell$ $s$ builds an oblique line of height $h$ (a
-dimension), of length $\ell$ and of slope $s$. Used to build oblique brackets.
-
-This feature is particularly useful for people who want to typeset
-\itxem{baroque} music using the ancient \itxem{ornament codings} rather than
-the modern equivalents. As a compromise, some macros kindly provided by Ian
-{\sc Collier} in Great Britain have slightly been updated and provided.
- \end{itemize}
+ \item \keyindex{varline}\itbrace{h}\itbrace{\ell}\itbrace{s}\ builds an
+oblique line starting at the current horizontal position. It must be used
+inside a zero box, such as for example as the second argument of
+\verb|\zcharnote|. $h$ is the height of the starting point, $\ell$ is the
+length, and $s$ is the slope. It is used in the definitions of some of
+the foregoing macros, and could be used, for example, to construct various
+obscure baroque ornaments made up of diagonal lines.
 
+\end{itemize}
 
-For example:
+For example,
 
 \begin{music}
 \setstaffs1{2}
@@ -4432,7 +5710,7 @@ For example:
 \NOtes\downtrio C16\qu {FH}|\uptrio o14\ql{lm}\en
 \endextract
 \end{music}
-\noindent
+\noindent is coded as
 \begin{quote}\begin{verbatim}
 \begin{music}
 \setstaffs1{2}
@@ -4443,38 +5721,33 @@ For example:
 \NOtes\lpar c\rpar c\qu c\en
 \NOtes\unbkt C15\qu {FH}|\ovbkt n14\ql{kl}\en
 \NOtes\downtrio C16\qu {FH}|\uptrio o14\ql{lm}\en
-\endextract
+\zendextract
 \end{music}
 \end{verbatim}\end{quote}
-\begin{remark} if you used \verb|\input musicext| before, pay attention to the
-commands \keyindex{ovbkt} and \keyindex{unbkt}, their parameter meaning has
-changed from \musictex{} to \musixtex.
- \end{remark}
- 
- \subsection{New line synchronization of coding}
- The procedure named \keyindex{everystaff} is executed each time a new system
-is typed. It is normally void, but it can be defined (simply by \verb|\def|%
-\keyindex{everystaff}\verb|{...}|) to tell \musixtex\ to post anything
-reasonable at the beginning of each system. It was used in the example
-{NWIDOR} to post octaviation dashed lines at the end of the piece.
-
-Caution should be exercised to call \verb|\everystaff| before
-\verb|\startpiece| if its effect is needed for the first system of the score.
-
- The procedure named \keyindex{atnextline}, normally void, is executed at the
-next computed or forced line break (using
-\keyindex{alaligne} or \keyindex{alapage}). More precisely, it is executed
-after the break and before the next system is typed. Thus it is fit for
-posting new definitions of layout parameters, when no system is
-pending\footnote{Its logic is similar to plain \TeX's \keyindex{vadjust}
-command.}.
-
- \index{tenor violin clef}In some scores, tenor parts are not coded using the
-\ital{bass} clef, but using rather the \ital{violin clef} subscripted by a
-{\tt8}. This is not directly supported by the \keyindex{setclef}
-command, but it can be handled using \keyindex{everystaff} and
-\keyindex{zcharnote}.
-As an example the following score
+
+ \subsection{Forcing activity at the beginning of systems}
+A macro named \keyindex{everystaff} is executed each time a new system
+begins. It is normally void, but it can be defined (simply by \verb|\def|%
+\keyindex{everystaff}\verb|{...}|) to cause \musixtex\ to post anything
+reasonable at the beginning of each system. For it to affect the first system
+in a score, it must be defined \ital{before}
+\verb|\startpiece|.
+
+If a macro named \keyindex{atnextline} is defined at any point in a score,
+it will be executed just once, viz., at the next computed or forced system
+break. More
+precisely, it is executed after the break and before the next system begins.
+Thus it is suitable for redefining layout parameters.
+
+ \index{octave treble clef}In some scores, tenor parts are not coded using the
+\ital{bass} clef, but using rather the \ital{octave treble clef}, which is
+subscripted by a numeral {\tt8}.
+This clef is supported by the clef substitution command
+\keyindex{settrebleclefsymbol}\onen\keyindex{treblelowoct}, as already
+explained in section \ref{treblelowoct}. However, if for some reason you
+aren't happy with the height of the ``8'', it can be posted on selected
+staves at the beginning of every system using \keyindex{everystaff} and
+\keyindex{zcharnote} as follows:
 
 \begin{music}
 \instrumentnumber{4}
@@ -4484,9 +5757,9 @@ As an example the following score
   &\zchar{-6}{\eightrm\kern-2\Interligne8}\en}%
 \startextract
 \NOTes\ha{HIJK}&\ha{efgh}&\ha{hijk}&\ha{hmlk}\en
-\endextract
+\zendextract
 \end{music}
-\noindent was coded as:
+\noindent The coding is
 \begin{quote}\begin{verbatim}
 \instrumentnumber{4}
 \setclef1\bass
@@ -4498,27 +5771,23 @@ As an example the following score
 \endextract
 \end{verbatim}\end{quote}
 
-\noindent{\sl{\bfseries Caution:} the \verb|\everystaff| must be called before
-\verb|startpiece| in order to have that subscript at the first staff.}
-\section{Small and tiny notes}
-Before entering details, let us point out that we are presently concerned with
-typing notes of smaller size than the normal one, without attempting to change
-the interval between the five lines building a single staff. Changing staff
-line interval will be treated in a further section.
- \subsection{Cadenzas and explicit ornaments}
- Ornaments and \itxem{cadenzas} usually need to be written using smaller
-notes\footnote{This is independent of the staff size.}. This can be done
-everywhere by stating \keyindex{smallnotesize} or \keyindex{tinynotesize}.
-Normal note size is restored by \keyindex{normalnotesize}.\index{ornaments}
-
- These macros only have a local scope. Thus, if these macros are invoked
-outside the \verb|\notes...\enotes| pair, the change is valid for
-the rest of the piece unless explicitely modified but, if they are invoked
-inside, their effect is local to the current staff of the current
-\verb|\notes...\enotes| pair.
-As an example, the following excerpt (beginning
+\section{Smaller notes in normal-sized staves}
+Here we describe how to reduce the size of note symbols without changing the
+size of the staff itself. Changing overall staff size will be treated in
+section \ref{staffspacing}.
+
+\subsection{Arbitrary sequences of notes}
+Written-out ornaments and \itxem{cadenzas} are usually typeset with
+smaller notes and spacing than normal. The smaller \ital{size} can be
+initiated anywhere inside a \verb|\notes| group by stating
+\keyindex{smallnotesize} or \keyindex{tinynotesize}. Normal note size is then
+restored by \keyindex{normalnotesize} or simply by terminating the
+\verb|notes| group and starting another. Smaller \ital{spacing} must also be
+explicitly indicated, usually by redefining \verb|\noteskip| in some way.
+
+As an example, this excerpt, from the beginning
 of the Aria of the ``Creation'' by Joseph {\sc Haydn})\index{Haydn, J.@{\sc
-Haydn, J.}}
+Haydn, J.}},
 
 \begin{music}
 \instrumentnumber{2}
@@ -4547,7 +5816,7 @@ Haydn, J.}}
 \notes&\sk\tbbl0\tbl0\qb0J|\tbl1\zq c\qb1e\en
 \endextract
 \end{music}
-\noindent can be coded as:
+\noindent can be coded as
 \begin{quote}\begin{verbatim}
 \instrumentnumber{2}
 \generalmeter{\meterfrac44}
@@ -4573,15 +5842,18 @@ Haydn, J.}}
 \notes&\sk\tbbl0\tbl0\qb0J|\tbl1\zq c\qb1e\en
 \endextract
 \end{verbatim}\end{quote}
- \subsection{Grace notes}
- Grace notes are a special case of small and tiny notes: the difference is
-that they are always coded as eighth notes with an oblique bar over the flag.
-To perform this, special variants of \keyindex{cu} and \keyindex{cl} have been
-provided, namely \keyindex{grcu} and \keyindex{grcl}, with the only difference
-that the flag has been slashed. Using this together with the note reduction
-macro, grace notes (optionally chord grace notes) can be easily coded:
 
-\begin{music}
+ \subsection{Grace notes}
+Grace notes are a special case of small and tiny notes, namely single-stemmed
+eighth notes with a diagonal slash through the flag. To enable this, there
+are the macros \keyindex{grcu}\pitchp\ and \keyindex{grcl}\pitchp, which by
+themselves would
+produce normal-sized eighth notes with a slash. They should be used along
+with the note size reduction macros and spacing reduction macros just
+discussed. In addition, chordal grace notes can be built as in the following
+example:
+
+\begin{music}\nostartrule
 \startextract
 \NOTes\hu h\enotes
 \notes\multnoteskip\smallvalue\smallnotesize\grcu j\enotes
@@ -4589,9 +5861,9 @@ macro, grace notes (optionally chord grace notes) can be easily coded:
 \bar
 \notes\multnoteskip\tinyvalue\tinynotesize\zq h\grcl j\enotes
 \NOTEs\wh i\enotes
-\endextract
+\zendextract
 \end{music}
-The previous example was coded as:
+\noindent which was coded as
 \begin{quote}\begin{verbatim}
 \startextract
 \NOTes\hu h\enotes
@@ -4600,76 +5872,137 @@ The previous example was coded as:
 \bar
 \notes\multnoteskip\tinyvalue\tinynotesize\zq h\grcl j\enotes
 \NOTEs\wh i\enotes
+\zendextract
+\end{verbatim}\end{quote}
+
+ \subsection[Ossia]{Ossia\texorpdfstring{\protect\footnote{(Italian O sia) Or else}}{}}
+This clever example had been provided by Olivier Vogel:\label{ossia}
+
+%\begin{center}
+%\includegraphics[scale=1]{./mxdexamples/ossiavogel.eps}
+%\end{center}
+
+\begin{music}
+%\startextract
+%\hsize70mm
+\let\extractline\hbox
+\hbox to \hsize{\hss
+\def\xnum#1#2#3{\off{#1\elemskip}\zcharnote{#2}{\smalltype\it #3}%
+\off{-#1\elemskip}}%
+\newbox\ornamentbox
+\setbox\ornamentbox=\hbox to 0pt{\kern-4pt\vbox{\hsize=2.6cm%
+\makeatletter
+\nostartrule\smallmusicsize\setsize1{\smallvalue}\setclefsymbol1\empty\global\clef@skip0pt%
+\makeatother
+%\smallmusicsize\setsize1{\smallvalue}\setclefsymbol1\empty%
+%\startpiece
+%\addspace{2pt}%
+\startextract
+\addspace{-2pt}%
+\let\notest\notes\def\notes{\vnotes2.1\elemskip}%
+\notes\ibbbl2{'c}0\qb2b\qb2c\qb2d\tbbbl2\qb2c\en%
+\notes\xnum{1.15}{'e}3\qb2d\qb2c\tbl2\qb2d\en%
+\notes\ibl2{'c}1\usf e\qb2c\en%
+\notes\tbl2\qb2{'d}\en
+\let\notes\notest%
+%\zstoppiece%
+\endextract
+}\hss}
+%\setbox\ornamentbox=\hbox to 0pt{Hello}
+%
+%
+%\normalmusicsize\nopagenumbers
+%\def\nbinstruments{1}%
+\setstaffs12\setclef1{60}%
+\generalsignature{-2}\generalmeter{\meterfrac{3}{4}}%
+%\parindent 0pt%
+%\stafftopmarg0pt\staffbotmarg5\Interligne\interstaff{10}\relax
+%\startpiece\addspace\afterruleskip%
+\startextract\addspace\afterruleskip%
+\NOtes\ibl1{'G}{-1}\qb1G\sk\bigna F\tbl1\qb1F|%
+\ibbl2{'b}0\qb2b\qb2a\qb2b\tbl2\qb2c\en%
+\NOtes\hl{'E}\bsk\raise6\internote\ds\ibu3{G}1\bigsh F%
+\qb3F\qb3G\tbu3\qb3{'A}|\zcharnote{10}{\copy\ornamentbox}\qlp{'c}\sk\sk%
+\cl d\en%
+%\endpiece
 \endextract
+\hss}
+%\vfill\eject\endmuflex
+\end{music}
+
+
+The code is:
+\begin{quote}\begin{verbatim}
+\hsize70mm%
+\def\xnum#1#2#3{\off{#1\elemskip}\zcharnote{#2}{\smalltype\it #3}%
+\off{-#1\elemskip}}%
+\newbox\ornamentbox
+\setbox\ornamentbox=\hbox to 0pt{\kern-4pt\vbox{\hsize=2.6cm%
+\nostartrule\smallmusicsize\setsize1{\smallvalue}\setclefsymbol1\empty%
+\startpiece\addspace{2pt}%
+\notes\ibbbl2{'c}0\qb2b\qb2c\qb2d\tbbbl2\qb2c\en%
+\notes\xnum{1.15}{'e}3\qb2d\qb2c\tbl2\qb2d\en%
+\notes\ibl2{'c}1\usf e\qb2c\en%
+\notes\tbl2\qb2{'d}\en%
+\zstoppiece%
+}\hss}
+\normalmusicsize\nopagenumbers
+\def\nbinstruments{1}%
+\setstaffs12\setclef1{60}%
+\generalsignature{-2}\generalmeter{\meterfrac{3}{4}}%
+\parindent 0pt%
+\stafftopmarg0pt\staffbotmarg5\Interligne\interstaff{10}\relax
+\startpiece\addspace\afterruleskip%
+\notes\ibl1{'G}{-1}\qb1G\sk\bigna F\tbl1\qb1F|%
+\ibbl2{'b}0\qb2b\qb2a\qb2b\tbl2\qb2c\en%
+\notes\hl{'E}\bsk\raise6\internote\ds\ibu3{G}1\bigsh F%
+\qb3F\qb3G\tbu3\qb3{'A}|\zcharnote{10}{\copy\ornamentbox}\qlp{'c}\sk\sk%
+\cl d\en%
 \end{verbatim}\end{quote}
- \subsection{Other note shapes}\label{othernotes} The classical note heads
-given above --- namely \raise.5ex\hbox{\musixchar7}~~, \raise.5ex
-\hbox{\musixchar8}~~ and \raise.5ex\hbox{\musixchar9}~~~
---- can be replaced with less classical note heads, for example to code
-special \itxem{violin harmonic notes} or \itxem{percussion music}. See an
-example in \ref{abnormalscores}.
-
- At present time, alternate available note heads can be found in the
-extension library, see \ref{diam}, \ref{perc}, \ref{gregnotes} and \ref{litu}.
-
-\section{Staff size} \index{staff size}
- \subsection{Moving from 20pt to 16pt, 24pt or 29pt staff sizes and
-conversely}
- You also want to write some parts of your score in 20pt
-staff size and others in 16pt or 24pt or 28.8pt staff size, namely
-for distinct parts of pieces. Changing the \ixem{general staff size}
-is done by saying:
-
-\keyindex{smallmusicsize}, or \keyindex{normalmusicsize}, or
-\keyindex{largemusicsize}, or \keyindex{Largemusicsize}.
-
-\noindent respectively.
- \subsection{Changing staff size for certain instruments}\label{staffspacing}
-Regardless of the general choice of \verb|\smallmusicsize| or
-\verb|\normalmusicsize|, it is now possible to assign certain instruments --
-not separate staffs belonging to a same instrument -- to have narrower or larger
-\itxem{staff size}, i.e. narrower or larger \itxem{staff spacing}. This is done using
-
-\keyindex{setsize} $n$\verb|{|\ital{size}\verb|}|
-
-\noindent where $n$ is the number of the instrument considered. Five different
-\ital{sizes} are available as standards: \keyindex{normalvalue}, which is
-the default, \keyindex{smallvalue} (0.80 times narrower),
-\keyindex{tinyvalue} (0.64 times narrower), \keyindex{largevalue} (1.2 times
-larger) and \keyindex{Largevalue} (1.44
-times larger). But, if you know perfectly what
-you are doing, you can also say:
-
-\verb|\setsize 3{2.0}|
-
-\noindent which will provide the third instrument with staffs of spacing
-twice the standard value. In that case, \musixtex\ will use the nearest
-symbol size available, but this is likely to be rather ugly.
-
- An alternate
-and equivalent coding --- a remnant from \musictex\ --- could be:
-
-\verb|\def\staffspacingiii{2.0}|\zkeyindex{staffspacing}
-
-
-
-\verb|\setsize| must be invoked before the starting command
-\verb|\startpiece|, since this statement does not only change the vertical
-spacing between staff lines, but it also changes the size of the key,
-accidental and note symbols to fit the modified staff line spacing.
-
- However, it must be emphasized that non-standard staff spacings use the
-nearest available font size. This make no serious problem for notes and
-accidentals which may be slightly too small or too big, but clefs and rests
-may appear to be shifted upwards or downwards. This trouble is progressively
-removed, but it requires changing the {\tt musix*} fonts, with some possible
-characters forgotten... or the fact that user uses a font older than T.60
-version.
+
+%
+% Why is this here?? DAS 4/30/06
+%
+% \subsection{Other note shapes}\label{othernotes}
+% The classical note heads
+%given above --- namely \raise.5ex\hbox{\musixchar7}~~, \raise.5ex
+%\hbox{\musixchar8}~~ and \raise.5ex\hbox{\musixchar9}~~~
+%--- can be replaced with less classical note heads, for example to code
+%special \itxem{violin harmonic notes} or \itxem{percussion music}. See an
+%example in \ref{abnormalscores}.
+%
+% At present time, alternate available note heads can be found in the
+%extension library, see \ref{diam}, \ref{perc}, \ref{gregnotes} and \ref{litu}.
+
+\section{Staff size} \index{staff size}\label{staffspacing}
+In contrast with the prior section, here we describe how to change the sizes
+of everything...staff, notes, and all other symbols. In
+section~\ref{whatspecify} we saw how to set the size for all instruments at
+the start of a score. Any one of the same macros---\verb|\normalmusicsize|,
+\verb|\smallmusicsize|, \verb|\largemusicsize|, or
+\verb|\Largemusicsize|---can be used to change the size of all instruments
+midway through a score, but in this case it must come between
+\verb|\stoppiece| and \verb|\startpiece|.
+
+Once the overall staff size is set, you can alter the size of any desired
+instrument with the macro \keyindex{setsize}\itbrace{n}\itbrace{s}, where
+$n$ is the instrument number and $s$ is a factor by which the size is to be
+changed from the prevailing overall size. There are five predefined macros
+that should be used for the size factor $s$. Their names and respective values
+are \keyindex{normalvalue}~(1.0), \keyindex{smallvalue}~(0.80),
+\keyindex{tinyvalue}~(0.64), \keyindex{largevalue}~(1.2), and
+\keyindex{Largevalue}~(1.44). \musixtex\ should not crash if you use an
+explicit number different from any of these, but the result may be
+less than satisfactory.
+
+Once again, if used at the beginning of a piece, the \verb|\setsize| macro
+must precede \verb|\startpiece| (not \verb|\contpiece|), and if used after
+the beginning, must be preceded by \verb|\stoppiece|.
 
 As an example, we give two bars of the \ital{Ave Maria} by Charles {\sc
 Gounod}\index{Gounod, C.@{\sc Gounod, C.}}, based on the first prelude of
-Johann-Sebastian Bach's \ital{Well Tempered Clavier} (transcription for
-organ, violin and voice, thanks to Markus {\sc Veittes}):\label{avemaria}
+J. S. Bach's \ital{Well Tempered Clavier}, as transcribed for
+organ, violin and voice by Markus {\sc Veittes}:\label{avemaria}
 
 \begin{music}
 \def\oct{\advance\transpose by 7}
@@ -4742,330 +6075,196 @@ organ, violin and voice, thanks to Markus {\sc Veittes}):\label{avemaria}
 \notes|\ibbu2i0\qb2{kfh}\tqh2k&\qp&\qp\enotes
 \endpiece
 \end{verbatim}\end{quote}
-\section{Layout parameters}
+
+\section{Layout parameters}\label{LayoutParameters}
  Most layout parameters are set by \musixtex\ to reasonable default values.
-However, sophisticated scores\footnote{To our knowledge, the most complicated
-scores are those written for the piano, during the romantic and post-romantic
-periods.} may need more place below the lowest staff, between staves, etc.
-\def\nochange{(\ital{NOT to be changed})} We give below a short list of the
-most significant parameters.
+However, some projects will require altering one or more of them. In this
+section we discuss the most important parameters and how to change them.
+
  \subsection{List of layout parameters}
- \begin{remark} the mention ``\nochange'' does not mean that this parameter
-cannot be changed, but that it should not be modified directly, e.g.\ by
-saying something like \verb|\Interligne=14pt|. In other words, changing these
-parameters must be performed using more comprehensive macros which not only
-update them but also perform some other compulsory related changes.
- \end{remark}
-
-\begin{description}
- \item[\keyindex{Interligne} :]vertical distance between the base of staff
-lines of the current instrument, taking no account of a possible specification
-of \keyindex{setsize$n$} \nochange.
- \item[\keyindex{internote} :]the vertical spacing of contiguous notes of
-the current instrument, taking account of a possible specification of
-\keyindex{setsize$n$} \nochange.
- \item[\keyindex{Internote} :]the vertical spacing of contiguous notes of
-the instrument(s) whose \keyindex{setsize$n$} has the \ital{default
-value} of one (\keyindex{normalvalue}),
-i.e.\ the half of \verb|\Interligne| \nochange
-
- \item[\keyindex{staffbotmarg} :]margin below the first staff of the lowest
-instrument. Changes are recognized at the next system and default is
-\verb|3\Interligne|.
- \item[\keyindex{stafftopmarg} :]margin above the upper staff of the upper
-instrument. Changes are recognized at the next system and default is
-\verb|3\Interligne|.
+ In the following, the indication ``\nochange'' does not mean that this
+parameter cannot be changed at all, but that it should not be modified
+directly, e.g.\ by saying something like \verb|\Interligne=14pt|. In other
+words, changes in these parameters must be accomplished only by more
+comprehensive macros which not only revise them but at the same time perform
+other necessary related changes. Even though you cannot \ital{change} these,
+you may \ital{refer} to them in your coding if that proves useful.
+
+\begin{description}\setlength{\itemsep}{0ex}
+ \item[\keyindex{Interligne} :]vertical distance between the bottoms of
+consecutive staff lines of the current instrument, taking no account of a
+possible alteration by \keyindex{setsize} \nochange.
+ \item[\keyindex{internote} :]vertical spacing between notes one scale
+step apart in the current instrument, taking account of a possible alteration
+by \keyindex{setsize} \nochange.
+ \item[\keyindex{Internote} :]vertical spacing between notes one scale
+step apart in any instrument whose \keyindex{setsize} has the default
+value \keyindex{normalvalue} (1.0), equal to \verb|0.5\Interligne| \nochange
+\item[\keyindex{staffbotmarg} :]margin below the first (lowest) staff of the
+first (lowest) instrument. Changes are recognized at the next system.
+Default is \verb|3\Interligne|.
+ \item[\keyindex{stafftopmarg} :]margin above the last (uppermost) staff of
+last (uppermost) instrument. Changes are recognized at the next system.
+Default is \verb|3\Interligne|.
  \item[\keyindex{interbeam} :]vertical distance between beams. \nochange.
- \item[\keyindex{interportee} :]the distance between the bottom of one staff and
-the bottom of the next one. It is set to
-\verb|2|\keyindex{interstaff}\verb|\internote| at the next system.
-Therefore, trying to change \verb|\interportee| will have no effect.
- %\check
- \item[\keyindex{interinstrument} :]the additional vertical distance between
-two different instruments. This means that the distance between the upper
-staff of the previous instrument and the lowest line of the current
-instrument is equal to \keyindex{interportee+\Bslash interinstrument}. This
-value is normally zero, but it helps putting additional space between
-distinct instruments for the sake of clarity. This is a general dimension
-register which holds for each of the vertical spaces between instruments,
-except above the upper one, in which case this interval is irrelevant.
-As usual in \TeX, it can be set using a command such as
-
- \verb|\interinstrument=10pt|
-
- \noindent or
-
- \verb|\interinstrument=6\internote|
-
-
- However, this general parameter can be overridden for the space above a
-specific instrument. For example (see the example {\tt angescao.tex}) one can
-state:
-
-\keyindex{setinterinstrument} $n$\verb|{1\Interligne}|
-
-\noindent to force an additional spacing of one \verb|\Interligne|
-above instrument $n$, whatever the value of \keyindex{interinstrument}.
- This feature can usefully be used to have more space before instruments
-representing \itxem{voices}, in order to have enough place to put
-\itxem{lyrics} without assigning these lyrics a zero staff specific instrument
-(useful to avoid having too many declared instruments in a choir score).
-
- The \verb|\setinterinstrument| is identical to the ancient --- and still
-working --- \musictex\ command:
-
- \verb|\def|\keyindex{interinstrumentiii}\verb|{5\interligne}|
-
- \noindent to add 5\verb|\interligne| above the 3rd instrument.
- %\check
-
+\item[\keyindex{interstaff} :]a very important macro with a single numerical
+argument representing the factor that multiplies \verb|2\internote| to give the
+distance between the bottom of one staff and the bottom of the next one. In
+fact the macro redefines the parameter \verb|\interfacteur|.
+\item[\keyindex{interportee} :]distance between the bottom of one staff and
+the bottom of the next one. It is always reset to
+\verb|2|\keyindex{interfacteur}\verb|\internote| at the next system.
+Therefore, trying to change \verb|\interportee| will have no effect. Change
+\verb|\interstaff| instead. Further, note that \verb|\interstaff| applies to all the
+instruments, but each distinct instrument may have a different
+\verb|\internote| (see \ref{staffspacing}).
 
- \item[\keyindex{systemheight} :]the distance from the bottom of the
-lowest staff to the top of the highest staff of the upper instrument. This is
-the height of the vertical bars (single, double, repeats, etc.) \nochange.
+\item[\keyindex{interinstrument} :]additional vertical distance between
+two consecutive instruments. This means that the distance between the lowest
+line of the previous instrument and the lowest line of the top staff of the current
+instrument is \keyindex{interportee+\Bslash interinstrument}. The
+default value of \verb|\interinstrument| is zero, but sometimes you
+may want additional space between distinct instruments. This is a general
+dimension register. As usual in \TeX, it can be set using a command such as
+\verb|\interinstrument=10pt| or \verb|\interinstrument=6\internote|. Its
+value can be overridden for the space above any particular instrument
+with the macro \keyindex{setinterinstrument}\itbrace{n}\itbrace{s}, where
+$n$ is the instrument and $s$ is the replacement value of the space to
+be added. The \verb|\setinterinstrument| macro may be useful in some vocal
+scores to provide vertical space for lyrics. Note that
+after you have used \keyindex{setinterinstrument},
+you cannot reset the distances for that instrument with
+\keyindex{interinstrument}; you must subsequently use
+\keyindex{setinterinstrument} for that purpose.
+
+ \item[\keyindex{systemheight} :]distance from the bottom of the
+lowest staff to the top of the highest one. This is the length of any
+vertical lines such as repeats that span the full height of a system.
+\nochange.
 \end{description}
+
  In addition, when handling notes of a given staff of a given instrument, the
 following dimensions are available (note these are not true registers, but
 \ital{equivalenced symbols} through a \verb|\def|):
-\begin{itemize}
- \item\keyindex{altplancher} : the altitude of the lowest line of the lowest
+
+\begin{description}\setlength{\itemsep}{0ex}
+ \item[\keyindex{altplancher} :]altitude of the lowest line of the lowest
 instrument \nochange.
- \item\keyindex{altitude} : the altitude of the lowest line of the lowest
+ \item[\keyindex{altitude} :]altitude of the lowest line of the lowest
 staff of the current instrument \nochange.
- \item\keyindex{altportee} : the altitude of the lowest line of the current
+ \item[\keyindex{altportee} :]altitude of the lowest line of the current
 staff \nochange.
 
  %??? Next perhaps will change to steps of \verb|\internote|.
 
- \item\keyindex{stemfactor} : a parameter defining the size of half, quarter
-and hooked eighth notes stems. Normally a stem has the length of one octave,
-i.e. 3.5\keyindex{Interligne}. However, this is not valid for small size
-notes and, therefore, the stem size is related to the \keyindex{interbeam}
-dimensions which, in turn, is \ital{normally} equal to 0.75
-\keyindex{Interligne}. Thus the normal value of \keyindex{stemfactor} is
-4.66, but it can be shortened for any purpose by saying, for example:
-
- \keyindex{stemlength}\verb|{3.5}|
-\end{itemize}
- \subsection{Changing layout parameters}
- Most of these values can be changed, but only between the end of the
-previous system and the beginning of the next one. This can be inserted
-between a \keyindex{stoppiece} (or a \keyindex{endpiece})
-and a \keyindex{contpiece} (or a \keyindex{startpiece}), but it is
-wiser to say, for example:
-
-\verb|\def\atnextline{\stafftopmarg=5\Interligne}|
-
- The user may prefer to change \keyindex{staffbotmarg} or
-to feed \keyindex{interstaff} with a
-given integer number, but this can be done only between a
-\keyindex{stoppiece} (or a \keyindex{endpiece}) and a
-\keyindex{contpiece} (or a \keyindex{startpiece}), but it is wiser to use
-\keyindex{atnextline} as previously.
-
- It is also wise to use \keyindex{atnextline} to change the
-number of instruments, the staff spacings, the number of staffs at the next
-line... provided that the coding of the notes \ital{resists} an unexpected
-line change executing the \keyindex{atnextline}.
- \subsection{Changing the staff distance within systems} The vertical
-distance of instruments with more than one staff can be changed, either
-outside \verb|\startpiece|...\verb|\endpiece| or using \keyindex{atnextline},
-by saying:
-
-\keyindex{interstaff}\verb|{|$n$\verb|}|
-
- Then the spacing between the staffs of the instruments will be
-$n$\verb|\internote|. Note that \verb|\interstaff| applies to all the
-instruments, but each distinct instrument may have a different
-\verb|\internote| (see \ref{staffspacing}).
-
- Note that this command is equivalent to an existing remnant of \musictex,
-namely:
-
- \verb|\def|\keyindex{interfacteur}\verb|{|$n$\verb|}|
-
-
- \medskip The distance between two different
-instruments can be increased by saying
-
-\keyindex{interinstrument}\verb|=|\ital{any \TeX-dimension}
-
-\noindent for all additional inter-instrument distances, or
-
-\keyindex{setinterinstrument} $n$\verb|{|\ital{any \TeX-dimension}\verb|}|
-
-\noindent for single distances.
- \subsection{Changing the number of lines in staffs}\index{staff line number}
-\label{stafflinenumber}
-Unless explicitely specified, staffs consist of five lines, in accordance to
-the normal way of coding music scores. However, exceptions might be
-preferred when using \musixtex~:
-
-\begin{itemize}
- \item \itxem{gregorian music} is often written using staff of
-four lines instead of five\footnote{German: \ital{Quadratnotation}.},
- \item \itxem{percussion music} (e.g.~drums, triangle) needs one, two, three
- or five lines, since the pitch cannot change but the number of percussion
- instruments.
- \item \itxem{guitar tablature} needs six lines. Although \ital{real} guitar
- players hate guitar tablature,
- for beginners they are a big help. Not ready yet. The lines
- are, but not the additional macros.
- 
- \item Early baroque music sometimes uses staffs with 6, 7, or 8 lines.
- 
- \end{itemize}
+ \item[\keyindex{stemfactor} :]parameter defining the length of stems on
+half, quarter, and beamed eighth notes, in units of \verb|\interbeam|.
+Normally a stem has the length of one octave,
+i.e. 3.5\keyindex{Interligne}. However, this is not correct for small or tiny
+note sizes. Therefore, stem length is defined as a multiple of the
+dimension \keyindex{interbeam}, which is chosen because it is automatically
+redefined as a
+different multiple of \keyindex{Interligne} whenever note size is changed. For
+example, with \verb|\normalmusicsize| when \verb|\setsize| is
+\verb|\normalvalue|, \verb|\interbeam| is 0.75 \keyindex{Interligne}. This
+legislates a default value for \keyindex{stemfactor} of 4.66 (=3.5/0.75).
+To change stem length, it is easiest to use e.g.
+\keyindex{stemlength}\verb|{3.5}|, which simply redefines \verb|\stemfactor|.
+Subsequently, \verb|\stemfactor| will not automatically be reset to the default,
+but keep in mind that if it is changed
+inside a notes group, the change will only be effective within that notes group.
+\end{description}
 
- Therefore \musixtex\ allows for choosing the number of lines of
-the staffs of an instrument. This is done by
-\keyindex{setlines}~$n$\verb|{|$N$\verb|}| --- where $n$ is the number of the
-wanted instrument as usual --- and $N$ the number of lines of the specific
-staff. Allowed numbers are up to 9 lines. For example:\label{gregorian}
- 
-\keyindex{setlines}\verb|2{4}|
+ \subsection{A convenient macro for changing layout parameters in mid-score}
+Of the parameters just described that can be changed, many should only be
+changed between the end of one system and the beginning of the next. The
+command sequence \verb|\def\atnextline{|\ital{any control sequence}\verb|}|
+may be useful for this purpose. It will cause \ital{any control sequence} to
+be inserted right before the next new line is begun, provided the line break
+is not initiated by a \verb|\startpiece|. Thus this will work with
+automatically generated line breaks, with those forced by \verb|\alaligne|, and
+with those forced by explicit use of \verb|\endpiece| or \verb|\stoppiece|
+followed by \verb|\contpiece|. (Note, however, that in the latter case it
+would be just as convenient to enter the parameter changes explicitly as well.)
+The control sequence will only be executed once,
+after which \verb|\atnextline| is redefined as \verb|\empty|.
+
+ \subsection{Changing the number of lines per staff}\label{stafflinenumber}
+Naturally, the default number of lines per staff is five. But you may want a
+different number in some or all staves, for example for gregorian music,
+percussion music, guitar tablature, or early baroque keyboard music. To do so,
+use the command \keyindex{setlines}\itbrace{n}\itbrace{m}~where $n$ is the
+instrument number and $m$ is the number of lines.
 
-\noindent will make the instrument number 2 to have staffs of four
-lines, that is, fit for gregorian music.
  \subsection{Resetting normal layout parameters}
- Except the general size which
-has to be explicitely changed if needed using \keyindex{smallmusicsize},
+The general size can only be changed with one of the commands
+\keyindex{smallmusicsize},
 \keyindex{normalmusicsize}, \keyindex{largemusicsize}, or
-\keyindex{Largemusicsize}, all layout registers are reset to \ixem{default
-values} by \keyindex{resetlayout}, which are explicitly:
-
- \begin{itemize}
- \item \keyindex{staffbotmarg} and \keyindex{stafftopmarg} are set to
-\verb|3\Interligne|.
- \item \keyindex{interstaff} is set to \verb|9|.
- \item The number of lines of all instruments are reset to 5.
- \item All clef symbols are standard clef symbols.
-\end{itemize}
-\noindent
-Besides, saying \keyindex{begin\LBR music\RBR} invokes \verb|\resetlayout|.
- \subsection{Typesetting one-line excerpts rather than large scores}
-Very often, what is wanted is not to typeset a large comprehensive score of
-several lines and pages, but an excerpt of one or two bars, preferably
-centered such as the various examples of this manual. This can be done simply
-by replacing \keyindex{startpiece} with
-\keyindex{startextract} and \verb|\endpiece| or \verb|\stoppiece| with
-\keyindex{endextract}. It is sometimes useful to get more than one excerpt in
-one line, this can be done with redefining of \keyindex{extractline}.
-
-With saying:
-
-\keyindex{let\Bslash extractline\Bslash hbox}
-
-\noindent you can put more than one example in one line. Helpful for getting
-\itxem{musical footnotes}, which explain the playing of special trills or
-give alternative ways of playing, is the redefining to:
-
-\keyindex{let\Bslash extractline\Bslash leftline}
-
-Besides, all changes inbetween
-\keyindex{begin\LBR music\RBR}...\keyindex{end\LBR music\RBR} are local,
-means not global.
+\keyindex{Largemusicsize}. Beyond that, the command
+\keyindex{resetlayout} will reset the following key layout parameters
+to their default values: \keyindex{staffbotmarg} (3\verb|\Interligne|),
+\keyindex{stafftopmarg} (3\verb|\Interligne|), \keyindex{interstaff} (9),
+ number of lines per staff for all instruments (5); and will reset all clef
+symbols to standard clef symbols.
+
+% The whole subsection on excerpts should go with "MusiXTeX and LaTeX", currently 2.25
+% \subsection{Typesetting one-line excerpts rather than large scores}\label{excerpts}
+
+% All the old lyrics stuff should be deleted, with a reference to some older version of
+% musixdoc.
+
+\section{Lyrics}\index{lyrics}\label{lyrics}
+\musixtex{} itself doesn't manage lyrics very well. You should use
+\verb+musixlyr+ instead, a MusiXTeX extension package for lyrics handling by Rainer Dunker.
+The \TeX~source and
+\href{http://icking-music-archive.org/software/musixtex/add-ons/mxlyrdoc.pdf}
+{\underline{documentation}}~are included in the \musixtex~distribution.
+
+But first we recall briefly on the older methods, who are still usefull when
+only a small number of words are involved.
+
+\subsection{Native lyrics method: placing single words}
+\subsubsection{Native \musixtex\ commands for lyrics}
+ \begin{enumerate}\setlength{\itemsep}{0ex}
+ \item An obvious solution consists in using the commandc
+\keyindex{zcharnote} (expanded to the right),
+\keyindex{lcharnote} (expanded to the left),
+\keyindex{ccharnote} (centered), to post the text at any position (computed in
+\verb|\internote|s) with respect to the lower line of the current staff.
+The pitch should be usually negative to have the text below the staff.
 
- If you want to terminate it without a bar, you code
-\keyindex{zendextract} which acts like \verb|\zstoppiece|.
- \subsection{*Lyrics}\index{lyrics}\label{lyrics}
- While they pose nearly no problem with \musictex\ which works using the glue
-facility of \TeX, lyrics raise several serious difficulties with \musixtex.
-The reason for that is that lyrics usually consist of \ital{text} which in
-turn consists of characters whose width is definitely not stretchable nor
-shrinkable proportionally to \verb|\noteskip| or \verb|\elemskip|.
+Example:\quad
+\raisebox{0ex}[4ex][3ex]{\musicintextnoclefn{\notes\sk\zcharnote{N}{Word}\wh g\sk\en}}
+\quad is coded by \quad
+\verb|\zcharnote{N}{Word}\wh g|~.
 
- Thus the width of a sequence of notes like
+\item The vertical position can also be given with a number in the commands
+\keyindex{zchar} (expanded to the right),
+\keyindex{lchar} (expanded to the left),
+\keyindex{cchar} (centered). The number is internally multiplied by \verb|\internote|~.
 
- \begin{music}
- \startextract
- \NOTEs\zcharnote{-5}{Words }\qu h\en
- \endextract
- \end{music}
+Example:\quad
+\raisebox{0ex}[4ex][3ex]{\musicintextnoclefn{\notes\sk\cchar{-4}{Word}\wh g\sk\en}}
+\quad is coded by \quad
+\verb|\cchar{-5}{Word}\wh g|~.
 
- \noindent may be either the width of ``{\tt Words }'' with the current font,
-or it may be \verb|1\elemskip|, whatever the largest. In the first case, the
-width is fixed (see \keyindex{hardspace}), in the second its width is not the
-same at \musixtex's first and second passes. But the unfortunate situation is that
-\musixtex\ \ital{must} know whether this feature has a \ital{hard} (not scalable)
-or a \ital{scalable} width \ital{at the first pass}, while the inequality
-is solved only at the second.
-
- This means that, in addition to the three pass system, the user must run
-trial and errors to find out whether some lyrics are wider than the final note
-spacing, or smaller. In that case a wrong decision might lead to questionable
-``\verb|Underfull hbox|''-es filled with ugly glue, or it may result in
-awful ``\verb|Overfull hbox|'' with its heavy bar punishment and possible
-over writings.
-
- However, before discussing this problem, we first describe the various ways of
-inserting lyrics under --- or above --- a staff.
-
- \subsubsection{Getting enough vertical space for lyrics}   Since songs are
-usually equivalent to a one-staff instrument (possibly with several voices)
-the recommended solution consists in adjusting the distance between
-instruments using either \keyindex{interinstrument}\verb|=|\ital{any
-\TeX-dimension} to give more place below all instruments or using
-\keyindex{setinterinstrument} to make more space above. Note that {\Bslash
-setinterinstrument} defines spacing above and not below an instrument. Since
-lyrics are usually set below the staff, the first argument of a
-\verb|\setinterinstrument| should be the song instrument number \ital{minus
-one}.
-
- In the case of a single staff tune, or if the song instrument is the lowest
-one, then additional place can be provided using \keyindex{staffbotmarg}.
-
- \subsubsection{Posting lyrics}
- Lyrics can be introduced in several ways.
- \begin{enumerate}
- \item One archaic solution could be to define a special instrument for the lyrics
-text, without effective staff, namely using the command
-\keyindex{setstaffs}~$n$\verb|{|$p$\verb|}| described in \ref{whatspecify}.
-The inconvenience of this solution is that it increases the number of
-instruments, which is limited to 6 in standard \musixtex, although it can be
-increased to 9 using {\tt musixadd.tex} and 12 with {\tt musixmad.tex}.
-
- \medskip
- Therefore, better solutions consist is posting the lyrics in the same
-instrument as the tune, provided that inter-instrument spacing has been
-adapted.
-
- \item Another simple obvious solution consists in using the command
-\keyindex{zcharnote} to post the text at any position (computed in
-\verb|\internote|s) with respect to the lower line of the current staff.
-The pitch should be usually negative to have the text below the staff. It
-could also be specified like a note pitch, for example ``{\tt a}'' if the song
-is in G-clef. The drawback is that the pitch has to be repeated for each text
-of each note, which is tideous unless a special macro has been defined.
-
- \item Rather than \verb|\zcharnote| and other \verb|\?charnote| commands, one
-should rather use \keyindex{zchar}, \keyindex{cchar} (centered) or
-\keyindex{lchar} (expanded to left) which only allow absolute numbers
-(internally multiplied by {\Bslash internote}). These command have the same
-drawback as above, namely the vertical position has to be repeated each time.
-
- \item Of easier use are the commands \keyindex{zsong} (right of the note),
+\item Of easier use are the commands \keyindex{zsong} (right of the note),
 \keyindex{lsong} (left) and \keyindex{csong} (centered) which post the lyrics
 at the lower staff line \ital{minus} the previous
 \keyindex{interinstrument}~$n$ or the \keyindex{staffbotmarg} quantity. These
 commands only have one argument, namely the lyrics text:
-
-
-\begin{center}
+%\begin{center}
 \keyindex{zsong}\verb|{|\ital{text}\verb|}|\quad
 \keyindex{lsong}\verb|{|\ital{text}\verb|}|\quad
 \keyindex{csong}\verb|{|\ital{text}\verb|}|
-\end{center}
-
+%\end{center}
  Depending on the values of the inter-instrument spacings and margins, the
 resulting vertical position might be inappropriate. Then it can be changed for
 any specific $n$-th instrument until further change using
-
 \begin{quote}
 \keyindex{setsongraise}~$n$\verb|{|\ital{any \TeX-dimension}\verb|}|
 \end{quote}
-
- \medskip As an example, the following French song
-
+As an example, the following French song\\
  \begin{music}
  \generalsignature{1}
  \startextract
@@ -5088,919 +6287,570 @@ any specific $n$-th instrument until further change using
  \end{music}
 
 \noindent was coded as:
-
 \begin{quote}\begin{verbatim}
  \generalsignature{1}
  \startextract
  \geometricskipscale
- \NOtes\zsong{Au }\qu g\en
- \NOtes\zsong{clair }\qu g\en
- \NOtes\zsong{de }\qu g\en
- \NOtes\zsong{la }\qu h\en
- \bar
- \NOTes\zsong{lu- }\hu i\en
- \NOTes\zsong{ne, }\hu h\en
- \bar
- \NOtes\zsong{mon }\qu g\en
- \NOtes\zsong{a- }\qu i\en
- \NOtes\zsong{mi }\qu h\en
- \NOtes\zsong{Pier- }\qu h\en
- \bar
+ \NOtes\zsong{Au }\qu g\zsong{clair }\qu g\en
+ \NOtes\zsong{de }\qu g\zsong{la }\qu h\en\bar
+ \NOTes\zsong{lu- }\hu i\zsong{ne, }\hu h\en\bar
+ \NOtes\zsong{mon }\qu g\zsong{a- }\qu i\en
+ \NOtes\zsong{mi }\qu h\zsong{Pier- }\qu h\en\bar
  \NOTes\zsong{rot, }\wh g\sk\en
- \endextract
+ \zendextract
 \end{verbatim}\end{quote}
+\end{enumerate}
 
+\subsubsection{Adapting note spacing for lyrics}
 
-  You can also use the macros from \verb|musixcho.tex|, which result in the
-same vertical positionning as \keyindex{zsong} and other \verb|\?song| do, but
-the text of the lyrics are better justified around the related note.
-
- \end{enumerate}
-
- \subsubsection{Handling lyrics width versus scalable note spacings}
-
- If one uses either \verb|\zsong| or \verb|\csong| or \verb|\lsong| without
-caution, one will probably get awful things such as:
+The command \keyindex{hardlyrics}\verb|{longword}| provides a spacing that is equal to the length
+of the text argument \verb|{longword}|. In the same time the argument \verb|{longword}|
+is saved in \keyindex{thelyrics}
 
- \begin{music}
- \generalsignature{1}
- \startextract
- \geometricskipscale
- \Notes\zsong{Au }\qu g\en
- \Notes\zsong{clair }\qu g\en
- \Notes\zsong{de }\qu g\en
- \Notes\zsong{la }\qu h\en
- \bar
- \NOtes\zsong{lu- }\hu i\en
- \NOtes\zsong{ne, }\hu h\en
- \bar
- \Notes\zsong{mon }\qu g\en
- \Notes\zsong{a- }\qu i\en
- \Notes\zsong{mi }\qu h\en
- \Notes\zsong{Pier- }\qu h\en
- \bar
- \NOTes\zsong{rot, }\wh g\sk\en
- \endextract
- \end{music}
+As an example \quad
+\raisebox{0ex}[5ex][4ex]%
+{\musicintextnoclefn{\staffbotmarg2\Interligne%
+\hardlyrics{clair}\notes\hsong{\thelyrics}\wh g\en\notes\wh{gg}\en}}
+\quad is coded by:
+\begin{tabular}{l}
+\verb|\hardlyrics{clair}%|\\
+\verb|\notes\hsong{\thelyrics}\wh g\en|\\
+\verb|\notes\wh{gg}\en|\\
+\end{tabular}
 
- \noindent which is the same example as above, with all spacings divided by
-1.41. Although locating ``overfull'' lyrics seems easy, it might be wiser to
-force their visibility, which is done replacing \verb|\zsong| with
-\keyindex{hsong} which encloses the hazardous text in a \verb|\hbox| of width
-\verb|\noteskip|, whose overfilling is diagnosed as usual by Plain \TeX\ or
-(especially in \LaTeX) by means of the \verb|\overfullrule=...| command:
+All notes with long lyrics need such a treatment. The commands only carry out on
+\verb|\notes| (not on \verb|\Notes|, \verb|\NOtes|...).
 
+If you want to go back to the normal placing on an easy way, you simply can replace
+'\verb|\hardlyrics|' by '\verb|\softlyrics|'.
 
- \begin{music}
- \generalsignature{1}
- \startextract
- \overfullrule 3pt%
- \geometricskipscale
- \Notes\hsong{Au }\qu g\en
- \Notes\hsong{clair }\qu g\en
- \Notes\hsong{de }\qu g\en
- \Notes\hsong{la }\qu h\en
- \bar
- \NOtes\hsong{lu- }\hu i\en
- \NOtes\hsong{ne, }\hu h\en
- \bar
- \Notes\hsong{mon }\qu g\en
- \Notes\hsong{a- }\qu i\en
- \Notes\hsong{mi }\qu h\en
- \Notes\hsong{Pier- }\qu h\en
- \bar
- \NOTes\hsong{rot, }\wh g\sk\en
- \endextract
- \end{music}
+ A complete score is given in example {\tt glorias.tex}\label{glorias} and in
+{\tt gloriab.tex}, the latter exhibiting not only the song tune but also the
+organ accompaniment.
 
- Alternate versions of \verb|\hsong| are \keyindex{dhsong} which has a fixed
+Alternate versions of \verb|\hsong| are \keyindex{dhsong} which has a fixed
 length of \verb|2\noteskip| and \keyindex{thsong} whose fixed length is
 \verb|3\noteskip|. These are useful when the text is set below (or above) a
 collective coding of two or three notes.
 
- Once one has diagnosed --- in the tentative final layout --- which lyrics
-lead to overfull texts, several corrections may be tried:
-
-\begin{enumerate}
- \item Increase the \keyindex{mulooseness} to have wider note spacing. This
-may work, but the inconvenience is that all notes would be stretched, and not
-only the faulty notes.
- \item Increase specific note spacings, replacing for example \verb|\Notes|
-with \verb|\NOtes| or \verb|\Notesp|. This is the easiest solution which may
-require several trials and errors since an increase of a few notes in a system
-may lead to a small shrinking of the others, to keep the total length
-constant.
- \item Decide that some notes --- only ``some'' notes, not all notes of the
-score, neither all the notes of a given system --- would have a \itxem{hard
-spacing} and not a scalable spacing. This is done using the command
-
- \begin{quote}
- \keyindex{hardnotes}\ital{ any hard \TeX\ dimension }\verb|\notes|\ital{
-normal note specif. }\verb|\en|
- \end{quote}
- \noindent   which ends the \verb|\notes...\en| with a \itxem{hard spacing} (see
-\verb|\hardspace| in \ref{hardspace}, p. \pageref{hardspace}) rather than a
-scalable spacing.
-
- A more practical variant has been provided especially for lyrics, namely
-
- \begin{quote}
- \keyindex{hardlyrics}\ital{ any text }\verb|\notes|\ital{
-normal note specif. }\verb|\en|
- \end{quote}
- \noindent which computes the width of ``any text'' by putting it in a
-\verb|\hbox| and reverting to \verb|\hardnotes| to perform the remainder of the
-task. In order to save repetitions, the text of the lyrics which has been used
-to compute the hard note spacing can be retrieved under the command name
-\keyindex{thelyrics}. \verb|\hardlyrics| must be followed by \verb|\notes|
-(with the lyrics text inbetween), not by \verb|\Notes| nor \verb|\NOtes|, etc.
-
-
- Besides, since moving the lyrics text between \verb|\hardlyrics| and
-\verb|\notes|\footnote{{\Bslash notes}, neither {\Bslash Notes} nor {\Bslash
-NOtes} nor {\Bslash NOTes} etc.} together with replacing it with
-\keyindex{thelyrics} at the initial location is a rather tedious operation
-with text editors, another command has been provided, namely
-\keyindex{softlyrics}:
-
- \verb|\softlyrics{|\ital{ any text }\verb|}|
-
- \noindent defines \verb|\thelyrics| to be ``\ital{ any text }'', so that
-going from \verb|\hardlyrics| to the default scalable behaviour of
-\verb|\noteskip| and inversely can easily be done by changing \verb|\hard|
-into \verb|\soft| in the source text, with optional change of the number of
-uppercase letters in \verb|\notes|.
-
-
- 
- \medskip\begin{important} since \/\verb|\hardlyrics| computes
-\/\verb|\noteskip|, its argument (before \/\verb|\notes|) may not refer to
-\/\verb|\noteskip|... which is not already computed.
- \end{important}
- \end{enumerate}
-
- \subsubsection{A more comprehensive example of lyrics}
- Here is an example taken from the French catholic liturgy (a French
-translation of the traditional \ital{Gloria in excelsis Deo}). We give first
-the adapted source of a part of the score:
-
+\subsection{Musixlyr}\label{musixlyr}
 
+Lyrics are best handled by the \texttt{musixlyr}\index{musixlyr} package by Rainer Dunker.
+The package can be used by inserting a file in your source code:
 \begin{quote}\begin{verbatim}
-\overfullrule 3pt
-\instrumentnumber{1}
-\setstaffs11
-%
-\generalsignature{-1}\relax % one flat
-\generalmeter{\meterfrac{2}{2}}
-%
-\staffbotmarg=5\Interligne\stafftopmarg=1.5\Interligne
-\startpiece
-\setsongraise1{2\Interligne}%
-\znotes\uptext{\kern -9mm\raise 9pt\hbox{\bigtype
-  Majestueux, sans tra\^\i ner \rm(\metron{\hu}{50})}}\enotes
-\hardlyrics {\kern-5pt Gloire }\notes\hsong{\thelyrics }\cu c\enotes
-\notes\hsong{\`a }\cu c\enotes
-\barre
-\NOTes\hsong{Dieu~}\hu f\enotes
-\notes\hsong{au}\cu f\enotes
-\hardlyrics{plus~}\notes\hsong{\thelyrics }\cu f\enotes
-\hardlyrics{haut~}\notes\hsong{\thelyrics }\cu g\enotes
-\notes\hsong{des}\cu g\enotes
-\barre
-\NOtes\hsong{cieux~}\qup h\enotes
-\notes\hsong{et~}\cu h\enotes
-\hardlyrics{paix~}\notes\hsong{\thelyrics }\qu i\enotes
-\hardlyrics{sur~}\notes\hsong{\thelyrics }\cu h\enotes
-\notes\hsong{la~}\cu g\enotes
-\barre
-\Notes\hsong{ter-}\qu f\enotes
-\notes\hsong{re~}\cu f\enotes
-\hardlyrics{aux~}\notes\hsong{\thelyrics}\cu f\enotes
-\hardlyrics{hom- }\notes\hsong{\thelyrics}\qu g\enotes
-\hardlyrics{mes~}\notes\hsong{\thelyrics }\cu h\enotes
-\hardlyrics{qu'il~}\notes\hsong{\thelyrics }\cu i\enotes
-\barre
-\NOtes\hsong{ai-}\hu g\enotes
-\Notes\hsong{me.}\hu f\enotes
-\Notes\uptext{\bf II }\enotes
-\barre
-\hardlyrics{Nous~}\notes\hsong{\thelyrics}\qu h\enotes
-\notes\hsong{Te~}\cu g\enotes
-\notes\hsong{lou-}\cu g\enotes
-\NOtes\hsong{ons,}\hu h\enotes
-\barre
-\hardlyrics{nous~}\notes\hsong{\thelyrics }\cu h\enotes
-\notes\hsong{Te~}\cu h\enotes
-\notes\hsong{b\'e-}\cu j\enotes
-\notes\hsong{nis-}\cu j\enotes
-\NOtes\hsong{sons,}\hu h\enotes
-\barre
-\Notes\hsong{nous~}\qu h\enotes
-\NOtes\hsong{t'a-}\hu g\enotes
-\Notes\hsong{do-}\qu f\enotes
-\barre
-\NOtes\hsong{rons,~}\hu f\enotes
-\notes\uptext{\bf I}\enotes
-\hardlyrics{nous~}\notes\hsong{\thelyrics }\cu h\enotes
-\notes\hsong{Te~}\cu h\enotes
-\notes\hsong{glo-}\cu g\enotes
-\notes\hsong{ri-}\cu g\enotes
-\barre
-\NOTEs\hsong{fions,~}\hu h\enotes
-\hardlyrics{\kern -4pt nous~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{Te~}\cu h\enotes
-\notes\hsong{ren-}\cu h\enotes
-\notes\zsong{dons~}\cu i\enotes
-\barre
-\NOtes\hsong{gr\^a~-}\qu g\enotes
-\notes\hsong{ces~}\cu g\enotes
-\hardlyrics{pour~}\notes\hsong\thelyrics\cu g\enotes
-\hardlyrics{Ton~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{im-}\cu i\enotes
-\hardlyrics{men-}\notes\hsong\thelyrics\cu j\enotes
-\notes\zsong{se~}\cu k\enotes
-\barre
-\Notes\hsong{gloi-}\ql j\enotes
-\Notes\hsong{-}\ql i\enotes
-\Notes\hsong{re~!}\qu h\enotes
-\notes\uptext{\bf II}\enotes
-\notes\hardlyrics{Sei-}\hsong\thelyrics\cu h\enotes
-\notes\zsong{gneur~}\cu i\enotes
-\barre
-\hardlyrics{Dieu,~}\notes\hsong\thelyrics\qu j\enotes
-\hardlyrics{Roi~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{du~}\cu g\enotes
-\Notes\hsong{Ciel,~}\qu h\enotes
-\hardlyrics{Dieu~}\notes\hsong\thelyrics\cu h\enotes
-\notes\zsong{le~}\cu g\enotes
-\barre
-\hardlyrics{P\`e-~}\notes\thelyrics\hsong\cu h\enotes
-\notes\hsong{re~}\cu i\enotes
-\hardlyrics{tout-}\notes\hsong\thelyrics\cu g\enotes
-\hardlyrics{puis-}\notes\hsong\thelyrics\cu h\enotes
-\hardlyrics{sant~!}\notes\hsong\thelyrics\qup h\enotes
-\notes\uptext{\bf I}\enotes
-\notes\zsong{Sei-}\cu h\enotes
-\mulooseness 2%
-\stoppiece
+\input musixtex
+\input musixlyr
+...
 \end{verbatim}\end{quote}
 
- The result clearly shows the inequality between note spacings,
-some of them forced by lyrics length, some others related to the
-value of \verb|\elemskip| choosen by {\tt musixflx} according to the
-given value of \keyindex{mulooseness}. Note that \verb|\zsong| still has been
-used for lyrics followed by a bar, since their extension across the bar is
-usually harmless.
-
+The manual, the input file and a few examples can be downloaded as
+compact musixlyr packet
+\href{http://icking-music-archive.org/software/musixtex/add-ons/musixlyr21c.zip}
+{\underline{for Windows}} or \href{http://icking-music-archive.org/software/musixtex/add-ons/musixlyr21c.tgz}
+{\underline{for \unix}}. Look at the manual for a detailed description. Here you can find an overview
+of the commands and an example of use.
+
+\def\keyexample#1{\keyindex{#1}}
+
+\noindent\begin{tabbing}
+\verb|\NOtes|\keyexample{assignlyricshere}\verb|{alto}\qa c\en|\quad\= assigning without staff number\kill
+Example\> Explanation
+\end{tabbing}
+\vspace{-1ex}
+\hrule
+\vspace{-2ex}
+\begin{tabbing}
+\verb|\NOtes|\keyexample{assignlyricshere}\verb|{alto}\qa c\en|\quad\= assigning without staff number\kill
+\keyexample{setlyrics}\verb|{sopr}{the ly_-ric words_}|\> defining the lyrics text\\
+\keyexample{copylyrics}\verb|{sopr}{alto}|\> alto has same lyrics as soprano\\
+\keyexample{appendlyrics}\verb|{alto}{more words}|\> alto lyrics is longer\\
+\keyexample{assignlyrics}\verb|2{sopr,alto}|\>soprano and alto lyrics at staff 2\\
+\keyexample{assignlyricsmulti}\verb|{1}{2}{alto}|\>assign alto lyrics to staff 2 of instrument 1\\
+\verb|\NOtes|\keyexample{assignlyricshere}\verb|{alto}\qa c\en|\>assigning without staff number\\
+\keyexample{auxlyr}\verb|\assignlyrics{2}{sopr}|\> assign soprano above staff 2\\[.8ex]
+\keyexample{lyrrule}\verb|\qu c|...\keyexample{lyrruleend}\verb|\qu c|\>make a melisma by hand\\
+\keyexample{beginmel}\verb|\qu c|...\keyexample{endmel}\verb|\qu c|\>melisma, same as word extension underline\\[.8ex]
+\keyexample{lyr}\verb|\qu c|\>force a syllable from lyrics text at this note or rest\\
+\keyexample{lyric}\verb|{word}\qu c|\>insert syllable 'word' at this note\\
+\verb|\loffset{2}{|\keyexample{lyric*}\verb|{1.}}\qu c|\>combine '1.' with regular syllable\\
+\keyexample{lyrich}\verb|{syl}\qu c|\>same as \verb|\lyric|, but with hyphenation\\
+\keyexample{lyrich*}\verb|{}\qu c|\>same as \verb|\lyric*|, but with hyphenation\\
+\keyexample{lyricsoff}...\keyexample{lyricson}\>stop lyrics, then start again\\
+\keyexample{nolyr}\verb|\qu c|\>no syllable at this note\\[.8ex]
+\keyexample{llabel}\verb|{labelname}name|\>labelling a ``go to'' target in text\\
+\keyexample{golyr}\verb|{labelname}\qu c|\>perform a jump, in music code\\[.8ex]
+\keyexample{lyrpt}\verb|,\qu c|\>add a comma to the syllable under this note\\
+\keyexample{lyrnop}\verb|\qu c|\>remove last character in syllable\\
+\keyexample{lclyr}\verb|\qu c|\>make first character lower case\\
+\keyexample{llyr}\verb|\qu c|\>left justified syllable\\
+\keyexample{leftlyrtrue}\verb|\qu c|...\keyexample{leftlyrfalse}\verb|\qu c|\>start and stop left justification as the default\\
+\keyexample{lyroffset}\verb|{-4}\qu c|\>shift syllable 1 notehead to the left\\[.8ex]
+\keyexample{minlyrspace}\verb|{3pt}\qu c|\>define minimum space between the words\\
+\keyexample{forcelyrhyphenstrue}\verb|\qu c|\>always use a hyphen from now on\\
+\keyexample{forcelyrhyphensfalse}\verb|\qu c|\>remove hyphen and make one word if necessary \\
+\keyexample{showlyrshifttrue}\verb|\qu c|\>show the lyric shift\\[.8ex]
+\keyexample{lyrraise}\verb|{1}{a 2\Interligne}|\>raise lyrics below staff 1 by \verb|2\Interligne|\\
+\keyexample{lyrraisemulti}\verb|{1}{2}{a 2\Interligne}|\>raise alto lyrics above staff 2 of instrument 1\\
+\keyexample{lyrraisehere}\verb|{b 2\Interligne}\qu c|\>raise lyrics below this staff by \verb|2\Interligne|\\[.8ex]
+\keyexample{minlyrrulelength}\verb|{2mm}|\>melismas shorter than 2mm are not shown \\
+\keyexample{minmulthyphens}\verb|{15mm}|\>distance between hyphens in 'hyphen melisma'\\
+\verb|\def|\keyexample{lyrhyphenchar}\verb|{-}|\>chose a hyphen character\\
+\verb|\setlyrics{|\keyexample{lyrlayout}\verb|{\it}..}|\>apply italics to all lyrics lines\\
+\keyexample{verses}\verb|{,\beginmel}\qu c|\>initiate melisma at second verse\\[.8ex]
+\verb|\small|\keyexample{setlyrstrut}\>adapt the vertical distance between lyrics lines\\
+\keyexample{lyrstrutbox}\verb|{10pt}|\> (re)define the distance between the lyrics lines\\[.8ex]
+\keyexample{lyrmodealter}\verb|2|\>attach lyrics of staff 2 to the upper voice\\
+\keyexample{lyrmodealtermulti}\verb|{1}{2}|\>attach lyrics of instr.\ 1 staff 2 to the upper voice\\
+\keyexample{lyrmodealterhere}\verb|\qu c|\>attach lyrics of this staff to the upper voice\\
+\keyexample{lyrmodenormal}\verb|2|\>restore the default behaviour\\
+\keyexample{lyrmodenormalmulti}\verb|{1}{2}|\>restore the default behaviour at staff 2 of instr.\ 1\\
+\keyexample{lyrmodenormalhere}\verb|\qu c|\>restore the default behaviour of this staff\\[.8ex]
+\keyexample{lyrlink}\>linking 2 words with a '$_{_\smile}$'\\
+\keyexample{lowlyrlink}\>same as \verb|\lyrlink| but a little bit lower\\[.8ex]
+\keyexample{resetlyrics}\>set word pointer to the first word in all lyrics lines\\[.8ex]
+\keyexample{enableauxlyrics}\>don't use this anymore\\
+\keyexample{setsongraise}\verb|{1}{2\Interligne}|\>same as \verb|{\lyrraise}{1}{b 2\Interligne}|\\
+\keyexample{auxsetsongraise}\verb|{1}{2\Interligne}|\>same as \verb|{\lyrraisemulti}{1}{b 2\Interligne}|\\
+\keyexample{oldlyrlinestart}\>don't let the lyrics extent to the left margin\\
+\end{tabbing}
+
+As a further illustration of the use of the commands, have a look at the following
+example\footnote{The example is taken from the musixlyr manual.}:
+
+\medskip\medskip
+%\oneversespace
 \begin{music}
-\small
-\overfullrule 3pt
-\instrumentnumber{1}
-\setstaffs11
-%
-\generalsignature{-1}\relax % one flat
-\generalmeter{\meterfrac{2}{2}}
-%
-\staffbotmarg=5\Interligne\stafftopmarg=1.5\Interligne
-\startpiece
-\setsongraise1{2\Interligne}%
-\znotes\uptext{\kern -9mm\raise 9pt\hbox{\bigtype
-  Majestueux, sans tra\^\i ner \rm(\metron{\hu}{50})}}\enotes
-\hardlyrics {\kern-5pt Gloire }\notes\hsong{\thelyrics }\cu c\enotes
-\notes\hsong{\`a }\cu c\enotes
-\barre
-\NOTes\hsong{Dieu~}\hu f\enotes
-\notes\hsong{au}\cu f\enotes
-\hardlyrics{plus~}\notes\hsong{\thelyrics }\cu f\enotes
-\hardlyrics{haut~}\notes\hsong{\thelyrics }\cu g\enotes
-\notes\hsong{des}\cu g\enotes
-\barre
-\NOtes\hsong{cieux~}\qup h\enotes
-\notes\hsong{et~}\cu h\enotes
-\hardlyrics{paix~}\notes\hsong{\thelyrics }\qu i\enotes
-\hardlyrics{sur~}\notes\hsong{\thelyrics }\cu h\enotes
-\notes\hsong{la~}\cu g\enotes
-\barre
-\Notes\hsong{ter-}\qu f\enotes
-\notes\hsong{re~}\cu f\enotes
-\hardlyrics{aux~}\notes\hsong{\thelyrics}\cu f\enotes
-\hardlyrics{hom- }\notes\hsong{\thelyrics}\qu g\enotes
-\hardlyrics{mes~}\notes\hsong{\thelyrics }\cu h\enotes
-\hardlyrics{qu'il~}\notes\hsong{\thelyrics }\cu i\enotes
-\barre
-\NOtes\hsong{ai-}\hu g\enotes
-\Notes\hsong{me.}\hu f\enotes
-\Notes\uptext{\bf II }\enotes
-\barre
-\hardlyrics{Nous~}\notes\hsong{\thelyrics}\qu h\enotes
-\notes\hsong{Te~}\cu g\enotes
-\notes\hsong{lou-}\cu g\enotes
-\NOtes\hsong{ons,}\hu h\enotes
-\barre
-\hardlyrics{nous~}\notes\hsong{\thelyrics }\cu h\enotes
-\notes\hsong{Te~}\cu h\enotes
-\notes\hsong{b\'e-}\cu j\enotes
-\notes\hsong{nis-}\cu j\enotes
-\NOtes\hsong{sons,}\hu h\enotes
-\barre
-\Notes\hsong{nous~}\qu h\enotes
-\NOtes\hsong{t'a-}\hu g\enotes
-\Notes\hsong{do-}\qu f\enotes
-\barre
-\NOtes\hsong{rons,~}\hu f\enotes
-\notes\uptext{\bf I}\enotes
-\hardlyrics{nous~}\notes\hsong{\thelyrics }\cu h\enotes
-\notes\hsong{Te~}\cu h\enotes
-\notes\hsong{glo-}\cu g\enotes
-\notes\hsong{ri-}\cu g\enotes
-\barre
-\NOTEs\hsong{fions,~}\hu h\enotes
-\hardlyrics{\kern -4pt nous~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{Te~}\cu h\enotes
-\notes\hsong{ren-}\cu h\enotes
-\notes\zsong{dons~}\cu i\enotes
-\barre
-\NOtes\hsong{gr\^a~-}\qu g\enotes
-\notes\hsong{ces~}\cu g\enotes
-\hardlyrics{pour~}\notes\hsong\thelyrics\cu g\enotes
-\hardlyrics{Ton~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{im-}\cu i\enotes
-\hardlyrics{men-}\notes\hsong\thelyrics\cu j\enotes
-\notes\zsong{se~}\cu k\enotes
-\barre
-\Notes\hsong{gloi-}\ql j\enotes
-\Notes\hsong{-}\ql i\enotes
-\Notes\hsong{re~!}\qu h\enotes
-\notes\uptext{\bf II}\enotes
-\hardlyrics{Sei-}\notes\hsong\thelyrics\cu h\enotes
-\notes\zsong{gneur~}\cu i\enotes
-\barre
-\hardlyrics{Dieu,~}\notes\hsong\thelyrics\qu j\enotes
-\hardlyrics{Roi~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{du~}\cu g\enotes
-\hardlyrics{Ciel,~}\notes\hsong\thelyrics\qu h\enotes
-\hardlyrics{Dieu~}\notes\hsong\thelyrics\cu h\enotes
-\notes\zsong{le~}\cu g\enotes
-\barre
-\hardlyrics{P\`e-~}\notes\hsong\thelyrics\cu h\enotes
-\notes\hsong{re~}\cu i\enotes
-\hardlyrics{tout-}\notes\hsong\thelyrics\cu g\enotes
-\hardlyrics{puis-}\notes\hsong\thelyrics\cu h\enotes
-\hardlyrics{sant~!}\notes\hsong\thelyrics\qup h\enotes
-\notes\uptext{\bf I}\enotes
-\notes\zsong{Sei-}\cu h\enotes
-\mulooseness 2%
-\stoppiece
+\input musixlyr
+ \resetlyrics \small
+\lyrmodealter0
+ \setlyrics{soprano}{bring her die Gans,} \auxlyr{\assignlyrics1{soprano}}
+ \copylyrics{soprano}{alto}                       \assignlyrics1{alto}
+
+ \generalsignature{-2}
+ \advance\stafftopmarg1\Interligne
+ \advance\staffbotmarg2\Interligne
+
+ \startextract\addspace\afterruleskip
+  \NOtes\zqu g\ql e\en
+  \bar
+  \Notes\zqu i\beginmel\ibslurd0f\ibl0f{-1}\qb0{fe}\en
+  \Notes\auxlyr\beginmel\ibsluru1i\zqup i\qb0d\en
+  \Notes\tqb0e\en
+  \Notes\endmel\tbslurd0e\ql c\en
+  \notes\ibbu0h{-1}\qb0h\tqh0g\en
+  \NOtes\auxlyr\endmel\tbsluru1h\zqu h\ql c\en
+  \bar
+  \NOTEs\auxlyr\lyr\zwh i%       The lyrics of the whole notes
+    \lyr\wh b\en     %       must be given manually.
+ \endextract
+ \lyrmodenormal0
 \end{music}
+\medskip
 
+%\oneversespace
 
- The complete score of this carol --- with slightly different layout
-due to different page size --- is given in example {\tt glorias.tex} and in
-{\tt gloriab.tex}, the latter exhibiting not only the song tune but also the
-organ accompaniment
-(both require {\tt musixsty.tex}).
-
-
-\section{Abnormal music coding}
- \subsection{Gregorian chant: staffs and clefs} \index{gregorian
-music}Gregorian chant is often coded using four line staffs (see sections
-\ref{gregorian} and \ref{stafflinenumber}) and using special notes (called
-\itxem{neumes}) which are described in section \ref{gregnotes}. But the
-gregorian chant also needs special clefs which are in fact the ancestors of
-the modern ones. The \itxem{gregorian clefs} can be invoked instead of the
-modern ones by:
-
-\keyindex{setaltoclefsymbol}\verb|3\gregorianCclef|
-
-\keyindex{setbassclefsymbol}\verb|3\gregorianFclef|
-
-\noindent will cause the instrument number 3 to exhibit the chosen gregorian
-clefs. The standard clefs can be restored for every instrument with
-\keyindex{resetclefsymbols}.
-
-It is to be emphasized that, since version T.40 of \musixtex, one should
-specify whether one wants to change the bass clef symbol or the alto clef
-symbol (also the treble clef symbol, but there is no treble clef in gregorian
-chant). The reason is that \musixtex\ (as well as \musictex) selects and
-raises differently the F, G and C clefs according to the arguments of the
-\keyindex{setclef} command. Therefore, if one had substituted any F clef
-symbol while saying \verb|\setclef1{1000}|, then an F clef would duly appear
-on the staff, but it would have been set at the position of an alto clef, thus
-seriously misleading the musician.
-
- However, for compatibility with what was previously choosen\footnote{By A.
-{\sc Egler}...}, the \keyindex{setclefsymbol} still exists, but it substitutes
-the given second argument \ital{to all clef symbols} of that instrument,
-regardless of the actual musical meaning of this symbol. \verb|\setclefsymbol|
-is therefore discouraged, unless one changes the design of the clef symbol of
-an instrument for the whole of the score.
-
- As an example, the same gregorian scale has been written with a gregorian C
-clef on all four lines of the staff:
-
- \begin{music}
- \parindent 19mm
- \instrumentnumber{4}
- \setname1{1st line} \setname2{2nd line} \setname3{3rd line} \setname4{4th line}
- \setlines1{4}\setlines2{4}\setlines3{4}\setlines4{4}
- \sepbarrules
- \generalmeter{\empty}
- \setclef1{1000} \setclef2{2000} \setclef3{3000} \setclef4{4000}
- \setaltoclefsymbol1\gregorianCclef
- \setaltoclefsymbol2\gregorianCclef
- \setaltoclefsymbol3\gregorianCclef
- \setaltoclefsymbol4\gregorianCclef
-\startextract
-\Notes\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\enotes
-\endextract
-\end{music}
-
- The coding was:
- \begin{verbatim}
- \instrumentnumber{4}
- \setname1{1st line} \setname2{2nd line} \setname3{3rd line} \setname4{4th line}
- \setlines1{4}\setlines2{4}\setlines3{4}\setlines4{4}
- \sepbarrules
- \generalmeter{\empty}
- \setclef1{1000} \setclef2{2000} \setclef3{3000} \setclef4{4000}
- \setaltoclefsymbol1\gregorianCclef
- \setaltoclefsymbol2\gregorianCclef
- \setaltoclefsymbol3\gregorianCclef
- \setaltoclefsymbol4\gregorianCclef
-\startextract
-\Notes\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\enotes
+which was coded as:
+\begin{quote}
+\begin{verbatim}
+% define lyrics above the staff
+\setlyrics{soprano}{bring her die Gans,}
+% lyric beneath the staff are the same
+\copylyrics{soprano}{alto}
+% assign alto lyrics below staff 1 on the notes with stem down
+\assignlyrics1{alto}
+% assign soprano lyrics above staff 1 on the notes with stem up
+\auxlyr{\assignlyrics1{soprano}}
+% attach both lyrics to the upper voice
+\lyrmodealter0
+\generalsignature{-2}
+% make place for the lyrics
+\advance\stafftopmarg1\Interligne\advance\staffbotmarg2\Interligne
+\startextract\addspace\afterruleskip
+\NOtes\zqu g\ql e\en\bar
+% start melisma in lower lyrics
+\Notes\zqu i\beginmel\ibslurd0f\ibl0f{-1}\qb0{fe}\en
+% start melisma in upper lyrics
+\Notes\auxlyr\beginmel\ibsluru1i\zqup i\qb0d\tqb0e\en
+% end melisma in lower lyrics
+\Notes\endmel\tbslurd0e\ql c\en
+\notes\ibbu0h{-1}\qb0h\tqh0g\en
+% start melisma in upper lyrics
+\NOtes\auxlyr\endmel\tbsluru1h\zqu h\ql c\en\bar
+% The lyrics of the whole notes (without stem) must be given manually.
+\NOTEs\auxlyr\lyr\zwh i\lyr\wh b\en
 \endextract
- \end{verbatim}
-
-
- \subsection{Music score without clefs or with special clefs}
-
- \subsubsection{Empty clefs}
-\index{clefs (empty)}
- Regardless of the number of lines of the staffs, an instrument may
-have no clefs, e.g.~for \itxem{percussion music} but also for any weird
-purpose. This is done by declaring the following item:
-
-\keyindex{setclefsymbol}~$n$\verb|\empty|
-
-\noindent Normal symbols for these clefs can be restored by:
-
-\keyindex{resetclefsymbols}
-
- \subsubsection{Octave clefs}\index{octave clefs}
- 
- Octave treble clefs and octave bass clefs are provided. They can replace the usual
- treble and bass clefs by saying:
-
- \keyindex{setclefsymbol}~$n$\keyindex{bassoct}
+\lyrmodenormal0
+\end{verbatim}\end{quote}
 
- \keyindex{setclefsymbol}~$n$\keyindex{trebleoct}
+  \subsection{Getting enough vertical space for lyrics}
+  Since songs are
+usually equivalent to a one-staff instrument (possibly with several voices)
+the recommended solution consists in adjusting the distance between
+instruments using either \keyindex{interinstrument}\verb|=|\ital{any
+\TeX-dimension} to give more place below all instruments or using
+\keyindex{setinterinstrument} to make more space above. Note that {\Bslash
+setinterinstrument} defines spacing above and not below an instrument. Since
+lyrics are usually set below the staff, the first argument of a
+\verb|\setinterinstrument| should be the song instrument number \ital{minus
+one}.
 
- \noindent for upper octaviation, and
+ In the case of a single staff tune, or if the song instrument is the lowest
+one, then additional place can be provided using \keyindex{staffbotmarg}.
 
- \keyindex{setclefsymbol}~$n$\keyindex{basslowoct}
+\subsection{Fine tuning the placement of the lyrics}
+ When not using \verb|\hardlyrics|, on short notes, sometimes
+ the lyrics are shifted away from the notes or they collide with other words.
+ This are a few approaches to get around this:
+\begin{enumerate}\setlength{\itemsep}{0ex}
+\item Making more music lines for the notes to go further apart. This could be done with
+\verb|\mulooseness|.
+\item Stretch a bar with short notes in it by i.e.\ replacing \verb|\notes| by \verb|\NOTes|.
+\item Insert space between the notes by using \verb|\sk|, \verb|\hsk|, \verb|\qsk|...
+\item Stretch a bar with short notes in it by using the command \keyindex{scale}:
+\begin{verbatim}
+\scale{1.6}\notes..\en\scale{1}%
+\end{verbatim}
+This method can be used in \textbf{PMX} but only with care, because it changes horizontal spacing
+in a way that \textbf{PMX} will not be aware of. It will not move bars to the next line, but
+will shorten the other bars on the line.
 
- \keyindex{setclefsymbol}~$n$\keyindex{treblelowoct}
+As an example, the lyrics of this music line are better placed by using \verb|\scale| in
+the first bar and moving to the left the word 'mon'. Note that the hyphen is removed
+when there is no place for it:
 
- \noindent for lower octaviation.
+ \begin{music}
+ \input musixlyr
+ \resetlyrics
+ \setlyrics{v1}{Au clair de la lu-ne, mon a-mi Pier-rot,}%
+ \assignlyrics1{}\assignlyrics1{v1}%
+ \staffbotmarg2\Interligne\generalsignature{1}%
+ \startextract
+ \geometricskipscale
+ \notes\qu{gggh}\en\bar
+ \Notes\hu{ih}\en\bar
+ \notes\qu{gihh}\en\bar
+ \Notes\wh g\en
+ \endextract
+% \end{music}
+%%%%% combined for saving registers %%%%%
+% \begin{music}\nostartrule
+% \input musixlyr
+ \resetlyrics
+ \setlyrics{v1}{Au clair de la lu-ne, \kernm1exmon a-mi Pier-rot,}%
+ \assignlyrics1{}\assignlyrics1{v1}%
+ \staffbotmarg2\Interligne\generalsignature{1}%
+ \startextract \geometricskipscale
+ \scale{1.4}\notes\qu{gggh}\en\bar\scale{1}%
+ \Notes\hu{ih}\en\bar
+ \notes\qu{gihh}\en\bar
+ \Notes\wh g\en
+ \endextract
+ \end{music}
 
+\medskip
+The code of the second music line is (\verb|\assignlyrics1{}| is only needed because
+lyrics are assigned before this in this manual):
+\begin{quote}\begin{verbatim}
  \begin{music}
- \parindent 19mm
- \instrumentnumber{4}
- \generalmeter{\empty}
- \setclef1\bass \setclef2\bass \setclef3\treble \setclef4\treble
- \setbassclefsymbol1\basslowoct
- \setbassclefsymbol2\bassoct
- \settrebleclefsymbol3\treblelowoct
- \settrebleclefsymbol4\trebleoct
+ \input musixlyr
+ \resetlyrics
+ \setlyrics{v1}{Au clair de la lu-ne, \kernm1exmon a-mi Pier-rot,}%
+ \assignlyrics1{}\assignlyrics1{v1}%
+ \staffbotmarg2\Interligne\generalsignature{1}%
+ \startextract \geometricskipscale
+ \scale{1.4}\notes\qu{gggh}\en\bar\scale{1}%
+ \Notes\hu{ih}\en\bar
+ \notes\qu{gihh}\en\bar
+ \Notes\wh g\en
+ \endextract
+ \end{music}
+\end{verbatim}\end{quote}
+
+\item Moving a word in any direction
+
+\noindent\begin{tabular}{ll}
+\multicolumn{2}{l}{\Bslash setlyrics\{alto\}\{\Bslash kernm3ex1.$\sim\sim$firstsyllable...\}}\\
+& left moving for numbering verses\\
+\verb|\setlyrics{alto}{...\kern1exword...}| &right moving a single word\\
+\verb|\setlyrics{alto}{...\lower2pt\hbox{word}...}|& lowering a single word\\
+\verb|\setlyrics{alto}{...\raise2pt\hbox{word}...}|& raising a single word\\
+\multicolumn{2}{l}{\Bslash def\Bslash strut\{\Bslash vbox to 2\Bslash Interligne\{\}\}%
+\Bslash setlyrics\{alto\}\{\Bslash lyrlayout\{\Bslash strut\}...\}} \\
+& controlling distance between verses\\
+\verb|\lyrlayout{\vphantom{Mp(\lowlyrlink}|& minimum distance between verses\\
+\multicolumn{2}{l}{\Bslash setbox\Bslash lyrstrutbox=\Bslash hbox\{\Bslash vphantom\{yM\Bslash lyrlink\}\}}\\
+& redefining default lyrstrut
+\end{tabular}
+
+\item Placing of accents can be made easier as shows this example:
+\begin{center}
+\begin{minipage}{50mm}
+\begin{music}\nostartrule
+\input musixlyr
+\catcode`\ä\active \defä{\"a}
+\catcode`\ö\active \defö{\"o}
+\catcode`\å\active \letå\aa
+\setlyrics1{å ä ö}
+\assignlyrics1{}\assignlyrics11
 \startextract
-\Notes\qu{`abcdefghi}&\qu{`abcdefghi}&\qu{abcdefghi}&\qu{abcdefghi}&\enotes
-\endextract
+ \setsongraise1{1ex}\NOtes\qa{ggg}\en
+\zendextract
 \end{music}
+\end{minipage}%
+\begin{minipage}{80mm}
+\verb|\catcode`\|\"a\verb|\active \def|\"a\verb|{\"a}|\\
+\verb|\catcode`\|\"o\verb|\active \def|\"o\verb|{\"o}|\\
+\verb|\catcode`\|\aa\verb|\active \let|\aa\verb|\aa|\\
+\verb|\setlyrics1{|\aa\ \"a\ \"o\verb|} \assignlyrics1{}|\\
+\verb|\assignlyrics11|\\
+\verb|\startextract|\\
+\verb|\NOtes\qa{ggg}\en|\\
+\verb|\zendextract|\\
+\end{minipage}
+\end{center}
+\item Using an 8-bit encoded characterset\label{8bit}
 
-{\noindent\sl REMARKS: \begin{itemize} \item The \keyindex{setclefsymbol},
-\keyindex{settrebleclefsymbol}, \keyindex{setaltoclefsymbol} and
-\keyindex{setbassclefsymbol} commands only change the symbol posted, not the
-altitude of the note head. Thus, if you say \verb|\setclef1\bass| and then
-|\setbassclefsymbol1\trebleclef|, your score will be definitely wrong. In the
-same way, \keyindex{trebleoct} and similar octave clefs will only change the
-symbol, but a note coded {\tt a} wiull have the same vertical position,
-regardless of the clef symbol chosen.
- \item Changing clef symbols also affect clef changes within the score, but
-this clef changes will be posted by large symbols, not smaller clefs as usual.
-Anyway, it can be remarked that clef changes only concern scores with standard
-treble, alto and bass clefs... 
-\end{itemize}
-}
-
- \subsubsection{Drum clef}
- A special \itxem{drum clef} (two heavy vertical bars) can
-replace for the $n$-th intrument any of the standard clefs by saying:
-
-\keyindex{setclefsymbol}~$n$\keyindex{drumclef}\label{sectiondrum}
+This can be achieved
+by putting
+\verb+\input plainenc\relax\inputencoding{cp850}+
+at the beginning of the file.
 
-\noindent However, since the vertical position of the clef depends on the
-previously stated clef, it is not wise to replace any clef symbol with the
-drum clef, but to have the instrument previously configured with the default
-violin clef, i.e. \verb|{0000}|.
+Here you must adapt the character
+set to your region.
+To do this, if necessary, replace \verb+cp850+ by
+\verb+cp1250+ (Czech, Croation region),
+\verb+cp1251+ (Russian, Bulgarian region),
+\verb+cp1252+ (most other European regions),
+\verb+cp1253+ (Greek region)
+or check your \TeX distribution for the right file.
 
- It is to be emphasised that these features are specific to one
-instrument --- not one staff of a several staff instrument --- so that some
-weird score for \ital{monks}, \ital{drum} and \ital{electronic keyboard}
-such as
+This is the coding for the previous example by using an 8-bit characterset:
 
-\begin{music}
-\parindent 19mm
-\instrumentnumber{3}
-\setname1{keyboard} \setname2{drum} \setname3{monks}
-\setlines2{1}
-\setlines3{4}
-\setinterinstrument1{-2\Interligne}% less vertical space above
-\setinterinstrument2{-2\Interligne}% and below the percussion
-\sepbarrules
-\setsign1{-1} % one flat at keyboard
-\generalmeter{\meterfrac24}
-\setmeter3\empty
-\setclef3\alto
-\setclef1\bass
-\setstaffs12 % 2 staffs at keyboard
-\setclefsymbol3\gregorianCclef % gregorian C clef at instrument 3
-\setclefsymbol2\drumclef       % cancel G clef at instrument 2
-\startextract
-\Notes\hu F|\zh c\hu h&\dnq4&\squ{acd}\enotes\bar
-\NOtes\qu I|\zq N\qu d&\qp&\diapunc f\enotes
-\NOtes\qu J|\zq a\qu e&\ynq4&\diapunc e\enotes\bar
-\notes\hu G|\zh b\hu d&\dnq4&\zsqu d\rsqu g\squ{hgh}\enotes
-\endextract
+\begin{center}
+\begin{minipage}{25mm}
+\begin{music}\nostartrule
+% this manual is in latex, the 8bit is taken by
+% \usepackage[ansinew]{inputenc}
+%
+%\input plainenc\relax\inputencoding{cp850}
+\input musixtex
+\input musixlyr
+\setlyrics1{á ä ö}\assignlyrics1{}\assignlyrics11%
+\startextract%
+\znotes\zcharnote{12}{Poème naïf}\en%
+\Notes\qa{ggg}\en%
+\zendextract%
 \end{music}
-\noindent could be coded as follows, regardless this is relevant (see remark
-in \ref{gregoriancappella}, p. \pageref{gregoriancappella}):
-\begin{verbatim}
-\parindent 19mm
-\instrumentnumber{3}
-\setname1{keyboard} \setname2{drum} \setname3{monks}
-\setlines2{1}
-\setlines3{4}
-\setinterinstrument1{-2\Interligne}% less vertical space above
-\setinterinstrument2{-2\Interligne}% and below the percussion
-\sepbarrules
-\setsign1{-1} % one flat at keyboard
-\generalmeter{\meterfrac24}
-\setmeter3{\empty}
-\setclef3{\alto}
-\setclef1{\bass}
-\setstaffs1{2} % 2 staffs at keyboard
-\setclefsymbol3{\gregorianCclef} % gregorian C clef at instrument 3
-\setclefsymbol2{\drumclef}       % cancel G clef at instrument 2
-\startextract
-\Notes\hu F|\zh c\hu h&\dnq4&\squ{acd}\enotes\bar
-\NOtes\qu I|\zq N\qu d&\qp&\diapunc f\enotes
-\NOtes\qu J|\zq a\qu e&\ynq4&\diapunc f\enotes\bar
-\notes\hu G|\zh b\hu d&\dnq4&\zsqu d\rsqu g\squ{hgh}\enotes
-\end{verbatim}
-In the same way, a possible violin score with \itxem{harmonic notes} (see
-\ref{othernotes}) could be:\label{abnormalscores}
+\end{minipage}
+~~~~~~
+\begin{minipage}{100mm}% program to run apart from musixdoc
+\verb+\input plainenc\relax\inputencoding{cp850}+\\
+\verb+\input musixtex+\\
+\verb+\input musixlyr+\\
+\verb+\startpiece%+\\
+\verb+\znotes\zcharnote{16}{Poème naïf}\en%+\\
+\verb+\setlyrics1{á ä ö}\assignlyrics11%+\\
+\verb+\Notes\qa{ggg}\en%+\\
+\verb+\Endpiece\vfill\eject \bye+
+\end{minipage}
+\end{center}
 
-\begin{music}
-\parindent0pt
-\generalsignature{-2}
-\generalmeter\allabreve
-\startextract
-\NOTes\dzq o\zh d\hu h\enotes
-\Notes\ibu0k0\zq g\yqb0k\qb0j\zq e\yqb0i\tbu0\qb0j\enotes
-\bar
-\NOTes\dzq g\hu k\enotes
-\NOTes\hpause\enotes
-\bar
-\NOTes\dzq o\zh d\hl h\enotes
-\Notes\ibl0e0\zq g\yqb0k\qb0j\zq e\yqb0i\tbl0\qb0j\enotes
-\bar
-\NOTes\dzq g\hu k\enotes
-\NOTes\hpause\enotes
-\endextract
-\end{music}
-It was coded as follows:
+\end{enumerate}
+
+\section{Embedding musical excerpts in text documents}
+
+Here we discuss the options for including music in text documents. The first
+decision is whether or not to use \LaTeX\footnote{We'll assume a user wanting
+to embed a musical excerpt in a \LaTeX\ document is already familiar with the
+fundamentals of \LaTeX. For more information about it, see for example the manual
+\ital{\LaTeX: A Document Preparation System} by Leslie {\sc Lamport}}.
+Because \LaTeX\ so effectively simplifies
+production of text-based \TeX\ documents, most users take that path, and most of the
+descriptions given here will assume that's the case\footnote{Please do not be confused;
+while \LaTeX\ is recommended for text-based documents containing musical
+exceprts, its use is definitely discouraged for ordinary self-contained musical scores
+of any sort.}.
+
+If for some reason you choose not to use \LaTeX\ to emplace musical excerpts,
+the basic approach is simply to set off the musical
+parts between \verb|\startpiece| or \verb|\contpiece| and \verb|\stoppiece| or
+\verb|\endpiece|, or between \verb|\startextract| and \verb|\zendextract|. But
+some details in what follows will also apply with no \LaTeX.
+
+There are two basic approaches to embedding musical excerpts in \LaTeX\
+documents. The first method is to directly include the \musixtex\ code in
+the \LaTeX\ source file. That will be the subject of the next subsection. The
+other is to create an EPS (encapsulated Postscript) file containing only the
+excerpt, and then ``paste'' it into the \LaTeX\ file. That will be covered in
+subsection \ref{embedeps}.
+
+The advantages of using the direct method are that all of the source code for
+all excerpts can be kept in the same file as the text, and that there is no
+limit on the length of the excerpt.
+The advantage of the EPS method is that you don't have to burden the \LaTeX\
+source with any of the \musixtex\ paraphernalia. That in turn permits use of
+primitive versions of the \TeX\ compiler that may not have the capacity
+to handle the direct method (due to the number of registers consumed by \LaTeX\
+and \musixtex). The disadvantages are that you must create and keep
+track of a separate \TeX\ and EPS file for every excerpt, and that the excerpt
+must not span any page breaks. On balance, the
+direct method is probably to be preferred.
+
+\subsection{Directly embedding excerpts in \LaTeX\ documents}\label{excerpts}
+
+To use the direct method, you should include ``\verb|musixtex|'' as one of the
+arguments of the \keyindex{documentstyle} command. This will cause the file
+\ttxem{musixtex.sty} to be loaded, so naturally you must make that file
+available in a place where \TeX\ can find it. That file simply inputs two
+other files, \verb|musixtex.tex| and \ttxem{musixltx.tex}, which again must
+obviously be available to \TeX.
+
+Now you are in position to directly embed an excerpt by inserting code at the
+appropriate place in the source file. The most common type of excerpt is
+one that occupies less than a full line and is to be horizontally centered. In
+that case, the extract should begin with the command \keyindex{begin\LBR music\RBR},
+followed by any preliminary commands. Then, instead of \verb|\startpiece|,
+use \keyindex{startextract}. Now comes the normal \musixtex\ coding. Finally,
+end the extract with \keyindex{endextract} instead of \verb|\endpiece|
+or \verb|\stoppiece|, followed by \keyindex{end\LBR music\RBR}.
+
+To terminate an extract without any bar line, use \keyindex{zendextract}
+instead of \verb|\zendextract|.
+
+To create a left-justified excerpt, use the sequence
+\keyindex{let\Bslash extractline\Bslash leftline}.
+
+If several extracts are to be placed on the same line, you can
+redefine \keyindex{extractline} as demonstrated in the following
+example\footnote{The macro {\tt\Bslash extractline} is defined once and for all in
+{\tt musixtex.tex} as {\tt\Bslash centerline}. You might think that the suggested
+coding would permanently redefine {\tt\Bslash extractline}, thereby upsetting the
+normal function of {\tt\Bslash startextract ... \Bslash endextract} for subsequent use.
+But it doesn't, because any actions within
+\keyindex{begin\LBR music\RBR}...\keyindex{end\LBR music\RBR} are local, not
+global.}:
+
+% DAS temp (where is the reference???)
+%An example of this is given at \ref{extractline} on page \pageref{extractline}.
+% end DAS temp
 \begin{quote}\begin{verbatim}
-\generalsignature{-2}
-\generalmeter\allabreve
-\startextract
-\NOTes\dzq o\zh d\hu h\enotes
-\Notes\ibu0k0\zq g\yqb0k\qb0j\zq e\yqb0i\tbu0\qb0j\enotes
-\bar
-\NOTes\dzq g\hu k\enotes
-\NOTes\hpause\enotes
-\bar
-\NOTes\dzq o\zh d\hl h\enotes
-\Notes\ibl0e0\zq g\yqb0k\qb0j\zq e\yqb0i\tbl0\qb0j\enotes
-\bar
-\NOTes\dzq g\hu k\enotes
-\NOTes\hpause\enotes
-\endextract
+\begin{music}\nostartrule
+\let\extractline\hbox
+\hbox to \hsize{%
+\hss\startextract ... \zendextract\hss%
+\hss\startextract ... \zendextract\hss}
+\end{music}
 \end{verbatim}\end{quote}
 
- \subsection{Usual percussion music}
-Besides single percussion scores usually
-written using one-line staffs, percussion music involving several instruments
-is often writen on five-line staffs with a \ital{drum clef}, where the
-instruments are distinguished by the type of the note heads and the apparent
-pitch of the note on the staff. We give an example --- kindly provided by
-Agusti {\sc Mart\'in Domingo}:
-
-\medskip
-\begin{music}
-\generalmeter{\meterfrac44}
-\setclefsymbol1\drumclef
-\parindent0pt\startpiece
-\leftrepeat
-\Notes\zql f\rlap\soupir\ibu0m0\xqb0{nn}\enotes
-\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
-\Notes\zql f\rlap\soupir\ibu0m0\xqb0{nn}\enotes
-\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
-\bar
-\Notes\zql f\rlap\soupir\ibu0m0\kqb0{nn}\enotes
-\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
-\Notes\zql f\rlap\soupir\ibu0m0\kqb0{nn}\enotes
-\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
-\bar
-\Notes\zql f\rlap\soupir\ibu0m0\oxqb0{nn}\enotes
-\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
-\Notes\zql f\rlap\soupir\ibu0m0\oxqb0{nn}\enotes
-\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
-\setrightrepeat\endpiece
-\end{music}
- Its coding was:
- \begin{quote}\begin{verbatim}
-\begin{music}
-\instrumentnumber{1}
-\generalmeter{\meterfrac44}
-\setclefsymbol1\drumclef
-\parindent0pt\startpiece
-\leftrepeat
-\Notes\zql f\rlap\soupir\ibu0m0\xqb0{nn}\enotes
-\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
-\Notes\zql f\rlap\soupir\ibu0m0\xqb0{nn}\enotes
-\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
-\bar
-\Notes\zql f\rlap\soupir\ibu0m0\kqb0{nn}\enotes
-\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
-\Notes\zql f\rlap\soupir\ibu0m0\kqb0{nn}\enotes
-\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
-\bar
-\Notes\zql f\rlap\soupir\ibu0m0\oxqb0{nn}\enotes
-\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
-\Notes\zql f\rlap\soupir\ibu0m0\oxqb0{nn}\enotes
-\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
-\setrightrepeat\endpiece
-\end{music}
- \end{verbatim}\end{quote}
- To use these different note heads, one must
- \begin{itemize}
- \item either include a specific percussion file namely\index{percussion
-music} \ttxem{musixper.tex} after the usual \verb|\input musixtex|;
- \item use special macro names to replace the usual elliptic black note head
-with other available note heads. Today only the most used note types are
-supported.
- \end{itemize}
+An even shorter type of extract is one that is embedded \ital{within} a line of text.
+To insert \musixtex\ symbols within a line of text, you could begin by defining
+\keyindex{notesintext} as follows\footnote{provided by Rainer {\sc Dunker}}:
 
+\begin{quote}\begin{verbatim}\begin{music}\nostartrule
+\makeatletter
+\def\notesintext#1{%
+  {\let\extractline\relax
+   \setlines10\smallmusicsize \nobarnumbers \nostartrule
+   \staffbotmarg0pt \setclefsymbol1\empty \global\clef@skip0pt
+   \startextract\addspace{-\afterruleskip}#1\zendextract}}
+\makeatother
+\end{music}\end{verbatim}\end{quote}
 
-\section{Writing your own macros: the {\Bslash catcode} problems}
-As seen before, the \keyindex{catcodes} of the \| and \verb|&| symbols
-are modified by \musixtex, in the range of the actual scores but not
-in the whole of the \TeX\ source.
-Thus, if you define your own macros to make
-your writing easier, you are likely to invoke the \| or \verb|&|
-symbols in a part of text where their \keyindex{catcode}s are not correctly set.
-\index{"|@{\tt\char'174}}
-This may result typically in a diagnostic like:
-
-\verb|! Misplaced alignment tab character &.|
-
-\noindent when you attempt, not to define, but to use your macro using the
-\verb|&| symbol to change the instrument. Smart \TeX ers know that the
-\keyindex{catcode}s are attached to the characters \ital{when they are input}
-and not when they are used; thus you must be sure that \| and \verb|&|
-have the correct \musixtex\ \keyindex{catcode} when the macro is defined,
-which may well occur outside the actual score.
-
-It is also worth pointing out that the same problem may occur with other
-punctuation marks like ``\verb|<|'', ``\verb|>|'', ``\verb|^|,
-etc., if their \keyindex{catcode} has been changed by some other set of
-macros, like \ttxem{french.sty}.
-
-\section{\LaTeX~and \musixtex}
- \subsection{The {\tt musixtex.sty} style}\label{musixltx}
- As said before, the amount of memory and registers used by \musixtex\ makes
-it hardly compatible with \LaTeX. However, Nicolas {\sc
-Brouard}\index{Brouard, N.@{\sc Brouard, N.}} succeeded in building a
-\ttxem{musixltx.tex} which is now included in the distribution. This is
-not recommended to make separate music scores. Its purpose is rather to
-provide a means of inserting short musical excerpts in books or articles
-written with \LaTeX. Then, the \keyindex{documentstyle} command should
-include {\tt musixtex} in the options.
-
-The \LaTeX\ \index{LaTeX@\LaTeX}style file \ttxem{musixtex.sty}
-simply \verb|\input|s the following files (in that very order):
-\begin{itemize}
- \item \verb|musixtex.tex|
- \item \verb|musixltx.tex|
-\end{itemize}
- In case of \verb|TeX capacity exceeded...|, use a ``Bigla\TeX'' (after
-checking there is no visible error in the source
-code).\index{BigLaTeX@Big\LaTeX}
- \subsection{Wide music in \LaTeX}\label{musixblx}
- Another difficulty appears with \LaTeX: internal \LaTeX\ macros handle the
-page size in a way which is not supposed to be changed within a given document.
-This means that text horizontal and vertical sizes are somewhat frozen so that
-one can hardly insert pieces of music of page size different from the size
-specified by the \LaTeX{} \itxem{style}.
-Although a \ttxem{musixblx.tex} has been provided, which makes the
-\ital{environment} \verb|bigmusic| available.
-\zkeyindex{begin\LBR bigmusic\RBR}
-The main drawback is an unpredictable behaviour of top and bottom
-printouts, especially page numberings.
-
- If the whole of a document has wide pages, it can be handled with the
-\ttxem{a4wide} style option, or any derivate of it.
- \subsection{The {\Bslash catcode} problems}
- The \verb|musixltx.tex| file merely overrides the \keyindex{catcode}s of the
-\| and \verb|&| symbols which are modified by \musixtex. To have access to
-these symbols when coding music, you should enclose the scores or excerpts
-within \verb|\begin{music}| and \verb|\end{music}|. But there is also another
-possibility, i.e.\ to say \keyindex{nextinstrument} instead of
-\verb|&|\index{\&} and \keyindex{nextstaff} instead of \|.
-\index{"|@{\tt\char'174}}
-
- Another problem comes from the {\tt\ixem{french.sty}} written by Bernard
-{\sc Gaulle}\index{Gaulle, B.@{\sc Gaulle, B.}} which is the standard of the
-\ixem{GUTenberg} French association. This style changes many
-\keyindex{catcode}s which lead \musixtex\ to fail in many cases. Therefore
-the \keyindex{catcode}s of all are forced to the adequate value at
-\keyindex{startpiece}, \keyindex{startextract} and restored at their original
-value at \keyindex{endpiece}, \keyindex{stoppiece} and \keyindex{endextract}.
-This means that some facilities like the \itxem{guillemets} or the
-\itxem{tabulation} character are inhibited within music scores (possible
-problem with sophisticated \itxem{lyrics}) but perfectly available within the
-normal text.
-
- Anyway, in case of emergency, one can invoke \keyindex{catcodesmusic} to
-establish the \keyindex{catcode}s at their value fit for music, and
-\keyindex{endcatcodesmusic} to reset them at their external value, for example
-those chosen by \verb|french.sty|.
-
-\section{Implementation and restrictions}
-
- The macroinstruction file \musixtex\ contains approximately 4200 lines of
-code, that is 98~000 bytes approximately. This requires your score to be
-compiled by the most extended versions of \TeX\ (65~000 words of working
-memory). It is therefore wise to say \verb|\tracingsstats=2| in
-order to have an information about the memory used in each page. In desperate
-situations, we recommend using the ``Big\TeX'' processors which,
-unfortunately, performed a great deal of disk input/outputs (on PCs with i286
-processors) which made them awfully slow. Of course, using i386 or i486 or Pentium
-processors, this problem disappears with the specific version of
-{\tt emTeX}, namely {\tt tex386}.\index{BigTeX@Big\TeX}\index{emTeX@em\TeX}
-
-In particular, the number of registers it uses and the amount of memory used
-by \LaTeX\ macros makes it doubtfully compatible with \LaTeX, unless using
-Big\LaTeX.\index{BigLaTeX@Big\LaTeX}
-
-Other precautions are necessary: beware of end-of-line spaces; they corrupt
-layout and cause {\tt underfull/overfull hbox} warnings during third pass.
-To avoid that, it is recommended
-to use \verb|%| at the end of source lines.
-
-
-%\subsection{ABC2MTeX}
-% Generally: yes
-%\subsection{MIDI2TeX}
-% s.a.a. (I already use a modified one, Thanx to C)
-%\subsection{SceX}
-% next time
-
-\section{From \musictex~to \musixtex: {\tt musixcpt}}
-\label{compatibility}
-
-This file is intended to run `{\bf old}' input files with as less changes
-(read \verb|musicdoc| {\bf and} \musixtex's laws~!) as possible. It slows
-down the speed and makes it impossible to use some\footnote{This was the will
-of one of the authors (A.E.) but we (we=D.T.) are now tending to remove any
-incompatibilities of {\tt musixcpt} with plain \musixtex.} of \musixtex\
-commands.
-
- To run \musictex\ examples --- not withstanding restrictions related to
-glue and ``hard'' spacings forbidden with
-\musixtex\ --- just replace all previous \verb|\input music*| by:
-
- \verb|\input musixtex|
-
- \verb|\input musixcpt|
-
-\noindent and, optionally
-
- \verb|\input musixsty|
-
-\subsection{Compatibility restrictions}
-
-The \ttxem{musixcpt.tex} file holds up
-compatibility to \musictex's sources, but there are some restrictions, which
-are caused either by missing glue in \musixtex\ --- sometimes ugly, but
-generally harmless --- or by some hard spacings such as \verb|\hbox|es
-containing lyrics exceeding the \keyindex{noteskip} dimension, and resulting
-in ``overfull hbox[es]'' that is, notes and symbols outside the score limits,
-with the heavy vertical bar as a standard \TeX\ punishment.
-
-The easiest way to avoid this consists in ending systematically
-\ital{all}\footnote{ALL lines, not ``most of them''.} input
-lines between \keyindex{startpiece}...\keyindex{stoppiece}\footnote{or
-\keyindex{Stoppiece} or \keyindex{endpiece} or \keyindex{Endpiece}.}
-with a comment sign\footnote{For \TeX perts: every line
-which does not end with a command}, namely a ``\verb|%|''.
-
-\medskip Besides, one might want to have a unique source file to be compiled
-with both the \musictex\ format and the \musixtex\ format, and\footnote{This
-might be considered as an excessive requirement, but we (D.T.) think it is a
-good way of including \musixtex's new facilities...} taking advantage of some
-specific possibilities of \musixtex. The leads to a need of testing whether
-the source file is compiled with one format or the other. In fact this test is
-easy:\zkeyindex{mxversion}
-
-\verb|\ifx\mxversion\undefined|
-
-\ \ \ the specific \musictex\ code
-
-\verb|\else|
-
-\ \ \ the specific \musixtex\ code, taking advantage of new features
-
-\verb|\fi|
-
-\medskip Several examples are now included in \musictex's examples, for
-example {\tt pacifiqn.tex}. Of course this would fail if the user
-inadvertently decided to define the command {\Bslash mxversion} in his source
-text.
- %\check
+Then, for example, the code
 
-\subsection{Additional commands in {\tt musixcpt.tex}}
+\begin{verbatim}
+Use \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\rql1\qu2\en}}
+not \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\ql2\lqu1\en}}
+\end{verbatim}
 
-The tentative user looking in given examples might find commands not described
-in the \musixtex\ manual (this one). Most frequent are (in case of missing
-description, revert to \musictex's manual, namely {\tt musicdoc.tex}, {\tt
-musicdoc.dvi}, {\tt musicdoc.ps}, {musicdoc.lj}, etc.):
+\noindent would produce: ``Use \raisebox{0ex}[0ex][0ex]{\notesintext{\notes\rql1\qu2\en}} not
+\raisebox{0ex}[0ex][0ex]{\notesintext{\notes\ql2\lqu1\en}}~''.
+
+\noindent The \verb|\raisebox| voids the vertical space that is introduced by the notes.
+
+Finally, you may want to insert an extract containing more than one line
+of music. Once having mastered \musixtex, this is the easiest of all: Between
+\verb|\begin{music}\nostartrule| and \verb|\end{music}|, use \ital{exactly} the same
+coding you would to make an ordinary score.
+
+The best way to learn how to apply these methods is to study
+\verb|musixdoc.tex|, the source file for this document\footnote{Do note,
+however, that {\tt musixdoc.tex} includes {\tt musixdoc} but not {\tt musixtex}
+as an argument of {\tt\Bslash documentstyle}. The former performs the functions
+of the latter as well as numerous tasks peculiar to this particular document.}.
+
+%DAS I don't think this section is worth including.
+
+% \subsection{Wide music in \LaTeX}\label{musixblx}
+% Another difficulty appears with \LaTeX: internal \LaTeX\ macros handle the
+%page size in a way which is not supposed to be changed within a given document.
+%This means that text horizontal and vertical sizes are somewhat frozen so that
+%one can hardly insert pieces of music of page size different from the size
+%specified by the \LaTeX{} \itxem{style}.
+%Although a \ttxem{musixblx.tex} has been provided, which makes the
+%\ital{environment} \verb|bigmusic| available.
+%\zkeyindex{begin\LBR bigmusic\RBR}
+%The main drawback is an unpredictable behaviour of top and bottom
+%printouts, especially page numberings.
+%
+% If the whole of a document has wide pages, it can be handled with the
+%\ttxem{a4wide} style option, or any derivate of it.
+
+\subsection{Embedding musical excerpts as encapsulated postscript files}
+\label{embedeps}
+To use this method of including excerpts, you first must create a separate
+\musixtex\ input file for each excerpt. Process each such file with
+\TeX\ and \verb|musixflx| to generate a \verb|.dvi| file. Generate
+a postscript file from each \verb|.dvi| using \verb|dvips|. Then
+convert each postscript file to an \verb|.eps| file. One way to do that is
+with \textbf{ghostscript} and---if you are using Windows---\textbf{GSview}.
+In general this is possible only for single-page postScript files.
+
+To set up your \LaTeX\ document for including \verb|.eps| files, you must post
+the command \verb|\usepackage[dvips]{graphicx}| in the preamble of the
+document. Now, you may include each \texttt{.eps} file at the appropriate place
+in the {\LaTeX} document with a command
+like \keyindex{includegraphics}\verb|{sample.eps}|.
+
+\subsection{Issues concerning \texorpdfstring{{\Bslash catcodes}}{catcodes}}
+\label{catcodeprobs}
+
+\musixtex\ uses the following symbols differently from plain \TeX: \verb|>|,
+ \verb|<|, \verb&|&, \verb|&|, \verb|!|, \verb|*|, \verb|.|, and \verb|:|\ .\\
+The symbols are given their special meanings by executing the macro
+\keyindex{catcodesmusic}, and are restored to their plain \TeX\ meanings with
+\keyindex{endcatcodesmusic}. When setting either a self-contained score or
+a musical extract, you normally need not worry
+about this at all, because \verb|\startpiece| or \verb|\startextract| executes
+\verb|\catcodesmusic| and \verb|\endpiece| or \verb|\zendextract| executes
+\verb|\endcatcodesmusic|. But there are some special situations where you
+might need to use these catcode-modifying macros explicitly. One is if you
+were to define a personalized macro outside
+\verb|\startpiece ... \endpiece|, but which incorporated any of the
+symbols with their \musixtex\ meanings. Another would be if you wished to have
+access to facilities enabled by alternate style files such as
+{\tt\ixem{french.sty}} which change \keyindex{catcode}s themselves. In
+such cases, provided you have input \verb|musixtex.tex|, you can always
+invoke \keyindex{catcodesmusic} to set the \keyindex{catcode}s at their
+\musixtex\ values, and \keyindex{endcatcodesmusic} to restore them to their
+prior values.
 
-\begin{itemize}
- \item\keyindex{qh} : same as \verb|\qb|, but was different with \musictex,
-since it distinguished notes hanging above (\verb|\qb|) and below (\verb|\qh|)
-the beam(s).
- \item\keyindex{debutmorceau} : nearly but not exactly  the same as
-\verb|\startpiece|.
- \item\keyindex{suspmorceau} : suspends the score at the end of the line, in
-order to permit inserting ordinary \TeX\ commands. Similar to
-\keyindex{stoppiece} but performs line counting necessary then using
-\musictex's \verb|\autolines| feature.
- \item \keyindex{reprmorceau} is synonym of \verb|\contpiece|.
- \item \keyindex{lreprmorceau} is synonym of \verb|\contpiece|.
- \item \keyindex{preprmorceau} ejects a newpage and performs \verb|\contpiece|.
- \item \keyindex{finmorceau} is synonym of \verb|\Stoppiece|, i.e. with heavy
-ending double bar..
-
- \item\keyindex{barre} : same as \verb|\bar|.
- \item\keyindex{dsoupir} : same as \verb|\ds|.
- \item\keyindex{qsoupir} : same as \verb|\qs|.
- \item\keyindex{demisoupir} : same as \verb|\ds|.
- \item\keyindex{temps} : was glue in \musictex, now equivalent to
-\verb|\empty|.
- \item\keyindex{autolines} is fit for scores with
-bars of regular length: after \keyindex{startpiece}, you code the
-following macro:
-
-
-\medskip\Bslash autolines $tml$
-
-\medskip\noindent\rm where $t$ is the number of \ital{elementary spacings}
-(the length of {\Bslash notes...\Bslash enotes}) in an average bar, $m$ is the
-number of bars you wish in a line and $l$ is the number of lines you wish in a
-page. This sets some parameters, namely \keyindex{maxbarsinline} and
-\keyindex{maxlinesinpage} which are simply used to count the bars (counter is
-\keyindex{barsinline}), optionally perform \keyindex{alaligne} or
-\keyindex{alapage} (counter is \keyindex{linesinpage}) instead of the normal
-\verb|barre| or \verb|bar|. You may freely alter the values of these
-parameters, once they have been established by \keyindex{autolines}. Moreover,
-you can still force line-breaking of page ejection using {\Bslash alaligne} or
-\keyindex{alapage} without problem since these macros actually reset the bar
-counters appropriately.
+\section{Extension Library}
+All following files are invoked by saying \keyindex{input} \ital{filename}\ .
+Most of them are fully compatible with \musixtex\ in that they do not redefine
+any existing macros but rather provide additional functionality. In future
+versions of \musixtex\ we may very well incorporate many of them directly into
+\verb|musixtex.tex|, but for now we leave them separate.
 
- \end{itemize}
+ \subsection{curly}
+Allows you to group more than 1 instrument with curly
+brackets (see \ref{curlybrackets}).
 
- %\check
-% \subsection{Often reported problems}
+ \subsection{musixadd}\ixtt{musixadd.tex}
+Increases the number of instruments, slurs and beams from six to nine.
 
- %\check
-\section{Extension Library}
-All following files are invoked with saying \keyindex{input} \ital{filename}
- \subsection{musixadd}
-Increases the number of instruments, slurs and beams up to nine.
  \subsection{musixbm}
- Provides 128th notes, either with hooks or with beams, namely the
+ Provides 128th notes, either with flags or with beams, via the commands
 \keyindex{ibbbbbu},
 \keyindex{ibbbbbl},
 \keyindex{nbbbbbu},
@@ -6013,9 +6863,10 @@ Increases the number of instruments, slurs and beams up to nine.
 \keyindex{ccccca},
 \keyindex{zcccccu},
 \keyindex{cccccl} and
-\keyindex{zcccccl} commands.
+\keyindex{zcccccl}.
+
  \subsection{musixbbm}
- Provides 256th notes, only with beams, namely the
+ Provides 256th notes, only with beams, via the commands
 \keyindex{ibbbbbbu},
 \keyindex{ibbbbbbl},
 \keyindex{nbbbbbbu},
@@ -6023,20 +6874,28 @@ Increases the number of instruments, slurs and beams up to nine.
 \keyindex{tbbbbbbu},
 \keyindex{tbbbbbbl},
 \keyindex{Ibbbbbbu} and
-\keyindex{Ibbbbbbl} commands.
- \subsection{*musixcho}\label{song}
- These are some macros fit for chorus music. Provides following commands:
+\keyindex{Ibbbbbbl}.
+
+\subsection{musixcho}\label{song}
+ Enables certain macros intended for choral music\footnote{Remember
+that we now recommend using \texttt{musixlyr} for any except the
+simplest lyrics. The extension \texttt{musixcho} is only for those
+diehards who choose to ignore this advice}. Provides the following commands:
 \keyindex{biglbrace}, \keyindex{bigrbrace}, \keyindex{braceheight},
-\keyindex{Dtx} and \keyindex{Drtx} for double text, \keyindex{Ttx} and
-\keyindex{Trtx} for triple text, \keyindex{Qtx} and \keyindex{Qrtx} for
-quadruple text.
+\keyindex{Dtx} and \keyindex{Drtx} for two-line text, \keyindex{Ttx} and
+\keyindex{Trtx} for three-line text, \keyindex{Qtx} and \keyindex{Qrtx} for
+four-line text.  To eliminate zigzagging lyrics lines, all multiple line texts
+are automatically vertically justified with the macro \keyindex{ChroirStrut},
+defined as \verb|\vphantom{\^Wgjpqy}|.
 
-\keyindex{tx}\verb|{|$text$\verb|}|,
-\keyindex{rtx}\verb|{|$text$\verb|}| for text of songs, with text extending
-to right instead centered.
- \keyindex{hf}\verb|{|$m$\verb|}| sets  text
-continuation rule of width $m$ \verb|\noteskip|.
+The macros \keyindex{tx}\verb|{|$text$\verb|}|,
+\keyindex{rtx}\verb|{|$text$\verb|}| cause song text to be left-justified
+on the insertion point rather then centered.
+ \keyindex{hf}\verb|{|$m$\verb|}| sets a text
+continuation rule of length $m$ \verb|\noteskip|.
 
+Consult the source file {\tt musixdoc.tex} to see the coding of the following
+example:
 
 \begin{music}
 \tenrm
@@ -6097,19 +6956,21 @@ continuation rule of width $m$ \verb|\noteskip|.
 \endpiece
 \end{music}
 
- See {\tt musixdoc.tex} source to get the coding of this long example.
-
- Note that, since vertion T.89, multiple line texts are vertically justified
- with a \keyindex{ChroirStrut} macro defined as \verb|\vphantom{\^Wgjpqy}| to
-eliminate zigzagging lyrics lines.
-
- %\check
- \subsection{musixdat}
-Here is the command \keyindex{today} defined for several languages.
-The default is \keyindex{dateUSenglish}, but this can freely be changed at
-end of \ttxem{musixdat.tex}.
-Also available are \keyindex{dategerman}, \keyindex{dateaustrian},
-\keyindex{dateenglish} and \keyindex{datefrench}, which yields:
+\subsection{musixcpt}
+
+Empowers \musixtex\ to run files created under
+Musi\textbf{c}TeX, the predecessor of \musixtex, such as some of the examples
+provided by Dani\"el {\sc Taupin}. It is not needed for any files created
+under \musixtex, and is included mainly for historical completeness.
+
+\subsection{musixdat}
+Enables the command \keyindex{today}, which sets the current date in one of
+several possible languages. The language is selected by an optional
+ preparatory command \verb|\date...|.
+The default is \keyindex{dateUSenglish}, but this can changed, either at the
+end of \ttxem{musixdat.tex} for a permanant change, or right before issuing
+\verb|\today|. Available choices and sample results are summarized below:
+\smallskip
 \begin{quote}\begin{tabular}{ll}\hline
 \verb|\dateUSenglish|&\dateUSenglish\today\\
 \verb|\dateaustrian|&\dateaustrian\today\\
@@ -6117,40 +6978,89 @@ Also available are \keyindex{dategerman}, \keyindex{dateaustrian},
 \verb|\datefrench|&\datefrench\today\\
 \verb|\dategerman|&\dategerman\today\\\hline
 \end{tabular}\end{quote}
- \subsection{*musixdia}\label{diam}
-These file is automatically loaded, if you use {\tt musixper.tex}.
-Here is the list of notes it provides:
- \begin{itemize}
- \item The \raise.5ex\hbox to 1em{\musixchar37} symbol is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a ``\verb|y|''
-(think of ``dyamond''). Available are \keyindex{yqu}, \keyindex{yqup},
+
+\subsection{musixdbr}
+Enables dashed and dotted bar lines (see \ref{musixdbr}).
+
+\subsection{musixdia}\label{diam}
+Enables notes with diamond-shaped heads as follows:
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item Solid note heads (\raise.5ex\hbox to .6em{\musixchar37}) are obtained
+using the macros
+ \keyindex{yqu}, \keyindex{yqup},
 \keyindex{yqupp}, \keyindex{yql}, \keyindex{yqlp}, \keyindex{yqlpp},
 \keyindex{yzq}, \keyindex{yzqp}, \keyindex{yzqpp}, \keyindex{yqb},
 \keyindex{ycu}, \keyindex{yccu}, \keyindex{ycccu}, \keyindex{yccccu},
 \keyindex{ycl}, \keyindex{yccl}, \keyindex{ycccl}, \keyindex{yccccl},
-\keyindex{ycup}, \keyindex{ycupp}, \keyindex{yclp}, \keyindex{yclpp}. The
-symbol without a stem can be obtained by saying \keyindex{ynq} and the
-non-spacing variant with \keyindex{zynq}.
- \item The \raise.5ex\hbox to 1em{\musixchar38} symbol is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a ``\verb|d|''
-(think of \ital{diamond}). Available are \keyindex{dqu}, \keyindex{dqup},
+\keyindex{ycup}, \keyindex{ycupp}, \keyindex{yclp}, \keyindex{yclpp}.
+(Think of d{\it y}\kern.5pt amond). A solid diamond with no stem is obtained
+with \keyindex{ynq} (spacing) or \keyindex{yznq} (non-spacing).
+ \item Open note heads (\raise.5ex\hbox to .6em{\musixchar38}) are obtained
+using the macros
+\keyindex{dqu}, \keyindex{dqup},
 \keyindex{dqupp}, \keyindex{dql}, \keyindex{dqlp}, \keyindex{dqlpp},
 \keyindex{dzq}, \keyindex{dzqp}, \keyindex{dzqpp}, \keyindex{dqb},
 \keyindex{dcu}, \keyindex{dccu}, \keyindex{dcccu}, \keyindex{dccccu},
 \keyindex{dcl}, \keyindex{dccl}, \keyindex{dcccl}, \keyindex{dccccl},
-\keyindex{dcup}, \keyindex{dcupp}, \keyindex{dclp}, \keyindex{dclpp}. The
-symbol without a stem can be obtained by saying \keyindex{dnq} and the
-non-spacing variant with \keyindex{dznq}.
+\keyindex{dcup}, \keyindex{dcupp}, \keyindex{dclp}, \keyindex{dclpp}.
+(Think of {\it d}\kern.5pt iamond).
+An open diamond with no stem is obtained
+with \keyindex{dnq} (spacing) or \keyindex{dznq} (non-spacing).
  \end{itemize}
- %\check
- \subsection{*musixeng}
- This package is made for music typesetters who are allergic to rest names
-taken from French, German or Italian\footnote{By the way, note that a
-\ital{whole rest} is called \ital{pause} in French, \ital{ganze Pause} in
-German, and \ital{pausa} in Italian.}. It does not provide new features, only
-new command names.
+
+One use of these note heads is for a string part with \itxem{harmonic notes}.
+%(see \ref{othernotes})
+% DAS removed description which was misplaced in the samll=notes section 2.18 4/30/06
+For example,
+
+\begin{music}
+\parindent0pt
+\generalsignature{-2}
+\generalmeter\allabreve
+\startextract
+\NOTes\dzq o\zh d\hu h\enotes
+\Notes\ibu0k0\zq g\yqb0k\qb0j\zq e\yqb0i\tbu0\qb0j\enotes
+\bar
+\NOTes\dzq g\hu k\enotes
+\NOTes\hpause\enotes
+\bar
+\NOTes\dzq o\zh d\hl h\enotes
+\Notes\ibl0e0\zq g\yqb0k\qb0j\zq e\yqb0i\tbl0\qb0j\enotes
+\bar
+\NOTes\dzq g\hu k\enotes
+\NOTes\hpause\enotes
+\endextract
+\end{music}
+\noindent was coded as follows:
+\begin{quote}\begin{verbatim}
+\generalsignature{-2}
+\generalmeter\allabreve
+\startextract
+\NOTes\dzq o\zh d\hu h\enotes
+\Notes\ibu0k0\zq g\yqb0k\qb0j\zq e\yqb0i\tbu0\qb0j\enotes
+\bar
+\NOTes\dzq g\hu k\enotes
+\NOTes\hpause\enotes
+\bar
+\NOTes\dzq o\zh d\hl h\enotes
+\Notes\ibl0e0\zq g\yqb0k\qb0j\zq e\yqb0i\tbl0\qb0j\enotes
+\bar
+\NOTes\dzq g\hu k\enotes
+\NOTes\hpause\enotes
+\endextract
+\end{verbatim}\end{quote}
+
+Another use is for percussion parts. In fact the file \verb|musixdia.tex|
+is automatically loaded if you input {\tt musixper.tex} (see \ref{perc}).
+
+ \subsection{musixeng}
+ This package is provided for music typesetters who are allergic to the default
+rest names, which are
+taken from French, German or Italian. It does not provide new features, only
+new command names:
+\medskip
  \begin{quote}\begin{tabular}{ll}\hline
-\ital{original}&\ital{alternative}\\\hline
+\ital{original}&\ital{alternate}\\\hline
 \keyindex{PAUSe}&\keyindex{Qwr}\\
 \keyindex{PAuse}&\keyindex{Dwr}\\
 \keyindex{liftpause}&\keyindex{liftwr}\\
@@ -6165,153 +7075,204 @@ new command names.
 \keyindex{hs}&\keyindex{eeer}\\
 \keyindex{qqs}&\keyindex{eeeer}\\\hline
 \end{tabular}\end{quote}
- \subsection{musixext}
 
-\keyindex{slide}\verb|{|pitch\verb|}{|elements\verb|}{|slope[-8 to 8]\verb|}|~:
-  glissando.
+\subsection{musixext}
+Defines the following two specific macros:
 
-\keyindex{raggedstoppiece} :
-  provides a ragged last line.
-  %\check
+\keyindex{slide}\itbrace{p}\itbrace{x}\itbrace{s}~, which provides a glissando
+starting at pitch {\it p} and extending for {\it x} \verb|\internote|s with
+slope {\it s} (ranging from -8 to 8).
+
+\keyindex{raggedstoppiece}~, which inhibits right-justification of the last
+line of a score.
 
  \subsection{musixf{}l{}l}
  \input musixfll
- \ttxem{musixfll.tex} may be used to modify the automatic
-generation of \ixem{ledger lines}. Ledger lines --- German Hilfslinien
---- are generated for notes placed above or below normal staff lines. 
-Ledger lines normally exceed the note head by a quarter of the width of
-the note head. If notes are set very narrowly, the ledger lines of
-consecutive notes may meet. In this case a player may misread the
-ledger lines as normal lines. Therefore \musixtex{} shortens the
-ledger lines if notes are set so narrowly that the ledger lines may
-meet. Because \musixtex{} does not know whether consecutive notes need
-ledger lines, this automatic shortening may be superfluous. So this
-automatism may be switched off and on. After including
-\ttxem{musixfll.tex} the automatic shortening of ledger lines is
-switched off. Afterwards it may be switched on again using
+ Enables modification of \ixem{ledger lines}. Ledger lines normally exceed the
+width of a note head by 25 percent in each direction. If the space between
+notes is insufficient, the ledger lines of
+consecutive notes may meet, creating visual ambiguities. Therefore,
+\musixtex{} shortens the
+ledger lines if notes are set so close together that the ledger lines may
+meet. But because \musixtex{} does not know whether consecutive notes need
+ledger lines, this automatic shortening may be superfluous. The extension
+file \ttxem{musixfll.tex} allows this feature to be switched off and on.
+Upon inputting \verb|musixfll.tex|, the automatic shortening of ledger lines
+is switched off. From then on, it may be switched on again using
 \keyindex{autoledgerlines} and switched off again using
 \keyindex{longledgerlines}. Both macros have global effect.
 
  The following example shows that narrowly set scales look better with
-\keyindex{autoledgerlines}, while single notes requiring ledger lines
-look better with \keyindex{longledgerlines}.
-
+\keyindex{autoledgerlines} (the default behavior), while single notes
+requiring ledger lines look better with \keyindex{longledgerlines}.
+\medskip
 \begin{music}
 \startextract
 \notes\multnoteskip{0.7}\Uptext{autoledgerlines}\autoledgerlines
-	\ibbbu0b0\qb0{cba`gfg'a}\tbu0\qb0b%
-	\ibbbl0{''b}0\qb0{abcdedc}\tbl0\qb0b%
-	\ibbbu0{``b}0\qb0{dad}\tbu0\qb0a%
-	\ibbbl0{''b}0\qb0{`g'c`g}\tbl0\qb0{'c}\en
-	\bar
+    \ibbbu0b0\qb0{cba`gfg'a}\tbu0\qb0b%
+    \ibbbl0{''b}0\qb0{abcdedc}\tbl0\qb0b%
+    \ibbbu0{``b}0\qb0{dad}\tbu0\qb0a%
+    \ibbbl0{''b}0\qb0{`g'c`g}\tbl0\qb0{'c}\en
+    \bar
 \notes\multnoteskip{0.7}\Uptext{longledgerlines}\longledgerlines
-	\ibbbu0b0\qb0{cba`gfg'a}\tbu0\qb0b%
-	\ibbbl0{''b}0\qb0{abcdedc}\tbl0\qb0b%
-	\ibbbu0{``b}0\qb0{dad}\tbu0\qb0a%
-	\ibbbl0{''b}0\qb0{`g'c`g}\tbl0\qb0{'c}\en
+    \ibbbu0b0\qb0{cba`gfg'a}\tbu0\qb0b%
+    \ibbbl0{''b}0\qb0{abcdedc}\tbl0\qb0b%
+    \ibbbu0{``b}0\qb0{dad}\tbu0\qb0a%
+    \ibbbl0{''b}0\qb0{`g'c`g}\tbl0\qb0{'c}\en
 \endextract
 \autoledgerlines
 \end{music}
 
- \subsection{*musixgre}\label{gregnotes}
+ \subsection{musixgre}\label{gregnotes}\index{gregorian chant}
 
+% \subsection{Gregorian chant: staffs and clefs}
+Gregorian chant is often coded using four line staffs
+(see
+%sections \ref{gregorian} and
+section \ref{stafflinenumber}) and using special notes called
+\itxem{neumes} (which are described later in this section). It also requires
+special clefs. One way to substitute them for the modern ones is for example
+with commands like
 
- Provided that four line staffs (see \ref{stafflinenumber}) are used,
-\itxem{gregorian music} is frequently quoted using specific \itxem{neumes},
-established in the thirteenth century, and this way of coding has been
-commonly used for the coding of liturgical chant in the Catholic Church until
-the middle of the twentieth century. Nevertheless, gregorian chant coding is
-not really an antique feature, since it has been codified in 1905 with recent
-quasi-official updates in the eightties.
+\keyindex{setaltoclefsymbol}\verb|3\gregorianCclef|
 
+\noindent or
 
-{\noindent\sl REMARK:\label{gregoriancappella} strictly writing, including
-gregorian chant coding in \musixtex{} is a pure nonsense. Of course, many
-people find it interesting to have the possibility of coding gregorian neumes
-together with modern music, but having a score with both a gregorian chant and
-a choir or instruments is definitely \ital{heretic}. The reason is that
-grogorian chant must be sung \ital{a cappella}, without instrument and without
-underlying polyphony. As a matter of fact, serious music schools ceased to
-teach how to accompany gregorian chant approximately 20 years ago.
+\keyindex{setbassclefsymbol}\verb|3\gregorianFclef| ,
 
- However, there are still some pseudo-gregorian chants in the Catholic
-repertoire which deserve organ or orchestra accompaniment: these are latine
-speaking gregorian imitations composed in the eighteenth century, such as the
-famous \ital{Angel's mass} of the \ital{Messe royale de Du Mont} which were
-printed using gregorian neumes by official catholic publishers instead of
-using the music denotations fit for renaissance and baroque pieces...}
+\noindent which will cause instrument number 3 to display the selected gregorian
+clef. The standard clefs can be restored for every instrument with
+\keyindex{resetclefsymbols}. Note that when using this method you must
+specify whether to substitute for the bass or alto clef
+symbol (there is no treble clef in gregorian
+chant). The reason is that \musixtex\ selects and
+raises the F and C clefs differently, according to the arguments of the
+\keyindex{setclef} command. Therefore, if one had substituted any F clef
+symbol while saying \verb|\setclef1{1000}|, then an F clef would duly appear
+on the staff, but it would be set at the position of an alto clef, thus
+seriously misleading the musician.
 
+Another method of clef substitution employs \keyindex{setclefsymbol} (see
+section  \ref{treblelowoct}), which substitutes the clef given by
+the second argument \ital{for all clef symbols} of the instrument given by the first,
+regardless of the actual musical meaning of the new clef symbol. This method is
+generally appropriate only if you want to change the clef symbol(s) of
+an instrument for the whole of the score.
 
- Symbols available in \musixtex\ are
-mainly those of the 1905 standard, as provided by Beda {\sc
-Szukics}\index{Szukics, B.@{\sc Szukics, B.}}:
+ As an example, the same gregorian scale has been written with a gregorian C
+clef on all four lines of the staff:
 
-\subsubsection{The clefs}
+ \begin{music}\nostartrule
+ \parindent 19mm
+ \instrumentnumber{4}
+ \setname1{1st line} \setname2{2nd line} \setname3{3rd line} \setname4{4th line}
+ \setlines1{4}\setlines2{4}\setlines3{4}\setlines4{4}
+ \sepbarrules
+ \generalmeter{\empty}
+ \setclef1{1000} \setclef2{2000} \setclef3{3000} \setclef4{4000}
+ \setaltoclefsymbol1\gregorianCclef
+ \setaltoclefsymbol2\gregorianCclef
+ \setaltoclefsymbol3\gregorianCclef
+ \setaltoclefsymbol4\gregorianCclef
+\startextract
+\Notes\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\enotes
+\zendextract
+\end{music}
 
-\begin{itemize}
- \item The gregorian C clef: \raise 2.5pt\hbox to 1cm{\gregorianCclef\hfil}~=
+ The coding was:
+ \begin{verbatim}
+ \instrumentnumber{4}
+ \setname1{1st line} \setname2{2nd line} \setname3{3rd line} \setname4{4th line}
+ \setlines1{4}\setlines2{4}\setlines3{4}\setlines4{4}
+ \sepbarrules
+ \generalmeter{\empty}
+ \setclef1{1000} \setclef2{2000} \setclef3{3000} \setclef4{4000}
+ \setaltoclefsymbol1\gregorianCclef
+ \setaltoclefsymbol2\gregorianCclef
+ \setaltoclefsymbol3\gregorianCclef
+ \setaltoclefsymbol4\gregorianCclef
+\startextract
+\Notes\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\squ{abcdefghi}&\enotes
+\zendextract
+ \end{verbatim}
+
+All of the special gregorian symbols available in \musixtex\ are described
+in the following subsections.
+
+\subsubsection{Clefs}
+
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item Gregorian C clef: \raise 2.5pt\hbox to 1cm{\gregorianCclef\hfil}~=
  \keyindex{gregorianCclef}, normally activated for instrument $n$ with the
-command:
- \begin{quote}
- \keyindex{setaltoclefsymbol} $n$ \keyindex{gregorianCclef}
- \end{quote}
- \item The gregorian F clef:  \raise 2.5pt\hbox to 1cm{\gregorianFclef\hfil}~=
-\keyindex{gregorianFclef}, normally activated with the
-\verb|\setbassclefsymbol| command.
+command
+ \keyindex{setaltoclefsymbol}\itbrace{n}\keyindex{gregorianCclef}
+\item Gregorian F clef:  \raise 2.5pt\hbox to 1cm{\gregorianFclef\hfil}~=
+\keyindex{gregorianFclef}, normally activated with the command
+\keyindex{setbassclefsymbol}\itbrace{n}\keyindex{gregorianFclef}
  \end{itemize}
 
- \subsubsection{The basic elementary symbols}
- \begin{itemize}
+ \subsubsection{Elementary symbols}
+
 
- \item Diamond shaped \itxem{punctum} (of different shape compared to the
+ \begin{itemize}\setlength{\itemsep}{0ex}
+
+ \item Diamond shaped \itxem{punctum} (This has a different shape compared to the
 percussion diamond): \raise 2.5pt\hbox{\xgregchar1}~ =
-\keyindex{diapunc}~$p$~.
+\keyindex{diapunc}\pitchp\ .
  \item Square \itxem{punctum}: \raise 2.5pt\hbox{\xgregchar5}~ =
-\keyindex{squ}~$p$ or \keyindex{punctum}~$p$~.
+\keyindex{squ}\pitchp\ or \keyindex{punctum}\pitchp\ .
  \item Left stemmed \itxem{virga} (not in the 1905 gregorian standard): \raise
-2.5pt\hbox{\xgregchar6}~ = \keyindex{lsqu}~$p$~.
+2.5pt\hbox{\xgregchar6}~ = \keyindex{lsqu}\pitchp\ .
  \item Right stemmed \itxem{virga}: \raise 2.5pt\hbox{\xgregchar7}~ =
-\keyindex{rsqu}~$p$ or \keyindex{virga}~$p$~.
+\keyindex{rsqu}\pitchp\ or \keyindex{virga}\pitchp\ .
  \item \ital{Apostropha}\index{apostropha}: \raise 2.5pt\hbox{\xgregchar3}~ =
-\keyindex{apostropha}~$p$~.
+\keyindex{apostropha}\pitchp\ .
  \item \ital{Oriscus}\index{oriscus}: \raise 2.5pt\hbox{\xgregchar10}~ =
-\keyindex{oriscus}~$p$~.
+\keyindex{oriscus}\pitchp\ .
 
  \item \ital{Quilisma}\index{quilisma}: \raise 2.5pt\hbox{\xgregchar125}~ =
-\keyindex{quilisma}~$p$~.
- \item \ital{Punctum auctum} (up)\index{punctum auctum}: \raise 2.5pt\hbox{\xgregchar9}~ =
-\keyindex{punctumauctup}~$p$~.
- \item \ital{Punctum auctum} (down)\index{punctum auctum}: \raise 2.5pt\hbox{\xgregchar8}~ =
-\keyindex{punctumauctdown}~$p$~.
+\keyindex{quilisma}\pitchp\ .
+ \item \ital{Punctum auctum} (up)\index{punctum auctum}: \raise
+2.5pt\hbox{\xgregchar9}~ =
+\keyindex{punctumauctup}\pitchp\ .
+ \item \ital{Punctum auctum} (down)\index{punctum auctum}: \raise
+2.5pt\hbox{\xgregchar8}~ =
+\keyindex{punctumauctdown}\pitchp\ .
  \item Diamond shaped \ital{punctum auctum} (down)\index{punctum auctum}:
-\raise 2.5pt\hbox{\xgregchar2}~ = \keyindex{diapunctumauctdown}~$p$~.
+\raise 2.5pt\hbox{\xgregchar2}~ = \keyindex{diapunctumauctdown}\pitchp\ .
  \item \ital{Punctum deminutum}\index{punctum deminutum}: \raise
-2.5pt\hbox{\xgregchar4}~ = \keyindex{punctumdeminutum}~$p$~.
+2.5pt\hbox{\xgregchar4}~ = \keyindex{punctumdeminutum}\pitchp\ .
  \item \ital{Apostropha aucta}\index{apostropha aucta}: \raise
-2.5pt\hbox{\xgregchar11}~ = \keyindex{apostropha aucta}~$p$~.
-
+2.5pt\hbox{\xgregchar11}~ = \keyindex{apostropha aucta}\pitchp\ .
 
 \end{itemize}
- All non-\ital{liquescens} symbols have a non-spacing variant, which are
+ All non-\ital{liquescens} symbols have non-spacing variants, namely
 \keyindex{zdiapunc}, \keyindex{zsqu}, \keyindex{zlsqu}, \keyindex{zrsqu},
 \keyindex{zapostropha} and \keyindex{zoriscus}.
 
-\subsubsection{The plain complex neumes}
+\subsubsection{Plain complex neumes}
 Other \itxem{neumes} can be obtained by combining two or more of these
 symbols. Since \itxem{neumes} have a special note head width, an additional
 shifting macro is provided, namely \keyindex{groff}. It is similar to
-\verb|\roff|, but the offset is smaller; to implement also triple symbol neumes,
-another shifting macro is provided, namely \keyindex{dgroff} which performs an
-offset twice the offset of \verb|\groff|..
+\verb|\roff|, but the offset is smaller. For use with comples neumes, another
+shifting macro is provided, namely \keyindex{dgroff}, which causes an
+offset twice the offset of \verb|\groff|.
 
  Since most of these symbols depend on relative pitches of their components,
-one could not provide all compact combinations as single symbols. Following
-compound symbols are:
+we cannot provide all possible compact combinations as single symbols. The ones
+that are available in \verb|musixgre| are described below. In the following,
+$p_1$, $p_2$, $p_3$, and $p_4$ represent pitches specified as usual. Please refer to
+the source file \verb|musixtex.tex| if you wish to see the coding of those
+examples for which it is not quoted here.
 
-\begin{description}
- \item[\keyindex{bivirga} $n$ $p$], for example:
+\def\twop{\itbrace{p_1}\itbrace{p_2}}
+\def\threep{\twop\itbrace{p_3}}
+\def\fourp{\threep\itbrace{p_4}}
 
- \begin{music}
+\begin{description}\setlength{\itemsep}{0ex}
+ \item[\keyindex{bivirga}\twop], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6322,8 +7283,9 @@ compound symbols are:
  \startextract
  \notes \bivirga ab\enotes
  \notes \bivirga cc\enotes
- \endextract
+ \zendextract
  \end{music}
+
   This example was coded as:
   \begin{quote}\begin{verbatim}
  \instrumentnumber 1
@@ -6334,12 +7296,12 @@ compound symbols are:
  \startextract
  \notes \bivirga ab\enotes
  \notes \bivirga cc\enotes
- \endextract
+ \zendextract
   \end{verbatim}\end{quote}
 
- \item[\keyindex{trivirga} $n$ $p$ $q$], for example:
+ \item[\keyindex{trivirga}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6350,12 +7312,12 @@ compound symbols are:
  \startextract
  \Notes \trivirga abc\enotes
  \Notes \trivirga cca\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{bistropha} $n$ $p$], for example:
+ \item[\keyindex{bistropha}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6366,12 +7328,12 @@ compound symbols are:
  \startextract
  \notes \bistropha ab\enotes
  \notes \bistropha cc\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{tristropha} $n$ $p$ $q$], for example:
+ \item[\keyindex{tristropha}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6382,12 +7344,12 @@ compound symbols are:
  \startextract
  \Notes \tristropha abc\enotes
  \Notes \tristropha cca\enotes
- \endextract
+ \zendextract
  \end{music}
 
-  \item[\keyindex{clivis} $n$ $p$], for example:
+  \item[\keyindex{clivis}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6398,12 +7360,13 @@ compound symbols are:
  \startextract
  \notes \clivis ba\enotes
  \notes \clivis ca\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{lclivis} $n$ $p$], for example:
+ \item[\keyindex{lclivis}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
+ \setsize1{\Largevalue}
  \elemskip 10pt
  \instrumentnumber 1
  \setstaffs 1 1
@@ -6413,12 +7376,12 @@ compound symbols are:
  \startextract
  \notes \lclivis ba\enotes
  \notes \lclivis ca\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{podatus} $n$ $p$], for example:
+ \item[\keyindex{podatus}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6430,12 +7393,12 @@ compound symbols are:
  \notes \podatus ab\enotes
  \notes \podatus ac\enotes
  \notes \podatus cf\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{podatusinitiodebilis} $n$ $p$], for example:
+ \item[\keyindex{podatusinitiodebilis}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6447,14 +7410,15 @@ compound symbols are:
  \notes \podatusinitiodebilis ab\enotes
  \notes \podatusinitiodebilis ac\enotes
  \notes \podatusinitiodebilis cf\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{lpodatus} $n$ $p$], for example:
+ \item[\keyindex{lpodatus}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
- \instrumentnumber 1
+ \setsize1{\Largevalue}
+  \instrumentnumber 1
  \setstaffs 1 1
  \setlines 1 4
  \setclef 1{3000}
@@ -6462,12 +7426,12 @@ compound symbols are:
  \startextract
  \notes \lpodatus ab\enotes
  \notes \lpodatus ce\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{pesquassus} $n$ $p$], for example:
- 
- \begin{music}
+ \item[\keyindex{pesquassus}\twop], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6478,12 +7442,12 @@ compound symbols are:
  \startextract
  \notes \pesquassus ab\enotes
  \notes \pesquassus ae\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{quilismapes} $n$ $p$], for example:
- 
- \begin{music}
+ \item[\keyindex{quilismapes}\twop], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6494,12 +7458,12 @@ compound symbols are:
  \startextract
  \notes \quilismapes ab\enotes
  \notes \quilismapes ae\enotes
- \endextract
+ \zendextract
  \end{music}
 
-  \item[\keyindex{torculus} $n$ $p$ $q$], for example:
+  \item[\keyindex{torculus}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6511,12 +7475,12 @@ compound symbols are:
  \notes \torculus aba\enotes
  \notes \torculus cfd\enotes
  \notes \torculus afc\enotes
- \endextract
+ \zendextract
  \end{music}
 
-  \item[\keyindex{torculusinitiodebilis} $n$ $p$ $q$], for example:
+  \item[\keyindex{torculusinitiodebilis}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6528,12 +7492,12 @@ compound symbols are:
  \notes \torculusinitiodebilis aba\enotes
  \notes \torculusinitiodebilis cfd\enotes
  \notes \torculusinitiodebilis afc\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{Porrectus} $n$ $p$ $q$], for example:
+ \item[\keyindex{Porrectus}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6547,7 +7511,7 @@ compound symbols are:
  \notes \Porrectus bNd\enotes
  \notes \Porrectus bMe\enotes
  \notes \Porrectus bLe\enotes
- \endextract
+ \zendextract
  \end{music}
 \noindent coded:
  \begin{quote}\begin{verbatim}
@@ -6560,14 +7524,14 @@ compound symbols are:
 
  \verb|\Porrectus| exists in four different shapes, depending on the
 difference between first and second argument. The constraint is that
- $$ n-4 \leq p \leq n-1 $$ otherwise a diagnostic occurs. Note also that
+ $$ p_1-4 \leq p_2 \leq p_1-1 $$ otherwise a diagnostic occurs. Note also that
 \keyindex{bporrectus} provides the first curved part of the \verb|porrectus|
-command, if you need it... It has two arguments, the starting pitch, the lower
+command, if you should need it. It has two arguments, the starting pitch and the lower
 pitch.
 
- \item[\keyindex{Porrectusflexus} $n$ $p$ $q$ $r$], for example:
+ \item[\keyindex{Porrectusflexus}\fourp], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6580,7 +7544,7 @@ pitch.
  \notes \Porrectusflexus  bNdb\enotes
  \notes \Porrectusflexus  bMeb\enotes
  \notes \Porrectusflexus  bLea\enotes
- \endextract
+ \zendextract
  \end{music}
 \noindent coded:
  \begin{quote}\begin{verbatim}
@@ -6590,10 +7554,10 @@ pitch.
  \notes \Porrectusflexus  bLea\enotes
  \end{verbatim}\end{quote}
 
- 
- \item[\keyindex{climacus} $n$ $p$ $q$], for example:
 
- \begin{music}
+ \item[\keyindex{climacus}\threep], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6605,12 +7569,12 @@ pitch.
  \Notes \climacus cbN\enotes
  \Notes \climacus cba\enotes
  \Notes \climacus dbN\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{climacusresupinus} $n$ $p$ $q$ $r$], for example:
+ \item[\keyindex{climacusresupinus}\fourp], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6622,14 +7586,15 @@ pitch.
  \Notes \climacusresupinus cbNa\enotes
  \Notes \climacusresupinus cbab\enotes
  \Notes \climacusresupinus dbNb\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{lclimacus} $n$ $p$ $q$], for example:
+ \item[\keyindex{lclimacus}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
- \instrumentnumber 1
+  \setsize1{\Largevalue}
+\instrumentnumber 1
  \setstaffs 1 1
  \setlines 1 4
  \setclef 1{3000}
@@ -6638,13 +7603,12 @@ pitch.
  \notes \lclimacus cbN\enotes
  \notes \lclimacus cfd\enotes
  \notes \lclimacus afc\enotes
- \endextract
+ \zendextract
  \end{music}
 
+ \item[\keyindex{scandicus}\threep], for example:
 
- \item[\keyindex{scandicus} $n$ $p$ $q$], for example:
-
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6655,12 +7619,12 @@ pitch.
  \startextract
  \notes \scandicus abe\enotes
  \notes \scandicus ceg\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{salicus} $n$ $p$ $q$], for example:
+ \item[\keyindex{salicus}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6671,12 +7635,12 @@ pitch.
  \startextract
  \Notes \salicus abe\enotes
  \Notes \salicus ceg\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{salicusflexus} $n$ $p$ $q$ $r$], for example:
+ \item[\keyindex{salicusflexus}\fourp], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6687,14 +7651,16 @@ pitch.
  \startextract
  \Notes \salicusflexus abec\enotes
  \Notes \salicusflexus cegd\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{trigonus} $n$ $p$ $q$], for example\footnote{The second
-example is in principle irrelevant, but it shows the possibilities, in case
-of.}:
+ \item[\keyindex{trigonus}\threep],
+%DAS ????????????
+%for example\footnote{The second example is in principle irrelevant,
+%but it shows the possibilities, in case of.}:
+for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6705,16 +7671,16 @@ of.}:
  \startextract
  \Notes \trigonus aaN\enotes
  \Notes \trigonus cef\enotes
- \endextract
+ \zendextract
  \end{music}
 
 \end{description}
 
-\subsubsection{The liquescens complex neumes}\index{liquescens neumes}
-\begin{description}
-  \item[\keyindex{clivisauctup} $n$ $p$], for example:
+\subsubsection{Liquescens complex neumes}\index{liquescens neumes}
+\begin{description}\setlength{\itemsep}{0ex}
+  \item[\keyindex{clivisauctup}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6725,11 +7691,11 @@ of.}:
  \startextract
  \notes \clivisauctup ba\enotes
  \notes \clivisauctup ca\enotes
- \endextract
+ \zendextract
  \end{music}
-  \item[\keyindex{clivisauctdown} $n$ $p$], for example:
+  \item[\keyindex{clivisauctdown}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6740,11 +7706,11 @@ of.}:
  \startextract
  \notes \clivisauctdown ba\enotes
  \notes \clivisauctdown ca\enotes
- \endextract
+ \zendextract
  \end{music}
- \item[\keyindex{podatusauctup} $n$ $p$], for example:
+ \item[\keyindex{podatusauctup}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6756,11 +7722,11 @@ of.}:
  \notes \podatusauctup ab\enotes
  \notes \podatusauctup ac\enotes
  \notes \podatusauctup cf\enotes
- \endextract
+ \zendextract
  \end{music}
- \item[\keyindex{podatusauctdown} $n$ $p$], for example:
+ \item[\keyindex{podatusauctdown}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6772,12 +7738,12 @@ of.}:
  \notes \podatusauctdown ab\enotes
  \notes \podatusauctdown ac\enotes
  \notes \podatusauctdown cf\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{pesquassusauctdown} $n$ $p$], for example:
- 
- \begin{music}
+ \item[\keyindex{pesquassusauctdown}\twop], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6788,12 +7754,12 @@ of.}:
  \startextract
  \notes \pesquassusauctdown ab\enotes
  \notes \pesquassusauctdown ae\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{quilismapesauctdown} $n$ $p$], for example:
- 
- \begin{music}
+ \item[\keyindex{quilismapesauctdown}\twop], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6804,12 +7770,12 @@ of.}:
  \startextract
  \notes \quilismapesauctdown ab\enotes
  \notes \quilismapesauctdown ae\enotes
- \endextract
+ \zendextract
  \end{music}
- 
-  \item[\keyindex{torculusauctdown} $n$ $p$ $q$], for example:
 
- \begin{music}
+  \item[\keyindex{torculusauctdown}\threep], for example:
+
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6821,12 +7787,12 @@ of.}:
  \notes \torculusauctdown aba\enotes
  \notes \torculusauctdown cfd\enotes
  \notes \torculusauctdown afc\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{Porrectusauctdown} $n$ $p$ $q$], for example:
+ \item[\keyindex{Porrectusauctdown}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6839,12 +7805,12 @@ of.}:
  \notes \Porrectusauctdown bNd\enotes
  \notes \Porrectusauctdown bMe\enotes
  \notes \Porrectusauctdown bLe\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{climacusauctdown} $n$ $p$ $q$], for example:
+ \item[\keyindex{climacusauctdown}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6856,12 +7822,12 @@ of.}:
  \Notes \climacusauctdown cbN\enotes
  \Notes \climacusauctdown caM\enotes
  \Notes \climacusauctdown aNM\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{scandicusauctdown} $n$ $p$ $q$], for example:
+ \item[\keyindex{scandicusauctdown}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6872,12 +7838,12 @@ of.}:
  \startextract
  \notes \scandicusauctdown abe\enotes
  \notes \scandicusauctdown ceg\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{salicusauctdown} $n$ $p$ $q$], for example:
+ \item[\keyindex{salicusauctdown}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6888,12 +7854,12 @@ of.}:
  \startextract
  \Notes \salicusauctdown abe\enotes
  \Notes \salicusauctdown ceg\enotes
- \endextract
+ \zendextract
  \end{music}
 
-  \item[\keyindex{clivisdeminut} $n$ $p$], for example:
+  \item[\keyindex{clivisdeminut}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \setsize1{\Largevalue}
  \instrumentnumber 1
@@ -6904,12 +7870,12 @@ of.}:
  \startextract
  \notes \clivisdeminut ba\enotes
  \notes \clivisdeminut ca\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{podatusdeminut} $n$ $p$], for example:
+ \item[\keyindex{podatusdeminut}\twop], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6921,12 +7887,12 @@ of.}:
  \notes \podatusdeminut ab\enotes
  \notes \podatusdeminut ac\enotes
  \notes \podatusdeminut cf\enotes
- \endextract
+ \zendextract
  \end{music}
 
-  \item[\keyindex{torculusdeminut} $n$ $p$ $q$], for example:
+  \item[\keyindex{torculusdeminut}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6938,12 +7904,12 @@ of.}:
  \notes \torculusdeminut aba\enotes
  \notes \torculusdeminut cfd\enotes
  \notes \torculusdeminut afc\enotes
- \endextract
+ \zendextract
  \end{music}
 
-  \item[\keyindex{torculusdebilis} $n$ $p$ $q$], for example:
+  \item[\keyindex{torculusdebilis}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6955,12 +7921,12 @@ of.}:
  \notes \torculusdebilis aba\enotes
  \notes \torculusdebilis cfd\enotes
  \notes \torculusdebilis afc\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{Porrectusdeminut} $n$ $p$ $q$], for example:
+ \item[\keyindex{Porrectusdeminut}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6973,12 +7939,12 @@ of.}:
  \notes \Porrectusdeminut bNd\enotes
  \notes \Porrectusdeminut bMe\enotes
  \notes \Porrectusdeminut bLe\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{climacusdeminut} $n$ $p$ $q$], for example:
+ \item[\keyindex{climacusdeminut}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -6990,12 +7956,12 @@ of.}:
  \Notes \climacusdeminut cbN\enotes
  \Notes \climacusdeminut caM\enotes
  \Notes \climacusdeminut aML\enotes
- \endextract
+ \zendextract
  \end{music}
 
- \item[\keyindex{scandicusdeminut} $n$ $p$ $q$], for example:
+ \item[\keyindex{scandicusdeminut}\threep], for example:
 
- \begin{music}
+ \begin{music}\nostartrule
  \elemskip 10pt
  \instrumentnumber 1
  \setsize1{\Largevalue}
@@ -7006,14 +7972,12 @@ of.}:
  \startextract
  \notes \scandicusdeminut abe\enotes
  \notes \scandicusdeminut ceg\enotes
- \endextract
+ \zendextract
  \end{music}
 \end{description}
 
- %\check
- \subsection{musixgui} \ttxem{musixgui.tex} provides some macros for
-typesetting \itxem{guitar tablatures}. Most times they are used above modern
-music. To give an example:
+\subsection{musixgui}\ixtt{musixgui.tex} Provides macros for
+typesetting modern style \itxem{guitar tablatures}. For example:
 
 \begin{music}
 \hsize130mm
@@ -7073,33 +8037,33 @@ music. To give an example:
 \end{music}
 
 \medskip
-\keyindex{guitar} sets the grid, the chord name, the relative barre and play
-indicators. As example the first chord in upper example was coded as:
+The macro \keyindex{guitar} sets the grid, chord name, barre type,
+and on-off indicators for the strings. For example, the first
+chord in above example was coded as
 
 \verb|\guitar G{}o-----\gbarre3\gdot25\gdot35\gdot44|
 
-where the first argument is put above the grid to indicate the chord name, the
-second is empty (relative barre) and the other six indicates if the string
-is played with either \verb|x|, \verb|o| or \verb|-|. The dots are set with
+\noindent where the first argument is the text to be placed above the grid, the
+second is empty (relative barre), and the next six characters indicate if the string
+is played or not with either \verb|x|, \verb|o| or \verb|-|. The dots are set with
 \keyindex{gdot}~$sb$ where the $s$ is the string and $b$ is the barre. The
-rule is set with \keyindex{gbarre}~$b$ where $b$ indicates the barre.
+rule is set with \keyindex{gbarre}~$b$ where $b$ indicates the position of the barre.
 
-The whole chord may be vertically shifted with
-\keyindex{raiseguitar}\verb|{|$n$\verb|}|, where $n$ is a number
-in units of \keyindex{internote}. It might be useful to reserve additional
+The whole symbol may be vertically shifted with
+\keyindex{raiseguitar}\onen, where $n$ is a number
+in units of \keyindex{internote}. When using guitar tablatures, it might be
+useful to reserve additional
 space above the chord by advancing \keyindex{stafftopmarg} to
 something like \verb|stafftopmarg=10\Interligne|.
 
-If you need the chords more often, it might be useful to define your own
-macros, e.g.~saying:
+For frequently used chords, it might be useful to define your own
+macros, e.g.
 
 \verb|\def\Dmajor{\guitar D{}x-----\gdot42\gdot53\gdot62}%|
- \subsection{*musixlit}\label{litu}\label{otherbars}
- Provides a way of coding intermediate between gregorian and baroque/romantic,
-still used\footnote{Was written by A. {\sc Egler}. To my knowledge (D. T.),
-liturgical works are either written with modern music quotation, or using the
-gregorian \itxem{neumes} which have been normalized in 1905.} for liturgical
-works!
+
+ \subsection{musixlit}\label{litu}\label{otherbars}
+ Provides a notation style intermediate between gregorian and baroque, for
+example
 
 \makeatletter
 \catcodesmusic
@@ -7177,7 +8141,7 @@ works!
 \end{music}
 
  This package provides:
- \begin{itemize}
+ \begin{itemize}\setlength{\itemsep}{0ex}
  \item\keyindex{oldGclef} which replaces the ordinary G clef with an old one,
 using (for instrument 2 as an example):
  \verb|\settrebleclefsymbol2\oldGclef|
@@ -7194,7 +8158,8 @@ pitch $p$.
  \item\keyindex{chl} $p$ provides a square headed half note with stem down at
 pitch $p$.
 
- \item\keyindex{cnqu} $p$ and \keyindex{cnql} $p$ provide a stemless square headed
+ \item\keyindex{cnqu} $p$ and \keyindex{cnql} $p$ provide a stemless square
+headed
 quarter note at pitch $p$.
 
  \item\keyindex{cnhu} $p$ and \keyindex{cnhl} $p$ provide a stemless square
@@ -7217,24 +8182,25 @@ the staff vertical width.
 staffs, rather that over them. This is an arbitrary question of taste...
  \end{itemize}
 
+ \subsection{musixlyr} \ixtt{musixlyr.tex}
+ Enables the recommended method for adding lyrics to a score (see \ref{musixlyr}).
 
+ \subsection{musixmad} \ixtt{musixmad.tex} Increases the number of
+instruments, slurs and beams up to twelve. When using this extension, it is
+not necessary to explicitly input \verb|musixadd.tex|.
 
- \subsection{musixmad} \ttxem{musixmad.tex} increases the number of
-instruments, slurs and beams up to twelve.
- \subsection{musixper}\label{perc}
 
-  Provides specific percussion symbols, especially \keyindex{drumclef}
-(used in section \ref{sectiondrum}). These definitions cause problems
-since drum and percussion notation is not standardized.
-So it might be clever to specifiy the names of instruments for each
-used symbol.
+\subsection{musixper}\label{perc}
 
+Provides special symbols intended for percussion parts. Included are a
+\ital{drum clef}---comprising two vertical parallel lines---and notes with
+various specially shaped heads. The note symbols that are available are as
+follows:
 
- %\check
- \begin{itemize}
+ \begin{itemize}\setlength{\itemsep}{0ex}
  \item The \raise.5ex\hbox{\musixchar113}~{}~symbol which is obtained using the
 \verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
-``\verb|dc|'' (think of \ital{DiagonalCross} for e.g. closed \itxem{hihat}).
+``\verb|dc|'' (think of {\it d}iagonal {\it c}ross).
 Available are
 \keyindex{dcqu},
 \keyindex{dcql},
@@ -7248,7 +8214,7 @@ Available are
  \item The \raise.5ex\hbox{\musixchar112}~{}~symbol which is obtained using the
 \verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
 ``\verb|dh|''
-(think of \ital{DiagonalcrossHalfcircle} for e.g. half open \itxem{hihat}).
+(think of {\it d}iagonal cross {\it h}alf open).
 Available are
 \keyindex{dhqu},
 \keyindex{dhql},
@@ -7262,7 +8228,7 @@ Available are
  \item The \raise.5ex\hbox{\musixchar111}~{}~symbol which is obtained using the
 \verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
 ``\verb|do|''
-(think of \ital{DiagonalCross and O for circle} for open \itxem{hihat}).
+(think of {\it d}iagonal cross {\it o}pen).
 Available are
 \keyindex{doqu},
 \keyindex{doql},
@@ -7274,8 +8240,8 @@ Available are
 \keyindex{doccl}.
 
  \item The \raise.5ex\hbox{\musixchar114}~{}~symbol which is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
-``\verb|x|'' (e.g. for spoken text of songs).
+\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded by
+``\verb|x|'' (e.g.\ for spoken text of songs).
 Available are
 \keyindex{xqu},
 \keyindex{xql},
@@ -7287,8 +8253,8 @@ Available are
 \keyindex{xccl}.
 
  \item The \raise.5ex\hbox{\musixchar115}~{}~symbol which is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
-``\verb|ox|'' (.!.).
+\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded by
+``\verb|ox|'' .
 Available are
 \keyindex{oxqu},
 \keyindex{oxql},
@@ -7300,8 +8266,8 @@ Available are
 \keyindex{oxccl}.
 
  \item The \raise.5ex\hbox{\musixchar118}~{}~symbol which is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
-``\verb|ro|'' (think of \ital{RhOmbus} for e.g.~shaker).
+\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded by
+``\verb|ro|'' (think of {\it r}h{\it o}mbus).
 Available are
 \keyindex{roqu},
 \keyindex{roql},
@@ -7313,8 +8279,8 @@ Available are
 \keyindex{roccl}.
 
  \item The \raise.5ex\hbox{\musixchar116}~{}~symbol which is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded with a
-``\verb|tg|'' (think of \ital{TrianGle} for e.g.~rattle).
+\verb|\qu|, \verb|\qb|, \verb|\cu|, etc. macros preceeded by
+``\verb|tg|'' (think of {\it t}rian{\it g}le).
 Available are
 \keyindex{tgqu},
 \keyindex{tgql},
@@ -7325,9 +8291,10 @@ Available are
 \keyindex{tgcl} and
 \keyindex{tgccl}.
 
- \item The \raise.5ex\hbox to 1em{\musixchar117\hfil} symbol which is obtained using the
-\verb|\qu|, \verb|\qb|, \verb|\cu|, etc.~macros preceeded with a
-``\verb|k|'' (for bongos).
+ \item The \raise.5ex\hbox to 1em{\musixchar117\hfil}~{}~symbol which is obtained
+using the
+\verb|\qu|, \verb|\qb|, \verb|\cu|, etc.~macros preceeded by
+``\verb|k|'' .
 Available are
 \keyindex{kqu},
 \keyindex{kql},
@@ -7338,8 +8305,142 @@ Available are
 \keyindex{kcl} and
 \keyindex{kccl}.
  \end{itemize}
+
+The diamond shaped noteheads described in section \ref{diam} are also
+available, because \verb|musixper.tex| inputs \verb|musixdia.tex|.
+
+If any of the foregoing notes need to be dotted, you must use the explicit
+dotting macros \verb|\pt|, \verb|\ppt|, or \verb|\pppt| as described in
+section \ref{dots}.
+
+Since the usage of these note symbols is
+not standardized, it would be wise to include in the score a explanation
+of which symbol corresponds to which specific percussion instrument.
+
+A special \itxem{drum clef}---comprising two heavy vertical bars---can
+be made to replace the normal clef for the $n$-th intrument by saying
+\keyindex{setclefsymbol}\onen\keyindex{drumclef} .
+To cause this to appear at the right vertical position, the instrument should
+previously have been assigned a treble clef (or not explicitly assigned any
+clef, thereby giving it a treble clef by default).
+
+Percussion music might be written on a staff with either one or five lines.
+If there are several different percussions instruments it may be useful to
+use a five-line staff with a drum clef, and differentiate the instruments
+by the type of the note heads and the apparent
+pitch of the note on the staff. Here is an example of the
+latter\footnote{provided by Agusti {\sc Mart\'in Domingo}}:
+
+\medskip
+\begin{music}
+\generalmeter{\meterfrac44}
+\setclefsymbol1\drumclef
+\parindent0pt\startpiece
+\leftrepeat
+\Notes\zql f\rlap\qp\ibu0m0\xqb0{nn}\enotes
+\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
+\Notes\zql f\rlap\qp\ibu0m0\xqb0{nn}\enotes
+\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
+\bar
+\Notes\zql f\rlap\qp\ibu0m0\kqb0{nn}\enotes
+\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
+\Notes\zql f\rlap\qp\ibu0m0\kqb0{nn}\enotes
+\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
+\bar
+\Notes\zql f\rlap\qp\ibu0m0\oxqb0{nn}\enotes
+\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
+\Notes\zql f\rlap\qp\ibu0m0\oxqb0{nn}\enotes
+\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
+\setrightrepeat\endpiece
+\end{music}
+\noindent Its coding is
+ \begin{quote}\begin{verbatim}
+\begin{music}
+\instrumentnumber{1}
+\generalmeter{\meterfrac44}
+\setclefsymbol1\drumclef
+\parindent0pt\startpiece
+\leftrepeat
+\Notes\zql f\rlap\qp\ibu0m0\xqb0{nn}\enotes
+\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
+\Notes\zql f\rlap\qp\ibu0m0\xqb0{nn}\enotes
+\Notes\kzq d\zql f\zq j\xqb0n\tbu0\xqb0n\enotes
+\bar
+\Notes\zql f\rlap\qp\ibu0m0\kqb0{nn}\enotes
+\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
+\Notes\zql f\rlap\qp\ibu0m0\kqb0{nn}\enotes
+\Notes\xzq d\zql f\zq j\kqb0n\tbu0\kqb0n\enotes
+\bar
+\Notes\zql f\rlap\qp\ibu0m0\oxqb0{nn}\enotes
+\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
+\Notes\zql f\rlap\qp\ibu0m0\oxqb0{nn}\enotes
+\Notes\oxzq d\zql f\zq j\kqb0n\tbu0\oxqb0n\enotes
+\setrightrepeat\endpiece
+\end{music}
+ \end{verbatim}\end{quote}
+
+Here is an example of a single-line percussion staff using
+diamond-shaped note heads:
+
+\begin{music}
+\parindent 19mm
+\instrumentnumber{3}
+\setname1{keyboard} \setname2{drum} \setname3{monks}
+\setlines2{1}
+\setlines3{4}
+\setinterinstrument1{-2\Interligne}% less vertical space above
+\setinterinstrument2{-2\Interligne}% and below the percussion
+\sepbarrules
+\setsign1{-1} % one flat at keyboard
+\generalmeter{\meterfrac24}
+\setmeter3\empty
+\setclef3\alto
+\setclef1\bass
+\setstaffs12 % 2 staffs at keyboard
+\setclefsymbol3\gregorianCclef % gregorian C clef at instrument 3
+\setclefsymbol2\drumclef       % cancel G clef at instrument 2
+\startextract
+\Notes\hu F|\zh c\hu h&\dnq4&\squ{acd}\enotes\bar
+\NOtes\qu I|\zq N\qu d&\qp&\diapunc f\enotes
+\NOtes\qu J|\zq a\qu e&\ynq4&\diapunc e\enotes\bar
+\notes\hu G|\zh b\hu d&\dnq4&\zsqu d\rsqu g\squ{hgh}\enotes
+\endextract
+\end{music}
+\noindent which is coded as follows:
+
+\begin{verbatim}
+\parindent 19mm
+\instrumentnumber{3}
+\setname1{keyboard} \setname2{drum} \setname3{monks}
+\setlines2{1}
+\setlines3{4}
+\setinterinstrument1{-2\Interligne}% less vertical space above
+\setinterinstrument2{-2\Interligne}% and below the percussion
+\sepbarrules
+\setsign1{-1} % one flat at keyboard
+\generalmeter{\meterfrac24}
+\setmeter3{\empty}
+\setclef3{\alto}
+\setclef1{\bass}
+\setstaffs1{2} % 2 staffs at keyboard
+\setclefsymbol3{\gregorianCclef} % gregorian C clef at instrument 3
+\setclefsymbol2{\drumclef}       % cancel G clef at instrument 2
+\startextract
+\end{verbatim}
+
+% (DAS) Sorry, guys, I couldn't figure out how to get the |'s to work in this
+% verbatim.
+%
+\vskip-11pt
+\def\Vert{{\tt\char'174}}
+\noindent\verb|\Notes\hu F|\Vert\verb|\zh c\hu h&\dnq4&\squ{acd}\enotes\bar|\\
+\verb|\NOtes\qu I|\Vert\verb|\zq N\qu d&\qp&\diapunc f\enotes|\\
+\verb|\NOtes\qu J|\Vert\verb|\zq a\qu e&\ynq4&\diapunc f\enotes\bar|\\
+\verb|\notes\hu G|\Vert\verb|\zh b\hu d&\dnq4&\zsqu d\rsqu g\squ{hgh}\enotes|\\
+\verb|\endextract|
+
  \subsection{musixpoi}
- Adds pointed compact definitions of notes.
+ Adds definitions of less common singly and doubly dotted notes.
 Available are
 \keyindex{ccup},
 \keyindex{zccup},
@@ -7367,24 +8468,22 @@ Available are
 \keyindex{zcccclpp}.
 
  %\check
- \subsection{musixstr}\label{musixstr}\index{musixstr@{\tt musixstr.tex}}
- This file provides a set of indications for \itxem{string instruments} (e.g.
-\ixem{violin}) execution, provided by Werner {\sc Icking}\index{Icking,
-W.@{\sc Icking, W.}}.
-
+ \subsection{musixps}\label{musixps}\index{musixps@{\tt musixps.tex}}
+ Activates type K postscript slurs, ties,  and hairpins (see \ref{PostscriptSlurs}).
 
- {\input musixstr
- The symbols described below should be posted at the wanted place using
- \verb|\zcharnote|$p$\verb|{|$<command-name>$\verb|}|.
+ \subsection{musixstr}\label{musixstr}\index{musixstr@{\tt musixstr.tex}}
+ Provides bowing and other symbols for \itxem{string instruments}\footnote{provided
+by Werner {\sc Icking}}. The symbol can be posted at the desired position using
+ \verb|\zcharnote|\pitchp\verb|{|$command$\verb|}|. The available symbols and
+their meanings are as follows:
 
-\begin{quote}\begin{description}
+{\input musixstr
+\begin{quote}\begin{description}\setlength{\itemsep}{0ex}
 
  \item[\hbox to 1em{\AB}~: \keyindex{AB} or  \keyindex{downbow}] down-bow
 
-
  \item[\hbox to 1em{\AUF}~: \keyindex{AUF} or \keyindex{upbow}] up-bow
 
-
  \item[\hbox to 1em{\SP}~: \keyindex{SP}] at the top of bow
 
  \item[\hbox to 1em{\FR}~: \keyindex{FR}] at the nut of bow
@@ -7408,20 +8507,17 @@ W.@{\sc Icking, W.}}.
  %\check
  \subsection{musixsty}\index{musixsty@{\tt musixsty.tex}}
 
- This file is made for non \TeX perts and/or lazy score typesetters. Although
-related to \musixtex, it has little to see with music, but it helps writing
-all surrounding texts, like \itxem{titles}, \itxem{author names}, historical
-comments, etc. It provides
- \begin{itemize}
- \item a set of font definitions of common use, such as \verb|\tenrm|,
-\verb|\eightrm|, etc.,
- \item a reasonable setting of \keyindex{hsize}, \keyindex{vsize},
-\keyindex{hoffset}, \keyindex{voffset} dimensions in order to have a good
-layout fit for European A4 paper\footnote{People addicted to \itxem{legal} or
-other paper sizes should correct it for their own purpose.}
+ Provides certain text-handling facilities for titles, footnotes, and other
+items not related to lyrics. It should not be used with \LaTeX. It includes
+ \begin{itemize}\setlength{\itemsep}{0ex}
+ \item definitions for commonly used fonts such as \verb|\tenrm|,
+\verb|\eightrm|, etc.;
+ \item definitions of \keyindex{hsize}, \keyindex{vsize},
+\keyindex{hoffset}, \keyindex{voffset} suitable for A4 paper; those using
+other sizes may wish to modify it once and for all;
  \item a set of text size commands:
 
- \begin{description}
+ \begin{description}\setlength{\itemsep}{0ex}
   \item[\keyindex{eightpoint}] which sets the usual \keyindex{rm},
 \keyindex{bf}, \keyindex{sl}, \keyindex{it} commands to 8 point font size;
   \item[\keyindex{tenpoint}] which sets the usual \keyindex{rm},
@@ -7432,69 +8528,62 @@ other paper sizes should correct it for their own purpose.}
   \item[\keyindex{twtypoint}] to get 20.74 point font size;
   \item[\keyindex{twfvpoint}] to get 24.88 point font size;
  \end{description}
- \item a set of commands to make easy piece titles:
-  \begin{itemize} \item \keyindex{author} or
+ \item commands for creating titles:
+  \begin{itemize}\setlength{\itemsep}{0ex} \item \keyindex{author} or
 \keyindex{fullauthor} to be put at the right of the first page, below the
-title of the piece; the calling sequence is, for example:
+title of the piece; the calling sequence is, for example
 
   \verb|     \author{Daniel TAUPIN\\organiste \`a Gif-sur-Yvette}|
 
-  \noindent where the \verb|\\| makes the author's name displayed on two or
-several lines.
-
+  \noindent where the \verb|\\| causes the author's name to be displayed on
+two lines;
 
-  \item \keyindex{shortauthor} to be put at the bottom of each page,
-  \item \keyindex{fulltitle} which is the big main title of the piece,
-  \item \keyindex{subtitle} is displayed below the main title of the piece,
+  \item \keyindex{shortauthor} to be put at the bottom of each page;
+  \item \keyindex{fulltitle} which is the main title of the piece;
+  \item \keyindex{subtitle} is displayed below the main title of the piece;
   \item \keyindex{shorttitle} or \keyindex{title}
-  which is the title repeated at the bottom of each page,
-  \item \keyindex{othermention} which is displayed on the left of the page, in
-front of the author's name (it may contain several \verb|\\| to display it on
-several lines,
-  \item \keyindex{maketitle}  which displays all the previous stuff.
+  which is the title repeated at the bottom of each page;
+  \item \keyindex{othermention} which is displayed on the left of the page,
+vertically aligned with author's name. It may contain \verb|\\| to display it on
+several lines;
+  \item \keyindex{maketitle}  which displays all the previous stuff;
   \end{itemize}
 
- \item  Some additional commands to make \itxem{footnotes}.
- These commands are
-  \begin{itemize}
-   \item The normal Plain-\TeX\ \keyindex{footnote} command which has two
-arguments --- not only one as in \LaTeX\index{LaTeX@\protect\LaTeX} --- namely
-the label of the footnote, i.e. any sequence of characters and not only
-figures, and the text of the footnote.
-
-\begin{important} the \verb|\footnote| command does not work inside
-boxes\footnote{This is not a \TeX-bug, this is a feature!}, therefore this
-command must not be issued within music. But another alternate feature is
-provided (see below).
- \end{important}
+ \item  commands for making \itxem{footnotes}:
+  \begin{itemize}\setlength{\itemsep}{0ex}
+   \item The normal Plain-\TeX\ \keyindex{footnote} command, which has two
+arguments---not just one as in \LaTeX\protect\index{LATEX@\LaTeX}---namely
+the label of the footnote, which can be any sequence of characters, and
+the text of the footnote. This command does not work inside
+boxes, so it cannot be issued within music;
 
  \item The \keyindex{Footnote} command, which counts the footnotes and uses a
-number as the label of the foot note (equivalent to \LaTeX's \verb|\footnote|
-command). The same restriction applies concerning footnotes within the music
-coding.
+number as the label of the footnote (equivalent to \LaTeX's \verb|\footnote|
+command). The same restriction as with \verb|\footnote| applies concerning
+its use within the music coding;
 
  \item The \keyindex{vfootnote} command, taken from the Plain-\TeX, which
-makes the footnote itself at the bottom of the current page, but does not put
-the footnote label at the place it is referred in the main text.
-
- Thus, if a footnote is needed whose reference lies inside the music itself,
-the music typesetter must perform it in two steps:
+places a footnote at the bottom of the current page, but does not put
+the footnote label at the place the command is entered in the main text. This
+also may not be used within music, but if a footnote is needed whose reference
+lies inside the music, it can be entered in two steps:
  \begin{enumerate}
-  \item quote the reference inside the music, using \verb|zcharnote| for
-example,
-  \item post the footnote itself, using \verb|\vfootnote| outside the music,
-either before \keyindex{startpiece} (or \verb|\debutmorceau| with {\tt
-musixcpt.tex})  or between \keyindex{stoppiece} and
-\keyindex{piececont} or equivalent commands.
+  \item manually insert the reference inside the music, using e.g. \verb|zcharnote|;
+  \item post the footnote itself with \verb|\vfootnote| outside the music,
+either before \keyindex{startpiece} or between \keyindex{stoppiece} and
+\keyindex{contpiece} or equivalent commands.
  \end{enumerate}
 
   \end{itemize}
 
  \end{itemize}
 
- Note that \verb|musixsty| should not be used with \LaTeX.
+ \subsection{musixtmr}\index{musixtmr@{\tt musixtmr.tex}}
+ Replaces the standard \texttt{musixtex} fonts by the Times series fonts,
+ as default (see \ref{musixtmr}).
+
  \subsection{musixtri}\index{musixtri@{\tt musixtri.tex}}
-Provides triple pointed note symbols.
+Provides triply dotted note symbols.
 Available are:
 \keyindex{lpppt},
 \keyindex{whppp},
@@ -7516,364 +8605,346 @@ Available are:
 \keyindex{qbppp} and
 \keyindex{zqbppp}.
 
-\section{Often reported problems and discussion faxilities}
-
-\subsection{Newsgroups}\index{newsgroups} No specific newsgroup exist
-concerning \mutex, \musictex{} or \musixtex; nevertheless W. Icking saw
-articles on this topic in  {\tt comp.text.tex} as well as in {\tt
-de.comp.text.tex}.
+ \subsection{tuplet}\index{tuplet@{\tt tuplet.tex}}
+ Causes the figure in xtuplets to be printed within a small gap in the bracket
+(see \ref{tuplet}).
 
-\subsection{Mailing list} A mailing-list does exist which was formerly
-dedicated to \mutex, and now to \musictex{} and mostly to \musixtex.
-You can subscribe to it by
-sending an e-mail to  {\tt mutex-request@gmd.de}
-with the message line\index{mailing list}
+% DAS Discussed elsewhere
+%\section{The \TeX-music Mailing List}
+%
+%If you decide to learn to use \musixtex, you are likely to wish that there were
+%someone to answer your questions. That is exactly what you'll find on the \TeX-music
+%mailing list: experts from all over the world with lots of experience with
+%\musixtex{} and related software, who are glad to answer questions and help solve
+%problems. You can find out more about the list and sign up at
+%\href{http://icking-music-archive.org/mailman/listinfo/tex-music}
+%{\underline{\tt http://icking-music-archive.org/mailman/listinfo/tex-music}}.
+
+
+\chapter{Acquiring, Installing, and Using \musixtex}\label{installation}
+
+This chapter will assume that \TeX\
+is installed. Most \unix\ or Linux systems come with \TeX\ already installed.
+If using MS Windows, you'll need to have manually installed some version of
+\TeX. MiK\TeX\ is the most common variant by far and therefore will be assumed. If
+you need to install MiK\TeX, you can get the software from
+\href{http://www.miktex.org/}{\underline{\texttt{http://www.miktex.org}}}
+or from CTAN. The Werner Icking Archive contains excellent
+\href{http://icking-music-archive.org/software/musixtex/musixwinstall.pdf}%
+{\underline{instructions for installing MiK\TeX}}%
+\footnote{Thanks to Eva {\sc Jaksch}}.
+
+\section{Where to get \musixtex: the Werner Icking Archive}\label{getstuff}
+
+As already mentioned, 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}}.
+The most up-to-date versions of \musixtex\ and friends are located in the
+\href{http://icking-music-archive.org/software/indexmt6.html}{\underline{software}}
+section of the archive. The stable distribution of \musixtex\ will be contained in
+\href{http://icking-music-archive.org/software/musixtex/musixtex.zip}
+{\underline{\verb|musixtex.zip|}}, which is intended to serve all operating
+systems.
+The CTAN servers are official mirrors. The main CTAN server's
+web link is\\
+\href{http://www.ctan.org/tex-archive/macros/musixtex/taupin/}
+{\underline{http://www.ctan.org/tex-archive/macros/musixtex/taupin/}}
+and the FTP link is\\
+\href{http://ftp.ctan.org/tex-archive/macros/musixtex/taupin/}
+{\underline{http://ftp.ctan.org/tex-archive/macros/musixtex/taupin/}}.
+
+\subsection{End of line char in text files}
+The files in the Werner Icking Archive have been contributed by such a wide
+range of authors that there is no common standard for the line endings in text files.
+But the key text files serve as input to programs such as \TeX\ and \MF\
+which are insensitive to this. If you use a PC and run into problems using any of
+these text files, you might be able to solve them with the program 
+\verb|flip.exe| which comes with the \musixtex\ distribution. Run it from a 
+command window by typing \verb|flip -m| $<$filename$>$, and it will 
+convert line endings from the \unix to MS-DOS convention.
+
+\subsection{Pre-installed \musixtex}
+Many versions of \TeX\ include \musixtex\ as a package. The included version is likely
+to be out of date and probably should not be used. When an archived version is
+downloaded and properly installed, it will supersede the pre-installed version. 
+
+\section{Installing \musixtex}
+The most useful \musixtex\ uses Postscript and produces PDF files. 
+The installation is very system dependent and therefore beyond the scope of this manual.
+You may refer to the installation manual or to the HOWTO files in the archive for either
+\href{http://icking-music-archive/software/musixtex/musixwinstall.pdf}
+{\underline{Windows}}\ or
+\href{http://icking-music-archive/software/musixtex/musixtex-for-unix.html}
+{\underline{\unix}}.
+Whatever course you choose, there are really just a few
+fundamental tasks you must accomplish:
+\begin{itemize}\setlength{\itemsep}{0ex}
+  \item \musixtex\ comprises some \TeX\ source files (\verb|.tex|, \verb|.sty|),
+font files, and the executable \verb|musixflx|. The \TeX\ sources and font
+files must be placed in locations where \TeX\ can find them;
+  \item \TeX\ must be advised of the locations of those files;
+  \item If you are installing any postscript fonts, you'll have to add a map
+file somewhere in the \TeX\ file structure, and locate and modify a configuration
+file such as \verb|config.ps| to record the addition of the map file.
+  \item \verb|musixflx| must be placed in a folder that is in your search path,
+so it can be executed from your working directory;
+  \item As stated before, to compile a score, you must run in sequence \verb|tex|, \verb|musixflx|,
+and \verb|tex| again. This will produce a \verb|.dvi| file;
+  \item To view the result, convert the file to
+postscript with \textbf{dvips} and then view it with a postscript viewer such
+as \textbf{GSview} and \textbf{ghostscript}, or convert the \verb|.dvi|
+directly to a PDF file with \textbf{pdftex} and then view it with any PDF viewer
+such as \textbf{Adobe Reader}. You also can use a DVI viewer, but if you are using type K postscript slurs, note that DVI viewers will not display the slurs.
+\end{itemize}
 
-{\tt subscribe}
 
-\subsection{FAQs}\index{FAQ}
+\section{Running Musix\TeX\ }
 
-{\tt gmd.de}, too, has a FAQ which is presently out-of-date and quite unusable
-since it displays many questions and comments without giving the answer.
-However, it will be probably enhanced in a near future. This
-FAQ can be accessed using {\tt
-ftp}:
+In most systems the commands run in a shell. Unix people are familiar with it.
+Also in MS Windows systems, there are a large number of editor/shell programs. Although not recommended, you always can use the DOS
+\verb|cmd| shell (\verb|cmd.exe|).
 
-{\tt ftp://ftp.gmd.de/music/mutex/faq}
 
-\noindent and the archive of the mailing list may be accessed also by {\tt
-ftp}:
+In the examples, a file \verb|mymp|
+(\textbf{my} \textbf{m}aster\textbf{p}iece) is used, for demonstrating
+the batch commands.
 
-{\tt ftp://ftp.gmd.de/music/mutex/archive}
 
-\noindent or:
 
-{\tt http://www.gmd.de/Mail/}
+\subsection{Batch commands for making DVI and postscript (MS Windows)}
 
- {\tt ftp.gmd.de} also contains a lot of stuff concerning music and
-typesetting music, which can be accessed by WWW at:
+This commands are available in the \musixtex\ distribution. They produce
+a DVI file that can be displayed by a viewer
+(normally a part of the \TeX\ installation), or/and a Postscript file (normally with GSview).
 
-{\tt http://www.gmd.de/Misc/Music/}
+After running \TeX\ on a music file, \verb|musixflx| must run. The program \verb|musixflx| calculates the number of bars on a system (music line), in order to have a nice layout. Then, \TeX\ must run again.
 
+When the paths to the binaries and the batch files are set properly, then the following commands can be used as is.
 
+\subsubsection{Using \TeX\ }
+The \ixem{musixtex.bat} command fulfills the sequence \texttt{\TeX\ $\Rightarrow$ musixflx $\Rightarrow$ \TeX}~.
 
-\chapter{Installation}\label{installation}
+\begin{quote}\begin{verbatim}
+rem musixtex.bat
+if not exist %1.tex goto end
+if exist %1.mx1 del %1.mx1
+if exist %1.mx2 del %1.mx2
+tex %1
+if errorlevel 2 goto end
+musixflx %1
+if errorlevel 1 goto end
+tex %1
+:end
+\end{verbatim}\end{quote}
+The next command (\verb|mupsgs.bat|) processes \verb|mymp.tex| and makes a Postscript file  and dispays the file.
+\begin{quote}\begin{verbatim}
+rem mupsgs.bat
+call musixtex.bat %1
+DVIPS.EXE -e0 -t a4 -P pdf -G0 %1.dvi
+gsview32.exe %1.ps
+\end{verbatim}\end{quote}
+The \verb|dvips| output looks a little bit nicer using the options
+\verb|-e0| (character drift value~=~0) and \verb|-G0| (shift low chars
+to higher position).
+\verb|-t a4| is for a4 paper (\verb|-t letter| for letter format).
+If the output is to be converted in Adobe Acrobat pdf format, the option \verb|-P pdf|
+(load \verb|config.pdf|) is needed.
 
-\section{*Getting the stuff}
+If you want to make a PDF output, you may add the line (after \verb+dvips+):
 
-As seen before, all the files are available at \itxem{anonymous ftp}
-\verb|hprib.lps.u-psud.fr| (193.55.39.152) in the directory
+\noindent{\small
+\verb+gswin32c -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -r600 -sOutputFile=%1.pdf -c save pop -f %1.ps+
+}
 
- {\tt /pub/musixtex}
+\subsubsection{Using La\TeX\ }
+Replace ``\verb+tex+'' by ``\verb+latex+'' in the file \verb+musixtex.bat+~.
 
- The {\tt *.mf} source files are in
 
- {\tt /pub/musixtex/mf}
+\subsection{Running \musixtex\ without a shell}
+You also may run the commands without a shell.
+To forward the argument in the batch file,
+use an other batch file which stays in the same directory as your
+masterpiece \verb|mymp.tex| and has the same name: \verb|mymp.bat|~.
+\verb|mymp.bat| consists of 1 line: \verb|musixtex.bat %~n0|~.
 
-\noindent and the {\tt *.tfm} files are in 
+\noindent Thus \verb|mymp.bat| passes his own name (\verb|mymp|) via \verb|%~n0|
+to the \verb|musixtex.bat| command.
 
- {\tt /pub/musixtex/tfm}
+Here are four examples of batch files, dependent of the method you are using.
+\endcatcodesmusic
+%\begin{quote}\begin{verbatim}
+\begin{center}
+\begin{tabular}{|l|l|l|}
+\multicolumn{3}{c}{Choose only one batch file}\\[.4ex]\hline
+Batch file for&making DVI&making postscript\\\hline
+name &\verb+rem mymp.bat+&\verb+rem mymp.bat+\\
+contents&\verb+musixtex.bat %~n0+&\verb+mupsgs.bat %~n0+\\\hline
+\end{tabular}
+%\end{verbatim}\end{quote}
+\end{center}
 
-\noindent Besides, this manual is in
+\subsection{Running \musixtex\ without giving a file name}
+If you want to process i.e.\ all \texttt{.tex} files in a directory, then you could make a batch file
+\texttt{texall.bat} with the following commands:
 
- {\tt /pub/musixtex/musixdoc.ps}
+\begin{quote}\begin{verbatim}
+rem texall
+for /F %%I in ('dir /B *.tex') do call mupsgs.bat %%~nI
+\end{verbatim}\end{quote}
 
- Another directory, namely {\tt /pub/music\_zips} normally contains {\tt
-musixtex.zip} which contains all the distribution for PC (\ixem{MS-DOS})
-computers. This is only for {\tt ftp}-ing convenience since all source files
-are directly available in the general directory and subdirectories. In
-addition a set of examples (i.e. the files whose name does not begin with
-``\verb|musix|'') is packed into \ttxem{musixexa.zip} and this manual is also in
-\ttxem{musixdoc\_ps.zip}  (the PostScript version) and
-\ttxem{musixdoc\_lj.zip} (the PCL version for Laserjets).
-Finally the PK files of specific fonts are provided in \ttxem{musixpk.zip},
-\ttxem{musixpk3.zip} (300 and 360 dpi) and  \ttxem{musixpk6.zip} (600 dpi);
-getting these files is useless if you are able to \MF{} the files whose {\tt
-*.mf} are provided in the main package.
+Of course, this command also works if there is only one file in a directory, which means you
+may use \texttt{texall.bat} for a single file, without giving an argument.
 
-{\sl\noindent CAUTION: the zipped files are provided in the PC line coding,
-i.e. with {\tt <cr><lf>} at line ends, rather than single {\tt <lf>} as in the
-\unix{} coding. This means that \unix{} users must carefully unzip these files
-using the ``{\tt-a}'' (our ``{\tt-aa}'' options of {\tt unzip} to get correct
-coding of the source files. Other wise they would find a lot of ``{\tt\^{}M}'' in
-their files, which may cause further troubles.}\index{PC end of line
-coding}\index{\^{}M}
 
+\chapter{\musixtex\ examples}
 
- Besides, /unix{} users can also --- when in directory {\tt /pub} --- ask for:
+The file \verb|musixdoc.tex|, the source for this manual, contains many useful
+examples. In the manual, many examples are accompanied by a display of the code
+that produced them, while for a few only an image of the extract is included and you'll
+have to look in \verb|musixdoc.tex| to see the coding.
 
- {\tt get musixtex.tar}\quad or
+Other useful examples cannot be embedded in the source, either because they are
+meant to be in \TeX, not La\TeX, or because they are simply to large. For
+these the source files also are provided separately.
 
- {\tt get musixtex.tar.Z}\quad or
+When compiling or viewing any of the examples, you should keep in mind that
+most DVI previewers and laser printers have
+their origin one inch below and one inch to the right of the upper right corner
+of the paper, while the musical examples have their upper left
+corner just one centimeter to the right and below the top left corner of the page.
+Therefore, special parameters may have to be given to the DVI transcription
+programs unless special \keyindex{hoffset} and \keyindex{voffset} \TeX\
+commands have been included within the \TeX\ source.
 
- {\tt get musixtex.tar.gz}\quad and even
+\section{Small examples}
 
- {\tt get musixtex.zip}
+\begin{itemize}\setlength{\itemsep}{0ex}
 
-  Then, the {\tt hprib.lps.u-psud.fr} server will perform required collection
-and/or compression ``on-the-fly''. Note that in that case the source files
-will be in the \unix{} coding rather than PC coding of end of lines. Usually,
-this is harmless for PC editors and \TeX{} motors, but who knows...
- 
+\item{\tt ossiaexa.tex}~: This is a stand-alone example of the use of ossia,
+provided by Olivier Vogel (section \ref{ossia} on page \pageref{ossia}).
 
-\ital{Fonts}\index{fonts} are provided in {\tt musixtex.zip} as {\tt *.mf}
-files but also as {\tt *.tfm} and {\tt*.pk} files for 300~dpi printers or
-previewers. Other values of the \ixem{dpi} parameter are also provided in
-\verb|musixpk*.zip|.
+\item{\tt 8bitchar.tex}~: Using 8bit characters. Here, the European
+character set is used. See section \ref{8bit} on page \pageref{8bit} for other sets.
 
-Needed fonts are {\tt musix20}, {\tt musix16}, {\tt musix13}, {\tt musix11},
-{\tt musix24}, {\tt musix29}, {\tt musixspx}\footnote{Inside this file are two
-types of piano brackets available. The default you can see printing this doc,
-the other you can see printing {\tt musicdoc}. If you prefer the other, which
-are designed by Stanislav Kneifl, follow the instruction inside {\tt
-musixsps.mf}},\index{Kneifl, S.@{\sc Kneifl, S.}}
- {\tt xslhu20}, {\tt xslhu16}, {\tt xslhu24}, {\tt xslhu29},
-{\tt xslhd20}, {\tt xslhd16}, {\tt xslhd24}, {\tt xslhd29},
-{\tt xslu20}, {\tt xslu16}, {\tt xslu24}, {\tt xslu29},
-{\tt xsld20}, {\tt xsld16}, {\tt xsld24}, {\tt xsld29},
-{\tt xslz20} and {\tt xslhz20}.
+\end{itemize}
 
-\section{Installing the fonts}
-\ital{All} files with the extension {\tt .tfm}\footnote{\TeX\ font metric,
-needed directly from binary for \TeX ing the examples or the doc.} must
-be copied in that directory, in which the other {\tt .tfm}'s are.
+\section{Full examples}
+All of these examples and many others are available in
+\href{http://icking-music-archive.org/software/musixtex/musixexa.zip}
+{\underline{\texttt{musixexa.zip}}} or
+\href{http://icking-music-archive.org/software/musixtex/musixexa-T112.tar.gz}
+{\underline{\texttt{musixexa-T112.tar.gz}}}. Some of them require the
+presence of \verb|musixcpt.tex| which makes examples created in
+Music\TeX\ compatible with \musixtex. Here we only mention a few of
+special interest.
+
+\subsection{Examples mentioned in the manual}
+
+\begin{itemize}\setlength{\itemsep}{0ex}
+ \item{\tt avemaria.tex}~: the ``M\'editation'' (alias ``Ave Maria'') by
+Charles {\sc Gounod} for organ and violin or voice.\index{Gounod, C.@{\sc Gounod, C.}}
+To run this five-page example you'll also need \texttt{avemariax.tex}.
+It demonstrates the use of separated bar rules (section \ref{avemaria2})
+and the use of staves of different sizes (section \ref{avemaria}).
+Also, an additional instrument is created for lyrics. This was a common
+practice before the \texttt{musixlyr} package was created by Rainer Dunker.
+
+ \item{\tt glorias.tex}~: a local melody for the French version of
+\ital{Gloria in excelsis Deo}, a three-page piece demonstrating the use of the hardlyrics
+commands (section \ref{glorias}). {\tt gloriab.tex} is the same piece, but with organ accompaniment.
 
-If you get the error message:
+\end{itemize}
 
-{\tt! Font ... not loadable: Metric (TFM) file not found.}
+\subsection{Other examples, provided by the authors of MusiX\TeX }
 
-\index{Metric (TFM) not found}\noindent this means you have not succeeded to
-install the {\tt .tfm}'s in the right directory. This is not a \musixtex\
-error, but a local \TeX\ implementation error/misunderstanding. Then read or
-re-read your \TeX\ installation doc, put the {\tt tfm}'s at the very right
-place and start again.
+\begin{itemize}\setlength{\itemsep}{0ex}
 
-The {\tt .tfm} only contains the width, height and depth of every character of
-a font and is the only needed font-file for \TeX ing. For previewing and/or
-printing you need the pixel fonts. On most systems they are packed and have
-the extension \verb|.pk|(but perhaps you need the \verb|.gf|-files or
-\verb|.300|-files or other: Ask your local \TeX-wizard\footnote{I have read a
-mail from somebody, who has said, that he is able --- because he is a
-professional --- to write an \verb|install| for installation of packages like
-\musixtex. Really? Do it.}!) Most needed and spreaded are fonts for
-\verb|dvi|-driver with resolution of 300dpi. Using em\TeX{} associated drivers
-the \verb|.pk|-fonts have to be copied in \verb|...\pixel.lj\300dpi\| as a
-default, and in general in a directory specified by the environment variable
-{\tt DVIDRVFONTS}\footnote{Look at {\tt dvidrv.doc} for more information.}. For
-other resolution refer your local manual or \TeX-wizard.
-
-\section{Building a format}\label{formatbuild}
-
-Introducing these files in a \itxem{format} (with \ixem{INITEX}) is a mean of
-saving computer time and memory. Besides, if you include {\tt musixcpt.tex} in
-your format, you will have a format compatible with \musictex\ and ---
-provided you made the symmetrical format for \musictex\ --- you can compile
-exactly the same source files with both \musictex\ and \musixtex, which is a
-good means of finding whether some strange behaviour is specific to one
-implementation of the other, or whether you made some general
-mistake\footnote{Not all authors have the same opinion :-). But I was told,
-that my opinion doesn't count, so forget it -- A.E.}...
-
-However, although having a \musixtex{} format saves much time, it can also
-lead to time wasting weird things in case of updates~: if you update your
-source of {\tt musixtex.tex} but not the format {\tt musixtex.fmt}, then
-running the command {\tt musixtex} will invoke the old unmodified format...
-
-\subsection{Starting from nil}
-\begin{enumerate}
- \item Build up a file called \verb|musixtex.ini| with following content:\\
-\begin{verbatim}
-\input plain % or dcplain or eplain or see later a safer way of doing
-\input musixtex
-% here can you add your most needed files from extension lib
-% musixcpt at very last !
-\end{verbatim}
-\verb|\def\fmtname{musixtex}\def\fmtversion{|{\tt\mxversion}\verb|}|
-\verb|\dump|
- \item \verb|initex musixtex.ini|\footnote{depends on your implementation}.
- \item \verb|tex &musixtex| \ital{jobname}\footnote{depends on your
-implementation}.
-\end{enumerate}
-\vfill
+ \item{\tt traeumer.tex}~: the famous ``Tr\"aumerei'' by
+Robert {\sc Schumann}\index{Schumann, R.@{\sc Schumann, R.}} for piano, in genuine
+\musixtex\ but with some
+additions to perform ascending bitmapped \itxem{crescendos}.
+There are also S-shaped slurs between 2 staves.
 
-\subsection{Starting from your usual plain format}
-\begin{enumerate}
- \item First, try to find --- on your favourite system --- whether \verb|tex|
-is an executable routine, or a \verb|tex.bat| command in MS-DOS or a
-\ital{shell} procedure under \unix.
- \item If \verb|tex| is a command try to find the ``{\tt initex}'' local
-command: usually it is either \verb|initex| or \verb|tex -i|.
- \item Try to find the name of the ``plain \TeX'' format (usually posted
-when \TeX ing anything).
- \item Then, \ital{mutatis mutandis}, assuming the ``{\tt initex}'' command
-has the name \verb|initex| and the ``plain \TeX'' format is \verb|plain|, run
-the shell command:
+ \item{\tt parnasum.tex}~: the first page of ``Doctor gradus ad
+Parnassum'' by Claude {\sc Debussy}\index{Debussy,
+C.@{\sc Debussy, C.}} for piano.
+It contains a rather complex example of a new command \verb+\Special+
+to create staff-jumping doubly beamed notes.
+\end{itemize}
 
- \medskip
- \verb|initex  \&plain musixtex.ins|
+\subsection{Additional documentation}
 
- \medskip\noindent which will produce a format file {\tt musixtex.fmt} which
-you shall put in the same directory  as the others formats (hoping you have
-the access rights...). Note --- in \unix{} systems --- the backslash before
-the \verb|&| which tells the system to consider this character as a member of
-the command, not a batch execution indication. Once this is done, you can
-\musixtex\ any score you have written using a command such as:
+\begin{itemize}\setlength{\itemsep}{0ex}
 
- \medskip
- \verb|tex \&musixtex my-score.tex|
+ \item{\tt sottieng}~:  Notation mistakes, provided by Jean-Pierre Coulon.
 
- \medskip\noindent that is, specifying your new format {\tt musixtex.fmt}
-instead of the usual {\tt plain.fmt}.
+\end{itemize}
 
- For \ixem{MS-DOS}/{\tt emTeX} users the format building command is:
+\section{Compiling musixdoc.tex}
+\subsection{Command sequence}
 
- \verb|tex386 -i &plain musixtex.ins|
+This is an example of a command sequence (in fact this is the normal procedure for La\TeX\ files). \verb|musixdoc.tex| is a large file, if you use an older version of La\TeX, use ``elatex'' in the command file.
+\begin{quote}\begin{verbatim}
+latex musixdoc
+musixflx musixdoc
+latex musixdoc
+makeindex -l musixdoc
+latex musixdoc
+(may require several more runs of elatex to get rid of
+    "labels may have changed ..." warnings)
+dvips -ta4 musixdoc
+\end{verbatim}\end{quote}
 
- \noindent (you can change \verb|plain| into \verb|dc-plain| or any other
-plain-like format you have) then:
+To produce \verb|musixdoc.pdf|, open \verb|musixdoc.ps| in \texttt{GSview}. Go to
+\verb+File|Convert+, select \verb|pdfwrite| at 600 dpi resolution, click
+\verb|OK|.
 
- \verb|copy musixtex.fmt \emtex\btexfmts\*.*|
+\subsection{Using batch files}
+There are
+many other files that are required to compile this document but all of them
+are included in \verb|musixtex.zip|, and will be placed in the proper locations
+if you have followed the installation instructions for \musixtex.
 
- \noindent and the {\tt musixtex.bat} command can be
+The two following batch files reside in the same dir as \texttt{musixdoc.tex} (or \texttt{musixdoc114.tex}).
 
-% It makes no sense to state -mt20000, perhaps this is useful for MusicTeX,
-% (it uses hyphenation to break a line) but not for MusiXTeX (it uses musixflx)
+This batch file makes a DVI, Postscript and PDF file, then displays the Postscript file.
+The full path names are shown as a comment.
+{\small
 \begin{quote}\begin{verbatim}
-if exist %1.tex goto tex
-goto end
-
-:tex
-if exist %1.mx1 del %1.mx1
-if exist %1.mx2 del %1.mx2
-tex386 -mt20000 &musixtex %1 %2 %3 %4 %5 %6 %7 %8 %9
-
-if errorlevel 2 goto end
+rem filename: lapdfview
+LATEX.EXE %1 %2.tex
+if errorlevel 1 goto end
+makeindex -l  %1
+rem C:\musixtex\system\musixflx\win32\musixflx %1
 musixflx %1
-
+LATEX.EXE %1 %2.tex
 if errorlevel 1 goto end
-tex386 -mt20000 &musixtex %1 %2 %3 %4 %5 %6 %7 %8 %9
-
+rem C:\"Program Files\MiKTeX 2.7"\miktex\bin\DVIPS.EXE -e0 -t a4 -P pdf -G0 %1.dvi
+DVIPS.EXE -e0 -t a4 -P pdf -G0 %1.dvi
+rem C:\"program files"\gs\gs8.63\bin\gswin32c -dBATCH ^
+rem -dNOPAUSE -sDEVICE=pdfwrite -r600 \
+rem -sOutputFile=%1.pdf -c save pop -f %1.ps
+gswin32c -dBATCH -dNOPAUSE -sDEVICE=pdfwrite -r600 ^
+-sOutputFile=%1.pdf -c save pop -f %1.ps
+pause
+rem C:\"program files"\Ghostgum\gsview\gsview32.exe %1.ps
+gsview32.exe %1.ps
+rem pause
 :end
- \end{verbatim}\end{quote}
-\end{enumerate}
-
-\begin{flushright}\it
-Don't expect a perfect package or miracles.\\
-There will be enough unexpected miracles.\\[\smallskipamount]
-{\sc Eberhard Mattes}
-\end{flushright}
-
-\chapter{Examples}
- Due to compatibility problems with \LaTeX\ (used to produce this notice)
-large examples must be \TeX -ed separately, i.e.\ using plain \TeX{} and not
-\LaTeX. Therefore, the \musixtex\ future user is suggested to produce some of
-the following examples and to look carefully at the way some special features
-have been coded.
-
- When producing this examples, care should be taken about the fact
-that several given files are supposed to be included (by means of
-\keyindex{input}) in other files. Thus the only good files to be directly
-\TeX-ed are those which begin with \verb|\input musixtex| or
- \verb|% \input musixtex|. This latter command is often commented out so that
-the examples can be run either using a \musixtex\ format including {\tt
-musixcpt.tex} and {\tt musixsty.tex} --- namely the format generated by {\tt
-musixtex.ins} --- or using a \musictex\ format including {\tt musictrp.tex},
-{\tt musicvbm.tex} and {\tt musicsty.tex} --- namely the format generated by
-{\tt musixtex.ins}.
-
-In addition, it must be noted that most DVI previewers and laser printers have
-their origin at one inch below and one inch right of the right upper corner
-of the paper, while the musical examples have their upper left significant
-corner only at one centimeter right and below the left top of the paper.
-Therefore, special parameters have to be given to the DVI transcription
-programs unless special \keyindex{hoffset} and \keyindex{voffset} \TeX\
-commands are introduced within the source \TeX\ text.
-
-\section{Clean \musixtex\ examples}
-
-\begin{itemize}
- \item{\tt avemaria.tex} to get the ``M\'editation'' (alias ``Ave Maria'') by
-Charles {\sc Gounod} for organ and violin or song in clean \musixtex-input.
-\index{Gounod, C.@{\sc Gounod, C.}}
- \item{\tt traeumer.tex} to get the famous ``Tr\"aumerei'' by
-Robert {\sc Schumann} for piano, in genuine \musixtex-input but with some
-additions to perform ascending \itxem{crescendos}.
-\index{Schumann, R.@{\sc Schumann, R.}}
- \item{\tt parnasum.tex} to get the first page of ``Doctor gradus ad
-Parnassum'' by Claude {\sc Debussy} for piano.\index{Debussy,
-C.@{\sc Debussy, C.}}
- \item{\tt glorias.tex} to get a local melody for the French version of
-\ital{Gloria in excelsis Deo}, showing use of lyrics commands. {\tt
-gloriab.tex} is the same, with organ accompaniment.
- \item Other clean \musixtex\ examples seem to be no more compatible with
-the present version, but they should be updated in a near future.
-\end{itemize}
-
-These examples are packed (zipped) in the {\ttxem{musixexa.zip}} file of the
-\musixtex\ distribution.
-
-\section{Nearly compatible \musictex\ examples}
-
-These are examples using not only {\tt musixtex} but also {\tt musixcpt} and
-{\tt musixsty}, which means their coding is easily understandable for
-\musictex{} previous users. However, they cannot be run as is with \musictex,
-since a few specific commands have been included, either for spacing, or for
-oblique slurs. They are given in {\tt musixexa.zip}, for example:
-
- \begin{itemize}
- \item {\tt gymnoman}~: an imitation of Erik {\sc Satie}'s
-\ital{Gymnop\'edies}\index{Satie, E.@{\sc Satie, E.}},
- \item {\tt canticor.tex}/{\tt canticox.tex}~:
-a famous tune by Georg Friedrich {\sc Haendel}\index{Haendel, G.F.@{\sc
-Haendel, G.F.}},
- \item {\tt ilfaitda.tex}/{\tt ilfaitdx.tex}~: a famous choral by J.-S.
-{\sc Bach}\index{Bach, J.S.@{\sc Bach, J.S.}} adapted with French lyrics for
-French churches,
- \item {\tt widor\_20.tex}~: the famous toccata for organ by Charles-Marie {\sc
-Widor}\index{Widor, C.M.@{\sc Widor, C.M.}} in 10 pages (more compact than
-commercial editions, and easier to play if nobody can turn the pages), and
-{\tt widor\_16.tex} which is the same in 16~pt size, i.e. more compact.
- \item{\tt souveni*.tex}~: a nice French tune of the fifties, by Oreste {\sc
-Rossi} and Fernand {\sc Capitani} with several transpositions.
- \item {\tt marcello.tex}~: the adagio of Benedetto {\sc
-Marcello}\index{Marcello, B.@{\sc Marcello, B.}}'s oboe concerto, transcribed
-for organ.
- \item {\tt hymnepas.tex}~: a modern Eastern canticle by A. {\sc Gouzes} and
-{\sc Palestrina}, showing heavy use of \keyindex{hardlyrics} for choral
-music.\index{Gouzes, A.@{\sc Gouzes, A.}}
-
- \end{itemize}
-
-\section{Compatible \musictex\ examples}
-
-They are all the examples provided in the \musictex\ distribution. To run them
-the easiest way is to have both a {\tt musictex} and a {\tt musixtex} format as
-described in \ref{formatbuild}. Otherwise, insert
-
- \verb|\input musixtex|
-
- \verb|\input musixcpt|
-
- \verb|\input musixsty|
-
- \noindent at the beginning of each example, and \TeX\ it.
-
- \section{Looking at examples before installing \musixtex}
-
- Most of the above examples (and some others) are posted, ready to print, as
-PostScript files in:
- \begin{itemize}
- \item {\tt ftp://hprib.lps.u-psud.fr/pub/music\_scores.zip/*/*/*.zip} (zipped
-PostScript 300dpi files)
- \item {\tt ftp://hprib.lps.u-psud.fr/pub/music\_scores.gz/*/*/*.ps.gz} (gzipped
-PostScript 300dpi files)
- \end{itemize}
-
- Printing them on any PostScript printer (needs A4 paper) is a good means of
-getting an overview of \musixtex's capabilities.
+\end{verbatim}\end{quote}
+}
 
+This batch file searches the folder for tex files and calls \texttt{lapdfview.bat}
+{\small
+\begin{quote}\begin{verbatim}
+rem latexall.bat
+rem proces all files with extension tex in this directory
+for /F %%I in ('dir /B *.tex') do call lapdfview.bat %%~nI
+pause
+\end{verbatim}\end{quote}
+}
 
-\printindex
+Thus, to produce \texttt{musixdoc.pdf}, double click on \texttt{latexall.bat}.
 
 \clearpage
 {\parindent0pt
@@ -8054,7 +9125,9 @@ number instead of the pitch}%
 %
 % clefs
 %
-\setclefsymbol1\empty \nostartrule\contpiece
+\setclefsymbol1\empty
+%\setlines 11\relax
+\nostartrule\contpiece
 \NOtes
   \zchar{13}{\bs trebleclef}\zchar0\trebleclef\sk
   \zchar9{\bs altoclef}\zchar0\altoclef\sk
@@ -8070,6 +9143,7 @@ number instead of the pitch}%
 %
 % Rests
 %
+\setlines 15\relax
 \resetclefsymbols\startrule\contpiece
 \NOtes
 \multnoteskip{.5}%
@@ -8175,6 +9249,34 @@ number instead of the pitch}%
 \rightrepeat
 \NOtes
   \loffset2{\zchar{-4}{\bs rightrepeat}}\en
-\endpiece\eject}%
+\endpiece\advance\textheight-40mm\eject%
 \endmuflex
+}
+
+%\makeatletter
+%\renewenvironment{theindex}{\newpage
+% \addcontentsline{toc}{chapter}{Index}%
+% \pagestyle{plain}
+% \let\item\@idxitem
+% \parskip\z@ \@plus .3\p@\relax
+% \begin{multicols}{2}[{\Huge\bfseries Index} ]
+% \par\bigskip}%
+%{\end{multicols}}%
+%\makeatother
+%\printindex
+
+\makeatletter
+\renewenvironment{theindex}{\newpage
+ \setcounter{secnumdepth}{-1}
+ \chapter[Index]{}\vspace*{-3cm}
+% \addcontentsline{toc}{chapter}{Index}
+  \pagestyle{plain}
+ \let\item\@idxitem
+ \parskip\z@ \@plus .3\p@\relax
+ \begin{multicols}{3}[{\Huge\bfseries Index} ]
+ \par\bigskip}%
+{\end{multicols}}%
+\makeatother
+ \printindex
+
 \end{document}