X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fsimultaneous.itely;h=71b3a166ea86a5cd2a1ddbdbd679960078bc3828;hb=f38331f2a44d40bb22b1b0a321463d0eae05e1bf;hp=b552bcb712105995c22689959796973eb86205cf;hpb=37962fadaca368e05afca5c88367c8671616cb9d;p=lilypond.git

diff --git a/Documentation/user/simultaneous.itely b/Documentation/user/simultaneous.itely
index b552bcb712..71b3a166ea 100644
--- a/Documentation/user/simultaneous.itely
+++ b/Documentation/user/simultaneous.itely
@@ -9,6 +9,8 @@
 @node Simultaneous notes
 @section Simultaneous notes
 
+@lilypondfile[quote]{simultaneous-headword.ly}
+
 Polyphony in music refers to having more than one voice occurring
 in a piece of music.  Polyphony in LilyPond refers to having more
 than one voice on the same staff.
@@ -23,18 +25,18 @@ than one voice on the same staff.
 @subsection Single voice
 
 @menu
-* Chords::                      
+* Chorded notes::                      
 * Clusters::                    
 @end menu
 
-@node Chords
-@unnumberedsubsubsec Chords
+@node Chorded notes
+@subsubsection Chorded notes
 
 @cindex Chords
 
 A chord is formed by a enclosing a set of pitches between @code{<}
 and @code{>}.  A chord may be followed by a duration, and a set of
-articulations, just like simple notes
+articulations, just like simple notes:
 
 @lilypond[verbatim,ragged-right,fragment,quote,relative=1]
 <c e g>4 <c>8
@@ -43,9 +45,23 @@ articulations, just like simple notes
 For more information about chords, see @ref{Introducing chord
 names}.
 
+@seealso
+
+Music Glossary: @rglos{chord}.
+
+Notation Reference: @ref{Introducing chord names}.
+
+Snippets: @lsrdir{Simultaneous,Simultaneous-notes}.
+
+@knownissues
+
+Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
+accurately.  Use @code{<g a>8 <e a>8} instead.
+
+
 
 @node Clusters
-@unnumberedsubsubsec Clusters
+@subsubsection Clusters
 
 @cindex cluster
 
@@ -65,16 +81,13 @@ clusters.
 
 @seealso
 
-Program reference: @internalsref{ClusterSpanner},
+Snippets: @lsrdir{Simultaneous,Simultaneous-notes}.
+
+Internals Reference: @internalsref{ClusterSpanner},
 @internalsref{ClusterSpannerBeacon},
 @internalsref{Cluster_spanner_engraver}.
 
-Examples: @lsr{contemporary,cluster@/.ly}.
-
-@refbugs
-
-Music expressions like @code{<< @{ g8 e8 @} a4 >>} are not printed
-accurately.  Use @code{<g a>8 <e a>8} instead.
+Examples: @c @lsr{contemporary,cluster@/.ly}.
 
 
 
@@ -82,136 +95,16 @@ accurately.  Use @code{<g a>8 <e a>8} instead.
 @subsection Multiple voices
 
 @menu
-* Explicitly instantiating voices::  
-* Collision Resolution::        
+* Collision resolution::        
 * Automatic part combining::    
 * Writing music in parallel::   
 @end menu
 
-@node Explicitly instantiating voices
-@unnumberedsubsubsec Explicitly instantiating voices
+@node Collision resolution
+@subsubsection Collision resolution
 
-@internalsref{Voice} contexts can also be instantiated manually
-inside a @code{<< >>} block to create polyphonic music, using
-@code{\voiceOne}, up to @code{\voiceFour} to assign stem
-directions and a horizontal shift for each part.
-
-Specifically,
-@example
-<< \upper \\ \lower >>
-@end example
-
-@noindent
-is equivalent to
-
-@example
-<<
-  \new Voice = "1" @{ \voiceOne \upper @}
-  \new Voice = "2" @{ \voiceTwo \lower @}
->>
-@end example
-
-The @code{\voiceXXX} commands set the direction of stems, slurs,
-ties, articulations, text annotations, augmentation dots of dotted
-notes, and fingerings.  @code{\voiceOne} and @code{\voiceThree}
-make these objects point upwards, while @code{\voiceTwo} and
-@code{\voiceFour} make them point downwards.  The command
-@code{\oneVoice} will revert back to the normal setting.
-
-An expression that appears directly inside a @code{<< >>} belongs
-to the main voice.  This is useful when extra voices appear while
-the main voice is playing.  Here is a more correct rendition of
-the example from the previous section.  The crossed colored
-noteheads demonstrate that the main melody is now in a single
-voice context.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Staff \relative c' {
-  \override NoteHead #'style = #'cross
-  \override NoteHead #'color = #red
-  c16 d e f
-  \voiceOne
-  <<
-    { g4 f e | d2 e2 }
-    \new Voice="1" { \voiceTwo
-      r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
-      \oneVoice
-    }
-    \new Voice { \voiceThree
-      s2. | s4 b4 c2
-      \oneVoice
-    }
-  >>
-  \oneVoice
-}
-@end lilypond
-
-The correct definition of the voices allows the melody to be
-slurred.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Staff \relative c' {
-  c16^( d e f
-  \voiceOne
-  <<
-    { g4 f e | d2 e2) }
-    \context Voice="1" { \voiceTwo
-      r8 e4 d c8 ~ | c8 b16 a b8 g ~ g2
-      \oneVoice
-    }
-    \new Voice { \voiceThree
-      s2. s4 b4 c2
-      \oneVoice
-    }
-  >>
-  \oneVoice
-}
-@end lilypond
-
-Avoiding the @code{\\} separator also allows nesting polyphony
-constructs, which in some case might be a more natural way to
-typeset the music.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Staff \relative c' {
-  c16^( d e f
-  \voiceOne
-  <<
-    { g4 f e | d2 e2) }
-    \context Voice="1" { \voiceTwo
-      r8 e4 d c8 ~ |
-      <<
-        {c8 b16 a b8 g ~ g2}
-        \new Voice { \voiceThree
-          s4 b4 c2
-          \oneVoice
-        }
-      >>
-    \oneVoice
-    }
-  >>
-  \oneVoice
-}
-@end lilypond
-
-In some instances of complex polyphonic music, you may need
-additional voices to avoid collisions between notes.  Additional
-voices are added by defining an identifier, as shown below:
-
-@lilypond[quote,verbatim,ragged-right,relative=2]
-voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
-
-\relative c''' <<
-  { \voiceOne g4 ~  \stemDown g32[ f( es d c b a b64 )g] } \\
-  { \voiceThree  b4} \\
-  { \voiceFive d,} \\
-  { \voiceTwo g,}
->>
-@end lilypond
-
-
-@node Collision Resolution
-@unnumberedsubsubsec Collision Resolution
+@cindex merging notes
+@cindex note collisions
 
 Normally, note heads with a different number of dots are not
 merged, but when the object property
@@ -241,7 +134,7 @@ c8 c4. } \\ { c2 c2 } >>
 @noindent
 @code{merge-differently-headed} and
 @code{merge-differently-dotted} only apply to opposing stem
-directions (ie. Voice 1 & 2).
+directions (i.e. Voice 1 & 2).
 
 LilyPond also vertically shifts rests that are opposite of a stem,
 for example
@@ -250,6 +143,8 @@ for example
 \new Voice << c''4 \\ r4 >>
 @end lilypond
 
+@cindex shift note
+
 If three or more notes line up in the same column,
 @code{merge-differently-headed} cannot successfully complete the
 merge of the two notes that should be merged.  To allow the merge
@@ -274,8 +169,28 @@ move the top @code{g} out of the column, and
 >>
 @end lilypond
 
+@cindex multiple voices
+@cindex polyphonic music
+@cindex shifting voices
+
+In some instances of complex polyphonic music, you may need
+additional voices to avoid collisions between notes.  Additional
+voices are added by defining an variable, as shown below:
+
+@lilypond[quote,verbatim,ragged-right,relative=2]
+voiceFive = #(context-spec-music (make-voice-props-set 4) 'Voice)
+
+\relative c''' <<
+  { \voiceOne g4 ~  \stemDown g32[ f( es d c b a b64 )g] } \\
+  { \voiceThree  b4} \\
+  { \voiceFive d,} \\
+  { \voiceTwo g,}
+>>
+@end lilypond
+
+
 
-@refcommands
+@predefined
 
 @funindex \oneVoice
 @code{\oneVoice},
@@ -288,6 +203,19 @@ move the top @code{g} out of the column, and
 @funindex \voiceFour
 @code{\voiceFour}.
 
+@funindex \voiceNeutralStyle
+@funindex \voiceOneStyle
+@funindex \voiceTwoStyle
+@funindex \voiceThreeStyle
+@funindex \voiceFourStyle
+@example
+\voiceNeutralStyle
+\voiceOneStyle
+\voiceTwoStyle
+\voiceThreeStyle
+\voiceFourStyle
+@end example
+
 @funindex \shiftOn
 @code{\shiftOn},
 @funindex \shiftOnn
@@ -321,12 +249,14 @@ override typesetting decisions.
 
 @seealso
 
-Program reference: the objects responsible for resolving
+Snippets: @lsrdir{Simultaneous,Simultaneous-notes}.
+
+Internals Reference: the objects responsible for resolving
 collisions are @internalsref{NoteCollision} and
 @internalsref{RestCollision}.
 
 
-@refbugs
+@knownissues
 
 When using @code{merge-differently-headed} with an upstem eighth
 or a shorter note, and a downstem half note, the eighth note gets
@@ -339,9 +269,10 @@ cluster notation (see @ref{Clusters}).
 
 
 @node Automatic part combining
-@unnumberedsubsubsec Automatic part combining
+@subsubsection Automatic part combining
 @cindex automatic part combining
 @cindex part combiner
+@cindex combining parts
 
 Automatic part combining is used to merge two parts of music onto
 a staff.  It is aimed at typesetting orchestral scores.  When the
@@ -359,7 +290,7 @@ The syntax for part combining is
 
 The following example demonstrates the basic functionality of the
 part combiner: putting parts on one staff, and setting stem
-directions and polyphony
+directions and polyphony.
 
 @lilypond[quote,verbatim,ragged-right,fragment]
 \new Staff \partcombine
@@ -375,7 +306,7 @@ and @q{Solo}, while the second (called @code{two}) always gets
 down stems and @q{Solo II}.
 
 If you just want the merging parts, and not the textual markings,
-you may set the property @code{printPartCombineTexts} to false
+you may set the property @code{printPartCombineTexts} to false.
 
 @lilypond[quote,verbatim,ragged-right,fragment,relative=2]
 \new Staff <<
@@ -419,11 +350,15 @@ has no effect on the pitches of @var{musicexpr1} and
 
 @seealso
 
-Program reference: @internalsref{PartCombineMusic}.
+Music Glossary: @rglos{a due}.
+
+Snippets: @lsrdir{Simultaneous,Simultaneous-notes}.
 
-@refbugs
+Internals Reference: @internalsref{PartCombineMusic}, @internalsref{Voice}.
 
-When @code{printPartCombineTexts} is set, when the two voices play
+@knownissues
+
+When @code{printPartCombineTexts} is set, if the two voices play
 the same notes on and off, the part combiner may typeset @code{a2}
 more than once in a measure.
 
@@ -439,12 +374,12 @@ events in those will be ignored.
 
 
 @node Writing music in parallel
-@unnumberedsubsubsec Writing music in parallel
+@subsubsection Writing music in parallel
 
 @cindex Writing music in parallel
 @cindex Interleaved music
 
-Music for multiple parts can be interleaved
+Music for multiple parts can be interleaved:
 
 @lilypond[quote,fragment,verbatim]
 \parallelMusic #'(voiceA voiceB) {
@@ -459,7 +394,7 @@ Music for multiple parts can be interleaved
 >>
 @end lilypond
 
-This works quite well for piano music
+This works quite well for piano music.
 
 @c  It would be nice if the first bar fit onto one 66-char line.
 @c  Maybe simplify the example?  -gp
@@ -506,5 +441,7 @@ music = {
 }
 @end lilypond
 
+@seealso
 
+Snippets: @lsrdir{Simultaneous,Simultaneous-notes}