X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=912378ab0877cede4d7fa8d02fc0fc68d1a076bc;hb=324ff94afc62c7011b7377f24392f95391ed3b84;hp=a04a8e6ede18177ca332210d899341beda7e2f80;hpb=4ca01b6da8d60b0d8575be05ae974429c91becd5;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index a04a8e6ede..912378ab08 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.19.2"
 
 @node Vocal music
 @section Vocal music
@@ -91,6 +91,7 @@ Notation Reference:
 Snippets:
 @rlsr{Vocal music}.
 
+
 @node Entering lyrics
 @unnumberedsubsubsec Entering lyrics
 
@@ -148,30 +149,11 @@ compile.  Instead, braces should always be surrounded with white space:
 \lyricmode @{ lah lah lah @}
 @end example
 
-@cindex overrides in lyric mode
-@funindex \override in \lyricmode
-
-Similarly, in lyric mode, a period will be included in the
-alphabetic sequence that it follows.  As a consequence, spaces
-must be inserted around the period in @code{\override} commands.
-Do @emph{not} write
-
-@example
-\override Score.LyricText #'font-shape = #'italic
-@end example
-
-@noindent
-but instead use
-
-@example
-\override Score . LyricText #'font-shape = #'italic
-@end example
-
 Punctuation, lyrics with accented characters, characters from
 non-English languages, or special characters (such as the heart
 symbol or slanted quotes), may simply be inserted directly
 into the input file, providing it is saved with UTF-8 encoding.
-For more information, see @ref{Text encoding}.
+For more information, see @ref{Special characters}.
 
 @lilypond[quote,verbatim]
 \relative c'' { d8 c16 a bes8 f e' d c4 }
@@ -218,13 +200,14 @@ Notation Reference:
 @ref{Formatting text},
 @ref{Input modes},
 @ref{Manual syllable durations},
-@ref{Text encoding}.
+@ref{Special characters}.
 
 Internals Reference:
 @rinternals{LyricText}.
 
 Snippets:
-@rlsr{Text}
+@rlsr{Text}.
+
 
 @node Aligning lyrics to a melody
 @unnumberedsubsubsec Aligning lyrics to a melody
@@ -326,11 +309,6 @@ see @ref{Manual syllable durations}.  This technique is also useful
 when setting dialogue over music; for examples showing this, see
 @ref{Dialogue over music}.
 
-When entered in this way the words are left-aligned to the notes
-by default, but may be center-aligned to the notes of a melody by
-specifying an associated voice, if one exists.  For details, see
-@ref{Manual syllable durations}.
-
 @end itemize
 
 @seealso
@@ -339,7 +317,7 @@ Learning Manual:
 
 Notation Reference:
 @ref{Contexts explained},
-@ref{Automatic syllable durations}.
+@ref{Automatic syllable durations},
 @ref{Stanzas},
 @ref{Manual syllable durations},
 @ref{Dialogue over music},
@@ -348,6 +326,7 @@ Notation Reference:
 Internals Reference:
 @rinternals{Lyrics}.
 
+
 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
 
@@ -399,7 +378,7 @@ the named Voice context containing the melody with
 @lilypond[quote,verbatim,relative=2]
 <<
   \new Voice = "melody" {
-    a4 a a a
+    a1 a4. a8 a2
   }
   \new Lyrics \lyricsto "melody" {
     These are the words
@@ -464,6 +443,7 @@ More stanzas can be added by adding more
 @end lilypond
 
 The command @code{\addlyrics} cannot handle polyphonic settings.
+Also, it cannot be used to associate lyrics to a @code{TabVoice}.
 For these cases one should use @code{\lyricsto}.
 
 @subheading Using associatedVoice
@@ -513,6 +493,7 @@ Notation Reference:
 @ref{Keeping contexts alive},
 @ref{Placing lyrics vertically}.
 
+
 @node Manual syllable durations
 @unnumberedsubsubsec Manual syllable durations
 
@@ -523,8 +504,7 @@ completely independently of notes.  In this case do not use
 but with pitches replaced by text -- and the duration of each
 syllable is entered explicitly after the syllable.
 
-By default, syllables will be left-aligned to the corresponding
-musical moment.  Hyphenated lines may be drawn between syllables
+Hyphenated lines may be drawn between syllables
 as usual, but extender lines cannot be drawn when there is no
 associated voice.
 
@@ -533,11 +513,10 @@ Here are two examples:
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
-    \time 3/4
-    c2 e4 g2 f
+    c'2 a f f e e
   }
   \new Lyrics \lyricmode {
-    play1 the4 game4
+    c4. -- a -- f -- f -- e2. -- e
   }
 >>
 @end lilypond
@@ -568,27 +547,22 @@ Here are two examples:
 This technique is useful when writing dialogue over music, see
 @ref{Dialogue over music}.
 
-To center-align syllables on the notes at the corresponding musical
-moments, set @code{associatedVoice} to the name of the Voice context
-containing those notes.  When @code{associatedVoice} is set, both
-double hyphens and double underscores can be used to draw
-hyphenated lines and extenders under melismata correctly.
+To change syllable alignment, simply override the @code{self-alignment-X}
+property:
 
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
     \time 3/4
-    c2 e4 g f g
+    c2 e4 g2 f
   }
   \new Lyrics \lyricmode {
-    \set associatedVoice = #"melody"
-    play2 the4 game2. __
+    \override LyricText.self-alignment-X = #LEFT
+    play1 a4 game4
   }
 >>
 @end lilypond
 
-@c TODO see also feature request 707 - show how to do this with manual durations
-
 @seealso
 Notation Reference:
 @ref{Dialogue over music}.
@@ -611,17 +585,21 @@ spaces between the syllables, you can surround the phrase with
 quotes or use a @code{_} character.  Alternatively, you can use
 the tilde symbol (@code{~}) to get a lyric tie.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[quote,ragged-right,verbatim,relative=2]
 {
-  \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 }
+  { \autoBeamOff
+    r8 b c fis, fis c' b e,
+  }
+  \addlyrics
+  {
+    \override LyricHyphen.minimum-distance = #1.0 % Ensure hyphens are visible
+    Che_in ques -- ta_e_in quel -- l'al -- tr'on -- da
+  }
+  \addlyrics { "Che in" ques -- "ta e in" quel -- l'al -- tr'on -- da }
+  \addlyrics { Che~in ques -- ta~e~in quel -- l'al -- tr'on -- da }
 }
 @end lilypond
 
-
 @seealso
 Internals Reference:
 @rinternals{LyricCombineMusic}.
@@ -636,12 +614,12 @@ Internals Reference:
 @funindex \melisma
 @funindex \melismaEnd
 
-Sometimes, particularly in Medieval music, several notes are to be
-sung on one syllable; such vocalises are called melismata, or
-@rglos{melisma}s.  The syllable to a melisma is usually
+Sometimes, particularly in Medieval and baroque music, several notes are
+sung on one syllable; this is called melisma, see
+@rglos{melisma}.  The syllable to a melisma is usually
 left-aligned with the first note of the melisma.
 
-When a melisma occurs on a syllable other that the last one in a
+When a melisma occurs on a syllable other than the last one in a
 word, that syllable is usually joined to the following one with a
 hyphenated line.  This is indicated by placing a double hyphen,
 @w{@code{--}}, immediately after the syllable.
@@ -664,8 +642,8 @@ together:
   \new Voice = "melody" {
     \time 3/4
     f4 g2 ~ |
-    g4 e2 ~ |
-    e8
+    4 e2 ~ |
+    8
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e __
@@ -691,6 +669,8 @@ entering lyrics:
 >>
 @end lilypond
 
+Note that phrasing slurs do not affect the creation of melismata.
+
 @item
 Notes are considered a melisma if they are manually beamed,
 providing automatic beaming is switched off.  See
@@ -733,9 +713,6 @@ are bracketed between @code{\melisma} and @code{\melismaEnd}.
 >>
 @end lilypond
 
-Note that this method cannot be used to indicate two melismata if
-the first one is immediately followed by another.
-
 @item
 A melisma can be defined entirely in the lyrics by entering a
 single underscore character, @code{_}, for every extra note that has
@@ -766,7 +743,7 @@ without their indicating melismata.  To do this, set
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
-    g8 [ f ] f4 ~ f
+    g8 [ f ] f4 ~ 4
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e e -- le -- i -- son
@@ -794,7 +771,7 @@ should be included in the melisma:
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
-    g8 [ f ] ~ f4 ~ f
+    g8 [ f ] ~ 4 ~ f
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- _ e __ _ _ _
@@ -827,7 +804,6 @@ Internals Reference:
 @rinternals{Tunable context properties}.
 
 @knownissues
-
 Extender lines under melismata are not created automatically; they
 must be inserted manually with a double underscore.
 
@@ -868,7 +844,6 @@ distance between two syllables) and the @code{minimum-length}
 (threshold below which hyphens are removed) properties of
 @code{LyricHyphen}.
 
-
 @seealso
 Internals Reference:
 @rinternals{LyricExtender},
@@ -886,6 +861,7 @@ Internals Reference:
 * Placing syllables horizontally::
 * Lyrics and repeats::
 * Divisi lyrics::
+* Polyphony with shared lyrics::
 @end menu
 
 
@@ -962,7 +938,6 @@ contraltoWords = \lyricmode { Con -- tral -- to words }
 }
 @end lilypond
 
-
 @seealso
 Notation Reference:
 @ref{Placing lyrics vertically}.
@@ -1034,7 +1009,7 @@ follows:
   <<
     \new Lyrics = "lyrics" \with {
       % lyrics above a staff should have this override
-      \override VerticalAxisGroup #'staff-affinity = #DOWN
+      \override VerticalAxisGroup.staff-affinity = #DOWN
     }
     \new Staff {
       \new Voice = "melody" {
@@ -1065,7 +1040,7 @@ is an example of the second method:
     \new Lyrics = "sopranos"
     \new Lyrics = "contraltos" \with {
       % lyrics above a staff should have this override
-      \override VerticalAxisGroup #'staff-affinity = #DOWN
+      \override VerticalAxisGroup.staff-affinity = #DOWN
     }
     \new Staff {
       \new Voice = "contraltos" {
@@ -1087,20 +1062,21 @@ is an example of the second method:
 @end lilypond
 
 Other combinations of lyrics and staves may be generated by
-elaborating these examples, or by examining the
-@rlearning{Vocal ensembles} templates in the Learning Manual.
+elaborating these examples, or by examining the templates in the
+Learning Manual, see @rlearning{Vocal ensembles templates}.
 
 @snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]
-{lyrics-old-spacing-settings.ly}
+{obtaining-2.12-lyrics-spacing-in-newer-versions.ly}
 
 @seealso
 Learning Manual:
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
-@ref{Aligning contexts},
-@ref{Creating contexts}.
+@ref{Context layout order},
+@ref{Creating and referencing contexts}.
+
 
 @node Placing syllables horizontally
 @unnumberedsubsubsec Placing syllables horizontally
@@ -1114,7 +1090,7 @@ To increase the spacing between lyrics, set the
 @lilypond[relative=1,verbatim,quote,ragged-right]
 {
   c c c c
-  \override Lyrics.LyricSpace #'minimum-distance = #1.0
+  \override Lyrics.LyricSpace.minimum-distance = #1.0
   c c c c
 }
 \addlyrics {
@@ -1140,7 +1116,7 @@ To make this change for all lyrics in the score, set the property in the
   \layout {
     \context {
       \Lyrics
-      \override LyricSpace #'minimum-distance = #1.0
+      \override LyricSpace.minimum-distance = #1.0
     }
   }
 }
@@ -1157,7 +1133,7 @@ requires additional calculations.  To speed up processing slightly, this
 feature can be disabled:
 
 @example
-\override Score.PaperColumn #'keep-inside-line = ##f
+\override Score.PaperColumn.keep-inside-line = ##f
 @end example
 
 To make lyrics avoid bar lines as well, use
@@ -1168,23 +1144,11 @@ To make lyrics avoid bar lines as well, use
     \Lyrics
       \consists "Bar_engraver"
       \consists "Separating_line_group_engraver"
-      \override BarLine #'transparent = ##t
+      \hide BarLine
   @}
 @}
 @end example
 
-@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
 
@@ -1335,6 +1299,54 @@ More verses may be added in a similar way:
 }
 @end lilypond
 
+@cindex alignBelowContext
+@funindex alignBelowContext
+
+However, if this construct is embedded within a multi-staved
+context such as a @code{ChoirStaff} the lyrics of the second and
+third verses will appear beneath the bottom staff.
+
+To position them correctly use @code{alignBelowContext}:
+
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+	  a4 a a a
+	  \repeat volta 3 { b4 b b b }
+          c4 c c c
+	}
+      }
+    }
+    \new Lyrics = "firstVerse" \lyricsto "melody" {
+      Not re -- peat -- ed.
+      <<
+        { The first time words.	}
+	\new Lyrics = "secondVerse"
+        \with { alignBelowContext = #"firstVerse" } {
+	  \set associatedVoice = "melody"
+	  Sec -- ond time words.
+	}
+	\new Lyrics = "thirdVerse"
+        \with { alignBelowContext = #"secondVerse" } {
+	  \set associatedVoice = "melody"
+	  The third time words.
+	}
+      >>
+      The end sec -- tion.
+    }
+    \new Voice = "harmony" {
+      \relative c' {
+        f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
+      }
+    }
+  >>
+}
+@end lilypond
+
+
 
 @c TODO positioning a common line of lyrics
 
@@ -1611,6 +1623,106 @@ attaching lyrics to those specific contexts:
 }
 @end lilypond
 
+It is common in choral music to have a voice part split for
+several measures.  The @code{<< @{@dots{}@} \\ @{@dots{}@} >>}
+construct, where the two (or more) musical expressions are
+separated by double backslashes, might seem the proper way to
+set the split voices.  This construct, however, will assign
+@strong{all} the expressions within it to @strong{NEW Voice
+contexts} which will result in @emph{no lyrics} being set for
+them since the lyrics will be set to the original voice context
+-- not, typically, what one wants.  The temporary polyphonic
+passage is the proper construct to use, see section
+@emph{Temporary polyphonic passages} in @ref{Single-staff polyphony}.
+
+
+@node Polyphony with shared lyrics
+@unnumberedsubsubsec Polyphony with shared lyrics
+
+@cindex NullVoice
+@cindex polyphony, shared lyrics
+@cindex lyrics, shared among voices
+@cindex \partcombine and lyrics
+@funindex \partcombine
+
+When two voices with different rhythms share the same lyrics,
+aligning the lyrics to one of the voices may lead to problems in
+the other voice.  For example, the second lyric extender below is
+too short, since the lyrics are aligned only to the top voice:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice = "sopranoVoice" { \voiceOne \soprano }
+  \new Voice { \voiceTwo \alto }
+  \new Lyrics \lyricsto "sopranoVoice" \words
+>>
+@end lilypond
+
+To get the desired result, align the lyrics to a new
+@code{NullVoice} context containing a suitable combination of the
+two voices.  The notes of the @code{NullVoice} context do not
+appear on the printed page, but can be used to align the lyrics
+appropriately:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+aligner = \relative { b'8( c d c) b( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice { \voiceOne \soprano }
+  \new Voice { \voiceTwo \alto }
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+>>
+@end lilypond
+
+This method also can be used with the @code{\partcombine}
+function, which does not allow lyrics on its own:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+aligner = \relative { b'8( c d c) b( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice \partcombine \soprano \alto
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+>>
+@end lilypond
+
+@knownissues
+The @code{\addLyrics} function only works with @code{Voice} lyrics
+and so cannot be used with @code{NullVoice}.
+
+@noindent
+The @code{\partcombine} function is described in
+@ref{Automatic part combining}.
+
+Lastly, this method can be used even when the voices are in
+different staves, and is not limited to only two voices:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+altoOne = \relative { g'2 b8( a b4) }
+altoTwo = \relative { d'2 g4( fis8 g) }
+aligner = \relative { b'8( c d c) d( d d d) }
+words = \lyricmode { la __ la __ }
+
+\new ChoirStaff <<
+  \new Staff \soprano
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+  \new Staff \partcombine \altoOne \altoTwo
+>>
+@end lilypond
 
 @node Stanzas
 @subsection Stanzas
@@ -1784,7 +1896,7 @@ changed:
 <<
   \new Voice = melody \relative c' {
     f4 \appoggiatura a32 b4
-    \grace { f16[ a16] } b2
+    \grace { f16 a16 } b2
     \afterGrace b2 { f16[ a16] }
     \appoggiatura a32 b4
     \acciaccatura a8 b4
@@ -1813,7 +1925,7 @@ block:
 @lilypond[verbatim,ragged-right,quote]
 <<
   \new Voice = melody \relative c' {
-    \grace { c16[( d e f] }
+    \grace { c16( d e f }
     g1) f
   }
   \new Lyrics \with { includeGraceNotes = ##t }
@@ -1840,9 +1952,9 @@ within the lyrics by setting the @code{associatedVoice} property:
     <<
       \new Voice = "alternative" {
         \voiceOne
-        \times 2/3 {
+        \tuplet 3/2 {
           % show associations clearly.
-          \override NoteColumn #'force-hshift = #-3
+          \override NoteColumn.force-hshift = #-3
           f8 f g
         }
       }
@@ -1953,7 +2065,7 @@ output in LilyPond.
 
 @lilypond[ragged-right,quote,verbatim]
 melody = \relative c' {
-  c c c c | d d d d
+  c4 c c c | d d d d
 }
 
 text = \lyricmode {
@@ -1972,7 +2084,7 @@ text = \lyricmode {
 \markup {
   \fill-line {
     \hspace #0.1 % moves the column off the left margin;
-        % can be removed if space on the page is tight
+     % can be removed if space on the page is tight
      \column {
       \line { \bold "2."
         \column {
@@ -1980,7 +2092,7 @@ text = \lyricmode {
           "It has two lines."
         }
       }
-      \hspace #0.1 % adds vertical spacing between verses
+      \combine \null \vspace #0.1 % adds vertical spacing between verses
       \line { \bold "3."
         \column {
           "This is verse three."
@@ -1988,17 +2100,15 @@ text = \lyricmode {
         }
       }
     }
-    \hspace #0.1  % adds horizontal spacing between columns;
-        % if they are still too close, add more " " pairs
-        % until the result looks good
-     \column {
+    \hspace #0.1 % adds horizontal spacing between columns;
+    \column {
       \line { \bold "4."
         \column {
           "This is verse four."
           "It has two lines."
         }
       }
-      \hspace #0.1 % adds vertical spacing between verses
+      \combine \null \vspace #0.1 % adds vertical spacing between verses
       \line { \bold "5."
         \column {
           "This is verse five."
@@ -2007,7 +2117,7 @@ text = \lyricmode {
       }
     }
   \hspace #0.1 % gives some extra space on the right margin;
-      % can be removed if page space is tight
+  % can be removed if page space is tight
   }
 }
 @end lilypond
@@ -2087,6 +2197,7 @@ Notation Reference:
 Snippets:
 @rlsr{Vocal music}.
 
+
 @node Lead sheets
 @unnumberedsubsubsec Lead sheets
 
@@ -2126,8 +2237,8 @@ etc.
 Choral music is usually notated on two, three or four staves within
 a @code{ChoirStaff} group.  Accompaniment, if required, is placed
 beneath in a @code{PianoStaff} group, which is usually reduced in
-size for @emph{a capella} choral works.  The notes for each vocal
-part are placed in a @code{Voice} context, with each staff
+size for rehearsal of @emph{a cappella} choral works.  The notes for
+each vocal part are placed in a @code{Voice} context, with each staff
 being given either a single vocal part (i.e., one @code{Voice}) or
 a pair of vocal parts (i.e., two @code{Voice}s).
 
@@ -2142,11 +2253,13 @@ Several common topics in choral music are described fully elsewhere:
 @item
 An introduction to creating an SATB vocal score can be found in
 the Learning Manual, see @rlearning{Four-part SATB vocal score}.
+There is also a built-in template which simplifies the entry of
+SATB vocal music, see @rlearning{Built-in templates}.
 
 @item
 Several templates suitable for various styles of choral music can
 also be found in the Learning Manual, see
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 @item
 For information about @code{ChoirStaff} and @code{PianoStaff} see
@@ -2162,6 +2275,11 @@ the higher part will be directed up and those of the lower part
 down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
 @ref{Single-staff polyphony}.
 
+@item
+When a vocal part temporarily splits, you should use
+@emph{Temporary polyphonic passages}
+(see @ref{Single-staff polyphony}).
+
 @end itemize
 
 @predefined
@@ -2172,7 +2290,7 @@ down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
 @seealso
 Learning Manual:
 @rlearning{Four-part SATB vocal score},
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Context layout order},
@@ -2188,6 +2306,7 @@ Internals Reference:
 @rinternals{Lyrics},
 @rinternals{PianoStaff}.
 
+
 @node Score layouts for choral
 @unnumberedsubsubsec Score layouts for choral
 
@@ -2251,8 +2370,8 @@ above their respective staves, as shown here:
   \layout {
     \context {
       \Score
-      \override DynamicText #'direction = #UP
-      \override DynamicLineSpanner #'direction = #UP
+      \override DynamicText.direction = #UP
+      \override DynamicLineSpanner.direction = #UP
     }
   }
 }
@@ -2270,7 +2389,7 @@ Notation Reference:
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
-@ref{Using an extra voice for breaks},
+@ref{Explicit breaks},
 @ref{Vertical spacing}.
 
 Internals Reference:
@@ -2372,10 +2491,10 @@ For details of other page formatting properties, see
 @ref{Page layout}.
 
 @item
-Dialogue cues and stage directions can be inserted with markup.
-See @ref{Text}.  Extensive stage directions can be inserted with
-a section of stand-alone markup between two @code{\score} blocks.
-See @ref{Separate text}.
+Dialogue cues, stage directions and footnotes can be inserted, see
+@ref{Creating footnotes} and @ref{Text}.  Extensive stage directions
+can also be added with a section of stand-alone markups between two
+@code{\score} blocks, see @ref{Separate text}.
 
 @end itemize
 
@@ -2386,6 +2505,7 @@ Musical Glossary:
 @rglos{transposing instrument}.
 
 Notation Reference:
+@ref{Creating footnotes},
 @ref{Grouping staves},
 @ref{Hiding staves},
 @ref{Instrument transpositions},
@@ -2455,14 +2575,16 @@ c c c
 Alternatively, if there are many character changes, it may be
 easier to set up @qq{instrument} definitions for each character at
 the top level so that @code{\instrumentSwitch} can be used to
-indicate each change.
+indicate each change.  As notes for vocal parts are usually entered
+at sounding pitch no instrument transposition is required, even
+when, as here, the tenor line is printed an octave higher.
 
 @lilypond[quote,verbatim]
 \addInstrumentDefinition #"kaspar"
-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
+  #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
      (shortInstrumentName . "Kas.")
      (clefGlyph . "clefs.G")
-     (clefOctavation . -7)
+     (clefTransposition . -7)
      (middleCPosition . 1)
      (clefPosition . -2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
@@ -2472,11 +2594,11 @@ indicate each change.
   #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
      (shortInstrumentName . "Mel.")
      (clefGlyph . "clefs.F")
-     (clefOctavation . 0)
+     (clefTransposition . 0)
      (middleCPosition . 6)
      (clefPosition . 2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
-     (midiInstrument . "voice aahs"))
+     (midiInstrument . "choir aahs"))
 
 \relative c' {
   \instrumentSwitch "kaspar"
@@ -2498,6 +2620,7 @@ Notation Reference:
 Extending LilyPond:
 @rextend{Markup construction in Scheme}.
 
+
 @node Musical cues
 @unnumberedsubsubsec Musical cues
 
@@ -2529,7 +2652,10 @@ pianoRH = \relative c'' {
   c4. g8
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
-  s1*0^\markup { \right-align { \tiny "Flute" } }
+  \new CueVoice {
+    \override InstrumentSwitch.self-alignment-X = #RIGHT
+    \set instrumentCueName = "Flute"
+  }
   \cueDuring "flute" #UP { g4 bes4 }
 }
 pianoLH = \relative c { c4 <c' e> e, <g c> }
@@ -2568,7 +2694,11 @@ clarinet = \relative c' {
 pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff
-  s1*0_\markup { \right-align { \tiny "Clar." } }
+  \new CueVoice {
+    \override InstrumentSwitch.self-alignment-X = #RIGHT
+    \override InstrumentSwitch.direction = #DOWN
+    \set instrumentCueName = "Clar."
+  }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }
@@ -2700,8 +2830,8 @@ dialogue = \lyricmode {
 \score {
   <<
     \new Lyrics \with {
-      \override LyricText #'font-shape = #'italic
-      \override LyricText #'self-alignment-X = #LEFT
+      \override LyricText.font-shape = #'italic
+      \override LyricText.self-alignment-X = #LEFT
     }
     { \dialogue }
     \new Staff {
@@ -2767,7 +2897,7 @@ Chants often use quarter notes without stems to indicate the pitch,
 with the rhythm being taken from the spoken rhythm of the words.
 
 @lilypond[verbatim,quote]
-stemOff = { \override Staff.Stem #'transparent = ##t }
+stemOff = { \hide Staff.Stem }
 
 \relative c' {
   \stemOff
@@ -2801,7 +2931,7 @@ all staves remove the bar line engraver completely:
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
+      \remove "Bar_engraver"
     }
   }
 }
@@ -2813,7 +2943,7 @@ Bar lines can also be removed on a staff-by-staff basis:
 \score {
   \new ChoirStaff <<
     \new Staff
-    \with { \remove Bar_engraver } {
+    \with { \remove "Bar_engraver" } {
       \relative c'' {
         a4 b c2 |
         a4 b c2 |
@@ -2858,9 +2988,9 @@ a4 b c2
 \bar "'"
 a4 b c2
 a4 b c2
-\bar ":"
+\bar ";"
 a4 b c2
-\bar "dashed"
+\bar "!"
 a4 b c2
 \bar "||"
 @end lilypond
@@ -2871,23 +3001,23 @@ modern.  This uses a modified @code{\breathe} mark:
 
 @lilypond[verbatim,quote]
 divisioMinima = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-minima
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-minima
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 divisioMaior = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maior
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-maior
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 divisioMaxima = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maxima
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-maxima
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 finalis = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::finalis
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::finalis
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 
@@ -2905,7 +3035,7 @@ finalis = {
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
+      \remove "Bar_engraver"
     }
   }
 }
@@ -2925,9 +3055,9 @@ Chants usually omit the time signature and often omit the clef too.
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
-      \remove Time_signature_engraver
-      \remove Clef_engraver
+      \remove "Bar_engraver"
+      \remove "Time_signature_engraver"
+      \remove "Clef_engraver"
     }
   }
 }
@@ -3001,8 +3131,7 @@ global = {
       \layout {
         \context {
           \Score
-          \override SpacingSpanner
-          #'base-shortest-duration = #(ly:make-moment 1 2)
+          \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1/2)
         }
         \context {
           \Staff
@@ -3034,7 +3163,7 @@ durations.
 @seealso
 Learning Manual:
 @rlearning{Visibility and color of objects},
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Ancient notation},
@@ -3193,11 +3322,12 @@ The use of markup to center text, and arrange lines in columns is
 described in @ref{Formatting text}.
 
 Most of these elements are shown in one or other of the two verses
-in the template, see @qq{Psalms} in @rlearning{Vocal ensembles}.
+in the template, see @rlearning{Psalms}.
 
 @seealso
 Learning Manual:
-@rlearning{Vocal ensembles}.
+@rlearning{Psalms},
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Fonts},