Begin merging Valentin's vocal music improvements.

diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index 28fa837d7510ea90fa62a9375f3c10cc1be52566..07b54772e9859a00c06090a195f61d2b488143cd 100644 (file)
--- a/Documentation/user/instrument-notation.itely
+++ b/Documentation/user/instrument-notation.itely
@@ -670,8 +670,8 @@ note@tie{}D.
 Song texts must be aligned with the notes of their melody.
 @end itemize
 
-There are a few different ways to define lyrics; the simplest
-way is to use the @code{\addlyrics} function.
+There are a few different ways to define lyrics; the shall begin
+by examining the simplest method, and gradually increase complexity.
 
 @menu
 * Setting simple songs::        
@@ -714,8 +714,10 @@ To make lyrics avoid barlines as well, use
 @node Setting simple songs
 @subsection Setting simple songs
 
-The easiest way to add lyrics to a melody is to append
 @cindex \addlyrics
+
+The easiest way to add lyrics to a melody is to append
+
 @example
 \addlyrics @{ @var{the lyrics} @}
 @end example
@@ -741,7 +743,8 @@ More stanzas can be added by adding more
 @end lilypond
 
 The command @code{\addlyrics} cannot handle polyphony settings.  For these
-cases you should use @code{\lyricsto} and @code{\lyricmode}.
+cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
+introduced in @ref{Entering lyrics}.
 
 
 
@@ -751,6 +754,8 @@ cases you should use @code{\lyricsto} and @code{\lyricmode}.
 @cindex lyrics
 @funindex \lyricmode
 @cindex punctuation
+@cindex spaces, in lyrics
+@cindex quotes, in lyrics
 
 Lyrics are entered in a special input mode.  This mode is introduced
 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
@@ -758,6 +763,7 @@ by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
 with punctuation and accents, and the input @code{d} is not parsed as
 a pitch, but rather as a one letter syllable.  Syllables are entered
 like notes, but with pitches replaced by text.  For example,
+
 @example
 \lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
 @end example
@@ -785,7 +791,15 @@ opening brace is not balanced
 @noindent
 Similarly, a period which follows an alphabetic sequence is included in
 the resulting string.  As a consequence, spaces must be inserted around
-property commands
+property 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
@@ -1470,27 +1484,25 @@ text = \lyricmode {
 its fleece was white as snow.
 }
 
-\book{
-  \score{ <<
-    \new Voice = "one" { \melody }
-    \new Lyrics \lyricsto "one" \text
-       >>
-    \layout { }
-  }
-  \markup { \column{
-    \line{ Verse 2. }
-    \line{ All the children laughed and played }
-    \line{ To see a lamb at school. }
-    }
+\score{ <<
+  \new Voice = "one" { \melody }
+  \new Lyrics \lyricsto "one" \text
+>>
+  \layout { }
+}
+\markup { \column{
+  \line{ Verse 2. }
+  \line{ All the children laughed and played }
+  \line{ To see a lamb at school. }
   }
-  \markup{
-    \wordwrap-string #"
-    Verse 3.
+}
+\markup{
+  \wordwrap-string #"
+  Verse 3.
 
-    Mary took it home again,
+  Mary took it home again,
 
-    It was against the rule."
-  }
+  It was against the rule."
 }
 @end lilypond