From 397a1e1a06382d372c35d8d8502c3d85ef62482e Mon Sep 17 00:00:00 2001
From: Trevor Daniels <t.daniels@treda.co.uk>
Date: Wed, 29 Sep 2010 17:48:42 +0100
Subject: [PATCH] Doc: NR 2.1 Vocal music: Placement of lyrics

 - first draft
---
 Documentation/notation/vocal.itely | 121 +++++++++++++++++++++++++++--
 1 file changed, 116 insertions(+), 5 deletions(-)

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index 03049feda1..cd038b345b 100644
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -595,7 +595,7 @@ Internals Reference:
 * Divisi lyrics::
 * Lyrics independent of notes::
 * Spacing out syllables::
-* Placement of lyrics between staves::
+* Placement of lyrics::
 @end menu
 
 
@@ -1235,12 +1235,123 @@ To make lyrics avoid bar lines as well, use
 @end ignore
 
 
-@node Placement of lyrics between staves
-@unnumberedsubsubsec Placement of lyrics between staves
+@node Placement of lyrics
+@unnumberedsubsubsec Placement of lyrics
+
+@cindex placement of lyrics
+@cindex lyrics, positioning
 
 @c TODO Add text from -user
-@c TODO Add new spacing properties, centering lyrics, etc
-TBC
+
+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
+context:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics {
+      \lyricsto "melody" {
+        Here are the words
+      }
+    }
+  >>
+}
+@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:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Lyrics = "lyrics"
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \context Lyrics = "lyrics" {
+      \lyricsto "melody" {
+        Here are the words
+      }
+    }
+  >>
+}
+@end lilypond
+
+Alternatively, the position of the lyrics may be specified
+explicitly:
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff = "staff" {
+      \new Voice = "melody" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics \with { alignAboveContext = "staff" } {
+      \lyricsto "melody" {
+        Here are the words
+      }
+    }
+  >>
+}
+@end lilypond
+
+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:
+
+@lilypond[quote,verbatim]
+\score {
+  \new ChoirStaff <<
+    \new Staff {
+      \new Voice = "sopranos" {
+        \relative c'' { c4 c c c }
+      }
+    }
+    \new Lyrics = "sopranos"
+    \new Lyrics = "contraltos"
+    \new Staff {
+      \new Voice = "contraltos" {
+        \relative c'' { a4 a a a }
+      }
+    }
+    \context Lyrics = "sopranos" {
+      \lyricsto "sopranos" {
+        Sop -- ra -- no words
+      }
+    }
+    \context Lyrics = "contraltos" {
+      \lyricsto "contraltos" {
+        Con -- tral -- to words
+      }
+    }
+  >>
+}
+@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.
+
+@seealso
+Learning Manual:
+@rlearning{Vocal ensembles}.
+
+Notation Reference:
+@ref{Aligning contexts},
+@ref{Creating contexts}.
 
 @node Stanzas
 @subsection Stanzas
-- 
2.39.2