X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=b8f13106e30ed0650294da924781e735aa9dfdfd;hb=2055f35c47a045a50a01ff4dba8524322cfc3b48;hp=5c5b87b5f4487118807472344faf82cab4301eb4;hpb=858cae3cf927e4ad957ef9fd3e3c0e3b19584581;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 5c5b87b5f4..b8f13106e3 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,12 +7,12 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.14.0"
 
 @node Vocal music
 @section Vocal music
 
-@c TODO: inspirational headword
+@lilypondfile[quote]{vocal-headword.ly}
 
 This section explains how to typeset vocal music, and make sure
 that the lyrics will be aligned with the notes of their melody.
@@ -43,7 +43,6 @@ This section discusses issues common to most types of vocal music.
 * Manual syllable durations::
 * Multiple syllables to one note::
 * Multiple notes to one syllable::
-* Skipping notes::
 * Extenders and hyphens::
 @end menu
 
@@ -57,17 +56,23 @@ that may arise in any type of vocal music.
 @itemize
 
 @item
-Most styles of vocal music use written text as lyrics.  An introduction
-to this notation is to be found in @rlearning{Setting simple songs}.
+Most styles of vocal music use written text as lyrics.  An
+introduction to this notation is to be found in
+@rlearning{Setting simple songs}.
 
 @item
-Vocal music is likely to require the use of @code{markup} mode, either
-for lyrics of for other text elements (character's names, etc.).
-This syntax is described in @ref{Text markup introduction}.
+Vocal music is likely to require the use of @code{markup} mode,
+either for lyrics or for other text elements (characters' names,
+etc.)  This syntax is described in @ref{Text markup introduction}.
 
 @item
-@notation{Ambitus} may be added at the beginning of vocal staves, as explained
-in @ref{Ambitus}.
+@notation{Ambitus} may be added at the beginning of vocal staves,
+as explained in @ref{Ambitus}.
+
+@item
+Dynamic markings by default are placed below the staff, but in
+choral music they are usually placed above the staff in order to
+avoid the lyrics, as explained in @ref{Score layouts for choral}.
 
 @end itemize
 
@@ -75,11 +80,24 @@ in @ref{Ambitus}.
 Music Glossary:
 @rglos{ambitus}.
 
+Learning Manual:
+@rlearning{Setting simple songs}.
+
+Notation Reference:
+@ref{Text markup introduction},
+@ref{Ambitus},
+@ref{Score layouts for choral}.
+
+Snippets:
+@rlsr{Vocal music}.
+
 @node Entering lyrics
 @unnumberedsubsubsec Entering lyrics
 
 @cindex lyrics, entering
 @cindex entering lyrics
+@cindex formatting in lyrics
+@cindex lyrics, formatting
 @cindex punctuation in lyrics
 @cindex lyrics punctuation
 @cindex spaces in lyrics
@@ -90,10 +108,10 @@ Music Glossary:
 
 Lyrics are entered in a special input mode, which can be introduced
 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
-@code{\lyricsto}.  In this mode the input @code{d} is not parsed as
-the pitch @notation{D}, but rather as a one-letter syllable of text.
-In other words, syllables are entered like notes but with pitches
-replaced by text.
+@code{\lyricsto}.  In this special input mode, the input @code{d}
+is not parsed as the pitch @notation{D}, but rather as a one-letter
+syllable of text.  In other words, syllables are entered like notes
+but with pitches replaced by text.
 
 For example:
 
@@ -156,8 +174,8 @@ into the input file, providing it is saved with UTF-8 encoding.
 For more information, see @ref{Text encoding}.
 
 @lilypond[quote,verbatim]
-\relative c' { e4 f e d e f e2 }
-\addlyrics { He said: “Let my peo -- ple go.” }
+\relative c'' { d8 c16 a bes8 f e' d c4 }
+\addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
 @end lilypond
 
 Normal quotes may be used in lyrics, but they have to be preceded
@@ -180,6 +198,16 @@ combination of a backslash followed by one of @code{`}, @code{'},
 
 @c " to balance double quotes for not-so-bright context-sensitive editors
 
+Great control over the appearance of lyrics comes from using
+@code{\markup} inside the lyrics themselves. For explanation of many
+options, see @ref{Formatting text}.
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{formatting-lyrics-syllables.ly}
+
+
 @seealso
 Learning Manual:
 @rlearning{Songs}.
@@ -187,17 +215,22 @@ Learning Manual:
 Notation Reference:
 @ref{Automatic syllable durations},
 @ref{Fonts},
+@ref{Formatting text},
 @ref{Input modes},
-@ref{Manual syllable durations}.
+@ref{Manual syllable durations},
+@ref{Text encoding}.
 
 Internals Reference:
 @rinternals{LyricText}.
 
+Snippets:
+@rlsr{Text}
 
 @node Aligning lyrics to a melody
 @unnumberedsubsubsec Aligning lyrics to a melody
 
 @cindex lyrics, aligning to a melody
+@cindex @code{associatedVoice}
 @funindex \lyricmode
 @funindex \addlyrics
 @funindex \lyricsto
@@ -214,63 +247,104 @@ Lyrics can be aligned with melodies in two main ways:
 @itemize
 
 @item
-They can be aligned automatically, with the durations of the
-syllables being taken from an associated melody or other voice
-of music, using @code{\addlyrics} or @code{\lyricsto}.  See
-@ref{Automatic syllable durations}.
+Lyrics can be aligned automatically, with the durations of the
+syllables being taken from another voice of music or (in special
+circumstances) an associated melody, using @code{\addlyrics},
+@code{\lyricsto}, or by setting the @code{associatedVoice} property.
+For more details, see @ref{Automatic syllable durations}.
 
-@item
-They can be aligned independently of the duration of any notes
-if the durations of the syllables are specified explicitly,
-and entered with @code{\lyricmode}.  See
-@ref{Manual syllable durations}.
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \new Staff <<
+    \time 2/4
+    \new Voice = "one" \relative c'' {
+      \voiceOne
+      c4 b8. a16 g4. r8 a4 ( b ) c2
+    }
+    \new Voice = "two" \relative c' {
+      \voiceTwo
+       s2 s4. f8 e4 d c2
+    }
+  >>
 
-@end itemize
+% takes durations and alignment from notes in "one"
+  \new Lyrics \lyricsto "one" {
+    Life is __ _ love, live __ life.
+  }
+
+% takes durations and alignment from notes in "one" initially
+% then switches to "two"
+  \new Lyrics \lyricsto "one" {
+    No more let
+    \set associatedVoice = "two"  % must be set one syllable early
+    sins and sor -- rows grow.
+  }
+>>
+@end lilypond
+
+The first stanza shows the normal way of entering lyrics.
 
-The following example compares different ways to align lyrics.
+The second stanza shows how the voice from which the lyric
+durations are taken can be changed.  This is useful if the words to
+different stanzas fit the notes in different ways and all the
+durations are available in Voice contexts.  For more details, see
+@ref{Stanzas}.
+
+@item
+Lyrics can be aligned independently of the duration of any notes
+if the durations of the syllables are specified explicitly,
+and entered with @code{\lyricmode}.
 
 @lilypond[quote,ragged-right,verbatim]
 <<
   \new Voice = "one" \relative c'' {
-    \autoBeamOff
     \time 2/4
     c4 b8. a16 g4. f8 e4 d c2
   }
 
-% uses default durations of 2;
+% uses previous explicit duration of 2;
   \new Lyrics \lyricmode {
     Joy to the earth!
   }
 
-% explicit durations; left-aligned by default
+% explicit durations, set to a different rhythm
   \new Lyrics \lyricmode {
-    Joy4 to8. the16 world!4. the8 Lord4 is come.2
-  }
-
-% takes durations and alignment from notes in "one"
-  \new Lyrics \lyricsto "one" {
-    No more let sins and sor -- rows grow.
+    Life4 is love,2. live4 life.2
   }
 >>
 @end lilypond
 
 The first stanza is not aligned with the notes because the durations
-were not specified, and the default value of 2 is used for each
-word.  This can be useful for dialogue over music; for more, see
+were not specified, and the previous value of 2 is used for each
+word.
+
+The second stanza shows how the words can be aligned quite
+independently from the notes.  This is useful if the words to
+different stanzas fit the notes in different ways and the required
+durations are not available in a music context.  For more details
+see @ref{Manual syllable durations}.  This technique is also useful
+when setting dialogue over music; for examples showing this, see
 @ref{Dialogue over music}.
 
-The second stanza with explicitly specified durations is
-aligned to the notes because the durations are the same as the
-corresponding notes.  The words are left-aligned to the notes by
-default.  Useful if the words to different stanzas fit the notes in
-different ways.
+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}.
 
-The third stanza shows the normal way of entering lyrics.
+@end itemize
 
 @seealso
 Learning Manual:
 @rlearning{Aligning lyrics to a melody}.
 
+Notation Reference:
+@ref{Contexts explained},
+@ref{Automatic syllable durations}.
+@ref{Stanzas},
+@ref{Manual syllable durations},
+@ref{Dialogue over music},
+@ref{Manual syllable durations}.
+
 Internals Reference:
 @rinternals{Lyrics}.
 
@@ -279,9 +353,33 @@ Internals Reference:
 
 @cindex syllable durations, automatic
 @cindex lyrics and melodies
+@cindex associatedVoice
+@funindex \addlyrics
+@funindex \lyricsto
+
+Lyrics can be automatically aligned to the notes of a melody in
+three ways:
+
+@itemize
 
-Lyrics are aligned and typeset with the help of skips, hyphens and
-extender lines.
+@item
+by specifying the named Voice context containing the melody with
+@code{\lyricsto},
+
+@item
+by introducing the lyrics with @code{\addlyrics} and placing them
+immediately after the Voice context containing the melody,
+
+@item
+by setting the @code{associatedVoice} property, the alignment of
+the lyrics may be switched to a different named Voice context at
+any musical moment.
+
+@end itemize
+
+In all three methods hyphens can be drawn between the syllables of
+a word and extender lines can be drawn beyond the end of a word.  For
+details, see @ref{Extenders and hyphens}.
 
 The @code{Voice} context containing the melody to which the lyrics
 are being aligned must not have @qq{died}, or the lyrics after that
@@ -289,27 +387,43 @@ point will be lost.  This can happen if there are periods when that
 voice has nothing to do.  For methods of keeping contexts alive, see
 @ref{Keeping contexts alive}.
 
-The lyrics can be aligned under a given melody
-automatically.  This is achieved by combining the
-melody and the lyrics with the @code{\lyricsto} expression
+@subheading Using @code{\lyricsto}
 
-@example
-\new Lyrics \lyricsto @var{name} @{ @dots{} @}
-@end example
+@cindex \lyricsto
+@funindex \lyricsto
+
+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]
+<<
+  \new Voice = "melody" {
+    a4 a a a
+  }
+  \new Lyrics \lyricsto "melody" {
+    These are the words
+  }
+>>
+@end lilypond
 
 @noindent
-This aligns the lyrics to the
-notes of the @code{Voice} context called @var{name}, which must
-already exist.  Therefore normally the @code{Voice} is specified first, and
-then the lyrics are specified with @code{\lyricsto}.  The command
-@code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
-@code{\lyricmode} keyword may be omitted.
+This aligns the lyrics to the notes of the named @code{Voice}
+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}.
 
+@subheading Using @code{\addlyrics}
 
 @cindex \addlyrics
+@funindex \addlyrics
 
-The @code{\addlyrics} command is actually just a convenient shortcut
-that can sometimes be used instead of having to set up the lyrics
+The @code{\addlyrics} command is just a convenient shortcut that
+can sometimes be used instead of having to set up the lyrics
 through a more complicated LilyPond structure.
 
 @example
@@ -321,48 +435,41 @@ through a more complicated LilyPond structure.
 is the same as
 
 @example
-\new Voice = "blah" @{ music @}
+\new Voice = "blah" @{ MUSIC @}
 \new Lyrics \lyricsto "blah" @{ LYRICS @}
 @end example
 
 Here is an example,
 
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
+@lilypond[verbatim,quote]
+{
+  \time 3/4
+  \relative c' { c2 e4 g2. }
+  \addlyrics { play the game }
+}
 @end lilypond
 
 More stanzas can be added by adding more
 @code{\addlyrics} sections:
 
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
-\addlyrics { speel het spel }
-\addlyrics { joue le jeu }
-@end lilypond
-
-The command @code{\addlyrics} cannot handle polyphony settings.
-For these cases one should use @code{\lyricsto} and
-@code{\lyricmode}, for details see @ref{Entering lyrics}.
 
-@node Manual syllable durations
-@unnumberedsubsubsec Manual syllable durations
+@lilypond[ragged-right,verbatim,quote]
+{
+  \time 3/4
+  \relative c' { c2 e4 g2. }
+  \addlyrics { play the game }
+  \addlyrics { speel het spel }
+  \addlyrics { joue le jeu }
+}
+@end lilypond
 
-Lyrics can also be entered without @code{\addlyrics} or
-@code{\lyricsto}.  In this case, syllables are entered like
-notes -- but with pitches replaced by text -- and the duration
-of each syllable must be entered explicitly.  For example:
+The command @code{\addlyrics} cannot handle polyphonic settings.
+For these cases one should use @code{\lyricsto}.
 
-@example
-play2 the4 game2.
-sink2 or4 swim2.
-@end example
+@subheading Using associatedVoice
 
-The alignment to a melody can be specified with the
-@code{associatedVoice} property,
+The melody to which the lyrics are being aligned can be changed by
+setting the @code{associatedVoice} property,
 
 @example
 \set associatedVoice = #"lala"
@@ -370,33 +477,71 @@ The alignment to a melody can be specified with the
 
 @noindent
 
-@c TODO setting associated voice does more than format extender
-@c lines.  Document it properly.  Does it have anything to do
-@c with manual durations in lyrics?
+The value of the property (here: @code{"lala"}) should be the name
+of a @code{Voice} context.  For technical reasons, the @code{\set}
+command must be placed one syllable before the one to which the
+change in voice is to apply.
+
+Here is an example demonstrating its use:
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \new Staff <<
+    \time 2/4
+    \new Voice = "one" \relative c'' {
+      \voiceOne
+      c4 b8. a16 g4. r8 a4 ( b ) c2
+    }
+    \new Voice = "two" \relative c' {
+      \voiceTwo
+       s2 s4. f8 e8 d4. c2
+    }
+  >>
+% takes durations and alignment from notes in "one" initially
+% then switches to "two"
+  \new Lyrics \lyricsto "one" {
+    No more let
+    \set associatedVoice = "two"  % must be set one syllable early
+    sins and sor -- rows grow.
+  }
+>>
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Extenders and hyphens},
+@ref{Keeping contexts alive},
+@ref{Placing lyrics vertically}.
+
+@node Manual syllable durations
+@unnumberedsubsubsec Manual syllable durations
+
+In some complex vocal music, it may be desirable to place lyrics
+completely independently of notes.  In this case do not use
+@code{\lyricsto} or @code{\addlyrics} and do not set
+@code{associatedVoice}.  Syllables are entered like notes --
+but with pitches replaced by text -- and the duration of each
+syllable is entered explicitly after the syllable.
 
-The value of the property (here: @code{"lala"}) should be the name of
-a @code{Voice} context.  Without this setting, extender lines
-will not be formatted properly.
+By default, syllables will be left-aligned to the corresponding
+musical moment.  Hyphenated lines may be drawn between syllables
+as usual, but extender lines cannot be drawn when there is no
+associated voice.
 
-Here is an example demonstrating manual lyric durations,
+Here are two examples:
 
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
     \time 3/4
-    c2 e4 g2.
+    c2 e4 g2 f
   }
   \new Lyrics \lyricmode {
-    \set associatedVoice = #"melody"
-    play2 the4 game2.
+    play1 the4 game4
   }
 >>
 @end lilypond
 
-In some complex vocal music, it may be desirable to place lyrics
-completely independently of notes.  In this case do not use
-@code{\lyricsto} or @code{\addlyrics} and do not set
-@code{associatedVoice}:
 
 @lilypond[quote,verbatim,ragged-right]
 <<
@@ -420,11 +565,33 @@ completely independently of notes.  In this case do not use
 >>
 @end lilypond
 
+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.
+
+@lilypond[relative=1,verbatim,quote]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    c2 e4 g f g
+  }
+  \new Lyrics \lyricmode {
+    \set associatedVoice = #"melody"
+    play2 the4 game2. __
+  }
+>>
+@end lilypond
+
 @c TODO see also feature request 707 - show how to do this with manual durations
 
 @seealso
 Notation Reference:
-@ref{Keeping contexts alive}.
+@ref{Dialogue over music}.
 
 Internals Reference:
 @rinternals{Lyrics},
@@ -444,15 +611,20 @@ spaces between the syllables, you can surround the phrase with
 quotes or use a @code{_} character.  Alternatively, you can use
 code the tilde symbol (@code{~}) to get a lyric tie.  The lyric
 tie is implemented with the Unicode character U+203F, so be
-sure to have a font (like DejaVuLGC) installed that includes this
-glyph.
+sure to use a font for this glyph which actually contains it.
+Freely available fonts with a lyric tie are, for example,
+`FreeSerif' (a Times clone), `DejaVuSans' (but not
+`DejaVuSerif'), or `TeXGyreSchola' (a Century Schoolbook
+clone).
 
-@lilypond[quote,ragged-right,fragment,verbatim]
-\time 3/4
-\relative c' { c2 e4 g2 e4 }
-\addlyrics { gran- de_a- mi- go }
-\addlyrics { pu- "ro y ho-" nes- to }
-\addlyrics { pu- ro~y~ho- nes- to }
+@lilypond[quote,ragged-right,verbatim]
+{
+  \time 3/4
+  \relative c' { c2 e4 g2 e4 }
+  \addlyrics { gran- de_a- mi- go }
+  \addlyrics { pu- "ro y ho-" nes- to }
+  \addlyrics { pu- ro~y~ho- nes- to }
+}
 @end lilypond
 
 
@@ -502,7 +674,7 @@ together:
     e8
   }
   \new Lyrics \lyricsto "melody" {
-    Ki -- ri -- e __
+    Ky -- ri -- e __
   }
 >>
 @end lilypond
@@ -520,7 +692,7 @@ entering lyrics:
     e8 ( d e2 )
   }
   \new Lyrics \lyricsto "melody" {
-    Ki -- ri -- e __
+    Ky -- ri -- e __
   }
 >>
 @end lilypond
@@ -539,12 +711,12 @@ providing automatic beaming is switched off.  See
     e2.
   }
   \new Lyrics \lyricsto "melody" {
-    Ki -- ri -- e
+    Ky -- ri -- e
   }
 >>
 @end lilypond
 
-Clearly this is not suited to melisma over notes which are longer
+Clearly this is not suited to melismata over notes which are longer
 than eighth notes.
 
 @item
@@ -562,7 +734,7 @@ are bracketed between @code{\melisma} and @code{\melismaEnd}.
     e2.
   }
   \new Lyrics \lyricsto "melody" {
-    Ki -- ri -- e
+    Ky -- ri -- e
   }
 >>
 @end lilypond
@@ -583,7 +755,7 @@ to be added to the melisma.
     e8 d e2
   }
   \new Lyrics \lyricsto "melody" {
-    Ki -- ri -- _ _ _ e __ _ _
+    Ky -- ri -- _ _ _ e __ _ _
   }
 >>
 @end lilypond
@@ -592,8 +764,7 @@ to be added to the melisma.
 
 It is possible to have ties, slurs and manual beams in the melody
 without their indicating melismata.  To do this, set
-@code{melismaBusyProperties} and indicate the melismata with single
-underscores in the lyrics, one underscore for each extra note:
+@code{melismaBusyProperties}:
 
 @lilypond[relative=1,verbatim,quote]
 <<
@@ -601,19 +772,42 @@ underscores in the lyrics, one underscore for each extra note:
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
-    g8 [ f ] f4( e)
-    d e ~ e
+    g8 [ f ] f4 ~ f
   }
   \new Lyrics \lyricsto "melody" {
-    Ky -- _ _ _ _ ri -- _ _ e __ _
+    Ky -- ri -- e e -- le -- i -- son
   }
 >>
 @end lilypond
 
 Other settings for @code{melismaBusyProperties} can be used to
-include or exclude ties, slurs, and beams from the automatic
-detection of melismata; see @code{melismaBusyProperties} in
-@rinternals{Tunable context properties}.
+selectively include or exclude ties, slurs, and beams from the
+automatic detection of melismata; see @code{melismaBusyProperties}
+in @rinternals{Tunable context properties}.
+
+Alternatively, if all melismata indications are to be ignored,
+@code{ignoreMelismata} may be set true;
+see @ref{Stanzas with different rhythms}.
+
+If a melisma is required during a passage in which
+@code{melismaBusyProperties} is active, it may be indicated by
+placing a single underscore in the lyrics for each note which
+should be included in the melisma:
+
+@lilypond[relative=1,verbatim,quote]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    \set melismaBusyProperties = #'()
+    c4 d ( e )
+    g8 [ f ] ~ f4 ~ f
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ky -- ri -- _ e __ _ _ _
+  }
+>>
+@end lilypond
+
 
 @predefined
 
@@ -632,7 +826,8 @@ Learning Manual:
 Notation Reference:
 @ref{Aligning lyrics to a melody},
 @ref{Automatic syllable durations},
-@ref{Setting automatic beam behavior}.
+@ref{Setting automatic beam behavior},
+@ref{Stanzas with different rhythms}.
 
 Internals Reference:
 @rinternals{Tunable context properties}.
@@ -642,25 +837,6 @@ Internals Reference:
 Extender lines under melismata are not created automatically; they
 must be inserted manually with a double underscore.
 
-@node Skipping notes
-@unnumberedsubsubsec Skipping notes
-
-Making a lyric line run slower than the melody can be achieved by
-inserting @code{\skip}s into the lyrics.  For every @code{\skip},
-the text will be delayed by another note.  The @code{\skip} command
-must be followed by a valid duration, but this is ignored when
-@code{\skip} is used in lyrics which derive their durations from the
-notes in an associated melody through @code{\addlyrics} or
-@code{\lyricsto}.
-
-@lilypond[verbatim,ragged-right,quote]
-\relative c' { c c g' }
-\addlyrics {
-  twin -- \skip 4
-  kle
-}
-@end lilypond
-
 
 @node Extenders and hyphens
 @unnumberedsubsubsec Extenders and hyphens
@@ -668,6 +844,8 @@ notes in an associated melody through @code{\addlyrics} or
 @cindex melisma
 @cindex extender
 
+@c TODO cf Multiple notes to one syllable; should this be merged in?
+
 @c leave this as samp. -gp
 In the last syllable of a word, melismata are sometimes indicated with
 a long horizontal line starting in the melisma syllable, and ending in
@@ -684,15 +862,17 @@ typeset by default.}
 @cindex hyphens
 
 @c leave this as samp. -gp
-Centered hyphens are entered as @samp{ -- } between syllables of a same word
-(note the spaces before and after the two hyphen characters).  The hyphen
-will be centered between the syllables, and its length will be adjusted
-depending on the space between the syllables.
+Centered hyphens are entered as @samp{ -- } between syllables of a
+same word (note the spaces before and after the two hyphen
+characters).  The hyphen will be centered between the syllables, and
+its length will be adjusted depending on the space between the
+syllables.
 
 In tightly engraved music, hyphens can be removed.  Whether this
 happens can be controlled with the @code{minimum-distance} (minimum
 distance between two syllables) and the @code{minimum-length}
-(threshold below which hyphens are removed).
+(threshold below which hyphens are removed) properties of
+@code{LyricHyphen}.
 
 
 @seealso
@@ -708,10 +888,10 @@ Internals Reference:
 
 @menu
 * Working with lyrics and variables::
-* Placement of lyrics::
+* Placing lyrics vertically::
+* Placing syllables horizontally::
 * Lyrics and repeats::
 * Divisi lyrics::
-* Spacing out syllables::
 @end menu
 
 
@@ -719,74 +899,95 @@ Internals Reference:
 @node Working with lyrics and variables
 @unnumberedsubsubsec Working with lyrics and variables
 
-@c TODO rewrite this section
+@cindex lyrics, using variables
 
-@cindex lyrics, variables
-
-To define variables containing lyrics, the function @code{\lyricmode}
-must be used.  Durations do not need to be added if the variable is
-to be invoked with @code{\addlyrics} or @code{\lyricsto}.
+Variables containing lyrics can be created, but the lyrics must be
+entered in lyric mode:
 
 @lilypond[quote,verbatim]
-verseOne = \lyricmode { Joy to the world, the Lord is come. }
+musicOne = \relative c'' {
+  c4 b8. a16 g4. f8 e4 d c2
+}
+verseOne = \lyricmode {
+  Joy to the world, the Lord is come.
+}
 \score {
   <<
-    \new Voice = "one" \relative c'' {
-      \autoBeamOff
+    \new Voice = "one" {
       \time 2/4
-      c4 b8. a16 g4. f8 e4 d c2
+      \musicOne
+    }
+    \new Lyrics \lyricsto "one" {
+      \verseOne
     }
-    \addlyrics { \verseOne }
   >>
 }
 @end lilypond
 
-For different or more complex orderings, the best way is to set up the
-hierarchy of staves and lyrics first, e.g.,
-@example
-\new ChoirStaff <<
-  \new Voice = "soprano" @{ @emph{music} @}
-  \new Lyrics = "sopranoLyrics" @{ s1 @}
-  \new Lyrics = "tenorLyrics" @{ s1 @}
-  \new Voice = "tenor" @{ @emph{music} @}
->>
-@end example
+Durations do not need to be added if the variable is to be invoked
+with @code{\addlyrics} or @code{\lyricsto}.
 
-@noindent
-and then combine the appropriate melodies and lyric lines:
+For different or more complex orderings, the best way is to define
+the music and lyric variables first, then set up the hierarchy of
+staves and lyrics, omitting the lyrics themselves, and then add the
+lyrics using @code{\context} underneath.  This ensures that the
+voices referenced by @code{\lyricsto} have always been defined
+earlier.  For example:
 
-@example
-\context Lyrics = sopranoLyrics \lyricsto "soprano"
-@emph{the lyrics}
-@end example
+@lilypond[quote,verbatim]
+sopranoMusic = \relative c'' { c4 c c c }
+contraltoMusic = \relative c'' { a4 a a a }
+sopranoWords = \lyricmode { Sop -- ra -- no words }
+contraltoWords = \lyricmode { Con -- tral -- to words }
 
-@noindent
-The final input would resemble
+\score {
+  \new ChoirStaff <<
+    \new Staff {
+      \new Voice = "sopranos" {
+        \sopranoMusic
+      }
+    }
+    \new Lyrics = "sopranos"
+    \new Lyrics = "contraltos"
+    \new Staff {
+      \new Voice = "contraltos" {
+        \contraltoMusic
+      }
+    }
+    \context Lyrics = "sopranos" {
+      \lyricsto "sopranos" {
+        \sopranoWords
+      }
+    }
+    \context Lyrics = "contraltos" {
+      \lyricsto "contraltos" {
+        \contraltoWords
+      }
+    }
+  >>
+}
+@end lilypond
 
-@example
-<<\new ChoirStaff << @emph{setup the music} >>
- \lyricsto "soprano" @emph{etc}
- \lyricsto "alto" @emph{etc}
-@emph{etc}
->>
-@end example
 
 @seealso
-@c TODO: document \new Staff << Voice \lyricsto >> bug
+Notation Reference:
+@ref{Placing lyrics vertically}.
+
 Internals Reference:
 @rinternals{LyricCombineMusic},
 @rinternals{Lyrics}.
 
 
-@node Placement of lyrics
-@unnumberedsubsubsec Placement of lyrics
+@node Placing lyrics vertically
+@unnumberedsubsubsec Placing lyrics vertically
 
 @cindex placement of lyrics
 @cindex lyrics, positioning
 
-Lyrics are positioned above the staff, below the staff, or between
-staves, depending on the type of music.  To place lyrics below the
-associated staff simply define the Lyrics context below the Staff
+Depending on the type of music, lyrics may be positioned
+above the staff, below the staff, or between staves.  Placing
+lyrics below the associated staff is the easiest, and can be
+achieved by simply defining the Lyrics context below the Staff
 context:
 
 @lilypond[quote,verbatim]
@@ -806,21 +1007,20 @@ context:
 }
 @end lilypond
 
-To position lyrics above the staff, place the declaration of the
-Lyrics context before the Staff and Voice contexts, but the
-@code{\lyricsto} command must come after the Voice declaration it
-references, like this:
+Lyrics may be positioned above the staff using one of
+two methods.  The simplest (and preferred) method
+is to use the same syntax as above and explicitly
+specify the position of the lyrics:
 
 @lilypond[quote,verbatim]
 \score {
   <<
-    \new Lyrics = "lyrics"
-    \new Staff {
+    \new Staff = "staff" {
       \new Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }
-    \context Lyrics = "lyrics" {
+    \new Lyrics \with { alignAboveContext = "staff" } {
       \lyricsto "melody" {
         Here are the words
       }
@@ -829,18 +1029,25 @@ references, like this:
 }
 @end lilypond
 
-Alternatively, the position of the lyrics may be specified
-explicitly:
+Alternatively, a two-step process may be used.  First the Lyrics
+context is declared (without any content) before the Staff and
+Voice contexts, then the @code{\lyricsto} command is placed after
+the Voice declaration it references by using @code{\context}, as
+follows:
 
 @lilypond[quote,verbatim]
 \score {
   <<
-    \new Staff = "staff" {
+    \new Lyrics = "lyrics" \with {
+      % lyrics above a staff should have this override
+      \override VerticalAxisGroup #'staff-affinity = #DOWN
+    }
+    \new Staff {
       \new Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }
-    \new Lyrics \with { alignAboveContext = "staff" } {
+    \context Lyrics = "lyrics" {
       \lyricsto "melody" {
         Here are the words
       }
@@ -851,7 +1058,7 @@ explicitly:
 
 When there are two voices on separate staves the lyrics may be
 placed between the staves using either of these methods.  Here
-is an example of the first method:
+is an example of the second method:
 
 @lilypond[quote,verbatim]
 \score {
@@ -862,7 +1069,10 @@ is an example of the first method:
       }
     }
     \new Lyrics = "sopranos"
-    \new Lyrics = "contraltos"
+    \new Lyrics = "contraltos" \with {
+      % lyrics above a staff should have this override
+      \override VerticalAxisGroup #'staff-affinity = #DOWN
+    }
     \new Staff {
       \new Voice = "contraltos" {
         \relative c'' { a4 a a a }
@@ -883,8 +1093,12 @@ is an example of the first method:
 @end lilypond
 
 Other combinations of lyrics and staves may be generated by
-elaborating these examples, or by examining the SATB templates in
-the Learning Manual.
+elaborating these examples, or by examining the
+@rlearning{Vocal ensembles} templates in the Learning Manual.
+
+@snippets
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{lyrics-old-spacing-settings.ly}
 
 @seealso
 Learning Manual:
@@ -894,6 +1108,89 @@ Notation Reference:
 @ref{Aligning contexts},
 @ref{Creating contexts}.
 
+@node Placing syllables horizontally
+@unnumberedsubsubsec Placing syllables horizontally
+
+@cindex Spacing lyrics
+@cindex Lyrics, increasing space between
+
+To increase the spacing between lyrics, set the
+@code{minimum-distance} property of @code{LyricSpace}.
+
+@lilypond[relative=1,verbatim,quote,ragged-right]
+{
+  c c c c
+  \override Lyrics.LyricSpace #'minimum-distance = #1.0
+  c c c c
+}
+\addlyrics {
+  longtext longtext longtext longtext
+  longtext longtext longtext longtext
+}
+@end lilypond
+
+@noindent
+To make this change for all lyrics in the score, set the property in the
+@code{\layout} block.
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+  \relative c' {
+  c c c c
+  c c c c
+  }
+  \addlyrics {
+  longtext longtext longtext longtext
+  longtext longtext longtext longtext
+  }
+  \layout {
+    \context {
+      \Lyrics
+      \override LyricSpace #'minimum-distance = #1.0
+    }
+  }
+}
+@end lilypond
+
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{lyrics-alignment.ly}
+
+@c TODO: move to LSR -vv
+
+Checking to make sure that text scripts and lyrics are within the margins
+requires additional calculations.  To speed up processing slightly, this
+feature can be disabled:
+
+@example
+\override Score.PaperColumn #'keep-inside-line = ##f
+@end example
+
+To make lyrics avoid bar lines as well, use
+
+@example
+\layout @{
+  \context @{
+    \Lyrics
+      \consists "Bar_engraver"
+      \consists "Separating_line_group_engraver"
+      \override BarLine #'transparent = ##t
+  @}
+@}
+@end example
+
+@c TODO Create and add lsr example of lyricMelismaAlignment
+@c It's used like this to center-align all lyric syllables,
+@c even when notes are tied. -td
+
+@ignore
+\layout
+{
+     \context { \Score lyricMelismaAlignment = #0 }
+}
+@end ignore
+
+
 @node Lyrics and repeats
 @unnumberedsubsubsec Lyrics and repeats
 
@@ -982,24 +1279,9 @@ simply enter all the words:
 }
 @end lilypond
 
-@cindex lyric skip
-@funindex \skip
-
 When the words to a repeated volta section are different, the words
-to each repeat must be entered in separate @code{Lyrics} contexts.
-Earlier unrepeated sections must be skipped in the second and
-subsequent repeats.  The easiest way to skip several notes is to
-use @code{\repeat unfold} around the @code{\skip} command.
-
-Note: do not use an underscore, @code{_}, to skip notes in this
-particular case.  As this syntax indicates a melisma, it will cause
-the preceding syllable to be left-aligned.
-
-@warning{The @code{@bs{}skip} command must be followed by a number,
-but this number is ignored in lyrics which derive their durations
-from the notes in an associated melody through @code{\addlyrics} or
-@code{\lyricsto}.  Each @code{@bs{}skip} skips a single note of any
-value, irrespective of the value of the following number.}
+to each repeat must be entered in separate @code{Lyrics} contexts,
+correctly nested in parallel sections:
 
 @lilypond[verbatim,quote]
 \score {
@@ -1012,69 +1294,55 @@ value, irrespective of the value of the following number.}
         }
       }
     }
-    \new Lyrics {
-      \lyricsto "melody" {
-        Not re -- peat -- ed.
-        The first time words.
-      }
-    }
-    \new Lyrics {
-      \lyricsto "melody" {
-        % skip 4 notes of any duration
-        \repeat unfold 4 { \skip 1 }
-        Sec -- ond time words.
-      }
+    \new Lyrics \lyricsto "melody" {
+      Not re -- peat -- ed.
+      <<
+	{ The first time words. }
+	\new Lyrics {
+	  \set associatedVoice = "melody"
+	  Sec -- ond time words.
+	}
+      >>
     }
   >>
 }
 @end lilypond
 
-@cindex lyrics, repeating with a temporary voice
+More verses may be added in a similar way:
 
-An alternative way, which avoids skips and having to count notes,
-is to use a temporary voice for the repeated section.  This may be
-preferable if the earlier sections are still subject to change.  A
-temporary voice can be inserted anywhere in the main music stream
-in parallel with it, as shown below, but it may be necessary to
-keep the main voice alive in complex scores when using this
-technique; see @ref{Keeping contexts alive}.
-
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \score {
   <<
     \new Staff {
       \new Voice = "singleVoice" {
-        \relative c'' { a4 a a a }
-        \new Voice = "repeatVoice" {
-          \relative c'' \repeat volta 3 { b4 b b b }
-        }
-        \relative c'' { c4 c c c }
-      }
-    }
-    \new Lyrics <<
-      \lyricsto "singleVoice" {
-        Not re -- peat -- ed.
-        The end sec -- tion.
-      }
-      \lyricsto "repeatVoice" {
-        The first time words.
-      }
-    >>
-    \new Lyrics {
-      \lyricsto "repeatVoice" {
-        Sec -- ond time words.
+        \relative c'' {
+	  a4 a a a
+	  \repeat volta 3 { b4 b b b }
+          c4 c c c
+	}
       }
     }
-    \new Lyrics {
-      \lyricsto "repeatVoice" {
-        The third time words.
-      }
+    \new Lyrics \lyricsto "singleVoice" {
+      Not re -- peat -- ed.
+      <<
+        { The first time words.	}
+	\new Lyrics {
+	  \set associatedVoice = "singleVoice"
+	  Sec -- ond time words.
+	}
+	\new Lyrics {
+	  \set associatedVoice = "singleVoice"
+	  The third time words.
+	}
+      >>
+      The end sec -- tion.
     }
   >>
 }
 @end lilypond
 
-@c TODO lowering a common line of lyrics
+
+@c TODO positioning a common line of lyrics
 
 @subheading Repeats with alternative endings
 
@@ -1109,10 +1377,24 @@ same structure can be used for both the lyrics and music.
 }
 @end lilypond
 
+@funindex \skip
+@cindex skipping notes in lyrics
+@cindex lyrics, skipping notes
+
 But when the repeated section has different words, a repeat
 construct cannot be used around the words and @code{\skip} commands
-have to be inserted manually as described in the previous section to
-skip over the notes in the alternative sections which do not apply.
+have to be inserted manually to skip over the notes in the
+alternative sections which do not apply.
+
+Note: do not use an underscore, @code{_}, to skip notes -- an
+underscore indicates a melisma, causing the preceding syllable
+to be left-aligned.
+
+@warning{The @code{@bs{}skip} command must be followed by a number,
+but this number is ignored in lyrics which derive their durations
+from the notes in an associated melody through @code{\addlyrics} or
+@code{\lyricsto}.  Each @code{@bs{}skip} skips a single note of any
+value, irrespective of the value of the following number.}
 
 @lilypond[verbatim,quote,ragged-right]
 \score {
@@ -1261,6 +1543,10 @@ alternative sections these must be inserted manually.
 }
 @end lilypond
 
+@seealso
+Notation Reference:
+@ref{Keeping contexts alive},
+@ref{Repeats}.
 
 
 @node Divisi lyrics
@@ -1332,92 +1618,6 @@ attaching lyrics to those specific contexts:
 @end lilypond
 
 
-@node Spacing out syllables
-@unnumberedsubsubsec Spacing out syllables
-
-@cindex Spacing lyrics
-@cindex Lyrics, increasing space between
-
-To increase the spacing between lyrics, set the @code{minimum-distance}
-property of @code{LyricSpace}.
-
-@lilypond[relative,verbatim,fragment,quote,ragged-right]
-{
-  c c c c
-  \override Lyrics.LyricSpace #'minimum-distance = #1.0
-  c c c c
-}
-\addlyrics {
-  longtext longtext longtext longtext
-  longtext longtext longtext longtext
-}
-@end lilypond
-
-@noindent
-To make this change for all lyrics in the score, set the property in the
-layout.
-
-@lilypond[verbatim,quote,ragged-right]
-\score {
-  \relative c' {
-  c c c c
-  c c c c
-  }
-  \addlyrics {
-  longtext longtext longtext longtext
-  longtext longtext longtext longtext
-  }
-  \layout {
-    \context {
-      \Lyrics
-      \override LyricSpace #'minimum-distance = #1.0
-    }
-  }
-}
-@end lilypond
-
-@c @snippets
-@c This snippet has been renamed to "lyrics-alignment.ly"
-@c update as soon as lsr/is updated -vv
-@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-@c {lyrics-alignment.ly}
-
-@c TODO: move to LSR -vv
-@snippets
-
-Checking to make sure that text scripts and lyrics are within the margins is
-a relatively large computational task.  To speed up processing, LilyPond does
-not perform such calculations by default; to enable it, use
-
-@example
-\override Score.PaperColumn #'keep-inside-line = ##t
-@end example
-
-To make lyrics avoid bar lines as well, use
-
-@example
-\layout @{
-  \context @{
-    \Lyrics
-      \consists "Bar_engraver"
-      \consists "Separating_line_group_engraver"
-      \override BarLine #'transparent = ##t
-  @}
-@}
-@end example
-
-@c TODO Create and add lsr example of lyricMelismaAlignment
-@c It's used like this to center-align all lyric syllables,
-@c even when notes are tied. -td
-
-@ignore
-\layout
-{
-     \context { \Score lyricMelismaAlignment = #0 }
-}
-@end ignore
-
-
 @node Stanzas
 @subsection Stanzas
 
@@ -1438,7 +1638,7 @@ To make lyrics avoid bar lines as well, use
 
 Stanza numbers can be added by setting @code{stanza}, e.g.,
 
-@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
+@lilypond[quote,ragged-right,verbatim,relative=2]
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
@@ -1491,9 +1691,9 @@ stanzaOneThree =  {
 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in
-front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
-are no different.  For technical reasons, you have to set the stanza
-outside @code{\lyricmode}:
+front of a stanza goes into the @code{StanzaNumber} object; dynamics
+marks are no different.  For technical reasons, you have to set the
+stanza outside @code{\lyricmode}:
 
 @lilypond[quote,ragged-right,verbatim]
 text = {
@@ -1520,9 +1720,10 @@ text = {
 
 Names of singers can also be added.  They are printed at the start of
 the line, just like instrument names.  They are created by setting
-@code{vocalName}.  A short version may be entered as @code{shortVocalName}.
+@code{vocalName}.  A short version may be entered as
+@code{shortVocalName}.
 
-@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
+@lilypond[ragged-right,quote,verbatim,relative=2]
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
@@ -1544,7 +1745,7 @@ differing ways.  Such variations can still be captured with
 @subsubheading Ignoring melismata
 
 One possibility is that the text has a melisma in one stanza, but
-multiple syllables in another one.  One solution is to make the faster
+multiple syllables in another.  One solution is to make the faster
 voice ignore the melisma.  This is done by setting
 @code{ignoreMelismata} in the Lyrics context.
 
@@ -1578,32 +1779,38 @@ are to be ignored.
 
 @subsubheading Adding syllables to grace notes
 
+@cindex grace notes and lyrics
+@cindex lyrics on grace notes
+
 By default, grace notes (e.g. via @code{\grace}) do not get assigned
 syllables when using @code{\lyricsto}, but this behavior can be
 changed:
 
 @lilypond[verbatim,ragged-right,quote]
-\relative c' {
-  f4 \appoggiatura a32 b4
-  \grace { f16[ a16] } b2
-  \afterGrace b2 { f16[ a16] }
-  \appoggiatura a32 b4
-  \acciaccatura a8 b4
-}
-\addlyrics {
-  normal
-  \set includeGraceNotes = ##t
-  case,
-  gra -- ce case,
-  after -- grace case,
-  \set ignoreMelismata = ##t
-  app. case,
-  acc. case.
-}
+<<
+  \new Voice = melody \relative c' {
+    f4 \appoggiatura a32 b4
+    \grace { f16[ a16] } b2
+    \afterGrace b2 { f16[ a16] }
+    \appoggiatura a32 b4
+    \acciaccatura a8 b4
+  }
+  \new Lyrics
+  \lyricsto melody {
+    normal
+    \set includeGraceNotes = ##t
+    case,
+    gra -- ce case,
+    after -- grace case,
+    \set ignoreMelismata = ##t
+    app. case,
+    acc. case.
+  }
+>>
 @end lilypond
 
 @knownissues
-Like for @code{associatedVoice}, @code{includeGraceNotes} needs to be
+Like @code{associatedVoice}, @code{includeGraceNotes} needs to be
 set at latest one syllable before the one which is to be put under a
 grace note.  For the case of a grace note at the very beginning of a
 piece of music, consider using a @code{\with} or @code{\context}
@@ -1624,11 +1831,14 @@ block:
 
 @subsubheading Switching to an alternative melody
 
-More complex variations in text underlay are possible.  It is possible
-to switch the melody for a line of lyrics during the text.  This is
-done by setting the @code{associatedVoice} property.  In the example
+@cindex associatedVoice
+@cindex alternative melody, switching to
+
+More complex variations in setting lyrics to music are possible.
+The melody to which the lyrics are being set can be changed from
+within the lyrics by setting the @code{associatedVoice} property:
 
-@lilypond[ragged-right,quote]
+@lilypond[verbatim,quote]
 <<
   \relative c' \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
@@ -1655,56 +1865,43 @@ done by setting the @code{associatedVoice} property.  In the example
   \new Lyrics \lyricsto "lahlah" {
     % Tricky: need to set associatedVoice
     % one syllable too soon!
-    \set associatedVoice = alternative % applies to "ran"
+    \set associatedVoice = "alternative" % applies to "ran"
     Ty --
     ran --
     no --
-    \set associatedVoice = lahlah % applies to "rus"
+    \set associatedVoice = "lahlah" % applies to "rus"
     sau -- rus Rex
   } >>
 @end lilypond
 
 @noindent
-the text for the first stanza is set to a melody called @q{lahlah},
-
-@example
-\new Lyrics \lyricsto "lahlah" @{
-  Ju -- ras -- sic Park
-@}
-@end example
+The text for the first stanza is set to the melody called
+@q{lahlah} in the usual way, but the second stanza is set initally
+to the @code{lahlah} context and is then switched to the
+@code{alternative} melody for the syllables @q{ran} to @q{sau} by
+the lines:
 
-
-The second stanza initially is set to the @code{lahlah} context, but
-for the syllable @q{ran}, it switches to a different melody.
-This is achieved with
 @example
-\set associatedVoice = alternative
+\set associatedVoice = "alternative" % applies to "ran"
+Ty --
+ran --
+no --
+\set associatedVoice = "lahlah" % applies to "rus"
+sau -- rus Rex
 @end example
 
 @noindent
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 
-@c TODO: make this easier to understand -vv
-This command must be one syllable too early, before @q{Ty} in this
-case.  In other words, changing the associatedVoice happens one step
-later than expected.  This is for technical reasons, and it is not a
-bug.
-
-@example
-\new Lyrics \lyricsto "lahlah" @{
-  \set associatedVoice = alternative % applies to "ran"
-  Ty --
-  ran --
-  no --
-  \set associatedVoice = lahlah % applies to "rus"
-  sau -- rus Rex
-@}
-@end example
+Note the placement of the @code{\set associatedVoice} command --
+it appears to be one syllable too early, but this is correct.
 
-@noindent
-The underlay is switched back to the starting situation by assigning
-@code{lahlah} to @code{associatedVoice}.
+@warning{The @code{\set associatedVoice} command must be placed
+one syllable @emph{before} the one at which the switch to the new
+voice is to occur.  In other words, changing the associated Voice
+happens one syllable later than expected.  This is for technical
+reasons, and it is not a bug.}
 
 
 @node Printing stanzas at the end
@@ -1770,10 +1967,11 @@ text = \lyricmode {
   It has two lines.
 }
 
-\score{ <<
+\score {
+  <<
     \new Voice = "one" { \melody }
     \new Lyrics \lyricsto "one" \text
-   >>
+  >>
   \layout { }
 }
 
@@ -1864,15 +2062,14 @@ For writing the lyrics to a melody line, see
 @ref{Common notation for vocal music}.
 
 @item
-For placing the lyrics, see @ref{Placement of lyrics}.
+For placing the lyrics, see @ref{Placing lyrics vertically}.
 
 @item
 For entering stanzas, see @ref{Stanzas}.
 
 @item
 Songs are frequently printed with the chording indicated by chord
-names above the staves.  This is described in
-@ref{Displaying chords}.
+names above the staves.  This is described in @ref{Displaying chords}.
 
 @item
 To print fret diagrams of the chords for guitar accompaniment or
@@ -1890,14 +2087,17 @@ Notation Reference:
 @ref{Displaying chords},
 @ref{Displaying staves},
 @ref{Keyboard and other multi-staff instruments},
-@ref{Placement of lyrics},
+@ref{Placing lyrics vertically},
 @ref{Stanzas}.
 
+Snippets:
+@rlsr{Vocal music}.
+
 @node Lead sheets
 @unnumberedsubsubsec Lead sheets
 
-Lead sheets may be printed by combining vocal parts and @q{chord mode};
-this syntax is explained in @ref{Chord notation}.
+Lead sheets may be printed by combining vocal parts and
+@q{chord mode}; this syntax is explained in @ref{Chord notation}.
 
 @snippets
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
@@ -1959,7 +2159,7 @@ For information about @code{ChoirStaff} and @code{PianoStaff} see
 @ref{Grouping staves}.
 
 @item
-Shape noteheads, as used in Sacred Harp and similar notation, are
+Shape note heads, as used in Sacred Harp and similar notation, are
 described in @ref{Shape note heads}.
 
 @item
@@ -1986,6 +2186,9 @@ Notation Reference:
 @ref{Shape note heads},
 @ref{Single-staff polyphony}.
 
+Snippets:
+@rlsr{Vocal music}.
+
 Internals Reference:
 @rinternals{ChoirStaff},
 @rinternals{Lyrics},
@@ -2023,7 +2226,7 @@ the two systems.  See @ref{Separating systems}.
 
 @item
 For details of other page formatting properties, see
-@ref{Page formatting}.
+@ref{Page layout}.
 
 @end itemize
 
@@ -2069,7 +2272,7 @@ Notation Reference:
 @ref{Changing spacing},
 @ref{Displaying spacing},
 @ref{Fitting music onto fewer pages},
-@ref{Page formatting},
+@ref{Page layout},
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
@@ -2172,7 +2375,7 @@ See @ref{Separating systems}.
 
 @item
 For details of other page formatting properties, see
-@ref{Page formatting}.
+@ref{Page layout}.
 
 @item
 Dialogue cues and stage directions can be inserted with markup.
@@ -2193,12 +2396,15 @@ Notation Reference:
 @ref{Hiding staves},
 @ref{Instrument transpositions},
 @ref{Nested staff groups},
-@ref{Page formatting},
+@ref{Page layout},
 @ref{Separating systems},
 @ref{Transpose},
 @ref{Writing parts},
 @ref{Writing text}.
 
+Snippets:
+@rlsr{Vocal music}.
+
 
 @node Character names
 @unnumberedsubsubsec Character names
@@ -2207,15 +2413,14 @@ Notation Reference:
 @cindex names, character
 
 Character names are usually shown to the left of the staff when the
-staff is dedicated to that character alone.  The instrument name can
-be used for this purpose.
+staff is dedicated to that character alone:
 
 @lilypond[quote,verbatim,ragged-right]
 \score {
   <<
     \new Staff {
-      \set Staff.instrumentName = #"Kaspar"
-      \set Staff.shortInstrumentName = #"Kas"
+      \set Staff.vocalName = \markup \smallCaps Kaspar
+      \set Staff.shortVocalName = \markup \smallCaps Kas.
       \relative c' {
         \clef "G_8"
         c4 c c c
@@ -2224,8 +2429,8 @@ be used for this purpose.
       }
     }
     \new Staff {
-      \set Staff.instrumentName = #"Melchior"
-      \set Staff.shortInstrumentName = #"Mel"
+      \set Staff.vocalName = \markup \smallCaps Melchior
+      \set Staff.shortVocalName = \markup \smallCaps Mel
       \clef "bass"
       \relative c' {
         a4 a a a
@@ -2317,9 +2522,8 @@ main text, see @ref{Quoting other voices} and
 @ref{Formatting cue notes}.  But when many cues have to be
 inserted, for example, as an aid to a conductor in a vocal score,
 the instrument name must be positioned carefully just before and
-close to the start of the cued notes.  The following example shows
-how this is done.  Note that the name of the grob for overriding
-the cued instrument name is @code{InstrumentSwitch}.
+close to the start of the cue notes.  The following example shows
+how this is done.
 
 @lilypond[quote,verbatim]
 flute = \relative c'' {
@@ -2329,12 +2533,9 @@ flute = \relative c'' {
 
 pianoRH = \relative c'' {
   c4. g8
-  % position name of cued instrument just before the cued notes
-  \once \override CueVoice.InstrumentSwitch
-    #'self-alignment-X = #RIGHT
-  % position name of cued instrument above the staff
-  \once \override CueVoice.InstrumentSwitch #'direction = #UP
-  \set CueVoice.instrumentCueName = "Flute"
+  % position name of cue-ing instrument just before the cue notes,
+  % and above the staff
+  s1*0^\markup { \right-align { \tiny "Flute" } }
   \cueDuring "flute" #UP { g4 bes4 }
 }
 pianoLH = \relative c { c4 <c' e> e, <g c> }
@@ -2352,14 +2553,14 @@ pianoLH = \relative c { c4 <c' e> e, <g c> }
 }
 @end lilypond
 
-If a transposing instrument is being cued the instrument part should
-specify its key so the conversion of its cued notes will be done
+If a transposing instrument is being quoted the instrument part should
+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 cued notes in this example begin at the start of the
+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.
 
@@ -2372,12 +2573,8 @@ clarinet = \relative c' {
 
 pianoRH = \relative c'' {
   \transposition c'
-  % position name of cued instrument just before the cued notes
-  \once \override CueVoice.InstrumentSwitch
-    #'self-alignment-X = #RIGHT
-  % position name of cued instrument below the staff
-  \once \override CueVoice.InstrumentSwitch #'direction = #DOWN
-  \set CueVoice.instrumentCueName = "Clar."
+  % position name of cue-ing instrument below the staff
+  s1*0_\markup { \right-align { \tiny "Clar." } }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }
@@ -2401,10 +2598,10 @@ pianoLH = \relative c { c4 <c' e> e, <g c> }
 @end lilypond
 
 From these two examples it is clear that inserting many cues in a
-Vocal Score would be extremely tedious, and the notes of the piano
-part would be obscured by the many overrides.  However, as the
-following snippet shows, it is possible to define a music function
-to reduce the amount of typing and to make the piano notes clearer.
+Vocal Score would be tedious, and the notes of the piano part would
+become obscured.  However, as the following snippet shows, it is
+possible to define a music function to reduce the amount of typing
+and to make the piano notes clearer.
 
 @snippets
 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
@@ -2422,7 +2619,7 @@ Notation Reference:
 @ref{Using music functions}.
 
 Snippets:
-@rlsr{vocal-music}.
+@rlsr{Vocal music}.
 
 Internals Reference:
 @rinternals{InstrumentSwitch},
@@ -2431,10 +2628,10 @@ Internals Reference:
 @knownissues
 @code{\cueDuring} automatically inserts a @code{CueVoice} context
 and all cue notes are placed in that context.  This means it is not
-possible to have two overlapping sequences of cued notes by this
+possible to have two overlapping sequences of cue notes by this
 technique.  Overlapping sequences could be entered by explicitly
 declaring separate @code{CueVoice} contexts and using
-@code{\quoteDuring} to extract and insert the cued notes.
+@code{\quoteDuring} to extract and insert the cue notes.
 
 
 @node Spoken music
@@ -2442,8 +2639,8 @@ declaring separate @code{CueVoice} contexts and using
 
 @cindex parlato
 @cindex Sprechgesang
-Such effects as @q{parlato} or @q{Sprechgesang} require performers to speak
-without pitch but still with rhythm; these are notated by cross
+Such effects as @q{parlato} or @q{Sprechgesang} require performers to
+speak without pitch but still with rhythm; these are notated by cross
 note heads, as demonstrated in @ref{Special note heads}.
 
 @c TODO add "marking-notes-on-spoken-parts" snippet -vv
@@ -2485,7 +2682,7 @@ to manually insert @code{\break}s and adjust the placing of the
 dialogue to avoid running into the right margin.  The final word of
 the last measure on a line should also be separated out, as above.
 
-Here is an example illustating how this might be done.
+Here is an example illustrating how this might be done.
 
 @c This should be a snippet, but it can't be as it needs to be
 @c manually adjusted to suit the imposed line length.  -td
@@ -2561,6 +2758,9 @@ is described in @ref{Ancient notation}.
 Notation reference:
 @ref{Ancient notation}.
 
+Snippets:
+@rlsr{Vocal music}.
+
 
 @node Setting a chant
 @unnumberedsubsubsec Setting a chant
@@ -2639,7 +2839,7 @@ Bar lines can also be removed on a staff-by-staff basis:
 
 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
-barlines with @code{\bar ""} to show where the line should break.
+bar lines with @code{\bar ""} to show where the line should break.
 
 @lilypond[verbatim,quote,relative=2]
 a4 b c2 |
@@ -3026,7 +3226,8 @@ commands at the end of each line.
 @node Ancient vocal music
 @subsection Ancient vocal music
 
-Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+Ancient vocal music is supported, as explained in
+@ref{Ancient notation}.
 
 @c TODO