From 29ffa6f896be486b81c09204edb404e8e66f8f57 Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Fri, 25 Jul 2008 13:41:47 -0700
Subject: [PATCH] Update from Francisco.

---
 Documentation/user/simultaneous.itely | 37 ++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 9 deletions(-)

diff --git a/Documentation/user/simultaneous.itely b/Documentation/user/simultaneous.itely
index 0de5874d02..b4b69b52a6 100644
--- a/Documentation/user/simultaneous.itely
+++ b/Documentation/user/simultaneous.itely
@@ -166,7 +166,9 @@ separated by double backslashes.
 
 First and third voices get stems up, second and fourth voices get
 stems down, third and fourth voice noteheads are horizontally shifted,
-and rests move to avoid collisions.
+and rests move to avoid collisions.  In the following example, the
+intermediate voice has stems up, therefore we enter it in the third
+place, so it becomes voice three which has the stems up as desired.
 
 @lilypond[quote,relative=3,verbatim]
 <<
@@ -178,9 +180,23 @@ and rests move to avoid collisions.
 >>
 @end lilypond
 
-For these purposes, the @code{\voiceOne} ... @code{\voiceFour}
-commands can be used instead.  Spacing rests are often used to avoid
-too many rests, as seen in the example avobe.
+Spacing rests are often used to avoid too many rests, as seen in the
+example above.
+
+The method exposed creates two new voices when the @code{<<@{...@} \\
+@{...@}>>} construction is found in the code; to temporally add only
+one additional voice to an existing one, it is necessary to
+instantiate that voice explicitly. For these purposes, the
+@code{\voiceOne} ... @code{\voiceFour}, and @code{\oneVoice} commands
+can be used:
+
+@example
+<< @{ \voiceOne ... @} \new Voice @{ \voiceTwo ... @} >> \oneVoice
+@end example
+
+This is a better construction to keep the control of the voices, for
+example, to ease a consistent assign of lyrics to the proper voice
+context.
 
 @predefined
 
@@ -191,12 +207,18 @@ too many rests, as seen in the example avobe.
 @funindex \voiceThree
 @code{\voiceThree},
 @funindex \voiceFour
-@code{\voiceFour}.
+@code{\voiceFour},
+@funindex \oneVoice
+@code{\oneVoice}.
 
 @seealso
 
 Learning Manual:
-@rlearning{Voices contain music}.
+@rlearning{Voices contain music},
+@rlearning{Explicitly instantiating voices}.
+
+Notation Reference:
+@ref{Percussion staves}.
 
 Snippets:
 @rlsr{Simultaneous notes}.
@@ -378,9 +400,6 @@ Notes are only merged if they have opposing stem directions (i.e., in
 @funindex \mergeDifferentlyHeadedOff
 @code{\mergeDifferentlyHeadedOff}.
 
-@funindex \oneVoice
-@code{\oneVoice}.
-
 @funindex \shiftOn
 @code{\shiftOn},
 @funindex \shiftOnn
-- 
2.39.2