+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 {
+ \clef "G_8"
+ c'4 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 {
+ 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 c' {
+ \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 variables to hold the definitions for each character so
+that the switch of characters can be indicated easily and concisely.
+
+@lilypond[quote,verbatim]
+kaspar = {
+ \clef "G_8"
+ \set Staff.shortVocalName = "Kas."
+ \set Staff.midiInstrument = "voice oohs"
+ <>^\markup \smallCaps "Kaspar"
+}
+
+melchior = {
+ \clef "bass"
+ \set Staff.shortVocalName = "Mel."
+ \set Staff.midiInstrument = "choir aahs"
+ <>^\markup \smallCaps "Melchior"
+}
+
+\relative c' {
+ \kaspar
+ c4 c c c
+ \melchior
+ a4 a a a
+ \kaspar
+ c4 c c c
+}
+@end lilypond
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
+
+Notation Reference:
+@ref{Text},
+@ref{Text markup commands}.
+
+
+@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 {
+ s4 s4 e'' g
+}
+\addQuote "flute" { \flute }
+
+pianoRH = \relative {
+ c''4. g8
+ % position name of cue-ing instrument just before the cue notes,
+ % and above the staff
+ <>^\markup { \right-align { \tiny "Flute" } }
+ \cueDuring "flute" #UP { g4 bes4 }
+}
+pianoLH = \relative { 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.
+
+@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
+ <>_\markup { \right-align { \tiny "Clar." } }
+ \cueDuring "clarinet" #DOWN { c4. g8 }
+ g4 bes4
+}
+pianoLH = \relative { 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,quote,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{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.
+