X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Frhythms.itely;h=e223bab4124b6d54cedca6e31056b37e6c6a3521;hb=6cc24e4a3246f1daaf79db3bec97a4a4541b5149;hp=9b719c93ea93e506fea2b44662b7441a0d33ba4d;hpb=95a4237d0aca94993bd3b91afc4ff0e4e2daec9f;p=lilypond.git

diff --git a/Documentation/notation/rhythms.itely b/Documentation/notation/rhythms.itely
index 9b719c93ea..e223bab412 100644
--- a/Documentation/notation/rhythms.itely
+++ b/Documentation/notation/rhythms.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.13.36"
+@c \version "2.15.18"
 
 @node Rhythms
 @section Rhythms
@@ -142,9 +142,11 @@ the staff; see @ref{Direction and placement}.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{changing-the-number-of-augmentation-dots-per-note.ly}
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{alternative-breve-note.ly}
 
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{changing-the-number-of-augmentation-dots-per-note.ly}
 
 @seealso
 Music Glossary:
@@ -171,9 +173,7 @@ Internals Reference:
 @rinternals{Dots},
 @rinternals{DotColumn}.
 
-
 @knownissues
-
 @c Deliberately duplicated in Durations and Rests.  -gp
 There is no fundamental limit to rest durations (both in terms of
 longest and shortest), but the number of glyphs is limited:
@@ -249,26 +249,25 @@ see @ref{Scaling durations}.
 @funindex tupletNumberFormatFunction
 @funindex tupletSpannerDuration
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {entering-several-tuplets-using-only-one--times-command.ly}
 
 @cindex Tuplet number changes
 
 @funindex TupletNumber
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {changing-the-tuplet-number.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {non-default-tuplet-numbers.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {controlling-tuplet-bracket-visibility.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {permitting-line-breaks-within-beamed-tuplets.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{triplet},
@@ -292,7 +291,6 @@ Internals Reference:
 @rinternals{TupletNumber},
 @rinternals{TimeScaledMusic}.
 
-
 @cindex grace notes within tuplet brackets
 
 @knownissues
@@ -372,7 +370,6 @@ and expanded:
 One application of this command is in polymetric
 notation, see @ref{Polymetric notation}.
 
-
 @seealso
 Notation Reference:
 @ref{Tuplets},
@@ -520,10 +517,24 @@ c2 ~ c
 c2 ~ c
 @end lilypond
 
-Dash pattern definitions for ties have the same structure as
-dash pattern definitions for slurs.
-For more information about complex dash patterns,
-see the snippets under @ref{Slurs}.
+Dash pattern definitions for ties have the same structure as dash
+pattern definitions for slurs. For more information about complex dash
+patterns, see @ref{Slurs}.
+
+Override @var{whiteout} and @var{layer} layout properties for ties that
+collide with other objects in a staff.
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+\override Tie #'layer = #-2
+\override Staff.TimeSignature #'layer = #-1
+\override Staff.KeySignature #'layer = #-1
+\override Staff.TimeSignature #'whiteout = ##t
+\override Staff.KeySignature #'whiteout = ##t
+b2 b~
+\time 3/4
+\key a \major
+b r4
+@end lilypond
 
 @predefined
 @code{\tieUp},
@@ -537,16 +548,14 @@ see the snippets under @ref{Slurs}.
 @code{\tieSolid}.
 @endpredefined
 
-
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {using-ties-with-arpeggios.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {engraving-ties-manually.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{tie},
@@ -557,6 +566,7 @@ Notation Reference:
 @ref{Automatic note splitting}.
 
 Snippets:
+@rlsr{Expressive marks},
 @rlsr{Rhythms}.
 
 Internals Reference:
@@ -565,14 +575,11 @@ Internals Reference:
 @rinternals{TieColumn},
 @rinternals{Tie}.
 
-
 @knownissues
-Switching staves when a tie is active will not produce a slanted
-tie.
-
-Changing clefs or octavations during a tie is not really
-well-defined.  In these cases, a slur may be preferable.
+Switching staves when a tie is active will not produce a slanted tie.
 
+Changing clefs or ottavations during a tie is not really well-defined.
+In these cases, a slur may be preferable.
 
 
 @node Writing rests
@@ -648,10 +655,9 @@ a4\rest d4\rest
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {rest-styles.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{breve},
@@ -667,9 +673,7 @@ Snippets:
 Internals Reference:
 @rinternals{Rest}.
 
-
 @knownissues
-
 @c Deliberately duplicated in Durations and Rests.  -gp
 There is no fundamental limit to rest durations (both in terms of
 longest and shortest), but the number of glyphs is limited: there
@@ -751,7 +755,6 @@ any kind.
 \skip 1 \skip1 \skip 1
 @end lilypond
 
-
 @seealso
 Learning Manual:
 @rlearning{Visibility and color of objects}.
@@ -916,19 +919,18 @@ setting, resulting bar-check warnings may not be displayed.
 @cindex rest, church
 @cindex kirchenpausen
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,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,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {positioning-multi-measure-rests.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {multi-measure-rest-markup.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{multi-measure rest}.
@@ -947,7 +949,6 @@ Internals Reference:
 @rinternals{MultiMeasureRestNumber},
 @rinternals{MultiMeasureRestText}.
 
-
 @cindex fingerings and multi-measure rests
 @cindex multi-measure rests and fingerings
 
@@ -966,6 +967,7 @@ into a single multi-measure rest.
 
 Multi-measure rests do not take part in rest collisions.
 
+
 @node Displaying rhythms
 @subsection Displaying rhythms
 
@@ -1056,25 +1058,23 @@ be changed, or new default values can be added:
 
 @lilypond[quote,verbatim]
 \score {
-  \relative c' {
-    \overrideTimeSignatureSettings
-      #'Score    % context
-      #'(4 . 4)  % timeSignatureFraction
-      #'(1 . 4)  % baseMomentFraction
-      #'(3 1)    % beatStructure
-      #'()       % beamExceptions
-    \time 4/4
-    \repeat unfold 8 { c8 } |
+  \new Staff {
+    \relative c' {
+      \overrideTimeSignatureSettings
+        #'(4 . 4)  % timeSignatureFraction
+        #'(1 . 4)  % baseMomentFraction
+        #'(3 1)    % beatStructure
+        #'()       % beamExceptions
+      \time 4/4
+      \repeat unfold 8 { c8 } |
+    }
   }
 }
 @end lilypond
 
-@code{\overrideTimeSignatureSettings} takes five arguments:
+@code{\overrideTimeSignatureSettings} takes four arguments:
 
 @enumerate
-@item
-@code{@var{context}}, a Scheme symbol that describes the context
-to which the default setting will apply.
 
 @item
 @code{@var{timeSignatureFraction}}, a Scheme pair describing the
@@ -1094,6 +1094,38 @@ for the time signature that go beyond ending at every beat, as
 described in @ref{Setting automatic beam behavior}.
 @end enumerate
 
+The context containing @code{\overrideTimeSignatureSettings} must
+be instantiated before the @code{\overrideTimeSignatureSettings}
+call is executed.  That means it must either be explicitly
+instantiated or there must be music in the context before the
+@code{\overrideTimeSignatureSettings} call:
+
+@lilypond[quote,verbatim]
+\score {
+  \relative c' {
+    % This call will fail because the context isn't yet instantiated
+    \overrideTimeSignatureSettings
+      #'(4 . 4)  % timeSignatureFraction
+      #'(1 . 4)  % baseMomentFraction
+      #'(3 1)    % beatStructure
+      #'()       % beamExceptions
+    \time 4/4
+    c8^\markup {"Beamed (2 2)"}
+    \repeat unfold 7 { c8 } |
+    % This call will succeed
+    \overrideTimeSignatureSettings
+      #'(4 . 4)  % timeSignatureFraction
+      #'(1 . 4)  % baseMomentFraction
+      #'(3 1)    % beatStructure
+      #'()       % beamExceptions
+    \time 4/4
+    c8^\markup {"Beamed (3 1)"}
+    \repeat unfold 7 { c8 } |
+  }
+}
+@end lilypond
+
+
 @cindex time signature properties, restoring default values
 @cindex restoring default properties for time signatures
 @funindex \revertTimeSignatureSettings
@@ -1106,20 +1138,61 @@ to the original values:
   \relative c' {
     \repeat unfold 8 { c8 } |
     \overrideTimeSignatureSettings
-      #'Score                         % context
-      #'(4 . 4)                       % timeSignatureFraction
-      #'(1 . 4)                       % baseMomentFraction
-      #'(3 1)                         % beatStructure
-      #'((end . (((1 . 8) . (3 1))))) % beamExceptions
+      #'(4 . 4)  % timeSignatureFraction
+      #'(1 . 4)  % baseMomentFraction
+      #'(3 1)    % beatStructure
+      #'()       % beamExceptions
     \time 4/4
     \repeat unfold 8 { c8 } |
-    \revertTimeSignatureSettings #'Score #'(4 . 4)
+    \revertTimeSignatureSettings #'(4 . 4)
     \time 4/4
     \repeat unfold 8 { c8 } |
   }
 }
 @end lilypond
 
+Different values of default time signature properties can be established
+for different staves by moving the @code{Timing_translator} and the
+@code{Default_bar_line_engraver} from the @code{Score} context to the
+@code{Staff} context.
+
+@lilypond[quote, verbatim]
+\score {
+  \new StaffGroup <<
+     \new Staff {
+        \overrideTimeSignatureSettings
+          #'(4 . 4)  % timeSignatureFraction
+          #'(1 . 4)  % baseMomentFraction
+          #'(3 1)    % beatStructure
+          #'()       % beamExceptions
+        \time 4/4
+        \repeat unfold 8 {c''8}
+     }
+     \new Staff {
+        \overrideTimeSignatureSettings
+          #'(4 . 4)  % timeSignatureFraction
+          #'(1 . 4)  % baseMomentFraction
+          #'(1 3)    % beatStructure
+          #'()       % beamExceptions
+        \time 4/4
+        \repeat unfold 8 {c''8}
+     }
+  >>
+  \layout {
+    \context {
+      \Score
+      \remove "Timing_translator"
+      \remove "Default_bar_line_engraver"
+    }
+    \context {
+      \Staff
+      \consists "Timing_translator"
+      \consists "Default_bar_line_engraver"
+    }
+  }
+}
+@end lilypond
+
 @predefined
 @code{\numericTimeSignature},
 @code{\defaultTimeSignature}.
@@ -1127,20 +1200,9 @@ to the original values:
 
 
 @snippets
-
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{changing-the-time-signature-without-affecting-the-beaming.ly}
-
-@cindex compound time signatures
-@cindex time signature, compound
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-{compound-time-signatures.ly}
-
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {time-signature-printing-only-the-numerator-as-a-number-instead-of-the-fraction.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{time signature}
@@ -1156,6 +1218,7 @@ Internals Reference:
 @rinternals{TimeSignature},
 @rinternals{Timing_translator}.
 
+
 @node Metronome marks
 @unnumberedsubsubsec Metronome marks
 
@@ -1175,6 +1238,14 @@ c2 d
 e4. d8 c2
 @end lilypond
 
+Metronome marks may also be printed as a range of two numbers:
+
+@lilypond[verbatim,quote,relative=1]
+\tempo 4 = 40 ~ 46
+c4. e8 a4 g
+b,2 d4 r
+@end lilypond
+
 Tempo indications with text can be used instead:
 
 @lilypond[verbatim,quote,relative=2]
@@ -1210,20 +1281,19 @@ d4 g e c
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {printing-metronome-and-rehearsal-marks-below-the-staff.ly}
 
 @c perhaps also an example of how to move it horizontally?
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {changing-the-tempo-without-a-metronome-mark.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {creating-metronome-marks-in-markup-mode.ly}
 
 For more details, see @ref{Formatting text}.
 
-
 @seealso
 Music Glossary:
 @rglos{metronome},
@@ -1249,54 +1319,57 @@ Internals Reference:
 @cindex upbeat
 @cindex partial measure
 @cindex measure, partial
+@cindex measure, pickup
 @cindex pickup measure
-@cindex measure, change length
 
 @funindex measurePosition
 @funindex \partial
 @funindex partial
 
-Partial or pick-up measures, such as an anacrusis or upbeat, are
-entered using the @code{\partial} command, with the syntax
+Partial or pick-up measures, such as an @emph{anacrusis} or an
+@emph{upbeat}, are entered using the @code{\partial} command,
 
 @example
 \partial @var{duration}
 @end example
 
 @noindent
-where @code{@var{duration}} is the rhythmic length of the
-remaining interval of the current measure before the start of the
-next.
+where @code{@var{duration}} is the @emph{remaining} length of the
+partial measure @emph{before} the start of the next full measure.
 
-@lilypond[quote,verbatim,relative=2]
-\partial 4 e4 |
-a2. c,4 |
+@lilypond[quote,verbatim,relative=1]
+\time 3/4
+\partial 8
+e8 | a4 c8 b c4 |
 @end lilypond
 
-The partial measure can be any duration less than the full measure:
+The @var{duration} can be any value less than a full measure:
 
-@lilypond[quote,verbatim,relative=2]
-\partial 8*3 c8 d e |
-a2. c,4 |
+@lilypond[quote,verbatim,relative=1]
+\time 3/4
+\partial 4.
+r4 e8 | a4 c8 b c4 |
 @end lilypond
 
-Internally, @code{\partial @var{duration}} is translated into:
+The @code{\partial @var{duration}} can also be written as;
 
 @example
 \set Timing.measurePosition -@var{duration}
 @end example
 
-For example, @code{\partial 8*3} becomes:
+So @code{\partial 8} becomes:
 
-@example
-\set Timing.measurePosition = #(ly:make-moment -3 8)
-@end example
+@lilypond[quote,verbatim,relative=1]
+\time 3/4
+\set Timing.measurePosition = #(ly:make-moment -1 8)
+e8 | a4 c8 b c4 |
+@end lilypond
 
 The property @code{measurePosition} contains a rational number
 indicating how much of the measure has passed at this point.  Note
 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.}
+i.e., @code{\partial 4} is internally translated to @w{@code{-4}},
+meaning @qq{there is a quarter note left in the measure.}
 
 @seealso
 Music Glossary:
@@ -1312,30 +1385,51 @@ Internal Reference:
 @rinternals{Timing_translator}.
 
 @knownissues
+The @code{\partial} command should be used only at the beginning of a
+piece.  If you use it after the beginning, warnings or problems may
+occur, so use @code{\set Timing.measurePosition} instead.
+
+@lilypond[quote,verbatim,relative=1]
+\time 6/8
+\partial 8
+e8 | a4 c8 b[ c b] |
+\set Timing.measurePosition = #(ly:make-moment -1 4)
+r8 e,8 | a4 c8 b[ c b] |
+@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 or effects may occur, in this case use
-@code{\set Timing.measurePosition} instead.
 
 @node Unmetered music
 @unnumberedsubsubsec Unmetered music
 
-@cindex bar lines, turning off
-@cindex bar numbering, turning off
 @cindex cadenza
+@cindex cadenza, beams
+@cindex cadenza, accidentals
+@cindex cadenza, bar lines
+@cindex cadenza, bar numbers
 @cindex unmetered music
+@cindex unmetered music, beams
+@cindex unmetered music, accidentals
+@cindex unmetered music, bar lines
+@cindex unmetered music, bar numbers
+@cindex accidentals, cadenzas
+@cindex accidentals, unmetered music
+@cindex bar lines, cadenzas
+@cindex bar lines, unmetered music
+@cindex bar numbers, cadenzas
+@cindex bar numbers, unmetered music
+@cindex beams, cadenzas
+@cindex beams, unmetered music
 
 @funindex \cadenzaOn
 @funindex cadenzaOn
 @funindex \cadenzaOff
 @funindex cadenzaOff
 
-Bar lines and bar numbers are calculated automatically.  For
-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.
+In metered music bar lines are inserted and bar numbers are calculated
+automatically. In unmetered music (i.e. cadenzas), this is not
+desirable and can be @q{switched off} using the command
+@code{\cadenzaOn}, then @q{switched back on} at the appropriate place
+using @code{\cadenzaOff}.
 
 @lilypond[verbatim,relative=2,quote]
 c4 d e d
@@ -1346,8 +1440,7 @@ c4 c d8[ d d] f4 g4.
 d4 e d c
 @end lilypond
 
-Bar numbering is resumed at the end of the cadenza as if the
-cadenza were not there:
+Bar numbering is resumed at the end of the cadenza.
 
 @lilypond[verbatim,relative=2,quote]
 % Show all bar numbers
@@ -1360,36 +1453,43 @@ c4 c d8[ d d] f4 g4.
 d4 e d c
 @end lilypond
 
-@cindex beaming in cadenzas
-@cindex beaming in unmetered music
-@cindex cadenza, beaming in
-@cindex unmetered music, beaming in
+A new bar is never started within a cadenza, even if one or more
+@code{\bar} commands are inserted within it.  Therefore, reminder
+accidentals will need to be added manually.  See @ref{Accidentals}.
 
-Automatic beaming is disabled by @code{\cadenzaOn} and enabled
-by @code{\cadenzaOff}.  Therefore, all beaming in cadenzas
-must be entered manually (@ref{Manual beams}).
+@lilypond[verbatim,relative=2,quote]
+c4 d e d
+\cadenzaOn
+cis4 d cis d
+\bar "|"
+cis4 d cis! d
+\cadenzaOff
+\bar "|"
+@end lilypond
+
+Automatic beaming is disabled by @code{\cadenzaOn}. Therefore, all
+beaming in cadenzas must be entered manually. See @ref{Manual beams}.
 
 @lilypond[verbatim,relative=2,quote]
 \repeat unfold 8 { c8 }
 \cadenzaOn
-\repeat unfold 5 { c8 }
+cis8 c c c c
 \bar"|"
+c8 c c
 \cadenzaOff
 \repeat unfold 8 { c8 }
 @end lilypond
 
-Note that these predefined commands affect all staves in the
-score, even when they are placed in just one @code{Voice}
-context.  To change this, move the @code{Timing_translator}
-from the @code{Score} context to the @code{Staff} context, as
-shown in @ref{Polymetric notation}.
+These predefined commands affect all staves in the score, even when
+placed in just one @code{Voice} context.  To change this, move the
+@code{Timing_translator} from the @code{Score} context to the
+@code{Staff} context.  See @ref{Polymetric notation}.
 
 @predefined
 @code{\cadenzaOn},
 @code{\cadenzaOff}.
 @endpredefined
 
-
 @seealso
 Music Glossary:
 @rglos{cadenza}.
@@ -1397,37 +1497,33 @@ Music Glossary:
 Notation Reference:
 @ref{Visibility of objects},
 @ref{Polymetric notation},
-@ref{Manual beams}.
+@ref{Manual beams},
+@ref{Accidentals}.
 
 Snippets:
 @rlsr{Rhythms}.
 
-
-@cindex cadenza line breaks
-@cindex cadenza page breaks
+@cindex cadenza, line breaks
+@cindex cadenza, page breaks
 @cindex unmetered music, line breaks
 @cindex unmetered music, page breaks
 @cindex breaks in unmetered music
-@cindex line breaks in cadenzas
-@cindex page breaks in cadenzas
-@cindex line breaks in unmetered music
-@cindex page breaks in unmetered music
+@cindex line breaks, cadenzas
+@cindex page breaks, cadenzas
+@cindex line breaks, unmetered music
+@cindex page breaks, unmetered music
 
 @knownissues
-
-LilyPond will insert line breaks and page breaks only at a
-bar line.  Unless the unmetered music ends before the end of the
-staff line, you will need to insert invisible bar lines with
+Automatic line and page breaks are inserted only at bar lines, so
+@q{invisible} bar lines will need to be inserted manually in long
+stretches of unmetered music to permit breaking:
 
 @example
 \bar ""
 @end example
 
-@noindent
-to indicate where breaks can occur.
-
-You should explicitly create a @code{Voice} context when starting a
-piece with @code{\cadenzaOn}, otherwise strange errors may occur.
+Explicitly create a @code{Voice} context when starting a piece with
+@code{\cadenzaOn}, else unexpected errors may occur.
 
 @example
 \new Voice @{
@@ -1460,42 +1556,38 @@ piece with @code{\cadenzaOn}, otherwise strange errors may occur.
 @funindex \times
 @funindex times
 
-Polymetric notation is supported, either explicitly or by modifying
-the visible time signature symbol and scaling the note durations.
+Polymetric notation is supported explicitly or by manually modifying the
+visible time signature symbol and/or scaling note durations.
 
-@strong{@i{Staves with different time signatures, equal measure lengths}}
+@subsubheading Different time signatures with equal-length measures
 
-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; see @ref{Time signature}.  The scaling 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}.
+Set a common time signature for each staff, and set the
+@code{timeSignatureFraction} to the desired fraction.  Then use the
+@code{\scaleDurations} function to scale the durations of the notes in
+each staff to the common time signature.
 
-@cindex beaming in polymetric music
-@cindex beaming in polymetric meter
+@cindex beams, with polymetric meters
+@cindex polymetric meters, with beams
 
-In this example, music with the time signatures of 3/4, 9/8, and
-10/8 are used in parallel.  In the second staff, shown durations
-are multiplied by 2/3, as 2/3 * 9/8 = 3/4, and in the third
-staff, shown durations are multiplied by 3/5, as 3/5 * 10/8 = 3/4.
-It will often be necessary to insert beams manually, as the
-duration scaling affects the autobeaming rules.
+In the following example, music with the time signatures of 3/4, 9/8 and
+10/8 are used in parallel.  In the second staff, shown durations are
+multiplied by 2/3 (because 2/3 * 9/8 = 3/4) and in the third staff, the
+shown durations are multiplied by 3/5 (because 3/5 * 10/8 = 3/4).  It
+may be necessary to insert beams manually, as the duration scaling will
+affect the autobeaming rules.
 
 @lilypond[quote,verbatim]
 \relative c' <<
   \new Staff {
     \time 3/4
     c4 c c |
-    c c c |
+    c4 c c |
   }
   \new Staff {
     \time 3/4
     \set Staff.timeSignatureFraction = #'(9 . 8)
     \scaleDurations #'(2 . 3)
-    \repeat unfold 6 { c8[ c c] }
+      \repeat unfold 6 { c8[ c c] }
   }
   \new Staff {
     \time 3/4
@@ -1503,13 +1595,13 @@ duration scaling affects the autobeaming rules.
     \scaleDurations #'(3 . 5) {
       \repeat unfold 2 { c8[ c c] }
       \repeat unfold 2 { c8[ c] } |
-      c4. c4. \times 2/3 { c8[ c c] } c4
+      c4. c \times 2/3 { c8[ c c] } c4
     }
   }
 >>
 @end lilypond
 
-@strong{@i{Staves with different time signatures, unequal bar lengths}}
+@subsubheading Different time signatures with unequal-length measures
 
 Each staff can be given its own independent time signature by
 moving the @code{Timing_translator} and the
@@ -1553,11 +1645,44 @@ moving the @code{Timing_translator} and the
 >>
 @end lilypond
 
-@snippets
+@funindex \compoundMeter
+@cindex compound time signatures
+@cindex time signature, compound
+
+@subsubheading Compound time signatures
+
+These are created using the @code{\compoundMeter} function.  The syntax
+for this is:
+
+@example
+\compoundMeter #'@code{(list of lists)}
+@end example
+
+The simplest construction is a single list, where the @emph{last} number
+indicates the bottom number of the time signature and those that come
+before it, the top numbers.
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{compound-time-signatures.ly}
+@lilypond[quote,verbatim]
+\relative c' {
+  \compoundMeter #'((2 2 2 8))
+  \repeat unfold 6 c8 \repeat unfold 12 c16
+}
+@end lilypond
 
+More complex meters can be constructed using additional lists.  Also,
+automatic beaming settings will be adjusted depending on the values.
+
+@lilypond[quote,verbatim]
+\relative c' {
+  \compoundMeter #'((1 4) (3 8))
+  \repeat unfold 5 c8 \repeat unfold 10 c16
+}
+
+\relative c' {
+  \compoundMeter #'((1 2 3 8) (3 4))
+  \repeat unfold 12 c8
+}
+@end lilypond
 
 @seealso
 Music Glossary:
@@ -1566,6 +1691,8 @@ Music Glossary:
 @rglos{meter}.
 
 Notation Reference:
+@ref{Automatic beams},
+@ref{Manual beams},
 @ref{Time signature},
 @ref{Scaling durations}.
 
@@ -1578,46 +1705,50 @@ Internals Reference:
 @rinternals{Default_bar_line_engraver},
 @rinternals{Staff}.
 
-
 @knownissues
+When using different time signatures in parallel, notes at the same
+moment will 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.
 
-When using different time signatures in parallel, notes
-at the same moment will 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
 @unnumberedsubsubsec Automatic note splitting
 
 @cindex notes, splitting
 @cindex splitting notes
+@cindex rests, splitting
+@cindex splitting rests
 
 @funindex Note_heads_engraver
 @funindex Completion_heads_engraver
+@funindex Completion_rest_engraver
 
-Long notes which overrun bar lines can be converted automatically
-to tied notes.  This is done by replacing the
-@code{Note_heads_engraver} with the
-@code{Completion_heads_engraver}.  In the following
-example, notes crossing the bar lines are split and tied.
+Long notes which overrun bar lines can be converted automatically to
+tied notes.  This is done by replacing the @code{Note_heads_engraver}
+with the @code{Completion_heads_engraver}.  Similarly, long rests which
+overrun bar lines are split automatically by replacing the
+@code{Rest_engraver} with the @code{Completion_rest_engraver}.  In the
+following example, notes and rests crossing the bar lines are split,
+notes are also tied.
 
 @lilypond[quote,verbatim,relative=1]
 \new Voice \with {
   \remove "Note_heads_engraver"
   \consists "Completion_heads_engraver"
+  \remove "Rest_engraver"
+  \consists "Completion_rest_engraver"
 }
 
-{ c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 }
+{ c2. c8 d4 e f g a b c8 c2 b4 a g16 f4 e d c8. c2 r1*2 }
 @end lilypond
 
-This engraver splits all running notes at the bar line, and
-inserts ties.  One of its uses is to debug complex scores: if the
-measures are not entirely filled, then the ties show exactly how
+These engravers split all running notes and rests at the bar line, and
+inserts ties for notes.  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.
 
-
 @seealso
 Music Glossary:
 @rglos{tie}
@@ -1632,11 +1763,11 @@ Snippets:
 Internals Reference:
 @rinternals{Note_heads_engraver},
 @rinternals{Completion_heads_engraver},
+@rinternals{Rest_engraver},
+@rinternals{Completion_rest_engraver},
 @rinternals{Forbid_line_break_engraver}.
 
-
 @knownissues
-
 Not all durations (especially those containing tuplets) can be
 represented exactly with normal notes and dots, but the
 @code{Completion_heads_engraver} will not insert tuplets.
@@ -1717,10 +1848,9 @@ be done with the @code{Pitch_squash_engraver} and
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {guitar-strum-rhythms.ly}
 
-
 @seealso
 Snippets:
 @rlsr{Rhythms}.
@@ -1747,8 +1877,7 @@ By default, beams are inserted automatically:
 
 @cindex beams, manual
 @cindex manual beams
-@cindex beams, setting rules for
-@cindex beams, custom rules for
+@cindex beams, customizing rules
 
 @funindex \autoBeamOn
 @funindex autoBeamOn
@@ -1775,48 +1904,42 @@ c4 c8 c8. c16 c8.
 c16 c8
 @end lilypond
 
-@cindex melismata, beams
-@cindex beams and melismata
+@cindex melismata, with beams
+@cindex beams, with melismata
 
 @warning{If beams are used to indicate melismata in songs, then
 automatic beaming should be switched off with @code{\autoBeamOff}
-and the beams indicated manually.}
-
-@warning{Using @code{@bs{}partcombine} with @code{@bs{}autoBeamOff} can
-produce unintended results.  See the snippet below for more information.}
+and the beams indicated manually.  Using @code{@bs{}partcombine} with
+@code{@bs{}autoBeamOff} can produce unintended results.  See the
+snippets for more information.}
 
 Beaming patterns that differ from the automatic defaults can be
 created; see @ref{Setting automatic beam behavior}.
 
-
 @predefined
 @code{\autoBeamOff},
 @code{\autoBeamOn}.
 @endpredefined
 
-
-@snippets
-
-
-@cindex line breaks and beams
-@cindex beams and line breaks
-
+@cindex beams, line breaks
+@cindex line breaks, beams
+@cindex beams, with knee gap
+@cindex knee gap, with beams
 @funindex breakable
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@snippets
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {beams-across-line-breaks.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {changing-beam-knee-gap.ly}
 
-@cindex \partcombine and \autoBeamOff
-@cindex \autoBeamOff and \partcombine
-
+@cindex beams, \partcombine with \autoBeamOff
+@cindex voices, \partcombine with \autoBeamOff
 
-@lilypondfile [verbatim, lilyquote, ragged-right, texidoc, doctitle]
+@lilypondfile [verbatim, quote, ragged-right, texidoc, doctitle]
 {partcombine-and-autobeamoff.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Manual beams},
@@ -1837,21 +1960,18 @@ Internals Reference:
 @rinternals{beam-interface},
 @rinternals{unbreakable-spanner-interface}.
 
-
 @knownissues
-
-Beams can collide with note heads and accidentals in other voices.
+The properties of a beam are determined at the @emph{start} of its
+construction and any additional beam-property changes that occur before
+the beam has been completed will not take effect until the @emph{next},
+new beam starts.
 
 
 @node Setting automatic beam behavior
 @unnumberedsubsubsec Setting automatic beam behavior
 
-
-@cindex automatic beams, tuning
-@cindex tuning automatic beaming
-@cindex automatic beam generation
-@cindex autobeam
-@cindex lyrics and beaming
+@cindex beams, with lyrics
+@cindex lyrics, with beams
 
 @funindex autoBeaming
 @funindex baseMoment
@@ -1964,7 +2084,7 @@ c16 c c |
 of beaming-rules.
 
 At this time the only available value of rule-type is
-@code{#'end} for beam ending.
+@code{'end} for beam ending.
 
 Beaming-rules is a scheme alist (or list of pairs) that indicates the
 beam type and the grouping to be applied to beams containing notes with
@@ -2006,10 +2126,54 @@ context to the default behavior.
 \repeat unfold 6 { a8 }
 @end lilypond
 
-These default automatic beaming settings for a time signature
+The default automatic beaming settings for a time signature
 are determined in @file{scm/time-signature-settings.scm}.
-The automatic beaming settings for a time signature can be changed
-as described in @ref{Time signature}.
+Changing the default automatic beaming settings
+for a time signature is described in @ref{Time signature}.
+
+Many automatic beaming settings for a time signature contain an
+entry for @code{beamExceptions}.  For example, 4/4 time tries to
+beam the measure in two if there are only eighth notes.  The
+@code{beamExceptions} rule can override the @code{beatStructure} setting
+if @code{beamExceptions} is not reset.
+
+@lilypond[quote,verbatim,relative=2]
+\time 4/4
+\set Timing.baseMoment = #(ly:make-moment 1 8)
+\set Timing.beatStructure = #'(3 3 2)
+% This won't beam (3 3 2) because of beamExceptions
+\repeat unfold 8 {c8} |
+% This will beam (3 3 2) because we clear beamExceptions
+\set Timing.beamExceptions = #'()
+\repeat unfold 8 {c8}
+@end lilypond
+
+In traditional engraving, eighth notes can have special beaming rules.
+A measure consisting of only eighth notes can be beamed in one.  This rule is
+controlled by the context property @code{beamWholeMeasure}:
+
+@lilypond[quote,verbatim,relative=2]
+\time 3/4
+% By default we beam in one
+\repeat unfold 6 { a8 }
+% We can avoid beaming in one
+\set Timing.beamWholeMeasure = ##f
+\repeat unfold 6 { a8 }
+@end lilypond
+
+In some engraving from the Romantic and Classical periods,
+a half-measure of eighth notes can be beamed
+together even though this violates the general rule (see Gould, p. 153).
+This behavior is controlled by the context property @code{beamHalfMeasure}:
+
+@lilypond[quote,verbatim,relative=2]
+\time 3/4
+% By default we avoid half-measure beams
+r4. a8 a a |
+% We can allow half-measure beams
+\set Timing.beamHalfMeasure = ##t
+r4. a8 a a |
+@end lilypond
 
 @i{@strong{How automatic beaming works}}
 
@@ -2042,36 +2206,40 @@ end beams at the end of beats.
 
 @end itemize
 
-In the rules above, the beam-type is the duration of the
+In the rules above, the @emph{beam-type} is the duration of the
 shortest note in the beamed group.
 
-For reference, the default beaming rules are found in
+The default beaming rules can be found in
 @file{scm/time-signature-settings.scm}.
 
 @snippets
 
 @cindex beams, subdividing
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {subdividing-beams.ly}
 
+@cindex beamlets, orienting
+
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{strict-beat-beaming.ly}
+
 @cindex measure groupings
 @cindex beats, grouping
 @cindex grouping beats
 @cindex measure sub-grouping
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {conducting-signs,-measure-grouping-signs.ly}
 
-@cindex beam, last in score
-@cindex beam, last in polyphonic voice
+@cindex beam, endings in a score
+@cindex beam, endings with multiple voices
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {beam-endings-in-score-context.ly}
 
-
 @seealso
-Installed files:
+Installed Files:
 @file{scm/beam-settings.scm}.
 
 Snippets:
@@ -2083,7 +2251,6 @@ Internals Reference:
 @rinternals{BeamForbidEvent},
 @rinternals{beam-interface}.
 
-
 @knownissues
 If a score ends while an automatic beam has not been ended and is
 still accepting notes, this last beam will not be typeset at all.
@@ -2093,6 +2260,52 @@ automatic beam is still accepting notes, it is not typeset.
 The workaround for these problems is to manually beam the last
 beam in the voice or score.
 
+By default, the @code{Timing} translator is aliased to the
+@code{Score} context.  This means that setting the time signature
+in one staff will affect the beaming of the other staves as well.
+Thus, a time signature setting in a later staff will reset custom
+beaming that was set in an earlier staff.
+One way to avoid this problem is to set the time signature
+in only one staff.
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  \new Staff {
+    \time 3/4
+    \set Timing.baseMoment = #(ly:make-moment 1 8)
+    \set Timing.beatStructure = #'(1 5)
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \repeat unfold 6 { a8 }
+  }
+>>
+@end lilypond
+
+The default beam settings for the time signature can also be changed, so
+that the desired beaming will always be used.  Changes in automatic
+beaming settings for a time signature are described in
+@ref{Time signature}.
+
+@lilypond[quote,verbatim,relative=2]
+<<
+  \new Staff {
+    \overrideTimeSignatureSettings
+      #'(3 . 4)         % timeSignatureFraction
+      #'(1 . 8)         % baseMomentFraction
+      #'(1 5)           % beatStructure
+      #'()		% beamExceptions
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+  \new Staff {
+    \time 3/4
+    \repeat unfold 6 { a8 }
+  }
+>>
+@end lilypond
+
+
 @node Manual beams
 @unnumberedsubsubsec Manual beams
 
@@ -2174,10 +2387,9 @@ g16 a]
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {flat-flags-and-beam-nibs.ly}
 
-
 @seealso
 Notation Reference:
 @ref{Direction and placement},
@@ -2212,9 +2424,9 @@ feathered beam must be indicated manually using @code{[} and
 direction to the @code{Beam} property @code{grow-direction}.
 
 If the placement of the notes and the sound in the MIDI output is to
-reflect the ritardando or accelerando indicated by the feathered beam
-the notes must be grouped as a music expression delimited by braces
-and preceded by a @code{featherDurations} command which specifies
+reflect the @emph{ritardando} or @emph{accelerando} indicated by the
+feathered beam the notes must be grouped as a music expression delimited
+by braces and preceded by a @code{featherDurations} command which specifies
 the ratio between the durations of the first and last notes in the
 group.
 
@@ -2245,7 +2457,6 @@ the last four 32nd notes are at a constant tempo.
 The spacing in the printed output represents the
 note durations only approximately, but the MIDI output is exact.
 
-
 @predefined
 @code{\featherDurations}.
 @endpredefined
@@ -2254,9 +2465,7 @@ note durations only approximately, but the MIDI output is exact.
 Snippets:
 @rlsr{Rhythms}.
 
-
 @knownissues
-
 The @code{\featherDurations} command only works with very short
 music snippets, and when numbers in the fraction are small.
 
@@ -2264,7 +2473,6 @@ music snippets, and when numbers in the fraction are small.
 @node Bars
 @subsection Bars
 
-
 @menu
 * Bar lines::
 * Bar numbers::
@@ -2504,7 +2712,6 @@ The default bar type used for automatically inserted bar lines is
 @code{"|"}.  This may be changed at any time with
 @samp{\set Timing.defaultBarType = @var{bartype}}.
 
-
 @seealso
 Notation Reference:
 @ref{Line breaking},
@@ -2568,30 +2775,33 @@ c1 | c | c | c
 c1 | c | c | c
 @end lilypond
 
-
 @snippets
-
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-the-bar-number-for-the-first-measure.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-bar-numbers-at-regular-intervals.ly}
 
 @cindex measure number, format
 @cindex bar number, format
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {printing-bar-numbers-inside-boxes-or-circles.ly}
 
+@cindex bar numbers, with letters
+@cindex bar numbers, with repeats
+
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{alternative-bar-numbering.ly}
+
 @cindex bar number alignment
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {aligning-bar-numbers.ly}
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {removing-bar-numbers-from-a-score.ly}
 
-
 @seealso
 Snippets:
 @rlsr{Rhythms}.
@@ -2600,7 +2810,6 @@ Internals Reference:
 @rinternals{BarNumber},
 @rinternals{Bar_number_engraver}.
 
-
 @cindex bar number collision
 @cindex collision, bar number
 
@@ -2689,7 +2898,6 @@ example,
 will print a warning if the @code{currentBarNumber} is not 123
 when it is processed.
 
-
 @seealso
 Snippets:
 @rlsr{Rhythms}.
@@ -2833,6 +3041,10 @@ For common tweaks to the positioning of rehearsal marks, see
 @ref{Formatting text}.  For more precise control, see
 @code{break-alignable-interface} in @ref{Aligning objects}.
 
+The file @file{scm/translation-functions.scm} contains
+the definitions of @code{format-mark-numbers} and
+@code{format-mark-letters}.  They can be used as inspiration for
+other formatting functions.
 
 @seealso
 Notation Reference:
@@ -2841,10 +3053,7 @@ Notation Reference:
 @ref{Aligning objects}.
 
 Installed Files:
-@file{scm/translation-functions.scm} contains
-the definitions of @code{format-mark-numbers} and
-@code{format-mark-letters}.  They can be used as inspiration for
-other formatting functions.
+@file{scm/translation-functions.scm}.
 
 Snippets:
 @rlsr{Rhythms}.
@@ -2874,33 +3083,39 @@ Internals Reference:
 @cindex acciaccatura
 
 @funindex \grace
-@funindex grace
+@funindex \slashedGrace
+@funindex \acciaccatura
+@funindex \appoggiatura
 
-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.
+Grace notes are musical ornaments, printed in a smaller font, that take
+up no additional logical time in a measure.
 
 @lilypond[quote,relative=2,verbatim]
-c4 \grace c16 c4
-\grace { c16[ d16] } c2
+c4 \grace b16 a4(
+\grace { b16[ c16] } a2)
 @end lilypond
 
-LilyPond also supports two special types of grace notes, the
+There are three other types of grace notes possible; 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.
+note with a slashed stem -- and the @emph{appoggiatura}, which takes a
+fixed fraction of the main note it is attached to and prints without the
+slash.  It is also possible to write a grace note with a slashed stem,
+like the @emph{acciaccatura} but without the slur, so as to place it
+between notes that are slurred themselves, using the
+@code{\slashedGrace} function.
 
 @lilypond[quote,relative=2,verbatim]
-\grace c8 b4
 \acciaccatura d8 c4
 \appoggiatura e8 d4
-\acciaccatura { g16[ f] } e4
+\acciaccatura { g16[ f] } e2
+\slashedGrace a,8 g4
+\slashedGrace b16 a4(
+\slashedGrace b8 a2)
 @end lilypond
 
-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
+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,relative=2,verbatim]
 <<
@@ -2987,19 +3202,18 @@ direction is overridden and then reverted.
 
 @snippets
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {using-grace-note-slashes-with-normal-heads.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {tweaking-grace-layout-within-music.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {redefining-grace-note-global-defaults.ly}
 
-@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+@lilypondfile[verbatim,quote,texidoc,doctitle]
 {positioning-grace-notes-with-floating-space.ly}
 
-
 @seealso
 Music Glossary:
 @rglos{grace notes},
@@ -3007,6 +3221,7 @@ Music Glossary:
 @rglos{appoggiatura}.
 
 Notation Reference:
+@ref{Scaling durations},
 @ref{Manual beams}.
 
 Installed Files:
@@ -3023,7 +3238,6 @@ Internals Reference:
 
 
 @knownissues
-
 @cindex acciaccatura, multi-note
 @cindex multi-note acciaccatura
 @cindex grace-note synchronization
@@ -3057,9 +3271,61 @@ durations in the other staves.  For the above example
 >>
 @end lilypond
 
-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.
+The use of grace notes within voice contexts confuses the way the voice
+is typeset. This can be overcome by inserting a rest or note between the
+voice command and the grace note.
+
+@lilypond[quote,verbatim]
+accMusic = {
+  \acciaccatura { f8 } e8 r8 \acciaccatura { f8 } e8 r4
+}
+
+\new Staff {
+  <<
+    \new Voice {
+      \relative c'' {
+        r8 r8 \voiceOne \accMusic \oneVoice r8 |
+        r8 \voiceOne r8 \accMusic \oneVoice r8 |
+      }
+    }
+    \new Voice {
+      \relative c' {
+        s8 s8 \voiceTwo \accMusic \oneVoice s8 |
+        s8 \voiceTwo r8 \accMusic \oneVoice s8 |
+      }
+    }
+  >>
+}
+@end lilypond
+
+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.
+
+Each grace note in MIDI output has a length of 1/4 of its actual
+duration.  If the combined length of the grace notes is greater than the
+length of the preceding note a @qq{@code{Going back in MIDI time}}
+error will be generated.  Either make the grace notes shorter in
+duration, for example:
+
+@example
+\acciaccatura @{ c'8[ d' e' f' g'] @}
+@end example
+
+becomes:
+
+@example
+\acciaccatura @{ c'16[ d' e' f' g'] @}
+@end example
+
+Or explicitly change the musical duration:
+
+@example
+\acciaccatura @{ \scaleDurations #' (1 . 2) @{ c'8[ d' e' f' g'] @} @}
+@end example
+
+See @ref{Scaling durations}.
+
 
 @node Aligning to cadenzas
 @unnumberedsubsubsec Aligning to cadenzas
@@ -3090,15 +3356,14 @@ MyCadenza = \relative c' {
     \MyCadenza c'1
   }
   \new Staff {
-    #(ly:export (mmrest-of-length MyCadenza))
+    $(mmrest-of-length MyCadenza)
     c'1
-    #(ly:export (skip-of-length MyCadenza))
+    $(skip-of-length MyCadenza)
     c'1
   }
 >>
 @end lilypond
 
-
 @seealso
 Music Glossary:
 @rglos{cadenza}.
@@ -3183,7 +3448,6 @@ duration of n/m of a whole note.  For example,
 @code{ly:make-moment 7 16} is the duration of seven sixteenths
 notes.
 
-
 @seealso
 Notation Reference:
 @ref{Bar numbers},
@@ -3195,4 +3459,3 @@ Snippets:
 Internals Reference:
 @rinternals{Timing_translator},
 @rinternals{Score}.
-