Issue 4075: Doc: Correct the instrumentTransposition setting in NR 2.1.6

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

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index a38092baa7e9ef03747b996ad472e4ca1d8fc032..912378ab0877cede4d7fa8d02fc0fc68d1a076bc 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
     Guide, node Updating translation committishes..
 @end ignore
 

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

 
 @node Vocal music
 @section Vocal music
 
 @node Vocal music
 @section Vocal music


@@ -149,25 +149,6 @@ compile.  Instead, braces should always be surrounded with white space:
 \lyricmode @{ lah lah lah @}
 @end example
 
 \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
 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


@@ -328,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 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
 @end itemize
 
 @seealso


@@ -402,7 +378,7 @@ the named Voice context containing the melody with
 @lilypond[quote,verbatim,relative=2]
 <<
   \new Voice = "melody" {
 @lilypond[quote,verbatim,relative=2]
 <<
   \new Voice = "melody" {

-    a4 a a a
+    a1 a4. a8 a2

   }
   \new Lyrics \lyricsto "melody" {
     These are the words
   }
   \new Lyrics \lyricsto "melody" {
     These are the words


@@ -467,6 +443,7 @@ More stanzas can be added by adding more
 @end lilypond
 
 The command @code{\addlyrics} cannot handle polyphonic settings.
 @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
 For these cases one should use @code{\lyricsto}.
 
 @subheading Using associatedVoice


@@ -527,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.
 
 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.
 
 as usual, but extender lines cannot be drawn when there is no
 associated voice.
 


@@ -537,11 +513,10 @@ Here are two examples:
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
 @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 {
   }
   \new Lyrics \lyricmode {

-    play1 the4 game4
+    c4. -- a -- f -- f -- e2. -- e

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


@@ -572,27 +547,22 @@ Here are two examples:
 This technique is useful when writing dialogue over music, see
 @ref{Dialogue over music}.
 
 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
 
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
     \time 3/4

-    c2 e4 g f g
+    c2 e4 g2 f

   }
   \new Lyrics \lyricmode {
   }
   \new Lyrics \lyricmode {

-    \set associatedVoice = #"melody"
-    play2 the4 game2. __
+    \override LyricText.self-alignment-X = #LEFT
+    play1 a4 game4

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

-@c TODO see also feature request 707 - show how to do this with manual durations
-

 @seealso
 Notation Reference:
 @ref{Dialogue over music}.
 @seealso
 Notation Reference:
 @ref{Dialogue over music}.


@@ -615,11 +585,16 @@ 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.
 
 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]

 {
 {

-  \relative c'' { \autoBeamOff
-    r8 b c fis, fis c' b e, }
-  \addlyrics { Che_in ques -- ta_e_in quel -- l'al -- tr'on -- da }
+  { \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 }
 }
   \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 }
 }


@@ -639,12 +614,12 @@ Internals Reference:
 @funindex \melisma
 @funindex \melismaEnd
 
 @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.
 
 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.
 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.


@@ -667,8 +642,8 @@ together:
   \new Voice = "melody" {
     \time 3/4
     f4 g2 ~ |
   \new Voice = "melody" {
     \time 3/4
     f4 g2 ~ |

-    g4 e2 ~ |
-    e8
+    4 e2 ~ |
+    8

   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e __
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e __


@@ -768,7 +743,7 @@ without their indicating melismata.  To do this, set
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
     \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
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e e -- le -- i -- son


@@ -796,7 +771,7 @@ should be included in the melisma:
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )

-    g8 [ f ] ~ f4 ~ f
+    g8 [ f ] ~ 4 ~ f

   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- _ e __ _ _ _
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- _ e __ _ _ _


@@ -886,6 +861,7 @@ Internals Reference:
 * Placing syllables horizontally::
 * Lyrics and repeats::
 * Divisi lyrics::
 * Placing syllables horizontally::
 * Lyrics and repeats::
 * Divisi lyrics::

+* Polyphony with shared lyrics::

 @end menu
 
 
 @end menu
 
 


@@ -1033,7 +1009,7 @@ follows:
   <<
     \new Lyrics = "lyrics" \with {
       % lyrics above a staff should have this override
   <<
     \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" {
     }
     \new Staff {
       \new Voice = "melody" {


@@ -1064,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
     \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" {
     }
     \new Staff {
       \new Voice = "contraltos" {


@@ -1086,8 +1062,8 @@ is an example of the second 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
-@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]
 
 @snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]


@@ -1095,11 +1071,11 @@ elaborating these examples, or by examining the
 
 @seealso
 Learning Manual:
 
 @seealso
 Learning Manual:

-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.

 
 Notation Reference:
 @ref{Context layout order},
 
 Notation Reference:
 @ref{Context layout order},

-@ref{Creating contexts}.
+@ref{Creating and referencing contexts}.

 
 
 @node Placing syllables horizontally
 
 
 @node 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
 @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 {
   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
   \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
 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
 @end example
 
 To make lyrics avoid bar lines as well, use


@@ -1168,7 +1144,7 @@ To make lyrics avoid bar lines as well, use
     \Lyrics
       \consists "Bar_engraver"
       \consists "Separating_line_group_engraver"
     \Lyrics
       \consists "Bar_engraver"
       \consists "Separating_line_group_engraver"

-      \override BarLine #'transparent = ##t
+      \hide BarLine

   @}
 @}
 @end example
   @}
 @}
 @end example


@@ -1323,6 +1299,54 @@ More verses may be added in a similar way:
 }
 @end lilypond
 
 }
 @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
 
 
 @c TODO positioning a common line of lyrics
 


@@ -1599,6 +1623,106 @@ attaching lyrics to those specific contexts:
 }
 @end lilypond
 
 }
 @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
 
 @node Stanzas
 @subsection Stanzas


@@ -1772,7 +1896,7 @@ changed:
 <<
   \new Voice = melody \relative c' {
     f4 \appoggiatura a32 b4
 <<
   \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
     \afterGrace b2 { f16[ a16] }
     \appoggiatura a32 b4
     \acciaccatura a8 b4


@@ -1801,7 +1925,7 @@ block:
 @lilypond[verbatim,ragged-right,quote]
 <<
   \new Voice = melody \relative c' {
 @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 }
     g1) f
   }
   \new Lyrics \with { includeGraceNotes = ##t }


@@ -1828,9 +1952,9 @@ within the lyrics by setting the @code{associatedVoice} property:
     <<
       \new Voice = "alternative" {
         \voiceOne
     <<
       \new Voice = "alternative" {
         \voiceOne

-        \times 2/3 {
+        \tuplet 3/2 {

           % show associations clearly.
           % show associations clearly.

-          \override NoteColumn #'force-hshift = #-3
+          \override NoteColumn.force-hshift = #-3

           f8 f g
         }
       }
           f8 f g
         }
       }


@@ -1968,7 +2092,7 @@ text = \lyricmode {
           "It has two lines."
         }
       }
           "It has two lines."
         }
       }

-      \vspace #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."
       \line { \bold "3."
         \column {
           "This is verse three."


@@ -1984,7 +2108,7 @@ text = \lyricmode {
           "It has two lines."
         }
       }
           "It has two lines."
         }
       }

-      \vspace #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."
       \line { \bold "5."
         \column {
           "This is verse five."


@@ -2113,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
 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).
 
 being given either a single vocal part (i.e., one @code{Voice}) or
 a pair of vocal parts (i.e., two @code{Voice}s).
 


@@ -2129,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}.
 @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
 
 @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
 
 @item
 For information about @code{ChoirStaff} and @code{PianoStaff} see


@@ -2149,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}.
 
 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
 @end itemize
 
 @predefined


@@ -2159,7 +2290,7 @@ down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
 @seealso
 Learning Manual:
 @rlearning{Four-part SATB vocal score},
 @seealso
 Learning Manual:
 @rlearning{Four-part SATB vocal score},

-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.

 
 Notation Reference:
 @ref{Context layout order},
 
 Notation Reference:
 @ref{Context layout order},


@@ -2239,8 +2370,8 @@ above their respective staves, as shown here:
   \layout {
     \context {
       \Score
   \layout {
     \context {
       \Score

-      \override DynamicText #'direction = #UP
-      \override DynamicLineSpanner #'direction = #UP
+      \override DynamicText.direction = #UP
+      \override DynamicLineSpanner.direction = #UP

     }
   }
 }
     }
   }
 }


@@ -2258,7 +2389,7 @@ Notation Reference:
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
 @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:
 @ref{Vertical spacing}.
 
 Internals Reference:


@@ -2444,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
 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"
 
 @lilypond[quote,verbatim]
 \addInstrumentDefinition #"kaspar"

-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
+  #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))

      (shortInstrumentName . "Kas.")
      (clefGlyph . "clefs.G")
      (shortInstrumentName . "Kas.")
      (clefGlyph . "clefs.G")

-     (clefOctavation . -7)
+     (clefTransposition . -7)

      (middleCPosition . 1)
      (clefPosition . -2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
      (middleCPosition . 1)
      (clefPosition . -2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))


@@ -2461,11 +2594,11 @@ indicate each change.
   #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
      (shortInstrumentName . "Mel.")
      (clefGlyph . "clefs.F")
   #`((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"))
      (middleCPosition . 6)
      (clefPosition . 2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))

-     (midiInstrument . "voice aahs"))
+     (midiInstrument . "choir aahs"))

 
 \relative c' {
   \instrumentSwitch "kaspar"
 
 \relative c' {
   \instrumentSwitch "kaspar"


@@ -2520,7 +2653,7 @@ pianoRH = \relative c'' {
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
   \new CueVoice {
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
   \new CueVoice {

-    \override InstrumentSwitch #'self-alignment-X = #RIGHT
+    \override InstrumentSwitch.self-alignment-X = #RIGHT

     \set instrumentCueName = "Flute"
   }
   \cueDuring "flute" #UP { g4 bes4 }
     \set instrumentCueName = "Flute"
   }
   \cueDuring "flute" #UP { g4 bes4 }


@@ -2562,8 +2695,8 @@ pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff
   \new CueVoice {
   \transposition c'
   % position name of cue-ing instrument below the staff
   \new CueVoice {

-    \override InstrumentSwitch #'self-alignment-X = #RIGHT
-    \override InstrumentSwitch #'direction = #DOWN
+    \override InstrumentSwitch.self-alignment-X = #RIGHT
+    \override InstrumentSwitch.direction = #DOWN

     \set instrumentCueName = "Clar."
   }
   \cueDuring "clarinet" #DOWN { c4. g8 }
     \set instrumentCueName = "Clar."
   }
   \cueDuring "clarinet" #DOWN { c4. g8 }


@@ -2697,8 +2830,8 @@ dialogue = \lyricmode {
 \score {
   <<
     \new Lyrics \with {
 \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 {
     }
     { \dialogue }
     \new Staff {


@@ -2764,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]
 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
 
 \relative c' {
   \stemOff


@@ -2798,7 +2931,7 @@ all staves remove the bar line engraver completely:
   \layout {
     \context {
       \Staff
   \layout {
     \context {
       \Staff

-      \remove Bar_engraver
+      \remove "Bar_engraver"

     }
   }
 }
     }
   }
 }


@@ -2810,7 +2943,7 @@ Bar lines can also be removed on a staff-by-staff basis:
 \score {
   \new ChoirStaff <<
     \new Staff
 \score {
   \new ChoirStaff <<
     \new Staff

-    \with { \remove Bar_engraver } {
+    \with { \remove "Bar_engraver" } {

       \relative c'' {
         a4 b c2 |
         a4 b c2 |
       \relative c'' {
         a4 b c2 |
         a4 b c2 |


@@ -2855,9 +2988,9 @@ a4 b c2
 \bar "'"
 a4 b c2
 a4 b c2
 \bar "'"
 a4 b c2
 a4 b c2

-\bar ":"
+\bar ";"

 a4 b c2
 a4 b c2

-\bar "dashed"
+\bar "!"

 a4 b c2
 \bar "||"
 @end lilypond
 a4 b c2
 \bar "||"
 @end lilypond


@@ -2868,23 +3001,23 @@ modern.  This uses a modified @code{\breathe} mark:
 
 @lilypond[verbatim,quote]
 divisioMinima = {
 
 @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 = {
   \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 = {
   \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 = {
   \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
 }
 
   \breathe
 }
 


@@ -2902,7 +3035,7 @@ finalis = {
   \layout {
     \context {
       \Staff
   \layout {
     \context {
       \Staff

-      \remove Bar_engraver
+      \remove "Bar_engraver"

     }
   }
 }
     }
   }
 }


@@ -2922,9 +3055,9 @@ Chants usually omit the time signature and often omit the clef too.
   \layout {
     \context {
       \Staff
   \layout {
     \context {
       \Staff

-      \remove Bar_engraver
-      \remove Time_signature_engraver
-      \remove Clef_engraver
+      \remove "Bar_engraver"
+      \remove "Time_signature_engraver"
+      \remove "Clef_engraver"

     }
   }
 }
     }
   }
 }


@@ -2998,8 +3131,7 @@ global = {
       \layout {
         \context {
           \Score
       \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
         }
         \context {
           \Staff


@@ -3031,7 +3163,7 @@ durations.
 @seealso
 Learning Manual:
 @rlearning{Visibility and color of objects},
 @seealso
 Learning Manual:
 @rlearning{Visibility and color of objects},

-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.

 
 Notation Reference:
 @ref{Ancient notation},
 
 Notation Reference:
 @ref{Ancient notation},


@@ -3190,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
 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:
 
 @seealso
 Learning Manual:

-@rlearning{Vocal ensembles}.
+@rlearning{Psalms},
+@rlearning{Vocal ensembles templates}.

 
 Notation Reference:
 @ref{Fonts},
 
 Notation Reference:
 @ref{Fonts},