From 99946c93ed832a33b6817bb118011753136d7892 Mon Sep 17 00:00:00 2001
From: Graham Percival <graham@percival-music.ca>
Date: Thu, 28 Dec 2006 00:04:26 -0800
Subject: [PATCH] Add info about alignFooContext.

---
 Documentation/user/changing-defaults.itely |  25 +++++
 Documentation/user/templates.itely         | 114 +++++++++++++++++++++
 2 files changed, 139 insertions(+)

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 3b681cb22d..1dfaffd479 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -428,6 +428,7 @@ This section describes what contexts are, and how to modify them.
 * Layout tunings within contexts::  
 * Changing context default settings::  
 * Defining new contexts::       
+* Aligning contexts::           
 @end menu
 
 
@@ -1206,6 +1207,30 @@ Then the output at the start of this subsection can be entered as
 @end example
 
 
+@node Aligning contexts
+@subsection Aligning contexts
+
+New contexts may be aligned above or below exisiting contexts.  This
+could be useful in setting up a vocal staff (@ref{Vocal ensembles}) and
+in ossia,
+
+@cindex ossia
+@findex alignAboveContext
+@findex alignBelowContext
+
+@lilypond[quote,ragged-right]
+ossia = { f4 f f f }
+\score{
+  \relative c' \new Staff = "main" {
+    c4 c c c
+    <<
+      \new Staff \with {alignAboveContext=main} \ossia
+      { d8 f d f d f d f }
+    >>
+  }
+}
+@end lilypond
+
 
 
 @node The \override command
diff --git a/Documentation/user/templates.itely b/Documentation/user/templates.itely
index 3e7845709c..dbb1490dfd 100644
--- a/Documentation/user/templates.itely
+++ b/Documentation/user/templates.itely
@@ -723,6 +723,120 @@ bassWords = \lyricmode {
 }
 @end lilypond
 
+@appendixsubsec SATB with aligned contexts
+
+Here all the lyrics lines are placed using @code{alignAboveContext}
+and @code{alignBelowContext}.
+
+@lilypond[quote,verbatim,ragged-right]
+\version "2.10.0"
+global = {
+  \key c \major
+  \time 4/4
+}
+
+sopMusic = \relative c'' {
+  c4 c c8[( b)] c4
+}
+sopWords = \lyricmode {
+  hi hi hi hi
+}
+
+altoMusic = \relative c' {
+  e4 f d e
+}
+altoWords =\lyricmode {
+  ha ha ha ha
+}
+
+tenorMusic = \relative c' {
+  g4 a f g
+}
+tenorWords = \lyricmode {
+  hu hu hu hu
+}
+
+bassMusic = \relative c {
+  c4 c g c
+}
+bassWords = \lyricmode {
+  ho ho ho ho
+}
+
+\score {
+  \new ChoirStaff <<
+     \new Staff = women <<
+        \new Voice =
+          "sopranos" { \voiceOne << \global \sopMusic >> }
+        \new Voice =
+          "altos" { \voiceTwo << \global \altoMusic >> }
+     >>
+     \new Lyrics \with {alignAboveContext=women} \lyricsto sopranos \sopWords
+     \new Lyrics \with {alignBelowContext=women} \lyricsto altos \altoWords
+% we could remove the line about this with the line below, since we want
+% the alto lyrics to be below the alto Voice anyway.
+%    \new Lyrics \lyricsto altos \altoWords
+
+     \new Staff = men <<
+        \clef bass
+        \new Voice =
+          "tenors" { \voiceOne <<\global \tenorMusic >> }
+        \new Voice =
+          "basses" { \voiceTwo <<\global \bassMusic >> }
+     >>
+
+     \new Lyrics \with {alignAboveContext=men} \lyricsto tenors \tenorWords
+     \new Lyrics \with {alignBelowContext=men} \lyricsto basses \bassWords
+% again, we could replace the line above this with the line below.
+%    \new Lyrics \lyricsto basses \bassWords
+  >>
+
+  \layout {
+     \context {
+        % a little smaller so lyrics
+        % can be closer to the staff
+        \Staff
+        \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
+     }
+  }
+}
+
+
+\score {
+  \new ChoirStaff <<
+     \new Staff = women <<
+        \new Voice =
+          "sopranos" { \voiceOne << \global \sopMusic >> }
+        \new Voice =
+          "altos" { \voiceTwo << \global \altoMusic >> }
+     >>
+
+     \new Lyrics \with {alignAboveContext=women} \lyricsto sopranos \sopWords
+     \new Lyrics \lyricsto altos \altoWords
+
+     \new Staff = men <<
+        \clef bass
+        \new Voice =
+          "tenors" { \voiceOne <<\global \tenorMusic >> }
+        \new Voice =
+          "basses" { \voiceTwo <<\global \bassMusic >> }
+     >>
+
+     \new Lyrics \with {alignAboveContext=men} \lyricsto tenors \tenorWords
+     \new Lyrics \lyricsto basses \bassWords
+  >>
+
+  \layout {
+     \context {
+        % a little smaller so lyrics
+        % can be closer to the staff
+        \Staff
+        \override VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
+     }
+  }
+} 
+@end lilypond
+
 
 @c bad node name to avoid node name confict
 @node Ancient notation templates
-- 
2.39.5