doc: explain how to add lyrics to polyphonic sections (issue 3236)

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index c6d3ee02bc8fe176fc7b578e5d0e3a27a8ba149c..3e4d3fd11e6bc81b42cf249aac2e7e3104536daa 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -1628,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
@@ -2178,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