PO: update template.

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

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 05d76e698d1da5a8bf7dbc6c3f0984244875a03b..118a58e4822b7ca9959377fbfc1550f4694e438f 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.13.36"
+@c \version "2.19.21"

 
 @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,14 +80,25 @@ 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}.
 
 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


@@ -133,33 +149,14 @@ 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
 into the input file, providing it is saved with UTF-8 encoding.
 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]
 
 @lilypond[quote,verbatim]

-\relative c'' { d8 c16 a bes8 f e' d c4 }
+\relative { d''8 c16 a bes8 f ees' d c4 }

 \addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
 @end lilypond
 
 \addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
 @end lilypond
 


@@ -168,7 +165,7 @@ with a backslash character and the whole syllable has to be
 enclosed between additional quotes.  For example,
 
 @lilypond[quote,verbatim]
 enclosed between additional quotes.  For example,
 
 @lilypond[quote,verbatim]

-\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
+\relative { \time 3/4 e'4 e4. e8 d4 e d c2. }

 \addlyrics { "\"I" am so lone -- "ly,\"" said she }
 @end lilypond
 
 \addlyrics { "\"I" am so lone -- "ly,\"" said she }
 @end lilypond
 


@@ -183,6 +180,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}.


@@ -190,12 +197,17 @@ 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{Special characters}.

 
 Internals Reference:
 @rinternals{LyricText}.
 
 
 Internals Reference:
 @rinternals{LyricText}.
 

+Snippets:
+@rlsr{Text}.
+

 
 @node Aligning lyrics to a melody
 @unnumberedsubsubsec Aligning lyrics to a melody
 
 @node Aligning lyrics to a melody
 @unnumberedsubsubsec Aligning lyrics to a melody


@@ -206,13 +218,22 @@ Internals Reference:
 @funindex \addlyrics
 @funindex \lyricsto
 
 @funindex \addlyrics
 @funindex \lyricsto
 

-Lyrics are printed by interpreting them in the context called
-@code{Lyrics}, see @ref{Contexts explained}.
+Lyrics are interpreted in @code{\lyricmode} and printed in a
+@code{Lyrics} context, see @ref{Contexts explained}.

 
 @example
 \new Lyrics \lyricmode @{ @dots{} @}
 @end example
 
 
 @example
 \new Lyrics \lyricmode @{ @dots{} @}
 @end example
 

+Two variants of @code{\lyricmode} additionally set an associated
+context used to synchronise the lyric syllables to music.  The more
+convenient @code{\addlyrics} immediately follows the musical content
+of the Voice context with which it should be synchronised, implicitly
+creating a Lyrics context of its own.  The more versatile
+@code{\lyricsto} requires both specifying the associated Voice context
+by name and explicitly creating a containing Lyrics context.  For
+details see @ref{Automatic syllable durations}.
+

 Lyrics can be aligned with melodies in two main ways:
 
 @itemize
 Lyrics can be aligned with melodies in two main ways:
 
 @itemize


@@ -228,13 +249,13 @@ For more details, see @ref{Automatic syllable durations}.
 <<
   \new Staff <<
     \time 2/4
 <<
   \new Staff <<
     \time 2/4

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

       \voiceOne
       \voiceOne

-      c4 b8. a16 g4. r8 a4 ( b ) c2
+      c''4 b8. a16 g4. r8 a4 ( b ) c2

     }
     }

-    \new Voice = "two" \relative c' {
+    \new Voice = "two" \relative {

       \voiceTwo
       \voiceTwo

-       s2 s4. f8 e4 d c2
+       s2 s4. f'8 e4 d c2

     }
   >>
 
     }
   >>
 


@@ -268,9 +289,9 @@ and entered with @code{\lyricmode}.
 
 @lilypond[quote,ragged-right,verbatim]
 <<
 
 @lilypond[quote,ragged-right,verbatim]
 <<

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

     \time 2/4
     \time 2/4

-    c4 b8. a16 g4. f8 e4 d c2
+    c''4 b8. a16 g4. f8 e4 d c2

   }
 
 % uses previous explicit duration of 2;
   }
 
 % uses previous explicit duration of 2;


@@ -297,20 +318,24 @@ 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
 Learning Manual:
 @rlearning{Aligning lyrics to a melody}.
 
 @end itemize
 
 @seealso
 Learning Manual:
 @rlearning{Aligning lyrics to a melody}.
 

+Notation Reference:
+@ref{Contexts explained},
+@ref{Automatic syllable durations},
+@ref{Stanzas},
+@ref{Manual syllable durations},
+@ref{Dialogue over music},
+@ref{Manual syllable durations}.
+

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

+

 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
 
 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
 


@@ -359,10 +384,10 @@ Lyrics can be aligned under a melody automatically by specifying
 the named Voice context containing the melody with
 @code{\lyricsto}:
 
 the named Voice context containing the melody with
 @code{\lyricsto}:
 

-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]

 <<
 <<

-  \new Voice = "melody" {
-    a4 a a a
+  \new Voice = "melody" \relative {
+    a'1 a4. a8 a2

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


@@ -376,9 +401,9 @@ context, which must already exist.  Therefore normally the
 @code{Voice} context is specified first, followed by the
 @code{Lyrics} context.  The lyrics themselves follow the
 @code{\lyricsto} command.  The @code{\lyricsto} command
 @code{Voice} context is specified first, followed by the
 @code{Lyrics} context.  The lyrics themselves follow the
 @code{\lyricsto} command.  The @code{\lyricsto} command

-invokes lyric mode automatically, so the @code{\lyricmode} keyword
-may be omitted.  By default, the lyrics are placed underneath the
-notes.  For other placements, see @ref{Placing lyrics vertically}.
+invokes lyric mode automatically.  By default, the lyrics are placed
+underneath the notes.  For other placements, see
+@ref{Placing lyrics vertically}.

 
 @subheading Using @code{\addlyrics}
 
 
 @subheading Using @code{\addlyrics}
 


@@ -407,7 +432,7 @@ Here is an example,
 @lilypond[verbatim,quote]
 {
   \time 3/4
 @lilypond[verbatim,quote]
 {
   \time 3/4

-  \relative c' { c2 e4 g2. }
+  \relative { c'2 e4 g2. }

   \addlyrics { play the game }
 }
 @end lilypond
   \addlyrics { play the game }
 }
 @end lilypond


@@ -416,15 +441,18 @@ More stanzas can be added by adding more
 @code{\addlyrics} sections:
 
 
 @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 }
+@lilypond[ragged-right,verbatim,quote]
+{
+  \time 3/4
+  \relative { c'2 e4 g2. }
+  \addlyrics { play the game }
+  \addlyrics { speel het spel }
+  \addlyrics { joue le jeu }
+}

 @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


@@ -449,13 +477,13 @@ Here is an example demonstrating its use:
 <<
   \new Staff <<
     \time 2/4
 <<
   \new Staff <<
     \time 2/4

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

       \voiceOne
       \voiceOne

-      c4 b8. a16 g4. r8 a4 ( b ) c2
+      c''4 b8. a16 g4. r8 a4 ( b ) c2

     }
     }

-    \new Voice = "two" \relative c' {
+    \new Voice = "two" \relative {

       \voiceTwo
       \voiceTwo

-       s2 s4. f8 e8 d4. c2
+       s2 s4. f'8 e8 d4. c2

     }
   >>
 % takes durations and alignment from notes in "one" initially
     }
   >>
 % takes durations and alignment from notes in "one" initially


@@ -471,7 +499,9 @@ Here is an example demonstrating its use:
 @seealso
 Notation Reference:
 @ref{Extenders and hyphens},
 @seealso
 Notation Reference:
 @ref{Extenders and hyphens},

-@ref{Keeping contexts alive}.
+@ref{Keeping contexts alive},
+@ref{Placing lyrics vertically}.
+

 
 @node Manual syllable durations
 @unnumberedsubsubsec Manual syllable durations
 
 @node Manual syllable durations
 @unnumberedsubsubsec Manual syllable durations


@@ -483,21 +513,19 @@ completely independently of notes.  In this case do not use
 but with pitches replaced by text -- and the duration of each
 syllable is entered explicitly after the syllable.
 
 but with pitches replaced by text -- and the duration of each
 syllable is entered explicitly after the syllable.
 

-By default, syllables will be left-aligned to the corresponding
-musical moment.  Hyphenated lines may be drawn between syllables
+Hyphenated lines may be drawn between syllables

 as usual, but extender lines cannot be drawn when there is no
 associated voice.
 
 Here are two examples:
 
 as usual, but extender lines cannot be drawn when there is no
 associated voice.
 
 Here are two examples:
 

-@lilypond[relative=1,verbatim,quote]
+@lilypond[verbatim,quote]

 <<
 <<

-  \new Voice = "melody" {
-    \time 3/4
-    c2 e4 g2 f
+  \new Voice = "melody" \relative {
+    c''2 a f f e e

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

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

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


@@ -506,8 +534,8 @@ Here are two examples:
 @lilypond[quote,verbatim,ragged-right]
 <<
   \new Staff {
 @lilypond[quote,verbatim,ragged-right]
 <<
   \new Staff {

-    \relative c'' {
-      c2 c2
+    \relative {
+      c''2 c2

       d1
     }
   }
       d1
     }
   }


@@ -517,8 +545,8 @@ Here are two examples:
     }
   }
   \new Staff {
     }
   }
   \new Staff {

-    \relative c' {
-      c8 c c c c c c c
+    \relative {
+      c'8 c c c c c c c

       c8 c c c c c c c
     }
   }
       c8 c c c c c c c
     }
   }


@@ -528,27 +556,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]
+@lilypond[verbatim,quote]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \time 3/4

-    c2 e4 g f g
+    c'2 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}.


@@ -569,20 +592,24 @@ 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]
+{
+  \relative {
+    \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
 
 @end lilypond
 

-

 @seealso
 Internals Reference:
 @rinternals{LyricCombineMusic}.
 @seealso
 Internals Reference:
 @rinternals{LyricCombineMusic}.


@@ -597,15 +624,15 @@ 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,
 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


@@ -620,16 +647,16 @@ There are five ways in which melismata can be indicated:
 Melismata are created automatically over notes which are tied
 together:
 
 Melismata are created automatically over notes which are tied
 together:
 

-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \time 3/4

-    f4 g2 ~ |
-    g4 e2 ~ |
-    e8
+    f''4 g2 ~ |
+    4 e2 ~ |
+    8

   }
   \new Lyrics \lyricsto "melody" {
   }
   \new Lyrics \lyricsto "melody" {

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

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


@@ -639,34 +666,36 @@ Melismata can be created automatically from the music by placing
 slurs over the notes of each melisma.  This is the usual way of
 entering lyrics:
 
 slurs over the notes of each melisma.  This is the usual way of
 entering lyrics:
 

-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \time 3/4

-    f4 g8 ( f e f )
+    f''4 g8 ( f e f )

     e8 ( d e2 )
   }
   \new Lyrics \lyricsto "melody" {
     e8 ( d e2 )
   }
   \new Lyrics \lyricsto "melody" {

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

   }
 >>
 @end lilypond
 
   }
 >>
 @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
 @ref{Setting automatic beam behavior}.
 
 @item
 Notes are considered a melisma if they are manually beamed,
 providing automatic beaming is switched off.  See
 @ref{Setting automatic beam behavior}.
 

-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \autoBeamOff
     \time 3/4
     \autoBeamOff

-    f4 g8[ f e f]
+    f''4 g8[ f e f]

     e2.
   }
   \new Lyrics \lyricsto "melody" {
     e2.
   }
   \new Lyrics \lyricsto "melody" {

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

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


@@ -678,39 +707,36 @@ than eighth notes.
 An unslurred group of notes will be treated as a melisma if they
 are bracketed between @code{\melisma} and @code{\melismaEnd}.
 
 An unslurred group of notes will be treated as a melisma if they
 are bracketed between @code{\melisma} and @code{\melismaEnd}.
 

-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,verbatim]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \time 3/4

-    f4 g8
+    f''4 g8

     \melisma
     f e f
     \melismaEnd
     e2.
   }
   \new Lyrics \lyricsto "melody" {
     \melisma
     f e f
     \melismaEnd
     e2.
   }
   \new Lyrics \lyricsto "melody" {

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

   }
 >>
 @end lilypond
 
   }
 >>
 @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
 to be added to the melisma.
 
 @item
 A melisma can be defined entirely in the lyrics by entering a
 single underscore character, @code{_}, for every extra note that has
 to be added to the melisma.
 

-@lilypond[verbatim, quote, relative=2]
+@lilypond[verbatim, quote]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \time 3/4

-    f4 g8 f e f
+    f''4 g8 f e f

     e8 d e2
   }
   \new Lyrics \lyricsto "melody" {
     e8 d e2
   }
   \new Lyrics \lyricsto "melody" {

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

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


@@ -719,35 +745,57 @@ 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[verbatim,quote]

 <<
 <<

-  \new Voice = "melody" {
+  \new Voice = "melody" \relative {

     \time 3/4
     \set melismaBusyProperties = #'()
     \time 3/4
     \set melismaBusyProperties = #'()

-    c4 d ( e )
-    g8 [ f ] f4( e)
-    d e ~ e
+    c'4 d ( e )
+    g8 [ f ] f4 ~ 4

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

 
 

-@predefined
+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[verbatim,quote]
+<<
+  \new Voice = "melody" \relative {
+    \time 3/4
+    \set melismaBusyProperties = #'()
+    c'4 d ( e )
+    g8 [ f ] ~ 4 ~ f
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ky -- ri -- _ e __ _ _ _
+  }
+>>
+@end lilypond

 
 

+
+@predefined

 @code{\autoBeamOff},
 @code{\autoBeamOn},
 @code{\melisma},
 @code{\melismaEnd}.
 @code{\autoBeamOff},
 @code{\autoBeamOn},
 @code{\melisma},
 @code{\melismaEnd}.

+@endpredefined

 
 @seealso
 Musical Glossary:
 
 @seealso
 Musical Glossary:


@@ -759,35 +807,16 @@ 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}.
 
 @knownissues
 
 Internals Reference:
 @rinternals{Tunable context properties}.
 
 @knownissues

-

 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


@@ -825,7 +854,6 @@ distance between two syllables) and the @code{minimum-length}
 (threshold below which hyphens are removed) properties of
 @code{LyricHyphen}.
 
 (threshold below which hyphens are removed) properties of
 @code{LyricHyphen}.
 

-

 @seealso
 Internals Reference:
 @rinternals{LyricExtender},
 @seealso
 Internals Reference:
 @rinternals{LyricExtender},


@@ -843,6 +871,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
 
 


@@ -856,8 +885,8 @@ Variables containing lyrics can be created, but the lyrics must be
 entered in lyric mode:
 
 @lilypond[quote,verbatim]
 entered in lyric mode:
 
 @lilypond[quote,verbatim]

-musicOne = \relative c'' {
-  c4 b8. a16 g4. f8 e4 d c2
+musicOne = \relative {
+  c''4 b8. a16 g4. f8 e4 d c2

 }
 verseOne = \lyricmode {
   Joy to the world, the Lord is come.
 }
 verseOne = \lyricmode {
   Joy to the world, the Lord is come.


@@ -886,8 +915,8 @@ voices referenced by @code{\lyricsto} have always been defined
 earlier.  For example:
 
 @lilypond[quote,verbatim]
 earlier.  For example:
 
 @lilypond[quote,verbatim]

-sopranoMusic = \relative c'' { c4 c c c }
-contraltoMusic = \relative c'' { a4 a a a }
+sopranoMusic = \relative { c''4 c c c }
+contraltoMusic = \relative { a'4 a a a }

 sopranoWords = \lyricmode { Sop -- ra -- no words }
 contraltoWords = \lyricmode { Con -- tral -- to words }
 
 sopranoWords = \lyricmode { Sop -- ra -- no words }
 contraltoWords = \lyricmode { Con -- tral -- to words }
 


@@ -919,7 +948,6 @@ contraltoWords = \lyricmode { Con -- tral -- to words }
 }
 @end lilypond
 
 }
 @end lilypond
 

-

 @seealso
 Notation Reference:
 @ref{Placing lyrics vertically}.
 @seealso
 Notation Reference:
 @ref{Placing lyrics vertically}.


@@ -946,7 +974,7 @@ context:
   <<
     \new Staff {
       \new Voice = "melody" {
   <<
     \new Staff {
       \new Voice = "melody" {

-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }

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


@@ -959,15 +987,16 @@ context:
 @end lilypond
 
 Lyrics may be positioned above the staff using one of
 @end lilypond
 
 Lyrics may be positioned above the staff using one of

-two methods.  The simplest is to use the same syntax as
-above and explicitly specify the position of the lyrics:
+two methods.  The simplest (and preferred) method
+is to use the same syntax as above and explicitly
+specify the position of the lyrics:

 
 @lilypond[quote,verbatim]
 \score {
   <<
     \new Staff = "staff" {
       \new Voice = "melody" {
 
 @lilypond[quote,verbatim]
 \score {
   <<
     \new Staff = "staff" {
       \new Voice = "melody" {

-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }

       }
     }
     \new Lyrics \with { alignAboveContext = "staff" } {
       }
     }
     \new Lyrics \with { alignAboveContext = "staff" } {


@@ -988,10 +1017,13 @@ follows:
 @lilypond[quote,verbatim]
 \score {
   <<
 @lilypond[quote,verbatim]
 \score {
   <<

-    \new Lyrics = "lyrics"
+    \new Lyrics = "lyrics" \with {
+      % lyrics above a staff should have this override
+      \override VerticalAxisGroup.staff-affinity = #DOWN
+    }

     \new Staff {
       \new Voice = "melody" {
     \new Staff {
       \new Voice = "melody" {

-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }

       }
     }
     \context Lyrics = "lyrics" {
       }
     }
     \context Lyrics = "lyrics" {


@@ -1012,14 +1044,17 @@ is an example of the second method:
   \new ChoirStaff <<
     \new Staff {
       \new Voice = "sopranos" {
   \new ChoirStaff <<
     \new Staff {
       \new Voice = "sopranos" {

-        \relative c'' { c4 c c c }
+        \relative { c''4 c c c }

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

-        \relative c'' { a4 a a a }
+        \relative { a'4 a a a }

       }
     }
     \context Lyrics = "sopranos" {
       }
     }
     \context Lyrics = "sopranos" {


@@ -1037,16 +1072,21 @@ 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]
+{obtaining-2.12-lyrics-spacing-in-newer-versions.ly}

 
 @seealso
 Learning Manual:
 
 @seealso
 Learning Manual:

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

 
 Notation Reference:
 
 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
 
 @node Placing syllables horizontally
 @unnumberedsubsubsec Placing syllables horizontally


@@ -1054,13 +1094,13 @@ Notation Reference:
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 

-To increase the spacing between lyrics, set the @code{minimum-distance}
-property of @code{LyricSpace}.
+To increase the spacing between lyrics, set the
+@code{minimum-distance} property of @code{LyricSpace}.

 
 

-@lilypond[relative,verbatim,fragment,quote,ragged-right]
-{
+@lilypond[verbatim,quote,ragged-right]
+\relative c' {

   c c c c
   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 {


@@ -1075,8 +1115,8 @@ To make this change for all lyrics in the score, set the property in the
 
 @lilypond[verbatim,quote,ragged-right]
 \score {
 
 @lilypond[verbatim,quote,ragged-right]
 \score {

-  \relative c' {
-  c c c c
+  \relative {
+  c' c c c

   c c c c
   }
   \addlyrics {
   c c c c
   }
   \addlyrics {


@@ -1086,24 +1126,24 @@ 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

     }
   }
 }
 @end lilypond
 
 @snippets
     }
   }
 }
 @end lilypond
 
 @snippets

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

 {lyrics-alignment.ly}
 
 @c TODO: move to LSR -vv
 
 {lyrics-alignment.ly}
 
 @c TODO: move to LSR -vv
 

-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
+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
 
 @example

-\override Score.PaperColumn #'keep-inside-line = ##t
+\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


@@ -1114,23 +1154,11 @@ 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
 

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


@@ -1152,8 +1180,8 @@ unchanged.
   <<
     \new Staff {
       \new Voice = "melody" {
   <<
     \new Staff {
       \new Voice = "melody" {

-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a

           \repeat volta 2 { b4 b b b }
         }
       }
           \repeat volta 2 { b4 b b b }
         }
       }


@@ -1177,8 +1205,8 @@ unfolded.
     <<
       \new Staff {
         \new Voice = "melody" {
     <<
       \new Staff {
         \new Voice = "melody" {

-          \relative c'' {
-            a4 a a a
+          \relative {
+            a'4 a a a

             \repeat volta 2 { b4 b b b }
           }
         }
             \repeat volta 2 { b4 b b b }
           }
         }


@@ -1202,8 +1230,8 @@ simply enter all the words:
   <<
     \new Staff {
       \new Voice = "melody" {
   <<
     \new Staff {
       \new Voice = "melody" {

-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a

           \repeat unfold 2 { b4 b b b }
         }
       }
           \repeat unfold 2 { b4 b b b }
         }
       }


@@ -1219,99 +1247,118 @@ 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 {
   <<
     \new Staff {
       \new Voice = "melody" {
 
 @lilypond[verbatim,quote]
 \score {
   <<
     \new Staff {
       \new Voice = "melody" {

-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a

           \repeat volta 2 { b4 b b b }
         }
       }
     }
           \repeat volta 2 { b4 b b b }
         }
       }
     }

-    \new Lyrics {
-      \lyricsto "melody" {
-        Not re -- peat -- ed.
-        The first time words.
-      }
+    \new Lyrics \lyricsto "melody" {
+      Not re -- peat -- ed.
+      <<
+       { The first time words. }
+       \new Lyrics {
+         \set associatedVoice = "melody"
+         Sec -- ond time words.
+       }
+      >>

     }
     }

-    \new Lyrics {
-      \lyricsto "melody" {
-        % skip 4 notes of any duration
-        \repeat unfold 4 { \skip 1 }
-        Sec -- ond time words.
+  >>
+}
+@end lilypond
+
+More verses may be added in a similar way:
+
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "singleVoice" {
+        \relative {
+         a'4 a a a
+         \repeat volta 3 { b4 b b b }
+          c4 c c c
+       }

       }
     }
       }
     }

+    \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
 

-@cindex lyrics, repeating with a temporary voice
+@cindex alignBelowContext
+@funindex alignBelowContext

 
 

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

 
 

-@lilypond[verbatim,quote,ragged-right]
+To position them correctly use @code{alignBelowContext}:
+
+@lilypond[verbatim,quote]

 \score {
   <<
     \new Staff {
 \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 Voice = "melody" {
+        \relative {
+         a'4 a a a
+         \repeat volta 3 { b4 b b b }
+          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.
-      }
+    \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 Lyrics {
-      \lyricsto "repeatVoice" {
-        The third time words.
+    \new Voice = "harmony" {
+      \relative {
+        f'4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2

       }
     }
   >>
 }
 @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
 


@@ -1319,8 +1366,11 @@ technique; see @ref{Keeping contexts alive}.
 @cindex repeating lyrics with alternative endings
 @cindex alternative endings and lyrics
 
 @cindex repeating lyrics with alternative endings
 @cindex alternative endings and lyrics
 

-If the words of the repeated section are the same, exactly the
-same structure can be used for both the lyrics and music.
+If the words of the repeated section are the same, and none of the
+@code{\alternative} blocks start with a rest, exactly the same
+structure can be used for both the lyrics and music.  This has the
+advantage that @code{\unfoldRepeats} will expand both music and
+lyrics correctly.

 
 @lilypond[quote,verbatim]
 \score {
 
 @lilypond[quote,verbatim]
 \score {


@@ -1328,8 +1378,8 @@ same structure can be used for both the lyrics and music.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
     \new Staff {
       \time 2/4
       \new Voice = "melody" {

-        \relative c'' {
-          a4 a a a
+        \relative {
+          a'4 a a a

           \repeat volta 2 { b4 b }
           \alternative { { b b } { b c } }
         }
           \repeat volta 2 { b4 b }
           \alternative { { b b } { b c } }
         }


@@ -1346,10 +1396,25 @@ same structure can be used for both the lyrics and music.
 }
 @end lilypond
 
 }
 @end lilypond
 

-But when the repeated section has different words, a repeat
+@funindex \skip
+@cindex skipping notes in lyrics
+@cindex lyrics, skipping notes
+
+But when the repeated section has different words, or when one
+of the @code{\alternative} blocks starts with a rest, a repeat

 construct cannot be used around the words and @code{\skip} commands
 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 {


@@ -1357,8 +1422,8 @@ skip over the notes in the alternative sections which do not apply.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
     \new Staff {
       \time 2/4
       \new Voice = "melody" {

-        \relative c'' {
-          \repeat volta 2 { b4 b }
+        \relative {
+          \repeat volta 2 { b'4 b }

           \alternative { { b b } { b c } }
           c4 c
         }
           \alternative { { b b } { b c } }
           c4 c
         }


@@ -1404,9 +1469,9 @@ melismata over the volta section and insert manual skips.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
     \new Staff {
       \time 2/4
       \new Voice = "melody" {

-        \relative c'' {
+        \relative {

           \set melismaBusyProperties = #'()
           \set melismaBusyProperties = #'()

-          \repeat volta 2 { b4 b ~}
+          \repeat volta 2 { b'4 b ~}

           \alternative { { b b } { b \repeatTie c } }
           \unset melismaBusyProperties
           c4 c
           \alternative { { b b } { b \repeatTie c } }
           \unset melismaBusyProperties
           c4 c


@@ -1441,8 +1506,8 @@ be inserted manually, as before.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
     \new Staff {
       \time 2/4
       \new Voice = "melody" {

-        \relative c'' {
-          \repeat volta 2 { b4 b ~}
+        \relative {
+          \repeat volta 2 { b'4 b ~}

           \alternative { { b b } { b \repeatTie c } }
           c4 c
         }
           \alternative { { b b } { b \repeatTie c } }
           c4 c
         }


@@ -1474,8 +1539,8 @@ alternative sections these must be inserted manually.
     \new Staff {
       \time 2/4
       \new Voice = "melody" {
     \new Staff {
       \time 2/4
       \new Voice = "melody" {

-        \relative c'' {
-          \repeat volta 2 { b4 b ~}
+        \relative {
+          \repeat volta 2 { b'4 b ~}

           \alternative { { b b } { b \repeatTie c } }
           c4 c
         }
           \alternative { { b b } { b \repeatTie c } }
           c4 c
         }


@@ -1498,6 +1563,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


@@ -1542,11 +1611,11 @@ attaching lyrics to those specific contexts:
 \score {
   <<
     \new Voice = "melody" {
 \score {
   <<
     \new Voice = "melody" {

-      \relative c' {
+      \relative {

         <<
           {
             \voiceOne
         <<
           {
             \voiceOne

-            e4 e8 e
+            e'4 e8 e

           }
           \new Voice = "splitpart" {
             \voiceTwo
           }
           \new Voice = "splitpart" {
             \voiceTwo


@@ -1568,6 +1637,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 \with {\accepts NullVoice } <<
+  \new Staff \soprano
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+  \new Staff \partcombine \altoOne \altoTwo
+>>
+@end lilypond

 
 @node Stanzas
 @subsection Stanzas
 
 @node Stanzas
 @subsection Stanzas


@@ -1589,9 +1758,9 @@ attaching lyrics to those specific contexts:
 
 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]
-\new Voice {
-  \time 3/4 g2 e4 a2 f4 g2.
+@lilypond[quote,ragged-right,verbatim]
+\new Voice \relative {
+  \time 3/4 g'2 e4 a2 f4 g2.

 } \addlyrics {
   \set stanza = #"1. "
   Hi, my name is Bert.
 } \addlyrics {
   \set stanza = #"1. "
   Hi, my name is Bert.


@@ -1642,9 +1811,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 = {


@@ -1671,11 +1840,12 @@ 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]
-\new Voice {
-  \time 3/4 g2 e4 a2 f4 g2.
+@lilypond[ragged-right,quote,verbatim]
+\new Voice \relative {
+  \time 3/4 g'2 e4 a2 f4 g2.

 } \addlyrics {
   \set vocalName = #"Bert "
   Hi, my name is Bert.
 } \addlyrics {
   \set vocalName = #"Bert "
   Hi, my name is Bert.


@@ -1701,9 +1871,9 @@ voice ignore the melisma.  This is done by setting
 
 @lilypond[verbatim,ragged-right,quote]
 <<
 
 @lilypond[verbatim,ragged-right,quote]
 <<

-  \relative c' \new Voice = "lahlah" {
+  \relative \new Voice = "lahlah" {

     \set Staff.autoBeaming = ##f
     \set Staff.autoBeaming = ##f

-    c4
+    c'4

     \slurDotted
     f8.[( g16])
     a4
     \slurDotted
     f8.[( g16])
     a4


@@ -1729,28 +1899,34 @@ are to be ignored.
 
 @subsubheading Adding syllables to grace notes
 
 
 @subsubheading Adding syllables to grace notes
 

-By default, grace notes (e.g. via @code{\grace}) do not get assigned
+@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]
 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 {
+    f'4 \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


@@ -1763,7 +1939,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 }


@@ -1784,15 +1960,15 @@ within the lyrics by setting the @code{associatedVoice} property:
 
 @lilypond[verbatim,quote]
 <<
 
 @lilypond[verbatim,quote]
 <<

-  \relative c' \new Voice = "lahlah" {
+  \relative \new Voice = "lahlah" {

     \set Staff.autoBeaming = ##f
     \set Staff.autoBeaming = ##f

-    c4
+    c'4

     <<
       \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
         }
       }


@@ -1819,10 +1995,11 @@ within the lyrics by setting the @code{associatedVoice} property:
 @end lilypond
 
 @noindent
 @end lilypond
 
 @noindent

-The text for the first stanza is set to the melody called @q{lahlah}
-in the usual way, but the second stanza is set initally to the
-@code{lahlah} context and is then switched to the @code{alternative}
-melody for the syllables @q{ran} to @q{sau} by the lines:
+The 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
 \set associatedVoice = "alternative" % applies to "ran"
 
 @example
 \set associatedVoice = "alternative" % applies to "ran"


@@ -1859,8 +2036,8 @@ different ways to force linebreaks when using
 @code{\markup}.
 
 @lilypond[ragged-right,verbatim,quote]
 @code{\markup}.
 
 @lilypond[ragged-right,verbatim,quote]

-melody = \relative c' {
-e d c d | e e e e |
+melody = \relative {
+e' d c d | e e e e |

 d d e d | c1 |
 }
 
 d d e d | c1 |
 }
 


@@ -1901,8 +2078,8 @@ introduces each verse.  The following example shows how to produce such
 output in LilyPond.
 
 @lilypond[ragged-right,quote,verbatim]
 output in LilyPond.
 
 @lilypond[ragged-right,quote,verbatim]

-melody = \relative c' {
-  c c c c | d d d d
+melody = \relative {
+  c'4 c c c | d d d d

 }
 
 text = \lyricmode {
 }
 
 text = \lyricmode {


@@ -1910,17 +2087,18 @@ 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 { }
 }
 
 \markup {
   \fill-line {
     \hspace #0.1 % moves the column off the left margin;
   \layout { }
 }
 
 \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 {
      \column {
       \line { \bold "2."
         \column {


@@ -1928,7 +2106,7 @@ text = \lyricmode {
           "It has two lines."
         }
       }
           "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."
       \line { \bold "3."
         \column {
           "This is verse three."


@@ -1936,17 +2114,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."
         }
       }
       \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."
       \line { \bold "5."
         \column {
           "This is verse five."


@@ -1955,7 +2131,7 @@ text = \lyricmode {
       }
     }
   \hspace #0.1 % gives some extra space on the right margin;
       }
     }
   \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
   }
 }
 @end lilypond


@@ -2011,8 +2187,7 @@ For entering stanzas, see @ref{Stanzas}.
 
 @item
 Songs are frequently printed with the chording indicated by chord
 
 @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


@@ -2036,14 +2211,15 @@ Notation Reference:
 Snippets:
 @rlsr{Vocal music}.
 
 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


@@ -2075,8 +2251,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).
 


@@ -2091,18 +2267,20 @@ 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
 @ref{Grouping staves}.
 
 @item
 
 @item
 For information about @code{ChoirStaff} and @code{PianoStaff} see
 @ref{Grouping staves}.
 
 @item

-Shape noteheads, as used in Sacred Harp and similar notation, are
+Shape note heads, as used in Sacred Harp and similar notation, are

 described in @ref{Shape note heads}.
 
 @item
 described in @ref{Shape note heads}.
 
 @item


@@ -2111,17 +2289,23 @@ 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
 @code{\oneVoice},
 @code{\voiceOne},
 @code{\voiceTwo}.
 @end itemize
 
 @predefined
 @code{\oneVoice},
 @code{\voiceOne},
 @code{\voiceTwo}.

+@endpredefined

 
 @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},


@@ -2137,6 +2321,7 @@ Internals Reference:
 @rinternals{Lyrics},
 @rinternals{PianoStaff}.
 
 @rinternals{Lyrics},
 @rinternals{PianoStaff}.
 

+

 @node Score layouts for choral
 @unnumberedsubsubsec Score layouts for choral
 
 @node Score layouts for choral
 @unnumberedsubsubsec Score layouts for choral
 


@@ -2169,7 +2354,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
 


@@ -2188,38 +2373,41 @@ above their respective staves, as shown here:
   \new ChoirStaff <<
     \new Staff {
       \new Voice {
   \new ChoirStaff <<
     \new Staff {
       \new Voice {

-        \relative c'' { g4\f g g g }
+        \relative { g'4\f g g g }

       }
     }
     \new Staff {
       \new Voice {
       }
     }
     \new Staff {
       \new Voice {

-        \relative c' { d4 d d\p d }
+        \relative { d'4 d d\p d }

       }
     }
   >>
   \layout {
     \context {
       \Score
       }
     }
   >>
   \layout {
     \context {
       \Score

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

     }
   }
 }
 @end lilypond
 
 @predefined
     }
   }
 }
 @end lilypond
 
 @predefined

-@code{\dynamicUp}, @code{\dynamicDown}, @code{\dynamicNeutral}.
+@code{\dynamicUp},
+@code{\dynamicDown},
+@code{\dynamicNeutral}.
+@endpredefined

 
 @seealso
 Notation Reference:
 @ref{Changing spacing},
 @ref{Displaying spacing},
 @ref{Fitting music onto fewer pages},
 
 @seealso
 Notation Reference:
 @ref{Changing spacing},
 @ref{Displaying spacing},
 @ref{Fitting music onto fewer pages},

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

 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},

-@ref{Using an extra voice for breaks},
+@ref{Breaks},

 @ref{Vertical spacing}.
 
 Internals Reference:
 @ref{Vertical spacing}.
 
 Internals Reference:


@@ -2232,7 +2420,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


@@ -2318,13 +2506,13 @@ 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
 
 @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
 
 
 @end itemize
 


@@ -2335,11 +2523,12 @@ Musical Glossary:
 @rglos{transposing instrument}.
 
 Notation Reference:
 @rglos{transposing instrument}.
 
 Notation Reference:

+@ref{Creating footnotes},

 @ref{Grouping staves},
 @ref{Hiding staves},
 @ref{Instrument transpositions},
 @ref{Nested staff groups},
 @ref{Grouping staves},
 @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{Separating systems},
 @ref{Transpose},
 @ref{Writing parts},


@@ -2364,9 +2553,9 @@ staff is dedicated to that character alone:
     \new Staff {
       \set Staff.vocalName = \markup \smallCaps Kaspar
       \set Staff.shortVocalName = \markup \smallCaps Kas.
     \new Staff {
       \set Staff.vocalName = \markup \smallCaps Kaspar
       \set Staff.shortVocalName = \markup \smallCaps Kas.

-      \relative c' {
+      \relative {

         \clef "G_8"
         \clef "G_8"

-        c4 c c c
+        c'4 c c c

         \break
         c4 c c c
       }
         \break
         c4 c c c
       }


@@ -2375,7 +2564,7 @@ staff is dedicated to that character alone:
       \set Staff.vocalName = \markup \smallCaps Melchior
       \set Staff.shortVocalName = \markup \smallCaps Mel
       \clef "bass"
       \set Staff.vocalName = \markup \smallCaps Melchior
       \set Staff.shortVocalName = \markup \smallCaps Mel
       \clef "bass"

-      \relative c' {
+      \relative {

         a4 a a a
         a4 a a a
       }
         a4 a a a
         a4 a a a
       }


@@ -2389,63 +2578,57 @@ usually printed above the staff at the start of every section
 applying to that character.  This can be done with markup.  Often a
 specific font is used for this purpose.
 
 applying to that character.  This can be done with markup.  Often a
 specific font is used for this purpose.
 

-@lilypond[quote,verbatim,relative=1]
-\clef "G_8"
-c4^\markup \fontsize #1 \smallCaps Kaspar
-c c c
-\clef "bass"
-a4^\markup \fontsize #1 \smallCaps Melchior
-a a a
-\clef "G_8"
-c4^\markup \fontsize #1 \smallCaps Kaspar
-c c c
+@lilypond[quote,verbatim]
+\relative c' {
+  \clef "G_8"
+  c4^\markup \fontsize #1 \smallCaps Kaspar
+  c c c
+  \clef "bass"
+  a4^\markup \fontsize #1 \smallCaps Melchior
+  a a a
+  \clef "G_8"
+  c4^\markup \fontsize #1 \smallCaps Kaspar
+  c c c
+}

 @end lilypond
 
 @end lilypond
 

-Alternatively, if there are many character changes, it may be
-easier to set up @qq{instrument} definitions for each character at
-the top level so that @code{\instrumentSwitch} can be used to
-indicate each change.
+Alternatively, if there are many character changes, it may be easier
+to set up variables to hold the definitions for each character so
+that the switch of characters can be indicated easily and concisely.

 
 @lilypond[quote,verbatim]
 
 @lilypond[quote,verbatim]

-\addInstrumentDefinition #"kaspar"
-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
-     (shortInstrumentName . "Kas.")
-     (clefGlyph . "clefs.G")
-     (clefOctavation . -7)
-     (middleCPosition . 1)
-     (clefPosition . -2)
-     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
-     (midiInstrument . "voice oohs"))
-
-\addInstrumentDefinition #"melchior"
-  #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
-     (shortInstrumentName . "Mel.")
-     (clefGlyph . "clefs.F")
-     (clefOctavation . 0)
-     (middleCPosition . 6)
-     (clefPosition . 2)
-     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
-     (midiInstrument . "voice aahs"))
+kaspar = {
+  \clef "G_8"
+  \set Staff.shortVocalName = "Kas."
+  \set Staff.midiInstrument = "voice oohs"
+  <>^\markup \smallCaps "Kaspar"
+}
+
+melchior = {
+  \clef "bass"
+  \set Staff.shortVocalName = "Mel."
+  \set Staff.midiInstrument = "choir aahs"
+  <>^\markup \smallCaps "Melchior"
+}

 
 \relative c' {
 
 \relative c' {

-  \instrumentSwitch "kaspar"
+  \kaspar

   c4 c c c
   c4 c c c

-  \instrumentSwitch "melchior"
+  \melchior

   a4 a a a
   a4 a a a

-  \instrumentSwitch "kaspar"
+  \kaspar

   c4 c c c
 }
 @end lilypond
 
 @seealso
   c4 c c c
 }
 @end lilypond
 
 @seealso

+Learning Manual:
+@rlearning{Organizing pieces with variables}.
+

 Notation Reference:
 Notation Reference:

-@ref{Instrument names},
-@ref{Scheme functions},

 @ref{Text},
 @ref{Text markup commands}.
 
 @ref{Text},
 @ref{Text markup commands}.
 

-Extending LilyPond:
-@rextend{Markup construction in Scheme}.

 
 @node Musical cues
 @unnumberedsubsubsec Musical cues
 
 @node Musical cues
 @unnumberedsubsubsec Musical cues


@@ -2469,19 +2652,19 @@ close to the start of the cue notes.  The following example shows
 how this is done.
 
 @lilypond[quote,verbatim]
 how this is done.
 
 @lilypond[quote,verbatim]

-flute = \relative c'' {
-  s4 s4 e g
+flute = \relative {
+  s4 s4 e'' g

 }
 \addQuote "flute" { \flute }
 
 }
 \addQuote "flute" { \flute }
 

-pianoRH = \relative c'' {
-  c4. g8
+pianoRH = \relative {
+  c''4. g8

   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff

-  s1*0^\markup { \right-align { \tiny "Flute" } }
+  <>^\markup { \right-align { \tiny "Flute" } }

   \cueDuring "flute" #UP { g4 bes4 }
 }
   \cueDuring "flute" #UP { g4 bes4 }
 }

-pianoLH = \relative c { c4 <c' e> e, <g c> }
+pianoLH = \relative { c4 <c' e> e, <g c> }

 
 \score {
   \new PianoStaff <<
 
 \score {
   \new PianoStaff <<


@@ -2500,12 +2683,8 @@ 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
 specify its key so the conversion of its cue notes will be done
 automatically.  The example below shows this transposition for a
 B-flat clarinet.  The notes in this example are low on the staff so

-@code{#DOWN} is specified in @code{\cueDuring} (so the stems are
-down) and the instrument name is positioned below the staff.  Note
-also that the piano right-hand voice is explicitly declared.  This
-is because the cue notes in this example begin at the start of the
-first bar and this would otherwise cause the entire piano right-hand
-notes to be placed in a @code{CueVoice} context.
+@code{DOWN} is specified in @code{\cueDuring} (so the stems are
+down) and the instrument name is positioned below the staff.

 
 @lilypond[quote,verbatim]
 clarinet = \relative c' {
 
 @lilypond[quote,verbatim]
 clarinet = \relative c' {


@@ -2517,11 +2696,11 @@ clarinet = \relative c' {
 pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff
 pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff

-  s1*0_\markup { \right-align { \tiny "Clar." } }
+  <>_\markup { \right-align { \tiny "Clar." } }

   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }

-pianoLH = \relative c { c4 <c' e> e, <g c> }
+pianoLH = \relative { c4 <c' e> e, <g c> }

 
 \score {
   <<
 
 \score {
   <<


@@ -2547,7 +2726,7 @@ possible to define a music function to reduce the amount of typing
 and to make the piano notes clearer.
 
 @snippets
 and to make the piano notes clearer.
 
 @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


@@ -2565,7 +2744,6 @@ Snippets:
 @rlsr{Vocal music}.
 
 Internals Reference:
 @rlsr{Vocal music}.
 
 Internals Reference:

-@rinternals{InstrumentSwitch},

 @rinternals{CueVoice}.
 
 @knownissues
 @rinternals{CueVoice}.
 
 @knownissues


@@ -2582,8 +2760,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


@@ -2601,10 +2779,12 @@ moment.
 
 For short interjections a simple markup suffices.
 
 
 For short interjections a simple markup suffices.
 

-@lilypond[quote,verbatim,relative=2]
-a4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
-a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
-a4 a a a
+@lilypond[quote,verbatim]
+\relative {
+  a'4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
+  a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
+  a4 a a a
+}

 @end lilypond
 
 For longer phrases it may be necessary to expand the music to make
 @end lilypond
 
 For longer phrases it may be necessary to expand the music to make


@@ -2625,14 +2805,14 @@ 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
 
 @lilypond[quote,verbatim,ragged-right]
 
 @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
 
 @lilypond[quote,verbatim,ragged-right]

-music = \relative c'' {
-  \repeat unfold 3 { a4 a a a }
+music = \relative {
+  \repeat unfold 3 { a'4 a a a }

 }
 
 dialogue = \lyricmode {
 }
 
 dialogue = \lyricmode {


@@ -2649,8 +2829,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 {


@@ -2716,7 +2896,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


@@ -2733,15 +2913,15 @@ all staves remove the bar line engraver completely:
 \score {
   \new StaffGroup <<
     \new Staff {
 \score {
   \new StaffGroup <<
     \new Staff {

-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |

         a4 b c2 |
         a4 b c2 |
       }
     }
     \new Staff {
         a4 b c2 |
         a4 b c2 |
       }
     }
     \new Staff {

-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |

         a4 b c2 |
         a4 b c2 |
       }
         a4 b c2 |
         a4 b c2 |
       }


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

-      \remove Bar_engraver
+      \remove "Bar_engraver"

     }
   }
 }
     }
   }
 }


@@ -2762,16 +2942,16 @@ 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 } {
-      \relative c'' {
-        a4 b c2 |
+    \with { \remove "Bar_engraver" } {
+      \relative {
+        a'4 b c2 |

         a4 b c2 |
         a4 b c2 |
       }
     }
     \new Staff {
         a4 b c2 |
         a4 b c2 |
       }
     }
     \new Staff {

-      \relative c'' {
-        a4 b c2 |
+      \relative {
+        a'4 b c2 |

         a4 b c2 |
         a4 b c2 |
       }
         a4 b c2 |
         a4 b c2 |
       }


@@ -2782,36 +2962,40 @@ 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 |
-\cadenzaOn
-a4 b c2
-a4 b c2
-\bar ""
-a4 b c2
-a4 b c2
-\cadenzaOff
-a4 b c2 |
-a4 b c2 |
+@lilypond[verbatim,quote]
+\relative a' {
+  a4 b c2 |
+  \cadenzaOn
+  a4 b c2
+  a4 b c2
+  \bar ""
+  a4 b c2
+  a4 b c2
+  \cadenzaOff
+  a4 b c2 |
+  a4 b c2 |
+}

 @end lilypond
 
 Rests or pauses in chants can be indicated by modified bar lines.
 
 @end lilypond
 
 Rests or pauses in chants can be indicated by modified bar lines.
 

-@lilypond[verbatim, quote,relative=2]
-a4
-\cadenzaOn
-b c2
-a4 b c2
-\bar "'"
-a4 b c2
-a4 b c2
-\bar ":"
-a4 b c2
-\bar "dashed"
-a4 b c2
-\bar "||"
+@lilypond[verbatim, quote]
+\relative a' {
+  a4
+  \cadenzaOn
+  b c2
+  a4 b c2
+  \bar "'"
+  a4 b c2
+  a4 b c2
+  \bar ";"
+  a4 b c2
+  \bar "!"
+  a4 b c2
+  \bar "||"
+}

 @end lilypond
 
 Alternatively, the notation used in Gregorian chant for pauses or
 @end lilypond
 
 Alternatively, the notation used in Gregorian chant for pauses or


@@ -2820,29 +3004,29 @@ 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
 }
 
 \score {
   \breathe
 }
 
 \score {

-  \relative c'' {
-    g2 a4 g
+  \relative {
+    g'2 a4 g

     \divisioMinima
     g2 a4 g
     \divisioMaior
     \divisioMinima
     g2 a4 g
     \divisioMaior


@@ -2854,7 +3038,7 @@ finalis = {
   \layout {
     \context {
       \Staff
   \layout {
     \context {
       \Staff

-      \remove Bar_engraver
+      \remove "Bar_engraver"

     }
   }
 }
     }
   }
 }


@@ -2865,8 +3049,8 @@ Chants usually omit the time signature and often omit the clef too.
 @lilypond[verbatim,quote]
 \score {
   \new Staff {
 @lilypond[verbatim,quote]
 \score {
   \new Staff {

-    \relative c'' {
-      a4 b c2 |
+    \relative {
+      a'4 b c2 |

       a4 b c2 |
       a4 b c2 |
     }
       a4 b c2 |
       a4 b c2 |
     }


@@ -2874,9 +3058,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"

     }
   }
 }
     }
   }
 }


@@ -2891,22 +3075,22 @@ in each half always contains a single chord of whole notes.  This is
 the @qq{reciting note}.  Chants are usually centered on the page.
 
 @lilypond[verbatim,quote]
 the @qq{reciting note}.  Chants are usually centered on the page.
 
 @lilypond[verbatim,quote]

-SopranoMusic = \relative g' {
-  g1 | c2 b | a1 | \bar "||"
+SopranoMusic = \relative {
+  g'1 | c2 b | a1 | \bar "||"

   a1 | d2 c | c b | c1 | \bar "||"
 }
 
   a1 | d2 c | c b | c1 | \bar "||"
 }
 

-AltoMusic = \relative c' {
-  e1 | g2 g | f1 |
+AltoMusic = \relative {
+  e'1 | g2 g | f1 |

   f1 | f2 e | d d | e1 |
 }
 
   f1 | f2 e | d d | e1 |
 }
 

-TenorMusic = \relative a {
-  c1 | c2 c | c1 |
+TenorMusic = \relative {
+  c'1 | c2 c | c1 |

   d1 | g,2 g | g g | g1 |
 }
 
   d1 | g,2 g | g g | g1 |
 }
 

-BassMusic =  \relative c {
+BassMusic =  \relative {

   c1 | e2 e | f1 |
   d1 | b2 c | g' g | c,1 |
 }
   c1 | e2 e | f1 |
   d1 | b2 c | g' g | c,1 |
 }


@@ -2950,8 +3134,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


@@ -2968,7 +3151,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


@@ -2977,13 +3160,13 @@ 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
 Learning Manual:
 @rlearning{Visibility and color of objects},
 {ancient-notation-template----modern-transcription-of-gregorian-music.ly}
 
 @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},


@@ -3142,11 +3325,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},


@@ -3162,14 +3346,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