]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/vocal.itely
Doc-hu: Fundamental concepts: nitpicks
[lilypond.git] / Documentation / notation / vocal.itely
index 3736331f836ad8867ef97c46b871345a512481f0..671db19355b7ffa3b1fbb0893548aae16ffb808b 100644 (file)
@@ -3,7 +3,8 @@
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
-    version that you are working on.  See TRANSLATION for details.
+    version that you are working on.  For details, see the Contributors'
+    Guide, node Updating translation committishes..
 @end ignore
 
 @c \version "2.12.0"
 @end ignore
 
 @c \version "2.12.0"
@@ -18,38 +19,43 @@ that the lyrics will be aligned with the notes of their melody.
 
 @menu
 * Common notation for vocal music::
 
 @menu
 * Common notation for vocal music::
-* Entering lyrics::
-* Aligning lyrics to a melody::
-* Specific uses of lyrics::
+* Techniques specific to lyrics::
 * Stanzas::
 * Stanzas::
+* Songs::
+* Choral::
+* Opera and stage musicals::
+* Chants psalms and hymns::
+* Ancient vocal music::
+
 @end menu
 
 
 @node Common notation for vocal music
 @subsection Common notation for vocal music
 
 @end menu
 
 
 @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.
+This section discusses issues common to most types of vocal music.
 
 @menu
 
 @menu
-* References for vocal music and lyrics::
-* Opera::
-* Song books::
-* Spoken music::
-* Chants::
-* Ancient vocal music::
+* References for vocal music::
+* Entering lyrics::
+* Aligning lyrics to a melody::
+* Automatic syllable durations::
+* Manual syllable durations::
+* Multiple syllables to one note::
+* Multiple notes to one syllable::
+* Skipping notes::
+* Extenders and hyphens::
 @end menu
 
 
 @end menu
 
 
-@node References for vocal music and lyrics
-@unnumberedsubsubsec References for vocal music and lyrics
+@node References for vocal music
+@unnumberedsubsubsec References for vocal music
 
 
-@c TODO: split this section in two parts? -vv
-
-Various issues may arise when engraving vocal music.  Some of these
-are discussed in this section, while others are explained elsewhere:
+This section indicates where to find details of notation issues
+that may arise in any type of vocal music.
 
 @itemize
 
 @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}.
 @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}.
@@ -60,94 +66,20 @@ for lyrics of for other text elements (character's names, etc.).
 This syntax is described in @ref{Text markup introduction}.
 
 @item
 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}.
-
-@item
-@q{Ambitus} may be added at the beginning of vocal staves, as explained
+@notation{Ambitus} may be added at the beginning of vocal staves, as explained
 in @ref{Ambitus}.
 
 in @ref{Ambitus}.
 
-@item
-Vocal parts may be printed using traditional clefs, as shown in @ref{Clef}.
-
-@item
-Ancient vocal music is supported, as explained in @ref{Ancient notation}.
 @end itemize
 
 @end itemize
 
-
-@node Opera
-@unnumberedsubsubsec Opera
-
-@c TODO
-TBC
-
-@c add characters names snippet -vv
-
-@node Song books
-@unnumberedsubsubsec Song books
-
-@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
 @seealso
-Notation Reference:
-@ref{Ancient notation}.
-
+Music Glossary:
+@rglos{ambitus}.
 
 @node Entering lyrics
 
 @node Entering lyrics
-@subsection Entering lyrics
+@unnumberedsubsubsec 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
+Lyrics are entered in lyric mode.  This section explains how this
+done.
 
 @cindex lyrics
 @funindex \lyricmode
 
 @cindex lyrics
 @funindex \lyricmode
@@ -155,7 +87,7 @@ Notation Reference:
 @cindex spaces, in lyrics
 @cindex quotes, in lyrics
 
 @cindex spaces, in lyrics
 @cindex quotes, in lyrics
 
-@c FIXME: this section is to be rewritten.
+@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
 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
@@ -219,30 +151,6 @@ but instead use
 \override Score . LyricText #'font-shape = #'italic
 @end example
 
 \override Score . LyricText #'font-shape = #'italic
 @end example
 
-@funindex _
-@cindex spaces, in lyrics
-@cindex quotes, in lyrics
-@cindex ties, in lyrics
-
-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.
-
-@lilypond[quote,ragged-right,fragment,verbatim]
-\time 3/4
-\relative c' { c2 e4 g2 e4 }
-\addlyrics { gran- de_a- mi- go }
-\addlyrics { pu- "ro y ho-" nes- to }
-\addlyrics { pu- ro~y~ho- nes- to }
-@end lilypond
-
-@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
@@ -300,147 +208,14 @@ Internals Reference:
 @rinternals{LyricSpace}.
 
 
 @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
-@unnumberedsubsubsec Working with lyrics and variables
-
-@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.
-
-@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
-
-For different or more complex orderings, the best way is to setup the
-hierarchy of staves and lyrics first, e.g.,
-@example
-\new ChoirStaff <<
-  \new Voice = "soprano" @{ @emph{music} @}
-  \new Lyrics = "sopranoLyrics" @{ s1 @}
-  \new Lyrics = "tenorLyrics" @{ s1 @}
-  \new Voice = "tenor" @{ @emph{music} @}
->>
-@end example
-
-and then combine the appropriate melodies and lyric lines
-
-@example
-\context Lyrics = sopranoLyrics \lyricsto "soprano"
-@emph{the lyrics}
-@end example
-
-@noindent
-
-The final input would resemble
-
-@example
-<<\new ChoirStaff << @emph{setup the music} >>
- \lyricsto "soprano" @emph{etc}
- \lyricsto "alto" @emph{etc}
-@emph{etc}
->>
-@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
-Internals Reference:
-@rinternals{LyricCombineMusic},
-@rinternals{Lyrics}.
-
-
 @node Aligning lyrics to a melody
 @node Aligning lyrics to a melody
-@subsection Aligning lyrics to a melody
+@unnumberedsubsubsec Aligning lyrics to a melody
 
 @funindex \lyricmode
 @funindex \addlyrics
 @funindex \lyricsto
 
 
 @funindex \lyricmode
 @funindex \addlyrics
 @funindex \lyricsto
 
-@c FIXME: this stuff is to be rewritten. -vv
+@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.
 
 Aligning of text with melodies can be made automatically, but if you
 specify the durations of the syllables it can also be made manually.
@@ -448,7 +223,7 @@ 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
 hyphens and extender lines.
 
 Lyrics are printed by interpreting them in the context called
-@rinternals{Lyrics}.
+@code{Lyrics}; see @rinternals{Lyrics}, for more.
 
 @example
 \new Lyrics \lyricmode @dots{}
 
 @example
 \new Lyrics \lyricmode @dots{}
@@ -461,7 +236,7 @@ of the syllables:
 @item
 by automatically aligning
 the lyrics to a melody or other voice of music, using @code{\addlyrics}
 @item
 by automatically aligning
 the lyrics to a melody or other voice of music, using @code{\addlyrics}
-or @code{\lyricsto}.
+or @code{\lyricsto}
 
 @item
 or by specifying the duration of each syllable
 
 @item
 or by specifying the duration of each syllable
@@ -475,20 +250,10 @@ voice has nothing to do.  For methods of keeping contexts alive, see
 @ref{Keeping contexts alive}.
 
 
 @ref{Keeping contexts alive}.
 
 
-@menu
-* Automatic syllable durations::
-* Manual syllable durations::
-* Multiple syllables to one note::
-* Multiple notes to one syllable::
-* Skipping notes::
-* Extenders and hyphens::
-* Lyrics and repeats::
-@end menu
-
 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
 
 @node Automatic syllable durations
 @unnumberedsubsubsec Automatic syllable durations
 
-@cindex automatic syllable durations
+@cindex syllable durations, automatic
 @cindex lyrics and melodies
 
 The lyrics can be aligned under a given melody
 @cindex lyrics and melodies
 
 The lyrics can be aligned under a given melody
@@ -499,8 +264,9 @@ melody and the lyrics with the @code{\lyricsto} expression
 \new Lyrics \lyricsto @var{name} @dots{}
 @end example
 
 \new Lyrics \lyricsto @var{name} @dots{}
 @end example
 
+@noindent
 This aligns the lyrics to the
 This aligns the lyrics to the
-notes of the @rinternals{Voice} context called @var{name}, which must
+notes of the @code{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
@@ -516,7 +282,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-aligned 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
@@ -530,6 +296,8 @@ The following example uses different commands for entering lyrics.
 The second stanza is not properly aligned because the durations
 were not specified.  A solution for that would be to use @code{\lyricsto}.
 
 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 way
 to write a more complicated LilyPond structure that sets up the
 lyrics.
@@ -547,6 +315,29 @@ is the same as
 \new Lyrics \lyricsto "blah" @{ LYRICS @}
 @end example
 
 \new Lyrics \lyricsto "blah" @{ LYRICS @}
 @end example
 
+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}, for details see @ref{Entering lyrics}.
+
 @node Manual syllable durations
 @unnumberedsubsubsec Manual syllable durations
 
 @node Manual syllable durations
 @unnumberedsubsubsec Manual syllable durations
 
@@ -569,7 +360,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 @rinternals{Voice} context.  Without this setting, extender lines
+a @code{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,
@@ -591,23 +382,25 @@ Notation Reference:
 @ref{Keeping contexts alive}.
 
 Internals Reference:
 @ref{Keeping contexts alive}.
 
 Internals Reference:
-@rinternals{Lyrics}.
+@rinternals{Lyrics},
+@rinternals{Voice}.
 
 
 @node Multiple syllables to one note
 @unnumberedsubsubsec Multiple syllables to one note
 
 
 
 @node Multiple syllables to one note
 @unnumberedsubsubsec Multiple syllables to one note
 
-
 @funindex _
 @funindex _
+@cindex spaces, in lyrics
+@cindex quotes, in lyrics
 @cindex ties, in lyrics
 
 @cindex ties, in lyrics
 
-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@footnote{The lyric ties is implemented with the Unicode character
-U+203F, so be
-sure to have a font (Like DejaVuLGC) installed that includes this
-glyph.}.
+In order to assign more than one syllable to a single note with
+spaces between the syllables, you can surround the phrase with
+quotes or use a @code{_} character.  Alternatively, you can use
+code the tilde  symbol (@code{~}) to get a lyric tie.  The lyric
+tie is implemented with the Unicode character U+203F, so be
+sure to have a font (like DejaVuLGC) installed that includes this
+glyph.
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 \time 3/4
 
 @lilypond[quote,ragged-right,fragment,verbatim]
 \time 3/4
@@ -622,6 +415,7 @@ glyph.}.
 Internals Reference:
 @rinternals{LyricCombineMusic}.
 
 Internals Reference:
 @rinternals{LyricCombineMusic}.
 
+
 @c Here come the section which used to be "Melismata"
 @c the new title might be more self-explanatory
 
 @c Here come the section which used to be "Melismata"
 @c the new title might be more self-explanatory
 
@@ -642,19 +436,19 @@ single syllable; such vocalises are called melismas, or melismata.
 You can define melismata entirely in the lyrics, by entering @code{_}
 for every extra note that has to be added to the melisma.
 
 You can define melismata entirely in the lyrics, by entering @code{_}
 for every extra note that has to be added to the melisma.
 
-@c FIXME: clarify: __ is used to crate a lyric extender,
+@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.
 
 @c verbose! --FV
 @c duplicated: TODO fix
 @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
+Additionally, you can make an extender line to be typeset to indicate
 the melisma in the score, writing a double underscore next to the
 the melisma in the score, writing a double underscore next to the
-first syllable of the melisma. This example shows the three elements
+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.
 
 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
+@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  }
@@ -692,12 +486,27 @@ 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 FIXME: this now links to LM -vv
-
-@cindex SATB
-@cindex choral score
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+<<
+  \new Voice = "lala" {
+    \time 3/4
+    \autoBeamOff
+    f4 g8[ f e f]
+    e2
+  }
+  \new Lyrics \lyricsto "lala" {
+    la di __ daah
+  }
+>>
+@end lilypond
+
+@c TODO: this now links to LM -vv
+@c   umm, yeah... so what?  -gp
+
+@cindex SATB
+@cindex choral score
 
 
-A complete example of a SATB score setup is in section
+A complete example of a SATB score setup is in
 @rlearning{Vocal ensembles}.
 
 
 @rlearning{Vocal ensembles}.
 
 
@@ -709,7 +518,7 @@ A complete example of a SATB score setup is in section
 @endpredefined
 
 
 @endpredefined
 
 
-@seealso
+@c @seealso
 @c @lsr{vocal,lyric@/-combine.ly}.
 
 
 @c @lsr{vocal,lyric@/-combine.ly}.
 
 
@@ -727,8 +536,6 @@ 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.
 
 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]
 \relative c' { c c g' }
 \addlyrics {
 @lilypond[verbatim,ragged-right,quote]
 \relative c' { c c g' }
 \addlyrics {
@@ -774,32 +581,294 @@ distance between two syllables) and the @code{minimum-length}
 @seealso
 Internals Reference:
 @rinternals{LyricExtender},
 @seealso
 Internals Reference:
 @rinternals{LyricExtender},
-@rinternals{LyricHyphen}
+@rinternals{LyricHyphen}.
+
+
+@node Techniques specific to lyrics
+@subsection Techniques specific to lyrics
+
+@c TODO This whole section is to be reorganized. -vv
+
+@menu
+* Working with lyrics and variables::
+* Lyrics and repeats::
+* Divisi lyrics::
+* Lyrics independent of notes::
+* Spacing out syllables::
+* Placement of lyrics between staves::
+@end menu
+
+
+
+@node Working with lyrics and variables
+@unnumberedsubsubsec Working with lyrics and variables
+
+@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.
+
+@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
+
+For different or more complex orderings, the best way is to set up the
+hierarchy of staves and lyrics first, e.g.,
+@example
+\new ChoirStaff <<
+  \new Voice = "soprano" @{ @emph{music} @}
+  \new Lyrics = "sopranoLyrics" @{ s1 @}
+  \new Lyrics = "tenorLyrics" @{ s1 @}
+  \new Voice = "tenor" @{ @emph{music} @}
+>>
+@end example
+
+@noindent
+and then combine the appropriate melodies and lyric lines
+
+@example
+\context Lyrics = sopranoLyrics \lyricsto "soprano"
+@emph{the lyrics}
+@end example
+
+@noindent
+The final input would resemble
+
+@example
+<<\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
+
+
+Be careful when defining a variable with lyrics that creates a new
+context, for example, using the deprecated @code{\lyrics} command.  See
+the next erroneous example:
+
+@example
+words = \lyrics{ %warning: this creates a new context
+ one two
+}
+<<
+  \new Voice = "sop" { c1 }
+  \new Lyrics \lyricsto "sop" { \words }
+  \new Voice = "alt" { c2 c }
+  \new Lyrics \lyricsto "alt" { \words }
+>>
+@end example
+
+the problem is that \lyricsto will try to connect the "sop" melody with the context
+created by "\new Lyrics".
+
+Then \lyrics in \words creates another context, and the original "\new Lyrics" one
+remains empty.
+
+@end ignore
+
+
+@seealso
+@c TODO: document \new Staff << Voice \lyricsto >> bug
+Internals Reference:
+@rinternals{LyricCombineMusic},
+@rinternals{Lyrics}.
 
 
 @node Lyrics and repeats
 @unnumberedsubsubsec Lyrics and repeats
 
 
 
 @node Lyrics and repeats
 @unnumberedsubsubsec Lyrics and repeats
 
-@c TODO New section.  Add text
-TBC
+@cindex repeats and lyrics
 
 
+@c see http://lists.gnu.org/archive/html/lilypond-user/2010-07/msg00022.html
+@c see http://lists.gnu.org/archive/html/lilypond-user/2010-06/msg00472.html
 
 
-@node Specific uses of lyrics
-@subsection Specific uses of lyrics
+@subheading Simple repeats
 
 
-@c FIXME This whole section is to be reorganized. -vv
+Repeats in @emph{music} are fully described elsewhere; see
+@ref{Repeats}.  This section explains how to add lyrics to repeated
+sections of music.
 
 
-Often, different stanzas of one song are put to one melody in slightly
-differing ways.  Such variations can still be captured with
-@code{\lyricsto}.
+Lyrics to a volta repeat can be written exactly as if the music was
+not repeated, if the words are unchanged.
 
 
-@menu
-* Divisi lyrics::
-* Lyrics independent of notes::
-* Spacing out syllables::
-* Centering lyrics between staves::
-@end menu
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+          a4 a a a
+          \repeat volta 2 { b4 b b b }
+        }
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        Not re -- peat -- ed.
+        Re -- peat -- ed twice.
+      }
+    }
+  >>
+}
+@end lilypond
+
+But if an unfold repeat is used, both the lyrics and the music must
+be repeated (assuming the repeated words are the same), otherwise
+the repeated section will have no lyrics.
+
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+          a4 a a a
+          \repeat unfold 2 { b4 b b b }
+        }
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        Not re -- peat -- ed.
+        \repeat unfold 2 { Re -- peat -- ed twice. }
+      }
+    }
+  >>
+}
+@end lilypond
+
+If the repeated section has different words and is unfolded simply
+enter all the words:
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+          a4 a a a
+          \repeat unfold 2 { b4 b b b }
+        }
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        Not re -- peat -- ed.
+        The first time words.
+        Sec -- ond time words.
+      }
+    }
+  >>
+}
+@end lilypond
+
+When the words to a repeated volta section are different the words
+to each repeat must 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}.
+
+@warning{The @code{\skip} command must be followed by a number,
+but this number is ignored in lyric mode.  Each @code{\skip} skips
+a single note of any value, irrespective of the value of the
+following number.}
+
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+          a4 a a a
+          \repeat volta 2 { b4 b b b }
+        }
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        Not re -- peat -- ed.
+        The first time words.
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        % skip 4 notes of any duration
+        \repeat unfold 4 { \skip 1 }
+        Sec -- ond time words.
+      }
+    }
+  >>
+}
+@end lilypond
+
+An alternative way, which avoids having to count notes, is to use a
+temporary voice for the repeated section.  This may be useful if
+the earlier sections are still subject to change.  A temporary voice
+can be inserted anywhere in the main music stream in parallel with
+it, as shown below, but it may be necessary to keep the main voice
+alive in complex scores when using this technique; see
+@ref{Keeping contexts alive}.
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "singleVoice" {
+        \relative c'' { a4 a a a }
+        \new Voice = "repeatVoice" {
+          \relative c'' \repeat volta 3 { b4 b b b }
+        }
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics <<
+      \lyricsto "singleVoice" {
+        Not re -- peat -- ed.
+        The end sec -- tion.
+      }
+      \lyricsto "repeatVoice" {
+        The first time words.
+      }
+    >>
+    \new Lyrics {
+      \lyricsto "repeatVoice" {
+        Sec -- ond time words.
+      }
+    }
+    \new Lyrics {
+      \lyricsto "repeatVoice" {
+        The third time words.
+      }
+    }
+  >>
+}
+@end lilypond
+
+@c TODO lowering a common line of lyrics
 
 
+@subheading Repeats with alternative endings
+
+TBC
 
 
 @node Divisi lyrics
 
 
 @node Divisi lyrics
@@ -880,7 +949,7 @@ lyr = \lyricmode { I like my cat! }
 
 This method is recommended only if the music in the @code{Devnull}
 context does not contain melismata.  Melismata are defined by the
 
 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
+@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.
 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.
@@ -895,8 +964,8 @@ the implicit melismata get ignored.
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
-To increase the spacing between lyrics, set the minimum-distance property of
-LyricSpace.
+To increase the spacing between lyrics, set the @code{minimum-distance}
+property of @code{LyricSpace}.
 
 @lilypond[relative,verbatim,fragment,quote,ragged-right]
 {
 
 @lilypond[relative,verbatim,fragment,quote,ragged-right]
 {
@@ -910,6 +979,7 @@ LyricSpace.
 }
 @end lilypond
 
 }
 @end lilypond
 
+@noindent
 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.
 
@@ -974,10 +1044,11 @@ To make lyrics avoid bar lines as well, use
 @end ignore
 
 
 @end ignore
 
 
-@node Centering lyrics between staves
-@unnumberedsubsubsec Centering lyrics between staves
+@node Placement of lyrics between staves
+@unnumberedsubsubsec Placement of lyrics between staves
 
 @c TODO Add text from -user
 
 @c TODO Add text from -user
+@c TODO Add new spacing properties, centering lyrics, etc
 TBC
 
 @node Stanzas
 TBC
 
 @node Stanzas
@@ -1099,6 +1170,10 @@ the line, just like instrument names.  They are created by setting
 @node Stanzas with different rhythms
 @unnumberedsubsubsec Stanzas with different rhythms
 
 @node Stanzas with different rhythms
 @unnumberedsubsubsec Stanzas with different rhythms
 
+Often, different stanzas of one song are put to one melody in slightly
+differing ways.  Such variations can still be captured with
+@code{\lyricsto}.
+
 @subsubheading Ignoring melismata
 
 One possibility is that the text has a melisma in one stanza, but
 @subsubheading Ignoring melismata
 
 One possibility is that the text has a melisma in one stanza, but
@@ -1134,6 +1209,52 @@ 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.
 
 @code{\set} and @code{\unset} to bracket the lyrics where melismata
 are to be ignored.
 
+@subsubheading Adding syllables to grace notes
+
+By default, grace notes (e.g. via @code{\grace}) do not get assigned
+syllables when using @code{\lyricsto}, but this behavior can be
+changed:
+
+@lilypond[verbatim,ragged-right,quote]
+\relative c' {
+  f4 \appoggiatura a32 b4
+  \grace { f16[ a16] } b2
+  \afterGrace b2 { f16[ a16] }
+  \appoggiatura a32 b4
+  \acciaccatura a8 b4
+}
+\addlyrics {
+  normal
+  \set includeGraceNotes = ##t
+  case,
+  gra -- ce case,
+  after -- grace case,
+  \set ignoreMelismata = ##t
+  app. case,
+  acc. case.
+}
+@end lilypond
+
+@knownissues
+Like for @code{associatedVoice}, @code{includeGraceNotes} needs to be
+set at latest one syllable before the one which is to be put under a
+grace note.  For the case of a grace note at the very beginning of a
+piece of music, consider using a @code{\with} or @code{\context}
+block:
+
+@lilypond[verbatim,ragged-right,quote]
+<<
+  \new Voice = melody \relative c' {
+    \grace { c16[( d e f] }
+    g1) f
+  }
+  \new Lyrics \with { includeGraceNotes = ##t }
+  \lyricsto melody {
+    Ah __ fa
+  }
+>>
+@end lilypond
+
 @subsubheading Switching to an alternative melody
 
 More complex variations in text underlay are possible.  It is possible
 @subsubheading Switching to an alternative melody
 
 More complex variations in text underlay are possible.  It is possible
@@ -1197,7 +1318,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
+@c TODO: 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
@@ -1339,5 +1460,924 @@ Internals Reference:
 @rinternals{StanzaNumber}.
 
 
 @rinternals{StanzaNumber}.
 
 
+@node Songs
+@subsection Songs
+
+@menu
+* References for songs::
+* Lead sheets::
+@end menu
+
+@node References for songs
+@unnumberedsubsubsec References for songs
+
+@c TODO chords, setting simple songs (LM), stanzas
+TBC
+
+@node Lead sheets
+@unnumberedsubsubsec Lead sheets
+
+Lead sheets may be printed by combining vocal parts and @q{chord mode};
+this syntax is explained in @ref{Chord notation}.
+
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{simple-lead-sheet.ly}
+
+@seealso
+Notation Reference:
+@ref{Chord notation}.
+
+
+@node Choral
+@subsection Choral
+
+@cindex anthems
+@cindex part songs
+@cindex oratorio
+@cindex SATB
+
+This section discusses notation issues that relate most directly
+to choral music.  This includes anthems, part songs, oratorio,
+etc.
+
+@menu
+* References for choral::
+* Score layouts for choral::
+* Divided voices::
+@end menu
+
+@node References for choral
+@unnumberedsubsubsec References for choral
+
+Choral music is usually notated on two, three or four staves within
+a @code{ChoirStaff} group.  Accompaniment, if required, is placed
+beneath in a @code{PianoStaff} group, which is usually reduced in
+size for @emph{a capella} choral works.  The notes for each vocal
+part are placed in a @code{Voice} context, with each staff
+being given either a single vocal part (i.e., one @code{Voice}) or
+a pair of vocal parts (i.e., two @code{Voice}s).
+
+Words are placed in @code{Lyrics} contexts, either underneath each
+corresponding music staff, or one above and one below the music
+staff if this contains the music for two parts.
+
+Several common topics in choral music are described fully elsewhere:
+
+@itemize
+
+@item
+An introduction to creating an SATB vocal score can be found in
+the Learning Manual, see @rlearning{Four-part SATB vocal score}.
+
+@item
+Several templates suitable for various styles of choral music can
+also be found in the Learning Manual, see
+@rlearning{Vocal ensembles}.
+
+@item
+For information about @code{ChoirStaff} and @code{PianoStaff} see
+@ref{Grouping staves}.
+
+@item
+Shape noteheads, as used in Sacred Harp and similar notation, are
+described in @ref{Shape note heads}.
+
+@item
+When two vocal parts share a staff the stems, ties, slurs, etc., of
+the higher part will be directed up and those of the lower part
+down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
+@ref{Single-staff polyphony}.
+
+@end itemize
+
+@predefined
+@code{\oneVoice},
+@code{\voiceOne},
+@code{\voiceTwo}.
+
+@seealso
+Learning Manual:
+@rlearning{Four-part SATB vocal score},
+@rlearning{Vocal ensembles}.
+
+Notation Reference:
+@ref{Context layout order},
+@ref{Grouping staves},
+@ref{Shape note heads},
+@ref{Single-staff polyphony}.
+
+Internals Reference:
+@rinternals{ChoirStaff},
+@rinternals{Lyrics},
+@rinternals{PianoStaff}.
+
+@node Score layouts for choral
+@unnumberedsubsubsec Score layouts for choral
+
+Choral music containing four staves, with or without piano
+accompaniment, is usually laid out with two systems per page.
+Depending on the page size, achieving this may require changes
+to several default settings.  The following settings should be
+considered:
+
+@itemize
+
+@item
+The global staff size can be modified to change the overall size
+of the elements of the score.  See @ref{Setting the staff size}.
+
+@item
+The distances between the systems, the staves and the lyrics can
+all be adjusted independently.  See @ref{Vertical spacing}.
+
+@item
+The dimensions of the vertical layout variables can be displayed as
+an aid to adjusting the vertical spacing.  This and other
+possibilities for fitting the music onto fewer pages are described
+in @ref{Fitting music onto fewer pages}.
+
+@item
+If the number of systems per page changes from one to two it is
+customary to indicate this with a system separator mark between
+the two systems.  See @ref{Separating systems}.
+
+@item
+For details of other page formatting properties, see
+@ref{Page formatting}.
+
+@end itemize
+
+
+Dynamic markings by default are placed below the staff, but in
+choral music they are usually placed above the staff in order to
+avoid the lyrics.  The predefined command @code{\dynamicUp} does
+this for the dynamic markings in a single @code{Voice} context.
+If there are many @code{Voice} contexts this predefined command
+would have to be placed in every one.  Alternatively its expanded
+form can be used to place all dynamic markings in the entire score
+above their respective staves, as shown here:
+
+@lilypond[verbatim,quote]
+\score {
+  \new ChoirStaff <<
+    \new Staff {
+      \new Voice {
+        \relative c'' { g4\f g g g }
+      }
+    }
+    \new Staff {
+      \new Voice {
+        \relative c' { d4 d d\p d }
+      }
+    }
+  >>
+  \layout {
+    \context {
+      \Score
+      \override DynamicText #'direction = #UP
+      \override DynamicLineSpanner #'direction = #UP
+    }
+  }
+}
+@end lilypond
+
+@predefined
+@code{\dynamicUp}, @code{\dynamicDown}, @code{\dynamicNeutral}.
+
+@seealso
+Notation Reference:
+@ref{Changing spacing},
+@ref{Displaying spacing},
+@ref{Fitting music onto fewer pages},
+@ref{Page formatting},
+@ref{Score layout},
+See @ref{Separating systems},
+@ref{Setting the staff size},
+@ref{Using an extra voice for breaks},
+@ref{Vertical spacing}.
+
+Internals Reference:
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
+
+
+@node Divided voices
+@unnumberedsubsubsec Divided voices
+
+@cindex voices, divided
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{using-arpeggiobracket-to-make-divisi-more-visible.ly}
+
+@seealso
+Notation Reference:
+@ref{Expressive marks as lines}.
+
+
+@node Opera and stage musicals
+@subsection Opera and stage musicals
+
+The music, lyrics and dialogue to opera and stage musicals are
+usually set out in one or more of the following forms:
+
+@itemize
+
+@item
+A @emph{Conductors' Score} containing the full orchestral and vocal
+parts, together with libretto cues if there are spoken passages.
+
+@item
+@emph{Orchestral Parts} containing the music for the individual
+instruments of the orchestra or band.
+
+@item
+A @emph{Vocal Score} containing all vocal parts with piano
+accompaniment.  The accompaniment is usually an orchestral
+reduction, and if so the name of the original orchestral instrument
+is often indicated.  Vocal scores sometimes includes stage
+directions and libretto cues.
+
+@item
+A @emph{Vocal Book} containing just the vocal parts
+(no accompaniment), sometimes combined with the libretto.
+
+@item
+A @emph{Libretto} containing the extended passages of spoken
+dialogue usually found in musicals, together with the words to the
+sung parts.  Stage directions are usually included.  LilyPond can
+be used to typeset libretti but as they contain no music
+alternative methods may be preferable.
+
+@end itemize
+
+The sections in the LilyPond documentation which cover the topics
+needed to create scores in the styles commonly found in opera and
+musicals are indicated in the References below.  This is followed
+by sections covering those techniques which are peculiar to
+typesetting opera and musical scores.
+
+@menu
+* References for opera and stage musicals::
+* Character names::
+* Spoken music::
+* Dialogue over music::
+@end menu
+
+@node References for opera and stage musicals
+@unnumberedsubsubsec References for opera and stage musicals
+
+@itemize
+
+@item
+A conductors' score contains many grouped staves and lyrics.  Ways
+of grouping staves is shown in @ref{Grouping staves}.  To nest
+groups of staves see @ref{Nested staff groups}.
+
+@item
+The printing of empty staves in conductors' scores and vocal scores
+is often suppressed.  To create such a @qq{Frenched score} see
+@ref{Hiding staves}.
+
+@item
+Writing orchestral parts is covered in @ref{Writing parts}.
+Other sections in the Specialist notation chapter may be relevant,
+depending on the orchestration used.  Many instruments are
+transposing instruments, see @ref{Instrument transpositions}.
+
+@item
+If the number of systems per page changes from page to page it is
+customary to separate the systems with a system separator mark.
+See @ref{Separating systems}.
+
+@item
+For details of other page formatting properties, see
+@ref{Page formatting}.
+
+@item
+Musical cues can be inserted with the @code{\cueDuring} predefined
+command.  For details of its use see @ref{Formatting cue notes}.
+
+@item
+Dialogue cues and stage directions can be inserted with markup.
+See @ref{Text}.  Extensive stage directions can be inserted with
+a section of stand-alone markup between two @code{\score} blocks.
+See @ref{Separate text}.
+
+@end itemize
+
+@predefined
+@code{\cueDuring},
+@code{\quoteDuring}.
+
+@seealso
+Musical Glossary:
+@rglos{cue-notes},
+@rglos{Frenched score},
+@rglos{Frenched staves},
+@rglos{transposing instrument}.
+
+Notation Manual:
+@ref{Grouping staves},
+@ref{Hiding staves},
+@ref{Instrument names},
+@ref{Instrument transpositions},
+@ref{Nested staff groups},
+@ref{Page formatting},
+@ref{Selecting font and font size},
+@ref{Separating systems},
+@ref{Text},
+@ref{Transpose},
+@ref{Writing parts},
+@ref{Writing text}.
+
+
+@node Character names
+@unnumberedsubsubsec Character names
+
+@cindex character names
+@cindex names, character
+
+Character names are usually shown to the left of the staff when the
+staff is dedicated to that character alone.  The instrument name can
+be used for this purpose.
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+  <<
+    \new Staff {
+      \set Staff.instrumentName = #"Kaspar"
+      \set Staff.shortInstrumentName = #"Kas"
+      \relative c' {
+        \clef "G_8"
+        c4 c c c
+        \break
+        c4 c c c
+      }
+    }
+    \new Staff {
+      \set Staff.instrumentName = #"Melchior"
+      \set Staff.shortInstrumentName = #"Mel"
+      \clef "bass"
+      \relative c' {
+        a4 a a a
+        a4 a a a
+      }
+    }
+  >>
+}
+@end lilypond
+
+When two or more characters share a staff the character's name is
+usually printed above the staff at the start of every section
+applying to that character.  This can be done with markup.  Often a
+specific font is used for this purpose.
+
+@lilypond[quote,verbatim,relative=1]
+\override TextScript #'font-family = #'typewriter
+\override TextScript #'font-size = #2
+\clef "G_8"
+c4^\markup Kaspar
+c c c
+\clef "bass"
+a4^\markup Melchior
+a a a
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Instrument names},
+@ref{Selecting font and font size},
+@ref{Text}.
+
+
+@node Spoken music
+@unnumberedsubsubsec Spoken music
+
+@cindex parlato
+@cindex Sprechgesang
+Such effects as @q{parlato} or @q{Sprechgesang} require performers to speak
+without pitch but still with rhythm; these are notated by cross
+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 Dialogue over music
+@unnumberedsubsubsec Dialogue over music
+
+TBC
+
+
+@node Chants psalms and hymns
+@subsection Chants psalms and hymns
+
+@cindex chants
+@cindex psalms
+@cindex hymns
+@cindex religious music
+
+The music and words for chants, psalms and hymns usually follow a
+well-established format in any particular church.  Although the
+formats may differ from church to church the type-setting problems
+which arise are broadly similar, and are covered in this section.
+
+@menu
+* References for chants and psalms::
+* Setting a chant::
+* Pointing a psalm::
+* Partial measures in hymn tunes::
+@end menu
+
+@node References for chants and psalms
+@unnumberedsubsubsec References for chants and psalms
+
+Typesetting Gregorian chant in various styles of ancient notation
+is described in @ref{Ancient notation}.
+
+@seealso
+Notation reference:
+@ref{Ancient notation}.
+
+
+@node Setting a chant
+@unnumberedsubsubsec Setting a chant
+
+Modern chant settings use modern notation with varying numbers of
+elements taken from ancient notation.  Some of the elements and
+methods to consider are shown here.
+
+Chants often use quarter notes without stems to indicate the pitch,
+with the rhythm being taken from the spoken rhythm of the words.
+
+@lilypond[verbatim,quote]
+stemOff = { \override Staff.Stem #'transparent = ##t }
+
+\relative c' {
+  \stemOff
+  a'4 b c2 |
+}
+
+@end lilypond
+
+Chants often omit the bar lines or use shortened or dotted bar
+lines to indicate pauses in the music.  To omit all bar lines from
+all staves remove the bar line engraver completely:
+
+@lilypond[verbatim,quote]
+\score {
+  \new StaffGroup <<
+    \new Staff {
+      \relative c'' {
+        a4 b c2 |
+        a4 b c2 |
+        a4 b c2 |
+      }
+    }
+    \new Staff {
+      \relative c'' {
+        a4 b c2 |
+        a4 b c2 |
+        a4 b c2 |
+      }
+    }
+  >>
+  \layout {
+    \context {
+      \Staff
+      \remove Bar_engraver
+    }
+  }
+}
+@end lilypond
+
+Bar lines can also be removed on a staff-by-staff basis:
+
+@lilypond[verbatim, quote]
+\score {
+  \new ChoirStaff <<
+    \new Staff
+    \with { \remove Bar_engraver } {
+      \relative c'' {
+        a4 b c2 |
+        a4 b c2 |
+        a4 b c2 |
+      }
+    }
+    \new Staff {
+      \relative c'' {
+        a4 b c2 |
+        a4 b c2 |
+        a4 b c2 |
+      }
+    }
+  >>
+}
+@end lilypond
+
+To remove bar lines from just a section of music treat it as a
+cadenza.  If the section is long you may need to insert dummy
+barlines with @code{\bar ""} to show where the line should break.
+
+@lilypond[verbatim,quote,relative=2]
+a4 b c2 |
+\cadenzaOn
+a4 b c2
+a4 b c2
+\bar ""
+a4 b c2
+a4 b c2
+\cadenzaOff
+a4 b c2 |
+a4 b c2 |
+@end lilypond
+
+Rests or pauses in chants can be indicated by modified bar lines.
+
+@lilypond[verbatim, quote,relative=2]
+a4
+\cadenzaOn
+b c2
+a4 b c2
+\bar "'"
+a4 b c2
+a4 b c2
+\bar ":"
+a4 b c2
+\bar "dashed"
+a4 b c2
+\bar "||"
+@end lilypond
+
+Alternatively, the notation used in Gregorian chant for pauses or
+rests is sometimes used even though the rest of the notation is
+modern.  This uses a modified @code{\breathe} mark:
+
+@lilypond[verbatim,quote]
+divisioMinima = {
+  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-minima
+  \once \override BreathingSign  #'Y-offset = #0
+  \breathe
+}
+divisioMaior = {
+  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maior
+  \once \override BreathingSign  #'Y-offset = #0
+  \breathe
+}
+divisioMaxima = {
+  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maxima
+  \once \override BreathingSign  #'Y-offset = #0
+  \breathe
+}
+finalis = {
+  \once \override BreathingSign  #'stencil = #ly:breathing-sign::finalis
+  \once \override BreathingSign  #'Y-offset = #0
+  \breathe
+}
+
+\score {
+  \relative c'' {
+    g2 a4 g
+    \divisioMinima
+    g2 a4 g
+    \divisioMaior
+    g2 a4 g
+    \divisioMaxima
+    g2 a4 g
+    \finalis
+  }
+  \layout {
+    \context {
+      \Staff
+      \remove Bar_engraver
+    }
+  }
+}
+@end lilypond
+
+Chants usually omit the time signature and often omit the clef too.
+
+@lilypond[verbatim,quote]
+\score {
+  \new Staff {
+    \relative c'' {
+      a4 b c2 |
+      a4 b c2 |
+      a4 b c2 |
+    }
+  }
+  \layout {
+    \context {
+      \Staff
+      \remove Bar_engraver
+      \remove Time_signature_engraver
+      \remove Clef_engraver
+    }
+  }
+}
+@end lilypond
+
+Chants for psalms in the Anglican tradition are usually either
+@emph{single}, with 7 bars of music, or @emph{double}, with two lots
+of 7 bars.  Each group of 7 bars is divided into two halves,
+corresponding to the two halves of each verse, usually separated by
+a double bar line.  Only whole and half notes are used.  The 1st bar
+in each half always contains a single chord of whole notes.  This is
+the @qq{reciting note}.  Chants are usually centered on the page.
+
+@lilypond[verbatim,quote]
+SopranoMusic = \relative g' {
+  g1 | c2 b | a1 | \bar "||"
+  a1 | d2 c | c b | c1 | \bar "||"
+}
+
+AltoMusic = \relative c' {
+  e1 | g2 g | f1 |
+  f1 | f2 e | d d | e1 |
+}
+
+TenorMusic = \relative a {
+  c1 | c2 c | c1 |
+  d1 | g,2 g | g g | g1 |
+}
+
+BassMusic =  \relative c {
+  c1 | e2 e | f1 |
+  d1 | b2 c | g' g | c,1 |
+}
+
+global = {
+  \time 2/2
+}
+
+% Use markup to center the chant on the page
+\markup {
+  \fill-line {
+    \score {  % centered
+      <<
+        \new ChoirStaff <<
+          \new Staff <<
+            \global
+            \clef "treble"
+            \new Voice = "Soprano" <<
+              \voiceOne
+              \SopranoMusic
+            >>
+            \new Voice = "Alto" <<
+              \voiceTwo
+              \AltoMusic
+            >>
+          >>
+          \new Staff <<
+            \clef "bass"
+            \global
+            \new Voice = "Tenor" <<
+              \voiceOne
+              \TenorMusic
+            >>
+            \new Voice = "Bass" <<
+              \voiceTwo
+              \BassMusic
+            >>
+          >>
+        >>
+      >>
+      \layout {
+        \context {
+          \Score
+          \override SpacingSpanner
+          #'base-shortest-duration = #(ly:make-moment 1 2)
+        }
+        \context {
+          \Staff
+          \remove "Time_signature_engraver"
+        }
+      }
+    }  % End score
+  }
+}  % End markup
+@end lilypond
+
+Some other approaches to setting such a chant are shown in the first
+of the following snippets.
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{chant-or-psalms-notation.ly}
+
+Canticles and other liturgical texts may be set more freely, and
+may use notational elements from ancient music.  Often the words
+are shown underneath and aligned with the notes.  If so, the notes
+are spaced in accordance with the syllables rather than the notes'
+durations.
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{ancient-notation-template----modern-transcription-of-gregorian-music.ly}
+
+@seealso
+Learning Manual:
+@rlearning{Visibility and color of objects},
+@rlearning{Vocal ensembles}.
+
+Notation Reference:
+@ref{Ancient notation},
+@ref{Bar lines},
+@ref{Modifying context plug-ins},
+@ref{Typesetting Gregorian chant},
+@ref{Unmetered music},
+@ref{Visibility of objects}.
+
+
+@node Pointing a psalm
+@unnumberedsubsubsec Pointing a psalm
+
+The words to an Anglican psalm are usually printed in separate
+verses centered underneath the chant.
+
+Single chants (with 7 bars) are repeated for every verse.  Double
+chants (with 14 bars) are repeated for every pair of verses.  Marks
+are inserted in the words to show how they should be fitted to the
+chant.  Each verse is divided into two halves.  A colon is usually
+used to indicate this division.  This corresponds to the double bar
+line in the music.  The words before the colon are sung to the first
+three bars of music; the words after the colon are sung to the last
+four bars.
+
+Single bar lines (or in some psalters an inverted comma or similar
+symbol) are inserted between words to indicate where the bar lines
+in the music fall.  In markup mode a single bar line can be entered
+with the bar check symbol, @code{|}.
+
+@lilypond[verbatim,quote]
+\markup {
+  \fill-line {
+    \column {
+      \left-align {
+        \line { O come let us sing | unto the | Lord : let }
+        \line { us heartily rejoice in the | strength of | our }
+        \line { sal- | -vation. }
+      }
+    }
+  }
+}
+@end lilypond
+
+Other symbols may require glyphs from the @code{fetaMusic} fonts.
+For details, see @ref{Fonts}.
+
+@lilypond[verbatim,quote]
+tick = \markup {
+  \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
+}
+\markup {
+  \fill-line {
+    \column {
+      \left-align {
+        \line { O come let us sing \tick unto the \tick Lord : let }
+        \line {
+          us heartily rejoice in the \tick strength of \tick our
+        }
+        \line { sal \tick vation. }
+      }
+    }
+  }
+}
+@end lilypond
+
+Where there is one whole note in a bar all the words corresponding
+to that bar are recited on that one note in speech rhythm.  Where
+there are two notes in a bar there will usually be only one or two
+corresponding syllables.  If there are more that two syllables a
+dot is usually inserted to indicate where the change in note occurs.
+
+@lilypond[verbatim,quote]
+dot = \markup {
+  \raise #0.7 \musicglyph #"dots.dot"
+}
+tick = \markup {
+  \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
+}
+\markup {
+  \fill-line {
+    \column {
+      \left-align {
+        \line {
+          O come let us sing \tick unto \dot the \tick Lord : let
+        }
+        \line {
+          us heartily rejoice in the \tick strength of \tick our
+        }
+        \line { sal \tick vation. }
+      }
+    }
+  }
+}
+@end lilypond
+
+In some psalters an asterisk is used to indicate a break in a
+recited section instead of a comma, and stressed or slightly
+lengthened syllables are indicated in bold text.
+
+@lilypond[verbatim,quote]
+dot = \markup {
+  \raise #0.7 \musicglyph #"dots.dot"
+}
+tick = \markup {
+  \raise #1 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
+}
+\markup {
+  \fill-line {
+    \column {
+      \left-align {
+        \line { Today if ye will hear his voice * }
+        \line {
+          \concat { \bold hard en }
+          | not your | hearts : as in the pro-
+        }
+        \line { vocation * and as in the \bold day of tempt- | }
+        \line { -ation | in the | wilderness. }
+      }
+    }
+  }
+}
+@end lilypond
+
+In other psalters an accent is placed over the syllable to indicate
+stress.
+
+@lilypond[verbatim,quote]
+tick = \markup {
+  \raise #2 \fontsize #-5 \musicglyph #"scripts.rvarcomma"
+}
+\markup {
+  \fill-line {
+    \column {
+      \left-align {
+        \line {
+          O come let us \concat {
+            si \combine \tick ng
+          }
+          | unto the | Lord : let
+        }
+        \line {
+          us heartily \concat {
+            rejo \combine \tick ice
+          }
+          in the | strength of | our
+        }
+        \line { sal- | -vation. }
+      }
+    }
+  }
+}
+@end lilypond
+
+The use of markup to center text, and arrange lines in columns is
+described in @ref{Formatting text}.
+
+Most of these elements are shown in one or other of the two verses
+in the template, see @qq{Psalms} in @rlearning{Vocal ensembles}.
+
+@seealso
+Learning Manual:
+@rlearning{Vocal ensembles}.
+
+Notation Reference:
+@ref{Fonts},
+@ref{Formatting text}.
+
+
+@node Partial measures in hymn tunes
+@unnumberedsubsubsec Partial measures in hymn tunes
+
+Hymn tunes frequently start and end every line of music with
+partial measures so that each line of music corresponds exactly
+with a line of text.  This requires a @code{\partial} command at
+the start of the music and @code{\bar "|"} or @code{\bar "||"}
+commands at the end of each line.
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{hymn-template.ly}
+
+
+@node Ancient vocal music
+@subsection Ancient vocal music
+
+Ancient vocal music is supported, as explained in @ref{Ancient notation}.
+
+@c TODO
+
+@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}.
+
+