X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=54a656959183fa54feaadf145adb0b7c11bb0c2d;hb=94dc452301cc0d1e9983f5aeb784884f7fe8c964;hp=9d645b78e0c5e7cded77c25c27e10d1580f5f100;hpb=4ab6e4df934e57c51dbbdbf2c209273c6cb5b888;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 9d645b78e0..54a6569591 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -7,7 +7,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.14.0"
+@c \version "2.17.18"
 
 @node Vocal music
 @section Vocal music
@@ -149,25 +149,6 @@ compile.  Instead, braces should always be surrounded with white space:
 \lyricmode @{ lah lah lah @}
 @end example
 
-@cindex overrides in lyric mode
-@funindex \override in \lyricmode
-
-Similarly, in lyric mode, a period will be included in the
-alphabetic sequence that it follows.  As a consequence, spaces
-must be inserted around the period in @code{\override} commands.
-Do @emph{not} write
-
-@example
-\override Score.LyricText #'font-shape = #'italic
-@end example
-
-@noindent
-but instead use
-
-@example
-\override Score . LyricText #'font-shape = #'italic
-@end example
-
 Punctuation, lyrics with accented characters, characters from
 non-English languages, or special characters (such as the heart
 symbol or slanted quotes), may simply be inserted directly
@@ -694,6 +675,8 @@ entering lyrics:
 >>
 @end lilypond
 
+Note that phrasing slurs do not affect the creation of melismata.
+
 @item
 Notes are considered a melisma if they are manually beamed,
 providing automatic beaming is switched off.  See
@@ -1031,7 +1014,7 @@ follows:
   <<
     \new Lyrics = "lyrics" \with {
       % lyrics above a staff should have this override
-      \override VerticalAxisGroup #'staff-affinity = #DOWN
+      \override VerticalAxisGroup.staff-affinity = #DOWN
     }
     \new Staff {
       \new Voice = "melody" {
@@ -1062,7 +1045,7 @@ is an example of the second method:
     \new Lyrics = "sopranos"
     \new Lyrics = "contraltos" \with {
       % lyrics above a staff should have this override
-      \override VerticalAxisGroup #'staff-affinity = #DOWN
+      \override VerticalAxisGroup.staff-affinity = #DOWN
     }
     \new Staff {
       \new Voice = "contraltos" {
@@ -1084,8 +1067,8 @@ is an example of the second method:
 @end lilypond
 
 Other combinations of lyrics and staves may be generated by
-elaborating these examples, or by examining the
-@rlearning{Vocal ensembles} templates in the Learning Manual.
+elaborating these examples, or by examining the templates in the
+Learning Manual, see @rlearning{Vocal ensembles templates}.
 
 @snippets
 @lilypondfile[verbatim,quote,texidoc,doctitle]
@@ -1093,11 +1076,11 @@ elaborating these examples, or by examining the
 
 @seealso
 Learning Manual:
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Context layout order},
-@ref{Creating contexts}.
+@ref{Creating and referencing contexts}.
 
 
 @node Placing syllables horizontally
@@ -1112,7 +1095,7 @@ To increase the spacing between lyrics, set the
 @lilypond[relative=1,verbatim,quote,ragged-right]
 {
   c c c c
-  \override Lyrics.LyricSpace #'minimum-distance = #1.0
+  \override Lyrics.LyricSpace.minimum-distance = #1.0
   c c c c
 }
 \addlyrics {
@@ -1138,7 +1121,7 @@ To make this change for all lyrics in the score, set the property in the
   \layout {
     \context {
       \Lyrics
-      \override LyricSpace #'minimum-distance = #1.0
+      \override LyricSpace.minimum-distance = #1.0
     }
   }
 }
@@ -1155,7 +1138,7 @@ requires additional calculations.  To speed up processing slightly, this
 feature can be disabled:
 
 @example
-\override Score.PaperColumn #'keep-inside-line = ##f
+\override Score.PaperColumn.keep-inside-line = ##f
 @end example
 
 To make lyrics avoid bar lines as well, use
@@ -1166,7 +1149,7 @@ To make lyrics avoid bar lines as well, use
     \Lyrics
       \consists "Bar_engraver"
       \consists "Separating_line_group_engraver"
-      \override BarLine #'transparent = ##t
+      \override BarLine.transparent = ##t
   @}
 @}
 @end example
@@ -1321,6 +1304,54 @@ More verses may be added in a similar way:
 }
 @end lilypond
 
+@cindex alignBelowContext
+@funindex alignBelowContext
+
+However, if this construct is embedded within a multi-staved
+context such as a @code{ChoirStaff} the lyrics of the second and
+third verses will appear beneath the bottom staff.
+
+To position them correctly use @code{alignBelowContext}:
+
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+	  a4 a a a
+	  \repeat volta 3 { b4 b b b }
+          c4 c c c
+	}
+      }
+    }
+    \new Lyrics = "firstVerse" \lyricsto "melody" {
+      Not re -- peat -- ed.
+      <<
+        { The first time words.	}
+	\new Lyrics = "secondVerse"
+        \with { alignBelowContext = #"firstVerse" } {
+	  \set associatedVoice = "melody"
+	  Sec -- ond time words.
+	}
+	\new Lyrics = "thirdVerse"
+        \with { alignBelowContext = #"secondVerse" } {
+	  \set associatedVoice = "melody"
+	  The third time words.
+	}
+      >>
+      The end sec -- tion.
+    }
+    \new Voice = "harmony" {
+      \relative c' {
+        f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
+      }
+    }
+  >>
+}
+@end lilypond
+
+
 
 @c TODO positioning a common line of lyrics
 
@@ -1597,6 +1628,18 @@ attaching lyrics to those specific contexts:
 }
 @end lilypond
 
+It is common in choral music to have a voice part split for
+several measures.  The @code{<< @{@dots{}@} \\ @{@dots{}@} >>}
+construct, where the two (or more) musical expressions are
+separated by double backslashes, might seem the proper way to
+set the split voices.  This construct, however, will assign
+@strong{all} the expressions within it to @strong{NEW Voice
+contexts} which will result in @emph{no lyrics} being set for
+them since the lyrics will be set to the original voice context
+-- not, typically, what one wants.  The temporary polyphonic
+passage is the proper construct to use, see section
+@emph{Temporary polyphonic passages} in @ref{Single-staff polyphony}.
+
 
 @node Stanzas
 @subsection Stanzas
@@ -1826,9 +1869,9 @@ within the lyrics by setting the @code{associatedVoice} property:
     <<
       \new Voice = "alternative" {
         \voiceOne
-        \times 2/3 {
+        \tuplet 3/2 {
           % show associations clearly.
-          \override NoteColumn #'force-hshift = #-3
+          \override NoteColumn.force-hshift = #-3
           f8 f g
         }
       }
@@ -2131,7 +2174,7 @@ the Learning Manual, see @rlearning{Four-part SATB vocal score}.
 @item
 Several templates suitable for various styles of choral music can
 also be found in the Learning Manual, see
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 @item
 For information about @code{ChoirStaff} and @code{PianoStaff} see
@@ -2147,6 +2190,11 @@ the higher part will be directed up and those of the lower part
 down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
 @ref{Single-staff polyphony}.
 
+@item
+When a vocal part temporarily splits, you should use
+@emph{Temporary polyphonic passages}
+(see @ref{Single-staff polyphony}).
+
 @end itemize
 
 @predefined
@@ -2157,7 +2205,7 @@ down.  To do this, use @code{\voiceOne} and @code{\voiceTwo}.  See
 @seealso
 Learning Manual:
 @rlearning{Four-part SATB vocal score},
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Context layout order},
@@ -2237,8 +2285,8 @@ above their respective staves, as shown here:
   \layout {
     \context {
       \Score
-      \override DynamicText #'direction = #UP
-      \override DynamicLineSpanner #'direction = #UP
+      \override DynamicText.direction = #UP
+      \override DynamicLineSpanner.direction = #UP
     }
   }
 }
@@ -2449,7 +2497,7 @@ indicate each change.
   #`((instrumentTransposition . ,(ly:make-pitch -1 0 0))
      (shortInstrumentName . "Kas.")
      (clefGlyph . "clefs.G")
-     (clefOctavation . -7)
+     (clefTransposition . -7)
      (middleCPosition . 1)
      (clefPosition . -2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Kaspar"))
@@ -2459,11 +2507,11 @@ indicate each change.
   #`((instrumentTransposition . ,(ly:make-pitch 0 0 0))
      (shortInstrumentName . "Mel.")
      (clefGlyph . "clefs.F")
-     (clefOctavation . 0)
+     (clefTransposition . 0)
      (middleCPosition . 6)
      (clefPosition . 2)
      (instrumentCueName . ,(markup #:fontsize 1 #:smallCaps "Melchior"))
-     (midiInstrument . "voice aahs"))
+     (midiInstrument . "choir aahs"))
 
 \relative c' {
   \instrumentSwitch "kaspar"
@@ -2518,7 +2566,7 @@ pianoRH = \relative c'' {
   % position name of cue-ing instrument just before the cue notes,
   % and above the staff
   \new CueVoice {
-    \override InstrumentSwitch #'self-alignment-X = #RIGHT
+    \override InstrumentSwitch.self-alignment-X = #RIGHT
     \set instrumentCueName = "Flute"
   }
   \cueDuring "flute" #UP { g4 bes4 }
@@ -2560,8 +2608,8 @@ 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
+    \override InstrumentSwitch.self-alignment-X = #RIGHT
+    \override InstrumentSwitch.direction = #DOWN
     \set instrumentCueName = "Clar."
   }
   \cueDuring "clarinet" #DOWN { c4. g8 }
@@ -2695,8 +2743,8 @@ dialogue = \lyricmode {
 \score {
   <<
     \new Lyrics \with {
-      \override LyricText #'font-shape = #'italic
-      \override LyricText #'self-alignment-X = #LEFT
+      \override LyricText.font-shape = #'italic
+      \override LyricText.self-alignment-X = #LEFT
     }
     { \dialogue }
     \new Staff {
@@ -2762,7 +2810,7 @@ Chants often use quarter notes without stems to indicate the pitch,
 with the rhythm being taken from the spoken rhythm of the words.
 
 @lilypond[verbatim,quote]
-stemOff = { \override Staff.Stem #'transparent = ##t }
+stemOff = { \override Staff.Stem.transparent = ##t }
 
 \relative c' {
   \stemOff
@@ -2796,7 +2844,7 @@ all staves remove the bar line engraver completely:
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
+      \remove "Bar_engraver"
     }
   }
 }
@@ -2808,7 +2856,7 @@ Bar lines can also be removed on a staff-by-staff basis:
 \score {
   \new ChoirStaff <<
     \new Staff
-    \with { \remove Bar_engraver } {
+    \with { \remove "Bar_engraver" } {
       \relative c'' {
         a4 b c2 |
         a4 b c2 |
@@ -2853,9 +2901,9 @@ a4 b c2
 \bar "'"
 a4 b c2
 a4 b c2
-\bar ":"
+\bar ";"
 a4 b c2
-\bar "dashed"
+\bar "!"
 a4 b c2
 \bar "||"
 @end lilypond
@@ -2866,23 +2914,23 @@ modern.  This uses a modified @code{\breathe} mark:
 
 @lilypond[verbatim,quote]
 divisioMinima = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-minima
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-minima
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 divisioMaior = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maior
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-maior
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 divisioMaxima = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::divisio-maxima
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::divisio-maxima
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 finalis = {
-  \once \override BreathingSign  #'stencil = #ly:breathing-sign::finalis
-  \once \override BreathingSign  #'Y-offset = #0
+  \once \override BreathingSign.stencil = #ly:breathing-sign::finalis
+  \once \override BreathingSign.Y-offset = #0
   \breathe
 }
 
@@ -2900,7 +2948,7 @@ finalis = {
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
+      \remove "Bar_engraver"
     }
   }
 }
@@ -2920,9 +2968,9 @@ Chants usually omit the time signature and often omit the clef too.
   \layout {
     \context {
       \Staff
-      \remove Bar_engraver
-      \remove Time_signature_engraver
-      \remove Clef_engraver
+      \remove "Bar_engraver"
+      \remove "Time_signature_engraver"
+      \remove "Clef_engraver"
     }
   }
 }
@@ -2996,8 +3044,7 @@ global = {
       \layout {
         \context {
           \Score
-          \override SpacingSpanner
-          #'base-shortest-duration = #(ly:make-moment 1 2)
+          \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1/2)
         }
         \context {
           \Staff
@@ -3029,7 +3076,7 @@ durations.
 @seealso
 Learning Manual:
 @rlearning{Visibility and color of objects},
-@rlearning{Vocal ensembles}.
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Ancient notation},
@@ -3188,11 +3235,12 @@ The use of markup to center text, and arrange lines in columns is
 described in @ref{Formatting text}.
 
 Most of these elements are shown in one or other of the two verses
-in the template, see @qq{Psalms} in @rlearning{Vocal ensembles}.
+in the template, see @rlearning{Psalms}.
 
 @seealso
 Learning Manual:
-@rlearning{Vocal ensembles}.
+@rlearning{Psalms},
+@rlearning{Vocal ensembles templates}.
 
 Notation Reference:
 @ref{Fonts},