Doc: Issue 3877: clarify use of \lyricmode and variants

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

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 187e10566f2970b358bce44a92f543ae645e25b5..0b69693beae7e38c57ecf88d4cc217c9cb806fda 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -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}
 
@@ -1682,13 +1691,6 @@ words = \lyricmode { la __ la __ }
 >>
 @end lilypond
 
-The @code{NullVoice} context must be placed within a @code{Staff}
-context and contain notes that are already being displayed in that staff and that are also in the same octave.  Otherwise the
-@code{NullVoice} may interact with the printed voices in
-unexpected ways.  For example, arbitrary notes in the
-@code{NullVoice} may cause accidentals to appear (or disappear) on
-the staff.
-
 This method also can be used with the @code{\partcombine}
 function, which does not allow lyrics on its own:
 
@@ -1724,23 +1726,13 @@ aligner = \relative { b'8( c d c) d( d d d) }
 words = \lyricmode { la __ la __ }
 
 \new ChoirStaff <<
-  \new Staff <<
-    \soprano
-    \new NullVoice = "aligner" \aligner
-  >>
+  \new Staff \soprano
+  \new NullVoice = "aligner" \aligner
   \new Lyrics \lyricsto "aligner" \words
   \new Staff \partcombine \altoOne \altoTwo
 >>
 @end lilypond
 
-However, note that in the second half of the measure above, the
-notes in the @code{NullVoice} context reflect the rhythm of the
-lower staff, but they do not deviate from the single pitch being
-displayed in the staff to which the @code{NullVoice} belongs.
-While not actually required in this particular example, it is a
-good idea in general to enter the notes in this way.
-
-
 @node Stanzas
 @subsection Stanzas
 
@@ -2406,7 +2398,7 @@ Notation Reference:
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
-@ref{Explicit breaks},
+@ref{Breaks},
 @ref{Vertical spacing}.
 
 Internals Reference:
@@ -2589,52 +2581,43 @@ 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.
+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]
-\addInstrumentDefinition #"kaspar"
-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
-     (shortInstrumentName . "Kas.")
-     (clefGlyph . "clefs.G")
-     (clefTransposition . -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")
-     (clefTransposition . 0)
-     (middleCPosition . 6)
-     (clefPosition . 2)
-     (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
-     (midiInstrument . "choir aahs"))
+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' {
-  \instrumentSwitch "kaspar"
+  \kaspar
   c4 c c c
-  \instrumentSwitch "melchior"
+  \melchior
   a4 a a a
-  \instrumentSwitch "kaspar"
+  \kaspar
   c4 c c c
 }
 @end lilypond
 
 @seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
+
 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