Merge branch 'master' into lilypond/translation

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

diff --git a/Documentation/user/vocal.itely b/Documentation/user/vocal.itely
index b7437808770a1d766ce0e77156a8a807fd107752..d9fedf2c5538036a9edfd2abdc66c238bb72384a 100644 (file)
--- a/Documentation/user/vocal.itely
+++ b/Documentation/user/vocal.itely
@@ -6,117 +6,145 @@
     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.38"
+@c \version "2.11.61"

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

-Since LilyPond input files are text, there are two issues to
-consider when working with vocal music:
+@c TODO: inspirational headword

 
 

-@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.
-
-@item
-Song texts must be aligned with the notes of their melody.
-@end itemize
-
-There are a few different ways to define lyrics; we shall begin
-by examining the simplest method, and gradually increase complexity.
+This section explains how to typeset vocal music, and make sure
+that the lyrics will be aligned with the notes of their melody.

 
 @menu
 
 @menu

-* Common notation for vocals::
+* Common notation for vocal music::
+* Entering lyrics::

 * Aligning lyrics to a melody::
 * Aligning lyrics to a melody::

-* Placement of lyrics::
+* Specific uses of lyrics::

 * Stanzas::
 @end menu
 
 * Stanzas::
 @end menu
 

-@snippets

 
 

-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
+@node Common notation for vocal music
+@subsection Common notation for vocal music

 
 

-@example
-\override Score.PaperColumn #'keep-inside-line = ##t
-@end example
+This section discusses issues related to vocal music in general, and
+to some particular styles of vocal music.

 
 

-To make lyrics avoid bar lines as well, use
+@menu
+* References for vocal music and lyrics::
+* Opera::
+* Song books::
+* Chants::
+* Spoken music::
+* Ancient vocal music::
+@end menu

 
 

-@example
-\layout @{
-  \context @{
-    \Lyrics
-      \consists "Bar_engraver"
-      \consists "Separating_line_group_engraver"
-      \override BarLine #'transparent = ##t
-  @}
-@}
-@end example

 
 

-@node Common notation for vocals
-@subsection Common notation for vocals
+@node References for vocal music and lyrics
+@unnumberedsubsubsec References for vocal music and lyrics

 
 

-@menu
-* References for vocal music::
-* Setting simple songs::
-* Entering lyrics::
-* Working with lyrics and variables::
-@end menu
+@c TODO: split this section in two parts? -vv

 
 

-@node References for vocal music
-@subsubsection References for vocal music
+Various issues may arise when engraving vocal music.  Some of these
+are discussed in this section, while others are explained elsewhere:

 
 

-TBC
-@c TODO Add @refs
+@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}.

 
 

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

 
 

+@item
+Lead sheets may be printed by combining vocal parts and @q{chord mode};
+this syntax is explained in @ref{Chord notation}.

 
 

-@node Setting simple songs
-@subsubsection Setting simple songs
+@item
+@q{Ambitus} may be added at the beginning of vocal staves, as explained
+in @ref{Ambitus}.

 
 

-@cindex \addlyrics
+@item
+Vocal parts may be printed using traditional clefs, as shown in @ref{Clef}.

 
 

-The easiest way to add lyrics to a melody is to append
+@item
+Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+@end itemize

 
 

-@example
-\addlyrics @{ @var{the lyrics} @}
-@end example

 
 

-@noindent
-to a melody.  Here is an example,
+@node Opera
+@unnumberedsubsubsec Opera

 
 

-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative { c2 e4 g2. }
-\addlyrics { play the game }
-@end lilypond
+@c TODO
+TBC

 
 

-More stanzas can be added by adding more
-@code{\addlyrics} sections
+@c add characters names snippet -vv

 
 

-@lilypond[ragged-right,verbatim,fragment,quote]
-\time 3/4
-\relative { c2 e4 g2. }
-\addlyrics { play the game }
-\addlyrics { speel het spel }
-\addlyrics { joue le jeu }
-@end lilypond
+@node Song books
+@unnumberedsubsubsec Song books

 
 

-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}.
+@c TODO
+TBC
+
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{simple-lead-sheet.ly}

 
 

+@seealso
+Notation Reference:
+@ref{Chord notation}.
+
+@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}.
+
+@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
+
+@node Chants
+@unnumberedsubsubsec Chants
+
+@c TODO Add text from lsr and -user
+TBC
+
+@node Ancient vocal music
+@unnumberedsubsubsec Ancient vocal music
+
+@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
+
+@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


@@ -124,6 +152,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 explicitely
+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,


@@ -188,29 +225,29 @@ In order to assign more than one syllable to a single note, you can
 surround them with quotes or use a @code{_} character, to get spaces
 between syllables, or use tilde  symbol (@code{~}) to get a lyric tie.
 
 surround them with quotes or use a @code{_} character, to get spaces
 between syllables, or use tilde  symbol (@code{~}) to get a lyric tie.
 

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

 \time 3/4
 \time 3/4

-\relative { c2 e4 g2 e4 }
+\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 }
 @end lilypond
 
 \addlyrics { gran- de_a- mi- go }
 \addlyrics { pu- "ro y ho-" nes- to }
 \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
 accented and special characters (such as the heart symbol or slanted quotes),
 simply insert the characters directly into the input file and save
 
 
 To enter lyrics with characters from non-English languages, or with
 accented and special characters (such as the heart symbol or slanted quotes),
 simply insert the characters directly into the input file and save

-it with utf-8 encoding.  See @ref{Text encoding}, for more info.
-
-FIXME: quotes.
+it with UTF-8 encoding.  See @ref{Text encoding}, for more info.

 
 @lilypond[quote,ragged-right,fragment,verbatim]
 
 @lilypond[quote,ragged-right,fragment,verbatim]

-\relative { e4 f e d e f e2 }
-\addlyrics { He said: ââ\82¬Å\93Let my peo ple goââ\82¬Â\9d. }
+\relative c' { e4 f e d e f e2 }
+\addlyrics { He said: â\80\9cLet my peo ple goâ\80\9d. }

 @end lilypond
 
 To use normal quotes in lyrics, add a backslash before the
 @end lilypond
 
 To use normal quotes in lyrics, add a backslash before the


@@ -253,10 +290,54 @@ verseOne = \lyricmode @{ Joy to the world the Lord is come @}
 
 @seealso
 
 
 @seealso
 

-Internals Reference: @internalsref{LyricText}, @internalsref{LyricSpace}.
+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
+
+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
 


@@ -309,11 +390,44 @@ The final input would resemble
 >>
 @end example
 
 >>
 @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.
+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
 @seealso
 
 @c TODO: document \new Staff << Voice \lyricsto >> bug

-Internals Reference: @internalsref{LyricCombineMusic},
-@internalsref{Lyrics}.
+Internals Reference:
+@rinternals{LyricCombineMusic},
+@rinternals{Lyrics}.

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


@@ -323,9 +437,15 @@ Internals Reference: @internalsref{LyricCombineMusic},
 @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
 
 Lyrics are printed by interpreting them in the context called

-@internalsref{Lyrics}.
+@rinternals{Lyrics}.

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


@@ -356,7 +476,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


@@ -370,7 +490,7 @@ melody and the lyrics with the @code{\lyricsto} expression
 @end example
 
 This aligns the lyrics to the
 @end example
 
 This aligns the lyrics to the

-notes of the @internalsref{Voice} context called @var{name}, which must
+notes of the @rinternals{Voice} context called @var{name}, which must

 already exist.  Therefore normally the @code{Voice} is specified first, and
 then the lyrics are specified with @code{\lyricsto}.  The command
 @code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
 already exist.  Therefore normally the @code{Voice} is specified first, and
 then the lyrics are specified with @code{\lyricsto}.  The command
 @code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the


@@ -385,8 +505,14 @@ The following example uses different commands for entering lyrics.
     \time 2/4
     c4 b8. a16 g4. f8 e4 d c2
   }
     \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 }
   \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. }
   \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
   \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
 >>
 @end lilypond


@@ -412,7 +538,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,


@@ -433,7 +559,7 @@ The alignment to a melody can be specified with the
 
 @noindent
 The value of the property (here: @code{"lala"}) should be the name of
 
 @noindent
 The value of the property (here: @code{"lala"}) should be the name of

-a @internalsref{Voice} context.  Without this setting, extender lines
+a @rinternals{Voice} context.  Without this setting, extender lines

 will not be formatted properly.
 
 Here is an example demonstrating manual lyric durations,
 will not be formatted properly.
 
 Here is an example demonstrating manual lyric durations,


@@ -451,11 +577,12 @@ Here is an example demonstrating manual lyric durations,
 
 @seealso
 
 
 @seealso
 

-Internals Reference: @internalsref{Lyrics}.
+Internals Reference:
+@rinternals{Lyrics}.

 
 
 @node Multiple syllables to one note
 
 
 @node Multiple syllables to one note

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

 
 
 @funindex _
 
 
 @funindex _


@@ -469,9 +596,9 @@ U+203F, so be
 sure to have a font (Like DejaVuLGC) installed that includes this
 glyph.}.
 
 sure to have a font (Like DejaVuLGC) installed that includes this
 glyph.}.
 

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

 \time 3/4
 \time 3/4

-\relative { c2 e4 g2 e4 }
+\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 }
 \addlyrics { gran- de_a- mi- go }
 \addlyrics { pu- "ro y ho-" nes- to }
 \addlyrics { pu- ro~y~ho- nes- to }


@@ -479,14 +606,15 @@ glyph.}.
 
 @seealso
 
 
 @seealso
 

-Internals Reference: @internalsref{LyricCombineMusic}.
+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
 
 @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
 
 @cindex melisma
 @cindex melismata


@@ -499,9 +627,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{_}
 @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 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  }
 @lilypond[relative=1,verbatim,fragment,quote]
 { \set melismaBusyProperties = #'()
  c d( e) f f( e) e e  }


@@ -539,8 +679,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


@@ -557,8 +696,6 @@ A complete example of a SATB score setup is in section
 
 @seealso
 
 
 @seealso
 

-Internals Reference: @internalsref{Melisma_translator}.
-

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


@@ -567,16 +704,18 @@ Melismata are not detected automatically, and extender lines must be
 inserted by hand.
 
 @node Skipping notes
 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}, 
 
 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.
+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,
 
 @lilypond[verbatim,ragged-right,quote]
 
 For example,
 
 @lilypond[verbatim,ragged-right,quote]

-\relative { c c g' }
+\relative c' { c c g' }

 \addlyrics {
   twin -- \skip 4
   kle
 \addlyrics {
   twin -- \skip 4
   kle


@@ -585,16 +724,23 @@ For example,
 
 
 @node Extenders and hyphens
 
 
 @node Extenders and hyphens

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

 
 @cindex melisma
 @cindex extender
 
 @c leave this as samp. -gp
 
 @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
 
 
 @cindex hyphens
 


@@ -611,18 +757,21 @@ distance between two syllables) and the @code{minimum-length}
 
 @seealso
 
 
 @seealso
 

-Internals Reference: @internalsref{LyricExtender},
-@internalsref{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


@@ -631,7 +780,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


@@ -639,7 +787,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.


@@ -685,7 +833,9 @@ section.
 
 
 @node Lyrics independent of notes
 
 
 @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
 
 In some complex vocal music, it may be desirable to place
 lyrics completely independently of notes.  Music defined


@@ -712,14 +862,19 @@ lyr = \lyricmode { I like my cat! }
 >>
 @end lilypond
 
 >>
 @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
 
 @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


@@ -742,7 +897,7 @@ LyricSpace.
 To make this change for all lyrics in the score, set the property in the
 layout.
 
 To make this change for all lyrics in the score, set the property in the
 layout.
 

-@lilypond[relative,verbatim,quote,ragged-right]
+@lilypond[verbatim,quote,ragged-right]

 \score {
   \relative c' {
   c c c c
 \score {
   \relative c' {
   c c c c


@@ -761,8 +916,50 @@ layout.
 }
 @end lilypond
 
 }
 @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
+
+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,
+@c even when notes are tied. -td
+
+@ignore
+\layout
+{
+     \context { \Score lyricMelismaAlignment = #0 }
+}
+@end ignore
+
+

 @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


@@ -781,7 +978,7 @@ TBC
 
 
 @node Adding stanza numbers
 
 
 @node Adding stanza numbers

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

 
 @cindex stanza number
 
 
 @cindex stanza number
 


@@ -795,16 +992,48 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
   Hi, my name is Bert.
 } \addlyrics {
   \set stanza = "2. "
   Hi, my name is Bert.
 } \addlyrics {
   \set stanza = "2. "

-  Oh, chÃ\83© -- ri, je t'aime
+  Oh, ché -- ri, je t'aime

 }
 @end lilypond
 
 }
 @end lilypond
 

+

 @noindent
 These numbers are put just before the start of the first syllable.
 
 @noindent
 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 (might need improving a bit) -td
+
+@ignore
+leftbrace = \markup { \override #'(font-encoding . fetaBraces) \lookup
+#"brace105" }
+
+stanzaOneOne = {
+  \set stanza = \markup { "1. " \leftbrace }
+  \lyricmode { Child, you're mine and I love you.
+    Lend thine ear to what I say.
+
+  }
+}
+
+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
 
 @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


@@ -830,7 +1059,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


@@ -847,12 +1076,12 @@ the line, just like instrument names.  They are created by setting
   Hi, my name is Bert.
 } \addlyrics {
   \set vocalName = "Ernie "
   Hi, my name is Bert.
 } \addlyrics {
   \set vocalName = "Ernie "

-  Oh, che -- ri, je t'aime
+  Oh, ché -- ri, je t'aime

 }
 @end lilypond
 
 @node Stanzas with different rhythms
 }
 @end lilypond
 
 @node Stanzas with different rhythms

-@subsubsection Stanzas with different rhythms
+@unnumberedsubsubsec Stanzas with different rhythms

 
 @subsubheading Ignoring melismata
 
 
 @subsubheading Ignoring melismata
 


@@ -866,10 +1095,10 @@ must be set one syllable @emph{before} the non-melismatic syllable
 in the text, as shown here,
 
 @c  TODO: breaks compile
 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]
 @lilypond[verbatim,ragged-right,quote]

-%{

 <<
 <<

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

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


@@ -886,7 +1115,6 @@ in the text, as shown here,
     still
   }
 >>
     still
   }
 >>

-%}

 @end lilypond
 
 
 @end lilypond
 
 


@@ -902,7 +1130,7 @@ done by setting the @code{associatedVoice} property.  In the example
 
 @lilypond[ragged-right,quote]
 <<
 
 @lilypond[ragged-right,quote]
 <<

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

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


@@ -957,8 +1185,11 @@ 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.
 

-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" @{
 
 @example
 \new Lyrics \lyricsto "lahlah" @{


@@ -977,7 +1208,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


@@ -1021,8 +1252,8 @@ its fleece was white as snow.
 @end lilypond
 
 
 @end lilypond
 
 

-@node Printing stanzas at the end in multiple columns 
-@subsubsection Printing stanzas at the end in multiple columns 
+@node 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


@@ -1048,8 +1279,8 @@ text = \lyricmode {
 
 \markup {
   \fill-line {
 
 \markup {
   \fill-line {

-    \hspace #0.1 % moves the column off the left margin; can be removed if
-        % space on the page is tight
+    \hspace #0.1 % moves the column off the left margin; 
+        % can be removed if space on the page is tight

      \column {
       \line { \bold "2."
         \column {
      \column {
       \line { \bold "2."
         \column {


@@ -1065,9 +1296,9 @@ text = \lyricmode {
         }
       }
     }
         }
       }
     }

-    \hspace #0.1  % adds horizontal spacing between columns; if they are
-        % still too close, add more " " pairs until the result 
-        % looks good
+    \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."
         \column {
      \column {
       \line { \bold "4."
         \column {


@@ -1083,8 +1314,8 @@ text = \lyricmode {
         }
       }
     }
         }
       }
     }

-  \hspace #0.1 % gives some extra space on the right margin; can
-      % be removed if page space is tight
+  \hspace #0.1 % gives some extra space on the right margin; 
+      % can be removed if page space is tight

   }
 }
 @end lilypond
   }
 }
 @end lilypond


@@ -1092,8 +1323,9 @@ text = \lyricmode {
 
 @seealso
 
 
 @seealso
 

-Internals Reference: @internalsref{LyricText}, @internalsref{StanzaNumber},
-@internalsref{VocalName}.
+Internals Reference:
+@rinternals{LyricText},
+@rinternals{StanzaNumber}.