1 files changed, 233 insertions, 0 deletions
diff --git a/macros/generic/musixtex/doc/musixdoc/restsdoc.tex b/macros/generic/musixtex/doc/musixdoc/restsdoc.tex
new file mode 100644
index 0000000000..2bf4aebfb6
--- /dev/null
+++ b/macros/generic/musixtex/doc/musixdoc/restsdoc.tex
@@ -0,0 +1,233 @@
+\chapter{Rests}
+ \section{Ordinary rests}
+ 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}, 
+half rest \keyindex{hpause} or \keyindex{hp}, 
+quarter rest \keyindex{qp} or \keyindex{soupir},
+eighth rest \keyindex{ds}, sixteenth rest \keyindex{qs},
+$32$nd~rest \keyindex{hs}, and $64$th rest \keyindex{qqs}.
+Dotted rests may be obtained by 
+using 
+\keyindex{pausep}, 
+\keyindex{hpausep} or \keyindex{hpp}, \keyindex{qpp}, \keyindex{dsp}, \keyindex{qsp},
+\keyindex{hsp} and \keyindex{qqsp}, 
+and double-dotted rests by
+\keyindex{pausepp}, 
+\keyindex{hpausepp} or \keyindex{hppp}, \keyindex{qppp}, \keyindex{dspp}, \keyindex{qspp},
+\keyindex{hspp} and \keyindex{qqspp},.
+
+
+ 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
+\end{music}
+ %\check
+\noindent
+The command \keyindex{Hpause} $p$ $n$ provides an arbitrary length pause at pitch
+$p$ and of length $n$ \keyindex{noteskip}.  For example,
+\verb|\NOTes\Hpause4{0.83}\en|
+produces
+
+\begin{music}
+\nostartrule
+\startextract
+\NOTes\Hpause4{0.83}\en
+\endextract
+\end{music}
+
+
+ \section{Raising rests and non-spacing rests}\index{raising rests}
+All the
+previous rests (except \keyindex{pausep},
+\keyindex{hpausep} and \keyindex{Hpause})  are \ital{hboxes}, which means that
+they can be vertically offset if needed using the
+standard \TeX\ command \keyindex{raise}. For example:
+
+ \begin{quote}
+ \begin{verbatim}
+ \raise 2\Interligne\qp
+ \raise 3mm\qqs
+ \end{verbatim}
+ \end{quote}
+
+\noindent where \keyindex{Interligne} is the distance from one staff line to the
+next.
+Similarly, non-spacing rests may be coded using the \TeX\ command \keyindex{rlap}, as in
+
+\begin{music}\nostartrule
+\startextract
+\notes\ibbu0h{-1}\zccl e\qb0h\raise-4\Interligne\rlap\qs\qb0e\en
+\notes\raise-4\Interligne\rlap\ds\qb0f\tqu0g\en
+\endextract
+\end{music}\noindent
+for which the coding is
+\begin{verbatim}
+\notes\ibbu0h{-1}\zccl e\qb0h\raise-4\Interligne\rlap\qs\qb0e\en
+\notes\raise-4\Interligne\rlap\ds\qb0f\tqu0g\en
+\end{verbatim}
+
+In addition, four special macros are available to raise or lower a whole or
+half rest. 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
+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$ to get
+  \hbox to10pt{\lifthpause{-1}\hss} raised the same way.
+ \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$ to get
+  \hbox to10pt{\lifthpausep{-1}\hss} raised the same way.
+ \end{itemize}
+
+ %\check
+ \section{Bar-centered rests}\label{barcentered}
+Sometimes it is necessary to place a rest (or some other symbols) exactly in the middle
+of the notes region of a bar
+(i.e., excluding any initial clef and key or time signatures).
+This can usually be done with combinations of the commands
+\keyindex{atnextbar},
+\keyindex{centerbar},
+\keyindex{cPAUSe},
+\keyindex{cPAuse},
+\keyindex{cpause},
+\keyindex{chpause},
+\keyindex{cHpause} $n$,
+as demonstrated in the following example:
+
+\begin{music}
+\generalmeter\meterC
+\generalsignature{3}
+\setclef1\bass
+\setstaffs1{2}
+\parindent0pt
+\startextract
+\NOtes|\qa{cegj}\en
+\def\atnextbar{\znotes\centerbar{\cpause}|\en}%
+\generalsignature{-3}\changecontext
+\NOTes\ha{Nc}|\en
+\def\atnextbar{\znotes|\centerbar{\cpause}\en}%
+\setclef1\alto\changeclefs%
+\generalmeter{\meterfrac21}\changecontext%
+\NOTEs\wh d\pause|\en
+\def\atnextbar{\znotes|\centerbar{\cPAuse}\en}%
+\bar
+\NOTEs|\en
+\def\atnextbar{\znotes\centerbar{\cHpause{12}}|\centerbar{\cHpause{12}}\en}%
+\endextract
+\end{music}
+\noindent with the coding
+\begin{verbatim}
+\generalmeter\meterC
+\generalsignature{3}
+\setclef1\bass
+\setstaffs1{2}
+\parindent0pt
+\startextract
+\NOtes|\qa{cegj}\en
+\def\atnextbar{\znotes\centerbar{\cpause}|\en}%
+\generalsignature{-3}\changecontext
+\NOTes\ha{Nc}|\en
+\def\atnextbar{\znotes|\centerbar{\cpause}\en}%
+\setclef1\alto\changeclefs%
+\generalmeter{\meterfrac21}\changecontext%
+\NOTEs\wh d\pause|\en
+\def\atnextbar{\znotes|\centerbar{\cPAuse}\en}%
+\bar
+\NOTEs|\en
+\def\atnextbar{\znotes\centerbar{\cHpause{12}}|\centerbar{\cHpause{12}}\en}%
+\endextract
+\end{verbatim}\noindent
+
+The following abbreviations are provided:
+\begin{quote}
+\begin{tabular}{lcl}
+\keyindex{centerpause}& for & \verb|\centerbar{\cpause}|\\
+\keyindex{centerhpause}& for & \verb|\centerbar{\chpause}|\\
+\keyindex{centerPAuse}& for & \verb|\centerbar{\cPAuse}|\\
+\keyindex{centerPAUSe}& for & \verb|\centerbar{\cPAUSe}|\\
+\keyindex{centerHpause} $n$ & for & \verb|\centerbar{\cHpause| $n$\verb|}|
+\end{tabular}
+\end{quote}
+Material other than these rests may be used as arguments to
+\verb|\centerbar|, as in:\\ 
+\begin{music}
+\nostartrule
+\generalmeter\meterC
+\parindent0pt
+\startextract
+\NOTEs\sk\hqsk\en\def\atnextbar{\znotes\centerbar{\ccn{9}{\meterfont7}}%
+\centerbar{\cPAUSe\off{2\elemskip}\cPAuse\off{2\elemskip}\cpause}\en}\bar
+\NOtes\ql{ghij}\en
+\def\atnextbar{\znotes\centerbar{\liftpause2}\en}\bar
+\NOTes\en
+\def\atnextbar{\znotes\centerbar{\duevolte}\en}\bar
+\NOTes\en
+\def\atnextbar{\znotes\loffset{0.7}{\centerbar{\Fermataup l\wh j}}\en}
+\endextract
+\end{music}
+\noindent for which the coding is:
+\begin{verbatim}
+\generalmeter\meterC
+\parindent0pt
+\startextract
+\NOTEs\en\def\atnextbar{\znotes\centerbar{\ccn{9}{\meterfont7}}%
+\centerbar{\cPAUSe\off{2\elemskip}\cPAuse\off{2\elemskip}\cpause}\en}\bar
+\NOtes\ql{ghij}\en
+\def\atnextbar{\znotes\centerbar{\liftpause2}\en}\bar
+\NOTes\en
+\def\atnextbar{\znotes\centerbar{\duevolte}\en}\bar
+\NOTes\en
+\def\atnextbar{\znotes\loffset{0.7}{\centerbar{\Fermataup l\wh j}}\en}
+\endextract
+\end{verbatim}
+In the last measure, 
+it has been necessary to use \keyindex{loffset} to correct the centering of 
+the off-center command
+\verb|\wh|\ldots.
+
+%To get proper positioning of \keyindex{centerbar} material before
+%a clef change, you may use an invisible bar line as in
+%\begin{quote}
+%\begin{verbatim}
+%\setclef1\bass
+%\startextract%
+%\NOTEs\Hpause4{0.83}\en
+%\def\atnextbar{\znotes\centerbar{\ccn9{\meterfont{4}}}\en}%
+%\qspace\setemptybar\bar%  invisible bar line
+%\setclef1\alto\zchangeclefs\bar%
+%\NOtes\qa{abcd}\en
+%\endextract
+%\end{verbatim}
+%\end{quote}
+%which produces
+%
+%\begin{music}
+%\nostartrule
+%\nobarnumbers
+%\setclef1\bass
+%\startextract%
+%\NOTEs\Hpause4{0.83}\en
+%\def\atnextbar{\znotes\centerbar{\ccn9{\meterfont{4}}}\en}%
+%%\qspace\setemptybar\bar%  invisible bar line
+%\setclef1\alto\changeclefs\bar%
+%\NOtes\qa{abcd}\en
+%\endextract
+%\end{music}