Update from Francisco.

diff --git a/Documentation/user/simultaneous.itely b/Documentation/user/simultaneous.itely
index be66dd6f597bc69eb7d4587729f24b5ef80429e2..b0cca0000cd2af0f88813879df79c407c865c259 100644 (file)
--- a/Documentation/user/simultaneous.itely
+++ b/Documentation/user/simultaneous.itely
@@ -18,8 +18,8 @@ in a piece of music.  Polyphony in LilyPond refers to having more
 than one voice on the same staff.
 
 @menu
-* Single voice::
-* Multiple voices::
+* Single voice::                
+* Multiple voices::             
 @end menu
 
 
@@ -29,9 +29,8 @@ than one voice on the same staff.
 This section discusses simultaneous notes inside the same voice.
 
 @menu
-* Chorded notes::
-* Parallel notes::
-* Clusters::
+* Chorded notes::               
+* Clusters::                    
 @end menu
 
 @node Chorded notes
@@ -76,40 +75,6 @@ staves.  To avoid this, use explicit chords instead as in
 @code{<g a>8 <e a>8}.
 @end ignore
 
-@node Parallel notes
-@unnumberedsubsubsec Parallel notes
-
-@ignore
-Pieces of music having the same rhythm form chords when
-combined in parallel into the same @code{Voice} context by enclosing
-them into double angle brackets:
-@end ignore
-
-Parallel pieces of music can be combined into a single
-@code{Voice} context, thus forming chords if they have the same
-rhythm.  To achieve this, enclose them in a simultaneous music
-construction:
-
-@lilypond[quote,relative=2,verbatim]
-\new Voice <<
-  { e4 f8 d e16 f g8 d4 }
-  { c4 d8 b c16 d e8 b4 }
->>
-@end lilypond
-
-@seealso
-
-Learning Manual:
-@rlearning{Voices contain music}.
-
-Snippets:
-@rlsr{Simultaneous notes}.
-
-@knownissues
-
-This method leads to strange beamings and warnings if the pieces of
-music do not have the same rhythm.
-
 @node Clusters
 @unnumberedsubsubsec Clusters
 
@@ -158,12 +123,141 @@ This section discusses simultaneous notes in multiple voices or
 multiple staves.
 
 @menu
-* Collision resolution::
-* Voice styles::
-* Automatic part combining::
-* Writing music in parallel::
+* Single-staff polyphony::      
+* Voice styles::                
+* Collision resolution::        
+* Automatic part combining::    
+* Writing music in parallel::   
 @end menu
 
+@node Single-staff polyphony
+@unnumberedsubsubsec Single-staff polyphony
+
+To typeset parallel pieces of music that have the same rhythm, they
+can be combined into a single @code{Voice} context, thus forming
+chords.  To achieve this, enclose them in a simultaneous music
+construction:
+
+@lilypond[quote,relative=2,verbatim]
+\new Voice <<
+  { e4 f8 d e16 f g8 d4 }
+  { c4 d8 b c16 d e8 b4 }
+>>
+@end lilypond
+
+This method leads to strange beamings and warnings if the pieces of
+music do not have the same rhythm.  To typeset multiple, truly
+independent voices in a single staff, the @code{<<@{...@} \\
+@{...@}>>} construction is used, where the two (or more) voices are
+separated by double backslashes.
+
+@lilypond[quote,relative=3,verbatim]
+<<
+  { r8 r16 g e8. f16 g8[ c,] f e16 d }
+  \\
+  { d16 c d8~ d16 b c8~ c16 b c8~ c16 b8. }
+>>
+@end lilypond
+
+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.  
+
+@lilypond[quote,relative=3,verbatim]
+<<
+  { r8 g g  g g f16 es f8 d }
+  \\  
+  { es,8 r es r d r d r }
+  \\
+  { d'8 s c s bes s a s }
+>>
+@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.
+
+@predefined
+
+@funindex \voiceOne
+@code{\voiceOne},
+@funindex \voiceTwo
+@code{\voiceTwo},
+@funindex \voiceThree
+@code{\voiceThree},
+@funindex \voiceFour
+@code{\voiceFour}.
+
+
+@seealso
+
+Learning Manual:
+@rlearning{Voices contain music}.
+
+Snippets:
+@rlsr{Simultaneous notes}.
+
+
+@node Voice styles
+@unnumberedsubsubsec Voice styles
+
+@cindex voice styles
+@cindex styles, voice
+@cindex coloring voices
+
+Voices may be given distinct colors and shapes, allowing them to be
+easily identified:
+
+@lilypond[quote,relative=2,verbatim]
+<<
+  { \voiceOneStyle d4 c2 b4 }
+  \\
+  { \voiceTwoStyle e,2 e }
+  \\
+  { \voiceThreeStyle b2. c4 }
+  \\
+  { \voiceFourStyle g'2 g }
+>>
+@end lilypond
+
+To revert the standard presentation, the @code{\voiceNeutralstyle}
+command is used.
+
+These styles are arbitrarily defined but can be changed. For example,
+the initial definition for @code{\voiceOneStyle} is as follows:
+
+@example
+voiceOneStyle = @{
+  \override NoteHead #'style = #'diamond
+  \override NoteHead #'color = #red
+  \override Stem #'color = #red
+  \override Beam #'color = #red
+@}
+@end example
+
+
+@predefined
+
+@funindex \voiceOneStyle
+@code{\voiceOneStyle},
+@funindex \voiceTwoStyle
+@code{\voiceTwoStyle},
+@funindex \voiceThreeStyle
+@code{\voiceThreeStyle},
+@funindex \voiceFourStyle
+@code{\voiceFourStyle},
+@funindex \voiceNeutralStyle
+@code{\voiceNeutralStyle}.
+
+@seealso
+
+Learning Manual:
+@rlearning{I'm hearing Voices},
+@rlearning{Other sources of information}.
+
+Snippets:
+@rlsr{Simultaneous notes}.
+
 @node Collision resolution
 @unnumberedsubsubsec Collision resolution
 
@@ -294,15 +388,7 @@ Notes are only merged if they have opposing stem directions (i.e., in
 @code{\mergeDifferentlyHeadedOff}.
 
 @funindex \oneVoice
-@code{\oneVoice},
-@funindex \voiceOne
-@code{\voiceOne},
-@funindex \voiceTwo
-@code{\voiceTwo},
-@funindex \voiceThree
-@code{\voiceThree},
-@funindex \voiceFour
-@code{\voiceFour}.
+@code{\oneVoice}.
 
 
 @funindex \shiftOn
@@ -357,54 +443,6 @@ different accidentals in the same chord.  In this case, it is
 recommended to use enharmonic transcription, or to use special
 cluster notation (see @ref{Clusters}).
 
-@node Voice styles
-@unnumberedsubsubsec Voice styles
-
-@cindex voice styles
-@cindex styles, voice
-@cindex coloring voices
-
-Voices may be given distinct colors and shapes, allowing them to be
-easily identified:
-
-@lilypond[quote,relative=2,verbatim]
-<<
-  {
-    a1
-    \voiceOneStyle
-    f2 g
-    \voiceNeutralStyle
-    a1
-  } \\ {
-    f1
-    \voiceTwoStyle
-    f4 f2 e4
-    \voiceNeutralStyle
-    f1
-  }
->>
-@end lilypond
-
-@predefined
-
-@funindex \voiceOneStyle
-@code{\voiceOneStyle},
-@funindex \voiceTwoStyle
-@code{\voiceTwoStyle},
-@funindex \voiceThreeStyle
-@code{\voiceThreeStyle},
-@funindex \voiceFourStyle
-@code{\voiceFourStyle},
-@funindex \voiceNeutralStyle
-@code{\voiceNeutralStyle}.
-
-@seealso
-
-Lerning Manual:
-@rlearning{I'm hearing Voices}.
-
-Snippets:
-@rlsr{Simultaneous notes}.
 
 @node Automatic part combining
 @unnumberedsubsubsec Automatic part combining
@@ -562,18 +600,19 @@ print the music.
 be of the same length.}
 
 @lilypond[quote,verbatim]
-\parallelMusic #'(voiceA voiceB) {
+\parallelMusic #'(voiceA voiceB  voiceC) {
   % Bar 1
   r8 g'16[ c''] e''[ g' c'' e''] r8 g'16[ c''] e''[ g' c'' e''] |
   c'2                               c'2                         |
-
+  r16 e'8.~     e'4                 r16 e'8.~  e'4              |
   % Bar 2
   r8 a'16[ d''] f''[ a' d'' f''] r8 a'16[ d''] f''[ a' d'' f''] |
   c'2                               c'2                         |
+  r16 d'8.~     d'4                 r16 d'8.~  d'4              |
 }
 \new StaffGroup <<
-  \new Staff  \voiceA
-  \new Staff  \voiceB
+  \new Staff << \voiceA \\ \voiceC >>
+  \new Staff { \clef bass \voiceB }
 >>
 @end lilypond
 
@@ -584,18 +623,20 @@ note in the input -- in other words, relative notes for
 @code{voiceA} ignore the notes in @code{voiceB}.
 
 @lilypond[quote,verbatim]
-\parallelMusic #'(voiceA voiceB) {
+\parallelMusic #'(voiceA voiceB voiceC) {
   % Bar 1
   r8 g16 c e g, c e r8 g,16 c e g, c e  |
   c2                c                   |
+  r16 e8.~ e4       r16 e8.~  e4        |
 
   % Bar 2
   r8 a,16 d f a, d f r8 a,16 d f a, d f |
   c2                 c                  |
+  r16 d8.~  d4       r16 d8.~  d4       |
  }
 \new StaffGroup <<
-  \new Staff \relative c'' \voiceA
-  \new Staff \relative c'  \voiceB
+  \new Staff << \relative c'' \voiceA \\ \relative c' \voiceC >>
+  \new Staff \relative c' { \clef bass \voiceB }
 >>
 @end lilypond