From c0c3cd6ac43112ce392f9559555f723b359580a6 Mon Sep 17 00:00:00 2001
From: Trevor Daniels <t.daniels@treda.co.uk>
Date: Sat, 30 Aug 2014 21:44:23 +0100
Subject: [PATCH] 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.
---
 Documentation/notation/vocal.itely | 55 ++++++++++++------------------
 1 file changed, 22 insertions(+), 33 deletions(-)

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 912378ab08..a86c0acbab 100644
--- 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
-- 
2.39.2