Issue 5114/4: Document \voices

diff --git a/Documentation/learning/fundamental.itely b/Documentation/learning/fundamental.itely
index 9a990ac9de5634d3d9663ebede32cf2cdc7717bd..8e8fd91b6e898fd5e54da600fc431d88f6465fce 100644 (file)
--- 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
 \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
 
   << { 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
 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
 @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
   <<  % Voice one
     { c''2 aes4. bes8 }
   \\  % Voice two


@@ -808,7 +827,6 @@ later sections.
       \once \override NoteColumn.force-hshift = #0.5
       des2
     }
       \once \override NoteColumn.force-hshift = #0.5
       des2
     }

-  \\  % No voice three

   \\  % Voice four
     {
       \override NoteColumn.force-hshift = #0
   \\  % Voice four
     {
       \override NoteColumn.force-hshift = #0


@@ -845,6 +863,7 @@ not understand.
 @lilypond[quote,ragged-right]
 \new Staff \relative {
   \key aes \major
 @lilypond[quote,ragged-right]
 \new Staff \relative {
   \key aes \major

+  \voices 1,2,4  % No Voice three (we want stems down)

   <<
     {  % Voice one
       \voiceOneStyle
   <<
     {  % Voice one
       \voiceOneStyle


@@ -858,7 +877,6 @@ not understand.
       \once \override NoteColumn.force-hshift = #0.5
       des2
     }
       \once \override NoteColumn.force-hshift = #0.5
       des2
     }

-  \\  % No Voice three (we want stems down)

   \\  % Voice four
     { \voiceThreeStyle
       \override NoteColumn.force-hshift = #0
   \\  % 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
 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
 
 @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 }
   <<  % Voice one
     { c''2 aes4. bes8 }
   \\  % Voice two
     { <ees, c>2 des }

-  \\  % Omit Voice three

   \\  % Voice four
     { aes'2 f4 fes }
   >> |
   \\  % Voice four
     { aes'2 f4 fes }
   >> |


@@ -1023,7 +1043,7 @@ markup, ties, slurs, and dynamics:
 }
 @end lilypond
 
 }
 @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.
 
 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
 
 }
 @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
 @cindex nesting music expressions
 @cindex nesting simultaneous constructs
 @cindex nesting voices

diff --git a/Documentation/notation/simultaneous.itely b/Documentation/notation/simultaneous.itely
index d9c7fb42d44056798d5ab8ca970a8809d2e8be90..c9810d62c305f127fb1255ba48188372b4f518a6 100644 (file)
--- 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
 
 >>
 @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.}
 
 @warning{Lyrics and spanners (such as slurs, ties, hairpins, etc.) cannot
 be created @q{across} voices.}