Create engravers for merging rests

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

diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index a29dd9c4ae25a89d80dfceb1fec95ec6c0c1c5be..1ad24d94b9f7a260d3f653659f466b8ac92c949f 100644 (file)
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -180,7 +180,7 @@ chord.  The chord repetition symbol is @code{q}:
 @end lilypond
 
 As with regular chords, the chord repetition symbol can be used with
-durations, articulations, markups, slurs, beams, etc. as only the
+durations, articulations, markups, slurs, beams, etc., as only the
 pitches of the previous chord are duplicated.
 
 @lilypond[verbatim,quote]
@@ -389,6 +389,7 @@ multiple staves.
 * Single-staff polyphony::
 * Voice styles::
 * Collision resolution::
+* Merging rests::
 * Automatic part combining::
 * Writing music in parallel::
 @end menu
@@ -559,8 +560,30 @@ upstems, and the even-numbered voices are given downstems:
 >>
 @end lilypond
 
-@warning{Lyrics, spanners (such as slurs, ties, hairpins etc.) cannot be
-created @q{across} voices.}
+@funindex \voices
+When a different voice entry order is desired, the command
+@code{\voices} may be convenient:
+
+@lilypond[quote,verbatim]
+\new Staff \voices 1,3,5,6,4,2 <<
+  \time 2/4
+  { f''2 }  % 1: highest
+  \\
+  { d''2 }  % 3: second-highest
+  \\
+  { b'2  }  % 5: third-highest
+  \\
+  { g'2  }  % 6: third-lowest
+  \\
+  { e'2  }  % 4: second-lowest
+  \\
+  { c'2  }  % 2: lowest
+>>
+@end lilypond
+
+
+@warning{Lyrics and spanners (such as slurs, ties, hairpins, etc.) cannot
+be created @q{across} voices.}
 
 @subsubsubheading Identical rhythms
 
@@ -887,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
 
@@ -1118,12 +1174,12 @@ started when combining notes that have just started in the other
 @code{Voice}.  This can lead to a number of unexpected issues including
 @qq{Solo} or @qq{Unison} marks being printed incorrectly.
 
-@code{\partcombine} keeps all spanners (slurs, ties, hairpins etc.) in
+@code{\partcombine} keeps all spanners (slurs, ties, hairpins, etc.) in
 the same @code{Voice} so that if any such spanners start or end in a
 different @code{Voice}, they may not be printed properly or at all.
 
 If the @code{\partcombine} function cannot combine both music
-expressions (i.e. when both voices have different durations), it will
+expressions (i.e., when both voices have different durations), it will
 give the voices, internally, its own custom names: @code{one} and
 @code{two} respectively.  This means if there is any @qq{switch} to a
 differently named @code{Voice} context, the events in that differently