Docs: Get rid of lilyquote snippet option, replaced by ordinary quote

[lilypond.git] / Documentation / notation / vocal.itely

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 4ecaacfdfd8896c534a8e745a4e428b181ce56ca..a04a8e6ede18177ca332210d899341beda7e2f80 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,12 +7,12 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

-@c \version "2.12.0"
+@c \version "2.14.0"

 
 @node Vocal music
 @section Vocal music
 
 
 @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.
 
 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::
 * Manual syllable durations::
 * Multiple syllables to one note::
 * Multiple notes to one syllable::

-* Skipping notes::

 * Extenders and hyphens::
 @end menu
 
 * Extenders and hyphens::
 @end menu
 


@@ -57,17 +56,23 @@ that may arise in any type of vocal music.
 @itemize
 
 @item
 @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
 
 @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
 
 @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
 
 
 @end itemize
 


@@ -75,11 +80,24 @@ in @ref{Ambitus}.
 Music Glossary:
 @rglos{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
 @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
 @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
 
 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:
 
 
 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]
 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
 @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
 
 
 @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,quote,ragged-right,texidoc,doctitle]
+{formatting-lyrics-syllables.ly}
+
+

 @seealso
 Learning Manual:
 @rlearning{Songs}.
 @seealso
 Learning Manual:
 @rlearning{Songs}.


@@ -187,17 +215,22 @@ Learning Manual:
 Notation Reference:
 @ref{Automatic syllable durations},
 @ref{Fonts},
 Notation Reference:
 @ref{Automatic syllable durations},
 @ref{Fonts},

+@ref{Formatting text},

 @ref{Input modes},
 @ref{Input modes},

-@ref{Manual syllable durations}.
+@ref{Manual syllable durations},
+@ref{Text encoding}.

 
 Internals Reference:
 @rinternals{LyricText}.
 
 
 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
 
 @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
 @funindex \lyricmode
 @funindex \addlyrics
 @funindex \lyricsto


@@ -214,63 +247,104 @@ Lyrics can be aligned with melodies in two main ways:
 @itemize
 
 @item
 @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 following example compares different ways to align lyrics.
+The first stanza shows the normal way of entering 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'' {
 
 @lilypond[quote,ragged-right,verbatim]
 <<
   \new Voice = "one" \relative c'' {

-    \autoBeamOff

     \time 2/4
     c4 b8. a16 g4. f8 e4 d c2
   }
 
     \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!
   }
 
   \new Lyrics \lyricmode {
     Joy to the earth!
   }
 

-% explicit durations; left-aligned by default
+% explicit durations, set to a different rhythm

   \new Lyrics \lyricmode {
   \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
   }
 >>
 @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}.
 
 @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}.
 
 
 @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}.
 
 Internals Reference:
 @rinternals{Lyrics}.
 


@@ -279,9 +353,33 @@ Internals Reference:
 
 @cindex syllable durations, automatic
 @cindex lyrics and melodies
 
 @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
+
+@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

 
 

-Lyrics are aligned and typeset with the help of skips, hyphens and
-extender lines.
+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
 
 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}.
 
 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
 
 @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
 
 @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
 through a more complicated LilyPond structure.
 
 @example


@@ -321,75 +435,163 @@ through a more complicated LilyPond structure.
 is the same as
 
 @example
 is the same as
 
 @example

-\new Voice = "blah" @{ music @}
+\new Voice = "blah" @{ MUSIC @}

 \new Lyrics \lyricsto "blah" @{ LYRICS @}
 @end example
 
 Here is an example,
 
 \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:
 
 @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"
 @end example
 
 @noindent
 
 @example
 \set associatedVoice = #"lala"
 @end example
 
 @noindent

-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.

 
 

-Here is an example demonstrating manual lyric durations,
+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.

 
 

-@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
-<< \new Voice = "melody" {
+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 are two examples:
+
+@lilypond[relative=1,verbatim,quote]
+<<
+  \new Voice = "melody" {

     \time 3/4
     \time 3/4

-    c2 e4 g2.
- }
- \new Lyrics \lyricmode {
-   \set associatedVoice = #"melody"
-   play2 the4 game2.
- } >>
+    c2 e4 g2 f
+  }
+  \new Lyrics \lyricmode {
+    play1 the4 game4
+  }
+>>

 @end lilypond
 
 
 @end lilypond
 
 

+@lilypond[quote,verbatim,ragged-right]
+<<
+  \new Staff {
+    \relative c'' {
+      c2 c2
+      d1
+    }
+  }
+  \new Lyrics {
+    \lyricmode {
+      I2 like4. my8 cat!1
+    }
+  }
+  \new Staff {
+    \relative c' {
+      c8 c c c c c c c
+      c8 c c c c c c c
+    }
+  }
+>>
+@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:
 @seealso
 Notation Reference:

-@ref{Keeping contexts alive}.
+@ref{Dialogue over music}.

 
 Internals Reference:
 @rinternals{Lyrics},
 
 Internals Reference:
 @rinternals{Lyrics},


@@ -407,17 +609,16 @@ Internals Reference:
 In order to assign more than one syllable to a single note with
 spaces between the syllables, you can surround the phrase with
 quotes or use a @code{_} character.  Alternatively, you can use
 In order to assign more than one syllable to a single note with
 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.
+the tilde symbol (@code{~}) to get a lyric tie.

 
 

-@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
 
 
 @end lilypond
 
 


@@ -443,7 +644,7 @@ left-aligned with the first note of the melisma.
 When a melisma occurs on a syllable other that 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,
 When a melisma occurs on a syllable other that 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,

-@code{--}, immediately after the syllable.
+@w{@code{--}}, immediately after the syllable.

 
 Alternatively, when a melisma occurs on the last or only syllable in
 a word an extender line is usually drawn from the end of the syllable
 
 Alternatively, when a melisma occurs on the last or only syllable in
 a word an extender line is usually drawn from the end of the syllable


@@ -467,7 +668,7 @@ together:
     e8
   }
   \new Lyrics \lyricsto "melody" {
     e8
   }
   \new Lyrics \lyricsto "melody" {

-    Ki -- ri -- e __
+    Ky -- ri -- e __

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -485,7 +686,7 @@ entering lyrics:
     e8 ( d e2 )
   }
   \new Lyrics \lyricsto "melody" {
     e8 ( d e2 )
   }
   \new Lyrics \lyricsto "melody" {

-    Ki -- ri -- e __
+    Ky -- ri -- e __

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -504,12 +705,12 @@ providing automatic beaming is switched off.  See
     e2.
   }
   \new Lyrics \lyricsto "melody" {
     e2.
   }
   \new Lyrics \lyricsto "melody" {

-    Ki -- ri -- e
+    Ky -- ri -- e

   }
 >>
 @end lilypond
 
   }
 >>
 @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
 than eighth notes.
 
 @item


@@ -527,7 +728,7 @@ are bracketed between @code{\melisma} and @code{\melismaEnd}.
     e2.
   }
   \new Lyrics \lyricsto "melody" {
     e2.
   }
   \new Lyrics \lyricsto "melody" {

-    Ki -- ri -- e
+    Ky -- ri -- e

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -548,7 +749,7 @@ to be added to the melisma.
     e8 d e2
   }
   \new Lyrics \lyricsto "melody" {
     e8 d e2
   }
   \new Lyrics \lyricsto "melody" {

-    Ki -- ri -- _ _ _ e __ _ _
+    Ky -- ri -- _ _ _ e __ _ _

   }
 >>
 @end lilypond
   }
 >>
 @end lilypond


@@ -557,8 +758,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
 
 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]
 <<
 
 @lilypond[relative=1,verbatim,quote]
 <<


@@ -566,19 +766,42 @@ underscores in the lyrics, one underscore for each extra note:
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )

-    g8 [ f ] f4( e)
-    d e ~ e
+    g8 [ f ] f4 ~ f

   }
   \new Lyrics \lyricsto "melody" {
   }
   \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
   }
 >>
 @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
 
 
 @predefined
 


@@ -597,7 +820,8 @@ Learning Manual:
 Notation Reference:
 @ref{Aligning lyrics to a melody},
 @ref{Automatic syllable durations},
 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}.
 
 Internals Reference:
 @rinternals{Tunable context properties}.


@@ -607,25 +831,6 @@ Internals Reference:
 Extender lines under melismata are not created automatically; they
 must be inserted manually with a double underscore.
 
 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
 
 @node Extenders and hyphens
 @unnumberedsubsubsec Extenders and hyphens


@@ -633,6 +838,8 @@ notes in an associated melody through @code{\addlyrics} or
 @cindex melisma
 @cindex extender
 
 @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
 @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


@@ -649,15 +856,17 @@ typeset by default.}
 @cindex hyphens
 
 @c leave this as samp. -gp
 @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}
 
 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
 
 
 @seealso


@@ -673,11 +882,10 @@ Internals Reference:
 
 @menu
 * Working with lyrics and variables::
 
 @menu
 * Working with lyrics and variables::

-* Placement of lyrics::
+* Placing lyrics vertically::
+* Placing syllables horizontally::

 * Lyrics and repeats::
 * Divisi lyrics::
 * Lyrics and repeats::
 * Divisi lyrics::

-* Lyrics independent of notes::
-* Spacing out syllables::

 @end menu
 
 
 @end menu
 
 


@@ -685,74 +893,95 @@ Internals Reference:
 @node Working with lyrics and variables
 @unnumberedsubsubsec Working with lyrics and variables
 
 @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]
 
 @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 {
   <<
 \score {
   <<

-    \new Voice = "one" \relative c'' {
-      \autoBeamOff
+    \new Voice = "one" {

       \time 2/4
       \time 2/4

-      c4 b8. a16 g4. f8 e4 d c2
+      \musicOne
+    }
+    \new Lyrics \lyricsto "one" {
+      \verseOne

     }
     }

-    \addlyrics { \verseOne }

   >>
 }
 @end lilypond
 
   >>
 }
 @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
 
 @seealso

-@c TODO: document \new Staff << Voice \lyricsto >> bug
+Notation Reference:
+@ref{Placing lyrics vertically}.
+

 Internals Reference:
 @rinternals{LyricCombineMusic},
 @rinternals{Lyrics}.
 
 
 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
 
 
 @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]
 context:
 
 @lilypond[quote,verbatim]


@@ -772,21 +1001,20 @@ context:
 }
 @end lilypond
 
 }
 @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 {
   <<
 
 @lilypond[quote,verbatim]
 \score {
   <<

-    \new Lyrics = "lyrics"
-    \new Staff {
+    \new Staff = "staff" {

       \new Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }
       \new Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }

-    \context Lyrics = "lyrics" {
+    \new Lyrics \with { alignAboveContext = "staff" } {

       \lyricsto "melody" {
         Here are the words
       }
       \lyricsto "melody" {
         Here are the words
       }


@@ -795,18 +1023,25 @@ references, like this:
 }
 @end lilypond
 
 }
 @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 {
   <<
 
 @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 Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }

-    \new Lyrics \with { alignAboveContext = "staff" } {
+    \context Lyrics = "lyrics" {

       \lyricsto "melody" {
         Here are the words
       }
       \lyricsto "melody" {
         Here are the words
       }


@@ -817,7 +1052,7 @@ explicitly:
 
 When there are two voices on separate staves the lyrics may be
 placed between the staves using either of these methods.  Here
 
 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 {
 
 @lilypond[quote,verbatim]
 \score {


@@ -828,7 +1063,10 @@ is an example of the first method:
       }
     }
     \new Lyrics = "sopranos"
       }
     }
     \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 }
     \new Staff {
       \new Voice = "contraltos" {
         \relative c'' { a4 a a a }


@@ -849,8 +1087,12 @@ is an example of the first method:
 @end lilypond
 
 Other combinations of lyrics and staves may be generated by
 @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,quote,texidoc,doctitle]
+{lyrics-old-spacing-settings.ly}

 
 @seealso
 Learning Manual:
 
 @seealso
 Learning Manual:


@@ -860,6 +1102,89 @@ Notation Reference:
 @ref{Aligning contexts},
 @ref{Creating contexts}.
 
 @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,quote,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
 
 @node Lyrics and repeats
 @unnumberedsubsubsec Lyrics and repeats
 


@@ -948,24 +1273,9 @@ simply enter all the words:
 }
 @end lilypond
 
 }
 @end lilypond
 

-@cindex lyric skip
-@funindex \skip
-

 When the words to a repeated volta section are different, the words
 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 {
 
 @lilypond[verbatim,quote]
 \score {


@@ -978,69 +1288,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
 
     }
   >>
 }
 @end lilypond
 

-@cindex lyrics, repeating with a temporary voice
-
-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}.
+More verses may be added in a similar way:

 
 

-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]

 \score {
   <<
     \new Staff {
       \new Voice = "singleVoice" {
 \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
 
     }
   >>
 }
 @end lilypond
 

-@c TODO lowering a common line of lyrics
+
+@c TODO positioning a common line of lyrics

 
 @subheading Repeats with alternative endings
 
 
 @subheading Repeats with alternative endings
 


@@ -1075,10 +1371,24 @@ same structure can be used for both the lyrics and music.
 }
 @end lilypond
 
 }
 @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
 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 {
 
 @lilypond[verbatim,quote,ragged-right]
 \score {


@@ -1227,6 +1537,10 @@ alternative sections these must be inserted manually.
 }
 @end lilypond
 
 }
 @end lilypond
 

+@seealso
+Notation Reference:
+@ref{Keeping contexts alive},
+@ref{Repeats}.

 
 
 @node Divisi lyrics
 
 
 @node Divisi lyrics


@@ -1298,137 +1612,6 @@ attaching lyrics to those specific contexts:
 @end lilypond
 
 
 @end lilypond
 
 

-@node Lyrics independent of notes
-@unnumberedsubsubsec Lyrics independent of notes
-
-@c TODO remove this section?  Don't use DevNull
-@c should be all in Manual Syllable durations
-
-@cindex Devnull context
-
-In some complex vocal music, it may be desirable to place
-lyrics completely independently of notes.  Music defined
-inside @code{lyricrhythm} disappears into the
-@code{Devnull} context, but the rhythms can still be used
-to place the lyrics.
-
-@lilypond[quote,verbatim,ragged-right]
-voice = {
-  c''2
-  \tag #'music { c''2 }
-  \tag #'lyricrhythm { c''4. c''8 }
-  d''1
-}
-
-lyr = \lyricmode { I like my cat! }
-
-<<
-  \new Staff \keepWithTag #'music \voice
-  \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
-  \new Lyrics \lyricsto "nowhere" \lyr
-  \new Staff { c'8 c' c' c' c' c' c' c'
-  c' c' c' c' c' c' c' c' }
->>
-@end lilypond
-
-This method is recommended only if the music in the @code{Devnull}
-context does not contain melismata.  Melismata are defined by the
-@code{Voice} context.  Connecting lyrics to a @code{Devnull} context
-makes the voice/lyrics links to get lost, and so does the info on
-melismata.  Therefore, if you link lyrics to a @code{Devnull} context,
-the implicit melismata get ignored.
-
-@c Conclusion: do not use devnull for lyrics -FV
-
-@c this clarifies http://code.google.com/p/lilypond/issues/detail?id=248
-@c see also feature request 777 - show how to do this in manual durations
-
-@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
 
 @node Stanzas
 @subsection Stanzas
 


@@ -1449,7 +1632,7 @@ To make lyrics avoid bar lines as well, use
 
 Stanza numbers can be added by setting @code{stanza}, e.g.,
 
 
 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 {
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {


@@ -1502,9 +1685,9 @@ stanzaOneThree =  {
 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in
 
 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 = {
 
 @lilypond[quote,ragged-right,verbatim]
 text = {


@@ -1531,9 +1714,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
 
 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 {
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {


@@ -1555,7 +1739,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
 @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.
 
 voice ignore the melisma.  This is done by setting
 @code{ignoreMelismata} in the Lyrics context.
 


@@ -1589,32 +1773,38 @@ are to be ignored.
 
 @subsubheading Adding syllables to grace notes
 
 
 @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]
 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
 @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}
 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}


@@ -1635,11 +1825,14 @@ block:
 
 @subsubheading Switching to an alternative melody
 
 
 @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
 <<
   \relative c' \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f


@@ -1666,56 +1859,43 @@ done by setting the @code{associatedVoice} property.  In the example
   \new Lyrics \lyricsto "lahlah" {
     % Tricky: need to set associatedVoice
     % one syllable too soon!
   \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 --
     Ty --
     ran --
     no --

-    \set associatedVoice = lahlah % applies to "rus"
+    \set associatedVoice = "lahlah" % applies to "rus"

     sau -- rus Rex
   } >>
 @end lilypond
 
 @noindent
     sau -- rus Rex
   } >>
 @end lilypond
 
 @noindent

-the text for the first stanza is set to a melody called @q{lahlah},
+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:

 
 @example
 
 @example

-\new Lyrics \lyricsto "lahlah" @{
-  Ju -- ras -- sic Park
-@}
-@end example
-
-
-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.
 
 @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
 
 
 @node Printing stanzas at the end


@@ -1781,10 +1961,11 @@ text = \lyricmode {
   It has two lines.
 }
 
   It has two lines.
 }
 

-\score{ <<
+\score {
+  <<

     \new Voice = "one" { \melody }
     \new Lyrics \lyricsto "one" \text
     \new Voice = "one" { \melody }
     \new Lyrics \lyricsto "one" \text

-   >>
+  >>

   \layout { }
 }
 
   \layout { }
 }
 


@@ -1875,15 +2056,14 @@ For writing the lyrics to a melody line, see
 @ref{Common notation for vocal music}.
 
 @item
 @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
 
 @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
 
 @item
 To print fret diagrams of the chords for guitar accompaniment or


@@ -1901,17 +2081,20 @@ Notation Reference:
 @ref{Displaying chords},
 @ref{Displaying staves},
 @ref{Keyboard and other multi-staff instruments},
 @ref{Displaying chords},
 @ref{Displaying staves},
 @ref{Keyboard and other multi-staff instruments},

-@ref{Placement of lyrics},
+@ref{Placing lyrics vertically},

 @ref{Stanzas}.
 
 @ref{Stanzas}.
 

+Snippets:
+@rlsr{Vocal music}.
+

 @node Lead sheets
 @unnumberedsubsubsec Lead sheets
 
 @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
 
 @snippets

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {simple-lead-sheet.ly}
 
 @seealso
 {simple-lead-sheet.ly}
 
 @seealso


@@ -1970,7 +2153,7 @@ For information about @code{ChoirStaff} and @code{PianoStaff} see
 @ref{Grouping staves}.
 
 @item
 @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
 described in @ref{Shape note heads}.
 
 @item


@@ -1997,6 +2180,9 @@ Notation Reference:
 @ref{Shape note heads},
 @ref{Single-staff polyphony}.
 
 @ref{Shape note heads},
 @ref{Single-staff polyphony}.
 

+Snippets:
+@rlsr{Vocal music}.
+

 Internals Reference:
 @rinternals{ChoirStaff},
 @rinternals{Lyrics},
 Internals Reference:
 @rinternals{ChoirStaff},
 @rinternals{Lyrics},


@@ -2034,7 +2220,7 @@ the two systems.  See @ref{Separating systems}.
 
 @item
 For details of other page formatting properties, see
 
 @item
 For details of other page formatting properties, see

-@ref{Page formatting}.
+@ref{Page layout}.

 
 @end itemize
 
 
 @end itemize
 


@@ -2080,7 +2266,7 @@ Notation Reference:
 @ref{Changing spacing},
 @ref{Displaying spacing},
 @ref{Fitting music onto fewer pages},
 @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},
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},


@@ -2097,7 +2283,7 @@ Internals Reference:
 
 @cindex voices, divided
 
 
 @cindex voices, divided
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {using-arpeggiobracket-to-make-divisi-more-visible.ly}
 
 @seealso
 {using-arpeggiobracket-to-make-divisi-more-visible.ly}
 
 @seealso


@@ -2183,7 +2369,7 @@ See @ref{Separating systems}.
 
 @item
 For details of other page formatting properties, see
 
 @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.
 
 @item
 Dialogue cues and stage directions can be inserted with markup.


@@ -2204,12 +2390,15 @@ Notation Reference:
 @ref{Hiding staves},
 @ref{Instrument transpositions},
 @ref{Nested staff groups},
 @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}.
 
 @ref{Separating systems},
 @ref{Transpose},
 @ref{Writing parts},
 @ref{Writing text}.
 

+Snippets:
+@rlsr{Vocal music}.
+

 
 @node Character names
 @unnumberedsubsubsec Character names
 
 @node Character names
 @unnumberedsubsubsec Character names


@@ -2218,15 +2407,14 @@ Notation Reference:
 @cindex names, character
 
 Character names are usually shown to the left of the staff when the
 @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 {
 
 @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
       \relative c' {
         \clef "G_8"
         c4 c c c


@@ -2235,8 +2423,8 @@ be used for this purpose.
       }
     }
     \new Staff {
       }
     }
     \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
       \clef "bass"
       \relative c' {
         a4 a a a


@@ -2328,9 +2516,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
 @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'' {
 
 @lilypond[quote,verbatim]
 flute = \relative c'' {


@@ -2340,12 +2527,9 @@ flute = \relative c'' {
 
 pianoRH = \relative c'' {
   c4. g8
 
 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> }
   \cueDuring "flute" #UP { g4 bes4 }
 }
 pianoLH = \relative c { c4 <c' e> e, <g c> }


@@ -2363,14 +2547,14 @@ pianoLH = \relative c { c4 <c' e> e, <g c> }
 }
 @end lilypond
 
 }
 @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
 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
+@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
 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.
 
 first bar and this would otherwise cause the entire piano right-hand
 notes to be placed in a @code{CueVoice} context.
 


@@ -2383,12 +2567,8 @@ clarinet = \relative c' {
 
 pianoRH = \relative c'' {
   \transposition 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
 }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }


@@ -2412,13 +2592,13 @@ pianoLH = \relative c { c4 <c' e> e, <g c> }
 @end lilypond
 
 From these two examples it is clear that inserting many cues in a
 @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
 
 @snippets

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {adding-orchestral-cues-to-a-vocal-score.ly}
 
 @seealso
 {adding-orchestral-cues-to-a-vocal-score.ly}
 
 @seealso


@@ -2433,7 +2613,7 @@ Notation Reference:
 @ref{Using music functions}.
 
 Snippets:
 @ref{Using music functions}.
 
 Snippets:

-@rlsr{vocal-music}.
+@rlsr{Vocal music}.

 
 Internals Reference:
 @rinternals{InstrumentSwitch},
 
 Internals Reference:
 @rinternals{InstrumentSwitch},


@@ -2442,10 +2622,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
 @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
 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
 
 
 @node Spoken music


@@ -2453,8 +2633,8 @@ declaring separate @code{CueVoice} contexts and using
 
 @cindex parlato
 @cindex Sprechgesang
 
 @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
 note heads, as demonstrated in @ref{Special note heads}.
 
 @c TODO add "marking-notes-on-spoken-parts" snippet -vv


@@ -2496,7 +2676,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.
 
 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
 
 @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


@@ -2572,6 +2752,9 @@ is described in @ref{Ancient notation}.
 Notation reference:
 @ref{Ancient notation}.
 
 Notation reference:
 @ref{Ancient notation}.
 

+Snippets:
+@rlsr{Vocal music}.
+

 
 @node Setting a chant
 @unnumberedsubsubsec Setting a chant
 
 @node Setting a chant
 @unnumberedsubsubsec Setting a chant


@@ -2650,7 +2833,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
 
 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 |
 
 @lilypond[verbatim,quote,relative=2]
 a4 b c2 |


@@ -2836,7 +3019,7 @@ of the following snippets.
 
 @snippets
 
 
 @snippets
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {chant-or-psalms-notation.ly}
 
 Canticles and other liturgical texts may be set more freely, and
 {chant-or-psalms-notation.ly}
 
 Canticles and other liturgical texts may be set more freely, and


@@ -2845,7 +3028,7 @@ are shown underneath and aligned with the notes.  If so, the notes
 are spaced in accordance with the syllables rather than the notes'
 durations.
 
 are spaced in accordance with the syllables rather than the notes'
 durations.
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {ancient-notation-template----modern-transcription-of-gregorian-music.ly}
 
 @seealso
 {ancient-notation-template----modern-transcription-of-gregorian-music.ly}
 
 @seealso


@@ -3030,14 +3213,15 @@ with a line of text.  This requires a @code{\partial} command at
 the start of the music and @code{\bar "|"} or @code{\bar "||"}
 commands at the end of each line.
 
 the start of the music and @code{\bar "|"} or @code{\bar "||"}
 commands at the end of each line.
 

-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]

 {hymn-template.ly}
 
 
 @node Ancient vocal music
 @subsection Ancient vocal music
 
 {hymn-template.ly}
 
 
 @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
 
 
 @c TODO