--- /dev/null
+@c -*- coding: utf-8; mode: texinfo; -*-
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
+@end ignore
+
+@c \version "2.14.0"
+
+@node Vocal music
+@section Vocal music
+
+@lilypondfile[quote]{vocal-headword.ly}
+
+This section explains how to typeset vocal music, and make sure
+that the lyrics will be aligned with the notes of their melody.
+
+@menu
+* Common notation for vocal music::
+* Techniques specific to lyrics::
+* 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
+
+This section discusses issues common to most types of vocal music.
+
+@menu
+* 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::
+* Extenders and hyphens::
+@end menu
+
+
+@node References for vocal music
+@unnumberedsubsubsec References for vocal music
+
+This section indicates where to find details of notation issues
+that may arise in any type of vocal music.
+
+@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
+Vocal music is likely to require the use of @code{markup} mode,
+either for lyrics or for other text elements (characters' names,
+etc.) This syntax is described in @ref{Text markup introduction}.
+
+@item
+@notation{Ambitus} may be added at the beginning of vocal staves,
+as explained in @ref{Ambitus}.
+
+@item
+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, as explained in @ref{Score layouts for choral}.
+
+@end itemize
+
+@seealso
+Music Glossary:
+@rglos{ambitus}.
+
+Learning Manual:
+@rlearning{Setting simple songs}.
+
+Notation Reference:
+@ref{Text markup introduction},
+@ref{Ambitus},
+@ref{Score layouts for choral}.
+
+Snippets:
+@rlsr{Vocal music}.
+
+@node Entering lyrics
+@unnumberedsubsubsec Entering lyrics
+
+@cindex lyrics, entering
+@cindex entering lyrics
+@cindex formatting in lyrics
+@cindex lyrics, formatting
+@cindex punctuation in lyrics
+@cindex lyrics punctuation
+@cindex spaces in lyrics
+@cindex quotes in lyrics
+@funindex \lyricmode
+
+@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 special input 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 @{ Three4 blind mice,2 three4 blind mice2 @}
+@end example
+
+There are two main methods for specifying the horizontal placement
+of the syllables, either by specifying the duration of each syllable
+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
+(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.
+
+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 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. Instead, braces should always be surrounded with white space:
+
+@example
+\lyricmode @{ lah lah lah @}
+@end example
+
+@cindex overrides in lyric mode
+@funindex \override in \lyricmode
+
+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
+@end example
+
+@noindent
+but instead use
+
+@example
+\override Score . LyricText #'font-shape = #'italic
+@end example
+
+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,verbatim]
+\relative c'' { d8 c16 a bes8 f e' d c4 }
+\addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
+@end lilypond
+
+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,verbatim]
+\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
+\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 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
+
+Great control over the appearance of lyrics comes from using
+@code{\markup} inside the lyrics themselves. For explanation of many
+options, see @ref{Formatting text}.
+
+@snippets
+
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{formatting-lyrics-syllables.ly}
+
+
+@seealso
+Learning Manual:
+@rlearning{Songs}.
+
+Notation Reference:
+@ref{Automatic syllable durations},
+@ref{Fonts},
+@ref{Formatting text},
+@ref{Input modes},
+@ref{Manual syllable durations},
+@ref{Text encoding}.
+
+Internals Reference:
+@rinternals{LyricText}.
+
+Snippets:
+@rlsr{Text}
+
+@node Aligning lyrics to a melody
+@unnumberedsubsubsec Aligning lyrics to a melody
+
+@cindex lyrics, aligning to a melody
+@cindex @code{associatedVoice}
+@funindex \lyricmode
+@funindex \addlyrics
+@funindex \lyricsto
+
+Lyrics are printed by interpreting them in the context called
+@code{Lyrics}, see @ref{Contexts explained}.
+
+@example
+\new Lyrics \lyricmode @{ @dots{} @}
+@end example
+
+Lyrics can be aligned with melodies in two main ways:
+
+@itemize
+
+@item
+Lyrics can be aligned automatically, with the durations of the
+syllables being taken from another voice of music or (in special
+circumstances) an associated melody, using @code{\addlyrics},
+@code{\lyricsto}, or by setting the @code{associatedVoice} property.
+For more details, see @ref{Automatic syllable durations}.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+ \new Staff <<
+ \time 2/4
+ \new Voice = "one" \relative c'' {
+ \voiceOne
+ c4 b8. a16 g4. r8 a4 ( b ) c2
+ }
+ \new Voice = "two" \relative c' {
+ \voiceTwo
+ s2 s4. f8 e4 d c2
+ }
+ >>
+
+% takes durations and alignment from notes in "one"
+ \new Lyrics \lyricsto "one" {
+ Life is __ _ love, live __ life.
+ }
+
+% takes durations and alignment from notes in "one" initially
+% then switches to "two"
+ \new Lyrics \lyricsto "one" {
+ No more let
+ \set associatedVoice = "two" % must be set one syllable early
+ sins and sor -- rows grow.
+ }
+>>
+@end lilypond
+
+The first stanza shows the normal way of entering lyrics.
+
+The second stanza shows how the voice from which the lyric
+durations are taken can be changed. This is useful if the words to
+different stanzas fit the notes in different ways and all the
+durations are available in Voice contexts. For more details, see
+@ref{Stanzas}.
+
+@item
+Lyrics can be aligned independently of the duration of any notes
+if the durations of the syllables are specified explicitly,
+and entered with @code{\lyricmode}.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+ \new Voice = "one" \relative c'' {
+ \time 2/4
+ c4 b8. a16 g4. f8 e4 d c2
+ }
+
+% uses previous explicit duration of 2;
+ \new Lyrics \lyricmode {
+ Joy to the earth!
+ }
+
+% explicit durations, set to a different rhythm
+ \new Lyrics \lyricmode {
+ Life4 is love,2. live4 life.2
+ }
+>>
+@end lilypond
+
+The first stanza is not aligned with the notes because the durations
+were not specified, and the previous value of 2 is used for each
+word.
+
+The second stanza shows how the words can be aligned quite
+independently from the notes. This is useful if the words to
+different stanzas fit the notes in different ways and the required
+durations are not available in a music context. For more details
+see @ref{Manual syllable durations}. This technique is also useful
+when setting dialogue over music; for examples showing this, see
+@ref{Dialogue over music}.
+
+When entered in this way the words are left-aligned to the notes
+by default, but may be center-aligned to the notes of a melody by
+specifying an associated voice, if one exists. For details, see
+@ref{Manual syllable durations}.
+
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Aligning lyrics to a melody}.
+
+Notation Reference:
+@ref{Contexts explained},
+@ref{Automatic syllable durations}.
+@ref{Stanzas},
+@ref{Manual syllable durations},
+@ref{Dialogue over music},
+@ref{Manual syllable durations}.
+
+Internals Reference:
+@rinternals{Lyrics}.
+
+@node Automatic syllable durations
+@unnumberedsubsubsec Automatic syllable durations
+
+@cindex syllable durations, automatic
+@cindex lyrics and melodies
+@cindex associatedVoice
+@funindex \addlyrics
+@funindex \lyricsto
+
+Lyrics can be automatically aligned to the notes of a melody in
+three ways:
+
+@itemize
+
+@item
+by specifying the named Voice context containing the melody with
+@code{\lyricsto},
+
+@item
+by introducing the lyrics with @code{\addlyrics} and placing them
+immediately after the Voice context containing the melody,
+
+@item
+by setting the @code{associatedVoice} property, the alignment of
+the lyrics may be switched to a different named Voice context at
+any musical moment.
+
+@end itemize
+
+In all three methods hyphens can be drawn between the syllables of
+a word and extender lines can be drawn beyond the end of a word. For
+details, see @ref{Extenders and hyphens}.
+
+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}.
+
+@subheading Using @code{\lyricsto}
+
+@cindex \lyricsto
+@funindex \lyricsto
+
+Lyrics can be aligned under a melody automatically by specifying
+the named Voice context containing the melody with
+@code{\lyricsto}:
+
+@lilypond[quote,verbatim,relative=2]
+<<
+ \new Voice = "melody" {
+ a4 a a a
+ }
+ \new Lyrics \lyricsto "melody" {
+ These are the words
+ }
+>>
+@end lilypond
+
+@noindent
+This aligns the lyrics to the notes of the named @code{Voice}
+context, which must already exist. Therefore normally the
+@code{Voice} context is specified first, followed by the
+@code{Lyrics} context. The lyrics themselves follow the
+@code{\lyricsto} command. The @code{\lyricsto} command
+invokes lyric mode automatically, so the @code{\lyricmode} keyword
+may be omitted. By default, the lyrics are placed underneath the
+notes. For other placements, see @ref{Placing lyrics vertically}.
+
+@subheading Using @code{\addlyrics}
+
+@cindex \addlyrics
+@funindex \addlyrics
+
+The @code{\addlyrics} command is 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 @}
+\addlyrics @{ LYRICS @}
+@end example
+
+@noindent
+is the same as
+
+@example
+\new Voice = "blah" @{ MUSIC @}
+\new Lyrics \lyricsto "blah" @{ LYRICS @}
+@end example
+
+Here is an example,
+
+@lilypond[verbatim,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,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 polyphonic settings.
+For these cases one should use @code{\lyricsto}.
+
+@subheading Using associatedVoice
+
+The melody to which the lyrics are being aligned can be changed by
+setting the @code{associatedVoice} property,
+
+@example
+\set associatedVoice = #"lala"
+@end example
+
+@noindent
+
+The value of the property (here: @code{"lala"}) should be the name
+of a @code{Voice} context. For technical reasons, the @code{\set}
+command must be placed one syllable before the one to which the
+change in voice is to apply.
+
+Here is an example demonstrating its use:
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+ \new Staff <<
+ \time 2/4
+ \new Voice = "one" \relative c'' {
+ \voiceOne
+ c4 b8. a16 g4. r8 a4 ( b ) c2
+ }
+ \new Voice = "two" \relative c' {
+ \voiceTwo
+ s2 s4. f8 e8 d4. c2
+ }
+ >>
+% takes durations and alignment from notes in "one" initially
+% then switches to "two"
+ \new Lyrics \lyricsto "one" {
+ No more let
+ \set associatedVoice = "two" % must be set one syllable early
+ sins and sor -- rows grow.
+ }
+>>
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Extenders and hyphens},
+@ref{Keeping contexts alive},
+@ref{Placing lyrics vertically}.
+
+@node Manual syllable durations
+@unnumberedsubsubsec Manual syllable durations
+
+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}. Syllables are entered like notes --
+but with pitches replaced by text -- and the duration of each
+syllable is entered explicitly after the syllable.
+
+By default, syllables will be left-aligned to the corresponding
+musical moment. Hyphenated lines may be drawn between syllables
+as usual, but extender lines cannot be drawn when there is no
+associated voice.
+
+Here are two examples:
+
+@lilypond[relative=1,verbatim,quote]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ c2 e4 g2 f
+ }
+ \new Lyrics \lyricmode {
+ play1 the4 game4
+ }
+>>
+@end lilypond
+
+
+@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
+
+This technique is useful when writing dialogue over music, see
+@ref{Dialogue over music}.
+
+To center-align syllables on the notes at the corresponding musical
+moments, set @code{associatedVoice} to the name of the Voice context
+containing those notes. When @code{associatedVoice} is set, both
+double hyphens and double underscores can be used to draw
+hyphenated lines and extenders under melismata correctly.
+
+@lilypond[relative=1,verbatim,quote]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ c2 e4 g f g
+ }
+ \new Lyrics \lyricmode {
+ \set associatedVoice = #"melody"
+ play2 the4 game2. __
+ }
+>>
+@end lilypond
+
+@c TODO see also feature request 707 - show how to do this with manual durations
+
+@seealso
+Notation Reference:
+@ref{Dialogue over music}.
+
+Internals Reference:
+@rinternals{Lyrics},
+@rinternals{Voice}.
+
+
+@node Multiple syllables to one note
+@unnumberedsubsubsec Multiple syllables to one note
+
+@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 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 use a font for this glyph which actually contains it.
+Freely available fonts with a lyric tie are, for example,
+`FreeSerif' (a Times clone), `DejaVuSans' (but not
+`DejaVuSerif'), or `TeXGyreSchola' (a Century Schoolbook
+clone).
+
+@lilypond[quote,ragged-right,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
+
+
+@seealso
+Internals Reference:
+@rinternals{LyricCombineMusic}.
+
+
+@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.
+
+There are five ways in which melismata can be indicated:
+
+@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" {
+ Ky -- ri -- e __
+ }
+>>
+@end lilypond
+
+@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:
+
+@lilypond[quote,relative=2,verbatim]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ f4 g8 ( f e f )
+ e8 ( d e2 )
+ }
+ \new Lyrics \lyricsto "melody" {
+ Ky -- ri -- e __
+ }
+>>
+@end lilypond
+
+@item
+Notes are considered a melisma if they are manually beamed,
+providing automatic beaming is switched off. See
+@ref{Setting automatic beam behavior}.
+
+@lilypond[quote,relative=2,verbatim]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ \autoBeamOff
+ f4 g8[ f e f]
+ e2.
+ }
+ \new Lyrics \lyricsto "melody" {
+ Ky -- ri -- e
+ }
+>>
+@end lilypond
+
+Clearly this is not suited to melismata over notes which are longer
+than eighth notes.
+
+@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,verbatim]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ f4 g8
+ \melisma
+ f e f
+ \melismaEnd
+ e2.
+ }
+ \new Lyrics \lyricsto "melody" {
+ Ky -- ri -- e
+ }
+>>
+@end lilypond
+
+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[verbatim, quote, relative=2]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ f4 g8 f e f
+ e8 d e2
+ }
+ \new Lyrics \lyricsto "melody" {
+ Ky -- ri -- _ _ _ e __ _ _
+ }
+>>
+@end lilypond
+
+@end itemize
+
+It is possible to have ties, slurs and manual beams in the melody
+without their indicating melismata. To do this, set
+@code{melismaBusyProperties}:
+
+@lilypond[relative=1,verbatim,quote]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ \set melismaBusyProperties = #'()
+ c4 d ( e )
+ g8 [ f ] f4 ~ f
+ }
+ \new Lyrics \lyricsto "melody" {
+ Ky -- ri -- e e -- le -- i -- son
+ }
+>>
+@end lilypond
+
+Other settings for @code{melismaBusyProperties} can be used to
+selectively include or exclude ties, slurs, and beams from the
+automatic detection of melismata; see @code{melismaBusyProperties}
+in @rinternals{Tunable context properties}.
+
+Alternatively, if all melismata indications are to be ignored,
+@code{ignoreMelismata} may be set true;
+see @ref{Stanzas with different rhythms}.
+
+If a melisma is required during a passage in which
+@code{melismaBusyProperties} is active, it may be indicated by
+placing a single underscore in the lyrics for each note which
+should be included in the melisma:
+
+@lilypond[relative=1,verbatim,quote]
+<<
+ \new Voice = "melody" {
+ \time 3/4
+ \set melismaBusyProperties = #'()
+ c4 d ( e )
+ g8 [ f ] ~ f4 ~ f
+ }
+ \new Lyrics \lyricsto "melody" {
+ Ky -- ri -- _ e __ _ _ _
+ }
+>>
+@end lilypond
+
+
+@predefined
+
+@code{\autoBeamOff},
+@code{\autoBeamOn},
+@code{\melisma},
+@code{\melismaEnd}.
+
+@seealso
+Musical Glossary:
+@rglos{melisma}.
+
+Learning Manual:
+@rlearning{Aligning lyrics to a melody}.
+
+Notation Reference:
+@ref{Aligning lyrics to a melody},
+@ref{Automatic syllable durations},
+@ref{Setting automatic beam behavior},
+@ref{Stanzas with different rhythms}.
+
+Internals Reference:
+@rinternals{Tunable context properties}.
+
+@knownissues
+
+Extender lines under melismata are not created automatically; they
+must be inserted manually with a double underscore.
+
+
+@node Extenders and hyphens
+@unnumberedsubsubsec Extenders and hyphens
+
+@cindex melisma
+@cindex extender
+
+@c TODO cf Multiple notes to one syllable; should this be merged in?
+
+@c leave this as samp. -gp
+In the last syllable of a word, melismata are sometimes indicated with
+a long horizontal line starting in the melisma syllable, and ending in
+the next one. Such a line is called an extender line, and it is
+entered as @samp{ __ } (note the spaces before and after the two
+underscore characters).
+
+@warning{Melismata are indicated in the score with extender lines,
+which are entered as one double underscore; but short melismata can
+also be entered by skipping individual notes, which are entered as
+single underscore characters; these do not make an extender line to be
+typeset by default.}
+
+@cindex hyphens
+
+@c leave this as samp. -gp
+Centered hyphens are entered as @samp{ -- } between syllables of a
+same word (note the spaces before and after the two hyphen
+characters). The hyphen will be centered between the syllables, and
+its length will be adjusted depending on the space between the
+syllables.
+
+In tightly engraved music, hyphens can be removed. Whether this
+happens can be controlled with the @code{minimum-distance} (minimum
+distance between two syllables) and the @code{minimum-length}
+(threshold below which hyphens are removed) properties of
+@code{LyricHyphen}.
+
+
+@seealso
+Internals Reference:
+@rinternals{LyricExtender},
+@rinternals{LyricHyphen}.
+
+
+@node Techniques specific to lyrics
+@subsection Techniques specific to lyrics
+
+@c TODO this whole section is to be reorganised
+
+@menu
+* Working with lyrics and variables::
+* Placing lyrics vertically::
+* Placing syllables horizontally::
+* Lyrics and repeats::
+* Divisi lyrics::
+@end menu
+
+
+
+@node Working with lyrics and variables
+@unnumberedsubsubsec Working with lyrics and variables
+
+@cindex lyrics, using variables
+
+Variables containing lyrics can be created, but the lyrics must be
+entered in lyric mode:
+
+@lilypond[quote,verbatim]
+musicOne = \relative c'' {
+ c4 b8. a16 g4. f8 e4 d c2
+}
+verseOne = \lyricmode {
+ Joy to the world, the Lord is come.
+}
+\score {
+ <<
+ \new Voice = "one" {
+ \time 2/4
+ \musicOne
+ }
+ \new Lyrics \lyricsto "one" {
+ \verseOne
+ }
+ >>
+}
+@end lilypond
+
+Durations do not need to be added if the variable is to be invoked
+with @code{\addlyrics} or @code{\lyricsto}.
+
+For different or more complex orderings, the best way is to define
+the music and lyric variables first, then set up the hierarchy of
+staves and lyrics, omitting the lyrics themselves, and then add the
+lyrics using @code{\context} underneath. This ensures that the
+voices referenced by @code{\lyricsto} have always been defined
+earlier. For example:
+
+@lilypond[quote,verbatim]
+sopranoMusic = \relative c'' { c4 c c c }
+contraltoMusic = \relative c'' { a4 a a a }
+sopranoWords = \lyricmode { Sop -- ra -- no words }
+contraltoWords = \lyricmode { Con -- tral -- to words }
+
+\score {
+ \new ChoirStaff <<
+ \new Staff {
+ \new Voice = "sopranos" {
+ \sopranoMusic
+ }
+ }
+ \new Lyrics = "sopranos"
+ \new Lyrics = "contraltos"
+ \new Staff {
+ \new Voice = "contraltos" {
+ \contraltoMusic
+ }
+ }
+ \context Lyrics = "sopranos" {
+ \lyricsto "sopranos" {
+ \sopranoWords
+ }
+ }
+ \context Lyrics = "contraltos" {
+ \lyricsto "contraltos" {
+ \contraltoWords
+ }
+ }
+ >>
+}
+@end lilypond
+
+
+@seealso
+Notation Reference:
+@ref{Placing lyrics vertically}.
+
+Internals Reference:
+@rinternals{LyricCombineMusic},
+@rinternals{Lyrics}.
+
+
+@node Placing lyrics vertically
+@unnumberedsubsubsec Placing lyrics vertically
+
+@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
+ }
+ }
+ >>
+}
+@end lilypond
+
+Lyrics may be positioned above the staff using one of
+two methods. The simplest (and preferred) method
+is to use the same syntax as above and explicitly
+specify the position of the lyrics:
+
+@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
+
+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 is placed after
+the Voice declaration it references by using @code{\context}, as
+follows:
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Lyrics = "lyrics" \with {
+ % lyrics above a staff should have this override
+ \override VerticalAxisGroup #'staff-affinity = #DOWN
+ }
+ \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" \with {
+ % lyrics above a staff should have this override
+ \override VerticalAxisGroup #'staff-affinity = #DOWN
+ }
+ \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.
+
+@snippets
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{lyrics-old-spacing-settings.ly}
+
+@seealso
+Learning Manual:
+@rlearning{Vocal ensembles}.
+
+Notation Reference:
+@ref{Aligning contexts},
+@ref{Creating contexts}.
+
+@node Placing syllables horizontally
+@unnumberedsubsubsec Placing syllables horizontally
+
+@cindex Spacing lyrics
+@cindex Lyrics, increasing space between
+
+To increase the spacing between lyrics, set the
+@code{minimum-distance} property of @code{LyricSpace}.
+
+@lilypond[relative=1,verbatim,quote,ragged-right]
+{
+ c c c c
+ \override Lyrics.LyricSpace #'minimum-distance = #1.0
+ c c c c
+}
+\addlyrics {
+ longtext longtext longtext longtext
+ longtext longtext longtext longtext
+}
+@end lilypond
+
+@noindent
+To make this change for all lyrics in the score, set the property in the
+@code{\layout} block.
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+ \relative c' {
+ c c c c
+ c c c c
+ }
+ \addlyrics {
+ longtext longtext longtext longtext
+ longtext longtext longtext longtext
+ }
+ \layout {
+ \context {
+ \Lyrics
+ \override LyricSpace #'minimum-distance = #1.0
+ }
+ }
+}
+@end lilypond
+
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{lyrics-alignment.ly}
+
+@c TODO: move to LSR -vv
+
+Checking to make sure that text scripts and lyrics are within the margins
+requires additional calculations. To speed up processing slightly, this
+feature can be disabled:
+
+@example
+\override Score.PaperColumn #'keep-inside-line = ##f
+@end example
+
+To make lyrics avoid bar lines as well, use
+
+@example
+\layout @{
+ \context @{
+ \Lyrics
+ \consists "Bar_engraver"
+ \consists "Separating_line_group_engraver"
+ \override BarLine #'transparent = ##t
+ @}
+@}
+@end example
+
+@c TODO Create and add lsr example of lyricMelismaAlignment
+@c It's used like this to center-align all lyric syllables,
+@c even when notes are tied. -td
+
+@ignore
+\layout
+{
+ \context { \Score lyricMelismaAlignment = #0 }
+}
+@end ignore
+
+
+@node Lyrics and repeats
+@unnumberedsubsubsec Lyrics and repeats
+
+@cindex repeats and lyrics
+@cindex lyrics, repeating
+
+@subheading Simple repeats
+
+Repeats in @emph{music} are fully described elsewhere; see
+@ref{Repeats}. This section explains how to add lyrics to repeated
+sections of music.
+
+Lyrics to a section of music that is repeated should be surrounded
+by exactly the same repeat construct as the music, if the words are
+unchanged.
+
+@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.
+ \repeat volta 2 { Re -- peat -- ed twice. }
+ }
+ }
+ >>
+}
+@end lilypond
+
+The words will then be correctly expanded if the repeats are
+unfolded.
+
+@lilypond[verbatim,quote]
+\score {
+ \unfoldRepeats {
+ <<
+ \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.
+ \repeat volta 2 { Re -- peat -- ed twice. }
+ }
+ }
+ >>
+ }
+}
+@end lilypond
+
+If the repeated section is to be unfolded and has different words,
+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 be entered in separate @code{Lyrics} contexts,
+correctly nested in parallel sections:
+
+@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 {
+ \set associatedVoice = "melody"
+ Sec -- ond time words.
+ }
+ >>
+ }
+ >>
+}
+@end lilypond
+
+More verses may be added in a similar way:
+
+@lilypond[verbatim,quote]
+\score {
+ <<
+ \new Staff {
+ \new Voice = "singleVoice" {
+ \relative c'' {
+ a4 a a a
+ \repeat volta 3 { b4 b b b }
+ c4 c c c
+ }
+ }
+ }
+ \new Lyrics \lyricsto "singleVoice" {
+ Not re -- peat -- ed.
+ <<
+ { The first time words. }
+ \new Lyrics {
+ \set associatedVoice = "singleVoice"
+ Sec -- ond time words.
+ }
+ \new Lyrics {
+ \set associatedVoice = "singleVoice"
+ The third time words.
+ }
+ >>
+ The end sec -- tion.
+ }
+ >>
+}
+@end lilypond
+
+
+@c TODO positioning a common line of lyrics
+
+@subheading Repeats with alternative endings
+
+@cindex lyrics, repeats with alternative endings
+@cindex repeating lyrics with alternative endings
+@cindex alternative endings and lyrics
+
+If the words of the repeated section are the same, exactly the
+same structure can be used for both the lyrics and music.
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \time 2/4
+ \new Voice = "melody" {
+ \relative c'' {
+ a4 a a a
+ \repeat volta 2 { b4 b }
+ \alternative { { b b } { b c } }
+ }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ Not re -- peat -- ed.
+ \repeat volta 2 { Re -- peat -- }
+ \alternative { { ed twice. } { ed twice. } }
+ }
+ }
+ >>
+}
+@end lilypond
+
+@funindex \skip
+@cindex skipping notes in lyrics
+@cindex lyrics, skipping notes
+
+But when the repeated section has different words, a repeat
+construct cannot be used around the words and @code{\skip} commands
+have to be inserted manually to skip over the notes in the
+alternative sections which do not apply.
+
+Note: do not use an underscore, @code{_}, to skip notes -- an
+underscore indicates a melisma, causing 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
+from the notes in an associated melody through @code{\addlyrics} or
+@code{\lyricsto}. Each @code{@bs{}skip} skips a single note of any
+value, irrespective of the value of the following number.}
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+ <<
+ \new Staff {
+ \time 2/4
+ \new Voice = "melody" {
+ \relative c'' {
+ \repeat volta 2 { b4 b }
+ \alternative { { b b } { b c } }
+ c4 c
+ }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ The first time words.
+ \repeat unfold 2 { \skip 1 }
+ End here.
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ Sec -- ond
+ \repeat unfold 2 { \skip 1 }
+ time words.
+ }
+ }
+ >>
+}
+@end lilypond
+
+@cindex lyrics and tied notes
+@funindex \repeatTie
+
+When a note is tied over into two or more alternative endings a
+tie is used to carry the note into the first alternative ending and
+a @code{\repeatTie} is used in the second and subsequent endings.
+This structure causes difficult alignment problems when lyrics are
+involved and increasing the length of the alternative sections so
+the tied notes are contained wholly within them may give a more
+acceptable result.
+
+The tie creates a melisma into the first alternative, but not into
+the second and subsequent alternatives, so to align the lyrics
+correctly it is necessary to disable the automatic creation of
+melismata over the volta section and insert manual skips.
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \time 2/4
+ \new Voice = "melody" {
+ \relative c'' {
+ \set melismaBusyProperties = #'()
+ \repeat volta 2 { b4 b ~}
+ \alternative { { b b } { b \repeatTie c } }
+ \unset melismaBusyProperties
+ c4 c
+ }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ \repeat volta 2 { Here's a __ }
+ \alternative {
+ { \skip 1 verse }
+ { \skip 1 sec }
+ }
+ ond one.
+ }
+ }
+ >>
+}
+@end lilypond
+
+Note that if @code{\unfoldRepeats} is used around a section
+containing @code{\repeatTie}, the @code{\repeatTie} should be
+removed to avoid both types of tie being printed.
+
+When the repeated section has different words a @code{\repeat}
+cannot be used around the lyrics and @code{\skip} commands need to
+be inserted manually, as before.
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \time 2/4
+ \new Voice = "melody" {
+ \relative c'' {
+ \repeat volta 2 { b4 b ~}
+ \alternative { { b b } { b \repeatTie c } }
+ c4 c
+ }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ Here's a __ verse.
+ \repeat unfold 2 { \skip 1 }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ Here's one
+ \repeat unfold 2 { \skip 1 }
+ more to sing.
+ }
+ }
+ >>
+}
+@end lilypond
+
+If you wish to show extenders and hyphens into and out of
+alternative sections these must be inserted manually.
+
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff {
+ \time 2/4
+ \new Voice = "melody" {
+ \relative c'' {
+ \repeat volta 2 { b4 b ~}
+ \alternative { { b b } { b \repeatTie c } }
+ c4 c
+ }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ Here's a __ verse.
+ \repeat unfold 2 { \skip 1 }
+ }
+ }
+ \new Lyrics {
+ \lyricsto "melody" {
+ Here's "a_"
+ \skip 1
+ "_" sec -- ond one.
+ }
+ }
+ >>
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Keeping contexts alive},
+@ref{Repeats}.
+
+
+@node Divisi lyrics
+@unnumberedsubsubsec Divisi lyrics
+
+@cindex divided lyrics
+@cindex lyrics, divided
+
+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" {
+ They shall not o -- ver -- come
+ }
+ \new Lyrics \lyricsto "melody" {
+ We will _
+ }
+ >>
+}
+@end lilypond
+
+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' {
+ <<
+ {
+ \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 Stanzas
+@subsection Stanzas
+
+@menu
+* Adding stanza numbers::
+* Adding dynamics marks to stanzas::
+* Adding singers' names to stanzas::
+* Stanzas with different rhythms::
+* Printing stanzas at the end::
+* Printing stanzas at the end in multiple columns::
+@end menu
+
+
+@node Adding stanza numbers
+@unnumberedsubsubsec Adding stanza numbers
+
+@cindex stanza number
+
+Stanza numbers can be added by setting @code{stanza}, e.g.,
+
+@lilypond[quote,ragged-right,verbatim,relative=2]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set stanza = #"1. "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set stanza = #"2. "
+ Oh, ché -- ri, je t'aime
+}
+@end lilypond
+
+
+@noindent
+These numbers are put just before the start of the first syllable.
+
+@c TODO Create and add snippet to show how two lines of a
+@c stanza can be grouped together, along these lines:
+@c (might need improving a bit) -td
+
+@ignore
+leftbrace = \markup { \override #'(font-encoding . fetaBraces) \lookup
+#"brace105" }
+
+stanzaOneOne = {
+ \set stanza = \markup { "1. " \leftbrace }
+ \lyricmode { Child, you're mine and I love you.
+ Lend thine ear to what I say.
+
+ }
+}
+
+stanzaOneThree = {
+% \set stanza = \markup { " "}
+ \lyricmode { Child, I have no great -- er joy
+ Than to have you walk in truth.
+
+ }
+}
+
+\new Voice {
+ \repeat volta 2 { c'8 c' c' c' c' c' c'4
+ c'8 c' c' c' c' c' c'4 }
+} \addlyrics { \stanzaOneOne }
+ \addlyrics { \stanzaOneThree }
+
+@end ignore
+
+@node Adding dynamics marks to stanzas
+@unnumberedsubsubsec Adding dynamics marks to stanzas
+
+Stanzas differing in loudness may be indicated by putting a
+dynamics mark before each stanza. In LilyPond, everything coming in
+front of a stanza goes into the @code{StanzaNumber} object; dynamics
+marks are no different. For technical reasons, you have to set the
+stanza outside @code{\lyricmode}:
+
+@lilypond[quote,ragged-right,verbatim]
+text = {
+ \set stanza = \markup { \dynamic "ff" "1. " }
+ \lyricmode {
+ Big bang
+ }
+}
+
+<<
+ \new Voice = "tune" {
+ \time 3/4
+ g'4 c'2
+ }
+\new Lyrics \lyricsto "tune" \text
+>>
+@end lilypond
+
+@node Adding singers' names to stanzas
+@unnumberedsubsubsec Adding singers' names to stanzas
+
+@cindex singer name
+@cindex name of singer
+
+Names of singers can also be added. They are printed at the start of
+the line, just like instrument names. They are created by setting
+@code{vocalName}. A short version may be entered as
+@code{shortVocalName}.
+
+@lilypond[ragged-right,quote,verbatim,relative=2]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set vocalName = #"Bert "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set vocalName = #"Ernie "
+ Oh, ché -- ri, je t'aime
+}
+@end lilypond
+
+@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
+multiple syllables in another. One solution is to make the faster
+voice ignore the melisma. This is done by setting
+@code{ignoreMelismata} in the Lyrics context.
+
+@lilypond[verbatim,ragged-right,quote]
+<<
+ \relative c' \new Voice = "lahlah" {
+ \set Staff.autoBeaming = ##f
+ c4
+ \slurDotted
+ f8.[( g16])
+ a4
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ more slow -- ly
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ go
+ \set ignoreMelismata = ##t
+ fas -- ter
+ \unset ignoreMelismata
+ still
+ }
+>>
+@end lilypond
+
+@knownissues
+Unlike most @code{\set} commands, @code{\set ignoreMelismata} does
+not work if prefixed with @code{\once}. It is necessary to use
+@code{\set} and @code{\unset} to bracket the lyrics where melismata
+are to be ignored.
+
+@subsubheading Adding syllables to grace notes
+
+@cindex grace notes and lyrics
+@cindex lyrics on 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]
+<<
+ \new Voice = melody \relative c' {
+ f4 \appoggiatura a32 b4
+ \grace { f16[ a16] } b2
+ \afterGrace b2 { f16[ a16] }
+ \appoggiatura a32 b4
+ \acciaccatura a8 b4
+ }
+ \new Lyrics
+ \lyricsto melody {
+ normal
+ \set includeGraceNotes = ##t
+ case,
+ gra -- ce case,
+ after -- grace case,
+ \set ignoreMelismata = ##t
+ app. case,
+ acc. case.
+ }
+>>
+@end lilypond
+
+@knownissues
+Like @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
+
+@cindex associatedVoice
+@cindex alternative melody, switching to
+
+More complex variations in setting lyrics to music are possible.
+The melody to which the lyrics are being set can be changed from
+within the lyrics by setting the @code{associatedVoice} property:
+
+@lilypond[verbatim,quote]
+<<
+ \relative c' \new Voice = "lahlah" {
+ \set Staff.autoBeaming = ##f
+ c4
+ <<
+ \new Voice = "alternative" {
+ \voiceOne
+ \times 2/3 {
+ % show associations clearly.
+ \override NoteColumn #'force-hshift = #-3
+ f8 f g
+ }
+ }
+ {
+ \voiceTwo
+ f8.[ g16]
+ \oneVoice
+ } >>
+ a8( b) c
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ Ju -- ras -- sic Park
+ }
+ \new Lyrics \lyricsto "lahlah" {
+ % Tricky: need to set associatedVoice
+ % one syllable too soon!
+ \set associatedVoice = "alternative" % applies to "ran"
+ Ty --
+ ran --
+ no --
+ \set associatedVoice = "lahlah" % applies to "rus"
+ sau -- rus Rex
+ } >>
+@end lilypond
+
+@noindent
+The text for the first stanza is set to the melody called
+@q{lahlah} in the usual way, but the second stanza is set initally
+to the @code{lahlah} context and is then switched to the
+@code{alternative} melody for the syllables @q{ran} to @q{sau} by
+the lines:
+
+@example
+\set associatedVoice = "alternative" % applies to "ran"
+Ty --
+ran --
+no --
+\set associatedVoice = "lahlah" % applies to "rus"
+sau -- rus Rex
+@end example
+
+@noindent
+Here, @code{alternative} is the name of the @code{Voice} context
+containing the triplet.
+
+Note the placement of the @code{\set associatedVoice} command --
+it appears to be one syllable too early, but this is correct.
+
+@warning{The @code{\set associatedVoice} command must be placed
+one syllable @emph{before} the one at which the switch to the new
+voice is to occur. In other words, changing the associated Voice
+happens one syllable later than expected. This is for technical
+reasons, and it is not a bug.}
+
+
+@node Printing stanzas at the end
+@unnumberedsubsubsec Printing stanzas at the end
+
+Sometimes it is appropriate to have one stanza set
+to the music, and the rest added in verse form at
+the end of the piece. This can be accomplished by adding
+the extra verses into a @code{\markup} section outside
+of the main score block. Notice that there are two
+different ways to force linebreaks when using
+@code{\markup}.
+
+@lilypond[ragged-right,verbatim,quote]
+melody = \relative c' {
+e d c d | e e e e |
+d d e d | c1 |
+}
+
+text = \lyricmode {
+\set stanza = #"1." Ma- ry had a lit- tle lamb,
+its fleece was white as snow.
+}
+
+\score{ <<
+ \new Voice = "one" { \melody }
+ \new Lyrics \lyricsto "one" \text
+>>
+ \layout { }
+}
+\markup { \column{
+ \line{ Verse 2. }
+ \line{ All the children laughed and played }
+ \line{ To see a lamb at school. }
+ }
+}
+\markup{
+ \wordwrap-string #"
+ Verse 3.
+
+ Mary took it home again,
+
+ It was against the rule."
+}
+@end lilypond
+
+
+@node Printing stanzas at the end in multiple columns
+@unnumberedsubsubsec Printing stanzas at the end in multiple columns
+
+When a piece of music has many verses, they are often printed in
+multiple columns across the page. An outdented verse number often
+introduces each verse. The following example shows how to produce such
+output in LilyPond.
+
+@lilypond[ragged-right,quote,verbatim]
+melody = \relative c' {
+ c c c c | d d d d
+}
+
+text = \lyricmode {
+ \set stanza = #"1." This is verse one.
+ It has two lines.
+}
+
+\score {
+ <<
+ \new Voice = "one" { \melody }
+ \new Lyrics \lyricsto "one" \text
+ >>
+ \layout { }
+}
+
+\markup {
+ \fill-line {
+ \hspace #0.1 % moves the column off the left margin;
+ % can be removed if space on the page is tight
+ \column {
+ \line { \bold "2."
+ \column {
+ "This is verse two."
+ "It has two lines."
+ }
+ }
+ \hspace #0.1 % adds vertical spacing between verses
+ \line { \bold "3."
+ \column {
+ "This is verse three."
+ "It has two lines."
+ }
+ }
+ }
+ \hspace #0.1 % adds horizontal spacing between columns;
+ % if they are still too close, add more " " pairs
+ % until the result looks good
+ \column {
+ \line { \bold "4."
+ \column {
+ "This is verse four."
+ "It has two lines."
+ }
+ }
+ \hspace #0.1 % adds vertical spacing between verses
+ \line { \bold "5."
+ \column {
+ "This is verse five."
+ "It has two lines."
+ }
+ }
+ }
+ \hspace #0.1 % gives some extra space on the right margin;
+ % can be removed if page space is tight
+ }
+}
+@end lilypond
+
+
+@seealso
+Internals Reference:
+@rinternals{LyricText},
+@rinternals{StanzaNumber}.
+
+
+@node Songs
+@subsection Songs
+
+@menu
+* References for songs::
+* Lead sheets::
+@end menu
+
+@node References for songs
+@unnumberedsubsubsec References for songs
+
+Songs are usually written on three staves with the melody for the
+singer on the top staff and two staves of piano accompaniment at
+the bottom. The lyrics of the first stanza are printed immediately
+underneath the top staff. If there are just a small number of
+further stanzas these can be printed immediately under the first
+one, but if there are more stanzas than can be easily accommodated
+there the second and subsequent stanzas are printed after the music
+as stand-alone text.
+
+All the notational elements needed to write songs are fully described
+elsewhere:
+
+@itemize
+
+@item
+For constructing the staff layout, see @ref{Displaying staves}.
+
+@item
+For writing piano music, see
+@ref{Keyboard and other multi-staff instruments}.
+
+@item
+For writing the lyrics to a melody line, see
+@ref{Common notation for vocal music}.
+
+@item
+For placing the lyrics, see @ref{Placing lyrics vertically}.
+
+@item
+For entering stanzas, see @ref{Stanzas}.
+
+@item
+Songs are frequently printed with the chording indicated by chord
+names above the staves. This is described in @ref{Displaying chords}.
+
+@item
+To print fret diagrams of the chords for guitar accompaniment or
+accompaniment by other fretted instruments, see @qq{Fret diagram
+markups} in @ref{Common notation for fretted strings}.
+
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Songs}.
+
+Notation Reference:
+@ref{Common notation for vocal music},
+@ref{Displaying chords},
+@ref{Displaying staves},
+@ref{Keyboard and other multi-staff instruments},
+@ref{Placing lyrics vertically},
+@ref{Stanzas}.
+
+Snippets:
+@rlsr{Vocal music}.
+
+@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 note heads, 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}.
+
+Snippets:
+@rlsr{Vocal music}.
+
+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 layout}.
+
+@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 layout},
+@ref{Score layout},
+@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::
+* Musical cues::
+* 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 layout}.
+
+@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
+
+@seealso
+Musical Glossary:
+@rglos{Frenched score},
+@rglos{Frenched staves},
+@rglos{transposing instrument}.
+
+Notation Reference:
+@ref{Grouping staves},
+@ref{Hiding staves},
+@ref{Instrument transpositions},
+@ref{Nested staff groups},
+@ref{Page layout},
+@ref{Separating systems},
+@ref{Transpose},
+@ref{Writing parts},
+@ref{Writing text}.
+
+Snippets:
+@rlsr{Vocal music}.
+
+
+@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:
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+ <<
+ \new Staff {
+ \set Staff.vocalName = \markup \smallCaps Kaspar
+ \set Staff.shortVocalName = \markup \smallCaps Kas.
+ \relative c' {
+ \clef "G_8"
+ c4 c c c
+ \break
+ c4 c c c
+ }
+ }
+ \new Staff {
+ \set Staff.vocalName = \markup \smallCaps Melchior
+ \set Staff.shortVocalName = \markup \smallCaps 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]
+\clef "G_8"
+c4^\markup \fontsize #1 \smallCaps Kaspar
+c c c
+\clef "bass"
+a4^\markup \fontsize #1 \smallCaps Melchior
+a a a
+\clef "G_8"
+c4^\markup \fontsize #1 \smallCaps Kaspar
+c c c
+@end lilypond
+
+Alternatively, if there are many character changes, it may be
+easier to set up @qq{instrument} definitions for each character at
+the top level so that @code{\instrumentSwitch} can be used to
+indicate each change.
+
+@lilypond[quote,verbatim]
+\addInstrumentDefinition #"kaspar"
+ #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
+ (shortInstrumentName . "Kas.")
+ (clefGlyph . "clefs.G")
+ (clefOctavation . -7)
+ (middleCPosition . 1)
+ (clefPosition . -2)
+ (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
+ (midiInstrument . "voice oohs"))
+
+\addInstrumentDefinition #"melchior"
+ #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
+ (shortInstrumentName . "Mel.")
+ (clefGlyph . "clefs.F")
+ (clefOctavation . 0)
+ (middleCPosition . 6)
+ (clefPosition . 2)
+ (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
+ (midiInstrument . "voice aahs"))
+
+\relative c' {
+ \instrumentSwitch "kaspar"
+ c4 c c c
+ \instrumentSwitch "melchior"
+ a4 a a a
+ \instrumentSwitch "kaspar"
+ c4 c c c
+}
+@end lilypond
+
+@seealso
+Notation Reference:
+@ref{Instrument names},
+@ref{Scheme functions},
+@ref{Text},
+@ref{Text markup commands}.
+
+Extending LilyPond:
+@rextend{Markup construction in Scheme}.
+
+@node Musical cues
+@unnumberedsubsubsec Musical cues
+
+@cindex musical cues
+@cindex cues, musical
+
+Musical cues can be inserted in Vocal Scores, Vocal Books and
+Orchestral Parts to indicate what music in another part
+immediately precedes an entry. Also, cues are often inserted in the
+piano reduction in Vocal Scores to indicate what each orchestral
+instrument is playing. This aids the conductor when a full
+Conductors' Score is not available.
+
+The basic mechanism for inserting cues is fully explained in the
+main text, see @ref{Quoting other voices} and
+@ref{Formatting cue notes}. But when many cues have to be
+inserted, for example, as an aid to a conductor in a vocal score,
+the instrument name must be positioned carefully just before and
+close to the start of the cue notes. The following example shows
+how this is done.
+
+@lilypond[quote,verbatim]
+flute = \relative c'' {
+ s4 s4 e g
+}
+\addQuote "flute" { \flute }
+
+pianoRH = \relative c'' {
+ c4. g8
+ % position name of cue-ing instrument just before the cue notes,
+ % and above the staff
+ s1*0^\markup { \right-align { \tiny "Flute" } }
+ \cueDuring "flute" #UP { g4 bes4 }
+}
+pianoLH = \relative c { c4 <c' e> e, <g c> }
+
+\score {
+ \new PianoStaff <<
+ \new Staff {
+ \pianoRH
+ }
+ \new Staff {
+ \clef "bass"
+ \pianoLH
+ }
+ >>
+}
+@end lilypond
+
+If a transposing instrument is being quoted the instrument part should
+specify its key so the conversion of its cue notes will be done
+automatically. The example below shows this transposition for a
+B-flat clarinet. The notes in this example are low on the staff so
+@code{#DOWN} is specified in @code{\cueDuring} (so the stems are
+down) and the instrument name is positioned below the staff. Note
+also that the piano right-hand voice is explicitly declared. This
+is because the cue notes in this example begin at the start of the
+first bar and this would otherwise cause the entire piano right-hand
+notes to be placed in a @code{CueVoice} context.
+
+@lilypond[quote,verbatim]
+clarinet = \relative c' {
+ \transposition bes
+ fis4 d d c
+}
+\addQuote "clarinet" { \clarinet }
+
+pianoRH = \relative c'' {
+ \transposition c'
+ % position name of cue-ing instrument below the staff
+ s1*0_\markup { \right-align { \tiny "Clar." } }
+ \cueDuring "clarinet" #DOWN { c4. g8 }
+ g4 bes4
+}
+pianoLH = \relative c { c4 <c' e> e, <g c> }
+
+\score {
+ <<
+ \new PianoStaff <<
+ \new Staff {
+ \new Voice {
+ \pianoRH
+ }
+ }
+ \new Staff {
+ \clef "bass"
+ \pianoLH
+ }
+ >>
+ >>
+}
+@end lilypond
+
+From these two examples it is clear that inserting many cues in a
+Vocal Score would be tedious, and the notes of the piano part would
+become obscured. However, as the following snippet shows, it is
+possible to define a music function to reduce the amount of typing
+and to make the piano notes clearer.
+
+@snippets
+@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
+{adding-orchestral-cues-to-a-vocal-score.ly}
+
+@seealso
+Musical Glossary:
+@rglos{cue-notes}.
+
+Notation Reference:
+@ref{Aligning objects},
+@ref{Direction and placement},
+@ref{Formatting cue notes},
+@ref{Quoting other voices},
+@ref{Using music functions}.
+
+Snippets:
+@rlsr{Vocal music}.
+
+Internals Reference:
+@rinternals{InstrumentSwitch},
+@rinternals{CueVoice}.
+
+@knownissues
+@code{\cueDuring} automatically inserts a @code{CueVoice} context
+and all cue notes are placed in that context. This means it is not
+possible to have two overlapping sequences of cue notes by this
+technique. Overlapping sequences could be entered by explicitly
+declaring separate @code{CueVoice} contexts and using
+@code{\quoteDuring} to extract and insert the cue notes.
+
+
+@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
+
+Dialogue over music is usually printed over the staves in an italic
+font, with the start of each phrase keyed in to a particular music
+moment.
+
+For short interjections a simple markup suffices.
+
+@lilypond[quote,verbatim,relative=2]
+a4^\markup { \smallCaps { Alex - } \italic { He's gone } } a a a
+a4 a a^\markup { \smallCaps { Bethan - } \italic Where? } a
+a4 a a a
+@end lilypond
+
+For longer phrases it may be necessary to expand the music to make
+the words fit neatly. There is no provision in LilyPond to do this
+fully automatically, and some manual intervention to layout the
+page will be necessary.
+
+For long phrases or for passages with a lot of closely packed
+dialogue, using a Lyrics context will give better results. The
+Lyrics context should not be associated with a music Voice; instead
+each section of dialogue should be given an explicit duration. If
+there is a gap in the dialogue, the final word should be separated
+from the rest and the duration split between them so that the
+underlying music spaces out smoothly.
+
+If the dialogue extends for more than one line it will be necessary
+to manually insert @code{\break}s and adjust the placing of the
+dialogue to avoid running into the right margin. The final word of
+the last measure on a line should also be separated out, as above.
+
+Here is an example illustrating how this might be done.
+
+@c This should be a snippet, but it can't be as it needs to be
+@c manually adjusted to suit the imposed line length. -td
+
+@lilypond[quote,verbatim,ragged-right]
+music = \relative c'' {
+ \repeat unfold 3 { a4 a a a }
+}
+
+dialogue = \lyricmode {
+ \markup {
+ \fontsize #1 \upright \smallCaps Abe:
+ "Say this over measures one and"
+ }4*7
+ "two"4 |
+ \break
+ "and this over measure"4*3
+ "three"4 |
+}
+
+\score {
+ <<
+ \new Lyrics \with {
+ \override LyricText #'font-shape = #'italic
+ \override LyricText #'self-alignment-X = #LEFT
+ }
+ { \dialogue }
+ \new Staff {
+ \new Voice { \music }
+ }
+ >>
+}
+@end lilypond
+
+@c TODO show use of \column to produce dialogue on two lines
+
+@seealso
+Notation Reference:
+@ref{Manual syllable durations},
+@ref{Text}.
+
+Internal Reference:
+@rinternals{LyricText}.
+
+
+@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}.
+
+Snippets:
+@rlsr{Vocal music}.
+
+
+@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
+bar lines 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}.
+
+
+
+
projects / lilypond.git / blobdiff