DOC: NR 1.5.2 Multiple voices - part combining (issue4188056)

[ColinPKCampbell]

Reviewers: ,

Message:
Add documentation of partcombine functions.
See issue 1518 on the bug tracker.

Description:
DOC: NR 1.5.2 Multiple voices - part combining

Adds explanations and examples of part combine functions to
NR 1.5.2 Multiple voices - Automatic part combining

Patch based on issue 4132045 by Reinhold

Please review this at http://codereview.appspot.com/4188056/

Affected files:
  M Documentation/notation/simultaneous.itely


Index: Documentation/notation/simultaneous.itely
diff --git a/Documentation/notation/simultaneous.itely  
b/Documentation/notation/simultaneous.itely
index  
ededc3fc377b06e3a6bce7cb11590c0567feca51..5a041e408248972b4a513f92513542841b06db9b  
100644
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -836,6 +836,70 @@ A @code{\relative} section that is outside of  
@code{\partcombine}
 has no effect on the pitches of @address@hidden and
 @address@hidden

+Often the decision to combine notes into a chord or to print one voice
+as solo is not ideal, since the part-combiner considers each note
+separately. However, in professional scores voices are kept apart for
+longer periods, even if one or two notes actually coincide and could be
+printed as unisono. For this reason, the part-combiner's strategy can be
+overriden with any of the following commands. All commands ending in
address@hidden apply only to the following note, while all other commands
+change the state permanently.
+
address@hidden
address@hidden
address@hidden, @code{\partcombineApartOnce}:
+Keep the notes as two separate voices, even if they can be combined to a
+chord or unisono.
+
address@hidden
address@hidden, @code{\partcombineChordsOnce}:
+Combine the notes to a chord.
+
address@hidden
address@hidden, @code{\partcombineUnisonoOnce}:
+The two voices are unisono.
+
address@hidden
address@hidden, @code{\partcombineSoloIOnce}:
+Show only voice one and mark it as solo.
+
address@hidden
address@hidden, @code{\partcombineSoloIIOnce}:
+Show only voice two and mark it as solo.
+
address@hidden
address@hidden, @code{\partcombineAutomaticOnce}:
+Use the combination strategy automatically determined, or revert
+from the left one of each pair of commands above.
+
address@hidden itemize
+
address@hidden,verbatim]
+instrumentOne = \relative c' {
+  \partcombineApart c2^"apart" e |
+  \partcombineAutomatic e^"auto" e |
+  \partcombineChords e'^"chord" e |
+  \partcombineAutomatic c c |
+  \partcombineApart c^"apart" \partcombineChordsOnce e^"chord once" |
+  c c |
+}
+instrumentTwo = \relative c' {
+  c2 c |
+  e2 e |
+  a,2 c |
+  c2 c' |
+  c2 c |
+  c2 c
+}
+
+<<
+  \new Staff \instrumentOne
+  \new Staff \instrumentTwo
+  \new Staff \partcombine \instrumentOne \instrumentTwo
+>>
address@hidden lilypond
+
+
 @snippets

 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]