<c e g>2 <c f a>4-> <e g c>-.
@end lilypond
+Relative mode can be used for pitches in chords; the preceding pitch
+into the same chord is still used as a reference for relative pitches,
+but when a chord is completed, the reference pitch for relative mode
+is the first note of this chord --not the last note of the chord.
+
For more information about chords, see @ref{Chord notation}.
@seealso
* Writing music in parallel::
@end menu
-@ignore FUTURE PLANS. Carl suggested:
-Perhaps it would be clearer if we started with single-staff polyphony
-with named and explicitly created voices, along with the \voiceOne
-through \voiceFour properties.
+@node Single-staff polyphony
+@unnumberedsubsubsec Single-staff polyphony
-We could then introduce the << \\ >> syntax as a simple way to handle
-music where we don't care that temporary voices are created and then
-discarded.
+@c Already reordered as Carl suggested --FV
+The basic structure of code needed to achieve multiple, independent
+voices in a single staff is illustrated in the following example:
-It seems to me to be much easier to go from the full understanding to
-the shortcut than the other way around.
-@end ignore
+@lilypond[quote,relative=3,verbatim]
+\new Staff <<
+ \new Voice = "first"
+ { \voiceOne r8 r16 g e8. f16 g8[ c,] f e16 d }
+ \new Voice= "second"
+ { \voiceTwo d16 c d8~ d16 b c8~ c16 b c8~ c16 b8. }
+>>
+@end lilypond
+Here, voices are instantiated explicitly and are given a name. The
+@code{\voiceOne} ... @code{\voiceFour} commands set up the voices so
+that first and third voices get stems up, second and fourth voices get
+stems down, third and fourth voice note heads are horizontally
+shifted, and rests in the respective voices move to avoid collisions.
-@node Single-staff polyphony
-@unnumberedsubsubsec Single-staff polyphony
+Using the @code{\oneVoice} command, we can make a voice to be into the
+same @code{Voice} context before and after a temporary polyphonic
+passage. For example:
-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:
+@example
+<< @{ \voiceOne ... @} \new Voice @{ \voiceTwo ... @} >> \oneVoice
+@end example
-@lilypond[quote,relative=2,verbatim]
-\new Voice <<
- { e4 f8 d e16 f g8 d4 }
- { c4 d8 b c16 d e8 b4 }
+This construct keeps a voice alive throughout the polyphonic section.
+Using the name given when created, this allows lyrics to be assigned
+to one consistent voice.
+
+@lilypond[quote, verbatim, relative=2]
+<<
+ \new Voice = "melody" {
+ a4
+ <<
+ {
+ \voiceOne
+ g f
+ }
+ \new Voice {
+ \voiceTwo
+ e d
+ }
+ >>
+ \oneVoice
+ e
+ }
+ \new Lyrics \lyricsto "melody" {
+ This is my song.
+ }
>>
@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 can be used as a simplified method, where the
-two (or more) voices are separated by double backslashes.
+The @code{<<@{...@} \\ @{...@}>>} construction can be used as a
+simplified method, where the two (or more) voices are separated by
+double backslashes. Our first example could be typeset as follows:
@lilypond[quote,relative=3,verbatim]
<<
>>
@end lilypond
-First and third voices get stems up, second and fourth voices get
-stems down, third and fourth voice note heads are horizontally shifted,
-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.
+This syntax is simpler and can be used where it does not care that
+temporary voices are created and then discarded. These implicitly
+created voices are given the settings equivalent to the effect of the
+@code{\voiceOne} ... @code{\voiceFour} commands, in the order in which
+they appear in the code. 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]
<<
Spacing rests are often used to avoid too many rests, as seen in the
example above.
-Voices created by this simplified method are implicit @code{Voice}
-contexts; in all but simplest works it is advised to create explicit
+In all but simplest works it is advised to create explicit
@code{Voice} contexts using the @code{\new} and @code{\context}
commands as it is explained in @rlearning{Contexts and engravers} and
@rlearning{Explicitly instantiating voices}.
-This applies to a common case: each music expression in the
-@code{<<@{...@} \\ @{...@}>>} construct is placed in a new voice,
-distinct from the voice for single-voice music; to temporarily add
-only one additional voice to an existing one, it is necessary to
-instantiate that voice explicitly. When doing this, to force the
-settings that would be implicitly made by the simplified method, the
-@code{\voiceOne} ... @code{\voiceFour}, and @code{\oneVoice} commands
-can be used:
-
-@example
-<< @{ \voiceOne ... @} \new Voice @{ \voiceTwo ... @} >> \oneVoice
-@end example
-
-This construct keeps a voice alive throughout the polyphonic section.
-For example, this allows lyrics to be assigned to one consistent voice.
+In the special case that we want to typeset parallel pieces of music
+that have the same rhythm, we can combine them into a single
+@code{Voice} context, thus forming chords. To achieve this, enclose
+them in a simple simultaneous music construction and make it to be an
+explicit voice:
-@lilypond[quote, verbatim, relative=2]
-<<
- \new Voice = "melody" {
- a4
- <<
- {
- \voiceOne
- g f
- }
- \new Voice {
- \voiceTwo
- e d
- }
- >>
- \oneVoice
- e
- }
- \new Lyrics \lyricsto "melody" {
- This is my song.
- }
+@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.
+
@predefined
@funindex \voiceOne