From 6e818e3e10f397ef94525b3a2698a1c75e67b706 Mon Sep 17 00:00:00 2001
From: Valentin Villenave <valentin@villenave.net>
Date: Fri, 15 Oct 2010 12:23:26 +0200
Subject: [PATCH] Doc: NR 2.1 Vocal proofreading, take2

This commit aims to make lyrics positioning above/below Staff
more progressive and hopefully easier to understand.
---
 Documentation/notation/vocal.itely | 47 +++++++++++++++++-------------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 5c5b87b5f4..69db16abb1 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -764,10 +764,13 @@ and then combine the appropriate melodies and lyric lines:
 The final input would resemble
 
 @example
-<<\new ChoirStaff << @emph{setup the music} >>
- \lyricsto "soprano" @emph{etc}
- \lyricsto "alto" @emph{etc}
-@emph{etc}
+<<
+  \new ChoirStaff <<
+    @emph{setup the music}
+  >>
+  \lyricsto "soprano" @emph{etc}
+  \lyricsto "alto" @emph{etc}
+  @emph{etc}
 >>
 @end example
 
@@ -784,9 +787,10 @@ Internals Reference:
 @cindex placement of lyrics
 @cindex lyrics, positioning
 
-Lyrics are positioned above the staff, below the staff, or between
-staves, depending on the type of music.  To place lyrics below the
-associated staff simply define the Lyrics context below the Staff
+Depending on the type of music, lyrics may be positioned
+above the staff, below the staff, or between staves.  Placing
+lyrics below the associated staff is the easiest, and can be
+achieved by simply defining the Lyrics context below the Staff
 context:
 
 @lilypond[quote,verbatim]
@@ -806,21 +810,19 @@ context:
 }
 @end lilypond
 
-To position lyrics above the staff, place the declaration of the
-Lyrics context before the Staff and Voice contexts, but the
-@code{\lyricsto} command must come after the Voice declaration it
-references, like this:
+Lyrics may be positioned above the staff using one of
+two methods.  The simplest is to use the same syntax as
+above and explicitly specify the position of the lyrics:
 
 @lilypond[quote,verbatim]
 \score {
   <<
-    \new Lyrics = "lyrics"
-    \new Staff {
+    \new Staff = "staff" {
       \new Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }
-    \context Lyrics = "lyrics" {
+    \new Lyrics \with { alignAboveContext = "staff" } {
       \lyricsto "melody" {
         Here are the words
       }
@@ -829,18 +831,21 @@ references, like this:
 }
 @end lilypond
 
-Alternatively, the position of the lyrics may be specified
-explicitly:
+Alternatively, a two-step process may be used.  First the Lyrics
+context is declared (without any content) before the Staff and
+Voice contexts, then the @code{\lyricsto} command comes after
+the Voice declaration it references, as follows:
 
 @lilypond[quote,verbatim]
 \score {
   <<
-    \new Staff = "staff" {
+    \new Lyrics = "lyrics"
+    \new Staff {
       \new Voice = "melody" {
         \relative c'' { c4 c c c }
       }
     }
-    \new Lyrics \with { alignAboveContext = "staff" } {
+    \context Lyrics = "lyrics" {
       \lyricsto "melody" {
         Here are the words
       }
@@ -851,7 +856,7 @@ explicitly:
 
 When there are two voices on separate staves the lyrics may be
 placed between the staves using either of these methods.  Here
-is an example of the first method:
+is an example of the second method:
 
 @lilypond[quote,verbatim]
 \score {
@@ -883,8 +888,8 @@ is an example of the first method:
 @end lilypond
 
 Other combinations of lyrics and staves may be generated by
-elaborating these examples, or by examining the SATB templates in
-the Learning Manual.
+elaborating these examples, or by examining the
+@rlearning{Vocal ensembles} templates in the Learning Manual.
 
 @seealso
 Learning Manual:
-- 
2.39.5