X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=b06de6f40b42b17d60b67326229f5e8f093a101d;hb=28add695953862ef4a87f9fbeadd1d02dc299244;hp=f1317f169a45b6401abe674664ff7973b4e0b847;hpb=f739a44f91a0b7ef5f634b6c4ca5b45c988798c1;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index f1317f169a..b06de6f40b 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.19"
+@c \version "2.19.21"
 
 @node Vocal music
 @section Vocal music
@@ -156,7 +156,7 @@ into the input file, providing it is saved with UTF-8 encoding.
 For more information, see @ref{Special characters}.
 
 @lilypond[quote,verbatim]
-\relative c'' { d8 c16 a bes8 f e' d c4 }
+\relative { d''8 c16 a bes8 f ees' d c4 }
 \addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
 @end lilypond
 
@@ -165,7 +165,7 @@ with a backslash character and the whole syllable has to be
 enclosed between additional quotes.  For example,
 
 @lilypond[quote,verbatim]
-\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
+\relative { \time 3/4 e'4 e4. e8 d4 e d c2. }
 \addlyrics { "\"I" am so lone -- "ly,\"" said she }
 @end lilypond
 
@@ -218,13 +218,22 @@ Snippets:
 @funindex \addlyrics
 @funindex \lyricsto
 
-Lyrics are printed by interpreting them in the context called
-@code{Lyrics}, see @ref{Contexts explained}.
+Lyrics are interpreted in @code{\lyricmode} and printed in a
+@code{Lyrics} context, see @ref{Contexts explained}.
 
 @example
 \new Lyrics \lyricmode @{ @dots{} @}
 @end example
 
+Two variants of @code{\lyricmode} additionally set an associated
+context used to synchronise the lyric syllables to music.  The more
+convenient @code{\addlyrics} immediately follows the musical content
+of the Voice context with which it should be synchronised, implicitly
+creating a Lyrics context of its own.  The more versatile
+@code{\lyricsto} requires both specifying the associated Voice context
+by name and explicitly creating a containing Lyrics context.  For
+details see @ref{Automatic syllable durations}.
+
 Lyrics can be aligned with melodies in two main ways:
 
 @itemize
@@ -240,13 +249,13 @@ For more details, see @ref{Automatic syllable durations}.
 <<
   \new Staff <<
     \time 2/4
-    \new Voice = "one" \relative c'' {
+    \new Voice = "one" \relative {
       \voiceOne
-      c4 b8. a16 g4. r8 a4 ( b ) c2
+      c''4 b8. a16 g4. r8 a4 ( b ) c2
     }
-    \new Voice = "two" \relative c' {
+    \new Voice = "two" \relative {
       \voiceTwo
-       s2 s4. f8 e4 d c2
+       s2 s4. f'8 e4 d c2
     }
   >>
 
@@ -280,9 +289,9 @@ and entered with @code{\lyricmode}.
 
 @lilypond[quote,ragged-right,verbatim]
 <<
-  \new Voice = "one" \relative c'' {
+  \new Voice = "one" \relative {
     \time 2/4
-    c4 b8. a16 g4. f8 e4 d c2
+    c''4 b8. a16 g4. f8 e4 d c2
   }
 
 % uses previous explicit duration of 2;
@@ -309,11 +318,6 @@ see @ref{Manual syllable durations}.  This technique is also useful
 when setting dialogue over music; for examples showing this, see
 @ref{Dialogue over music}.
 
-When entered in this way the words are left-aligned to the notes
-by default, but may be center-aligned to the notes of a melody by
-specifying an associated voice, if one exists.  For details, see
-@ref{Manual syllable durations}.
-
 @end itemize
 
 @seealso
@@ -380,10 +384,10 @@ Lyrics can be aligned under a melody automatically by specifying
 the named Voice context containing the melody with
 @code{\lyricsto}:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 <<
-  \new Voice = "melody" {
-    a1 a4. a8 a2
+  \new Voice = "melody" \relative {
+    a'1 a4. a8 a2
   }
   \new Lyrics \lyricsto "melody" {
     These are the words
@@ -397,9 +401,9 @@ context, which must already exist.  Therefore normally the
 @code{Voice} context is specified first, followed by the
 @code{Lyrics} context.  The lyrics themselves follow the
 @code{\lyricsto} command.  The @code{\lyricsto} command
-invokes lyric mode automatically, so the @code{\lyricmode} keyword
-may be omitted.  By default, the lyrics are placed underneath the
-notes.  For other placements, see @ref{Placing lyrics vertically}.
+invokes lyric mode automatically.  By default, the lyrics are placed
+underneath the notes.  For other placements, see
+@ref{Placing lyrics vertically}.
 
 @subheading Using @code{\addlyrics}
 
@@ -428,7 +432,7 @@ Here is an example,
 @lilypond[verbatim,quote]
 {
   \time 3/4
-  \relative c' { c2 e4 g2. }
+  \relative { c'2 e4 g2. }
   \addlyrics { play the game }
 }
 @end lilypond
@@ -440,7 +444,7 @@ More stanzas can be added by adding more
 @lilypond[ragged-right,verbatim,quote]
 {
   \time 3/4
-  \relative c' { c2 e4 g2. }
+  \relative { c'2 e4 g2. }
   \addlyrics { play the game }
   \addlyrics { speel het spel }
   \addlyrics { joue le jeu }
@@ -448,6 +452,7 @@ More stanzas can be added by adding more
 @end lilypond
 
 The command @code{\addlyrics} cannot handle polyphonic settings.
+Also, it cannot be used to associate lyrics to a @code{TabVoice}.
 For these cases one should use @code{\lyricsto}.
 
 @subheading Using associatedVoice
@@ -472,13 +477,13 @@ Here is an example demonstrating its use:
 <<
   \new Staff <<
     \time 2/4
-    \new Voice = "one" \relative c'' {
+    \new Voice = "one" \relative {
       \voiceOne
-      c4 b8. a16 g4. r8 a4 ( b ) c2
+      c''4 b8. a16 g4. r8 a4 ( b ) c2
     }
-    \new Voice = "two" \relative c' {
+    \new Voice = "two" \relative {
       \voiceTwo
-       s2 s4. f8 e8 d4. c2
+       s2 s4. f'8 e8 d4. c2
     }
   >>
 % takes durations and alignment from notes in "one" initially
@@ -508,21 +513,19 @@ completely independently of notes.  In this case do not use
 but with pitches replaced by text -- and the duration of each
 syllable is entered explicitly after the syllable.
 
-By default, syllables will be left-aligned to the corresponding
-musical moment.  Hyphenated lines may be drawn between syllables
+Hyphenated lines may be drawn between syllables
 as usual, but extender lines cannot be drawn when there is no
 associated voice.
 
 Here are two examples:
 
-@lilypond[relative=1,verbatim,quote]
+@lilypond[verbatim,quote]
 <<
-  \new Voice = "melody" {
-    \time 3/4
-    c2 e4 g2 f
+  \new Voice = "melody" \relative {
+    c''2 a f f e e
   }
   \new Lyrics \lyricmode {
-    play1 the4 game4
+    c4. -- a -- f -- f -- e2. -- e
   }
 >>
 @end lilypond
@@ -531,8 +534,8 @@ Here are two examples:
 @lilypond[quote,verbatim,ragged-right]
 <<
   \new Staff {
-    \relative c'' {
-      c2 c2
+    \relative {
+      c''2 c2
       d1
     }
   }
@@ -542,8 +545,8 @@ Here are two examples:
     }
   }
   \new Staff {
-    \relative c' {
-      c8 c c c c c c c
+    \relative {
+      c'8 c c c c c c c
       c8 c c c c c c c
     }
   }
@@ -553,27 +556,22 @@ Here are two examples:
 This technique is useful when writing dialogue over music, see
 @ref{Dialogue over music}.
 
-To center-align syllables on the notes at the corresponding musical
-moments, set @code{associatedVoice} to the name of the Voice context
-containing those notes.  When @code{associatedVoice} is set, both
-double hyphens and double underscores can be used to draw
-hyphenated lines and extenders under melismata correctly.
+To change syllable alignment, simply override the @code{self-alignment-X}
+property:
 
-@lilypond[relative=1,verbatim,quote]
+@lilypond[verbatim,quote]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
-    c2 e4 g f g
+    c'2 e4 g2 f
   }
   \new Lyrics \lyricmode {
-    \set associatedVoice = #"melody"
-    play2 the4 game2. __
+    \override LyricText.self-alignment-X = #LEFT
+    play1 a4 game4
   }
 >>
 @end lilypond
 
-@c TODO see also feature request 707 - show how to do this with manual durations
-
 @seealso
 Notation Reference:
 @ref{Dialogue over music}.
@@ -596,10 +594,11 @@ spaces between the syllables, you can surround the phrase with
 quotes or use a @code{_} character.  Alternatively, you can use
 the tilde symbol (@code{~}) to get a lyric tie.
 
-@lilypond[quote,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 {
-  { \autoBeamOff
-    r8 b c fis, fis c' b e,
+  \relative {
+    \autoBeamOff
+    r8 b' c fis, fis c' b e,
   }
   \addlyrics
   {
@@ -630,7 +629,7 @@ sung on one syllable; this is called melisma, see
 @rglos{melisma}.  The syllable to a melisma is usually
 left-aligned with the first note of the melisma.
 
-When a melisma occurs on a syllable other that the last one in a
+When a melisma occurs on a syllable other than the last one in a
 word, that syllable is usually joined to the following one with a
 hyphenated line.  This is indicated by placing a double hyphen,
 @w{@code{--}}, immediately after the syllable.
@@ -648,13 +647,13 @@ There are five ways in which melismata can be indicated:
 Melismata are created automatically over notes which are tied
 together:
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
-    f4 g2 ~ |
-    g4 e2 ~ |
-    e8
+    f''4 g2 ~ |
+    4 e2 ~ |
+    8
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e __
@@ -667,11 +666,11 @@ Melismata can be created automatically from the music by placing
 slurs over the notes of each melisma.  This is the usual way of
 entering lyrics:
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
-    f4 g8 ( f e f )
+    f''4 g8 ( f e f )
     e8 ( d e2 )
   }
   \new Lyrics \lyricsto "melody" {
@@ -687,12 +686,12 @@ Notes are considered a melisma if they are manually beamed,
 providing automatic beaming is switched off.  See
 @ref{Setting automatic beam behavior}.
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
     \autoBeamOff
-    f4 g8[ f e f]
+    f''4 g8[ f e f]
     e2.
   }
   \new Lyrics \lyricsto "melody" {
@@ -708,11 +707,11 @@ than eighth notes.
 An unslurred group of notes will be treated as a melisma if they
 are bracketed between @code{\melisma} and @code{\melismaEnd}.
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
-    f4 g8
+    f''4 g8
     \melisma
     f e f
     \melismaEnd
@@ -729,11 +728,11 @@ A melisma can be defined entirely in the lyrics by entering a
 single underscore character, @code{_}, for every extra note that has
 to be added to the melisma.
 
-@lilypond[verbatim, quote, relative=2]
+@lilypond[verbatim, quote]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
-    f4 g8 f e f
+    f''4 g8 f e f
     e8 d e2
   }
   \new Lyrics \lyricsto "melody" {
@@ -748,13 +747,13 @@ It is possible to have ties, slurs and manual beams in the melody
 without their indicating melismata.  To do this, set
 @code{melismaBusyProperties}:
 
-@lilypond[relative=1,verbatim,quote]
+@lilypond[verbatim,quote]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
     \set melismaBusyProperties = #'()
-    c4 d ( e )
-    g8 [ f ] f4 ~ f
+    c'4 d ( e )
+    g8 [ f ] f4 ~ 4
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e e -- le -- i -- son
@@ -776,13 +775,13 @@ If a melisma is required during a passage in which
 placing a single underscore in the lyrics for each note which
 should be included in the melisma:
 
-@lilypond[relative=1,verbatim,quote]
+@lilypond[verbatim,quote]
 <<
-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {
     \time 3/4
     \set melismaBusyProperties = #'()
-    c4 d ( e )
-    g8 [ f ] ~ f4 ~ f
+    c'4 d ( e )
+    g8 [ f ] ~ 4 ~ f
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- _ e __ _ _ _
@@ -872,6 +871,7 @@ Internals Reference:
 * Placing syllables horizontally::
 * Lyrics and repeats::
 * Divisi lyrics::
+* Polyphony with shared lyrics::
 @end menu
 
 
@@ -885,8 +885,8 @@ Variables containing lyrics can be created, but the lyrics must be
 entered in lyric mode:
 
 @lilypond[quote,verbatim]
-musicOne = \relative c'' {
-  c4 b8. a16 g4. f8 e4 d c2
+musicOne = \relative {
+  c''4 b8. a16 g4. f8 e4 d c2
 }
 verseOne = \lyricmode {
   Joy to the world, the Lord is come.
@@ -915,8 +915,8 @@ voices referenced by @code{\lyricsto} have always been defined
 earlier.  For example:
 
 @lilypond[quote,verbatim]
-sopranoMusic = \relative c'' { c4 c c c }
-contraltoMusic = \relative c'' { a4 a a a }
+sopranoMusic = \relative { c''4 c c c }
+contraltoMusic = \relative { a'4 a a a }
 sopranoWords = \lyricmode { Sop -- ra -- no words }
 contraltoWords = \lyricmode { Con -- tral -- to words }
 
@@ -974,7 +974,7 @@ context:
   <<
     \new Staff {
       \new Voice = "melody" {
-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }
       }
     }
     \new Lyrics {
@@ -996,7 +996,7 @@ specify the position of the lyrics:
   <<
     \new Staff = "staff" {
       \new Voice = "melody" {
-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }
       }
     }
     \new Lyrics \with { alignAboveContext = "staff" } {
@@ -1023,7 +1023,7 @@ follows:
     }
     \new Staff {
       \new Voice = "melody" {
-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }
       }
     }
     \context Lyrics = "lyrics" {
@@ -1044,7 +1044,7 @@ is an example of the second method:
   \new ChoirStaff <<
     \new Staff {
       \new Voice = "sopranos" {
-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }
       }
     }
     \new Lyrics = "sopranos"
@@ -1054,7 +1054,7 @@ is an example of the second method:
     }
     \new Staff {
       \new Voice = "contraltos" {
-        \relative c'' { a4 a a a }
+        \relative { a'4 a a a }
       }
     }
     \context Lyrics = "sopranos" {
@@ -1097,8 +1097,8 @@ Notation Reference:
 To increase the spacing between lyrics, set the
 @code{minimum-distance} property of @code{LyricSpace}.
 
-@lilypond[relative=1,verbatim,quote,ragged-right]
-{
+@lilypond[verbatim,quote,ragged-right]
+\relative c' {
   c c c c
   \override Lyrics.LyricSpace.minimum-distance = #1.0
   c c c c
@@ -1115,8 +1115,8 @@ To make this change for all lyrics in the score, set the property in the
 
 @lilypond[verbatim,quote,ragged-right]
 \score {
-  \relative c' {
-  c c c c
+  \relative {
+  c' c c c
   c c c c
   }
   \addlyrics {
@@ -1154,7 +1154,7 @@ To make lyrics avoid bar lines as well, use
     \Lyrics
       \consists "Bar_engraver"
       \consists "Separating_line_group_engraver"
-      \override BarLine.transparent = ##t
+      \hide BarLine
   @}
 @}
 @end example
@@ -1180,8 +1180,8 @@ unchanged.
   <<
     \new Staff {
       \new Voice = "melody" {
-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a
           \repeat volta 2 { b4 b b b }
         }
       }
@@ -1205,8 +1205,8 @@ unfolded.
     <<
       \new Staff {
         \new Voice = "melody" {
-          \relative c'' {
-            a4 a a a
+          \relative {
+            a'4 a a a
             \repeat volta 2 { b4 b b b }
           }
         }
@@ -1230,8 +1230,8 @@ simply enter all the words:
   <<
     \new Staff {
       \new Voice = "melody" {
-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a
           \repeat unfold 2 { b4 b b b }
         }
       }
@@ -1256,8 +1256,8 @@ correctly nested in parallel sections:
   <<
     \new Staff {
       \new Voice = "melody" {
-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a
           \repeat volta 2 { b4 b b b }
         }
       }
@@ -1283,8 +1283,8 @@ More verses may be added in a similar way:
   <<
     \new Staff {
       \new Voice = "singleVoice" {
-        \relative c'' {
-	  a4 a a a
+        \relative {
+	  a'4 a a a
 	  \repeat volta 3 { b4 b b b }
           c4 c c c
 	}
@@ -1323,8 +1323,8 @@ To position them correctly use @code{alignBelowContext}:
   <<
     \new Staff {
       \new Voice = "melody" {
-        \relative c'' {
-	  a4 a a a
+        \relative {
+	  a'4 a a a
 	  \repeat volta 3 { b4 b b b }
           c4 c c c
 	}
@@ -1348,8 +1348,8 @@ To position them correctly use @code{alignBelowContext}:
       The end sec -- tion.
     }
     \new Voice = "harmony" {
-      \relative c' {
-        f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
+      \relative {
+        f'4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
       }
     }
   >>
@@ -1366,8 +1366,11 @@ To position them correctly use @code{alignBelowContext}:
 @cindex repeating lyrics with alternative endings
 @cindex alternative endings and lyrics
 
-If the words of the repeated section are the same, exactly the
-same structure can be used for both the lyrics and music.
+If the words of the repeated section are the same, and none of the
+@code{\alternative} blocks start with a rest, exactly the same
+structure can be used for both the lyrics and music.  This has the
+advantage that @code{\unfoldRepeats} will expand both music and
+lyrics correctly.
 
 @lilypond[quote,verbatim]
 \score {
@@ -1375,8 +1378,8 @@ same structure can be used for both the lyrics and music.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a
           \repeat volta 2 { b4 b }
           \alternative { { b b } { b c } }
         }
@@ -1397,7 +1400,8 @@ same structure can be used for both the lyrics and music.
 @cindex skipping notes in lyrics
 @cindex lyrics, skipping notes
 
-But when the repeated section has different words, a repeat
+But when the repeated section has different words, or when one
+of the @code{\alternative} blocks starts with a rest, a repeat
 construct cannot be used around the words and @code{\skip} commands
 have to be inserted manually to skip over the notes in the
 alternative sections which do not apply.
@@ -1418,8 +1422,8 @@ value, irrespective of the value of the following number.}
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
-        \relative c'' {
-          \repeat volta 2 { b4 b }
+        \relative {
+          \repeat volta 2 { b'4 b }
           \alternative { { b b } { b c } }
           c4 c
         }
@@ -1465,9 +1469,9 @@ melismata over the volta section and insert manual skips.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
-        \relative c'' {
+        \relative {
           \set melismaBusyProperties = #'()
-          \repeat volta 2 { b4 b ~}
+          \repeat volta 2 { b'4 b ~}
           \alternative { { b b } { b \repeatTie c } }
           \unset melismaBusyProperties
           c4 c
@@ -1502,8 +1506,8 @@ be inserted manually, as before.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
-        \relative c'' {
-          \repeat volta 2 { b4 b ~}
+        \relative {
+          \repeat volta 2 { b'4 b ~}
           \alternative { { b b } { b \repeatTie c } }
           c4 c
         }
@@ -1535,8 +1539,8 @@ alternative sections these must be inserted manually.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
-        \relative c'' {
-          \repeat volta 2 { b4 b ~}
+        \relative {
+          \repeat volta 2 { b'4 b ~}
           \alternative { { b b } { b \repeatTie c } }
           c4 c
         }
@@ -1607,11 +1611,11 @@ attaching lyrics to those specific contexts:
 \score {
   <<
     \new Voice = "melody" {
-      \relative c' {
+      \relative {
         <<
           {
             \voiceOne
-            e4 e8 e
+            e'4 e8 e
           }
           \new Voice = "splitpart" {
             \voiceTwo
@@ -1646,6 +1650,94 @@ passage is the proper construct to use, see section
 @emph{Temporary polyphonic passages} in @ref{Single-staff polyphony}.
 
 
+@node Polyphony with shared lyrics
+@unnumberedsubsubsec Polyphony with shared lyrics
+
+@cindex NullVoice
+@cindex polyphony, shared lyrics
+@cindex lyrics, shared among voices
+@cindex \partcombine and lyrics
+@funindex \partcombine
+
+When two voices with different rhythms share the same lyrics,
+aligning the lyrics to one of the voices may lead to problems in
+the other voice.  For example, the second lyric extender below is
+too short, since the lyrics are aligned only to the top voice:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice = "sopranoVoice" { \voiceOne \soprano }
+  \new Voice { \voiceTwo \alto }
+  \new Lyrics \lyricsto "sopranoVoice" \words
+>>
+@end lilypond
+
+To get the desired result, align the lyrics to a new
+@code{NullVoice} context containing a suitable combination of the
+two voices.  The notes of the @code{NullVoice} context do not
+appear on the printed page, but can be used to align the lyrics
+appropriately:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+aligner = \relative { b'8( c d c) b( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice { \voiceOne \soprano }
+  \new Voice { \voiceTwo \alto }
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+>>
+@end lilypond
+
+This method also can be used with the @code{\partcombine}
+function, which does not allow lyrics on its own:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+aligner = \relative { b'8( c d c) b( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice \partcombine \soprano \alto
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+>>
+@end lilypond
+
+@knownissues
+The @code{\addLyrics} function only works with @code{Voice} lyrics
+and so cannot be used with @code{NullVoice}.
+
+@noindent
+The @code{\partcombine} function is described in
+@ref{Automatic part combining}.
+
+Lastly, this method can be used even when the voices are in
+different staves, and is not limited to only two voices:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+altoOne = \relative { g'2 b8( a b4) }
+altoTwo = \relative { d'2 g4( fis8 g) }
+aligner = \relative { b'8( c d c) d( d d d) }
+words = \lyricmode { la __ la __ }
+
+\new ChoirStaff \with {\accepts NullVoice } <<
+  \new Staff \soprano
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+  \new Staff \partcombine \altoOne \altoTwo
+>>
+@end lilypond
+
 @node Stanzas
 @subsection Stanzas
 
@@ -1666,9 +1758,9 @@ passage is the proper construct to use, see section
 
 Stanza numbers can be added by setting @code{stanza}, e.g.,
 
-@lilypond[quote,ragged-right,verbatim,relative=2]
-\new Voice {
-  \time 3/4 g2 e4 a2 f4 g2.
+@lilypond[quote,ragged-right,verbatim]
+\new Voice \relative {
+  \time 3/4 g'2 e4 a2 f4 g2.
 } \addlyrics {
   \set stanza = #"1. "
   Hi, my name is Bert.
@@ -1751,9 +1843,9 @@ the line, just like instrument names.  They are created by setting
 @code{vocalName}.  A short version may be entered as
 @code{shortVocalName}.
 
-@lilypond[ragged-right,quote,verbatim,relative=2]
-\new Voice {
-  \time 3/4 g2 e4 a2 f4 g2.
+@lilypond[ragged-right,quote,verbatim]
+\new Voice \relative {
+  \time 3/4 g'2 e4 a2 f4 g2.
 } \addlyrics {
   \set vocalName = #"Bert "
   Hi, my name is Bert.
@@ -1779,9 +1871,9 @@ voice ignore the melisma.  This is done by setting
 
 @lilypond[verbatim,ragged-right,quote]
 <<
-  \relative c' \new Voice = "lahlah" {
+  \relative \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
-    c4
+    c'4
     \slurDotted
     f8.[( g16])
     a4
@@ -1816,9 +1908,9 @@ changed:
 
 @lilypond[verbatim,ragged-right,quote]
 <<
-  \new Voice = melody \relative c' {
-    f4 \appoggiatura a32 b4
-    \grace { f16[ a16] } b2
+  \new Voice = melody \relative {
+    f'4 \appoggiatura a32 b4
+    \grace { f16 a16 } b2
     \afterGrace b2 { f16[ a16] }
     \appoggiatura a32 b4
     \acciaccatura a8 b4
@@ -1847,7 +1939,7 @@ block:
 @lilypond[verbatim,ragged-right,quote]
 <<
   \new Voice = melody \relative c' {
-    \grace { c16[( d e f] }
+    \grace { c16( d e f }
     g1) f
   }
   \new Lyrics \with { includeGraceNotes = ##t }
@@ -1868,9 +1960,9 @@ within the lyrics by setting the @code{associatedVoice} property:
 
 @lilypond[verbatim,quote]
 <<
-  \relative c' \new Voice = "lahlah" {
+  \relative \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
-    c4
+    c'4
     <<
       \new Voice = "alternative" {
         \voiceOne
@@ -1944,8 +2036,8 @@ different ways to force linebreaks when using
 @code{\markup}.
 
 @lilypond[ragged-right,verbatim,quote]
-melody = \relative c' {
-e d c d | e e e e |
+melody = \relative {
+e' d c d | e e e e |
 d d e d | c1 |
 }
 
@@ -1986,8 +2078,8 @@ introduces each verse.  The following example shows how to produce such
 output in LilyPond.
 
 @lilypond[ragged-right,quote,verbatim]
-melody = \relative c' {
-  c4 c c c | d d d d
+melody = \relative {
+  c'4 c c c | d d d d
 }
 
 text = \lyricmode {
@@ -2175,6 +2267,8 @@ Several common topics in choral music are described fully elsewhere:
 @item
 An introduction to creating an SATB vocal score can be found in
 the Learning Manual, see @rlearning{Four-part SATB vocal score}.
+There is also a built-in template which simplifies the entry of
+SATB vocal music, see @rlearning{Built-in templates}.
 
 @item
 Several templates suitable for various styles of choral music can
@@ -2278,12 +2372,12 @@ above their respective staves, as shown here:
   \new ChoirStaff <<
     \new Staff {
       \new Voice {
-        \relative c'' { g4\f g g g }
+        \relative { g'4\f g g g }
       }
     }
     \new Staff {
       \new Voice {
-        \relative c' { d4 d d\p d }
+        \relative { d'4 d d\p d }
       }
     }
   >>
@@ -2309,7 +2403,7 @@ Notation Reference:
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
-@ref{Using an extra voice for breaks},
+@ref{Breaks},
 @ref{Vertical spacing}.
 
 Internals Reference:
@@ -2455,9 +2549,9 @@ staff is dedicated to that character alone:
     \new Staff {
       \set Staff.vocalName = \markup \smallCaps Kaspar
       \set Staff.shortVocalName = \markup \smallCaps Kas.
-      \relative c' {
+      \relative {
         \clef "G_8"
-        c4 c c c
+        c'4 c c c
         \break
         c4 c c c
       }
@@ -2466,7 +2560,7 @@ staff is dedicated to that character alone:
       \set Staff.vocalName = \markup \smallCaps Melchior
       \set Staff.shortVocalName = \markup \smallCaps Mel
       \clef "bass"
-      \relative c' {
+      \relative {
         a4 a a a
         a4 a a a
       }
@@ -2480,64 +2574,57 @@ usually printed above the staff at the start of every section
 applying to that character.  This can be done with markup.  Often a
 specific font is used for this purpose.
 
-@lilypond[quote,verbatim,relative=1]
-\clef "G_8"
-c4^\markup \fontsize #1 \smallCaps Kaspar
-c c c
-\clef "bass"
-a4^\markup \fontsize #1 \smallCaps Melchior
-a a a
-\clef "G_8"
-c4^\markup \fontsize #1 \smallCaps Kaspar
-c c c
+@lilypond[quote,verbatim]
+\relative c' {
+  \clef "G_8"
+  c4^\markup \fontsize #1 \smallCaps Kaspar
+  c c c
+  \clef "bass"
+  a4^\markup \fontsize #1 \smallCaps Melchior
+  a a a
+  \clef "G_8"
+  c4^\markup \fontsize #1 \smallCaps Kaspar
+  c c c
+}
 @end lilypond
 
-Alternatively, if there are many character changes, it may be
-easier to set up @qq{instrument} definitions for each character at
-the top level so that @code{\instrumentSwitch} can be used to
-indicate each change.
+Alternatively, if there are many character changes, it may be easier
+to set up variables to hold the definitions for each character so
+that the switch of characters can be indicated easily and concisely.
 
 @lilypond[quote,verbatim]
-\addInstrumentDefinition #"kaspar"
-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
-     (shortInstrumentName . "Kas.")
-     (clefGlyph . "clefs.G")
-     (clefTransposition . -7)
-     (middleCPosition . 1)
-     (clefPosition . -2)
-     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
-     (midiInstrument . "voice oohs"))
-
-\addInstrumentDefinition #"melchior"
-  #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
-     (shortInstrumentName . "Mel.")
-     (clefGlyph . "clefs.F")
-     (clefTransposition . 0)
-     (middleCPosition . 6)
-     (clefPosition . 2)
-     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
-     (midiInstrument . "choir aahs"))
+kaspar = {
+  \clef "G_8"
+  \set Staff.shortVocalName = "Kas."
+  \set Staff.midiInstrument = "voice oohs"
+  <>^\markup \smallCaps "Kaspar"
+}
+
+melchior = {
+  \clef "bass"
+  \set Staff.shortVocalName = "Mel."
+  \set Staff.midiInstrument = "choir aahs"
+  <>^\markup \smallCaps "Melchior"
+}
 
 \relative c' {
-  \instrumentSwitch "kaspar"
+  \kaspar
   c4 c c c
-  \instrumentSwitch "melchior"
+  \melchior
   a4 a a a
-  \instrumentSwitch "kaspar"
+  \kaspar
   c4 c c c
 }
 @end lilypond
 
 @seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
+
 Notation Reference:
-@ref{Instrument names},
-@ref{Scheme functions},
 @ref{Text},
 @ref{Text markup commands}.
 
-Extending LilyPond:
-@rextend{Markup construction in Scheme}.
-
 
 @node Musical cues
 @unnumberedsubsubsec Musical cues
@@ -2561,22 +2648,19 @@ close to the start of the cue notes.  The following example shows
 how this is done.
 
 @lilypond[quote,verbatim]
-flute = \relative c'' {
-  s4 s4 e g
+flute = \relative {
+  s4 s4 e'' g
 }
 \addQuote "flute" { \flute }
 
-pianoRH = \relative c'' {
-  c4. g8
+pianoRH = \relative {
+  c''4. g8
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
-  \new CueVoice {
-    \override InstrumentSwitch.self-alignment-X = #RIGHT
-    \set instrumentCueName = "Flute"
-  }
+  <>^\markup { \right-align { \tiny "Flute" } }
   \cueDuring "flute" #UP { g4 bes4 }
 }
-pianoLH = \relative c { c4 <c' e> e, <g c> }
+pianoLH = \relative { c4 <c' e> e, <g c> }
 
 \score {
   \new PianoStaff <<
@@ -2596,11 +2680,7 @@ specify its key so the conversion of its cue notes will be done
 automatically.  The example below shows this transposition for a
 B-flat clarinet.  The notes in this example are low on the staff so
 @code{DOWN} is specified in @code{\cueDuring} (so the stems are
-down) and the instrument name is positioned below the staff.  Note
-also that the piano right-hand voice is explicitly declared.  This
-is because the cue notes in this example begin at the start of the
-first bar and this would otherwise cause the entire piano right-hand
-notes to be placed in a @code{CueVoice} context.
+down) and the instrument name is positioned below the staff.
 
 @lilypond[quote,verbatim]
 clarinet = \relative c' {
@@ -2612,15 +2692,11 @@ clarinet = \relative c' {
 pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff
-  \new CueVoice {
-    \override InstrumentSwitch.self-alignment-X = #RIGHT
-    \override InstrumentSwitch.direction = #DOWN
-    \set instrumentCueName = "Clar."
-  }
+  <>_\markup { \right-align { \tiny "Clar." } }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }
-pianoLH = \relative c { c4 <c' e> e, <g c> }
+pianoLH = \relative { c4 <c' e> e, <g c> }
 
 \score {
   <<
@@ -2664,7 +2740,6 @@ Snippets:
 @rlsr{Vocal music}.
 
 Internals Reference:
-@rinternals{InstrumentSwitch},
 @rinternals{CueVoice}.
 
 @knownissues
@@ -2700,10 +2775,12 @@ moment.
 
 For short interjections a simple markup suffices.
 
-@lilypond[quote,verbatim,relative=2]
-a4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
-a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
-a4 a a a
+@lilypond[quote,verbatim]
+\relative {
+  a'4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
+  a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
+  a4 a a a
+}
 @end lilypond
 
 For longer phrases it may be necessary to expand the music to make
@@ -2730,8 +2807,8 @@ Here is an example illustrating how this might be done.
 @c manually adjusted to suit the imposed line length.  -td
 
 @lilypond[quote,verbatim,ragged-right]
-music = \relative c'' {
-  \repeat unfold 3 { a4 a a a }
+music = \relative {
+  \repeat unfold 3 { a'4 a a a }
 }
 
 dialogue = \lyricmode {
@@ -2815,7 +2892,7 @@ Chants often use quarter notes without stems to indicate the pitch,
 with the rhythm being taken from the spoken rhythm of the words.
 
 @lilypond[verbatim,quote]
-stemOff = { \override Staff.Stem.transparent = ##t }
+stemOff = { \hide Staff.Stem }
 
 \relative c' {
   \stemOff
@@ -2832,15 +2909,15 @@ all staves remove the bar line engraver completely:
 \score {
   \new StaffGroup <<
     \new Staff {
-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |
         a4 b c2 |
         a4 b c2 |
       }
     }
     \new Staff {
-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |
         a4 b c2 |
         a4 b c2 |
       }
@@ -2862,15 +2939,15 @@ Bar lines can also be removed on a staff-by-staff basis:
   \new ChoirStaff <<
     \new Staff
     \with { \remove "Bar_engraver" } {
-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |
         a4 b c2 |
         a4 b c2 |
       }
     }
     \new Staff {
-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |
         a4 b c2 |
         a4 b c2 |
       }
@@ -2883,34 +2960,38 @@ To remove bar lines from just a section of music treat it as a
 cadenza.  If the section is long you may need to insert dummy
 bar lines with @code{\bar ""} to show where the line should break.
 
-@lilypond[verbatim,quote,relative=2]
-a4 b c2 |
-\cadenzaOn
-a4 b c2
-a4 b c2
-\bar ""
-a4 b c2
-a4 b c2
-\cadenzaOff
-a4 b c2 |
-a4 b c2 |
+@lilypond[verbatim,quote]
+\relative a' {
+  a4 b c2 |
+  \cadenzaOn
+  a4 b c2
+  a4 b c2
+  \bar ""
+  a4 b c2
+  a4 b c2
+  \cadenzaOff
+  a4 b c2 |
+  a4 b c2 |
+}
 @end lilypond
 
 Rests or pauses in chants can be indicated by modified bar lines.
 
-@lilypond[verbatim, quote,relative=2]
-a4
-\cadenzaOn
-b c2
-a4 b c2
-\bar "'"
-a4 b c2
-a4 b c2
-\bar ";"
-a4 b c2
-\bar "!"
-a4 b c2
-\bar "||"
+@lilypond[verbatim, quote]
+\relative a' {
+  a4
+  \cadenzaOn
+  b c2
+  a4 b c2
+  \bar "'"
+  a4 b c2
+  a4 b c2
+  \bar ";"
+  a4 b c2
+  \bar "!"
+  a4 b c2
+  \bar "||"
+}
 @end lilypond
 
 Alternatively, the notation used in Gregorian chant for pauses or
@@ -2940,8 +3021,8 @@ finalis = {
 }
 
 \score {
-  \relative c'' {
-    g2 a4 g
+  \relative {
+    g'2 a4 g
     \divisioMinima
     g2 a4 g
     \divisioMaior
@@ -2964,8 +3045,8 @@ Chants usually omit the time signature and often omit the clef too.
 @lilypond[verbatim,quote]
 \score {
   \new Staff {
-    \relative c'' {
-      a4 b c2 |
+    \relative {
+      a'4 b c2 |
       a4 b c2 |
       a4 b c2 |
     }
@@ -2990,22 +3071,22 @@ in each half always contains a single chord of whole notes.  This is
 the @qq{reciting note}.  Chants are usually centered on the page.
 
 @lilypond[verbatim,quote]
-SopranoMusic = \relative g' {
-  g1 | c2 b | a1 | \bar "||"
+SopranoMusic = \relative {
+  g'1 | c2 b | a1 | \bar "||"
   a1 | d2 c | c b | c1 | \bar "||"
 }
 
-AltoMusic = \relative c' {
-  e1 | g2 g | f1 |
+AltoMusic = \relative {
+  e'1 | g2 g | f1 |
   f1 | f2 e | d d | e1 |
 }
 
-TenorMusic = \relative a {
-  c1 | c2 c | c1 |
+TenorMusic = \relative {
+  c'1 | c2 c | c1 |
   d1 | g,2 g | g g | g1 |
 }
 
-BassMusic =  \relative c {
+BassMusic =  \relative {
   c1 | e2 e | f1 |
   d1 | b2 c | g' g | c,1 |
 }