X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=0fe84ae2032b29b62f99ed85ce829c1b39abf058;hb=09f29b31d131ad75f09a2492c50860f1b1cbc4c8;hp=aa33746150899da70b0e05f33fa8b41f3b6fe120;hpb=7044a6e78c052315e4fbc05cb9a05fbfb16de9f5;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index aa33746150..0fe84ae203 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,12 +7,12 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.13.36"
+@c \version "2.17.5"
 
 @node Vocal music
 @section Vocal music
 
-@c TODO: inspirational headword
+@lilypondfile[quote]{vocal-headword.ly}
 
 This section explains how to typeset vocal music, and make sure
 that the lyrics will be aligned with the notes of their melody.
@@ -43,7 +43,6 @@ This section discusses issues common to most types of vocal music.
 * Manual syllable durations::
 * Multiple syllables to one note::
 * Multiple notes to one syllable::
-* Skipping notes::
 * Extenders and hyphens::
 @end menu
 
@@ -92,11 +91,14 @@ Notation Reference:
 Snippets:
 @rlsr{Vocal music}.
 
+
 @node Entering lyrics
 @unnumberedsubsubsec Entering lyrics
 
 @cindex lyrics, entering
 @cindex entering lyrics
+@cindex formatting in lyrics
+@cindex lyrics, formatting
 @cindex punctuation in lyrics
 @cindex lyrics punctuation
 @cindex spaces in lyrics
@@ -170,7 +172,7 @@ Punctuation, lyrics with accented characters, characters from
 non-English languages, or special characters (such as the heart
 symbol or slanted quotes), may simply be inserted directly
 into the input file, providing it is saved with UTF-8 encoding.
-For more information, see @ref{Text encoding}.
+For more information, see @ref{Special characters}.
 
 @lilypond[quote,verbatim]
 \relative c'' { d8 c16 a bes8 f e' d c4 }
@@ -197,6 +199,16 @@ combination of a backslash followed by one of @code{`}, @code{'},
 
 @c " to balance double quotes for not-so-bright context-sensitive editors
 
+Great control over the appearance of lyrics comes from using
+@code{\markup} inside the lyrics themselves. For explanation of many
+options, see @ref{Formatting text}.
+
+@snippets
+
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{formatting-lyrics-syllables.ly}
+
+
 @seealso
 Learning Manual:
 @rlearning{Songs}.
@@ -204,12 +216,17 @@ Learning Manual:
 Notation Reference:
 @ref{Automatic syllable durations},
 @ref{Fonts},
+@ref{Formatting text},
 @ref{Input modes},
-@ref{Manual syllable durations}.
+@ref{Manual syllable durations},
+@ref{Special characters}.
 
 Internals Reference:
 @rinternals{LyricText}.
 
+Snippets:
+@rlsr{Text}.
+
 
 @node Aligning lyrics to a melody
 @unnumberedsubsubsec Aligning lyrics to a melody
@@ -322,9 +339,18 @@ specifying an associated voice, if one exists.  For details, see
 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}.
 
+
 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
 
@@ -487,7 +513,9 @@ Here is an example demonstrating its use:
 @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
@@ -585,22 +613,18 @@ 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
-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,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 }
+  \relative c'' { \autoBeamOff
+    r8 b c fis, fis c' b e, }
+  \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 }
 }
 @end lilypond
 
-
 @seealso
 Internals Reference:
 @rinternals{LyricCombineMusic}.
@@ -623,7 +647,7 @@ left-aligned with the first note of the melisma.
 When a melisma occurs on a syllable other that the last one in a
 word, that syllable is usually joined to the following one with a
 hyphenated line.  This is indicated by placing a double hyphen,
-@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
@@ -670,6 +694,8 @@ entering lyrics:
 >>
 @end lilypond
 
+Note that phrasing slurs do not affect the creation of melismata.
+
 @item
 Notes are considered a melisma if they are manually beamed,
 providing automatic beaming is switched off.  See
@@ -712,9 +738,6 @@ are bracketed between @code{\melisma} and @code{\melismaEnd}.
 >>
 @end lilypond
 
-Note that this method cannot be used to indicate two melismata if
-the first one is immediately followed by another.
-
 @item
 A melisma can be defined entirely in the lyrics by entering a
 single underscore character, @code{_}, for every extra note that has
@@ -737,8 +760,7 @@ to be added to the melisma.
 
 It is possible to have ties, slurs and manual beams in the melody
 without their indicating melismata.  To do this, set
-@code{melismaBusyProperties} and indicate the melismata with single
-underscores in the lyrics, one underscore for each extra note:
+@code{melismaBusyProperties}:
 
 @lilypond[relative=1,verbatim,quote]
 <<
@@ -746,19 +768,42 @@ underscores in the lyrics, one underscore for each extra note:
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
-    g8 [ f ] f4( e)
-    d e ~ e
+    g8 [ f ] f4 ~ f
   }
   \new Lyrics \lyricsto "melody" {
-    Ky -- _ _ _ _ ri -- _ _ e __ _
+    Ky -- ri -- e e -- le -- i -- son
   }
 >>
 @end lilypond
 
 Other settings for @code{melismaBusyProperties} can be used to
-include or exclude ties, slurs, and beams from the automatic
-detection of melismata; see @code{melismaBusyProperties} in
-@rinternals{Tunable context properties}.
+selectively include or exclude ties, slurs, and beams from the
+automatic detection of melismata; see @code{melismaBusyProperties}
+in @rinternals{Tunable context properties}.
+
+Alternatively, if all melismata indications are to be ignored,
+@code{ignoreMelismata} may be set true;
+see @ref{Stanzas with different rhythms}.
+
+If a melisma is required during a passage in which
+@code{melismaBusyProperties} is active, it may be indicated by
+placing a single underscore in the lyrics for each note which
+should be included in the melisma:
+
+@lilypond[relative=1,verbatim,quote]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    \set melismaBusyProperties = #'()
+    c4 d ( e )
+    g8 [ f ] ~ f4 ~ f
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ky -- ri -- _ e __ _ _ _
+  }
+>>
+@end lilypond
+
 
 @predefined
 
@@ -777,35 +822,16 @@ Learning Manual:
 Notation Reference:
 @ref{Aligning lyrics to a melody},
 @ref{Automatic syllable durations},
-@ref{Setting automatic beam behavior}.
+@ref{Setting automatic beam behavior},
+@ref{Stanzas with different rhythms}.
 
 Internals Reference:
 @rinternals{Tunable context properties}.
 
 @knownissues
-
 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
@@ -843,7 +869,6 @@ distance between two syllables) and the @code{minimum-length}
 (threshold below which hyphens are removed) properties of
 @code{LyricHyphen}.
 
-
 @seealso
 Internals Reference:
 @rinternals{LyricExtender},
@@ -937,7 +962,6 @@ contraltoWords = \lyricmode { Con -- tral -- to words }
 }
 @end lilypond
 
-
 @seealso
 Notation Reference:
 @ref{Placing lyrics vertically}.
@@ -977,8 +1001,9 @@ context:
 @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 {
@@ -1006,7 +1031,10 @@ follows:
 @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" {
         \relative c'' { c4 c c c }
@@ -1034,7 +1062,10 @@ is an example of the second method:
       }
     }
     \new Lyrics = "sopranos"
-    \new Lyrics = "contraltos"
+    \new Lyrics = "contraltos" \with {
+      % lyrics above a staff should have this override
+      \override VerticalAxisGroup #'staff-affinity = #DOWN
+    }
     \new Staff {
       \new Voice = "contraltos" {
         \relative c'' { a4 a a a }
@@ -1058,22 +1089,27 @@ 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.
 
+@snippets
+@lilypondfile[verbatim,quote,texidoc,doctitle]
+{obtaining-2.12-lyrics-spacing-in-newer-versions.ly}
+
 @seealso
 Learning Manual:
 @rlearning{Vocal ensembles}.
 
 Notation Reference:
-@ref{Aligning contexts},
+@ref{Context layout order},
 @ref{Creating contexts}.
 
+
 @node Placing syllables horizontally
 @unnumberedsubsubsec Placing syllables horizontally
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
-To increase the spacing between lyrics, set the @code{minimum-distance}
-property of @code{LyricSpace}.
+To increase the spacing between lyrics, set the
+@code{minimum-distance} property of @code{LyricSpace}.
 
 @lilypond[relative=1,verbatim,quote,ragged-right]
 {
@@ -1111,17 +1147,17 @@ To make this change for all lyrics in the score, set the property in the
 @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
 
-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
-\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
@@ -1137,18 +1173,6 @@ To make lyrics avoid bar lines as well, use
 @}
 @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
 
@@ -1237,24 +1261,9 @@ simply enter all the words:
 }
 @end lilypond
 
-@cindex lyric skip
-@funindex \skip
-
 When the words to a repeated volta section are different, the words
-to each repeat must be entered in separate @code{Lyrics} contexts.
-Earlier unrepeated sections must be skipped in the second and
-subsequent repeats.  The easiest way to skip several notes is to
-use @code{\repeat unfold} around the @code{\skip} command.
-
-Note: do not use an underscore, @code{_}, to skip notes in this
-particular case.  As this syntax indicates a melisma, it will cause
-the preceding syllable to be left-aligned.
-
-@warning{The @code{@bs{}skip} command must be followed by a number,
-but this number is ignored in lyrics which derive their durations
-from the notes in an associated melody through @code{\addlyrics} or
-@code{\lyricsto}.  Each @code{@bs{}skip} skips a single note of any
-value, irrespective of the value of the following number.}
+to each repeat must be entered in separate @code{Lyrics} contexts,
+correctly nested in parallel sections:
 
 @lilypond[verbatim,quote]
 \score {
@@ -1267,69 +1276,103 @@ value, irrespective of the value of the following number.}
         }
       }
     }
-    \new Lyrics {
-      \lyricsto "melody" {
-        Not re -- peat -- ed.
-        The first time words.
-      }
+    \new Lyrics \lyricsto "melody" {
+      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 c'' {
+	  a4 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
 
-@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 {
-      \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 c'' {
+	  a4 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 c' {
+        f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
       }
     }
   >>
 }
 @end lilypond
 
-@c TODO lowering a common line of lyrics
+
+
+@c TODO positioning a common line of lyrics
 
 @subheading Repeats with alternative endings
 
@@ -1364,10 +1407,24 @@ same structure can be used for both the lyrics and music.
 }
 @end lilypond
 
+@funindex \skip
+@cindex skipping notes in lyrics
+@cindex lyrics, skipping notes
+
 But when the repeated section has different words, a repeat
 construct cannot be used around the words and @code{\skip} commands
-have to be inserted manually as described in the previous section to
-skip over the notes in the alternative sections which do not apply.
+have to be inserted manually to skip over the notes in the
+alternative sections which do not apply.
+
+Note: do not use an underscore, @code{_}, to skip notes -- an
+underscore indicates a melisma, causing the preceding syllable
+to be left-aligned.
+
+@warning{The @code{@bs{}skip} command must be followed by a number,
+but this number is ignored in lyrics which derive their durations
+from the notes in an associated melody through @code{\addlyrics} or
+@code{\lyricsto}.  Each @code{@bs{}skip} skips a single note of any
+value, irrespective of the value of the following number.}
 
 @lilypond[verbatim,quote,ragged-right]
 \score {
@@ -1516,6 +1573,10 @@ alternative sections these must be inserted manually.
 }
 @end lilypond
 
+@seealso
+Notation Reference:
+@ref{Keeping contexts alive},
+@ref{Repeats}.
 
 
 @node Divisi lyrics
@@ -1660,9 +1721,9 @@ stanzaOneThree =  {
 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in
-front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
-are no different.  For technical reasons, you have to set the stanza
-outside @code{\lyricmode}:
+front of a stanza goes into the @code{StanzaNumber} object; dynamics
+marks are no different.  For technical reasons, you have to set the
+stanza outside @code{\lyricmode}:
 
 @lilypond[quote,ragged-right,verbatim]
 text = {
@@ -1689,7 +1750,8 @@ text = {
 
 Names of singers can also be added.  They are printed at the start of
 the line, just like instrument names.  They are created by setting
-@code{vocalName}.  A short version may be entered as @code{shortVocalName}.
+@code{vocalName}.  A short version may be entered as
+@code{shortVocalName}.
 
 @lilypond[ragged-right,quote,verbatim,relative=2]
 \new Voice {
@@ -1747,28 +1809,34 @@ are to be ignored.
 
 @subsubheading Adding syllables to grace notes
 
+@cindex grace notes and lyrics
+@cindex lyrics on grace notes
+
 By default, grace notes (e.g. via @code{\grace}) do not get assigned
 syllables when using @code{\lyricsto}, but this behavior can be
 changed:
 
 @lilypond[verbatim,ragged-right,quote]
-\relative c' {
-  f4 \appoggiatura a32 b4
-  \grace { f16[ a16] } b2
-  \afterGrace b2 { f16[ a16] }
-  \appoggiatura a32 b4
-  \acciaccatura a8 b4
-}
-\addlyrics {
-  normal
-  \set includeGraceNotes = ##t
-  case,
-  gra -- ce case,
-  after -- grace case,
-  \set ignoreMelismata = ##t
-  app. case,
-  acc. case.
-}
+<<
+  \new Voice = melody \relative c' {
+    f4 \appoggiatura a32 b4
+    \grace { f16[ a16] } b2
+    \afterGrace b2 { f16[ a16] }
+    \appoggiatura a32 b4
+    \acciaccatura a8 b4
+  }
+  \new Lyrics
+  \lyricsto melody {
+    normal
+    \set includeGraceNotes = ##t
+    case,
+    gra -- ce case,
+    after -- grace case,
+    \set ignoreMelismata = ##t
+    app. case,
+    acc. case.
+  }
+>>
 @end lilypond
 
 @knownissues
@@ -1837,10 +1905,11 @@ within the lyrics by setting the @code{associatedVoice} property:
 @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"
@@ -1920,7 +1989,7 @@ output in LilyPond.
 
 @lilypond[ragged-right,quote,verbatim]
 melody = \relative c' {
-  c c c c | d d d d
+  c4 c c c | d d d d
 }
 
 text = \lyricmode {
@@ -1928,17 +1997,18 @@ text = \lyricmode {
   It has two lines.
 }
 
-\score{ <<
+\score {
+  <<
     \new Voice = "one" { \melody }
     \new Lyrics \lyricsto "one" \text
-   >>
+  >>
   \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 {
@@ -1946,7 +2016,7 @@ text = \lyricmode {
           "It has two lines."
         }
       }
-      \hspace #0.1 % adds vertical spacing between verses
+      \vspace #0.1 % adds vertical spacing between verses
       \line { \bold "3."
         \column {
           "This is verse three."
@@ -1954,17 +2024,15 @@ text = \lyricmode {
         }
       }
     }
-    \hspace #0.1  % adds horizontal spacing between columns;
-        % if they are still too close, add more " " pairs
-        % until the result looks good
-     \column {
+    \hspace #0.1 % adds horizontal spacing between columns;
+    \column {
       \line { \bold "4."
         \column {
           "This is verse four."
           "It has two lines."
         }
       }
-      \hspace #0.1 % adds vertical spacing between verses
+      \vspace #0.1 % adds vertical spacing between verses
       \line { \bold "5."
         \column {
           "This is verse five."
@@ -1973,7 +2041,7 @@ text = \lyricmode {
       }
     }
   \hspace #0.1 % gives some extra space on the right margin;
-      % can be removed if page space is tight
+  % can be removed if page space is tight
   }
 }
 @end lilypond
@@ -2029,8 +2097,7 @@ For entering stanzas, see @ref{Stanzas}.
 
 @item
 Songs are frequently printed with the chording indicated by chord
-names above the staves.  This is described in
-@ref{Displaying chords}.
+names above the staves.  This is described in @ref{Displaying chords}.
 
 @item
 To print fret diagrams of the chords for guitar accompaniment or
@@ -2054,14 +2121,15 @@ Notation Reference:
 Snippets:
 @rlsr{Vocal music}.
 
+
 @node Lead sheets
 @unnumberedsubsubsec Lead sheets
 
-Lead sheets may be printed by combining vocal parts and @q{chord mode};
-this syntax is explained in @ref{Chord notation}.
+Lead sheets may be printed by combining vocal parts and
+@q{chord mode}; this syntax is explained in @ref{Chord notation}.
 
 @snippets
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {simple-lead-sheet.ly}
 
 @seealso
@@ -2120,7 +2188,7 @@ For information about @code{ChoirStaff} and @code{PianoStaff} see
 @ref{Grouping staves}.
 
 @item
-Shape noteheads, as used in Sacred Harp and similar notation, are
+Shape note heads, as used in Sacred Harp and similar notation, are
 described in @ref{Shape note heads}.
 
 @item
@@ -2155,6 +2223,7 @@ Internals Reference:
 @rinternals{Lyrics},
 @rinternals{PianoStaff}.
 
+
 @node Score layouts for choral
 @unnumberedsubsubsec Score layouts for choral
 
@@ -2250,7 +2319,7 @@ Internals Reference:
 
 @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
@@ -2339,10 +2408,10 @@ For details of other page formatting properties, see
 @ref{Page layout}.
 
 @item
-Dialogue cues and stage directions can be inserted with markup.
-See @ref{Text}.  Extensive stage directions can be inserted with
-a section of stand-alone markup between two @code{\score} blocks.
-See @ref{Separate text}.
+Dialogue cues, stage directions and footnotes can be inserted, see
+@ref{Creating footnotes} and @ref{Text}.  Extensive stage directions
+can also be added with a section of stand-alone markups between two
+@code{\score} blocks, see @ref{Separate text}.
 
 @end itemize
 
@@ -2353,6 +2422,7 @@ Musical Glossary:
 @rglos{transposing instrument}.
 
 Notation Reference:
+@ref{Creating footnotes},
 @ref{Grouping staves},
 @ref{Hiding staves},
 @ref{Instrument transpositions},
@@ -2465,6 +2535,7 @@ Notation Reference:
 Extending LilyPond:
 @rextend{Markup construction in Scheme}.
 
+
 @node Musical cues
 @unnumberedsubsubsec Musical cues
 
@@ -2496,7 +2567,10 @@ pianoRH = \relative c'' {
   c4. g8
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
-  s1*0^\markup { \right-align { \tiny "Flute" } }
+  \new CueVoice {
+    \override InstrumentSwitch #'self-alignment-X = #RIGHT
+    \set instrumentCueName = "Flute"
+  }
   \cueDuring "flute" #UP { g4 bes4 }
 }
 pianoLH = \relative c { c4 <c' e> e, <g c> }
@@ -2518,7 +2592,7 @@ If a transposing instrument is being quoted the instrument part should
 specify its key so the conversion of its cue notes will be done
 automatically.  The example below shows this transposition for a
 B-flat clarinet.  The notes in this example are low on the staff so
-@code{#DOWN} is specified in @code{\cueDuring} (so the stems are
+@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
@@ -2535,7 +2609,11 @@ clarinet = \relative c' {
 pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff
-  s1*0_\markup { \right-align { \tiny "Clar." } }
+  \new CueVoice {
+    \override InstrumentSwitch #'self-alignment-X = #RIGHT
+    \override InstrumentSwitch #'direction = #DOWN
+    \set instrumentCueName = "Clar."
+  }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }
@@ -2565,7 +2643,7 @@ possible to define a music function to reduce the amount of typing
 and to make the piano notes clearer.
 
 @snippets
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {adding-orchestral-cues-to-a-vocal-score.ly}
 
 @seealso
@@ -2600,8 +2678,8 @@ declaring separate @code{CueVoice} contexts and using
 
 @cindex parlato
 @cindex Sprechgesang
-Such effects as @q{parlato} or @q{Sprechgesang} require performers to speak
-without pitch but still with rhythm; these are notated by cross
+Such effects as @q{parlato} or @q{Sprechgesang} require performers to
+speak without pitch but still with rhythm; these are notated by cross
 note heads, as demonstrated in @ref{Special note heads}.
 
 @c TODO add "marking-notes-on-spoken-parts" snippet -vv
@@ -2643,7 +2721,7 @@ to manually insert @code{\break}s and adjust the placing of the
 dialogue to avoid running into the right margin.  The final word of
 the last measure on a line should also be separated out, as above.
 
-Here is an example illustating how this might be done.
+Here is an example illustrating how this might be done.
 
 @c This should be a snippet, but it can't be as it needs to be
 @c manually adjusted to suit the imposed line length.  -td
@@ -2768,7 +2846,7 @@ all staves remove the bar line engraver completely:
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
+      \remove "Bar_engraver"
     }
   }
 }
@@ -2780,7 +2858,7 @@ Bar lines can also be removed on a staff-by-staff basis:
 \score {
   \new ChoirStaff <<
     \new Staff
-    \with { \remove Bar_engraver } {
+    \with { \remove "Bar_engraver" } {
       \relative c'' {
         a4 b c2 |
         a4 b c2 |
@@ -2800,7 +2878,7 @@ Bar lines can also be removed on a staff-by-staff basis:
 
 To remove bar lines from just a section of music treat it as a
 cadenza.  If the section is long you may need to insert dummy
-barlines with @code{\bar ""} to show where the line should break.
+bar lines with @code{\bar ""} to show where the line should break.
 
 @lilypond[verbatim,quote,relative=2]
 a4 b c2 |
@@ -2825,9 +2903,9 @@ a4 b c2
 \bar "'"
 a4 b c2
 a4 b c2
-\bar ":"
+\bar ";"
 a4 b c2
-\bar "dashed"
+\bar "!"
 a4 b c2
 \bar "||"
 @end lilypond
@@ -2872,7 +2950,7 @@ finalis = {
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
+      \remove "Bar_engraver"
     }
   }
 }
@@ -2892,9 +2970,9 @@ Chants usually omit the time signature and often omit the clef too.
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
-      \remove Time_signature_engraver
-      \remove Clef_engraver
+      \remove "Bar_engraver"
+      \remove "Time_signature_engraver"
+      \remove "Clef_engraver"
     }
   }
 }
@@ -2986,7 +3064,7 @@ of the following 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
@@ -2995,7 +3073,7 @@ are shown underneath and aligned with the notes.  If so, the notes
 are spaced in accordance with the syllables rather than the notes'
 durations.
 
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
 {ancient-notation-template----modern-transcription-of-gregorian-music.ly}
 
 @seealso
@@ -3180,14 +3258,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.
 
-@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
 
-Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+Ancient vocal music is supported, as explained in
+@ref{Ancient notation}.
 
 @c TODO