Doc: document use of alignAboveContext (2557)

Also alignBelowContext.

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 4c3562d08d36ace16aad2f304f91556eb297a88d..59b234a5f83e1ea8c53332afe2a9546a0d1c5087 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -1007,7 +1007,43 @@ Note that a context will be silently created implicitly if a command
 is encountered when there is no suitable context available to
 contain it.  This can give rise to unexpected new staves or scores.
 
+@cindex alignAboveContext
+@cindex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
+
+Sometimes a context is required to exist for just a brief period, a
+good example being the staff context for an ossia.  This is usually
+achieved by introducing the context definition at the appropriate
+place in parallel with corresponding section of the main music.
+By default, the temporary context will be placed below all the
+existing contexts.  To reposition it above the context called
+@qq{main}, it should be defined like this:
+
+@example
+@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+@end example
+
+A similar situation arises when positioning a temporary lyrics
+context within a multi-staved layout such as a @code{ChoirStaff},
+for example, when adding a second verse to a repeated section.
+By default the temporary lyrics context will be placed beneath the
+lower staves.  By defining the temporary lyrics context with
+@code{alignBelowContext} it can be positioned correctly beneath
+the (named) lyrics context containing the first verse.
+
+Examples showing this repositioning of temporary contexts can be
+found elsewhere --- see @rlearning{Nesting music expressions},
+@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
+
 @seealso
+Learning Manual:
+@rlearning{Nesting music expressions}.
+
+Notation Reference:
+@ref{Modifying single staves},
+@ref{Techniques specific to lyrics}.
+
 Application Usage:
 @rprogram{An extra staff appears}.
 

diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely
index a38092baa7e9ef03747b996ad472e4ca1d8fc032..265374eb47012c00705ff227d9ebd20a7bb0ea39 100644 (file)
--- a/Documentation/notation/vocal.itely
+++ b/Documentation/notation/vocal.itely
@@ -1323,6 +1323,54 @@ More verses may be added in a similar way:
 }
 @end lilypond
 
+@cindex alignBelowContext
+@funindex alignBelowContext
+
+However, if this construct is embedded within a multi-staved
+context such as a @code{ChoirStaff} the lyrics of the second and
+third verses will appear beneath the bottom staff.
+
+To position them correctly use @code{alignBelowContext}:
+
+@lilypond[verbatim,quote]
+\score {
+  <<
+    \new Staff {
+      \new Voice = "melody" {
+        \relative c'' {
+         a4 a a a
+         \repeat volta 3 { b4 b b b }
+          c4 c c c
+       }
+      }
+    }
+    \new Lyrics = "firstVerse" \lyricsto "melody" {
+      Not re -- peat -- ed.
+      <<
+        { The first time words.        }
+       \new Lyrics = "secondVerse"
+        \with { alignBelowContext = #"firstVerse" } {
+         \set associatedVoice = "melody"
+         Sec -- ond time words.
+       }
+       \new Lyrics = "thirdVerse"
+        \with { alignBelowContext = #"secondVerse" } {
+         \set associatedVoice = "melody"
+         The third time words.
+       }
+      >>
+      The end sec -- tion.
+    }
+    \new Voice = "harmony" {
+      \relative c' {
+        f4 f f f \repeat volta 2 { g8 g g4 g2 } a4 a8. a16 a2
+      }
+    }
+  >>
+}
+@end lilypond
+
+
 
 @c TODO positioning a common line of lyrics