X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fvocal.itely;h=3736331f836ad8867ef97c46b871345a512481f0;hb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;hp=ed497c421ec44cd0f82cfdd86767049828e4ed53;hpb=a38a563f999c2b0c6fe2715e19b14afe77108338;p=lilypond.git

diff --git a/Documentation/user/vocal.itely b/Documentation/user/vocal.itely
index ed497c421e..3736331f83 100644
--- a/Documentation/user/vocal.itely
+++ b/Documentation/user/vocal.itely
@@ -6,151 +6,148 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.12.0"
 
 @node Vocal music
 @section Vocal music
 
-TODO
-CLARIFY
-http://code.google.com/p/lilypond/issues/detail?id=248
-http://code.google.com/p/lilypond/issues/detail?id=329
+@c TODO: inspirational headword
 
+This section explains how to typeset vocal music, and make sure
+that the lyrics will be aligned with the notes of their melody.
 
+@menu
+* Common notation for vocal music::
+* Entering lyrics::
+* Aligning lyrics to a melody::
+* Specific uses of lyrics::
+* Stanzas::
+@end menu
 
-> I think the issue here is that changing the associatedVoice
-> happens one step
-> later than expected.  I could be wrong, but I don't think this
-> is obviously
-> documented.
 
-If you read section "Switching the melody associated with a lyrics
-line"
-it indeed says "Again, the command must be one syllable too
-early,..."!
-One problem with the current formulation is that the "Again"
-refers to what's described 2 subsections earlier in "Lyrics to
-multiple notes of a melisma", which isn't obvious unless you have
-read all the sections
-sequentially.
+@node Common notation for vocal music
+@subsection Common notation for vocal music
 
+This section discusses issues related to vocal music in general, and
+to some particular styles of vocal music.
 
-I don't know who's working on the vocal music right now, but I
-found something that should be clarified in NR 2.1.2.4.
+@menu
+* References for vocal music and lyrics::
+* Opera::
+* Song books::
+* Spoken music::
+* Chants::
+* Ancient vocal music::
+@end menu
 
-It should be made clear that __ is used to crate a lyric extender,
-and _ is used to add a note to a melisma, so both __ and _ are
-used.  The example shows it, but there is no description of the
-lyrics extender in this section.
 
+@node References for vocal music and lyrics
+@unnumberedsubsubsec References for vocal music and lyrics
 
+@c TODO: split this section in two parts? -vv
 
-Since LilyPond input files are text, there are two issues to
-consider when working with vocal music:
+Various issues may arise when engraving vocal music.  Some of these
+are discussed in this section, while others are explained elsewhere:
 
 @itemize
 @item
-Song texts must be entered as text, not notes.  For example, the
-input@tie{}@code{d} should be interpreted as a one letter syllable, not the
-note@tie{}D.
+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
-Song texts must be aligned with the notes of their melody.
-@end itemize
+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}.
 
-There are a few different ways to define lyrics; we shall begin
-by examining the simplest method, and gradually increase complexity.
-
-@menu
-* Common notation for vocals::
-* Aligning lyrics to a melody::
-* Placement of lyrics::
-* Stanzas::
-@end menu
+@item
+Lead sheets may be printed by combining vocal parts and @q{chord mode};
+this syntax is explained in @ref{Chord notation}.
 
-@snippets
+@item
+@q{Ambitus} may be added at the beginning of vocal staves, as explained
+in @ref{Ambitus}.
 
-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
+@item
+Vocal parts may be printed using traditional clefs, as shown in @ref{Clef}.
 
-@example
-\override Score.PaperColumn #'keep-inside-line = ##t
-@end example
+@item
+Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+@end itemize
 
-To make lyrics avoid bar lines as well, use
 
-@example
-\layout @{
-  \context @{
-    \Lyrics
-      \consists "Bar_engraver"
-      \consists "Separating_line_group_engraver"
-      \override BarLine #'transparent = ##t
-  @}
-@}
-@end example
+@node Opera
+@unnumberedsubsubsec Opera
 
-@node Common notation for vocals
-@subsection Common notation for vocals
+@c TODO
+TBC
 
-@menu
-* References for vocal music::
-* Setting simple songs::
-* Entering lyrics::
-* Working with lyrics and variables::
-@end menu
+@c add characters names snippet -vv
 
-@node References for vocal music
-@subsubsection References for vocal music
+@node Song books
+@unnumberedsubsubsec Song books
 
+@c TODO
 TBC
-@c TODO Add @refs
 
-@q{Parlato} is spoken without pitch but still with rhythm; it is
-notated by cross note heads.  This is demonstrated in
-@ref{Special note heads}.
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{simple-lead-sheet.ly}
 
 
-@node Setting simple songs
-@subsubsection Setting simple songs
+@seealso
+Notation Reference:
+@ref{Chord notation}.
 
-@cindex \addlyrics
 
-The easiest way to add lyrics to a melody is to append
+@node Spoken music
+@unnumberedsubsubsec Spoken music
+@cindex parlato
+@cindex Sprechgesang
+Such effects as @q{parlato} or @q{Sprechgesang} require perfomers to speak
+without pitch but still with rhythm; these are notated by cross
+note heads, as demonstrated in @ref{Special note heads}.
 
-@example
-\addlyrics @{ @var{the lyrics} @}
-@end example
+@c TODO add "marking-notes-on-spoken-parts" snippet -vv
+@c add "showing the rhythm of a melody" snip
+@c add "one staff-line notation"
+@c add "improvisation" ref
+@c add "lyrics independents of notes" ref
 
-@noindent
-to a melody.  Here is an example,
+@node Chants
+@unnumberedsubsubsec Chants
 
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
-@end lilypond
+@c TODO Add text from lsr and -user
+TBC
 
-More stanzas can be added by adding more
-@code{\addlyrics} sections
+@node Ancient vocal music
+@unnumberedsubsubsec Ancient vocal music
 
-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
-\addlyrics { speel het spel }
-\addlyrics { joue le jeu }
-@end lilypond
+@c TODO
+TBC
+
+@c Add "Printing both the ancient and the modern clef in vocal music" snippet,
+@c and "Transcription of Ancient music with incipit" snippet. -vv
 
-The command @code{\addlyrics} cannot handle polyphony settings.  For these
-cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
-introduced in @ref{Entering lyrics}.
 
+@seealso
+Notation Reference:
+@ref{Ancient notation}.
 
 
 @node Entering lyrics
-@subsubsection Entering lyrics
+@subsection Entering lyrics
+
+@c TODO add one sentence here. -vv
+
+@menu
+* Lyrics explained::
+* Setting simple songs::
+* Working with lyrics and variables::
+@end menu
+
+
+@node Lyrics explained
+@unnumberedsubsubsec Lyrics explained
 
 @cindex lyrics
 @funindex \lyricmode
@@ -158,6 +155,15 @@ introduced in @ref{Entering lyrics}.
 @cindex spaces, in lyrics
 @cindex quotes, in lyrics
 
+@c FIXME: this section is to be rewritten.
+Since LilyPond input files are text, there is at least one
+issue to consider when working with vocal music:
+song texts must be interpreted as text, not notes.  For example, the
+input@tie{}@code{d} should be interpreted as a one letter syllable,
+not the note@tie{}D.
+Therefore, a special lyric mode has to be used, either explicitly
+or using some abbreviated methods.
+
 Lyrics are entered in a special input mode, which can be introduced
 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
 @code{\lyricsto}.  In this mode you can enter lyrics,
@@ -230,9 +236,11 @@ between syllables, or use tilde  symbol (@code{~}) to get a lyric tie.
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 
-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.
+@noindent
+The lyric tie is implemented with the Unicode character
+@code{U+203F}; therefore a font that includes this glyph
+(such as DejaVuLGC) has to be used.  More explanations about
+text and non-text fonts can be found in @ref{Fonts}.
 
 
 To enter lyrics with characters from non-English languages, or with
@@ -284,11 +292,55 @@ verseOne = \lyricmode @{ Joy to the world the Lord is come @}
 
 
 @seealso
+Notation Reference:
+@ref{Fonts}.
+
+Internals Reference:
+@rinternals{LyricText},
+@rinternals{LyricSpace}.
+
+
+@c FIXME: this title has to be changed (possible confusion with LM) -vv
+@node Setting simple songs
+@unnumberedsubsubsec Setting simple songs
+
+@cindex \addlyrics
+
+The easiest way to add lyrics to a melody is to append
+
+@example
+\addlyrics @{ @var{the lyrics} @}
+@end example
+
+@noindent
+to a melody.  Here is an example,
+
+@lilypond[ragged-right,verbatim,fragment,quote]
+\time 3/4
+\relative c' { c2 e4 g2. }
+\addlyrics { play the game }
+@end lilypond
+
+More stanzas can be added by adding more
+@code{\addlyrics} sections
+
+@lilypond[ragged-right,verbatim,fragment,quote]
+\time 3/4
+\relative c' { c2 e4 g2. }
+\addlyrics { play the game }
+\addlyrics { speel het spel }
+\addlyrics { joue le jeu }
+@end lilypond
 
-Internals Reference: @rinternals{LyricText}, @rinternals{LyricSpace}.
+The command @code{\addlyrics} cannot handle polyphony settings.  For these
+cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
+introduced in @ref{Lyrics explained}.
+
+@c TODO: one additional section may be needed here,
+@c such as "advanced lyric syntax" or whatever -vv
 
 @node Working with lyrics and variables
-@subsubsection Working with lyrics and variables
+@unnumberedsubsubsec Working with lyrics and variables
 
 @cindex lyrics, variables
 
@@ -341,10 +393,43 @@ The final input would resemble
 >>
 @end example
 
-@seealso
+@ignore
+@c FIXME
+http://code.google.com/p/lilypond/issues/detail?id=329
+The problem cannot be reproduced.
+The following has no sense, because the issue seems to be fixed.
+A comment is in tracker waiting for response ---FV
+
+
+Be careful when defining a variable with lyrics that creates a new
+context, for example, using the deprecated @code{\lyrics} command. See
+the next erroneous example:
 
+@example
+words = \lyrics{ %warning: this creates a new context
+ one two
+}
+<<
+  \new Voice = "sop" { c1 }
+  \new Lyrics \lyricsto "sop" { \words }
+  \new Voice = "alt" { c2 c }
+  \new Lyrics \lyricsto "alt" { \words }
+>>
+@end example
+
+the problem is that \lyricsto will try to connect the "sop" melody with the context
+created by "\new Lyrics".
+
+Then \lyrics in \words creates another context, and the original "\new Lyrics" one
+remains empty.
+
+@end ignore
+
+
+@seealso
 @c TODO: document \new Staff << Voice \lyricsto >> bug
-Internals Reference: @rinternals{LyricCombineMusic},
+Internals Reference:
+@rinternals{LyricCombineMusic},
 @rinternals{Lyrics}.
 
 
@@ -355,6 +440,12 @@ Internals Reference: @rinternals{LyricCombineMusic},
 @funindex \addlyrics
 @funindex \lyricsto
 
+@c FIXME: this stuff is to be rewritten. -vv
+
+Aligning of text with melodies can be made automatically, but if you
+specify the durations of the syllables it can also be made manually.
+Lyrics aligning and typesetting are prepared with the help of skips,
+hyphens and extender lines.
 
 Lyrics are printed by interpreting them in the context called
 @rinternals{Lyrics}.
@@ -377,6 +468,13 @@ or by specifying the duration of each syllable
 explicitly, using @code{\lyricmode}
 @end itemize
 
+The @code{Voice} context containing the melody to which the lyrics
+are being aligned must not have @qq{died}, or the lyrics after that
+point will be lost.  This can happen if there are periods when that
+voice has nothing to do.  For methods of keeping contexts alive, see
+@ref{Keeping contexts alive}.
+
+
 @menu
 * Automatic syllable durations::
 * Manual syllable durations::
@@ -388,7 +486,7 @@ explicitly, using @code{\lyricmode}
 @end menu
 
 @node Automatic syllable durations
-@subsubsection Automatic syllable durations
+@unnumberedsubsubsec Automatic syllable durations
 
 @cindex automatic syllable durations
 @cindex lyrics and melodies
@@ -417,8 +515,14 @@ The following example uses different commands for entering lyrics.
     \time 2/4
     c4 b8. a16 g4. f8 e4 d c2
   }
+
+% not recommended: left aligns syllables
   \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
+
+% wrong: durations needed
   \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }
+
+%correct
   \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
 >>
 @end lilypond
@@ -444,7 +548,7 @@ is the same as
 @end example
 
 @node Manual syllable durations
-@subsubsection Manual syllable durations
+@unnumberedsubsubsec Manual syllable durations
 
 Lyrics can also be entered without @code{\addlyrics} or
 @code{\lyricsto}.  In this case,
@@ -481,13 +585,17 @@ Here is an example demonstrating manual lyric durations,
  } >>
 @end lilypond
 
+
 @seealso
+Notation Reference:
+@ref{Keeping contexts alive}.
 
-Internals Reference: @rinternals{Lyrics}.
+Internals Reference:
+@rinternals{Lyrics}.
 
 
 @node Multiple syllables to one note
-@subsubsection Multiple syllables to one note
+@unnumberedsubsubsec Multiple syllables to one note
 
 
 @funindex _
@@ -509,16 +617,17 @@ glyph.}.
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 
-@seealso
 
-Internals Reference: @rinternals{LyricCombineMusic}.
+@seealso
+Internals Reference:
+@rinternals{LyricCombineMusic}.
 
 @c Here come the section which used to be "Melismata"
 @c the new title might be more self-explanatory
 
 
 @node Multiple notes to one syllable
-@subsubsection Multiple notes to one syllable
+@unnumberedsubsubsec Multiple notes to one syllable
 
 @cindex melisma
 @cindex melismata
@@ -531,9 +640,21 @@ single syllable; such vocalises are called melismas, or melismata.
 @c it might be better to present it first - vv
 
 You can define melismata entirely in the lyrics, by entering @code{_}
-for every note
-that is part of the melisma.
+for every extra note that has to be added to the melisma.
 
+@c FIXME: clarify: __ is used to crate a lyric extender,
+@c _ is used to add a note to a melisma, so both __ and _ are needed.
+
+@c verbose! --FV
+@c duplicated: TODO fix
+Additionaly, you can make an extender line to be typeset to indicate
+the melisma in the score, writing a double underscore next to the
+first syllable of the melisma. This example shows the three elements
+that are used for this purpose (all of them surrounded by spaces):
+double hyphens to separate syllables in a word, underscores to add
+notes to a melisma, and a double underscore to put an extender line.
+
+@c wrong: extender line only on last syllable of a word. Change example
 @lilypond[relative=1,verbatim,fragment,quote]
 { \set melismaBusyProperties = #'()
  c d( e) f f( e) e e  }
@@ -571,8 +692,7 @@ In addition, notes are considered a melisma if they are manually
 beamed, and automatic beaming (see @ref{Setting automatic beam
 behavior}) is switched off.
 
-@c TODO: there might be some more relevant place for
-@c the following link (?)
+@c FIXME: this now links to LM -vv
 
 @cindex SATB
 @cindex choral score
@@ -582,28 +702,30 @@ A complete example of a SATB score setup is in section
 
 
 @predefined
-
-@code{\melisma}, @code{\melismaEnd}
-@funindex \melismaEnd
 @funindex \melisma
+@code{\melisma},
+@funindex \melismaEnd
+@code{\melismaEnd}.
+@endpredefined
 
-@seealso
-
-Internals Reference: @rinternals{Melisma_translator}.
 
+@seealso
 @c @lsr{vocal,lyric@/-combine.ly}.
 
+
 @knownissues
 
 Melismata are not detected automatically, and extender lines must be
 inserted by hand.
 
 @node Skipping notes
-@subsubsection 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 another note.
+inserting @code{\skip}s into the lyrics.  For every @code{\skip},
+the text will be delayed another note.  The @code{\skip} command
+must be followed by a valid duration, but this is ignored when
+@code{\skip} is used in lyrics.
 
 For example,
 
@@ -617,16 +739,23 @@ For example,
 
 
 @node Extenders and hyphens
-@subsubsection Extenders and hyphens
+@unnumberedsubsubsec Extenders and hyphens
 
 @cindex melisma
 @cindex extender
 
 @c leave this as samp. -gp
-Melismata are indicated with a horizontal line centered between a syllable
-and the next one.  Such a line is called an extender line, and it is entered
-as @samp{ __ } (note the spaces before and after the two underscore
-characters).
+In the last syllable of a word, melismata are sometimes indicated with
+a long horizontal line starting in the melisma syllable, and ending in
+the next one.  Such a line is called an extender line, and it is
+entered as @samp{ __ } (note the spaces before and after the two
+underscore characters).
+
+@warning{Melismata are indicated in the score with extender lines,
+which are entered as one double underscore; but short melismata can
+also be entered by skipping individual notes, which are entered as
+single underscore characters; these do not make an extender line to be
+typeset by default.}
 
 @cindex hyphens
 
@@ -641,20 +770,24 @@ happens can be controlled with the @code{minimum-distance} (minimum
 distance between two syllables) and the @code{minimum-length}
 (threshold below which hyphens are removed).
 
-@seealso
 
-Internals Reference: @rinternals{LyricExtender},
+@seealso
+Internals Reference:
+@rinternals{LyricExtender},
 @rinternals{LyricHyphen}
 
+
 @node Lyrics and repeats
-@subsubsection Lyrics and repeats
+@unnumberedsubsubsec Lyrics and repeats
 
 @c TODO New section.  Add text
 TBC
 
 
-@node Placement of lyrics
-@subsection Placement of lyrics
+@node Specific uses of lyrics
+@subsection Specific uses of lyrics
+
+@c FIXME This whole section is to be reorganized. -vv
 
 Often, different stanzas of one song are put to one melody in slightly
 differing ways.  Such variations can still be captured with
@@ -663,7 +796,6 @@ differing ways.  Such variations can still be captured with
 @menu
 * Divisi lyrics::
 * Lyrics independent of notes::
-* Chants::
 * Spacing out syllables::
 * Centering lyrics between staves::
 @end menu
@@ -671,7 +803,7 @@ differing ways.  Such variations can still be captured with
 
 
 @node Divisi lyrics
-@subsubsection Divisi lyrics
+@unnumberedsubsubsec Divisi lyrics
 
 You can display alternate (or divisi) lyrics by naming voice
 contexts and attaching lyrics to those specific contexts.
@@ -717,7 +849,9 @@ section.
 
 
 @node Lyrics independent of notes
-@subsubsection Lyrics independent of notes
+@unnumberedsubsubsec Lyrics independent of notes
+
+@cindex Devnull context
 
 In some complex vocal music, it may be desirable to place
 lyrics completely independently of notes.  Music defined
@@ -744,14 +878,19 @@ lyr = \lyricmode { I like my cat! }
 >>
 @end lilypond
 
-@node Chants
-@subsubsection Chants
+This method is recommended only if the music in the @code{Devnull}
+context does not contain melismata.  Melismata are defined by the
+@code{Voice} context. Connecting lyrics to a @code{Devnull} context
+makes the voice/lyrics links to get lost, and so does the info on
+melismata.  Therefore, if you link lyrics to a @code{Devnull} context,
+the implicit melismata get ignored.
 
-@c TODO Add text from lsr and -user
-TBC
+@c Conclusion: do not use devnull for lyrics -FV
+
+@c this clarifies http://code.google.com/p/lilypond/issues/detail?id=248
 
 @node Spacing out syllables
-@subsubsection Spacing out syllables
+@unnumberedsubsubsec Spacing out syllables
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
@@ -793,9 +932,35 @@ layout.
 }
 @end lilypond
 
+@c @snippets
+@c This snippet has been renamed to "lyrics-alignment.ly"
+@c update as soon as lsr/is updated -vv
+@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+@c {lyrics-alignment.ly}
+
+@c TODO: move to LSR -vv
 @snippets
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{aligning-lyrics.ly}
+
+Checking to make sure that text scripts and lyrics are within the margins is
+a relatively large computational task.  To speed up processing, LilyPond does
+not perform such calculations by default; to enable it, use
+
+@example
+\override Score.PaperColumn #'keep-inside-line = ##t
+@end example
+
+To make lyrics avoid bar lines as well, use
+
+@example
+\layout @{
+  \context @{
+    \Lyrics
+      \consists "Bar_engraver"
+      \consists "Separating_line_group_engraver"
+      \override BarLine #'transparent = ##t
+  @}
+@}
+@end example
 
 @c TODO Create and add lsr example of lyricMelismaAlignment
 @c It's used like this to center-align all lyric syllables,
@@ -808,8 +973,9 @@ layout.
 }
 @end ignore
 
+
 @node Centering lyrics between staves
-@subsubsection Centering lyrics between staves
+@unnumberedsubsubsec Centering lyrics between staves
 
 @c TODO Add text from -user
 TBC
@@ -818,17 +984,17 @@ TBC
 @subsection Stanzas
 
 @menu
-* Adding stanza numbers ::
+* Adding stanza numbers::
 * Adding dynamics marks to stanzas::
 * Adding singers' names to stanzas::
 * Stanzas with different rhythms::
-* Printing stanzas at the end ::
-* Printing stanzas at the end in multiple columns ::
+* Printing stanzas at the end::
+* Printing stanzas at the end in multiple columns::
 @end menu
 
 
 @node Adding stanza numbers
-@subsubsection Adding stanza numbers
+@unnumberedsubsubsec Adding stanza numbers
 
 @cindex stanza number
 
@@ -838,10 +1004,10 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
-  \set stanza = "1. "
+  \set stanza = #"1. "
   Hi, my name is Bert.
 } \addlyrics {
-  \set stanza = "2. "
+  \set stanza = #"2. "
   Oh, ché -- ri, je t'aime
 }
 @end lilypond
@@ -851,7 +1017,7 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
 These numbers are put just before the start of the first syllable.
 
 @c TODO Create and add snippet to show how two lines of a
-@c stanza can be grouped together, along these lines: 
+@c stanza can be grouped together, along these lines:
 @c (might need improving a bit) -td
 
 @ignore
@@ -862,7 +1028,7 @@ stanzaOneOne = {
   \set stanza = \markup { "1. " \leftbrace }
   \lyricmode { Child, you're mine and I love you.
     Lend thine ear to what I say.
-    ...
+
   }
 }
 
@@ -870,13 +1036,20 @@ stanzaOneThree =  {
 %  \set stanza = \markup { "   "}
   \lyricmode { Child, I have no great -- er joy
     Than to have you walk in truth.
-...
+
   }
 }
+
+\new Voice {
+  \repeat volta 2 { c'8 c' c' c' c' c' c'4
+                    c'8 c' c' c' c' c' c'4   }
+}  \addlyrics { \stanzaOneOne }
+   \addlyrics { \stanzaOneThree }
+
 @end ignore
 
 @node Adding dynamics marks to stanzas
-@subsubsection Adding dynamics marks to stanzas
+@unnumberedsubsubsec Adding dynamics marks to stanzas
 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in
@@ -902,7 +1075,7 @@ text = {
 @end lilypond
 
 @node Adding singers' names to stanzas
-@subsubsection Adding singers' names to stanzas
+@unnumberedsubsubsec Adding singers' names to stanzas
 
 @cindex singer name
 @cindex name of singer
@@ -915,16 +1088,16 @@ the line, just like instrument names.  They are created by setting
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
-  \set vocalName = "Bert "
+  \set vocalName = #"Bert "
   Hi, my name is Bert.
 } \addlyrics {
-  \set vocalName = "Ernie "
+  \set vocalName = #"Ernie "
   Oh, ché -- ri, je t'aime
 }
 @end lilypond
 
 @node Stanzas with different rhythms
-@subsubsection Stanzas with different rhythms
+@unnumberedsubsubsec Stanzas with different rhythms
 
 @subsubheading Ignoring melismata
 
@@ -933,13 +1106,7 @@ multiple syllables in another one.  One solution is to make the faster
 voice ignore the melisma.  This is done by setting
 @code{ignoreMelismata} in the Lyrics context.
 
-There is one tricky aspect: the setting for @code{ignoreMelismata}
-must be set one syllable @emph{before} the non-melismatic syllable
-in the text, as shown here,
-
-@c  TODO: breaks compile
 @lilypond[verbatim,ragged-right,quote]
-%{
 <<
   \relative c' \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
@@ -952,19 +1119,20 @@ in the text, as shown here,
     more slow -- ly
   }
   \new Lyrics \lyricsto "lahlah" {
-    \set ignoreMelismata = ##t % applies to "fas"
-    go fas -- ter
+    go
+    \set ignoreMelismata = ##t
+    fas -- ter
     \unset ignoreMelismata
     still
   }
 >>
-%}
 @end lilypond
 
-
-The @code{ignoreMelismata} applies to the syllable @q{fas}, so it
-should be entered before @q{go}.
-
+@knownissues
+Unlike most @code{\set} commands, @code{\set ignoreMelismata} does
+not work if prefixed with @code{\once}.  It is necessary to use
+@code{\set} and @code{\unset} to bracket the lyrics where melismata
+are to be ignored.
 
 @subsubheading Switching to an alternative melody
 
@@ -1029,8 +1197,11 @@ This is achieved with
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 
-Again, the command must be one syllable too early, before @q{Ty} in
-this case.
+@c FIXME: make this easier to understand -vv
+This command must be one syllable too early, before @q{Ty} in this
+case.  In other words, changing the associatedVoice happens one step
+later than expected.  This is for technical reasons, and it is not a
+bug.
 
 @example
 \new Lyrics \lyricsto "lahlah" @{
@@ -1049,7 +1220,7 @@ The underlay is switched back to the starting situation by assigning
 
 
 @node Printing stanzas at the end
-@subsubsection Printing stanzas at the end
+@unnumberedsubsubsec Printing stanzas at the end
 
 Sometimes it is appropriate to have one stanza set
 to the music, and the rest added in verse form at
@@ -1066,7 +1237,7 @@ d d e d | c1 |
 }
 
 text = \lyricmode {
-\set stanza = "1." Ma- ry had a lit- tle lamb,
+\set stanza = #"1." Ma- ry had a lit- tle lamb,
 its fleece was white as snow.
 }
 
@@ -1094,7 +1265,7 @@ its fleece was white as snow.
 
 
 @node Printing stanzas at the end in multiple columns
-@subsubsection Printing stanzas at the end in multiple columns
+@unnumberedsubsubsec Printing stanzas at the end in multiple columns
 
 When a piece of music has many verses, they are often printed in
 multiple columns across the page.  An outdented verse number often
@@ -1105,9 +1276,9 @@ output in LilyPond.
 melody = \relative c' {
   c c c c | d d d d
 }
- 
+
 text = \lyricmode {
-  \set stanza = "1." This is verse one.
+  \set stanza = #"1." This is verse one.
   It has two lines.
 }
 
@@ -1120,7 +1291,7 @@ text = \lyricmode {
 
 \markup {
   \fill-line {
-    \hspace #0.1 % moves the column off the left margin; 
+    \hspace #0.1 % moves the column off the left margin;
         % can be removed if space on the page is tight
      \column {
       \line { \bold "2."
@@ -1137,8 +1308,8 @@ text = \lyricmode {
         }
       }
     }
-    \hspace #0.1  % adds horizontal spacing between columns; 
-        % if they are still too close, add more " " pairs  
+    \hspace #0.1  % adds horizontal spacing between columns;
+        % if they are still too close, add more " " pairs
         % until the result looks good
      \column {
       \line { \bold "4."
@@ -1155,7 +1326,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
   }
 }
@@ -1163,9 +1334,9 @@ text = \lyricmode {
 
 
 @seealso
-
-Internals Reference: @rinternals{LyricText}, @rinternals{StanzaNumber},
-@rinternals{VocalName}.
+Internals Reference:
+@rinternals{LyricText},
+@rinternals{StanzaNumber}.