Merge remote branch 'origin/master' into release/unstable

[lilypond.git] / Documentation / notation / vocal.itely

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index a9914f3a729f85964bb0f88b6cccd251544543fc..013fabfd9b17b804d5a3be7d6b058c28f2bfb0ef 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -156,7 +156,7 @@ into the input file, providing it is saved with UTF-8 encoding.
 For more information, see @ref{Special characters}.
 
 @lilypond[quote,verbatim]
-\relative c'' { d8 c16 a bes8 f e' d c4 }
+\relative c'' { d8 c16 a bes8 f ees' d c4 }
 \addlyrics { „Schad’ um das schö -- ne grü -- ne Band, }
 @end lilypond
 
@@ -218,13 +218,22 @@ Snippets:
 @funindex \addlyrics
 @funindex \lyricsto
 
-Lyrics are printed by interpreting them in the context called
-@code{Lyrics}, see @ref{Contexts explained}.
+Lyrics are interpreted in @code{\lyricmode} and printed in a
+@code{Lyrics} context, see @ref{Contexts explained}.
 
 @example
 \new Lyrics \lyricmode @{ @dots{} @}
 @end example
 
+Two variants of @code{\lyricmode} additionally set an associated
+context used to synchronise the lyric syllables to music.  The more
+convenient @code{\addlyrics} immediately follows the musical content
+of the Voice context with which it should be synchronised, implicitly
+creating a Lyrics context of its own.  The more versatile
+@code{\lyricsto} requires both specifying the associated Voice context
+by name and explicitly creating a containing Lyrics context.  For
+details see @ref{Automatic syllable durations}.
+
 Lyrics can be aligned with melodies in two main ways:
 
 @itemize
@@ -392,9 +401,9 @@ 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}.
+invokes lyric mode automatically.  By default, the lyrics are placed
+underneath the notes.  For other placements, see
+@ref{Placing lyrics vertically}.
 
 @subheading Using @code{\addlyrics}
 
@@ -2641,10 +2650,7 @@ pianoRH = \relative c'' {
   c4. g8
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
-  \new CueVoice {
-    \override InstrumentSwitch.self-alignment-X = #RIGHT
-    \set instrumentCueName = "Flute"
-  }
+  <>^\markup { \right-align { \tiny "Flute" } }
   \cueDuring "flute" #UP { g4 bes4 }
 }
 pianoLH = \relative c { c4 <c' e> e, <g c> }
@@ -2667,11 +2673,7 @@ 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.
+down) and the instrument name is positioned below the staff.
 
 @lilypond[quote,verbatim]
 clarinet = \relative c' {
@@ -2683,11 +2685,7 @@ clarinet = \relative c' {
 pianoRH = \relative c'' {
   \transposition c'
   % position name of cue-ing instrument below the staff
-  \new CueVoice {
-    \override InstrumentSwitch.self-alignment-X = #RIGHT
-    \override InstrumentSwitch.direction = #DOWN
-    \set instrumentCueName = "Clar."
-  }
+  <>_\markup { \right-align { \tiny "Clar." } }
   \cueDuring "clarinet" #DOWN { c4. g8 }
   g4 bes4
 }
@@ -2735,7 +2733,6 @@ Snippets:
 @rlsr{Vocal music}.
 
 Internals Reference:
-@rinternals{InstrumentSwitch},
 @rinternals{CueVoice}.
 
 @knownissues