This section describes what contexts are, and how to modify them.
@menu
-* Contexts explained::
-* Creating contexts::
-* Modifying context plug-ins::
-* Changing context default settings::
-* Defining new contexts::
+* Contexts explained::
+* Creating contexts::
+* Modifying context plug-ins::
+* Changing context default settings::
+* Defining new contexts::
* Aligning contexts::
@end menu
+@seealso
+
+Learning Manual:
+@rlearning{Contexts and engravers}.
+
+Installed files:
+@file{ly/@/engraver@/-init@/.ly},
+@file{ly/@/performer@/-init@/.ly}.
+
+Snippets:
+@rlsr{Contexts and engravers}.
+
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{Engravers and Performers}.
+
@node Contexts explained
@subsection Contexts explained
@node Changing context default settings
@subsection Changing context default settings
-The adjustments of the previous subsections (
-@ref{The set command}, @ref{Modifying context plug-ins}, and
-@ref{Overview of modifying properties}) can also be entered
-separately from the music in the @code{\layout} block,
-
-@example
-\layout @{
- @dots{}
- \context @{
- \Staff
-
- \set fontSize = #-2
- \override Stem #'thickness = #4.0
- \remove "Time_signature_engraver"
- @}
-@}
-@end example
+The context settings which are to be used by default in
+@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
+in a @code{\layout} block, as illustrated in the following example.
+The @code{\layout} block should be placed within the @code{\score}
+block to which it is to apply, but outside any music.
-The @code{\Staff} command brings in the existing definition of the
-staff context so that it can be modified.
+Note that the @code{\set} command itself and the context must be
+omitted when the context default values are specified in this way:
-The statements
-@example
-\set fontSize = #-2
-\override Stem #'thickness = #4.0
-\remove "Time_signature_engraver"
-@end example
-
-@noindent
-affect all staves in the score. Other contexts can be modified
-analogously.
-
-The @code{\set} keyword is optional within the @code{\layout} block, so
-
-@example
-\context @{
- @dots{}
- fontSize = #-2
-@}
-@end example
-
-@noindent
-will also work.
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ a4^"Really small, thicker stems, no time signature" a a a
+ a a a a
+ }
+ \layout {
+ \context {
+ \Staff
+ fontSize = #-4
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+ }
+ }
+}
+@end lilypond
+In this example, the @code{\Staff} command specifies that the
+subsequent specifications are to be applied to all staves within
+this score block.
+Modifications can be made to the @code{Score} context or all
+@code{Voice} contexts in a similar way.
@knownissues
@c TODO Better example needed. Ref LM, and expand on it.
@cindex ossia
-@findex alignAboveContext
-@findex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
@lilypond[quote,ragged-right]
ossia = { f4 f f f }
}
@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 }
+ \new Staff {
+ \clef "bass"
+ { c,1 }
+ }
+>>
+@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:
+
+@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
@menu
-* Navigating the program reference::
-* Layout interfaces::
-* Determining the grob property::
-* Naming conventions::
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
@end menu
@node Navigating the program reference
* Input modes::
* Direction and placement::
* Distances and measurements::
+* Staff symbol properties::
* Spanners::
* Visibility of objects::
* Line styles::
@c TODO Add table showing these
-@strong{Context layout}
+@strong{Context layout order}
-Contexts are positioned in a system from top to bottom in the
-order in which they are encountered. Note, however, that a
-context will be created implicitly if a command is encountered
-when there is no suitable context available to contain it.
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered. Note, however, that
+a context will be created implicitly if a command is encountered
+when there is no suitable context available to contain it. When
+contexts are nested, the outer context will exclude inner contexts
+which are not included in its @qq{accepts} list; excluded contexts
+will be repositioned below the outer context.
-@c TODO Add example ?
-
-The default order in which contexts are laid out can be changed,
-see @ref{Aligning contexts}
+The default order in which contexts are laid out and the
+@qq{accepts} list can be changed, see @ref{Aligning contexts}.
@strong{Articulation direction indicators}
@ref{Setting the staff size}.
+@node Staff symbol properties
+@subsection Staff symbol properties
+
+@cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex staff symbol, setting of
+
+@c TODO Extend or remove this section. See also NR 1.6.2 Staff symbol
+@c Need to think of uses for these properties. Eg 'line-positions
+@c is used in a snippet to thicken centre line.
+@c If retained, add @ref to here in 1.6.2 -td
+
+The vertical position of staff lines and the number of staff lines
+can be defined at the same time. As the following example shows,
+note positions are not influenced by the staff line positions.
+
+@warning{The @code{'line-positions} property overrides the
+@code{'line-count} property. The number of staff lines is
+implicitly defined by the number of elements in the list of values
+for @code{'line-positions}.}
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+ \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+The width of a staff can be modified. The units are staff
+spaces. The spacing of objects inside the staff is not affected by
+this setting.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+ \override StaffSymbol #'width = #23
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+
@node Spanners
@subsection Spanners
beginning of a line. Or to be more precise, before a line break,
where there is no line break, or after a line break.
-Alternatively, seven of the eight combinations may be specified
+Alternatively, these eight combinations may be specified
by pre-defined functions, defined in @file{scm/output-lib.scm},
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:
-@multitable @columnfractions .40 .15 .1 .1 .1
-@c TODO check these more carefully
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
@headitem Function @tab Vector @tab Before @tab At no @tab After
@headitem form @tab form @tab break @tab break @tab break
-@item @code{all-invisible} @tab @code{'#(#f #f #f)} @ @ @tab no @tab no @tab no
+@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
@item @code{begin-of-line-visible} @tab @code{'#(#f #f #t)} @tab no @tab no @tab yes
+@item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
@item @code{end-of-line-visible} @tab @code{'#(#t #f #f)} @tab yes @tab no @tab no
-@item @code{all-visible} @tab @code{'#(#t #t #t)} @tab yes @tab yes @tab yes
-@c The center-visible function is not defined
-@c @item @code{center-visible} @tab @code{'#(#f #t #f)} @tab no @tab yes @tab no
@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
-@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
@item @code{center-invisible} @tab @code{'#(#t #f #t)} @tab yes @tab no @tab yes
+@item @code{end-of-line-invisible} @tab @code{'#(#f #t #t)} @tab no @tab yes @tab yes
+@item @code{all-invisible} @tab @code{'#(#f #f #f)} @tab no @tab no @tab no
@end multitable
-The @code{center-visible} function is not pre-defined.
-
The default settings of @code{break-visibility} depend on the
layout object. The following table shows all the layout objects
of interest which are affected by @code{break-visibility} and the
@node Advanced tweaks
@section Advanced tweaks
+This section discusses various approaches to fine tuning the
+appearance of the printed score.
+
@menu
* Aligning objects::
* Vertical grouping of grobs::
* Modifying shapes::
@end menu
+@seealso
+
+Learning Manual:
+@rlearning{Tweaking output},
+@rlearning{Other sources of information}.
+
+Notation Reference:
+@ref{Explaining the Internals Reference},
+@ref{Modifying properties},
+@ref{Interfaces for programmers}.
+
+Installed Files:
+@file{scm/@/define@/-grobs@/.scm}.
+
+Snippets:
+@rlsr{Tweaks and overrides}.
+
+Internals Reference:
+@rinternals{All layout objects}.
+
@node Aligning objects
@subsection Aligning objects
projects / lilypond.git / blobdiff