lilypond-book robustness: ensure EOL at the end of @verbatim

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

diff --git a/Documentation/user/vocal.itely b/Documentation/user/vocal.itely
index accea8762540fe939377da27aa10084f54eef611..3736331f836ad8867ef97c46b871345a512481f0 100644 (file)
--- a/Documentation/user/vocal.itely
+++ b/Documentation/user/vocal.itely
@@ -6,145 +6,148 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.57"
+@c \version "2.12.0"

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

-@c TODO: CLARIFY
-@c TODO: delete this comment block
-@c http://code.google.com/p/lilypond/issues/detail?id=248
-@c Done, see @node Lyrics independent of notes ----FV
+@c TODO: inspirational headword

 
 

-@c http://code.google.com/p/lilypond/issues/detail?id=329
-@c Done, see @node Working with lyrics and variables ----FV
+This section explains how to typeset vocal music, and make sure
+that the lyrics will be aligned with the notes of their melody.

 
 

-@c partially done, needs improvement, see Switching to an alternative melody ----FV
-@ignore
+@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.
-
-
-@c Done in @node Extenders and hyphens ---FV
-@c also done (duplicated) in @node Multiple notes to one syllable --FV
-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.
-
-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.
-@end ignore

 
 

+@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.
+
+@menu
+* References for vocal music and lyrics::
+* Opera::
+* Song books::
+* Spoken music::
+* Chants::
+* Ancient vocal music::
+@end menu
+
+
+@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
 
 @itemize
 @item

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

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

 
 

-To address the first issue, the fundamental method is the special mode
-opened by @code{\lyricmode} that interprets its contents as text.
-This mode is implicit by some abbreviated methods, as we will see.
+@item
+Lead sheets may be printed by combining vocal parts and @q{chord mode};
+this syntax is explained in @ref{Chord notation}.

 
 

-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.
+@item
+@q{Ambitus} may be added at the beginning of vocal staves, as explained
+in @ref{Ambitus}.

 
 

-All these methods and their combinations lead to a few different ways
-to define lyrics; we shall begin by examining the simplest method, and
-gradually increase complexity.
+@item
+Vocal parts may be printed using traditional clefs, as shown in @ref{Clef}.

 
 

-@menu
-* Common notation for vocals::
-* Aligning lyrics to a melody::
-* Placement of lyrics::
-* Stanzas::
-@end menu
+@item
+Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+@end itemize

 
 
 
 

-@node Common notation for vocals
-@subsection Common notation for vocals
+@node Opera
+@unnumberedsubsubsec Opera

 
 

-@menu
-* References for vocal music::
-* Setting simple songs::
-* Entering lyrics::
-* Working with lyrics and variables::
-@end menu
+@c TODO
+TBC
+
+@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
 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}
+

 
 

+@seealso
+Notation Reference:
+@ref{Chord notation}.

 
 

-@node Setting simple songs
-@subsubsection Setting simple songs

 
 

-@cindex \addlyrics
+@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}.

 
 

-The easiest way to add lyrics to a melody is to append
+@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

 
 

-@example
-\addlyrics @{ @var{the lyrics} @}
-@end example
+@node Chants
+@unnumberedsubsubsec Chants

 
 

-@noindent
-to a melody.  Here is an example,
+@c TODO Add text from lsr and -user
+TBC

 
 

-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative c' { c2 e4 g2. }
-\addlyrics { play the game }
-@end lilypond
+@node Ancient vocal music
+@unnumberedsubsubsec Ancient vocal music

 
 

-More stanzas can be added by adding more
-@code{\addlyrics} sections
+@c TODO
+TBC

 
 

-@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 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
 
 
 @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
 
 @cindex lyrics
 @funindex \lyricmode


@@ -152,6 +155,15 @@ introduced in @ref{Entering lyrics}.
 @cindex spaces, in lyrics
 @cindex quotes, in 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,
 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,


@@ -224,9 +236,11 @@ between syllables, or use tilde  symbol (@code{~}) to get a lyric tie.
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 
 \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
 
 
 To enter lyrics with characters from non-English languages, or with


@@ -278,13 +292,55 @@ verseOne = \lyricmode @{ Joy to the world the Lord is come @}
 
 
 @seealso
 
 
 @seealso

+Notation Reference:
+@ref{Fonts}.

 
 Internals Reference:
 @rinternals{LyricText},
 @rinternals{LyricSpace}.
 
 
 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
+
+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
 @node Working with lyrics and variables

-@subsubsection Working with lyrics and variables
+@unnumberedsubsubsec Working with lyrics and variables

 
 @cindex lyrics, variables
 
 
 @cindex lyrics, variables
 


@@ -338,7 +394,7 @@ The final input would resemble
 @end example
 
 @ignore
 @end example
 
 @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.
 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.


@@ -369,8 +425,8 @@ remains empty.
 
 @end ignore
 
 
 @end ignore
 

-@seealso

 
 

+@seealso

 @c TODO: document \new Staff << Voice \lyricsto >> bug
 Internals Reference:
 @rinternals{LyricCombineMusic},
 @c TODO: document \new Staff << Voice \lyricsto >> bug
 Internals Reference:
 @rinternals{LyricCombineMusic},


@@ -384,6 +440,12 @@ Internals Reference:
 @funindex \addlyrics
 @funindex \lyricsto
 
 @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}.
 
 Lyrics are printed by interpreting them in the context called
 @rinternals{Lyrics}.


@@ -406,6 +468,13 @@ or by specifying the duration of each syllable
 explicitly, using @code{\lyricmode}
 @end itemize
 
 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::
 @menu
 * Automatic syllable durations::
 * Manual syllable durations::


@@ -417,7 +486,7 @@ explicitly, using @code{\lyricmode}
 @end menu
 
 @node Automatic syllable durations
 @end menu
 
 @node Automatic syllable durations

-@subsubsection Automatic syllable durations
+@unnumberedsubsubsec Automatic syllable durations

 
 @cindex automatic syllable durations
 @cindex lyrics and melodies
 
 @cindex automatic syllable durations
 @cindex lyrics and melodies


@@ -447,7 +516,7 @@ The following example uses different commands for entering lyrics.
     c4 b8. a16 g4. f8 e4 d c2
   }
 
     c4 b8. a16 g4. f8 e4 d c2
   }
 

-% not recommended: left aligns syllables 
+% not recommended: left aligns syllables

   \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
 
 % wrong: durations needed
   \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
 
 % wrong: durations needed


@@ -479,7 +548,7 @@ is the same as
 @end example
 
 @node Manual syllable durations
 @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,
 
 Lyrics can also be entered without @code{\addlyrics} or
 @code{\lyricsto}.  In this case,


@@ -516,14 +585,17 @@ Here is an example demonstrating manual lyric durations,
  } >>
 @end lilypond
 
  } >>
 @end lilypond
 

+

 @seealso
 @seealso

+Notation Reference:
+@ref{Keeping contexts alive}.

 
 Internals Reference:
 @rinternals{Lyrics}.
 
 
 @node Multiple syllables to one note
 
 Internals Reference:
 @rinternals{Lyrics}.
 
 
 @node Multiple syllables to one note

-@subsubsection Multiple syllables to one note
+@unnumberedsubsubsec Multiple syllables to one note

 
 
 @funindex _
 
 
 @funindex _


@@ -545,8 +617,8 @@ glyph.}.
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 
 \addlyrics { pu- ro~y~ho- nes- to }
 @end lilypond
 

-@seealso

 
 

+@seealso

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


@@ -555,7 +627,7 @@ Internals Reference:
 
 
 @node Multiple notes to one syllable
 
 
 @node Multiple notes to one syllable

-@subsubsection Multiple notes to one syllable
+@unnumberedsubsubsec Multiple notes to one syllable

 
 @cindex melisma
 @cindex melismata
 
 @cindex melisma
 @cindex melismata


@@ -568,7 +640,10 @@ 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{_}
 @c it might be better to present it first - vv
 
 You can define melismata entirely in the lyrics, by entering @code{_}

-for every extra note that has to be added to the 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
 
 @c verbose! --FV
 @c duplicated: TODO fix


@@ -617,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.
 
 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
 
 @cindex SATB
 @cindex choral score


@@ -628,26 +702,30 @@ A complete example of a SATB score setup is in section
 
 
 @predefined
 
 
 @predefined

-
-@code{\melisma}, @code{\melismaEnd}
-@funindex \melismaEnd

 @funindex \melisma
 @funindex \melisma

+@code{\melisma},
+@funindex \melismaEnd
+@code{\melismaEnd}.
+@endpredefined

 
 

-@seealso

 
 

+@seealso

 @c @lsr{vocal,lyric@/-combine.ly}.
 
 @c @lsr{vocal,lyric@/-combine.ly}.
 

+

 @knownissues
 
 Melismata are not detected automatically, and extender lines must be
 inserted by hand.
 
 @node Skipping notes
 @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
 
 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,
 
 
 For example,
 


@@ -661,7 +739,7 @@ For example,
 
 
 @node Extenders and hyphens
 
 
 @node Extenders and hyphens

-@subsubsection Extenders and hyphens
+@unnumberedsubsubsec Extenders and hyphens

 
 @cindex melisma
 @cindex extender
 
 @cindex melisma
 @cindex extender


@@ -692,21 +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).
 
 distance between two syllables) and the @code{minimum-length}
 (threshold below which hyphens are removed).
 

-@seealso

 
 

+@seealso

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

+

 @node Lyrics and repeats
 @node Lyrics and repeats

-@subsubsection Lyrics and repeats
+@unnumberedsubsubsec Lyrics and repeats

 
 @c TODO New section.  Add text
 TBC
 
 
 
 @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
 
 Often, different stanzas of one song are put to one melody in slightly
 differing ways.  Such variations can still be captured with


@@ -715,7 +796,6 @@ differing ways.  Such variations can still be captured with
 @menu
 * Divisi lyrics::
 * Lyrics independent of notes::
 @menu
 * Divisi lyrics::
 * Lyrics independent of notes::

-* Chants::

 * Spacing out syllables::
 * Centering lyrics between staves::
 @end menu
 * Spacing out syllables::
 * Centering lyrics between staves::
 @end menu


@@ -723,7 +803,7 @@ differing ways.  Such variations can still be captured with
 
 
 @node Divisi lyrics
 
 
 @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.
 
 You can display alternate (or divisi) lyrics by naming voice
 contexts and attaching lyrics to those specific contexts.


@@ -769,7 +849,7 @@ section.
 
 
 @node Lyrics independent of notes
 
 
 @node Lyrics independent of notes

-@subsubsection Lyrics independent of notes
+@unnumberedsubsubsec Lyrics independent of notes

 
 @cindex Devnull context
 
 
 @cindex Devnull context
 


@@ -809,15 +889,8 @@ the implicit melismata get ignored.
 
 @c this clarifies http://code.google.com/p/lilypond/issues/detail?id=248
 
 
 @c this clarifies http://code.google.com/p/lilypond/issues/detail?id=248
 

-
-@node Chants
-@subsubsection Chants
-
-@c TODO Add text from lsr and -user
-TBC
-

 @node Spacing out syllables
 @node Spacing out syllables

-@subsubsection Spacing out syllables
+@unnumberedsubsubsec Spacing out syllables

 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between


@@ -859,11 +932,13 @@ layout.
 }
 @end lilypond
 
 }
 @end lilypond
 

-@snippets
-@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
-{aligning-lyrics.ly}
-
+@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
 
 Checking to make sure that text scripts and lyrics are within the margins is
 @snippets
 
 Checking to make sure that text scripts and lyrics are within the margins is


@@ -900,7 +975,7 @@ To make lyrics avoid bar lines as well, use
 
 
 @node Centering lyrics between staves
 
 
 @node Centering lyrics between staves

-@subsubsection Centering lyrics between staves
+@unnumberedsubsubsec Centering lyrics between staves

 
 @c TODO Add text from -user
 TBC
 
 @c TODO Add text from -user
 TBC


@@ -909,17 +984,17 @@ TBC
 @subsection Stanzas
 
 @menu
 @subsection Stanzas
 
 @menu

-* Adding stanza numbers ::
+* Adding stanza numbers::

 * Adding dynamics marks to stanzas::
 * Adding singers' names to stanzas::
 * Stanzas with different rhythms::
 * 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
 @end menu
 
 
 @node Adding stanza numbers

-@subsubsection Adding stanza numbers
+@unnumberedsubsubsec Adding stanza numbers

 
 @cindex stanza number
 
 
 @cindex stanza number
 


@@ -929,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 {
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {

-  \set stanza = "1. "
+  \set stanza = #"1. "

   Hi, my name is Bert.
 } \addlyrics {
   Hi, my name is Bert.
 } \addlyrics {

-  \set stanza = "2. "
+  \set stanza = #"2. "

   Oh, ché -- ri, je t'aime
 }
 @end lilypond
   Oh, ché -- ri, je t'aime
 }
 @end lilypond


@@ -942,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
 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
 @c (might need improving a bit) -td
 
 @ignore


@@ -966,15 +1041,15 @@ stanzaOneThree =  {
 }
 
 \new Voice {
 }
 
 \new Voice {

-  \repeat volta 2 { c'8 c' c' c' c' c' c'4 
-                    c'8 c' c' c' c' c' c'4   } 
+  \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
 }  \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
 
 Stanzas differing in loudness may be indicated by putting a
 dynamics mark before each stanza.  In LilyPond, everything coming in


@@ -1000,7 +1075,7 @@ text = {
 @end lilypond
 
 @node Adding singers' names to stanzas
 @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
 
 @cindex singer name
 @cindex name of singer


@@ -1013,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 {
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {

-  \set vocalName = "Bert "
+  \set vocalName = #"Bert "

   Hi, my name is Bert.
 } \addlyrics {
   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
   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
 
 
 @subsubheading Ignoring melismata
 


@@ -1031,12 +1106,6 @@ 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.
 
 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
-@c seems to be fixed, does not break compile anymore --FV

 @lilypond[verbatim,ragged-right,quote]
 <<
   \relative c' \new Voice = "lahlah" {
 @lilypond[verbatim,ragged-right,quote]
 <<
   \relative c' \new Voice = "lahlah" {


@@ -1050,18 +1119,20 @@ in the text, as shown here,
     more slow -- ly
   }
   \new Lyrics \lyricsto "lahlah" {
     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
 
     \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
 
 
 @subsubheading Switching to an alternative melody
 


@@ -1126,6 +1197,7 @@ This is achieved with
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 

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


@@ -1148,7 +1220,7 @@ The underlay is switched back to the starting situation by assigning
 
 
 @node Printing stanzas at the end
 
 
 @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
 
 Sometimes it is appropriate to have one stanza set
 to the music, and the rest added in verse form at


@@ -1165,7 +1237,7 @@ d d e d | c1 |
 }
 
 text = \lyricmode {
 }
 
 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.
 }
 
 its fleece was white as snow.
 }
 


@@ -1193,7 +1265,7 @@ its fleece was white as snow.
 
 
 @node Printing stanzas at the end in multiple columns
 
 
 @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
 
 When a piece of music has many verses, they are often printed in
 multiple columns across the page.  An outdented verse number often


@@ -1204,9 +1276,9 @@ output in LilyPond.
 melody = \relative c' {
   c c c c | d d d d
 }
 melody = \relative c' {
   c c c c | d d d d
 }

- 
+

 text = \lyricmode {
 text = \lyricmode {

-  \set stanza = "1." This is verse one.
+  \set stanza = #"1." This is verse one.

   It has two lines.
 }
 
   It has two lines.
 }
 


@@ -1219,7 +1291,7 @@ text = \lyricmode {
 
 \markup {
   \fill-line {
 
 \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."
         % can be removed if space on the page is tight
      \column {
       \line { \bold "2."


@@ -1236,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."
         % until the result looks good
      \column {
       \line { \bold "4."


@@ -1254,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
   }
 }
       % can be removed if page space is tight
   }
 }


@@ -1262,7 +1334,6 @@ text = \lyricmode {
 
 
 @seealso
 
 
 @seealso

-

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