Create engravers for merging rests

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

diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index b7b2f3e7ea228203142d76591c57e428d7dea481..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]
@@ -341,7 +341,6 @@ collision resolution whatsover and may have other unintended effects
 @cindex note cluster
 
 @funindex \makeClusters
-@funindex makeClusters
 
 A cluster indicates a continuous range of pitches to be played.
 They can be denoted as the envelope of a set of notes.  They are
@@ -390,6 +389,7 @@ multiple staves.
 * Single-staff polyphony::
 * Voice styles::
 * Collision resolution::
+* Merging rests::
 * Automatic part combining::
 * Writing music in parallel::
 @end menu
@@ -404,11 +404,9 @@ multiple staves.
 @cindex lyrics assigned to one voice
 
 @funindex \voiceOne
-@funindex voiceOne
 @funindex \voiceOne ... \voiceFour
 @funindex Voice
 @funindex \oneVoice
-@funindex oneVoice
 
 @subsubsubheading Explicitly instantiating voices
 
@@ -562,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
 
@@ -667,21 +687,13 @@ Snippets:
 @cindex voices, multiple
 @cindex shift rest, automatic
 @funindex \shiftOn
-@funindex shiftOn
 @funindex \shiftOnn
-@funindex shiftOnn
 @funindex \shiftOnnn
-@funindex shiftOnnn
 @funindex \shiftOff
-@funindex shiftOff
 @funindex \mergeDifferentlyDottedOn
-@funindex mergeDifferentlyDottedOn
 @funindex \mergeDifferentlyDottedOff
-@funindex mergeDifferentlyDottedOff
 @funindex \mergeDifferentlyHeadedOn
-@funindex mergeDifferentlyHeadedOn
 @funindex \mergeDifferentlyHeadedOff
-@funindex mergeDifferentlyHeadedOff
 
 The note heads of notes in different voices with the same pitch,
 same note head and opposite stem direction are automatically
@@ -898,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
 
@@ -907,7 +952,6 @@ are at the same time differently dotted are not clear.
 @cindex a due part
 @cindex solo part
 @funindex \partcombine
-@funindex partcombine
 
 Automatic part combining is used to merge two separate parts of music
 onto a single staff. This can be especially helpful when typesetting
@@ -1010,17 +1054,11 @@ effect on the pitches of @code{@var{musicexpr1}} or
 @code{@var{musicexpr2}}.
 
 @funindex \partcombineChords
-@funindex partcombineChords
 @funindex \partcombineApart
-@funindex partcombineApart
 @funindex \partcombineUnisono
-@funindex partcombineUnisono
 @funindex \partcombineSoloI
-@funindex partcombineSoloI
 @funindex \partcombineSoloII
-@funindex partcombineSoloII
 @funindex \partcombineAutomatic
-@funindex partcombineAutomatic
 
 In professional scores, voices are often kept apart from each other for
 long passages of music even if some of the notes are the same in both
@@ -1136,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
@@ -1159,7 +1197,6 @@ Refer also to @emph{Known issues and warnings} when using
 @cindex interleaved music
 @cindex parallel music
 @funindex \parallelMusic
-@funindex parallelMusic
 
 Music for multiple parts can be interleaved in input code.  The
 function @code{\parallelMusic} accepts a list with the names of a