Issue 4075: Doc: Correct the instrumentTransposition setting in NR 2.1.6

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

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 06aa65d46d7133a6933f31facc9e9f91b438d5b2..912378ab0877cede4d7fa8d02fc0fc68d1a076bc 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.30"
+@c \version "2.19.2"
 
 @node Vocal music
 @section Vocal music
@@ -309,11 +309,6 @@ see @ref{Manual syllable durations}.  This technique is also useful
 when setting dialogue over music; for examples showing this, see
 @ref{Dialogue over music}.
 
-When entered in this way the words are left-aligned to the notes
-by default, but may be center-aligned to the notes of a melody by
-specifying an associated voice, if one exists.  For details, see
-@ref{Manual syllable durations}.
-
 @end itemize
 
 @seealso
@@ -509,8 +504,7 @@ completely independently of notes.  In this case do not use
 but with pitches replaced by text -- and the duration of each
 syllable is entered explicitly after the syllable.
 
-By default, syllables will be left-aligned to the corresponding
-musical moment.  Hyphenated lines may be drawn between syllables
+Hyphenated lines may be drawn between syllables
 as usual, but extender lines cannot be drawn when there is no
 associated voice.
 
@@ -519,11 +513,10 @@ Here are two examples:
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
-    \time 3/4
-    c2 e4 g2 f
+    c'2 a f f e e
   }
   \new Lyrics \lyricmode {
-    play1 the4 game4
+    c4. -- a -- f -- f -- e2. -- e
   }
 >>
 @end lilypond
@@ -554,27 +547,22 @@ Here are two examples:
 This technique is useful when writing dialogue over music, see
 @ref{Dialogue over music}.
 
-To center-align syllables on the notes at the corresponding musical
-moments, set @code{associatedVoice} to the name of the Voice context
-containing those notes.  When @code{associatedVoice} is set, both
-double hyphens and double underscores can be used to draw
-hyphenated lines and extenders under melismata correctly.
+To change syllable alignment, simply override the @code{self-alignment-X}
+property:
 
 @lilypond[relative=1,verbatim,quote]
 <<
   \new Voice = "melody" {
     \time 3/4
-    c2 e4 g f g
+    c2 e4 g2 f
   }
   \new Lyrics \lyricmode {
-    \set associatedVoice = #"melody"
-    play2 the4 game2. __
+    \override LyricText.self-alignment-X = #LEFT
+    play1 a4 game4
   }
 >>
 @end lilypond
 
-@c TODO see also feature request 707 - show how to do this with manual durations
-
 @seealso
 Notation Reference:
 @ref{Dialogue over music}.
@@ -654,8 +642,8 @@ together:
   \new Voice = "melody" {
     \time 3/4
     f4 g2 ~ |
-    g4 e2 ~ |
-    e8
+    4 e2 ~ |
+    8
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e __
@@ -755,7 +743,7 @@ without their indicating melismata.  To do this, set
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
-    g8 [ f ] f4 ~ f
+    g8 [ f ] f4 ~ 4
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- e e -- le -- i -- son
@@ -783,7 +771,7 @@ should be included in the melisma:
     \time 3/4
     \set melismaBusyProperties = #'()
     c4 d ( e )
-    g8 [ f ] ~ f4 ~ f
+    g8 [ f ] ~ 4 ~ f
   }
   \new Lyrics \lyricsto "melody" {
     Ky -- ri -- _ e __ _ _ _
@@ -1694,13 +1682,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:
 
@@ -1736,23 +1717,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
 
@@ -2282,6 +2253,8 @@ Several common topics in choral music are described fully elsewhere:
 @item
 An introduction to creating an SATB vocal score can be found in
 the Learning Manual, see @rlearning{Four-part SATB vocal score}.
+There is also a built-in template which simplifies the entry of
+SATB vocal music, see @rlearning{Built-in templates}.
 
 @item
 Several templates suitable for various styles of choral music can
@@ -2416,7 +2389,7 @@ Notation Reference:
 @ref{Score layout},
 @ref{Separating systems},
 @ref{Setting the staff size},
-@ref{Using an extra voice for breaks},
+@ref{Explicit breaks},
 @ref{Vertical spacing}.
 
 Internals Reference:
@@ -2602,11 +2575,13 @@ c c c
 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.
+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.
 
 @lilypond[quote,verbatim]
 \addInstrumentDefinition #"kaspar"
-  #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
+  #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
      (shortInstrumentName . "Kas.")
      (clefGlyph . "clefs.G")
      (clefTransposition . -7)