Create engravers for merging rests

[lilypond.git] / Documentation / notation / simultaneous.itely

diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index c9810d62c305f127fb1255ba48188372b4f518a6..1ad24d94b9f7a260d3f653659f466b8ac92c949f 100644 (file)
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -389,6 +389,7 @@ multiple staves.
 * Single-staff polyphony::
 * Voice styles::
 * Collision resolution::
+* Merging rests::
 * Automatic part combining::
 * Writing music in parallel::
 @end menu
@@ -909,6 +910,39 @@ are at the same time differently dotted are not clear.
 @end ignore
 
 
+@node Merging rests
+@unnumberedsubsubsec Merging rests
+
+When using multiple voices it is common to merge rests which occur in both
+parts. This can be accomplished using @code{Merge_rests_engraver}.
+
+@lilypond[quote,verbatim]
+voiceA = \relative { d''4 r d2 | R1 | }
+voiceB = \relative { fis'4 r g2 | R1 | }
+\score {
+  <<
+    \new Staff \with {
+      instrumentName = "unmerged"
+    }
+    <<
+      \new Voice { \voiceOne \voiceA }
+      \new Voice { \voiceTwo \voiceB }
+    >>
+    \new Staff \with {
+      instrumentName = "merged"
+      \consists #Merge_rests_engraver
+    }
+    <<
+      \new Voice { \voiceOne \voiceA }
+      \new Voice { \voiceTwo \voiceB }
+    >>
+  >>
+}
+@end lilypond
+
+Setting the context property @code{suspendRestMerging} to @code{##t} allows for
+turning off rest merging temporarily.
+
 @node Automatic part combining
 @unnumberedsubsubsec Automatic part combining