From 32c862967d559ab512cd96e3321a2c8dabe724ca Mon Sep 17 00:00:00 2001 From: James Lowe Date: Sat, 24 Sep 2011 21:47:15 +0100 Subject: [PATCH] Doc: NR rewrite of 5.1.7 - context layout order This is from suggestions by Trevor D and Neil P. Tracker issue 1812 --- .../notation/changing-defaults.itely | 141 +++++++----------- Documentation/notation/vocal.itely | 2 +- 2 files changed, 55 insertions(+), 88 deletions(-) diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index e10986e7cf..fb892d0bb3 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -64,7 +64,7 @@ This section describes what contexts are, and how to modify them. * Modifying context plug-ins:: * Changing context default settings:: * Defining new contexts:: -* Aligning contexts:: +* Context layout order:: @end menu @@ -929,79 +929,73 @@ Then the output at the start of this subsection can be entered as @end example -@node Aligning contexts -@subsection Aligning contexts +@node Context layout order +@subsection Context layout order -New contexts may be aligned above or below existing contexts. This -could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and -in ossia, +@cindex contexts, layout order +@funindex \accepts +@funindex \denies -@c TODO Better example needed. Ref LM, and expand on it. +Contexts are normally positioned in a system from top to bottom +in the order in which they are encountered in the input file. When +contexts are nested, the outer context will include inner nested +contexts as specified in the input file, provided the inner contexts +are included in the outer context's @qq{accepts} list. Nested +contexts which are not included in the outer context's @qq{accepts} +list will be repositioned below the outer context rather than nested +within it. -@cindex ossia -@funindex alignAboveContext -@funindex alignBelowContext +The @qq{accepts} list of a context can be changed with the +@code{\accepts} and @code{\denies} commands. @code{\accepts} adds a +context to the @qq{accepts} list and @code{\denies} removes a context +from the list. For example, it would not normally be desirable for +chord names to be nested within a @code{Staff} context, so the +@code{ChordNames} context is not included by default in the @qq{accepts} +list of the @code{Staff} context, but if this were to be required it can +be done: -@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 } - >> +@lilypond[verbatim,quote] +\score { + \new Staff { + c' d' e' f' + \chords { d1:m7 b1:min7.5- } } } @end lilypond -@cindex nested contexts -@cindex contexts, nested - -@funindex \accepts -@funindex \denies - -Contexts like @code{PianoStaff} can contain other contexts -nested within them. Contexts which are acceptable for nesting -are defined by the @qq{accepts} list of a context. Contexts -which are not in this list are placed below the outer context -in the printed score. -For example, the @code{PianoStaff} context is defined by default -to accept @code{Staff} and @code{FiguredBass} contexts within -it, but not (for example) a @code{Lyrics} context. So in the -following structure the lyrics are placed below the piano staff -rather than between the two staves: - -@lilypond[verbatim,quote,relative=1] -\new PianoStaff -<< - \new Staff { e4 d c2 } - \addlyrics { Three blind mice } +@lilypond[verbatim,quote] +\score { \new Staff { - \clef "bass" - { c,1 } + c' d' e' f' + \chords { d1:m7 b1:min7.5- } } ->> + \layout { + \context { + \Staff + \accepts "ChordNames" + } + } +} @end lilypond -The @qq{accepts} list of a context can be modified to include -additional nested contexts, so if we wanted the lyrics to appear -between the two staves we could use: +@code{\denies} is mainly used when a new context is being based on +another, but the required nesting differs. For example, the +@code{VaticanaStaff} context is based on the @code{Staff} context, but +with the @code{VaticanaVoice} context substituted for the @code{Voice} +context in the @qq{accepts} list. + +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. + +@seealso +Usage Manual: +@rprogram{An extra staff appears}. + +Installed Files: +@file{ly/engraver-init.ly}. -@lilypond[verbatim,quote,relative=1] -\new PianoStaff \with { \accepts Lyrics } -<< - \new Staff { e4 d c2 } - \addlyrics { Three blind mice } - \new Staff { - \clef "bass" - { c,1 } - } ->> -@end lilypond -The opposite of @code{\accepts} is @code{\denies}; this removes a -context from the @qq{accepts} list. @node Explaining the Internals Reference @section Explaining the Internals Reference @@ -2101,7 +2095,6 @@ modified by completely re-defining them as alists.} @menu * Input modes:: * Direction and placement:: -* Context layout order:: * Distances and measurements:: * Staff symbol properties:: * Spanners:: @@ -2307,32 +2300,6 @@ c2( c) @end lilypond -@node Context layout order -@subsection Context layout order - -@cindex contexts, layout order - -Contexts are normally positioned in a system from top to bottom -in the order in which they are encountered in the input file. When -contexts are nested, the outer context will include inner nested -contexts as specified in the input file, provided the inner contexts -are included in the outer context's @qq{accepts} list. Nested -contexts which are not included in the outer context's @qq{accepts} -list will be repositioned below the outer context rather than nested -within it. - -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. - -The default order in which contexts are laid out and the -@qq{accepts} list can be changed, see @ref{Aligning contexts}. - -@seealso -Usage Manual: -@rprogram{An extra staff appears}. - - @node Distances and measurements @subsection Distances and measurements diff --git a/Documentation/notation/vocal.itely b/Documentation/notation/vocal.itely index 0890ed6455..b30e14ac38 100644 --- a/Documentation/notation/vocal.itely +++ b/Documentation/notation/vocal.itely @@ -1099,7 +1099,7 @@ Learning Manual: @rlearning{Vocal ensembles}. Notation Reference: -@ref{Aligning contexts}, +@ref{Context layout order}, @ref{Creating contexts}. @node Placing syllables horizontally -- 2.39.2