X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=69db16abb172a155cf19c96b94d79a7de9d6f377;hb=6e818e3e10f397ef94525b3a2698a1c75e67b706;hp=756fb3fdcb2083f9a545b02be2d888dee868b051;hpb=d29eebdeb66b6651e1e565eafd4fad68c0d2e2bf;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 756fb3fdcb..69db16abb1 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -78,67 +78,65 @@ Music Glossary:
 @node Entering lyrics
 @unnumberedsubsubsec Entering lyrics
 
-Lyrics are entered in lyric mode.  This section explains how this
-done.
-
-@cindex lyrics
+@cindex lyrics, entering
+@cindex entering lyrics
+@cindex punctuation in lyrics
+@cindex lyrics punctuation
+@cindex spaces in lyrics
+@cindex quotes in lyrics
 @funindex \lyricmode
-@cindex punctuation
-@cindex spaces, in lyrics
-@cindex quotes, in lyrics
 
-@c TODO: 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.
+@c TODO should we explain hyphens here
 
 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,
-with punctuation and accents, and the input @code{d} is not parsed as
-a pitch, but rather as a one letter syllable.  Syllables are entered
-like notes, but with pitches replaced by text.  For example,
+@code{\lyricsto}.  In this mode the input @code{d} is not parsed as
+the pitch @notation{D}, but rather as a one-letter syllable of text.
+In other words, syllables are entered like notes but with pitches
+replaced by text.
+
+For example:
 
 @example
-\lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
+\lyricmode @{ Three4 blind mice,2 three4 blind mice2 @}
 @end example
 
-There are two main methods to specify the horizontal placement
+There are two main methods for specifying the horizontal placement
 of the syllables, either by specifying the duration of each syllable
-explicitly, like in the example above, or by automatically aligning
-the lyrics to a melody or other voice of music, using @code{\addlyrics}
-or @code{\lyricsto}.
-@c  TODO: broken
-@c For more details see @ref{The Lyrics context}.
+explicitly, as in the example above, or by leaving the lyrics to be
+aligned automatically to a melody or other voice of music, using
+@code{\addlyrics} or @code{\lyricsto}.  The former method is
+described below in @ref{Manual syllable durations}.  The latter
+method is described in @ref{Automatic syllable durations}.
 
-A word or syllable of lyrics begins with an alphabetic character, and ends
-with
-any space or digit.  The following characters can be any character
-that is not a digit or white space.
+A word or syllable of lyrics begins with an alphabetic character
+(plus some other characters, see below) and is terminated by any
+white space or a digit.  Later characters in the syllable can be any
+character that is not a digit or white space.
 
-Any character that is not a digit or white space will be regarded as
-part of the syllable; one important consequence of this is that a word
-can end with @code{@}}, which often leads to the following mistake:
+Because any character that is not a digit or white space is regarded
+as part of the syllable, a word is valid even if it ends with
+@code{@}}, which often leads to the following mistake:
 
 @example
-\lyricmode @{ lah- lah@}
+\lyricmode @{ lah lah lah@}
 @end example
 
 In this example, the @code{@}} is included in the final syllable, so the
 opening brace is not balanced and the input file will probably not
-compile.
+compile.  Instead, braces should always be surrounded with white space:
 
+@example
+\lyricmode @{ lah lah lah @}
+@end example
 
-@funindex \property in \lyricmode
+@cindex overrides in lyric mode
+@funindex \override in \lyricmode
 
-@noindent
-Similarly, a period which follows an alphabetic sequence is included in
-the resulting string.  As a consequence, spaces must be inserted around
-property commands: do @emph{not} write
+Similarly, in lyric mode, a period will be included in the
+alphabetic sequence that it follows.  As a consequence, spaces
+must be inserted around the period in @code{\override} commands.
+Do @emph{not} write
 
 @example
 \override Score.LyricText #'font-shape = #'italic
@@ -151,104 +149,130 @@ but instead use
 \override Score . LyricText #'font-shape = #'italic
 @end example
 
-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.
+Punctuation, lyrics with accented characters, characters from
+non-English languages, or special characters (such as the heart
+symbol or slanted quotes), may simply be inserted directly
+into the input file, providing it is saved with UTF-8 encoding.
+For more information, see @ref{Text encoding}.
 
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[quote,verbatim]
 \relative c' { e4 f e d e f e2 }
-\addlyrics { He said: “Let my peo ple go”. }
+\addlyrics { He said: “Let my peo -- ple go.” }
 @end lilypond
 
-To use normal quotes in lyrics, add a backslash before the
-quotes.  For example,
+Normal quotes may be used in lyrics, but they have to be preceded
+with a backslash character and the whole syllable has to be
+enclosed between additional quotes.  For example,
 
-@lilypond[quote,ragged-right,fragment,verbatim]
+@lilypond[quote,verbatim]
 \relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
-\addlyrics { "\"I" am so lone- "ly\"" said she }
+\addlyrics { "\"I" am so lone -- "ly,\"" said she }
 @end lilypond
 
-The full definition of a word start in Lyrics mode is somewhat more
-complex.
-
-A word in Lyrics mode begins with: an alphabetic character, @code{_},
-@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
-through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
-any 8-bit character with ASCII code over 127, or a two-character
+The full definition of a word start in lyrics mode is somewhat more
+complex.  A word in lyrics mode is one that begins with an
+alphabetic character, @code{_}, @code{?}, @code{!}, @code{:},
+@code{'}, the control characters @code{^A} through @code{^F},
+@code{^Q} through @code{^W}, @code{^Y}, @code{^^}, any 8-bit
+character with an ASCII code over 127, or a two-character
 combination of a backslash followed by one of @code{`}, @code{'},
 @code{"}, or @code{^}.
 
 @c " to balance double quotes for not-so-bright context-sensitive editors
 
-To define variables containing lyrics, the function @code{lyricmode}
-must be used.
-
-@example
-verseOne = \lyricmode @{ Joy to the world the Lord is come @}
-\score @{
-  <<
-    \new Voice = "one" \relative c'' @{
-      \autoBeamOff
-      \time 2/4
-      c4 b8. a16 g4. f8 e4 d c2
-    @}
-    \addlyrics @{ \verseOne @}
-  >>
-@}
-@end example
-
-
 @seealso
+Learning Manual:
+@rlearning{Songs}.
+
 Notation Reference:
-@ref{Fonts}.
+@ref{Automatic syllable durations},
+@ref{Fonts},
+@ref{Input modes},
+@ref{Manual syllable durations}.
 
 Internals Reference:
-@rinternals{LyricText},
-@rinternals{LyricSpace}.
+@rinternals{LyricText}.
 
 
 @node Aligning lyrics to a melody
 @unnumberedsubsubsec Aligning lyrics to a melody
 
+@cindex lyrics, aligning to a melody
 @funindex \lyricmode
 @funindex \addlyrics
 @funindex \lyricsto
 
-@c TODO: 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
-@code{Lyrics}; see @rinternals{Lyrics}, for more.
+@code{Lyrics}, see @ref{Contexts explained}.
 
 @example
-\new Lyrics \lyricmode @dots{}
+\new Lyrics \lyricmode @{ @dots{} @}
 @end example
 
-There are two main methods to specify the horizontal placement
-of the syllables:
+Lyrics can be aligned with melodies in two main ways:
 
 @itemize
+
 @item
-by automatically aligning
-the lyrics to a melody or other voice of music, using @code{\addlyrics}
-or @code{\lyricsto}
+They can be aligned automatically, with the durations of the
+syllables being taken from an associated melody or other voice
+of music, using @code{\addlyrics} or @code{\lyricsto}.  See
+@ref{Automatic syllable durations}.
 
 @item
-or by specifying the duration of each syllable
-explicitly, using @code{\lyricmode}
+They can be aligned independently of the duration of any notes
+if the durations of the syllables are specified explicitly,
+and entered with @code{\lyricmode}.  See
+@ref{Manual syllable durations}.
+
 @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}.
+The following example compares different ways to align lyrics.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \new Voice = "one" \relative c'' {
+    \autoBeamOff
+    \time 2/4
+    c4 b8. a16 g4. f8 e4 d c2
+  }
+
+% uses default durations of 2;
+  \new Lyrics \lyricmode {
+    Joy to the earth!
+  }
+
+% explicit durations; left-aligned by default
+  \new Lyrics \lyricmode {
+    Joy4 to8. the16 world!4. the8 Lord4 is come.2
+  }
+
+% takes durations and alignment from notes in "one"
+  \new Lyrics \lyricsto "one" {
+    No more let sins and sor -- rows grow.
+  }
+>>
+@end lilypond
+
+The first stanza is not aligned with the notes because the durations
+were not specified, and the default value of 2 is used for each
+word.  This can be useful for dialogue over music; for more, see
+@ref{Dialogue over music}.
+
+The second stanza with explicitly specified durations is
+aligned to the notes because the durations are the same as the
+corresponding notes.  The words are left-aligned to the notes by
+default.  Useful if the words to different stanzas fit the notes in
+different ways.
 
+The third stanza shows the normal way of entering lyrics.
+
+@seealso
+Learning Manual:
+@rlearning{Aligning lyrics to a melody}.
+
+Internals Reference:
+@rinternals{Lyrics}.
 
 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
@@ -256,12 +280,21 @@ voice has nothing to do.  For methods of keeping contexts alive, see
 @cindex syllable durations, automatic
 @cindex lyrics and melodies
 
+Lyrics are aligned and typeset with the help of skips, hyphens and
+extender lines.
+
+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}.
+
 The lyrics can be aligned under a given melody
 automatically.  This is achieved by combining the
 melody and the lyrics with the @code{\lyricsto} expression
 
 @example
-\new Lyrics \lyricsto @var{name} @dots{}
+\new Lyrics \lyricsto @var{name} @{ @dots{} @}
 @end example
 
 @noindent
@@ -272,35 +305,12 @@ then the lyrics are specified with @code{\lyricsto}.  The command
 @code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
 @code{\lyricmode} keyword may be omitted.
 
-The following example uses different commands for entering lyrics.
-
-@lilypond[quote,fragment,ragged-right,verbatim]
-<<
-  \new Voice = "one" \relative c'' {
-    \autoBeamOff
-    \time 2/4
-    c4 b8. a16 g4. f8 e4 d c2
-  }
-
-% not recommended: left-aligned 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
-
-The second stanza is not properly aligned because the durations
-were not specified.  A solution for that would be to use @code{\lyricsto}.
 
 @cindex \addlyrics
 
-The @code{\addlyrics} command is actually just a convenient way
-to write a more complicated LilyPond structure that sets up the
-lyrics.
+The @code{\addlyrics} command is actually just a convenient shortcut
+that can sometimes be used instead of having to set up the lyrics
+through a more complicated LilyPond structure.
 
 @example
 @{ MUSIC @}
@@ -324,7 +334,7 @@ Here is an example,
 @end lilypond
 
 More stanzas can be added by adding more
-@code{\addlyrics} sections
+@code{\addlyrics} sections:
 
 @lilypond[ragged-right,verbatim,fragment,quote]
 \time 3/4
@@ -335,16 +345,16 @@ More stanzas can be added by adding more
 @end lilypond
 
 The command @code{\addlyrics} cannot handle polyphony settings.
-For these cases you should use @code{\lyricsto} and
+For these cases one should use @code{\lyricsto} and
 @code{\lyricmode}, for details see @ref{Entering lyrics}.
 
 @node Manual syllable durations
 @unnumberedsubsubsec Manual syllable durations
 
 Lyrics can also be entered without @code{\addlyrics} or
-@code{\lyricsto}.  In this case,
-syllables are entered like notes -- but with pitches replaced by text -- and the
-duration of each syllable must be entered explicitly.  For example:
+@code{\lyricsto}.  In this case, syllables are entered like
+notes -- but with pitches replaced by text -- and the duration
+of each syllable must be entered explicitly.  For example:
 
 @example
 play2 the4 game2.
@@ -359,23 +369,58 @@ The alignment to a melody can be specified with the
 @end example
 
 @noindent
+
+@c TODO setting associated voice does more than format extender
+@c lines.  Document it properly.  Does it have anything to do
+@c with manual durations in lyrics?
+
 The value of the property (here: @code{"lala"}) should be the name of
 a @code{Voice} context.  Without this setting, extender lines
 will not be formatted properly.
 
 Here is an example demonstrating manual lyric durations,
 
-@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
-<< \new Voice = "melody" {
+@lilypond[relative=1,verbatim,quote]
+<<
+  \new Voice = "melody" {
     \time 3/4
     c2 e4 g2.
- }
- \new Lyrics \lyricmode {
-   \set associatedVoice = #"melody"
-   play2 the4 game2.
- } >>
+  }
+  \new Lyrics \lyricmode {
+    \set associatedVoice = #"melody"
+    play2 the4 game2.
+  }
+>>
+@end lilypond
+
+In some complex vocal music, it may be desirable to place lyrics
+completely independently of notes.  In this case do not use
+@code{\lyricsto} or @code{\addlyrics} and do not set
+@code{associatedVoice}:
+
+@lilypond[quote,verbatim,ragged-right]
+<<
+  \new Staff {
+    \relative c'' {
+      c2 c2
+      d1
+    }
+  }
+  \new Lyrics {
+    \lyricmode {
+      I2 like4. my8 cat!1
+    }
+  }
+  \new Staff {
+    \relative c' {
+      c8 c c c c c c c
+      c8 c c c c c c c
+    }
+  }
+>>
 @end lilypond
 
+@c TODO see also feature request 707 - show how to do this with manual durations
 
 @seealso
 Notation Reference:
@@ -397,7 +442,7 @@ Internals Reference:
 In order to assign more than one syllable to a single note with
 spaces between the syllables, you can surround the phrase with
 quotes or use a @code{_} character.  Alternatively, you can use
-code the tilde  symbol (@code{~}) to get a lyric tie.  The lyric
+code the tilde symbol (@code{~}) to get a lyric tie.  The lyric
 tie is implemented with the Unicode character U+203F, so be
 sure to have a font (like DejaVuLGC) installed that includes this
 glyph.
@@ -416,116 +461,186 @@ 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
 @unnumberedsubsubsec Multiple notes to one syllable
 
 @cindex melisma
 @cindex melismata
 @cindex phrasing, in lyrics
+@funindex \melisma
+@funindex \melismaEnd
+
+Sometimes, particularly in Medieval music, several notes are to be
+sung on one syllable; such vocalises are called melismata, or
+@rglos{melisma}s.  The syllable to a melisma is usually
+left-aligned with the first note of the melisma.
+
+When a melisma occurs on a syllable other that the last one in a
+word, that syllable is usually joined to the following one with a
+hyphenated line.  This is indicated by placing a double hyphen,
+@code{--}, immediately after the syllable.
+
+Alternatively, when a melisma occurs on the last or only syllable in
+a word an extender line is usually drawn from the end of the syllable
+to the last note of the melisma.  This is indicated by placing a
+double underscore, @code{__}, immediately after the word.
 
-Sometimes, particularly in Medieval music, several notes are to be sung on one
-single syllable; such vocalises are called melismas, or melismata.
+There are five ways in which melismata can be indicated:
 
-@c this method seems to be the simplest; therefore
-@c it might be better to present it first - vv
+@itemize
+
+@item
+Melismata are created automatically over notes which are tied
+together:
+
+@lilypond[quote,relative=2,verbatim]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    f4 g2 ~ |
+    g4 e2 ~ |
+    e8
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ki -- ri -- e __
+  }
+>>
+@end lilypond
 
-You can define melismata entirely in the lyrics, by entering @code{_}
-for every extra note that has to be added to the melisma.
+@item
+Melismata can be created automatically from the music by placing
+slurs over the notes of each melisma.  This is the usual way of
+entering lyrics:
 
-@c TODO: clarify: __ is used to crate a lyric extender,
-@c _ is used to add a note to a melisma, so both __ and _ are needed.
+@lilypond[quote,relative=2,verbatim]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    f4 g8 ( f e f )
+    e8 ( d e2 )
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ki -- ri -- e __
+  }
+>>
+@end lilypond
 
-@c verbose! --FV
-@c duplicated: TODO fix
-Additionally, 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.
+@item
+Notes are considered a melisma if they are manually beamed,
+providing automatic beaming is switched off.  See
+@ref{Setting automatic beam behavior}.
 
-@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  }
-\addlyrics
- { Ky -- _ _ ri __ _ _ _  e }
+@lilypond[quote,relative=2,verbatim]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    \autoBeamOff
+    f4 g8[ f e f]
+    e2.
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ki -- ri -- e
+  }
+>>
 @end lilypond
 
-In this case, you can also have ties and slurs in the melody if you
-set @code{melismaBusyProperties}, as is done in the example above.
+Clearly this is not suited to melisma over notes which are longer
+than eighth notes.
 
-However, the @code{\lyricsto} command can also
-detect melismata automatically: it only puts one
-syllable under a tied or slurred group of notes.  If you want to force
-an unslurred group of notes to be a melisma, insert @code{\melisma}
-after the first note of the group, and @code{\melismaEnd} after the
-last one, e.g.,
+@item
+An unslurred group of notes will be treated as a melisma if they
+are bracketed between @code{\melisma} and @code{\melismaEnd}.
 
-@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+@lilypond[quote,relative=2,verbatim]
 <<
-  \new Voice = "lala" {
+  \new Voice = "melody" {
     \time 3/4
     f4 g8
     \melisma
     f e f
     \melismaEnd
-    e2
+    e2.
   }
-  \new Lyrics \lyricsto "lala" {
-    la di __ daah
+  \new Lyrics \lyricsto "melody" {
+    Ki -- ri -- e
   }
 >>
 @end lilypond
 
-In addition, notes are considered a melisma if they are manually
-beamed, and automatic beaming (see @ref{Setting automatic beam
-behavior}) is switched off.
+Note that this method cannot be used to indicate two melismata if
+the first one is immediately followed by another.
+
+@item
+A melisma can be defined entirely in the lyrics by entering a
+single underscore character, @code{_}, for every extra note that has
+to be added to the melisma.
 
-@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+@lilypond[verbatim, quote, relative=2]
 <<
-  \new Voice = "lala" {
+  \new Voice = "melody" {
     \time 3/4
-    \autoBeamOff
-    f4 g8[ f e f]
-    e2
+    f4 g8 f e f
+    e8 d e2
   }
-  \new Lyrics \lyricsto "lala" {
-    la di __ daah
+  \new Lyrics \lyricsto "melody" {
+    Ki -- ri -- _ _ _ e __ _ _
   }
 >>
 @end lilypond
 
-@c TODO: this now links to LM -vv
-@c   umm, yeah... so what?  -gp
+@end itemize
 
-@cindex SATB
-@cindex choral score
+It is possible to have ties, slurs and manual beams in the melody
+without their indicating melismata.  To do this, set
+@code{melismaBusyProperties} and indicate the melismata with single
+underscores in the lyrics, one underscore for each extra note:
 
-A complete example of a SATB score setup is in
-@rlearning{Vocal ensembles}.
+@lilypond[relative=1,verbatim,quote]
+<<
+  \new Voice = "melody" {
+    \time 3/4
+    \set melismaBusyProperties = #'()
+    c4 d ( e )
+    g8 [ f ] f4( e)
+    d e ~ e
+  }
+  \new Lyrics \lyricsto "melody" {
+    Ky -- _ _ _ _ ri -- _ _ e __ _
+  }
+>>
+@end lilypond
 
+Other settings for @code{melismaBusyProperties} can be used to
+include or exclude ties, slurs, and beams from the automatic
+detection of melismata; see @code{melismaBusyProperties} in
+@rinternals{Tunable context properties}.
 
 @predefined
-@funindex \melisma
+
+@code{\autoBeamOff},
+@code{\autoBeamOn},
 @code{\melisma},
-@funindex \melismaEnd
 @code{\melismaEnd}.
-@endpredefined
 
+@seealso
+Musical Glossary:
+@rglos{melisma}.
+
+Learning Manual:
+@rlearning{Aligning lyrics to a melody}.
 
-@c @seealso
-@c @lsr{vocal,lyric@/-combine.ly}.
+Notation Reference:
+@ref{Aligning lyrics to a melody},
+@ref{Automatic syllable durations},
+@ref{Setting automatic beam behavior}.
 
+Internals Reference:
+@rinternals{Tunable context properties}.
 
 @knownissues
 
-Melismata are not detected automatically, and extender lines must be
-inserted by hand.
+Extender lines under melismata are not created automatically; they
+must be inserted manually with a double underscore.
 
 @node Skipping notes
 @unnumberedsubsubsec Skipping notes
@@ -589,15 +704,14 @@ Internals Reference:
 @node Techniques specific to lyrics
 @subsection Techniques specific to lyrics
 
-@c TODO This whole section is to be reorganized. -vv
+@c TODO this whole section is to be reorganised
 
 @menu
 * Working with lyrics and variables::
+* Placement of lyrics::
 * Lyrics and repeats::
 * Divisi lyrics::
-* Lyrics independent of notes::
 * Spacing out syllables::
-* Placement of lyrics::
 @end menu
 
 
@@ -605,26 +719,27 @@ Internals Reference:
 @node Working with lyrics and variables
 @unnumberedsubsubsec Working with lyrics and variables
 
+@c TODO rewrite this section
+
 @cindex lyrics, variables
 
 To define variables containing lyrics, the function @code{\lyricmode}
-must be used.  You do not have to enter durations though, if you add
-@code{\addlyrics} or @code{\lyricsto}
-when invoking your variable.
+must be used.  Durations do not need to be added if the variable is
+to be invoked with @code{\addlyrics} or @code{\lyricsto}.
 
-@example
-verseOne = \lyricmode @{ Joy to the world the Lord is come @}
-\score @{
- <<
-   \new Voice = "one" \relative c'' @{
-     \autoBeamOff
-     \time 2/4
-     c4 b8. a16 g4. f8 e4 d c2
-   @}
-   \addlyrics @{ \verseOne @}
- >>
-@}
-@end example
+@lilypond[quote,verbatim]
+verseOne = \lyricmode { Joy to the world, the Lord is come. }
+\score {
+  <<
+    \new Voice = "one" \relative c'' {
+      \autoBeamOff
+      \time 2/4
+      c4 b8. a16 g4. f8 e4 d c2
+    }
+    \addlyrics { \verseOne }
+  >>
+}
+@end lilypond
 
 For different or more complex orderings, the best way is to set up the
 hierarchy of staves and lyrics first, e.g.,
@@ -638,7 +753,7 @@ hierarchy of staves and lyrics first, e.g.,
 @end example
 
 @noindent
-and then combine the appropriate melodies and lyric lines
+and then combine the appropriate melodies and lyric lines:
 
 @example
 \context Lyrics = sopranoLyrics \lyricsto "soprano"
@@ -649,52 +764,140 @@ and then combine the appropriate melodies and lyric lines
 The final input would resemble
 
 @example
-<<\new ChoirStaff << @emph{setup the music} >>
- \lyricsto "soprano" @emph{etc}
- \lyricsto "alto" @emph{etc}
-@emph{etc}
+<<
+  \new ChoirStaff <<
+    @emph{setup the music}
+  >>
+  \lyricsto "soprano" @emph{etc}
+  \lyricsto "alto" @emph{etc}
+  @emph{etc}
 >>
 @end example
 
-@ignore
-@c TODO
-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
+@seealso
+@c TODO: document \new Staff << Voice \lyricsto >> bug
+Internals Reference:
+@rinternals{LyricCombineMusic},
+@rinternals{Lyrics}.
 
 
-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:
+@node Placement of lyrics
+@unnumberedsubsubsec Placement of lyrics
 
-@example
-words = \lyrics{ %warning: this creates a new context
- one two
+@cindex placement of lyrics
+@cindex lyrics, positioning
+
+Depending on the type of music, lyrics may be positioned
+above the staff, below the staff, or between staves.  Placing
+lyrics below the associated staff is the easiest, and can be
+achieved by simply defining the Lyrics context below the Staff
+context:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        Here are the words
+      }
+    }
+  >>
 }
-<<
-  \new Voice = "sop" { c1 }
-  \new Lyrics \lyricsto "sop" { \words }
-  \new Voice = "alt" { c2 c }
-  \new Lyrics \lyricsto "alt" { \words }
->>
-@end example
+@end lilypond
 
-the problem is that \lyricsto will try to connect the "sop" melody with the context
-created by "\new Lyrics".
+Lyrics may be positioned above the staff using one of
+two methods.  The simplest is to use the same syntax as
+above and explicitly specify the position of the lyrics:
 
-Then \lyrics in \words creates another context, and the original "\new Lyrics" one
-remains empty.
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff = "staff" {
+      \new Voice = "melody" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics \with { alignAboveContext = "staff" } {
+      \lyricsto "melody" {
+        Here are the words
+      }
+    }
+  >>
+}
+@end lilypond
 
-@end ignore
+Alternatively, a two-step process may be used.  First the Lyrics
+context is declared (without any content) before the Staff and
+Voice contexts, then the @code{\lyricsto} command comes after
+the Voice declaration it references, as follows:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Lyrics = "lyrics"
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \context Lyrics = "lyrics" {
+      \lyricsto "melody" {
+        Here are the words
+      }
+    }
+  >>
+}
+@end lilypond
+
+When there are two voices on separate staves the lyrics may be
+placed between the staves using either of these methods.  Here
+is an example of the second method:
+
+@lilypond[quote,verbatim]
+\score {
+  \new ChoirStaff <<
+    \new Staff {
+      \new Voice = "sopranos" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics = "sopranos"
+    \new Lyrics = "contraltos"
+    \new Staff {
+      \new Voice = "contraltos" {
+        \relative c'' { a4 a a a }
+      }
+    }
+    \context Lyrics = "sopranos" {
+      \lyricsto "sopranos" {
+        Sop -- ra -- no words
+      }
+    }
+    \context Lyrics = "contraltos" {
+      \lyricsto "contraltos" {
+        Con -- tral -- to words
+      }
+    }
+  >>
+}
+@end lilypond
 
+Other combinations of lyrics and staves may be generated by
+elaborating these examples, or by examining the
+@rlearning{Vocal ensembles} templates in the Learning Manual.
 
 @seealso
-@c TODO: document \new Staff << Voice \lyricsto >> bug
-Internals Reference:
-@rinternals{LyricCombineMusic},
-@rinternals{Lyrics}.
+Learning Manual:
+@rlearning{Vocal ensembles}.
 
+Notation Reference:
+@ref{Aligning contexts},
+@ref{Creating contexts}.
 
 @node Lyrics and repeats
 @unnumberedsubsubsec Lyrics and repeats
@@ -759,8 +962,8 @@ unfolded.
 }
 @end lilypond
 
-If the repeated section has different words and is unfolded simply
-enter all the words:
+If the repeated section is to be unfolded and has different words,
+simply enter all the words:
 
 @lilypond[verbatim,quote,ragged-right]
 \score {
@@ -787,15 +990,15 @@ enter all the words:
 @cindex lyric skip
 @funindex \skip
 
-When the words to a repeated volta section are different the words
+When the words to a repeated volta section are different, the words
 to each repeat must be entered in separate @code{Lyrics} contexts.
 Earlier unrepeated sections must be skipped in the second and
 subsequent repeats.  The easiest way to skip several notes is to
 use @code{\repeat unfold} around the @code{\skip} command.
 
-Note: do not use an underscore, @code{_}, to skip notes as this
-indicates a melisma and will cause the preceding syllable to be
-left-aligned.
+Note: do not use an underscore, @code{_}, to skip notes in this
+particular case.  As this syntax indicates a melisma, it will cause
+the preceding syllable to be left-aligned.
 
 @warning{The @code{@bs{}skip} command must be followed by a number,
 but this number is ignored in lyrics which derive their durations
@@ -1068,90 +1271,72 @@ alternative sections these must be inserted manually.
 @node Divisi lyrics
 @unnumberedsubsubsec Divisi lyrics
 
-You can display alternate (or divisi) lyrics by naming voice
-contexts and attaching lyrics to those specific contexts.
+@cindex divided lyrics
+@cindex lyrics, divided
 
-@lilypond[verbatim,ragged-right,quote]
-\score{ <<
-  \new Voice = "melody" {
-    \relative c' {
-      c4
-      <<
-        { \voiceOne c8 e }
-        \new Voice = "splitpart" { \voiceTwo c4 }
-      >>
-      \oneVoice c4 c | c
+When just the words and rhythms of the two parts differ with the
+pitches remaining the same, temporarily turning off the automatic
+detection of melismata and indicating the melisma in the lyrics
+may be the appropriate method to use:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Voice = "melody" {
+      \relative c' {
+        \set melismaBusyProperties = #'()
+        \slurDown
+        \slurDashed
+        e4 e8 ( e ) c4 c |
+        \unset melismaBusyProperties
+        c
+      }
     }
-  }
-  \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
-  \new Lyrics \lyricsto "splitpart" { will }
->> }
+    \new Lyrics \lyricsto "melody" {
+      They shall not o -- ver -- come
+    }
+    \new Lyrics \lyricsto "melody" {
+      We will _
+    }
+  >>
+}
 @end lilypond
 
-
-You can use this trick to display different lyrics for a repeated
-section.
+When both music and words differ it may be better to display
+the differing music and lyrics by naming voice contexts and
+attaching lyrics to those specific contexts:
 
 @lilypond[verbatim,ragged-right,quote]
-\score{ <<
-  \new Voice = "melody" \relative c' {
-    c2 e | g e | c1 |
-    \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
-    a2 b | c1}
-  \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
-    do mi sol mi do
-    la si do }
-  \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
-   do re mi fa sol }
-  \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
-   dodo rere mimi fafa solsol }
->>
+\score {
+  <<
+    \new Voice = "melody" {
+      \relative c' {
+        <<
+          {
+            \voiceOne
+            e4 e8 e
+          }
+          \new Voice = "splitpart" {
+            \voiceTwo
+            c4 c
+          }
+        >>
+        \oneVoice
+        c4 c |
+        c
+      }
+    }
+    \new Lyrics \lyricsto "melody" {
+      They shall not o -- ver -- come
+    }
+    \new Lyrics \lyricsto "splitpart" {
+      We will
+    }
+  >>
 }
 @end lilypond
 
 
-
-@node 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
-inside @code{lyricrhythm} disappears into the
-@code{Devnull} context, but the rhythms can still be used
-to place the lyrics.
-
-@lilypond[quote,verbatim,ragged-right]
-voice = {
-  c''2
-  \tag #'music { c''2 }
-  \tag #'lyricrhythm { c''4. c''8 }
-  d''1
-}
-
-lyr = \lyricmode { I like my cat! }
-
-<<
-  \new Staff \keepWithTag #'music \voice
-  \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
-  \new Lyrics \lyricsto "nowhere" \lyr
-  \new Staff { c'8 c' c' c' c' c' c' c'
-  c' c' c' c' c' c' c' c' }
->>
-@end lilypond
-
-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 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
 @unnumberedsubsubsec Spacing out syllables
 
@@ -1238,124 +1423,6 @@ To make lyrics avoid bar lines as well, use
 @end ignore
 
 
-@node Placement of lyrics
-@unnumberedsubsubsec Placement of lyrics
-
-@cindex placement of lyrics
-@cindex lyrics, positioning
-
-@c TODO Add text from -user
-
-Lyrics are positioned above the staff, below the staff, or between
-staves, depending on the type of music.  To place lyrics below the
-associated staff simply define the Lyrics context below the Staff
-context:
-
-@lilypond[quote,verbatim]
-\score {
-  <<
-    \new Staff {
-      \new Voice = "melody" {
-        \relative c'' { c4 c c c }
-      }
-    }
-    \new Lyrics {
-      \lyricsto "melody" {
-        Here are the words
-      }
-    }
-  >>
-}
-@end lilypond
-
-To position lyrics above the staff, place the declaration of the
-Lyrics context before the Staff and Voice contexts, but the
-@code{\lyricsto} command must come after the Voice declaration it
-references, like this:
-
-@lilypond[quote,verbatim]
-\score {
-  <<
-    \new Lyrics = "lyrics"
-    \new Staff {
-      \new Voice = "melody" {
-        \relative c'' { c4 c c c }
-      }
-    }
-    \context Lyrics = "lyrics" {
-      \lyricsto "melody" {
-        Here are the words
-      }
-    }
-  >>
-}
-@end lilypond
-
-Alternatively, the position of the lyrics may be specified
-explicitly:
-
-@lilypond[quote,verbatim]
-\score {
-  <<
-    \new Staff = "staff" {
-      \new Voice = "melody" {
-        \relative c'' { c4 c c c }
-      }
-    }
-    \new Lyrics \with { alignAboveContext = "staff" } {
-      \lyricsto "melody" {
-        Here are the words
-      }
-    }
-  >>
-}
-@end lilypond
-
-When there are two voices on separate staves the lyrics may be
-placed between the staves using either of these methods.  Here
-is an example of the first method:
-
-@lilypond[quote,verbatim]
-\score {
-  \new ChoirStaff <<
-    \new Staff {
-      \new Voice = "sopranos" {
-        \relative c'' { c4 c c c }
-      }
-    }
-    \new Lyrics = "sopranos"
-    \new Lyrics = "contraltos"
-    \new Staff {
-      \new Voice = "contraltos" {
-        \relative c'' { a4 a a a }
-      }
-    }
-    \context Lyrics = "sopranos" {
-      \lyricsto "sopranos" {
-        Sop -- ra -- no words
-      }
-    }
-    \context Lyrics = "contraltos" {
-      \lyricsto "contraltos" {
-        Con -- tral -- to words
-      }
-    }
-  >>
-}
-@end lilypond
-
-Other combinations of lyrics and staves may be generated by
-elaborating these examples, or by examining the SATB templates in
-the Learning Manual.
-
-@seealso
-Learning Manual:
-@rlearning{Vocal ensembles}.
-
-Notation Reference:
-@ref{Aligning contexts},
-@ref{Creating contexts}.
-
 @node Stanzas
 @subsection Stanzas