@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.12.0"

@node Vocal music
@section Vocal music

@c TODO: inspirational headword

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::
* Skipping notes::
* 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 of for other text elements (character's 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}.

@end itemize

@seealso
Music Glossary:
@rglos{ambitus}.

@node Entering lyrics
@unnumberedsubsubsec Entering lyrics

Lyrics are entered in lyric mode.  This section explains how this
done.

@cindex lyrics
@funindex \lyricmode
@cindex punctuation
@cindex spaces, in lyrics
@cindex quotes, in lyrics

@c TODO: this section is to be rewritten.
Since LilyPond input files are text, there is at least one
issue to consider when working with vocal music:
song texts must be interpreted as text, not notes.  For example, the
input@tie{}@code{d} should be interpreted as a one letter syllable,
not the note@tie{}D.
Therefore, a special lyric mode has to be used, either explicitly
or using some abbreviated methods.

Lyrics are entered in a special input mode, which can be introduced
by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
@code{\lyricsto}.  In this mode you can enter lyrics,
with punctuation and accents, and the input @code{d} is not parsed as
a pitch, but rather as a one letter syllable.  Syllables are entered
like notes, but with pitches replaced by text.  For example,

@example
\lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
@end example

There are two main methods to specify the horizontal placement
of the syllables, either by specifying the duration of each syllable
explicitly, like in the example above, or by automatically aligning
the lyrics to a melody or other voice of music, using @code{\addlyrics}
or @code{\lyricsto}.
@c  TODO: broken
@c For more details see @ref{The Lyrics context}.

A word or syllable of lyrics begins with an alphabetic character, and ends
with
any space or digit.  The following characters can be any character
that is not a digit or white space.

Any character that is not a digit or white space will be regarded as
part of the syllable; one important consequence of this is that a word
can end with @code{@}}, which often leads to the following mistake:

@example
\lyricmode @{ 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.


@funindex \property in \lyricmode

@noindent
Similarly, a period which follows an alphabetic sequence is included in
the resulting string.  As a consequence, spaces must be inserted around
property commands: do @emph{not} write

@example
\override Score.LyricText #'font-shape = #'italic
@end example

@noindent
but instead use

@example
\override Score . LyricText #'font-shape = #'italic
@end example

To enter lyrics with characters from non-English languages, or with
accented and special characters (such as the heart symbol or slanted quotes),
simply insert the characters directly into the input file and save
it with UTF-8 encoding.  See @ref{Text encoding}, for more info.

@lilypond[quote,ragged-right,fragment,verbatim]
\relative c' { e4 f e d e f e2 }
\addlyrics { He said: “Let my peo ple go”. }
@end lilypond

To use normal quotes in lyrics, add a backslash before the
quotes.  For example,

@lilypond[quote,ragged-right,fragment,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 begins with: an alphabetic character, @code{_},
@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
any 8-bit character with ASCII code over 127, or a two-character
combination of a backslash followed by one of @code{`}, @code{'},
@code{"}, or @code{^}.

@c " to balance double quotes for not-so-bright context-sensitive editors

To define variables containing lyrics, the function @code{lyricmode}
must be used.

@example
verseOne = \lyricmode @{ Joy to the world the Lord is come @}
\score @{
  <<
    \new Voice = "one" \relative c'' @{
      \autoBeamOff
      \time 2/4
      c4 b8. a16 g4. f8 e4 d c2
    @}
    \addlyrics @{ \verseOne @}
  >>
@}
@end example


@seealso
Notation Reference:
@ref{Fonts}.

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


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

@funindex \lyricmode
@funindex \addlyrics
@funindex \lyricsto

@c TODO: this stuff is to be rewritten. -vv

Aligning of text with melodies can be made automatically, but if you
specify the durations of the syllables it can also be made manually.
Lyrics aligning and typesetting are prepared with the help of skips,
hyphens and extender lines.

Lyrics are printed by interpreting them in the context called
@code{Lyrics}; see @rinternals{Lyrics}, for more.

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

There are two main methods to specify the horizontal placement
of the syllables:

@itemize
@item
by automatically aligning
the lyrics to a melody or other voice of music, using @code{\addlyrics}
or @code{\lyricsto}

@item
or by specifying the duration of each syllable
explicitly, using @code{\lyricmode}
@end itemize

The @code{Voice} context containing the melody to which the lyrics
are being aligned must not have @qq{died}, or the lyrics after that
point will be lost.  This can happen if there are periods when that
voice has nothing to do.  For methods of keeping contexts alive, see
@ref{Keeping contexts alive}.


@node Automatic syllable durations
@unnumberedsubsubsec Automatic syllable durations

@cindex syllable durations, automatic
@cindex lyrics and melodies

The lyrics can be aligned under a given melody
automatically.  This is achieved by combining the
melody and the lyrics with the @code{\lyricsto} expression

@example
\new Lyrics \lyricsto @var{name} @dots{}
@end example

@noindent
This aligns the lyrics to the
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
@code{\lyricmode} keyword may be omitted.

The following example uses different commands for entering lyrics.

@lilypond[quote,fragment,ragged-right,verbatim]
<<
  \new Voice = "one" \relative c'' {
    \autoBeamOff
    \time 2/4
    c4 b8. a16 g4. f8 e4 d c2
  }

% not recommended: left-aligned syllables
  \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }

% wrong: durations needed
  \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }

%correct
  \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
>>
@end lilypond

The second stanza is not properly aligned because the durations
were not specified.  A solution for that would be to use @code{\lyricsto}.

@cindex \addlyrics

The @code{\addlyrics} command is actually just a convenient way
to write a more complicated LilyPond structure that sets up the
lyrics.

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

Lyrics can also be entered without @code{\addlyrics} or
@code{\lyricsto}.  In this case,
syllables are entered like notes -- but with pitches replaced by text -- and the
duration of each syllable must be entered explicitly.  For example:

@example
play2 the4 game2.
sink2 or4 swim2.
@end example

The alignment to a melody can be specified with 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.  Without this setting, extender lines
will not be formatted properly.

Here is an example demonstrating manual lyric durations,

@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
<< \new Voice = "melody" {
    \time 3/4
    c2 e4 g2.
 }
 \new Lyrics \lyricmode {
   \set associatedVoice = #"melody"
   play2 the4 game2.
 } >>
@end lilypond


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

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 have a font (like DejaVuLGC) installed that includes this
glyph.

@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


@seealso
Internals Reference:
@rinternals{LyricCombineMusic}.


@c Here come the section which used to be "Melismata"
@c the new title might be more self-explanatory


@node Multiple notes to one syllable
@unnumberedsubsubsec Multiple notes to one syllable

@cindex melisma
@cindex melismata
@cindex phrasing, in lyrics

Sometimes, particularly in Medieval music, several notes are to be sung on one
single syllable; such vocalises are called melismas, or melismata.

@c this method seems to be the simplest; therefore
@c it might be better to present it first - vv

You can define melismata entirely in the lyrics, by entering @code{_}
for every extra note that has to be added to the melisma.

@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
Additionally, you can make an extender line to be typeset to indicate
the melisma in the score, writing a double underscore next to the
first syllable of the melisma.  This example shows the three elements
that are used for this purpose (all of them surrounded by spaces):
double hyphens to separate syllables in a word, underscores to add
notes to a melisma, and a double underscore to put an extender line.

@c wrong: extender line only on last syllable of a word.  Change example
@lilypond[relative=1,verbatim,fragment,quote]
{ \set melismaBusyProperties = #'()
 c d( e) f f( e) e e  }
\addlyrics
 { Ky -- _ _ ri __ _ _ _  e }
@end lilypond

In this case, you can also have ties and slurs in the melody if you
set @code{melismaBusyProperties}, as is done in the example above.

However, the @code{\lyricsto} command can also
detect melismata automatically: it only puts one
syllable under a tied or slurred group of notes.  If you want to force
an unslurred group of notes to be a melisma, insert @code{\melisma}
after the first note of the group, and @code{\melismaEnd} after the
last one, e.g.,

@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
<<
  \new Voice = "lala" {
    \time 3/4
    f4 g8
    \melisma
    f e f
    \melismaEnd
    e2
  }
  \new Lyrics \lyricsto "lala" {
    la di __ daah
  }
>>
@end lilypond

In addition, notes are considered a melisma if they are manually
beamed, and automatic beaming (see @ref{Setting automatic beam
behavior}) is switched off.

@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
@rlearning{Vocal ensembles}.


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


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


@knownissues

Melismata are not detected automatically, and extender lines must be
inserted by hand.

@node Skipping notes
@unnumberedsubsubsec Skipping notes

Making a lyric line run slower than the melody can be achieved by
inserting @code{\skip}s into the lyrics.  For every @code{\skip},
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.

@lilypond[verbatim,ragged-right,quote]
\relative c' { c c g' }
\addlyrics {
  twin -- \skip 4
  kle
}
@end lilypond


@node Extenders and hyphens
@unnumberedsubsubsec Extenders and hyphens

@cindex melisma
@cindex extender

@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).


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

@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

@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 volta repeat can be written exactly as if the music was
not repeated, 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.
        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
@unnumberedsubsubsec Divisi lyrics

You can display alternate (or divisi) lyrics by naming voice
contexts and attaching lyrics to those specific contexts.

@lilypond[verbatim,ragged-right,quote]
\score{ <<
  \new Voice = "melody" {
    \relative c' {
      c4
      <<
        { \voiceOne c8 e }
        \new Voice = "splitpart" { \voiceTwo c4 }
      >>
      \oneVoice c4 c | c
    }
  }
  \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
  \new Lyrics \lyricsto "splitpart" { will }
>> }
@end lilypond


You can use this trick to display different lyrics for a repeated
section.

@lilypond[verbatim,ragged-right,quote]
\score{ <<
  \new Voice = "melody" \relative c' {
    c2 e | g e | c1 |
    \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
    a2 b | c1}
  \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
    do mi sol mi do
    la si do }
  \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
   do re mi fa sol }
  \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
   dodo rere mimi fafa solsol }
>>
}
@end lilypond



@node Lyrics independent of notes
@unnumberedsubsubsec Lyrics independent of notes

@cindex Devnull context

In some complex vocal music, it may be desirable to place
lyrics completely independently of notes.  Music defined
inside @code{lyricrhythm} disappears into the
@code{Devnull} context, but the rhythms can still be used
to place the lyrics.

@lilypond[quote,verbatim,ragged-right]
voice = {
  c''2
  \tag #'music { c''2 }
  \tag #'lyricrhythm { c''4. c''8 }
  d''1
}

lyr = \lyricmode { I like my cat! }

<<
  \new Staff \keepWithTag #'music \voice
  \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
  \new Lyrics \lyricsto "nowhere" \lyr
  \new Staff { c'8 c' c' c' c' c' c' c'
  c' c' c' c' c' c' c' c' }
>>
@end lilypond

This method is recommended only if the music in the @code{Devnull}
context does not contain melismata.  Melismata are defined by the
@code{Voice} context.  Connecting lyrics to a @code{Devnull} context
makes the voice/lyrics links to get lost, and so does the info on
melismata.  Therefore, if you link lyrics to a @code{Devnull} context,
the implicit melismata get ignored.

@c Conclusion: do not use devnull for lyrics -FV

@c this clarifies http://code.google.com/p/lilypond/issues/detail?id=248

@node Spacing out syllables
@unnumberedsubsubsec Spacing out syllables

@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,verbatim,fragment,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
layout.

@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

@c @snippets
@c This snippet has been renamed to "lyrics-alignment.ly"
@c update as soon as lsr/is updated -vv
@c @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
@c {lyrics-alignment.ly}

@c TODO: move to LSR -vv
@snippets

Checking to make sure that text scripts and lyrics are within the margins is
a relatively large computational task.  To speed up processing, LilyPond does
not perform such calculations by default; to enable it, use

@example
\override Score.PaperColumn #'keep-inside-line = ##t
@end example

To make lyrics avoid bar lines as well, use

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

@c TODO Create and add lsr example of lyricMelismaAlignment
@c It's used like this to center-align all lyric syllables,
@c even when notes are tied. -td

@ignore
\layout
{
     \context { \Score lyricMelismaAlignment = #0 }
}
@end ignore


@node Placement of lyrics between staves
@unnumberedsubsubsec Placement of lyrics between staves

@c TODO Add text from -user
@c TODO Add new spacing properties, centering lyrics, etc
TBC

@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,fragment]
\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[fragment,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.  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

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
to switch the melody for a line of lyrics during the text.  This is
done by setting the @code{associatedVoice} property.  In the example

@lilypond[ragged-right,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 a melody called @q{lahlah},

@example
\new Lyrics \lyricsto "lahlah" @{
  Ju -- ras -- sic Park
@}
@end example


The second stanza initially is set to the @code{lahlah} context, but
for the syllable @q{ran}, it switches to a different melody.
This is achieved with
@example
\set associatedVoice = alternative
@end example

@noindent
Here, @code{alternative} is the name of the @code{Voice} context
containing the triplet.

@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
bug.

@example
\new Lyrics \lyricsto "lahlah" @{
  \set associatedVoice = alternative % applies to "ran"
  Ty --
  ran --
  no --
  \set associatedVoice = lahlah % applies to "rus"
  sau -- rus Rex
@}
@end example

@noindent
The underlay is switched back to the starting situation by assigning
@code{lahlah} to @code{associatedVoice}.


@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

@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::
* 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 formatting}.

@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 Manual:
@ref{Grouping staves},
@ref{Hiding staves},
@ref{Instrument transpositions},
@ref{Nested staff groups},
@ref{Page formatting},
@ref{Separating systems},
@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]
\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 cued notes.  The following example shows
how this is done.  Note that the name of the grob for overriding
the cued instrument name is @code{InstrumentSwitch}.

@lilypond[quote,verbatim]
flute = \relative c'' {
  s4 s4 e g
}
\addQuote "flute" { \flute }

pianoRH = \relative c'' {
  c4. g8
  % position name of cued instrument just before the cued notes
  \once \override CueVoice.InstrumentSwitch
    #'self-alignment-X = #RIGHT
  % position name of cued instrument above the staff
  \once \override CueVoice.InstrumentSwitch #'direction = #UP
  \set CueVoice.instrumentCueName = "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 cued the instrument part should
specify its key so the conversion of its cued 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 cued 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 cued instrument just before the cued notes
  \once \override CueVoice.InstrumentSwitch
    #'self-alignment-X = #RIGHT
  % position name of cued instrument below the staff
  \once \override CueVoice.InstrumentSwitch #'direction = #DOWN
  \set CueVoice.instrumentCueName = "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 extremely tedious, and the notes of the piano
part would be obscured by the many overrides.  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 cued 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 cued 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

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