version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.61"
+@c \version "2.12.0"
@node Changing defaults
@chapter Changing defaults
@menu
* Contexts explained::
* Creating contexts::
+* Keeping contexts alive::
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
* Aligning contexts::
@end menu
-@seealso
+@seealso
Learning Manual:
@rlearning{Contexts and engravers}.
@c TODO Describe propagation of property values -td
-Contexts are arranged heirarchically:
+Contexts are arranged hierarchically:
@menu
* Score - the master of all contexts::
Groups staves while adding a bracket on the left side, grouping
the staves together. The bar lines of the contained staves are
-connected vertically. StaffGroup only consists of a collection
+connected vertically. @code{StaffGroup} only consists of a collection
of staves, with a bracket in front and spanning bar lines.
@strong{@emph{ChoirStaff}}
-Identical to StaffGroup except that the bar lines of the contained
-staves are not connected vertically.
+Identical to @code{StaffGroup} except that the bar lines of the
+contained staves are not connected vertically.
@strong{@emph{GrandStaff}}
-A group of staves, with a brace on the left side, grouping
-the staves together. The bar lines of the contained staves are
+A group of staves, with a brace on the left side, grouping the
+staves together. The bar lines of the contained staves are
connected vertically.
@strong{@emph{PianoStaff}}
-@c TODO No longer correct? Check. -td
-Just like GrandStaff but with a forced distance between the
-staves, so cross staff beaming and slurring can be used.
-
-@ignore
-@strong{@emph{InnerStaffGroup}}
-
-TODO -td
-
-@strong{@emph{InnerChoirStaff}}
-
-TODO -td
-
-@end ignore
+Just like @code{GrandStaff}, but with support for instrument names
+to the left of each system.
@node Intermediate-level contexts - staves
@unnumberedsubsubsec Intermediate-level contexts - staves
@strong{@emph{Staff}}
-Handles clefs, bar lines, keys, accidentals. It can contain
-Voice contexts.
+Handles clefs, bar lines, keys, accidentals. It can contain
+@code{Voice} contexts.
@strong{@emph{RhythmicStaff}}
-Like Staff but for printing rhythms. Pitches are ignored;
+Like @code{Staff} but for printing rhythms. Pitches are ignored;
the notes are printed on one line.
@strong{@emph{TabStaff}}
-Context for generating tablature. By default lays the music
+Context for generating tablature. By default lays the music
expression out as a guitar tablature, printed on six lines.
@strong{@emph{DrumStaff}}
-Handles typesetting for percussion. Can contain DrumVoice
+Handles typesetting for percussion. Can contain @code{DrumVoice}
@strong{@emph{VaticanaStaff}}
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
a piece in gregorian style.
@strong{@emph{MensuralStaff}}
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
a piece in mensural style.
@node Bottom-level contexts - voices
@strong{@emph{Voice}}
-Corresponds to a voice on a staff. This context handles the
+Corresponds to a voice on a staff. This context handles the
conversion of dynamic signs, stems, beams, super- and sub-scripts,
slurs, ties, and rests. You have to instantiate this explicitly
if you require multiple voices on the same staff.
@strong{@emph{VaticanaVoice}}
-Same as Voice, except that it is designed for typesetting a piece
-in gregorian style.
+Same as @code{Voice}, except that it is designed for typesetting
+a piece in gregorian style.
@strong{@emph{MensuralVoice}}
-Same as Voice, with modifications for typesetting a piece in
+Same as @code{Voice}, with modifications for typesetting a piece in
mensural style.
@strong{@emph{Lyrics}}
-Corresponds to a voice with lyrics. Handles the printing of a
+Corresponds to a voice with lyrics. Handles the printing of a
single line of lyrics.
@strong{@emph{DrumVoice}}
@strong{@emph{FiguredBass}}
-The context in which BassFigure objects are created from
+The context in which @code{BassFigure} objects are created from
input entered in @code{\figuremode} mode.
@strong{@emph{TabVoice}}
-The voice context used within a TabStaff context. Usually left to
-be created implicitly.
+The voice context used within a @code{TabStaff} context. Usually
+left to be created implicitly.
@strong{@emph{ChordNames}}
@end itemize
+@node Keeping contexts alive
+@subsection Keeping contexts alive
+
+@cindex contexts, keeping alive
+@cindex contexts, lifetime
+
+Contexts are usually terminated at the first musical moment in
+which they have nothing to do. So @code{Voice} contexts die as
+soon as they contain no events; @code{Staff} contexts die as soon
+as all the @code{Voice} contexts within them contain no events; etc.
+This can cause difficulties if earlier contexts which have died
+have to be referenced, for example, when changing staves with
+@code{\change} commands, associating lyrics with a voice with
+@code{\lyricsto} commands, or when adding further musical events to
+an earlier context.
+
+There is an exception to this general rule: just one of the
+@code{Voice} contexts in a @code{Staff} context or in a
+@code{<<...>>} construct will always persist to the end of the
+enclosing @code{Staff} context or @code{<<...>>} construct, even
+though there may be periods when it has nothing to do. The context
+to persist in this way will be the first one encountered in the
+first enclosed @code{@{...@}} construct, ignoring any in enclosed
+@code{<<...>>} constructs.
+
+Any context can be kept alive by ensuring it has something to do at
+every musical moment. @code{Staff} contexts are kept alive by
+ensuring one of their voices is kept alive. One way of doing this
+is to add spacer rests to a voice in parallel with the real music.
+These need to be added to every @code{Voice} context which needs to
+be kept alive. If several voices are to be used sporadically it is
+safest to keep them all alive rather than attempting to rely on the
+exceptions mentioned above.
+
+In the following example, both voice A and voice B are kept alive
+in this way for the duration of the piece:
+
+@lilypond[quote,verbatim]
+musicA = \relative c'' { d4 d d d }
+musicB = \relative c'' { g4 g g g }
+keepVoicesAlive = {
+ <<
+ \new Voice = "A" { s1*5 } % Keep Voice "A" alive for 5 bars
+ \new Voice = "B" { s1*5 } % Keep Voice "B" alive for 5 bars
+ >>
+}
+
+music = {
+ \context Voice = "A" {
+ \voiceOneStyle
+ \musicA
+ }
+ \context Voice = "B" {
+ \voiceTwoStyle
+ \musicB
+ }
+ \context Voice = "A" { \musicA }
+ \context Voice = "B" { \musicB }
+ \context Voice = "A" { \musicA }
+}
+
+\score {
+ \new Staff <<
+ \keepVoicesAlive
+ \music
+ >>
+}
+@end lilypond
+
+@cindex lyrics, aligning with sporadic melody
+
+The following example shows how a sporadic melody line with lyrics
+might be written using this approach. In a real situation the
+melody and accompaniment would consist of several different
+sections, of course.
+
+@lilypond[quote,verbatim]
+melody = \relative c'' { a4 a a a }
+accompaniment = \relative c' { d4 d d d }
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+\score {
+ <<
+ \new Staff = "music" {
+ <<
+ \new Voice = "melody" {
+ \voiceOne
+ s1*4 % Keep Voice "melody" alive for 4 bars
+ }
+ {
+ \new Voice = "accompaniment" {
+ \voiceTwo
+ \accompaniment
+ }
+ <<
+ \context Voice = "melody" { \melody }
+ \context Voice = "accompaniment" { \accompaniment }
+ >>
+ \context Voice = "accompaniment" { \accompaniment }
+ <<
+ \context Voice = "melody" { \melody }
+ \context Voice = "accompaniment" { \accompaniment }
+ >>
+ }
+ >>
+ }
+ \new Lyrics \with { alignAboveContext = #"music" }
+ \lyricsto "melody" { \words }
+ >>
+}
+@end lilypond
+
+An alternative way, which may be better in many circumstances, is
+to keep the melody line alive by simply including spacer notes to
+line it up correctly with the accompaniment:
+
+@lilypond[quote,verbatim]
+melody = \relative c'' {
+ s1 % skip a bar
+ a4 a a a
+ s1 % skip a bar
+ a4 a a a
+}
+accompaniment = \relative c' {
+ d4 d d d
+ d4 d d d
+ d4 d d d
+ d4 d d d
+}
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+
+\score {
+ <<
+ \new Staff = "music" {
+ <<
+ \new Voice = "melody" {
+ \voiceOne
+ \melody
+ }
+ \new Voice = "accompaniment" {
+ \voiceTwo
+ \accompaniment
+ }
+ >>
+ }
+ \new Lyrics \with { alignAboveContext = #"music" }
+ \lyricsto "melody" { \words }
+ >>
+}
+@end lilypond
+
@node Modifying context plug-ins
@subsection Modifying context plug-ins
@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 @code{\Staff} command brings in the existing definition of the
-staff context so that it can be modified.
-
-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 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{\set} keyword is optional within the @code{\layout} block, so
+Note that the @code{\set} command itself and the context must be
+omitted when the context default values are specified in this way:
-@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
\name ImproVoice
\type "Engraver_group"
\consists "Note_heads_engraver"
+ \consists "Rhythmic_column_engraver"
\consists "Text_engraver"
\consists Pitch_squash_engraver
squashedPosition = #0
\relative c' \new Staff = "main" {
c4 c c c
<<
- \new Staff \with {alignAboveContext=main} \ossia
+ \new Staff \with { alignAboveContext = #"main" } \ossia
{ d8 f d f d f d f }
>>
}
such as
@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example
@seealso
-
Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
@rinternals{PropertySet}, @rinternals{Backend}, and
@rinternals{All layout objects}.
properties. To tweak those, use commands in the form
@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example
@cindex internal documentation
to apply after the input file has been converted to a music stream.
This is often not the case, as many additional elements are inserted
into the music stream implicitly. For example, when a note which is
-not part of a chord is processed, Lilypond implicitly inserts a
+not part of a chord is processed, LilyPond implicitly inserts a
@code{ChordEvent} event before the note, so separating the tweak
from the note. However, if chord symbols are placed round the
tweak and the note, the @code{\tweak} command comes after the
see @ref{Displaying music expressions}. This may be helpful in
determining what may be modified by a @code{\tweak} command.
-@seealso
+@seealso
Learning Manual:
@rlearning{Tweaking methods}.
Notation Reference:
@ref{Displaying music expressions}.
+
@knownissues
@cindex tweaks in a variable
@code{staff-space}. For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.
-@seealso
+@seealso
Learning Manual:
@rlearning{Length and thickness of objects}.
@lilypond[relative=2,quote,verbatim]
e2 \glissando b
-\once \override Glissando #'bound-details #'left #'Y = #3
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details left Y) = #3
+\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando b
@end lilypond
@lilypond[relative=2,ragged-right,verbatim,fragment]
\override Glissando #'breakable = ##t
-\override Glissando #'bound-details #'right-broken #'Y = #-3
+\override Glissando #'(bound-details right-broken Y) = #-3
c1 \glissando \break
f1
@end lilypond
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
+\override TextSpanner #'(bound-details left text)
= \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond
relative to the end point of the line:
@lilypond[relative=1,fragment,verbatim]
-\override TextSpanner #'bound-details
- #'left #'stencil-align-dir-y = #-2
-\override TextSpanner #'bound-details
- #'right #'stencil-align-dir-y = #UP
-
-\override TextSpanner #'bound-details
- #'left #'text = #"ggg"
-\override TextSpanner #'bound-details
- #'right #'text = #"hhh"
+\override TextSpanner
+ #'(bound-details left stencil-align-dir-y) = #-2
+\override TextSpanner
+ #'(bound-details right stencil-align-dir-y) = #UP
+
+\override TextSpanner
+ #'(bound-details left text) = #"ggg"
+\override TextSpanner
+ #'(bound-details right text) = #"hhh"
c4^\startTextSpan c c c \stopTextSpan
@end lilypond
hairpins with @code{\!}.
-
@seealso
-
Internals Reference: @rinternals{TextSpanner},
@rinternals{Glissando}, @rinternals{VoiceFollower},
@rinternals{TrillSpanner},
considerations.
@menu
-* Removing the stencil::
-* Making objects transparent::
-* Painting objects white::
-* Using break-visibility::
-* Special considerations::
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
@end menu
@c FIXME Complete
@lilypond[relative=2,ragged-right,verbatim,fragment]
e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando f
@end lilypond
* Modifying shapes::
@end menu
-@seealso
+@seealso
Learning Manual:
@rlearning{Tweaking output},
@rlearning{Other sources of information}.
Internals Reference:
@rinternals{All layout objects}.
+
@node Aligning objects
@subsection Aligning objects
* Setting @code{X-offset} and @code{Y-offset} directly::
* Using the @code{side-position-interface}::
* Using the @code{self-alignment-interface}::
-* Using the @code{break-aligned-interface}::
+* Using the @code{break-alignable-interface}::
@end menu
@node Setting @code{X-offset} and @code{Y-offset} directly
@c TODO The align-interface, BassFigureAlignment and VerticalAlignment
-@node Using the @code{break-aligned-interface}
-@unnumberedsubsubsec Using the @code{break-aligned-interface}
+@node Using the @code{break-alignable-interface}
+@unnumberedsubsubsec Using the @code{break-alignable-interface}
+
+@cindex align to objects
+@cindex break-align-symbols
-Rehearsal marks may be aligned with notation objects other
-than bar lines. These objects include @code{ambitus},
+Rehearsal marks and bar numbers may be aligned with notation
+objects other than bar lines. These objects include @code{ambitus},
@code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
@code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
@code{time-signature}.
-By default, rehearsal marks will be horizontally centered above the
-object:
+By default, rehearsal marks and bar numbers will be horizontally
+centered above the object:
@lilypond[verbatim,quote,relative=1]
e1
e2.
@end lilypond
+A list of possible target alignment objects may be specified. If
+some of the objects are invisible at that point due to the setting
+of @code{break-visibility} or the explicit visibility settings for
+keys and clefs, the rehearsal mark or bar number is aligned to the
+first object in the list which is visible. If no objects in the
+list are visible the object is aligned to the bar line. If the bar
+line is invisible the object is aligned to the place where the bar
+line would be.
+
+@lilypond[verbatim,quote,relative=1]
+e1
+% the RehearsalMark will be centered above the Key Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e
+% the RehearsalMark will be centered above the Clef
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \minor
+\clef bass
+\mark "↓"
+e,
+@end lilypond
+
The alignment of the rehearsal mark relative to the notation object
can be changed, as shown in the following example. In a score with
multiple staves, this setting should be done for all the staves.
@end lilypond
-
@node Vertical grouping of grobs
@subsection Vertical grouping of grobs
@c TODO Add inserting Postscript or ref to later
-@seealso
+@seealso
Notation Reference:
@ref{Graphic notation inside markup},
@ref{Formatting text},