More tutorial improvements from Trevor Daniels.

diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 2f121cc6e7df55d968fc124a37681a7dee027e63..6f65af792c9f2ae1d8dca0759c89779b661ab3cf 100644 (file)
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1160,23 +1160,27 @@ See @ruser{Basic polyphony}.
 This section introduces vocal music and simple song sheets.
 
 @menu
-* Printing lyrics::             
+* Setting simple songs::        
+* Aligning lyrics to a melody::  
+* Lyrics to multiple staves::   
 * A lead sheet::                
 @end menu
 
 
-@node Printing lyrics
-@subsection Printing lyrics
+@node Setting simple songs
+@subsection Setting simple songs
 
 @cindex Lyrics
 @cindex Songs
-Consider a simple melody:
+Here is the start of the melody to a nursery
+rhyme, @qq{Girls and boys come out to play}:
 
 @lilypond[verbatim,quote,ragged-right]
-\relative c'' {
-  a4 e c8 e r4
-  b2 c4( d)
-}
+ \relative c'' {
+  \key g \major
+  \time 6/8
+  d4 b8 c4 a8 d4 b8 g4
+ }
 @end lilypond
 
 The lyrics can be set to these notes, combining both with the
@@ -1185,48 +1189,194 @@ syllable with a space.
 
 @lilypond[verbatim,quote,ragged-right]
 <<
-  \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
-  }
-  \addlyrics { One day this shall be free }
+ \relative c'' {
+  \key g \major
+  \time 6/8
+  d4 b8 c4 a8 d4 b8 g4
+ }
+ \addlyrics {
+  Girls and boys come out to play,
+ }
 >>
 @end lilypond
 
+Note the curly brackets delimiting both the music and the lyrics,
+and the angle brackets @code{<< ... >>} around the whole piece to
+show that the music and lyrics are to occur at the same time.
+
+@node Aligning lyrics to a melody
+@subsection Aligning lyrics to a melody
+
 @cindex melisma
 @cindex extender line
-This melody ends on a @rglos{melisma}, a single syllable
-(@q{free}) sung to more than one note.  This is indicated with an
-@emph{extender line}.  It is entered as two underscores @code{__}:
+@cindex hyphens
+@cindex underscore
+
+The next line in the nursery rhyme is @q{The moon doth shine as
+bright as day}.  Let's extend it:
 
+@lilypond[verbatim,quote,ragged-right]
+<<
+ \relative c'' {
+  \key g \major
+  \time 6/8
+  d4 b8 c4 a8 d4 b8 g4 g8
+  a4 b8 c b a
+  d4 b8 g4.
+ }
+ \addlyrics {
+  Girls and boys come out to play,
+  The moon doth shine as bright as day;
+ }
+>>
+@end lilypond
+
+We see the extra lyrics do not align properly with the notes.  The
+word @q{shine} should be sung on two notes, not one.  This is
+called a @rglos{melisma}, a single syllable sung to more than one
+note.  There are several ways to spread a syllable over multiple
+notes, the simplest being to add a slur across them (see @ref{Ties
+and slurs}):
+
+@lilypond[verbatim,quote,ragged-right]
+<<
+ \relative c'' {
+  \key g \major
+  \time 6/8
+  d4 b8 c4 a8 d4 b8 g4 g8
+  a4 b8 c([ b)] a
+  d4 b8 g4.
+ }
+ \addlyrics {
+  Girls and boys come out to play,
+  The moon doth shine as bright as day;
+ }
+>> 
+@end lilypond
+
+Here we have also used manual beaming (the square brackets @code{[
+]} ) to generate the beaming which is customarily used with lyrics.
+
+If a syllable extends over several notes or a single very long
+note an @emph{extender line} is usually drawn from the syllable
+extending under all the notes for that syllable.  It is entered as
+two underscores @code{__}.  Here is an example from the first
+three bars of Dido's Lament, from Purcell's Dido and Æneas:
+ 
 @lilypond[verbatim,quote,ragged-right]
 <<
   \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
+    \key g \minor
+    \time 3/2
+    g2 a bes
+    bes( a) b
+    c4.( bes8 a4. g8 fis4.) g8
+    fis1
+  }
+  \addlyrics {
+    When I am laid, am laid __ in earth,
   }
-  \addlyrics { One day this shall be free __ }
 >>
 @end lilypond
 
-Similarly, hyphens between words can be entered as two dashes,
-resulting in a centered hyphen between two syllables
+None of the examples so far have involved words containing more
+than one syllable.  Such words are usually split one syllable to a
+note, with hyphens between syllables.  Such hyphens are entered as
+two dashes, resulting in a centered hyphen between the syllables.
+Here is an example showing this and everything we have learned so
+far about aligning lyrics to notes.
 
-@c no ragged-right here because otherwise the hypens get lost.
+@c no ragged-right here because otherwise the hyphens get lost,
+@c but the example is long enough to avoid looking strange.
 @lilypond[quote,verbatim]
 <<
   \relative c' {
-    \time 2/4
-    f4 f c c
+    \key g \major
+    \time 3/4
+    \partial 4
+    d4
+    g4 g a8( b) g4
+    g4 b8( c) d4 d
+    e4 c2
+  }
+  \addlyrics {
+    A -- way in a __ man -- ger, no __ crib for a bed, __
   }
-  \addlyrics { A -- le -- gri -- a }
 >>
 @end lilypond
 
+Some lyrics, especially those in Italian, require the opposite:
+setting more than one syllable to a single note.  This is
+achieved by linking the syllables together with a single
+underscore @code{_} (with no spaces), or enclosing them in
+quotes.  Here's an example from Rossini's Figaro, where
+@q{al} has to be sung on the same note as the @q{go} of 
+@q{Largo} in Figaro's aria @q{Largo al factotum}:
+
+@c no ragged-right here because otherwise the hyphens get lost,
+@c but the example is long enough to avoid looking strange.
+@lilypond[quote,verbatim]
+<<
+  \relative c' {
+    \clef bass
+    \key c \major
+    \time 6/8
+    c4.~ c8 d b c([ d)] b c d b c
+  }
+  \addlyrics {
+    Lar -- go_al fac -- to -- tum del -- la cit -- tà
+  }
+>>
+@end lilypond
+
+
+@seealso
+@quotation
+More options, such as inserting explicit rhythms into lyrics,
+inserting lyric ties (e.g., between @q{go al} above, 
+alternative ways of handling melismata,
+and adding extra verses,
+are discussed in @ruser{Vocal music}.
+@end quotation
+
+@node Lyrics to multiple staves
+@subsection Lyrics to multiple staves
+
+The simple approach using @code{\addlyrics} can be used for
+placing lyrics under more than one staff.  Here is an
+example from Handel's Judas Maccabæus:
+
+@lilypond[verbatim,quote,ragged-right]
+<<
+  {
+    \time 6/8
+    \partial 8
+  }
+  \relative c'' { \key f \major
+    c8 c([ bes)] a a([ g)] f f'4. b, c4.~ c4
+  }
+  \addlyrics {
+    Let flee -- cy flocks the hills a -- dorn, __
+  }
+  \relative c' { \key f \major
+    r8 r4. r4 c8 a'([ g)] f f([ e)] d e([ d)] c bes'4
+  }
+  \addlyrics {
+    Let flee -- cy flocks the hills a -- dorn,
+  }
+>>
+@end lilypond
+
+but scores any more complex than this simple example are
+better produced by separating out the staff structure
+from the notes and lyrics with identifiers.  These are
+discussed later (see @ref{Organizing pieces with identifiers}).
+
 @seealso
 @quotation
-More options, such as putting multiple stanzas below a melody, are
-discussed in @ruser{Vocal music}.
+More options, such as putting multiple stanzas below the score,
+setting choral music, and lyrics to divided voices, 
+are discussed in @ruser{Vocal music}.
 @end quotation