From 4244c3a9fbf1f3ff2e20e665f92516d35b61de53 Mon Sep 17 00:00:00 2001
From: David Kastrup <dak@gnu.org>
Date: Mon, 3 Apr 2017 00:25:10 +0200
Subject: [PATCH] Issue 5114/4: Document \voices

---
 Documentation/learning/fundamental.itely  | 65 ++++++++++++++++++++---
 Documentation/notation/simultaneous.itely | 22 ++++++++
 2 files changed, 80 insertions(+), 7 deletions(-)

diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 9a990ac9de..8e8fd91b6e 100644
--- a/Documentation/learning/fundamental.itely
+++ b/Documentation/learning/fundamental.itely
@@ -683,12 +683,30 @@ of slurs, stems, ties, dynamics etc., is set appropriately.
 \new Staff \relative {
   % Main voice
   c'16 d e f
-  %    Voice = "1"   Voice = "2"              Voice = "3"
+  %  Voice = "1"   Voice = "2"             Voice = "3"
   << { g4 f e } \\ { r8 e4 d c8~ } >> |
   << { d2 e }   \\ { c8 b16 a b8 g~ 2 } \\ { s4 b c2 } >> |
 }
 @end lilypond
 
+@funindex \voices
+If you prefer entering the voices in a different order, like top
+to bottom, you can specify the respective voice numbers in front
+of one @code{<< @dots{} >>} construct using the @code{\voices}
+command, like
+
+@lilypond[quote,verbatim]
+\new Staff \relative {
+  % Main voice
+  c'16 d e f
+  %  Voice = "1"   Voice = "2"
+  << { g4 f e } \\ { r8 e4 d c8~ } >> |
+  \voices 1,3,2
+  %  Voice = "1"   Voice = "3"    Voice = "2"
+  << { d2 e }   \\ { s4 b c2 } \\ { c8 b16 a b8 g~ 2 } >> |
+}
+@end lilypond
+
 These voices are all separate from the main voice that contains
 the notes just outside the @code{<< @dots{} >>} construct.  Let's call
 this the @emph{simultaneous construct}.  Slurs and ties may only
@@ -798,6 +816,7 @@ later sections.
 @lilypond[quote,ragged-right]
 \new Staff \relative {
   \key aes \major
+  \voices 1,2,4    % No voice three
   <<  % Voice one
     { c''2 aes4. bes8 }
   \\  % Voice two
@@ -808,7 +827,6 @@ later sections.
       \once \override NoteColumn.force-hshift = #0.5
       des2
     }
-  \\  % No voice three
   \\  % Voice four
     {
       \override NoteColumn.force-hshift = #0
@@ -845,6 +863,7 @@ not understand.
 @lilypond[quote,ragged-right]
 \new Staff \relative {
   \key aes \major
+  \voices 1,2,4  % No Voice three (we want stems down)
   <<
     {  % Voice one
       \voiceOneStyle
@@ -858,7 +877,6 @@ not understand.
       \once \override NoteColumn.force-hshift = #0.5
       des2
     }
-  \\  % No Voice three (we want stems down)
   \\  % Voice four
     { \voiceThreeStyle
       \override NoteColumn.force-hshift = #0
@@ -895,17 +913,19 @@ odd-numbered voices taking upward stems and the even-numbered
 voices downward ones.  The stems for voices 1 and 2 are right,
 but the stems in voice 3 should go down in this particular piece
 of music.  We can correct this by skipping voice three
-and placing the music in voice four.  This is done by simply
-adding another pair of @code{\\}.
+and placing the music in voice four.  This could be done by simply
+adding another pair of @code{\\}, but we use the @code{\voices}
+command instead (which would also allow us to enter the voices in
+different order if we preferred doing that):
 
 @lilypond[quote,verbatim,ragged-right]
 \new Staff \relative {
   \key aes \major
+  \voices 1,2,4   % Omit Voice three
   <<  % Voice one
     { c''2 aes4. bes8 }
   \\  % Voice two
     { <ees, c>2 des }
-  \\  % Omit Voice three
   \\  % Voice four
     { aes'2 f4 fes }
   >> |
@@ -1023,7 +1043,7 @@ markup, ties, slurs, and dynamics:
 }
 @end lilypond
 
-Now let's look at three different ways to notate the same passage of
+Now let's look at four different ways to notate the same passage of
 polyphonic music, each of which is advantageous in different
 circumstances, using the example from the previous section.
 
@@ -1059,6 +1079,37 @@ permitting a phrasing slur to be drawn over them.
 }
 @end lilypond
 
+@cindex voices, continued
+@funindex \voices
+
+The @code{\voices} command can also be used for continuing a main
+voice into the simultaneous construct:
+
+@lilypond[quote,ragged-right,verbatim]
+\new Staff \relative {
+  \new Voice = "main" {
+    \voiceOneStyle
+    % This section is homophonic
+    c'16^( d e f
+    % Start simultaneous section of three voices
+    \voices "main",2,3
+    <<
+      % Continue the main voice in parallel
+      { g4 f e | d2 e) | }
+      % Initiate second voice
+    \\
+      % Set stems, etc., down
+      { r8 e4 d c8~ | 8 b16 a b8 g~ 2 | }
+    \\
+      % Initiate third voice
+      % Set stems, etc, up
+      { s2. | s4 b c2 | }
+    >>
+  }
+}
+@end lilypond
+
+
 @cindex nesting music expressions
 @cindex nesting simultaneous constructs
 @cindex nesting voices
diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index d9c7fb42d4..c9810d62c3 100644
--- a/Documentation/notation/simultaneous.itely
+++ b/Documentation/notation/simultaneous.itely
@@ -559,6 +559,28 @@ upstems, and the even-numbered voices are given downstems:
 >>
 @end lilypond
 
+@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.}
 
-- 
2.39.2