From 7a33fdecc591b5f0826476cb24f1dda747388d2d Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Sun, 8 Jul 2007 15:17:33 -0700
Subject: [PATCH] From Valentin: clarify identifiers with Vocal music.

---
 Documentation/user/instrument-notation.itely | 111 +++++++++----------
 1 file changed, 50 insertions(+), 61 deletions(-)

diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index 27a48002a1..977a0be395 100644
--- a/Documentation/user/instrument-notation.itely
+++ b/Documentation/user/instrument-notation.itely
@@ -983,39 +983,6 @@ is the same as
 @c TODO: Move the following section to 
 @c "Working with lyrics and identifiers"
 
-For different or more complex orderings, the best way is to setup the
-hierarchy of staves and lyrics first, e.g.,
-@example
-\new ChoirStaff <<
-  \new Voice = "soprano" @{ @emph{music} @}
-  \new Lyrics = "sopranoLyrics" @{ s1 @}
-  \new Lyrics = "tenorLyrics" @{ s1 @}
-  \new Voice = "tenor" @{ @emph{music} @}
->>
-@end example
-
-and then combine the appropriate melodies and lyric lines
-
-@example
-\context Lyrics = sopranoLyrics \lyricsto "soprano"
-  @emph{the lyrics}
-@end example
-
-@noindent
-The final input would resemble
-
-@example
-<<\new ChoirStaff << @emph{setup the music} >>
-  \lyricsto "soprano" @emph{etc}
-  \lyricsto "alto" @emph{etc}
-  @emph{etc}
->>
-@end example
-
-@seealso
-
-Program reference: @internalsref{LyricCombineMusic},
-@internalsref{Lyrics}.
 
 @node Assigning more than one syllable to a single note
 @subsubsection Assigning more than one syllable to a single note
@@ -1161,41 +1128,63 @@ Program reference: @internalsref{LyricExtender},
 @subsection Working with lyrics and identifiers
 @cindex lyrics, identifiers
 
-Lyrics can also be entered without @code{\lyricsto}.  In this case the
-duration of each syllable must be entered explicitly, for example,
-
+To define identifiers containing lyrics, the function @code{\lyricmode}
+must be used. You do not have to enter durations though, if you add
+@code{\addlyrics} or @code{\lyricsto}
+when invoking your identifier.
+ 
 @example
-play2 the4 game2.
-sink2 or4 swim2.
+verseOne = \lyricmode @{ Joy to the world the Lord is come @}
+\score @{
+ <<
+   \new Voice = "one" \relative c'' @{
+     \autoBeamOff
+     \time 2/4
+     c4 b8. a16 g4. f8 e4 d c2
+   @}
+   \addlyrics @{ \verseOne @}
+ >>
+@}
 @end example
-
-The alignment to a melody can be specified with the
-@code{associatedVoice} property,
-
+ 
+@c TODO: Move the following section to 
+@c "Working with lyrics and identifiers"
+ 
+For different or more complex orderings, the best way is to setup the
+hierarchy of staves and lyrics first, e.g.,
 @example
-\set associatedVoice = #"lala"
+\new ChoirStaff <<
+  \new Voice = "soprano" @{ @emph{music} @}
+  \new Lyrics = "sopranoLyrics" @{ s1 @}
+  \new Lyrics = "tenorLyrics" @{ s1 @}
+  \new Voice = "tenor" @{ @emph{music} @}
+>>
 @end example
-
+ 
+and then combine the appropriate melodies and lyric lines
+ 
+@example
+\context Lyrics = sopranoLyrics \lyricsto "soprano"
+@emph{the lyrics}
+@end example
+ 
 @noindent
-The value of the property (here: @code{"lala"}) should be the name of
-a @internalsref{Voice} context.  Without this setting, extender lines
-will not be formatted properly.
-
-Here is an example demonstrating manual lyric durations,
-
-@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
-<< \new Voice = "melody" {
-     \time 3/4
-     c2 e4 g2.
-  }
-  \new Lyrics \lyricmode {
-    \set associatedVoice = #"melody"
-    play2 the4 game2.
-  } >>
-@end lilypond
-
 
+The final input would resemble
+ 
+@example
+<<\new ChoirStaff << @emph{setup the music} >>
+ \lyricsto "soprano" @emph{etc}
+ \lyricsto "alto" @emph{etc}
+@emph{etc}
+>>
+@end example
+ 
+@seealso
+ 
 @c TODO: document \new Staff << Voice \lyricsto >> bug
+Program reference: @internalsref{LyricCombineMusic},
+@internalsref{Lyrics}.  
 
 @node Flexibility in placement
 @subsection Flexibility in placement
-- 
2.39.2