X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fvocal.itely;h=62600cf5478aa0f2d27d84db3a5453d6119183d5;hb=3b65aea88185c2ce92b1a905e0535d7d4c60d71a;hp=c91fe3253fc1948ea5e9614f09daf67ab62510e7;hpb=ed76c4d5b51a69c84b10a7ecc1d29d3faf4081b9;p=lilypond.git

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index c91fe3253f..62600cf547 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.17.19"
+@c \version "2.19.2"
 
 @node Vocal music
 @section Vocal music
@@ -654,8 +654,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 +755,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 +783,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 __ _ _ _
@@ -873,6 +873,7 @@ Internals Reference:
 * Placing syllables horizontally::
 * Lyrics and repeats::
 * Divisi lyrics::
+* Polyphony with shared lyrics::
 @end menu
 
 
@@ -1155,7 +1156,7 @@ To make lyrics avoid bar lines as well, use
     \Lyrics
       \consists "Bar_engraver"
       \consists "Separating_line_group_engraver"
-      \override BarLine.transparent = ##t
+      \hide BarLine
   @}
 @}
 @end example
@@ -1647,6 +1648,111 @@ passage is the proper construct to use, see section
 @emph{Temporary polyphonic passages} in @ref{Single-staff polyphony}.
 
 
+@node Polyphony with shared lyrics
+@unnumberedsubsubsec Polyphony with shared lyrics
+
+@cindex NullVoice
+@cindex polyphony, shared lyrics
+@cindex lyrics, shared among voices
+@cindex \partcombine and lyrics
+@funindex \partcombine
+
+When two voices with different rhythms share the same lyrics,
+aligning the lyrics to one of the voices may lead to problems in
+the other voice.  For example, the second lyric extender below is
+too short, since the lyrics are aligned only to the top voice:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice = "sopranoVoice" { \voiceOne \soprano }
+  \new Voice { \voiceTwo \alto }
+  \new Lyrics \lyricsto "sopranoVoice" \words
+>>
+@end lilypond
+
+To get the desired result, align the lyrics to a new
+@code{NullVoice} context containing a suitable combination of the
+two voices.  The notes of the @code{NullVoice} context do not
+appear on the printed page, but can be used to align the lyrics
+appropriately:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+aligner = \relative { b'8( c d c) b( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice { \voiceOne \soprano }
+  \new Voice { \voiceTwo \alto }
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+>>
+@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:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+alto = \relative { g'2 b8( a g a) }
+aligner = \relative { b'8( c d c) b( a g a) }
+words = \lyricmode { la __ la __ }
+
+\new Staff <<
+  \new Voice \partcombine \soprano \alto
+  \new NullVoice = "aligner" \aligner
+  \new Lyrics \lyricsto "aligner" \words
+>>
+@end lilypond
+
+@knownissues
+The @code{\addLyrics} function only works with @code{Voice} lyrics
+and so cannot be used with @code{NullVoice}.
+
+@noindent
+The @code{\partcombine} function is described in
+@ref{Automatic part combining}.
+
+Lastly, this method can be used even when the voices are in
+different staves, and is not limited to only two voices:
+
+@lilypond[quote,verbatim]
+soprano = \relative { b'8( c d c) d2 }
+altoOne = \relative { g'2 b8( a b4) }
+altoTwo = \relative { d'2 g4( fis8 g) }
+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 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
 
@@ -1819,7 +1925,7 @@ changed:
 <<
   \new Voice = melody \relative c' {
     f4 \appoggiatura a32 b4
-    \grace { f16[ a16] } b2
+    \grace { f16 a16 } b2
     \afterGrace b2 { f16[ a16] }
     \appoggiatura a32 b4
     \acciaccatura a8 b4
@@ -1848,7 +1954,7 @@ block:
 @lilypond[verbatim,ragged-right,quote]
 <<
   \new Voice = melody \relative c' {
-    \grace { c16[( d e f] }
+    \grace { c16( d e f }
     g1) f
   }
   \new Lyrics \with { includeGraceNotes = ##t }
@@ -2176,6 +2282,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
@@ -2816,7 +2924,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 = { \hide Staff.Stem }
 
 \relative c' {
   \stemOff