X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frhythms.itely;h=b716ab08a055cb359b24321881ae1690a02e737b;hb=dc8e9c050a98c809e66b10d9ae1d3df9d3b0190f;hp=83ecb95d70ea09b8afa46593693fb59285c49fd7;hpb=f436cbf790e4a6100bf2b21e4fb2ff9f3dfcc3cf;p=lilypond.git

diff --git a/Documentation/user/rhythms.itely b/Documentation/user/rhythms.itely
index 83ecb95d70..b716ab08a0 100644
--- a/Documentation/user/rhythms.itely
+++ b/Documentation/user/rhythms.itely
@@ -6,15 +6,11 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.38"
+@c \version "2.11.61"
 
 @ignore
 GDP TODO list
 
-\compressMusic -> \scaleDurations.
-approved by Han-Wen; just needs somebody to kick up a fuss about
-it.
-
 1.2.3.1 Time signature
 Needs an example of beatLength, which is broken (see my recent
 mail
@@ -43,12 +39,12 @@ days ago).  Text left in Snippets: with TODO.
 This section discusses rhythms, rests, durations, beaming and bars.
 
 @menu
-* Writing rhythms::             
-* Writing rests::               
-* Displaying rhythms::          
-* Beams::                       
-* Bars::                        
-* Special rhythmic concerns::   
+* Writing rhythms::
+* Writing rests::
+* Displaying rhythms::
+* Beams::
+* Bars::
+* Special rhythmic concerns::
 @end menu
 
 
@@ -56,10 +52,10 @@ This section discusses rhythms, rests, durations, beaming and bars.
 @subsection Writing rhythms
 
 @menu
-* Durations::                   
-* Tuplets::                     
-* Scaling durations::           
-* Ties::                        
+* Durations::
+* Tuplets::
+* Scaling durations::
+* Ties::
 @end menu
 
 @node Durations
@@ -141,9 +137,9 @@ proportional notation, see @ref{Proportional notation}.
 @funindex \dotsNeutral
 
 Dots are normally moved up to avoid staff lines, except in
-polyphonic situations.  Predefined commands are available to 
+polyphonic situations.  Predefined commands are available to
 force a particular direction manually, for details
-see @ref{Controlling direction and placement}.
+see @ref{Direction and placement}.
 
 @predefined
 
@@ -210,7 +206,6 @@ the notes are 2/3 of their written length.
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 a2 \times 2/3 { b4 b b }
 c4 c \times 2/3 { b4 a g }
-
 @end lilypond
 
 @funindex \tupletUp
@@ -219,7 +214,7 @@ c4 c \times 2/3 { b4 a g }
 
 The automatic placement of the tuplet bracket above or below the
 notes may be overridden manually with predefined commands, for
-details see @ref{Controlling direction and placement}.
+details see @ref{Direction and placement}.
 
 Tuplets may be nested:
 
@@ -249,15 +244,15 @@ see @ref{Scaling durations}.
 @funindex tupletNumberFormatFunction
 @funindex tupletSpannerDuration
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {entering-several-tuplets-using-only-one--times-command.ly}
 
 @funindex TupletNumber
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-the-tuplet-number.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {permitting-line-breaks-within-beamed-tuplets.ly}
 
 @seealso
@@ -272,7 +267,7 @@ Learning Manual: @rlearning{Tweaking methods}.
 Notation Reference:
 @ref{Time administration},
 @ref{Scaling durations},
-@ref{Objects connected to the input},
+@ref{The tweak command},
 @ref{Polymetric notation}.
 
 Snippets:
@@ -285,7 +280,7 @@ Internals Reference:
 
 @knownissues
 @cindex grace notes within tuplet brackets
-When the very first note on a staff is a grace note followed by a
+When the first note on a staff is a grace note followed by a
 tuplet the grace note must be placed before the @code{\times}
 command to avoid errors.  Anywhere else, grace notes may be
 placed within tuplet brackets.
@@ -297,8 +292,6 @@ placed within tuplet brackets.
 @cindex scaling durations
 @cindex durations, scaling
 
-TODO Change \compressMusic to \scaleDurations when implemented.
-
 You can alter the duration of single notes, rests or chords by a
 fraction @code{N/M} by appending @code{*N/M} (or @code{*N} if
 @code{M} is 1) to the duration.
@@ -327,34 +320,26 @@ a multiplier.  This is useful for skipping many measures, e.g.,
 @code{s1*23}.
 
 @cindex compressing music
-@funindex \compressMusic
-
-Longer stretches of music may be compressed by a fraction in
-the same way, as if every note, chord or rest had the fraction
-as a multiplier.  The general syntax of the command to do this
-is:
-
-@example
-\compressMusic #'(@emph{num} . @emph{den}) @{ @emph{music} @}
-@end example
+@funindex \scaleDurations
 
-@noindent
-This will leave the appearance of @emph{music} unchanged but
+Longer stretches of music may be compressed by a fraction in the
+same way, as if every note, chord or rest had the fraction as a
+multiplier.  This leaves the appearance of the music unchanged but
 the internal duration of the notes will be multiplied by the
-fraction @emph{num}/@emph{den}.  The spaces around the dot
-are required.  Here is an example showing how music can be
-compressed and expanded:
+fraction @emph{num}/@emph{den}.  The spaces around the dot are
+required.  Here is an example showing how music can be compressed
+and expanded:
 
 @lilypond[quote,fragment,relative=2,ragged-right,verbatim]
 \time 2/4
 % Normal durations
 <c a>4 c8 a
 % Scale music by *2/3
-\compressMusic #'(2 . 3) {
+\scaleDurations #'(2 . 3) {
   <c a f>4. c8 a f
 }
 % Scale music by *2
-\compressMusic #'(2 . 1) {
+\scaleDurations #'(2 . 1) {
   <c' a>4 c8 b
 }
 @end lilypond
@@ -368,7 +353,7 @@ notation, see @ref{Polymetric notation}.
 
 Notation Reference:
 @ref{Tuplets},
-@ref{Skips},
+@ref{Invisible rests},
 @ref{Polymetric notation}.
 
 Snippets:
@@ -392,7 +377,7 @@ duration, similar to the augmentation dot.}
 A tie is entered using the tilde symbol @code{~}
 
 @lilypond[quote,ragged-right,fragment,verbatim]
-e' ~ e'
+e'2 ~ e'
 @end lilypond
 
 
@@ -454,7 +439,7 @@ piano, harp and other string and percussion instruments.  They can
 be entered as follows:
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=1]
-<c f g>\laissezVibrer
+<c f g>1\laissezVibrer
 @end lilypond
 
 @cindex ties, placement
@@ -464,7 +449,7 @@ be entered as follows:
 
 The vertical placement of ties may be controlled, see
 Predefined commands, or for details, see
-@ref{Controlling direction and placement}.
+@ref{Direction and placement}.
 
 @cindex ties, appearance
 @funindex \tieDotted
@@ -487,10 +472,10 @@ commands.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {using-ties-with-arpeggios.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {engraving-ties-manually.ly}
 
 
@@ -527,15 +512,18 @@ well-defined.  In these cases, a slur may be preferable.
 @node Writing rests
 @subsection Writing rests
 
+Rests are entered as part of the music in music expressions.
+
 @menu
-* Rests::                       
-* Skips::                       
-* Full measure rests::          
+* Rests::
+* Invisible rests::
+* Full measure rests::
 @end menu
 
 @node Rests
 @subsubsection Rests
 @cindex rest
+@cindex rest, entering durations
 @cindex maxima
 @cindex longa
 @cindex breve
@@ -546,8 +534,9 @@ well-defined.  In these cases, a slur may be preferable.
 @funindex \longa
 @funindex \breve
 
-Rests are entered like notes with the note name @code{r};
-longer rests with the predefined commands shown:
+Rests are entered like notes with the note name @code{r}.
+Durations longer than a whole rest use the predefined
+commands shown:
 
 @c \time 16/1 is used to avoid spurious bar lines
 @c and long tracts of empty measures
@@ -562,20 +551,25 @@ longer rests with the predefined commands shown:
   r\longa
   % Print a breve rest
   r\breve
-  r1 r2 r4 r8 r16 r32 r64
+  r1 r2 r4 r8 r16 r32 r64 r128
 }
 @end lilypond
 
-Whole measure rests, centered in the middle of the measure, must
-be entered as multi-measure rests.  They can be used for a single
-measure as well as many measures and are discussed in
-@ref{Full measure rests}.
+@cindex rest, multi-measure
+@cindex rest, whole-measure
+
+Whole measure rests, centered in the middle of the measure, must be
+entered as multi-measure rests.  They can be used for a single
+measure as well as many measures and are discussed in @ref{Full
+measure rests}.
+
+@cindex rest, specifying vertical position
 
 To explicitly specify a rest's vertical position, write a note
-followed by @code{\rest}.  A rest will be placed in the position
-where the note would appear.  This allows for precise manual
-formatting of polyphonic music, since the automatic rest collision
-formatter will leave these rests alone.
+followed by @code{\rest}.  A rest of the duration of the note will
+be placed at the staff position where the note would appear.  This
+allows for precise manual formatting of polyphonic music, since the
+automatic rest collision formatter will not move these rests.
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 a4\rest d4\rest
@@ -583,18 +577,20 @@ a4\rest d4\rest
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {rest-styles.ly}
 
 
 @seealso
 
-Notation Reference: @ref{Full measure rests}
+Notation Reference:
+@ref{Full measure rests}.
 
 Snippets:
 @rlsr{Rhythms}.
 
-Internals Reference: @rinternals{Rest}
+Internals Reference:
+@rinternals{Rest}.
 
 
 @knownissues
@@ -604,63 +600,60 @@ There is no fundamental limit to rest durations (both in terms of
 longest and shortest), but the number of glyphs is limited: there
 are rests from 128th to maxima (8 x whole).
 
-@node Skips
-@subsubsection Skips
+
+@node Invisible rests
+@subsubsection Invisible rests
 
 @cindex skip
 @cindex invisible rest
 @cindex rest, invisible
 @cindex spacer note
-
-@funindex \skip
 @funindex s
+@funindex \skip
 
-An invisible rest (also called a @q{skip rest}) can be entered like a
-note with note name @code{s} or with the predefined skip command
-followed by the required duration, as shown here:
+An invisible rest (also called a @q{spacer rest}) can be entered
+like a note with the note name@tie{}@code{s}:
 
-@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-% Skip the third beat in the first measure
-a4 a4 s4 a4
-% Use skip command to skip a whole note (measure)
-\skip 1
-a2 a2
+@lilypond[verbatim,quote,relative=2]
+c4 c s c
+s2 c
 @end lilypond
 
 @cindex lyrics, skip
 
-The @code{s} syntax is only available in note mode and chord mode.
-In other situations, for example, when entering lyrics, one must
-use the predefined skip command:
+Spacer rests are available only in note mode and chord mode.  In
+other situations, for example, when entering lyrics, @code{\skip}
+is used to skip a musical moment.  @code{\skip} requires an
+explicit duration.
 
 @lilypond[quote,ragged-right,verbatim,relative=2]
 <<
-  { a2 a2 }
-  \new Lyrics \lyricmode { \skip 2 bla2 }
+  {
+    a2 \skip2 a2 a2
+  }
+  \new Lyrics {
+    \lyricmode {
+      foo2 \skip 1 bla2
+    }
+  }
 >>
 @end lilypond
 
-The @code{s} skip rest implicitly causes @code{Staff} and
-@code{Voice} contexts to be created if none exist, just
-like notes and rests do.  These in turn cause a staff with default
-clef and time signature to be printed, with bar lines if necessary.
-For example, the following results in a complete staff with three
-short empty measures:
+A spacer rest implicitly causes @code{Staff} and @code{Voice}
+contexts to be created if none exist, just like notes and rests
+do:
 
-@lilypond[quote,verbatim,fragment,ragged-right]
-{ s1 s s }
+@lilypond[quote,verbatim,fragment]
+s1 s s
 @end lilypond
 
-However, the predefined skip command behaves differently: it is
-merely an empty musical placeholder.  It does not create any 
-contexts and does not cause anything to be printed, not even 
-transparently.  On its own it does not even print an
-empty page:
+@code{\skip} simply skips musical time; it creates no output of
+any kind.
 
-@example
+@lilypond[quote,verbatim,fragment]
 % This is valid input, but does nothing
-@{ \skip 1 @}
-@end example
+\skip 1 \skip1 \skip 1
+@end lilypond
 
 @seealso
 
@@ -684,7 +677,7 @@ Rests for one or more full measures are entered like notes with
 the note name uppercase @code{R}:
 
 @lilypond[quote,fragment,verbatim,relative=2]
-% Rest bars contracted to single bar
+% Rest measures contracted to single measure
 \compressFullBarRests
 R1*4
 R1*24
@@ -692,15 +685,44 @@ R1*4
 b2^"Tutti" b4 a4
 @end lilypond
 
+The duration of full-measure rests is identical to the duration notation
+used for notes.  The duration in a multi-measure rest must always be an
+integral number of measure-lengths, so augmentation
+dots or fractions must often be used:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\compressFullBarRests
+\time 2/4
+R1 | R2 |
+\time 3/4
+R2. | R2.*2 |
+\time 13/8
+R1*13/8 | R1*13/8*12 |
+\time 10/8
+R4*5*4 |
+@end lilypond
+
+A full-measure rest is printed as either a whole
+or breve rest, centered in the measure, depending on the time
+signature.
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\time 4/4
+R1 |
+\time 6/4
+R1*3/2 |
+\time 8/4
+R1*2 |
+@end lilypond
 @funindex \expandFullBarRests
 @funindex \compressFullBarRests
 @cindex multi-measure rest, expanding
 @cindex multi-measure rest, contracting
 
 By default a multi-measure rest is expanded in the printed score
-to show all the rest measures explicitly or (as in the example
-above) it can be contracted to a single measure containing a
-multi-measure rest symbol, with the number of measures of rest
+to show all the rest measures explicitly.
+Alternatively, a mult-measure rest can be shown as a single measure
+containing a multi-measure rest symbol, with the number of measures of rest
 printed above the measure:
 
 @lilypond[quote,ragged-right,fragment,verbatim]
@@ -717,26 +739,6 @@ r1 | R1*17 | R1*4 |
 R2.*2 |
 @end lilypond
 
-The @code{1} in @code{R1} is similar to the duration notation
-used for notes and is the length of a measure in 2/2 or 4/4 time.
-The duration in a multi-measure rest must always be an integral
-number of measure-lengths, so in other time signatures augmentation
-dots or fractions must be used:
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\compressFullBarRests
-\time 3/4
-R2. | R2.*2
-\time 13/8
-R1*13/8 | R1*13/8*12 |
-\time 10/8
-R4*5*4 |
-@end lilypond
-
-An @code{R} spanning a single measure is printed as either a whole
-or breve rest, centered in the measure, regardless of the time
-signature.
-
 
 @cindex text on multi-measure rest
 @cindex multi-measure rest, attaching text
@@ -745,9 +747,8 @@ signature.
 @cindex fermata on multi-measure rest
 @cindex multi-measure rest, attaching fermata
 
-Text can be added to multi-measure rests by using the
-@var{note} - @code{\markup} syntax described in
-@ref{Formatting text}.  The predefined command @code{\fermataMarkup}
+Markups can be added to multi-measure rests.
+The predefined command @code{\fermataMarkup}
 is provided for adding fermatas.
 
 @lilypond[quote,ragged-right,verbatim,fragment]
@@ -757,10 +758,12 @@ R2.*10^\markup { \italic "ad lib." }
 R2.^\fermataMarkup
 @end lilypond
 
-@warning{Text attached to a multi-measure rest is created
-by @code{MultiMeasureRestText}, not
+@warning{
+Markups attached to a multi-measure rest are
+objects of type @code{MultiMeasureRestText}, not
 @code{TextScript}.  Overrides must be directed to the correct
-object, or they will be ignored.  See the following example.}
+object, or they will be ignored.  See the following example.
+}
 
 @lilypond[quote,ragged-right,verbatim,fragment]
 % This fails, as the wrong object name is specified
@@ -771,38 +774,8 @@ R1^"wrong"
 R1^"right"
 @end lilypond
 
-Text attached to a multi-measure rest will be centered above or
-below it.  Long text attached in this way does not cause the
-measure to expand, and may collide with text in adjacent measures.
-This behavior may be changed with the predefined command
-@code{\textLengthOn}, which will cause following bars to expand
-as necessary to accommodate text.  @code{\textLengthOff} returns
-to the default behavior.  To left-align text within a bar attach
-it to a zero-length skip note preceding the rest.
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-\compressFullBarRests
-\textLengthOn
-s1*0^\markup { [MAJOR GENERAL] }
-R1*19
-s1*0^\markup { [MABEL] }
-s1*0_\markup { \italic { Cue: ... it is yours } }
-R1*30
-\textLengthOff
-c4^\markup { CHORUS } d f c
-@end lilypond
-
-@noindent
-Text attached to a skip note in this way is left-aligned to the
-position where the note would be placed in the measure, and placed
-above the measure count numeral, but if the measure length is
-determined by the length of the text, the text will appear to be
-centered.  If two (or more) texts are
-attached to skip notes in a measure the measure length is determined by
-the longer text, and the shorter text is then clearly
-left-aligned, as shown in the second measure above.  If the shorter
-text of two marks is short enough to fit it will be placed
-alongside and to the left of the measure count numeral.
+When a multi-measure rest immediately follows a @code{\partial}
+setting, resulting bar-check warnings may not be displayed.
 
 @predefined
 @code{\textLengthOn},
@@ -817,20 +790,44 @@ alongside and to the left of the measure count numeral.
 @cindex rest, church
 @cindex kirchenpausen
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {changing-form-of-multi--measure-rests.ly}
 
 @cindex multi-measure rests, positioning
 @cindex positioning multi-measure rests
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {positioning-multi--measure-rests.ly}
 
+@c TODO -- convert to snippet -- submitted to Neil
+Markups attached to a multi-measure rest will be centered above or
+below it.  Long markups attached to multi-measure rests do not cause
+the measure to expand. To expand a multi-measure rest to fit the markup,
+use a spacer rest with an attached markup before the multi-measure rest:
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\compressFullBarRests
+\textLengthOn
+s1*0^\markup { [MAJOR GENERAL] }
+R1*19
+s1*0_\markup { \italic { Cue: ... it is yours } }
+s1*0^\markup { A }
+R1*30^\markup { [MABEL] }
+\textLengthOff
+c4^\markup { CHORUS } d f c
+@end lilypond
+
+@noindent
+Note that the spacer rest causes a bar to be inserted.
+Text attached to a spacer rest in this way is left-aligned to the
+position where the note would be placed in the measure, but if the
+measure length is determined by the length of the text, the text will
+appear to be centered.
+
 @seealso
 
 Music Glossary:
-@rglos{multi-measure rest},
-@rglos{church rests}.
+@rglos{multi-measure rest}.
 
 Notation Reference:
 @ref{Durations},
@@ -855,34 +852,25 @@ fingering numeral (4) may collide with the bar counter
 numeral (10).
 
 @cindex condensing rests
-@cindex rests, condensing ordinary
+@cindex rest, condensing ordinary
 
 There is no way to automatically condense multiple ordinary rests
 into a single multi-measure rest.
 
-@cindex rests, collisions of
+@cindex rest, collisions of
 
 Multi-measure rests do not take part in rest collisions.
 
-Be careful when entering multi-measure rests followed by whole
-notes.  The following will enter two notes lasting four measures
-each:
-
-@example
-R1*4 cis cis
-@end example
-
-
 @node Displaying rhythms
 @subsection Displaying rhythms
 
 @menu
-* Time signature::              
-* Upbeats::                     
-* Unmetered music::             
-* Polymetric notation::         
-* Automatic note splitting::    
-* Showing melody rhythms::     
+* Time signature::
+* Upbeats::
+* Unmetered music::
+* Polymetric notation::
+* Automatic note splitting::
+* Showing melody rhythms::
 @end menu
 
 @node Time signature
@@ -901,18 +889,28 @@ The time signature is set as follows:
 
 @cindex Time signature, visibility of
 
-Time signatures by default are printed at the start of every line
+Time signatures are printed at the beginning of a piece
 and whenever the time signature changes.  If a change takes place
-at the end of a line a warning time signature sign is printed 
-there.  This default behavior may be changed, see 
-@ref{Controlling visibility of objects}.
+at the end of a line a warning time signature sign is printed
+there.  This default behavior may be changed, see
+@ref{Visibility of objects}.
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\time 2/4
+c2 c
+\break
+c c
+\break
+\time 4/4
+c c c c
+@end lilypond
 
 @funindex \numericTimeSignature
 @funindex \defaultTimeSignature
 @cindex time signature style
 
-The symbol that is printed in 2/2 and 4/4 time can be customized
-to use a numeric style:
+The time signature symbol that is used in 2/2 and 4/4 time can be
+changed to a numeric style:
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 % Default style
@@ -992,7 +990,7 @@ the 9/8 measure is subdivided in 2, 2, 2 and 3.  This is passed to
 @cindex compound time signatures
 @cindex time signature, compound
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
 {compound-time-signatures.ly}
 
 
@@ -1035,16 +1033,22 @@ Partial or pick-up measures, such as an anacrusis or upbeat, are
 entered using the @code{\partial} command, with the syntax
 
 @example
-\partial @var{duration} @emph{notes}
+\partial @var{duration} 
 @end example
 
-where @code{duration} is the rhythmic length of the @emph{notes}
-which are to be placed before the first complete measure:
+where @code{duration} is the rhythmic length of the interval
+before the start of the first complete measure:
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
-\partial 16*5 c16 cis d dis e |
+\partial 4 e4 |
+a2. c,4 |
+@end lilypond
+
+The partial measure can be any duration less than a full measure:
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\partial 8*3 c8 d e |
 a2. c,4 |
-b2
 @end lilypond
 
 Internally, this is translated into
@@ -1059,7 +1063,6 @@ that this is set to a negative number by the @code{\partial}
 command: i.e., @code{\partial 4} is internally translated to
 @code{-4}, meaning @qq{there is a quarter note left in the measure.}
 
-
 @seealso
 
 Music Glossary: @rglos{anacrusis}
@@ -1069,23 +1072,13 @@ Notation Reference: @ref{Grace notes}
 Snippets:
 @rlsr{Rhythms}.
 
-Internal Reference: @rinternals{Timing_translator}
+Internal Reference:
+@rinternals{Timing_translator}
 
 @knownissues
 
 @cindex grace notes, in anacruses
 
-This command does not take into account grace notes at the start
-of the music.  If the pick-up starts with one or more grace
-notes, then the @code{\partial} should follow the grace note(s):
-
-@lilypond[verbatim,quote,ragged-right,relative,fragment]
-\grace f16
-\partial 4
-g4
-a2 g2
-@end lilypond
-
 The @code{\partial} command is intended to be used only at the
 beginning of a piece.  If you use it after the beginning, some
 odd warnings may occur.
@@ -1101,10 +1094,10 @@ odd warnings may occur.
 @cindex unmetered music
 
 Bar lines and bar numbers are calculated automatically.  For
-unmetered music (cadenzas, for example), this is not desirable.
-To turn off automatic bar lines and bar numbers, use the command
-@code{\cadenzaOn}, and use @code{\cadenzaOff} to turn them on
-again.
+unmetered music (some cadenzas, for example), this is not desirable.
+To turn off automatic calculation of bar lines and bar numbers,
+use the command @code{\cadenzaOn}, and use @code{\cadenzaOff} 
+to turn them on again.
 
 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
 c4 d e d
@@ -1136,9 +1129,11 @@ d4 e d c
 
 @seealso
 
-Music Glossary: @rglos{cadenza}
+Music Glossary:
+@rglos{cadenza}
 
-Notation Reference: @ref{Controlling visibility of objects}
+Notation Reference:
+@ref{Visibility of objects}
 
 Snippets:
 @rlsr{Rhythms}.
@@ -1165,32 +1160,8 @@ to indicate where breaks can occur.
 @cindex polymetric signatures
 @cindex meter, polymetric
 
-@strong{Alternating time signatures}
-
-Regularly alternating double time signatures are not supported
-explicitly, but they can be faked.  In the next example, the
-double time signature is created with markup text, while the
-real time signature is set in the usual way with @code{\time}.
-
-@lilypond[verbatim,ragged-right]
-% Create 9/8 split into 2/4 + 5/8
-tsMarkup = \markup {
-  \override #'(baseline-skip . 2) \number {
-    \column { "2" "4" }
-    \vcenter "+"
-    \bracket \column { "5" "8" }
-  }
-}
-
-{
-  \override Staff.TimeSignature #'stencil =
-    #ly:text-interface::print
-  \override Staff.TimeSignature #'text = #tsMarkup
-  \time 9/8
-  c'2 \bar ":" c'4 c'4.
-  c'2 \bar ":" c'4 c'4.
-}
-@end lilypond
+Polymetric notation is supported, either explicitly or through
+clever use of markup features.
 
 @strong{Staves with different time signatures, equal measure lengths}
 
@@ -1198,7 +1169,7 @@ This notation can be created by setting a common time signature
 for each staff but replacing the symbol manually by setting
 @code{timeSignatureFraction} to the desired fraction and scaling
 the printed durations in each staff to the common time
-signature.  This done with @code{\compressMusic}, which
+signature.  This is done with @code{\scaleDurations}, which
 is used in a similar way to @code{\times}, but does not create
 a tuplet bracket, see @ref{Scaling durations}.
 
@@ -1217,13 +1188,13 @@ staff, shown durations are multiplied by 3/5, as 3/5 * 10/8 = 3/4.
   \new Staff {
     \time 3/4
     \set Staff.timeSignatureFraction = #'(9 . 8)
-    \compressMusic #'(2 . 3)
+    \scaleDurations #'(2 . 3)
       \repeat unfold 6 { c8[ c c] }
   }
   \new Staff {
     \time 3/4
     \set Staff.timeSignatureFraction = #'(10 . 8)
-    \compressMusic #'(3 . 5) {
+    \scaleDurations #'(3 . 5) {
       \repeat unfold 2 { c8[ c c] }
       \repeat unfold 2 { c8[ c] } |
       c4. c4. \times 2/3 { c8 c c } c4
@@ -1275,6 +1246,37 @@ moving the @code{Timing_translator} to the @code{Staff} context.
 >>
 @end lilypond
 
+@snippets
+
+@c TODO -- Convert to snippet. -- Sent to Neil 8/14/08
+
+@strong{Alternating time signatures}
+
+Regularly alternating double time signatures are not supported
+explicitly, but they can be faked.  In the next example, the
+double time signature is created with markup text, while the
+real time signature is set in the usual way with @code{\time}.
+
+@lilypond[verbatim,ragged-right]
+% Create 9/8 split into 2/4 + 5/8
+tsMarkup = \markup {
+  \override #'(baseline-skip . 2) \number {
+    \column { "2" "4" }
+    \vcenter "+"
+    \bracket \column { "5" "8" }
+  }
+}
+
+{
+  \override Staff.TimeSignature #'stencil =
+    #ly:text-interface::print
+  \override Staff.TimeSignature #'text = #tsMarkup
+  \time 9/8
+  c'2 \bar ":" c'4 c'4.
+  c'2 \bar ":" c'4 c'4.
+}
+@end lilypond
+
 
 @seealso
 
@@ -1292,14 +1294,17 @@ Snippets:
 
 Internals Reference:
 @rinternals{TimeSignature},
-@rinternals{Timing-translator},
+@rinternals{Timing_translator},
 @rinternals{Staff}.
 
 @knownissues
 
-When using different time signatures in parallel, the spacing is
-aligned vertically, but bar lines distort the regular spacing.
-
+When using different time signatures in parallel, notes
+at the same moment will be be placed at the same horizontal
+location.  However, the bar lines in the different staves
+will cause the note spacing to be less regular in each of the
+individual staves than would be normal without the different
+time signatures.
 
 @node Automatic note splitting
 @subsubsection Automatic note splitting
@@ -1309,7 +1314,7 @@ aligned vertically, but bar lines distort the regular spacing.
 
 Long notes which overrun bar lines can be converted automatically
 to tied notes.  This is done by replacing the
-@code{Note_heads_engraver} by the
+@code{Note_heads_engraver} with the
 @code{Completion_heads_engraver}.  In the following
 example, notes crossing the bar lines are split and tied.
 
@@ -1327,11 +1332,6 @@ inserts ties.  One of its uses is to debug complex scores: if the
 measures are not entirely filled, then the ties show exactly how
 much each measure is off.
 
-To allow line breaking on the bar lines where the
-@code{Completion_heads_engraver} has inserted a split note, remove
-the @code{Forbid_line_break_engraver} too.
-
-
 @seealso
 
 Music Glossary: @rglos{tie}
@@ -1352,8 +1352,8 @@ Internals Reference:
 @knownissues
 
 Not all durations (especially those containing tuplets) can be
-represented exactly with normal notes and dots, but the engraver
-will not insert tuplets.
+represented exactly with normal notes and dots, but the 
+@code{Completion_heads_engraver} will not insert tuplets.
 
 The @code{Completion_heads_engraver} only affects notes; it does not
 split rests.
@@ -1366,23 +1366,125 @@ Sometimes you might want to show only the rhythm of a melody.  This
 can be done with the rhythmic staff.  All pitches of notes on such a
 staff are squashed, and the staff itself has a single line
 
-@c TODO Devise a more realistic example, perhaps with lyrics -td
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-\new RhythmicStaff {
-  \time 4/4
-  c4 e8 f g2 | r4 g r2 | g1 | r1 |
-}
+<<
+  \new RhythmicStaff {
+    \new Voice = "myRhythm" {
+      \time 4/4
+      c4 e8 f g2
+      r4 g g f
+      g1
+    }
+  }
+  \new Lyrics {
+    \lyricsto "myRhythm" {
+      This is my song
+      I like to sing
+    }
+  }
+>>
+@end lilypond
+
+Guitar chord charts often show the strumming rhythms.  This can
+be done with the @code{Pitch_squash_engraver} and
+@code{\improvisationOn}.
+
+ 
+@lilypond[quote,verbatim]
+<<
+  \new ChordNames {
+    \chordmode {
+      c1 f g c
+    }
+  }
+
+  \new Voice \with {
+    \consists Pitch_squash_engraver
+  } \relative c'' {
+    \improvisationOn
+    c4 c8 c c4 c8 c
+    f4 f8 f f4 f8 f
+    g4 g8 g g4 g8 g
+    c4 c8 c c4 c8 c
+  }
+>>
+@end lilypond
+
+@predefined
+@code{\improvisationOn},
+@code{\improvisationOff}.
+
+@snippets
+@c TODO -- Convert to snippet;
+@c     tag for both Rhythms and Guitar? Move to @seealso?
+
+For guitar music, it is possible to show strum rhythms, along
+with melody notes, chord names, and fret diagrams.
+
+
+@lilypond[quote,verbatim]
+\include "predefined-guitar-fretboards.ly"
+<<
+  \new ChordNames {
+    \chordmode {
+      c1 f g c
+    }
+  }
+
+  \new FretBoards {
+    \chordmode {
+      c1 f g c
+    }
+  }
+
+  
+  \new Voice \with {
+    \consists Pitch_squash_engraver
+  } \relative c'' {
+    \improvisationOn
+    c4 c8 c c4 c8 c
+    f4 f8 f f4 f8 f
+    g4 g8 g g4 g8 g
+    c4 c8 c c4 c8 c
+  }
+
+
+  \new Voice = "melody" {
+    \relative c'' {
+      \improvisationOff
+      c2 e4 e4 
+      f2. r4
+      g2. a4
+      e4 c2.
+    }
+  }
+ 
+  \new Lyrics {
+    \lyricsto "melody" {
+      This is my song.
+      I like to sing.
+    }
+  }
+>>
 @end lilypond
 
+@seealso
+
+Snippets:
+@rlsr{Rhythms}.
+
+Internals Reference:
+@rinternals{RhythmicStaff},
+@rinternals{Pitch_squash_engraver}.
 
 @node Beams
 @subsection Beams
 
 @menu
-* Automatic beams::             
-* Setting automatic beam behavior::  
-* Manual beams::                
-* Feathered beams::             
+* Automatic beams::
+* Setting automatic beam behavior::
+* Manual beams::
+* Feathered beams::
 @end menu
 
 @node Automatic beams
@@ -1419,9 +1521,13 @@ c4 c8 c8. c16 c8.
 c16 c8
 @end lilypond
 
+@predefined
+@code{\autoBeamOff},
+@code{\autoBeamOn}.
 
 @snippets
 
+@c TODO -- convert to snippet
 Beaming patterns may be altered with the @code{beatGrouping} property,
 
 @lilypond[quote,verbatim,relative=2,fragment,ragged-right]
@@ -1432,11 +1538,12 @@ c8[^"(2+3)" c16 c8]
 c8[^"(3+2)" c16 c8]
 @end lilypond
 
+@c TODO  convert to snippet
 The beams of consecutive 16th (or shorter) notes are, by default,
 not sub-divided.  That is, the three (or more) beams stretch
 unbroken over entire groups of notes.  This behavior can
-be modified to sub-divide the beams into sub-groups by setting 
-the property @code{subdivideBeams}.  When set, multiple beams 
+be modified to sub-divide the beams into sub-groups by setting
+the property @code{subdivideBeams}.  When set, multiple beams
 will be sub-divided at intervals defined by the current value of
 @code{beatLength} by reducing the multiple beams to just one beam
 between the sub-groups. Note that @code{beatLength} lives in the
@@ -1465,8 +1572,9 @@ For more information about @code{make-moment}, see
 @cindex break, line
 @cindex line breaks
 
+@c TODO  convert to snippet
 Line breaks are normally forbidden when beams cross bar lines.
-This behavior can be changed by setting the @code{breakable} 
+This behavior can be changed by setting the @code{breakable}
 property: @code{\override Beam #'breakable = ##t}.
 
 @lilypond[ragged-right,relative=2,fragment,verbatim,quote]
@@ -1479,10 +1587,11 @@ c8 \repeat unfold 15 { c[ c] } c
 @cindex kneed beams
 @cindex auto-knee-gap
 
+@c TODO convert to snippet
 Kneed beams are inserted automatically when a large gap is
 detected between the note heads.  This behavior can be tuned
 through the @code{auto-knee-gap} property.  A kneed beam is
-drawn if the gap is larger than the value of 
+drawn if the gap is larger than the value of
 @code{auto-knee-gap} plus the width of the beam object (which
 depends on the duration of the notes and the slope of the beam).
 By default @code{auto-knee-gap} is set to 5.5 staff spaces.
@@ -1496,7 +1605,12 @@ f8 f''8 f8 f''8
 
 @seealso
 
-Notation Reference: @ref{Manual beams}, @ref{Setting automatic beam behavior}.
+Notation Reference: 
+@ref{Manual beams}, 
+@ref{Setting automatic beam behavior}.
+
+Installed Files:
+@file{scm/auto-beam.scm}.
 
 Snippets:
 @rlsr{Rhythms}.
@@ -1533,24 +1647,32 @@ defined in @file{scm/@/auto@/-beam@/.scm}.
 
 In order to add a rule to the list, use
 @example
-#(override-auto-beam-setting '(be p q n m) a b [context])
+#(override-auto-beam-setting 
+  '(beam-limit beam-numerator  beam-denominator
+     time-signature-numerator time-signature-denominator) 
+  moment-numerator moment-denominator [context])
 @end example
 
 @itemize
 
-@item @code{be} is either @code{begin} or @code{end}.
+@item @code{beam-limit} is the type of automatic beam limit
+defined, either @code{begin} or @code{end}.
 
-@item @code{p/q} is the duration of the note for which you want
-to add a rule.  A beam is considered to have the duration of its
-shortest note.  Set @code{p} and @code{q} to @code{'*'} to
-have this apply to any beam.
+@item @code{beam-numerator/beam-denominator} is the beam duration
+for which you want to add a rule.  A beam is considered to have 
+the duration of its shortest note.  Set @code{beam-numerator} and 
+@code{beam-denominator} to @code{'*'} to
+have this rule apply beams of any duration.
 
-@item @code{n/m} is the time signature to which
-this rule should apply.  Set @code{n} and @code{m} to @code{'*'}
-to have this apply in any time signature.
+@item @code{time-signature-numerator/time-signature-denominator}
+is the time signature to which
+this rule should apply.  Set @code{time-signature-numerator} and 
+@code{time-signature-denominator} to @code{'*'}
+to have this rule apply in any time signature.
 
-@item @code{a/b} is the position in the bar at which the beam should
-begin/end.
+@item @code{monent-numerator/moment-denominator} is the position 
+in the bar at which the beam should
+begin or end.
 
 @item @code{context} is optional, and it specifies the context at which
 the change should be made.  The default is @code{'Voice}.
@@ -1560,6 +1682,7 @@ the change should be made.  The default is @code{'Voice}.
 
 @end itemize
 
+TODO -- convert to music example
 For example, if automatic beams should always end on the first quarter
 note, use
 
@@ -1572,9 +1695,11 @@ note is a certain duration
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 \time 2/4
+% end 1/16 beams for all time signatures at the 1/16 moment
 #(override-auto-beam-setting '(end 1 16 * *) 1 16)
 a16 a a a a a a a |
 a32 a a a a16 a a a a a |
+% end 1/32 beams for all time signatures at the 1/16 moment
 #(override-auto-beam-setting '(end 1 32 * *) 1 16)
 a32 a a a a16 a a a a a |
 @end lilypond
@@ -1584,6 +1709,7 @@ signatures
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 \time 5/8
+% end beams of all durations in 5/8 time signature at the 2/8 moment
 #(override-auto-beam-setting '(end * * 5 8) 2 8)
 c8 c d d d
 \time 4/4
@@ -1592,21 +1718,27 @@ e8 e f f e e d d
 c8 c d d d
 @end lilypond
 
-You can also remove a previously set beam-ending rule by using
+Existing auto-beam rules are removed by using
 
 @example
-#(revert-auto-beam-setting '(be p q n m) a b [context])
+#(revert-auto-beam-setting 
+  '(beam-limit beam-numerator  beam-denominator
+     time-signature-numerator time-signature-denominator) 
+  moment-numerator moment-denominator [context])
 @end example
 
 @noindent
-@code{be}, @code{p}, @code{q}, @code{n}, @code{m}, @code{a},
-@code{b} and @code{context} are the same as above.  Note that the
-default rules are specified in @file{scm/@/auto@/-beam@/.scm},
+@code{beam-limit}, @code{beam-numerator}, @code{beam-denominator}, 
+@code{time-signature-numerator}, @code{time-signature-denominator},
+@code{moment-numerator}, @code{moment-denominator} and @code{context}
+are the same as above.  Note that the default auto-beaming rules are 
+specified in @file{scm/@/auto@/-beam@/.scm},
 so you can revert rules that you did not explicitly create.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 \time 4/4
 a16 a a a a a a a a a a a a a a a
+% undo a rule ending 1/16 beams in 4/4 time at 1/4 moment
 #(revert-auto-beam-setting '(end 1 16 4 4) 1 4)
 a16 a a a a a a a a a a a a a a a
 @end lilypond
@@ -1706,6 +1838,8 @@ Snippets:
 @subsubsection Manual beams
 
 @cindex beams, manual
+@funindex ]
+@funindex [
 
 In some cases it may be necessary to override the automatic
 beaming algorithm.  For example, the autobeamer will not put beams
@@ -1720,6 +1854,7 @@ marking the begin and end point with @code{[} and @code{]}
 }
 @end lilypond
 
+@funindex \noBeam
 
 Individual notes may be marked with @code{\noBeam} to prevent them
 from being beamed:
@@ -1728,9 +1863,6 @@ from being beamed:
 \time 2/4 c8 c\noBeam c c
 @end lilypond
 
-@funindex ]
-@funindex [
-
 @funindex stemLeftBeamCount
 @funindex stemRightBeamCount
 
@@ -1743,6 +1875,7 @@ then it is erased.  In this example, the last @code{f} is printed
 with only one beam on the left side, i.e., the eighth-note beam of
 the group as a whole.
 
+TODO -- no difference based on stemLeftBeamCount in this example
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 {
   f8[ r16 f g a]
@@ -1759,13 +1892,17 @@ the group as a whole.
 @subsubsection Feathered beams
 
 @cindex beams, feathered
-@funindex \featherDurations 
+@funindex \featherDurations
+
+TODO -- this section relies on overrides.  We need to either add
+a predefined, move this to snippets (whole section), or violate
+policy for this section.
 
 Feathered beams are used to indicate that a small group of notes
 should be played at an increasing (or decreasing) tempo, without
-changing the overall tempo of the piece.  The extent of the 
+changing the overall tempo of the piece.  The extent of the
 feathered beam must be indicated manually using @code{[} and
-@code{]}, and the beam feathering is turned on by specifying a 
+@code{]}, and the beam feathering is turned on by specifying a
 direction to the @code{Beam} property @code{grow-direction}.
 
 If the placement of the notes and the sound in the MIDI output
@@ -1777,9 +1914,11 @@ between the durations of the first and last notes in the group.
 
 The square brackets
 show the extent of the beam and the braces show
-which notes are to have their durations modified.  Normally 
+which notes are to have their durations modified.  Normally
 these would delimit the same group of notes, but this is not
-required: the two commands are independent. 
+required: the two commands are independent.
+
+@c TODO -- eliminate "Talking through code"
 
 In the following example the eight 16th notes occupy exactly the
 same time as a half note, but the first note is one half as long
@@ -1800,9 +1939,12 @@ the last four 32nd notes are at a constant tempo.
 @end lilypond
 
 @noindent
-The spacing in the printed output represents the 
+The spacing in the printed output represents the
 note durations only approximately, but the midi output is exact.
 
+@c TODO -- resolve whether or not midi is capitalized -- policy 
+@c  decision needed
+
 @knownissues
 
 The @code{\featherDurations} command only works with very short
@@ -1820,10 +1962,10 @@ Snippets:
 
 
 @menu
-* Bar lines::                   
-* Bar numbers::                 
-* Bar and bar number checks::   
-* Rehearsal marks::             
+* Bar lines::
+* Bar numbers::
+* Bar and bar number checks::
+* Rehearsal marks::
 @end menu
 
 @node Bar lines
@@ -1836,10 +1978,10 @@ Snippets:
 
 Bar lines delimit measures, and are also used to indicate
 repeats.  Normally, simple bar lines are automatically inserted
-into the printed output at places based on the current time 
-signature.  
+into the printed output at places based on the current time
+signature.
 
-The simple bar lines inserted automatically can be changed to 
+The simple bar lines inserted automatically can be changed to
 other types with the @code{\bar} command.  For example, a closing
 double bar line is usually placed at the end of a piece:
 
@@ -1847,15 +1989,20 @@ double bar line is usually placed at the end of a piece:
 e4 d c2 \bar "|."
 @end lilypond
 
+@c TODO -- make this warning more clear.  What does it mean?
 @warning{An incorrect duration can lead to poorly formatted
 music.}
- 
-It is not invalid if the final note in a measure does not 
-end on the automatically entered bar line: the note is assumed 
+
+@c TODO -- check this.  I think this behavior no longer happens
+@c with completion_heads_engraver, but it may with note_heads_engraver
+@c Make an example showing the problem
+
+It is not invalid if the final note in a measure does not
+end on the automatically entered bar line: the note is assumed
 to carry over into the next measure.  But if a long sequence
 of such carry-over measures appears the music can appear compressed
 or even flowing off the page.  This is because automatic line
-breaks happen only at the end of complete measures, i.e., where 
+breaks happen only at the end of complete measures, i.e., where
 the end of a note coincides with the end of a measure.
 
 @cindex line breaks
@@ -1863,7 +2010,7 @@ the end of a note coincides with the end of a measure.
 @cindex measure lines, invisible
 
 Line breaks are also permitted at manually inserted bar lines
-even within incomplete measures.  To allow a line break without 
+even within incomplete measures.  To allow a line break without
 printing a bar line, use
 
 @example
@@ -1872,23 +2019,23 @@ printing a bar line, use
 
 @noindent
 This will insert an invisible bar line and allow (but not
-force) a line break to occur at this point.  The bar number 
-counter is not increased.  To force a line break see 
+force) a line break to occur at this point.  The bar number
+counter is not increased.  To force a line break see
 @ref{Line breaking}.
 
 This and other special bar lines may be inserted manually at any
 point.  When they coincide with the end of a measure they replace
-the simple bar line which would have been inserted there 
+the simple bar line which would have been inserted there
 automatically.  When they do not coincide
 with the end of a measure the specified bar line is inserted at that
 point in the printed output.  Such insertions do not affect
-the calculation and placement of subsequent automatic bar lines.  
+the calculation and placement of subsequent automatic bar lines.
 
-The simple bar line and four types of double bar line are available
+The simple bar line and five types of double bar line are available
 for manual insertion:
 
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-f1 \bar "|" g \bar "||" a \bar ".|" b \bar ".|." c \bar "|." d
+f1 \bar "|" g \bar "||" a \bar ".|" b \bar ".|." c \bar "|.|" d \bar "|." e
 @end lilypond
 
 @noindent
@@ -1899,10 +2046,10 @@ f1 \bar ":" g \bar "dashed" a
 @end lilypond
 
 @noindent
-and three types of repeat bar line:
+and five types of repeat bar line:
 
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
-f1 \bar "|:" g \bar ":|:" a \bar ":|" b
+f1 \bar "|:" g \bar ":|:" a \bar ":|.|:" b \bar ":|.:" c \bar ":|" d
 @end lilypond
 
 @cindex repeats
@@ -1916,21 +2063,21 @@ automatically print the appropriate bar lines.
 In addition, you can specify @code{"||:"}, which is equivalent to
 @code{"|:"} except at line breaks, where it gives a double bar
 line at the end of the line and a start repeat at the beginning of
-the next line. 
+the next line.
 
 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
 \override Score.RehearsalMark #'padding = #3
 c c c c
-\bar "||:" 
+\bar "||:"
 c c c c \break
-\bar "||:" 
+\bar "||:"
 c c c c
 @end lilypond
 
 In scores with many staves, a @code{\bar} command in one staff is
 automatically applied to all staves.  The resulting bar lines are
 connected between different staves of a @code{StaffGroup},
-@code{PianoStaff}, or @code{GrandStaff}.
+@code{InnerStaffGroup}, @code{PianoStaff}, or @code{GrandStaff}.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 <<
@@ -1953,13 +2100,13 @@ connected between different staves of a @code{StaffGroup},
 @funindex defaultBarType
 
 The command @code{\bar }@var{bartype} is a shortcut for
-@code{\set Timing.whichBar = }@var{bartype}.  A bar line is 
+@code{\set Timing.whichBar = }@var{bartype}.  A bar line is
 created whenever the @code{whichBar} property is
-set.  
+set.
 
 The default bar type used for automatically inserted bar lines is
 @code{"|"}.  This may be changed at any time
-with @code{\set Timing.defaultBarType = }@var{bartype}.  
+with @code{\set Timing.defaultBarType = }@var{bartype}.
 
 @seealso
 
@@ -2013,7 +2160,7 @@ line visible}, @code{beginning of line visible}.  In the following
 example bar numbers are printed at all possible places:
 
 @lilypond[verbatim,ragged-right,quote,fragment,relative]
-\override Score.BarNumber #'break-visibility = ##(#t #t #t)
+\override Score.BarNumber #'break-visibility = #'#(#t #t #t)
 \set Score.currentBarNumber = #11
 \bar ""  % Permit first bar number to be printed
 c1 c c c
@@ -2029,7 +2176,7 @@ and here the bar numbers are printed every two measures
 except at the end of the line:
 
 @lilypond[verbatim,ragged-right,quote,fragment,relative]
-\override Score.BarNumber #'break-visibility = ##(#f #t #t)
+\override Score.BarNumber #'break-visibility = #'#(#f #t #t)
 \set Score.currentBarNumber = #11
 \bar ""  % Permit first bar number to be printed
 % Print a bar number every second measure
@@ -2043,7 +2190,7 @@ c c c c c
 @cindex bar number, format
 
 The size of the bar number may be changed.  This is illustrated
-in the following example, which also shows how to enclose bar 
+in the following example, which also shows how to enclose bar
 numbers in boxes and circles, and shows an alternative way
 of specifying @code{#(#f #t #t)} for @code{break-visibility}.
 
@@ -2052,7 +2199,7 @@ of specifying @code{#(#f #t #t)} for @code{break-visibility}.
 \override Score.BarNumber #'break-visibility
   = #end-of-line-invisible
 
-% Increase the size of the bar number by 2 
+% Increase the size of the bar number by 2
 \override Score.BarNumber #'font-size = #2
 \repeat unfold 3 { c1 } \bar "|"
 
@@ -2072,12 +2219,12 @@ of specifying @code{#(#f #t #t)} for @code{break-visibility}.
 Bar numbers by default are left-aligned to their parent object.
 This is usually the left edge of a line or, if numbers are printed
 within a line, the left bar line of the measure.  The numbers may also
-be positioned directly on the bar line or right-aligned to the 
+be positioned directly on the bar line or right-aligned to the
 bar line:
 
 @lilypond[verbatim,ragged-right,quote,fragment,relative]
 \set Score.currentBarNumber = #111
-\override Score.BarNumber #'break-visibility = ##(#t #t #t)
+\override Score.BarNumber #'break-visibility = #'#(#t #t #t)
 % Increase the size of the bar number by 2
 \override Score.BarNumber #'font-size = #2
 % Print a bar number every second measure
@@ -2146,11 +2293,11 @@ c1 c c c
 @funindex |
 
 Bar checks help detect errors in the entered durations.
-A bar check may be entered using the bar symbol, @code{|}, 
-at any place where a bar line is expected to fall.  
-If bar check lines are encountered at other places, 
+A bar check may be entered using the bar symbol, @code{|},
+at any place where a bar line is expected to fall.
+If bar check lines are encountered at other places,
 a list of warnings is printed in the log file,
-showing the line numbers and lines  
+showing the line numbers and lines
 in which the bar checks failed.  In the next
 example, the second bar check will signal an error.
 
@@ -2172,20 +2319,25 @@ especially if the score is polyphonic, so a good place to start
 correcting input is by scanning for failed bar checks and
 incorrect durations.
 
+If successive bar checks are off by the same musical interval,
+only the first warning message is displayed.  This allows the
+warning to focus on the source of the timing error.
+
+
 @funindex |
 @funindex pipeSymbol
 
-It is also possible to redefine the action taken when a bar check 
-or pipe symbol, @code{|}, is encountered in the input, so that 
-it does something other than a bar check.  This is done by 
-assigning a music expression to @code{pipeSymbol}.  
-In the following example @code{|} is set to insert a double bar 
-line wherever it appears in the input, rather than checking 
+It is also possible to redefine the action taken when a bar check
+or pipe symbol, @code{|}, is encountered in the input, so that
+it does something other than a bar check.  This is done by
+assigning a music expression to @code{pipeSymbol}.
+In the following example @code{|} is set to insert a double bar
+line wherever it appears in the input, rather than checking
 for end of bar.
 
 @lilypond[quote,ragged-right,verbatim]
 pipeSymbol = \bar "||"
-{ 
+{
   c'2 c'2 |
   c'2 c'2
   c'2 | c'2
@@ -2315,29 +2467,31 @@ For common tweaks to the positioning of rehearsal marks, see
 
 @seealso
 
-Snippets:
-@rlsr{Rhythms}.
-
-This manual: @ref{The Feta font}, @ref{Formatting text}.
-
-Internals Reference: @rinternals{RehearsalMark}.
+This manual: 
+@ref{The Feta font}, 
+@ref{Formatting text}.
 
-Init files: @file{scm/@/translation@/-functions@/.scm} contains
+Installed Files: 
+@file{scm/@/translation@/-functions@/.scm} contains
 the definition of @code{format-mark-numbers} and
 @code{format-mark-letters}.  They can be used as inspiration for
 other formatting functions.
 
-Examples: @c @lsr{parts,rehearsal-mark-numbers.ly}
+Snippets:
+@rlsr{Rhythms}.
+
+Internals Reference: @rinternals{RehearsalMark}.
 
+Examples: @c @lsr{parts,rehearsal-mark-numbers.ly}
 
 @node Special rhythmic concerns
 @subsection Special rhythmic concerns
 
 
 @menu
-* Grace notes::                 
-* Aligning to cadenzas::        
-* Time administration::         
+* Grace notes::
+* Aligning to cadenzas::
+* Time administration::
 @end menu
 
 @node Grace notes
@@ -2349,42 +2503,35 @@ Examples: @c @lsr{parts,rehearsal-mark-numbers.ly}
 @cindex appoggiatura
 @cindex acciaccatura
 
-Grace notes are ornaments that are written out. They are made with
-the @code{\grace} command.  By prefixing this keyword to a music
-expression, a new one is formed, which will be printed in a
-smaller font and takes up no logical time in a measure.
+Grace notes are ornaments that are written out. Grace notes
+are printed in a smaller font and take up no logical time 
+in a measure.
 
 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
 c4 \grace c16 c4
-\grace { c16[ d16] } c2 c4
+\grace { c16[ d16] } c2
 @end lilypond
 
-Two special forms of the @code{\grace} command exist.
-An @emph{acciaccatura}, which should be played as very short,
-is denoted by a slurred small note with a slashed stem.  The
-@emph{appoggiatura}, a grace note that takes a fixed fraction of the
-main note, is denoted as a slurred note in small print without
-a slash.  They are entered with the commands @code{\acciaccatura}
-and @code{\appoggiatura}, as demonstrated in the following
-example:
+Lilypond also supports two special types of grace notes, the 
+@emph{acciaccatura}--an unmeasured grace note indicated by a slurred 
+small note with a slashed stem--and the @emph{appoggiatura}, which 
+takes a fixed fraction of the main note and appears in small print 
+without a slash. 
 
 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
-b4 \acciaccatura d8 c4 
+\grace c8 b4 
+\acciaccatura d8 c4
 \appoggiatura e8 d4
 \acciaccatura { g16[ f] } e4
 @end lilypond
 
-@noindent
-@code{\acciaccatura} and @code{\appoggiatura} start a slur, 
-@code{\grace} does not.
-
 The placement of grace notes is synchronized between different
 staves.  In the following example, there are two sixteenth grace
 notes for every eighth grace note
 
 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
-<< \new Staff { e4 \grace { c16[ d e f] } e4 }
-   \new Staff { c4 \grace { g8[ b] } c4 } >>
+<< \new Staff { e2 \grace { c16[ d e f] } e2 }
+   \new Staff { c2 \grace { g8[ b] } c2 } >>
 @end lilypond
 
 @funindex \afterGrace
@@ -2396,39 +2543,50 @@ command.  It takes two arguments: the main note, and the grace
 notes following the main note.
 
 @lilypond[quote,ragged-right,verbatim,relative=2,fragment]
-c1 \afterGrace d1 { c16[ d] } c4
+c1 \afterGrace d1 { c16[ d] } c1
 @end lilypond
 
-This will put the grace notes after a @q{space} lasting 3/4 of the
-length of the main note.  The fraction 3/4 can be changed by
-setting @code{afterGraceFraction}, i.e.,
-
-@example
-#(define afterGraceFraction (cons 7 8))
-@end example
+This will put the grace notes after a space lasting 3/4 of the
+length of the main note.  The default fraction 3/4 can be changed by
+setting @code{afterGraceFraction}.  The following example shows
+the results from setting the space at the default,  at 15/16, and 
+finally at 1/2 of the main note.
 
-@noindent
-will put the grace note at 7/8 of the main note.
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+<<
+  \new Staff {
+    c1 \afterGrace d1 { c16[ d] } c1
+  }
+  \new Staff {
+    #(define afterGraceFraction (cons 15 16))
+    c1 \afterGrace d1 { c16[ d] } c1
+  }
+  \new Staff {
+    #(define afterGraceFraction (cons 1 2))
+    c1 \afterGrace d1 { c16[ d] } c1
+  }
+>>
+@end lilypond
 
-The same effect can be achieved manually by doing
+The space between the main note and the grace note may also be
+specified using spacers. The following example places the grace
+note after a space lasting 7/8 of the main note.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \new Voice {
   << { d1^\trill_( }
-     { s2 \grace { c16[ d] } } >>
-  c4)
+     { s2 s4. \grace { c16[ d] } } >>
+  c1)
 }
 @end lilypond
 
-@noindent
-By adjusting the duration of the skip note (here it is a
-half-note), the space between the main note and the grace
-may be adjusted.
-
 A @code{\grace} music expression will introduce special
 typesetting settings, for example, to produce smaller type, and
-set directions.  Hence, when introducing layout tweaks, they
-should be inside the grace expression, for example,
+set directions.  Hence, when introducing layout tweaks to
+override the special settings, they should be placed inside
+the grace expression. The overrides should also be reverted
+inside the grace expression. Here, the grace note's default stem
+direction is overriden and then reverted.
 
 @lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \new Voice {
@@ -2437,63 +2595,69 @@ should be inside the grace expression, for example,
     f16->
     \stemNeutral
   }
-  g4
+  g4 e c2
 }
 @end lilypond
 
-@noindent
-The overrides should also be reverted inside the grace expression.
+
+@cindex stem, with slash
+
+
+@snippets
+
+The slash through the stem found in @emph{acciaccatura}s can be applied 
+in other situations:
+
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\relative c'' {
+  \override Stem #'stroke-style = #"grace"
+  c8( d2) e8( f4)
+}
+@end lilypond
 
 The layout of grace expressions can be changed throughout the
 music using the function @code{add-grace-property}.  The following
 example undefines the @code{Stem} direction for this grace, so
 that stems do not always point up.
 
-@example
-\new Staff @{
-  #(add-grace-property 'Voice 'Stem 'direction '())
-  @dots{}
-@}
-@end example
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
+\relative c'' {
+  \new Staff {
+    #(add-grace-property 'Voice 'Stem 'direction ly:stem::calc-direction)
+    #(remove-grace-property 'Voice 'Stem 'direction)
+    \new Voice {
+       \acciaccatura { f16 } g4 
+       \grace { d16[ e] } f4
+       \appoggiatura { a,32[ b c d] } e2
+    }
+  }
+}
+@end lilypond
 
-@noindent
 Another option is to change the variables @code{startGraceMusic},
 @code{stopGraceMusic}, @code{startAcciaccaturaMusic},
 @code{stopAcciaccaturaMusic}, @code{startAppoggiaturaMusic},
 @code{stopAppoggiaturaMusic}.  The default values of these can be
-seen in the file @file{ly/@/grace@/-init@/.ly}.  By redefining
+seen in the file @code{ly/@/grace@/-init@/.ly}.  By redefining
 them other effects may be obtained.
 
-@cindex stem, with slash
-
-@noindent
-The slash through the stem in @emph{acciaccatura}s can be obtained in
-other situations by @code{\override Stem  #'stroke-style =
-#"grace"}.
-
+Grace notes may be forced to align with regular notes
+in other staves:
 
-@snippets
-
-Grace notes may be forced to use align with regular notes
-in other staves by setting @code{strict-grace-spacing} to
-##t:
-
-@lilypond[relative=2,ragged-right]
-<<
-  \override Score.SpacingSpanner #'strict-grace-spacing = ##t
-  \new Staff {
-     c'4
-     \afterGrace
-     c'4
-     { c'16[ c'8 c'16] }
-     c'4
-  }  
-  \new Staff {
-     c'16[ c'16 c'16 c'16]
-     c'16[ c'16 c'16 c'16]
-     c'4
-  }
->>
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  <<
+    \override Score.SpacingSpanner #'strict-grace-spacing = ##t
+    \new Staff {
+      c4
+      \afterGrace c4 { c16[ c8 c16] }
+      c4 r
+    }
+    \new Staff {
+      c16 c c c c c c c c4 r
+    }
+  >>
+}
 @end lilypond
 
 
@@ -2502,17 +2666,18 @@ in other staves by setting @code{strict-grace-spacing} to
 Music Glossary:
 @rglos{grace notes},
 @rglos{acciaccatura},
-@rglos{appoggiatura}
+@rglos{appoggiatura}.
 
-Snippets:
-@rlsr{Rhythms}.
+Installed Files: @file{ly/@/grace@/-init@/.ly}.
+
+Snippets: @rlsr{Rhythms}.
 
 Internals Reference: @rinternals{GraceMusic}.
 
 
 @knownissues
 
-A multi-note beamed @emph{acciaccatura} is printed without a slash, 
+A multi-note beamed @emph{acciaccatura} is printed without a slash,
 and looks exactly the same as a multi-note beamed
 @emph{appoggiatura}.
 @c TODO Add link to LSR snippet to add slash when available
@@ -2523,8 +2688,8 @@ synchronized.  Take care when you mix staves with grace notes and
 staves without, for example,
 
 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
-<< \new Staff { e4 \bar "|:" \grace c16 d4 }
-   \new Staff { c4 \bar "|:" d4 } >>
+<< \new Staff { e4 \bar "|:" \grace c16 d2. }
+   \new Staff { c4 \bar "|:" d2. } >>
 @end lilypond
 
 @noindent
@@ -2532,10 +2697,15 @@ This can be remedied by inserting grace skips of the corresponding
 durations in the other staves.  For the above example
 
 @lilypond[quote,ragged-right,relative=2,verbatim,fragment]
-<< \new Staff { e4 \bar "|:" \grace c16 d4 }
-   \new Staff { c4 \bar "|:" \grace s16 d4 } >>
+<< \new Staff { e4 \bar "|:" \grace c16 d2. }
+   \new Staff { c4 \bar "|:" \grace s16 d2. } >>
 @end lilypond
 
+Predefined commands, like @code{\voiceOne}, which are intended to
+change the behaviour of the notation after a grace note, may not
+be effective if placed immediately before the grace note -- they
+should be placed after it.
+
 Grace sections should only be used within sequential music
 expressions.  Nesting or juxtaposing grace sections is not
 supported, and might produce crashes or other errors.
@@ -2548,33 +2718,40 @@ supported, and might produce crashes or other errors.
 @cindex aligning to cadenza
 
 In an orchestral context, cadenzas present a special problem: when
-constructing a score that includes a cadenza, all other
-instruments should skip just as many notes as the length of the
-cadenza, otherwise they will start too soon or too late.
+constructing a score that includes a measured cadenza or other solo
+passage, all other instruments should skip just as many notes as the 
+length of the cadenza, otherwise they will start too soon or too late. 
 
-A solution to this problem is to use the functions
+One solution to this problem is to use the functions
 @code{mmrest-of-length} and @code{skip-of-length}.  These Scheme
-functions take a piece of music as argument, and generate a multi-measure
-rest or @code{\skip}, exactly as long as the piece.  The use of
-@code{mmrest-of-length} is demonstrated in the following example.
+functions take a defined piece of music as an argument and generate a 
+multi-measure rest or @code{\skip} exactly as long as the piece.  
 
 @lilypond[verbatim,ragged-right,quote]
-cadenza = \relative c' {
-  c4 d8 << { e f g } \\ { d4. } >>
-  g4 f2 g4 g
+MyCadenza = \relative c' {
+  c4 d8 e f g g4 
+  f2 g4 g
 }
 
 \new GrandStaff <<
-  \new Staff { \cadenza c'4 }
+  \new Staff { 
+    \MyCadenza c'1 
+    \MyCadenza c'1
+  }
   \new Staff {
-    #(ly:export (mmrest-of-length cadenza))
-    c'4
+    #(ly:export (mmrest-of-length MyCadenza))
+    c'1
+    #(ly:export (skip-of-length MyCadenza))
+    c'1
   }
 >>
 @end lilypond
 
 @seealso
 
+Music Glossary:
+@rglos{cadenza}.
+
 Snippets:
 @rlsr{Rhythms}.
 
@@ -2598,7 +2775,7 @@ default is to be found in the @code{Score} context.  An alias,
 
 The following properties of @code{Timing} are used
 to keep track of timing within the score.
- 
+
 @cindex bar number
 @cindex measure number
 
@@ -2616,7 +2793,7 @@ should be generated.
 @item measurePosition
 The point within the measure where we currently are.  This
 quantity is reset by subtracting @code{measureLength} whenever
-@code{measureLength} is reached or exceeded.  When that happens, 
+@code{measureLength} is reached or exceeded.  When that happens,
 @code{currentBarNumber} is incremented.
 
 @item timing
@@ -2627,7 +2804,7 @@ measure indefinitely.
 @end table
 
 Timing can be changed by setting any of these variables
-explicitly.  In the next example, the default 4/4 time 
+explicitly.  In the next example, the default 4/4 time
 signature is printed, but @code{measureLength} is set to 5/4.
 At 4/8 through the third measure, the @code{measurePosition} is
 advanced by 1/8 to 5/8, shortening that bar by 1/8.