Issue 4078: Doc: Use variables rather than instrument definitions

  Using variables for switching character names in vocal music
  rather than instrument definitions is easier to understand,
  easier to set up and quicker to type.  It also frees up the
  use of instrument definitions so they may be tailored for
  better use in instrumental compositions.

  Remove the mention of \transposition.  This is never required
  in vocal music.

  Adjust references to match the changes.

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 912378ab0877cede4d7fa8d02fc0fc68d1a076bc..a86c0acbab70f4da7cc043c1ebd131d3d2daaa37 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -2572,54 +2572,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.  As notes for vocal parts are usually entered
-at sounding pitch no instrument transposition is required, even
-when, as here, the tenor line is printed an octave higher.
+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 0 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