Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.6"
+@c \version "2.19.7"
@node Changing defaults
@chapter Changing defaults
@menu
* Contexts explained::
-* Creating contexts::
+* Creating and referencing contexts::
* Keeping contexts alive::
* Modifying context plug-ins::
* Changing context default settings::
Contexts are arranged hierarchically:
@menu
+* Output definitions - blueprints for contexts::
* Score - the master of all contexts::
* Top-level contexts - staff containers::
* Intermediate-level contexts - staves::
* Bottom-level contexts - voices::
@end menu
+@node Output definitions - blueprints for contexts
+@unnumberedsubsubsec Output definitions - blueprints for contexts
+
+This section explains the relevance of output definitions when
+working with contexts. Examples for actual output definitions are
+given later (see @ref{Changing all contexts of the same type}).
+
+@cindex output definitions
+@funindex \layout
+While music written in a file may refer to context types and
+names, contexts are created only when the music is actually being
+interpreted. LilyPond interprets music under control of an
+@q{output definition} and may do so for several different output
+definitions, resulting in different output. The output definition
+relevant for printing music is specified using @code{\layout}.
+
+@funindex \midi
+A much simpler output definition used for producing Midi output is
+specified using @code{\midi}. Several other output definitions
+are used by LilyPond internally, like when using the part combiner
+(@ref{Automatic part combining}) or creating music quotes
+(@ref{Quoting other voices}).
+
+Output definitions define the relation between contexts as well as
+their respective default settings. While most changes will
+usually be made inside of a @code{\layout} block, Midi-related
+settings will only have an effect when made within a @code{\midi}
+block.
+
+@funindex autoBeaming
+Some settings affect several outputs: for example, if
+@code{autoBeaming} is turned off in some context, beams count as
+melismata for the purpose of matching music to lyrics as described
+in @ref{Automatic syllable durations}. This matching is done both
+for printed output as well as for Midi. If changes made to
+@code{autoBeaming} within a context definition of a @code{\layout}
+block are not repeated in the corresponding @code{\midi} block,
+lyrics and music will get out of sync in Midi.
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.
+@file{ly/performer-init.ly}.
+
@node Score - the master of all contexts
@unnumberedsubsubsec Score - the master of all contexts
across staves.
A Score context is instantiated implicitly when a
-@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
-processed.
+@code{\score @{@dots{}@}} block is processed.
@node Top-level contexts - staff containers
@unnumberedsubsubsec Top-level contexts - staff containers
@strong{@emph{RhythmicStaff}}
-Like @code{Staff} but for printing rhythms. Pitches are ignored;
-the notes are printed on one line.
+Like @code{Staff} but for printing rhythms. Pitches are ignored
+when engraving; the notes are printed on one line. The MIDI
+rendition retains pitches unchanged.
@strong{@emph{TabStaff}}
@unnumberedsubsubsec Bottom-level contexts - voices
Voice-level contexts initialise certain properties and start
-appropriate engravers. Being bottom-level contexts, they cannot
-contain other contexts.
+appropriate engravers. A bottom-level context is one without
+@code{defaultchild}. While it is possible to let it
+accept/@/contain subcontexts, they can only be created and entered
+explicitly.
@strong{@emph{Voice}}
@end ignore
-@node Creating contexts
-@subsection Creating contexts
-
-@c TODO more complete descriptions rather than learning style
-
-For scores with only one voice and one staff, contexts are
-created automatically. For more complex scores, it is necessary to
-create them by hand. There are three commands that do this.
-
-@itemize
-
-@item
-The easiest command is @code{\new}, and it also the quickest to type.
-It is prepended to a music expression, for example
+@node Creating and referencing contexts
+@subsection Creating and referencing contexts
@funindex \new
+@funindex \context
@cindex new contexts
-@cindex Context, creating
+@cindex referencing contexts
+@cindex Contexts, creating and referencing
+
+LilyPond will create lower-level contexts automatically if a music
+expression is encountered before a suitable context exists, but this
+is usually successful only for simple scores or music fragments like
+the ones in the documentation. For more complex scores it is
+advisable to specify all contexts explicitly with either the
+@code{\new} or @code{\context} command. The syntax of
+these two commands is very similar:
@example
-\new @var{type} @var{music expression}
+[\new | \context] @var{Context} [ = @var{name}] [@var{music-expression}]
@end example
@noindent
-where @var{type} is a context name (like @code{Staff} or
-@code{Voice}). This command creates a new context, and starts
-interpreting the @var{music expression} with that.
+where either @code{\new} or @code{\context} may be specified.
+@var{Context} is the type of context which is to be created,
+@var{name} is an optional name to be given to the particular context
+being created and @var{music-expression} is a single music expression
+that is to be interpreted by the engravers and performers in this
+context.
-A practical application of @code{\new} is a score with many
-staves. Each part that should be on its own staff, is preceded with
-@code{\new Staff}.
+The @code{\new} prefix without a name is commonly used to create
+scores with many staves:
-@lilypond[quote,verbatim,relative=2,ragged-right]
+@lilypond[quote,verbatim,relative=2]
<<
- \new Staff { c4 c }
- \new Staff { d4 d }
+ \new Staff {
+ % leave the Voice context to be created implicitly
+ c4 c
+ }
+ \new Staff {
+ d4 d
+ }
>>
@end lilypond
-The @code{\new} command may also give a name to the context,
+@noindent
+and to place several voices into one staff:
-@example
-\new @var{type} = @var{id} @var{music}
-@end example
-However, this user specified name is only used if there is no other
-context already earlier with the same name.
+@lilypond[quote,verbatim,relative=2]
+<<
+ \new Staff <<
+ \new Voice {
+ \voiceOne
+ c8 c c4 c c
+ }
+ \new Voice {
+ \voiceTwo
+ g4 g g g
+ }
+ >>
+>>
+@end lilypond
+@noindent
+@code{\new} should always be used to specify unnamed contexts.
-@funindex \context
+The difference between @code{\new} and @code{\context} is in the
+action taken:
+@itemize
@item
-Like @code{\new}, the @code{\context} command also directs a music
-expression to a context object, but gives the context an explicit name. The
-syntax is
+@code{\new} with or without a name will always create a fresh,
+distinct, context, even if one with the same name already exists:
-@example
-\context @var{type} = @var{id} @var{music}
-@end example
+@lilypond[quote,verbatim,relative=2]
+<<
+ \new Staff <<
+ \new Voice = "A" {
+ \voiceOne
+ c8 c c4 c c
+ }
+ \new Voice = "A" {
+ \voiceTwo
+ g4 g g g
+ }
+ >>
+>>
+@end lilypond
-This form will search for an existing context of type @var{type}
-called @var{id}. If that context does not exist yet, a new
-context with the specified name is created. This is useful if
-the context is referred to later on. For example, when
-setting lyrics the melody is in a named context
+@item
+@code{\context} with a name specified will create a distinct context
+only if a context of the same type with the same name in the same
+context hierarchy does not already exist. Otherwise it will be taken
+as a reference to that previously created context, and its music
+expression will be passed to that context for interpretation.
-@example
-\context Voice = "@b{tenor}" @var{music}
-@end example
+One application of named contexts is in separating the score layout
+from the musical content. Either of these two forms is valid:
-@noindent
-so the texts can be properly aligned to its notes,
+@lilypond[quote,verbatim]
+\score {
+ <<
+ % score layout
+ \new Staff <<
+ \new Voice = "one" {
+ \voiceOne
+ }
+ \new Voice = "two" {
+ \voiceTwo
+ }
+ >>
-@example
-\new Lyrics \lyricsto "@b{tenor}" @var{lyrics}
-@end example
+ % musical content
+ \context Voice = "one" {
+ \relative c'' {
+ c4 c c c
+ }
+ }
+ \context Voice = "two" {
+ \relative c'' {
+ g8 g g4 g g
+ }
+ }
+ >>
+}
+@end lilypond
-@noindent
+@lilypond[quote,verbatim]
+\score {
+ <<
+ % score layout
+ \new Staff <<
+ \context Voice = "one" {
+ \voiceOne
+ }
+ \context Voice = "two" {
+ \voiceTwo
+ }
+ >>
-Another possible use of named contexts is funneling two different
-music expressions into one context. In the following example,
-articulations and notes are entered separately,
+ % musical content
+ \context Voice = "one" {
+ \relative c'' {
+ c4 c c c
+ }
+ }
+ \context Voice = "two" {
+ \relative c'' {
+ g8 g g4 g g
+ }
+ }
+ >>
+}
+@end lilypond
-@example
-music = @{ c4 c4 @}
-arts = @{ s4-. s4-> @}
-@end example
+@noindent
+Alternatively, variables may be employed to similar effect. See
+@rlearning{Organizing pieces with variables}.
-They are combined by sending both to the same @code{Voice} context,
+@item
+@code{\context} with no name will match the first of any previously
+created contexts of the same type in the same context heirarchy,
+even one that has been given a name, and its music expression will be
+passed to that context for interpretation. This form is rarely
+useful. However, @code{\context} with no name and no music expression
+is used to set the context in which a Scheme procedure specified with
+@code{\applyContext} is executed:
@example
-<<
- \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
->>
+\new Staff \relative c' @{
+ c1
+ \context Timing
+ \applyContext #(lambda (ctx)
+ (newline)
+ (display (ly:context-current-moment ctx)))
+ c1
+@}
@end example
-@lilypond[quote,ragged-right]
-music = { c4 c4 }
-arts = { s4-. s4-> }
-\relative c'' <<
- \new Staff \context Voice = "A" \music
- \context Voice = "A" \arts
->>
-@end lilypond
-With this mechanism, it is possible to define an Urtext (original
-edition), with the option to put several distinct articulations on the
-same notes.
+@end itemize
-@cindex creating contexts
+A context must be named if it is to be referenced later, for example
+when lyrics are associated with music:
-@item
-The third command for creating contexts is
@example
-\context @var{type} @var{music}
+\new Voice = "tenor" @var{music}
+@dots{}
+\new Lyrics \lyricsto "tenor" @var{lyrics}
@end example
-
@noindent
-This is similar to @code{\context} with @code{= @var{id}}, but matches
-any context of type @var{type}, regardless of its given name.
+For details of associating lyrics with music see
+@ref{Automatic syllable durations}.
-This variant is used with music expressions that can be interpreted at
-several levels. For example, the @code{\applyOutput} command (see
-@rextend{Running a function on all layout objects}). Without an explicit
-@code{\context}, it is usually applied to @code{Voice}
+The properties of all contexts of a particular type can be modified
+in a @code{\layout} block (with a different syntax), see
+@ref{Changing all contexts of the same type}. This construct also
+provides a means of keeping layout instructions separate from the
+musical content. If a single context is to be modified, a @code{\with}
+block must be used, see @ref{Changing just one specific context}.
-@example
-\applyOutput #'@var{context} #@var{function} % apply to Voice
-@end example
-
-To have it interpreted at the @code{Score} or @code{Staff} level use
-these forms
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables}.
-@example
-\applyOutput #'Score #@var{function}
-\applyOutput #'Staff #@var{function}
-@end example
+Notation Reference:
+@ref{Changing just one specific context},
+@ref{Automatic syllable durations}.
-@end itemize
@node Keeping contexts alive
@subsection Keeping contexts alive
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
+@code{<<@dots{}>>} construct will always persist to the end of the
+enclosing @code{Staff} context or @code{<<@dots{}>>} 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.
+first enclosed @code{@{@dots{}@}} construct, ignoring any in enclosed
+@code{<<@dots{}>>} 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
@emph{etc.}
@}
@{
- @emph{..music..}
+ @emph{@dots{}music@dots{}}
@}
@end example
time signature.
@cindex polymetric scores
-@cindex Time signatures, multiple
+@cindex time signature, multiple
@lilypond[quote,verbatim]
\score {
\new Staff \with {
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
- } {
+ }
+ \relative c'' {
\time 3/4
c4 c c c c c
}
\new Staff \with {
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
- } {
+ }
+ \relative c'' {
\time 2/4
c4 c c c c c
}
@funindex \context
@funindex \layout
-The context settings which are to be used by default in
+The default context settings which are to be used for typesetting in
@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
-specified in a @code{\context} block within any @code{\layout} block.
+specified in a @code{\context} block within any @code{\layout}
+block.
+
+Settings for Midi output as opposed to typesetting will have to be
+separately specified in @code{\midi} blocks (see @ref{Output
+definitions - blueprints for contexts}).
+
The @code{\layout} block should be placed within the @code{\score}
block to which it is to apply, after the music.
\layout {
\context {
\Staff
- \override Stem #'thickness = #4.0
+ \override Stem.thickness = #4.0
}
}
}
\layout {
\accidentalStyle dodecaphonic
\set fontSize = #-4
- \override Voice.Stem #'thickness = #4.0
+ \override Voice.Stem.thickness = #4.0
}
}
@end lilypond
command:
@example
-\new Staff
-\with @{
- [context settings for this context instance only]
-@} @{
-...
+\new Staff \with @{ [context settings for this context instance only] @}
+@{
+ @dots{}
@}
@end example
+Since such a @q{context modification} is specified inside of
+music, it will affect @emph{all} outputs (typesetting @emph{and}
+Midi) as opposed to changes within an output definition.
+
The following types of settings may be specified:
@itemize
@lilypond[quote,verbatim]
\score {
\new Staff {
- \new Voice
- \with {
- \override Stem #'thickness = #4.0
- }
+ \new Voice \with { \override Stem.thickness = #4.0 }
{
\relative c'' {
a4^"Thick stems" a a a
a4 a a a
}
}
- \new Staff
- \with {
- fontSize = #-4
- } {
+ \new Staff \with { fontSize = #-4 }
+ {
\relative c'' {
a4^"Smaller font" a a a
a4 a a a
}
}
}
- \new Staff
- \with { \accidentalStyle dodecaphonic }
+ \new Staff \with { \accidentalStyle dodecaphonic }
{
- \new Voice
- \with { \dynamicUp }
+ \new Voice \with { \dynamicUp }
{
\relative c'' {
a4^"Dynamics above" a a a
@item
otherwise the default value taken from the most recent appropriate
-@code{\context} block in the @code{\layout} blocks is used,
+@code{\context} block in the @code{\layout} or @code{\midi} blocks
+is used,
@item
otherwise the LilyPond built-in default is used.
@ref{Bottom-level contexts - voices},
@ref{The set command},
@ref{The override command},
-@ref{The \layout block}.
+@ref{The layout block,,The @code{@bs{}layout} block}.
@node Defining new contexts
@funindex \denies
@funindex denies
-Specific contexts, like @code{Staff} and @code{Voice}, are made of
+Specific contexts, like @code{Staff} and @code{Voice}, are made from
simple building blocks. It is possible to create new types of
contexts with different combinations of engraver plug-ins.
\consists "Text_engraver"
\consists "Pitch_squash_engraver"
squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \override Flag #'transparent = ##t
+ \override NoteHead.style = #'slash
+ \hide Stem
\alias Voice
}
\context { \Staff
\name ImproVoice
@end example
-Since it is similar to the @code{Voice}, we want commands that work
-on (existing) @code{Voice}s to remain working. This is achieved by
-giving the new context an alias @code{Voice},
+Since it is similar to the @code{Voice} context, we want commands that
+work in (existing) @code{Voice} contexts to continue working. This is
+achieved by giving the new context an alias of @code{Voice},
@example
\alias Voice
@end example
The context will print notes and instructive texts, so we need to add
-the engravers which provide this functionality,
+the engravers which provide this functionality, plus the engraver which
+groups notes, stems and rests which occur at the same musical moment
+into columns,
@example
\consists "Note_heads_engraver"
\consists "Text_engraver"
+\consists "Rhythmic_column_engraver"
@end example
-but we only need this on the center line,
+The note heads should all be placed on the center line,
@example
\consists "Pitch_squash_engraver"
squashedPosition = #0
@end example
-The @rinternals{Pitch_squash_engraver} modifies note heads (created
-by @rinternals{Note_heads_engraver}) and sets their vertical
-position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
-the center line.
+The @code{Pitch_squash_engraver} modifies note heads (created
+by the @code{Note_heads_engraver}) and sets their vertical
+position to the value of @code{squashedPosition}, in this
+case@tie{}@code{0}, the center line.
The notes look like a slash, and have no stem,
@example
-\override NoteHead #'style = #'slash
-\override Stem #'transparent = ##t
-\override Flag #'transparent = ##t
+\override NoteHead.style = #'slash
+\hide Stem
@end example
-All these plug-ins have to cooperate, and this is achieved with a
-special plug-in, which must be marked with the keyword @code{\type}.
-This should always be @code{Engraver_group}.
+All these plug-ins have to communicate under the control of the
+context. The mechanisms with which contexts communicate are
+established by declaring the context @code{\type}. Within a
+@code{\layout} block, most contexts will be of type
+@code{Engraver_group}. Some special contexts and contexts in
+@code{\midi} blocks use other context types. Copying and
+modifying an existing context definition will also fill in the
+type. Since this example creates a definition from scratch, it
+needs to be specified explicitly.
@example
\type "Engraver_group"
\type "Engraver_group"
\consists "Note_heads_engraver"
\consists "Text_engraver"
+ \consists "Rhythmic_column_engraver"
\consists "Pitch_squash_engraver"
squashedPosition = #0
- \override NoteHead #'style = #'slash
- \override Stem #'transparent = ##t
- \override Flag #'transparent = ##t
+ \override NoteHead.style = #'slash
+ \hide Stem
\alias Voice
@}
@end example
@funindex \accepts
-Contexts form hierarchies. We want to hang the @code{ImproVoice}
-under @code{Staff}, just like normal @code{Voice}s. Therefore, we
-modify the @code{Staff} definition with the @code{\accepts}
-command,
+Contexts form hierarchies. We want to place the @code{ImproVoice}
+context within the @code{Staff} context, just like normal @code{Voice}
+contexts. Therefore, we modify the @code{Staff} definition with the
+@code{\accepts} command,
@example
\context @{
@}
@end example
+To complete this example, changes affecting the context hierarchy
+should be repeated in a @code{\midi} block so that Midi output
+depends on the same context relations.
+
+@seealso
+
+Internals Reference:
+@rinternals{Note_heads_engraver},
+@rinternals{Text_engraver},
+@rinternals{Rhythmic_column_engraver},
+@rinternals{Pitch_squash_engraver}.
+
@node Context layout order
@subsection Context layout order
within it.
The @qq{accepts} list of a context can be changed with the
-@code{\accepts} and @code{\denies} commands. @code{\accepts} adds a
+@code{\accepts} or @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:
+from the list.
+
+For example, a square-braced staff group is not usually found within a
+curved-braced staff with connecting staff bars, and a @code{GrandStaff}
+does not accept a @code{StaffGroup} inside it by default.
@lilypond[verbatim,quote]
\score {
- \new Staff {
- c' d' e' f'
- \chords { d1:m7 b1:min7.5- }
- }
+ \new GrandStaff <<
+ \new StaffGroup <<
+ \new Staff { c'1 }
+ \new Staff { d'1 }
+ >>
+ \new Staff { \set Staff.instrumentName = bottom f'1 }
+ >>
}
@end lilypond
+However, by using the @code{\accepts} command, @code{StaffGroup} can be
+added to the @code{GrandStaff} context:
+
@lilypond[verbatim,quote]
\score {
- \new Staff {
- c' d' e' f'
- \chords { d1:m7 b1:min7.5- }
- }
+ \new GrandStaff <<
+ \new StaffGroup <<
+ \new Staff { c'1 }
+ \new Staff { d'1 }
+ >>
+ \new Staff { \set Staff.instrumentName = bottom f'1 }
+ >>
\layout {
\context {
- \Staff
- \accepts "ChordNames"
+ \GrandStaff
+ \accepts "StaffGroup"
}
}
}
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.
+@cindex contexts, implicit
+@cindex implicit contexts
+@funindex \defaultchild
+
+Note that a context will be silently created implicitly if a
+command is encountered when there is no suitable context available
+to contain it.
+
+Within a context definition, the type of subcontext to be
+implicitly created is specified using @code{\defaultchild}. A
+number of music events require a @samp{Bottom} context: when such
+an event is encountered, subcontexts are created recursively until
+reaching a context with no @samp{defaultchild} setting.
+
+Implicit context creation can at times give rise to unexpected new
+staves or scores. Using @code{\new} to create contexts explicitly
+avoids those problems.
@cindex alignAboveContext
@cindex alignBelowContext
3 staff spaces of white
between the note and the fingering:
@example
-\once \override Voice.Fingering #'padding = #3
+\once \override Voice.Fingering.padding = #3
@end example
Inserting this command before the Fingering object is created,
i.e., before @code{c2}, yields the following result:
@lilypond[quote,relative=2,verbatim]
-\once \override Voice.Fingering #'padding = #3
+\once \override Voice.Fingering.padding = #3
c-2
\stemUp
f
The command
@verbatim
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem.thickness = #4.0
@end verbatim
@noindent
@lilypond[quote,verbatim,relative=2]
c4
-\override Staff.Stem #'thickness = #4.0
+\override Staff.Stem.thickness = #4.0
c4
c4
c4
@lilypond[quote,verbatim,relative=2]
c4
-\once \override Stem #'thickness = #4.0
+\once \override Stem.thickness = #4.0
c4
c4
@end lilypond
when the object is created. In this example,
@lilypond[quote,verbatim,relative=2]
-\override Slur #'thickness = #3.0
+\override Slur.thickness = #3.0
c8[( c
-\override Beam #'beam-thickness = #0.6
+\override Beam.beam-thickness = #0.6
c8 c])
@end lilypond
@code{\revert} in the next example does not do anything.
@example
-\override Voice.Stem #'thickness = #4.0
-\revert Staff.Stem #'thickness
+\override Voice.Stem.thickness = #4.0
+\revert Staff.Stem.thickness
@end example
Some tweakable options are called @q{subproperties} and reside inside
such as
@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
+\override Stem.details.beamed-lengths = #'(4 4 3)
@end example
@end ignore
Contexts properties are usually named in
@code{studlyCaps}. They mostly control the translation from
-music to notation, e.g. @code{localKeySignature} (for determining
+music to notation, e.g. @code{localAlterations} (for determining
whether to print accidentals), or @code{measurePosition} (for
determining when to print a bar line). Context properties can
change value over time while interpreting a piece of music;
Internals Reference:
@rinternals{Tunable context properties}.
-@cindex grob properties
-@cindex properties, grob
-@funindex \override
-
@node The override command
@subsection The @code{\override} command
+@cindex grob properties
+@cindex properties, grob
+@funindex \override
+
There is a special type of context property: the grob
description. Grob descriptions are named in @code{StudlyCaps}
(starting with capital letters). They contain the
to see the settings for each grob description. Grob descriptions
are modified with @code{\override}.
-@code{\override} is actually a shorthand;
-
-@example
-\override @var{context}.@var{GrobName} #'@var{property} = #@var{value}
-@end example
-
-@noindent
-is more or less equivalent to
+The syntax for the @code{\override} command is
-@c leave this long line -gp
@example
-\set @var{context}.@var{GrobName} =
- #(cons (cons '@var{property} @var{value})
- <previous value of @var{context}.@var{GrobName}>)
+\override [@var{context}.]@var{GrobName}.@var{property} = #@var{value}
@end example
-The value of @code{context}.@code{GrobName} (the alist) is used to initialize
-the properties of individual grobs. Grobs have
-properties, named in Scheme style, with
-@code{dashed-words}. The values of grob properties change
-during the formatting process: formatting basically amounts
-to computing properties using callback functions.
-
For example, we can increase the thickness of a note stem by
overriding the @code{thickness} property of the @code{Stem}
object:
@lilypond[quote,verbatim,relative=2]
c4 c
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
c4 c
@end lilypond
context is used:
@lilypond[quote,verbatim,relative=2]
-{ \override Staff.Stem #'thickness = #3.0
+{ \override Staff.Stem.thickness = #3.0
<<
{
e4 e
- \override Stem #'thickness = #0.5
+ \override Stem.thickness = #0.5
e4 e
} \\ {
c4 c c c
}
@end lilypond
+Some tweakable options are called @q{subproperties} and reside inside
+properties. To tweak those, use commands in the form
+
+@example
+\override Stem.details.beamed-lengths = #'(4 4 3)
+@end example
+
+or to modify the ends of spanners, use a form like these
+
+@example
+\override TextSpanner.bound-details.left.text = #"left text"
+\override TextSpanner.bound-details.right.text = #"right text"
+@end example
+
@funindex \revert
@cindex reverting overrides
@cindex overrides, reverting
-The effects of @code{\override} can be undone by @code{\revert}:
+The effects of @code{\override} can be undone by @code{\revert}.
+
+The syntax for the @code{\revert} command is
+
+@example
+\revert [@var{context}.]@var{GrobName}.@var{property}
+@end example
+
+For example,
@lilypond[quote,verbatim,relative=2]
c4
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
c4 c
-\revert Voice.Stem #'thickness
+\revert Voice.Stem.thickness
c4
@end lilypond
<<
{
e4
- \override Staff.Stem #'thickness = #3.0
+ \override Staff.Stem.thickness = #3.0
e4 e e
} \\ {
c4 c c
- \revert Staff.Stem #'thickness
+ \revert Staff.Stem.thickness
c4
}
>>
{
<<
{
- \override Stem #'thickness = #3.0
+ \override Stem.thickness = #3.0
e4 e e e
} \\ {
c4
- \once \override Stem #'thickness = #3.0
+ \once \override Stem.thickness = #3.0
c4 c c
}
>>
Commands which change output generally look like
@example
-\override Voice.Stem #'thickness = #3.0
+\override Voice.Stem.thickness = #3.0
@end example
@noindent
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called @q{subproperties} and reside inside
-properties. To tweak those, use commands in the form
-
-@example
-\override Stem #'(details beamed-lengths) = #'(4 4 3)
-@end example
-
@cindex internal documentation
@cindex finding graphical objects
@cindex graphical object descriptions
syntax:
@example
-\tweak @var{layout-object} #'@var{grob-property} @var{value}
+\tweak [@var{layout-object}.]@var{grob-property} @var{value}
@end example
Specifying @var{layout-object} is optional.
@lilypond[relative=2,verbatim,quote]
< c
- \tweak #'color #red
+ \tweak color #red
d
g
- \tweak #'duration-log #1
+ \tweak duration-log #1
a
> 4
--\tweak #'padding #8
+-\tweak padding #8
-^
@end lilypond
-But the main use of the @code{\tweak} command is to modify just
+The main use of the @code{\tweak} command is to modify just
one of a number of notation elements which start at the same musical
moment, like the notes of a chord, or tuplet brackets which start
at the same time.
So, this works:
@lilypond[relative=2,verbatim,quote]
-<\tweak #'color #red c>4
+<\tweak color #red c>4
@end lilypond
@noindent
but this does not:
@lilypond[relative=2,verbatim,quote]
-\tweak #'color #red c4
+\tweak color #red c4
@end lilypond
@end ignore
@lilypond[relative=2,verbatim,quote]
< c
- \tweak #'color #red
+ \tweak color #red
d
g
- \tweak #'duration-log #1
+ \tweak duration-log #1
a
> 4
@end lilypond
@code{\tweak} can be used to modify slurs:
@lilypond[verbatim,quote,relative=1]
-c-\tweak #'thickness #5 ( d e f)
+c-\tweak thickness #5 ( d e f)
@end lilypond
inside of the @code{EventChord}:
@lilypond[relative=2,verbatim,quote]
-\tweak #'color #red c4
-\tweak #'color #red <c e>4
-<\tweak #'color #red c e>4
+\tweak color #red c4
+\tweak color #red <c e>4
+<\tweak color #red c e>4
@end lilypond
The simple @code{\tweak} command cannot be used to modify any object
@code{NoteHead} layout objects rather than by music elements in the
input stream.
-Such indirectly created layout objects can be tweaked using the explicit
-form of the @code{\tweak} command:
+Such indirectly created layout objects can be tweaked using the form
+of the @code{\tweak} command in which the grob name is specified
+explicitly:
@lilypond[relative=2,verbatim,quote]
\tweak Stem.color #red
@lilypond[verbatim,quote,relative=1]
c
--\tweak #'style #'dashed-line
--\tweak #'dash-fraction #0.2
--\tweak #'thickness #3
--\tweak #'color #red
+-\tweak style #'dashed-line
+-\tweak dash-fraction #0.2
+-\tweak thickness #3
+-\tweak color #red
\glissando
f'
@end lilypond
@node set versus override
@subsection @code{\set} vs. @code{\override}
-@c TODO -- This section is probably unnecessary now.
-
-@ignore
-We have seen two methods of changing properties: @code{\set} and
-@code{\override}. There are actually two different kinds of
-properties.
-
-@code{fontSize} is a special property: it is equivalent to
-entering @code{\override ... #'font-size} for all pertinent
-objects. Since this is a common change, the special
-property (modified with @code{\set}) was created.
-
-@end ignore
+@c TODO Should't a bunch of that be explained earlier?
+@funindex \set
+@funindex \override
+Both @code{\set} and @code{\override} manipulate properties
+associated with contexts. In either case, properties heed the
+hierarchy of contexts: properties not set in a context itself show
+the values of the respective parent context.
+
+Values and lifetime of context properties are dynamic and only
+available when music is being interpreted, @q{iterated}. At the
+time of context creation, properties are initialized from the
+corresponding context definition and possible context
+modifications. Afterwards, changes are achieved with
+property-setting commands in the music itself.
+
+Now grob definitions are a special category of context properties.
+Since their structure, bookkeeping and use is different from
+ordinary context properties, they are accessed with a different
+set of commands, and treated separately in the documentation.
+
+As opposed to plain context properties, grob definitions are
+subdivided into grob properties. A @qq{grob} (graphical object)
+is usually created by an engraver at the time of interpreting a
+music expression and receives its initial properties from the
+current grob definition of the engraver's context. The engraver
+(or other @q{backend} parts of LilyPond) may subsequently add or
+change properties to the grob, but that does not affect the
+context's grob definition.
+
+What we call @q{grob properties} in the context of user-level
+tweaking are actually the properties of a context's grob
+definition. In contrast to ordinary context properties, grob
+definitions have the bookkeeping required to keep track of its
+parts, the individual grob properties (and even subproperties of
+them) separately so that it is possible to define those parts in
+different contexts and have the overall grob definition at the
+time of grob creation be assembled from pieces provided in
+different contexts among the current context and its parents.
+
+Grob definitions are manipulated using @code{\override} and
+@code{\revert} and have a name starting with a capital letter
+(like @samp{NoteHead}) whereas ordinary context properties are
+manipulated using @code{\set} and @code{\unset} and are named
+starting with a lowercase letter.
+
+@cindex tweak, relation to @code{\override}
+@funindex \tweak
+@funindex \overrideProperty
+The special commands @code{\tweak} and @code{\overrideProperty}
+change grob properties bypassing context properties completely.
+Instead they catch grobs as they are being created and then
+directly set properties on them when they originate from a tweaked
+music event or are of a particular kind, respectively.
@node Modifying alists
@subsection Modifying alists
% reduced space between staves
\new PianoStaff \with {
% this is the nested declaration
- \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #7
} <<
\new Staff { \clef treble c''1 }
\new Staff { \clef bass c1 }
@lilypond[quote,verbatim]
\new PianoStaff \with {
- \override StaffGrouper #'staff-staff-spacing =
+ \override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 0)
(minimum-distance . 0)
(padding . 0)
declarations are equivalent:
@example
-\override StaffGrouper #'staff-staff-spacing =
+\override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 7))
-\override StaffGrouper #'staff-staff-spacing =
+\override StaffGrouper.staff-staff-spacing =
#'((basic-distance . 7)
(minimum-distance . 0)
(padding . 0)
key-values individually with a nested declaration.
@warning{Nested declarations will not work for context property
-alists (such as @code{beamExceptions}, @code{keySignature},
+alists (such as @code{beamExceptions}, @code{keyAlterations},
@code{timeSignatureSettings}, etc.). These properties can only be
modified by completely re-defining them as alists.}
* Input modes::
* Direction and placement::
* Distances and measurements::
+* Dimensions::
* Staff symbol properties::
* Spanners::
* Visibility of objects::
The way in which the notation contained within an input file is
interpreted is determined by the current input mode.
-@strong{Chord mode}
+@subsubsubheading Chord mode
This is activated with the @code{\chordmode} command, and causes
input to be interpreted with the syntax of chord notation, see
chord notation and rendered as chord names in the @code{ChordNames}
context, see @ref{Printing chord names}.
-@strong{Drum mode}
+@subsubsubheading Drum mode
This is activated with the @code{\drummode} command, and causes
input to be interpreted with the syntax of drum notation, see
Drum mode is also activated with the @code{\drums} command.
This also creates a new @code{DrumStaff} context and causes the
following input to be interpreted with the syntax of drum notation
-and rendered as drum symbols on a drum staff, see @ref{Basic
-percussion notation}.
+and rendered as drum symbols on a drum staff, see
+@ref{Basic percussion notation}.
-@strong{Figure mode}
+@subsubsubheading Figure mode
This is activated with the @code{\figuremode} command, and causes
input to be interpreted with the syntax of figured bass, see
and rendered as figured bass symbols in the @code{FiguredBass}
context, see @ref{Introduction to figured bass}.
-@strong{Fret and tab modes}
+@subsubsubheading Fret and tab modes
There are no special input modes for entering fret and tab symbols.
above the notes using the @code{\fret-diagram} command (see
@ref{Fret diagram markups}).
-@strong{Lyrics mode}
+@subsubsubheading Lyrics mode
This is activated with the @code{\lyricmode} command, and causes
input to be interpreted as lyric syllables with optional durations
@code{\lyricsto} command which associates the following lyrics
with the preceding music.
-@strong{Markup mode}
+@subsubsubheading Markup mode
This is activated with the @code{\markup} command, and causes
input to be interpreted with the syntax of markup, see
@ref{Text markup commands}.
-@c silly work-around for texinfo broken-ness
-@c (@strong{Note...} causes a spurious cross-reference in Info)
-@b{Note mode}
+@subsubsubheading Note mode
This is the default mode or it may be activated with the
@code{\notemode} command. Input is interpreted as pitches,
are in lyric mode, chord mode or any other mode and want to insert
something that only can be done with note mode syntax.
-For example, to indicate dynamic markings for the verses of a
-choral pieces it is necessary to enter note mode to interpret
-the markings:
-
-@lilypond[verbatim,relative=2,quote]
-{ c4 c4 c4 c4 }
-\addlyrics {
- \notemode{\set stanza = \markup{ \dynamic f 1. } }
- To be sung loudly
-}
-\addlyrics {
- \notemode{\set stanza = \markup{ \dynamic p 2. } }
- To be sung quietly
-}
-@end lilypond
-
-
@node Direction and placement
@subsection Direction and placement
be determined automatically by LilyPond, but in some cases it may
be desirable to force a particular direction or placement.
-@strong{Articulation direction indicators}
+@menu
+* Articulation direction indicators::
+* The direction property::
+@end menu
+
+@node Articulation direction indicators
+@unnumberedsubsubsec Articulation direction indicators
By default some directions are always up or always down (e.g.
dynamics or fermata), while other things can alternate between
c2^( c)
@end lilypond
-@strong{The direction property}
+@node The direction property
+@unnumberedsubsubsec The direction property
The position or direction of many layout objects is controlled by the
@code{direction} property.
@ref{Setting the staff size}.
+@node Dimensions
+@subsection Dimensions
+
+@cindex dimensions
+@cindex bounding box
+
+The dimensions of a graphical object specify the positions of the left
+and right edges and the bottom and top edges of the objects' bounding
+box as distances from the objects' reference point in units of
+staff-spaces. These positions are usually coded as two Scheme pairs.
+For example, the text markup command @code{\with-dimensions} takes
+three arguments, the first two of which are a Scheme pair giving the
+left and right edge positions and a Scheme pair giving the bottom and
+top edge positions:
+
+@example
+\with-dimensions #'(-5 . 10) #'(-3 . 15) @var{arg}
+@end example
+
+This specifies a bounding box for @var{arg} with its left edge at -5,
+its right edge at 10, its bottom edge at -3 and its top edge at 15,
+all measured from the objects' reference point in units of
+staff-spaces.
+
+@seealso
+Notation Reference:
+@ref{Distances and measurements}.
+
+
@node Staff symbol properties
@subsection Staff symbol properties
@lilypond[verbatim,quote,relative=1]
\new Staff \with {
- \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+ \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond
@lilypond[verbatim,quote,relative=1]
\new Staff \with {
- \override StaffSymbol #'width = #23
+ \override StaffSymbol.width = #23
}
{ a4 e' f b | d1 }
@end lilypond
those that draw a straight line between the two objects, support in
addition the @code{line-spanner-interface}.
+@menu
+* Using the spanner-interface::
+* Using the line-spanner-interface::
+@end menu
+
+@node Using the spanner-interface
@unnumberedsubsubsec Using the @code{spanner-interface}
This interface provides two properties that apply to several spanners.
-@strong{@i{The @code{minimum-length} property}}
+@subsubsubheading The @code{minimum-length} property
The minimum length of the spanner is specified by the
@code{minimum-length} property. Increasing this usually has the
@end ignore
@lilypond[verbatim,quote,relative=2]
-a~a
+a~ a
a
% increase the length of the tie
--\tweak #'minimum-length #5
-~a
+-\tweak minimum-length #5
+~ a
@end lilypond
@lilypond[verbatim,quote,relative=2]
\compressFullBarRests
R1*23
% increase the length of the rest bar
-\once \override MultiMeasureRest #'minimum-length = #20
+\once \override MultiMeasureRest.minimum-length = #20
R1*23
a1
@end lilypond
@lilypond[verbatim,quote,relative=2]
a \< a a a \!
% increase the length of the hairpin
-\override Hairpin #'minimum-length = #20
+\override Hairpin.minimum-length = #20
a \< a a a \!
@end lilypond
phrasing slurs:
@lilypond[verbatim,quote,relative=2]
-a( a)
+a( g)
a
--\tweak #'minimum-length #5
-( a)
+-\tweak minimum-length #5
+( g)
-a\( a\)
+a\( g\)
a
--\tweak #'minimum-length #5
-\( a\)
+-\tweak minimum-length #5
+\( g\)
@end lilypond
For some layout objects, the @code{minimum-length} property becomes
e \glissando c'
% not effective alone
-\once \override Glissando #'minimum-length = #20
+\once \override Glissando.minimum-length = #20
e, \glissando c'
% effective only when both overrides are present
-\once \override Glissando #'minimum-length = #20
-\once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
+\once \override Glissando.minimum-length = #20
+\once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
e, \glissando c'
@end lilypond
@lilypond[verbatim,quote,relative=1]
% not effective alone
-\once \override Beam #'minimum-length = #20
+\once \override Beam.minimum-length = #20
e8 e e e
% effective only when both overrides are present
-\once \override Beam #'minimum-length = #20
-\once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
+\once \override Beam.minimum-length = #20
+\once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
e8 e e e
@end lilypond
-@strong{@i{The @code{to-barline} property}}
+@subsubsubheading The @code{to-barline} property
The second useful property of the @code{spanner-interface} is
@code{to-barline}. By default this is true, causing hairpins and
@lilypond[verbatim,quote,relative=2]
a \< a a a a \! a a a \break
-\override Hairpin #'to-barline = ##f
+\override Hairpin.to-barline = ##f
a \< a a a a \! a a a
@end lilypond
or on other spanners for which terminating on the bar line would
not be meaningful.
+@node Using the line-spanner-interface
@unnumberedsubsubsec Using the @code{line-spanner-interface}
Objects which support the @code{line-spanner-interface} include
@end itemize
The routine responsible for drawing the stencils for these spanners is
-@code{ly:line-interface::print}. This routine determines the
+@code{ly:line-spanner::print}. This routine determines the
exact location of the two end points and draws a line
between them, in the style requested. The locations of the two
end points of the spanner are computed on-the-fly, but it is
@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
sub-lists of @code{bound-details}. For example:
@lilypond[relative=2,ragged-right,verbatim,quote]
-\override Glissando #'breakable = ##t
-\override Glissando #'(bound-details right-broken Y) = #-3
+\override Glissando.breakable = ##t
+\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,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,quote,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
@unnumberedsubsubsec Removing the stencil
@cindex stencil, removing
+@funindex \omit
Every layout object has a stencil property. By default this is set
to the specific function which draws that object. If this property
@lilypond[quote,verbatim,relative=1]
a1 a
-\override Score.BarLine #'stencil = ##f
+\override Score.BarLine.stencil = ##f
+a a
+\revert Score.BarLine.stencil
+a a a
+@end lilypond
+
+This rather common operation has a shortcut @code{\omit}:
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\omit Score.BarLine
a a
-\revert Score.BarLine #'stencil
+\undo \omit Score.BarLine
a a a
@end lilypond
@unnumberedsubsubsec Making objects transparent
@cindex transparent, making objects
+@funindex \hide
Every layout object has a transparent property which by default is
set to @code{#f}. If set to @code{#t} the object still occupies
@lilypond[quote,verbatim,relative=2]
a4 a
-\once \override NoteHead #'transparent = ##t
+\once \override NoteHead.transparent = ##t
+a a
+@end lilypond
+
+This rather common operation has a shortcut @code{\hide}:
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \hide NoteHead
a a
@end lilypond
here:
@lilypond[quote,verbatim,relative=2]
-\override Staff.Clef #'color = #white
+\override Staff.Clef.color = #white
a1
@end lilypond
@code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
@lilypond[quote,verbatim,relative=2]
-\override Staff.Clef #'color = #white
-\override Staff.Clef #'layer = #-1
+\override Staff.Clef.color = #white
+\override Staff.Clef.layer = #-1
a1
@end lilypond
where the last three columns indicate whether the layout objects
will be visible in the positions shown at the head of the columns:
-@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
-@headitem Function @tab Vector @tab Before @tab At no @tab After
-@headitem form @tab form @tab break @tab break @tab break
-
-@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{begin-of-line-invisible} @tab @code{'#(#t #t #f)} @tab yes @tab yes @tab no
-@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
+@multitable {@code{begin-of-line-invisible}} {@code{#(#t #t #t)}} {Before} {At no} {After}
+@headitem Function @tab Vector @tab Before @tab At no @tab After
+@headitem form @tab form @tab break @tab break @tab break
+
+@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{begin-of-line-invisible} @tab @code{#(#t #t #f)} @tab yes @tab yes @tab no
+@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 default settings of @code{break-visibility} depend on the
@item @code{Clef} @tab @code{Staff} @tab @code{begin-of-line-visible}
@item @code{Custos} @tab @code{Staff} @tab @code{end-of-line-visible}
@item @code{DoublePercentRepeat} @tab @code{Voice} @tab @code{begin-of-line-invisible}
-@c omit KeyCancellation until it can be explained -td
-@c @item @code{KeyCancellation} @tab ?? @tab @code{begin-of-line-invisible}
+@item @code{KeyCancellation} @tab @code{Staff} @tab @code{begin-of-line-invisible}
@item @code{KeySignature} @tab @code{Staff} @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge} @tab @code{Score} @tab @code{center-invisible}
-@item @code{OctavateEight} @tab @code{Staff} @tab @code{begin-of-line-visible}
+@item @code{ClefModifier} @tab @code{Staff} @tab @code{begin-of-line-visible}
@item @code{RehearsalMark} @tab @code{Score} @tab @code{end-of-line-invisible}
@item @code{TimeSignature} @tab @code{Staff} @tab @code{all-visible}
f4 g a b
f4 g a b
% Remove bar line at the end of the current line
-\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\once \override Score.BarLine.break-visibility = ##(#f #t #t)
\break
f4 g a b
f4 g a b
suppressed. Use begin-of line-invisible to print and
all-invisible to suppress.
@item Key signature -- see below
-@item OctavateEight -- see below
+@item ClefModifier -- see below
@end itemize
@node Special considerations
@unnumberedsubsubsec Special considerations
-@strong{@emph{Visibility following explicit changes}}
+@subsubsubheading Visibility following explicit changes
@cindex key signature, visibility following explicit change
@cindex explicitKeySignatureVisibility
\key g \major
f4 g a b
% Try to remove all key signatures
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond
-@strong{@emph{Visibility of cautionary accidentals}}
+@subsubsubheading Visibility of cancelling accidentals
-To remove the cautionary accidentals printed at an explicit key
+To remove the cancelling accidentals printed at an explicit key
change, set the Staff context property @code{printKeyCancellation}
to @code{#f}:
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
-\override Staff.KeySignature #'break-visibility = #all-invisible
+\override Staff.KeySignature.break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
With these overrides only the accidentals before the notes remain
to indicate the change of key.
+Note that when changing the key to C@tie{}major or A@tie{}minor
+the cancelling accidentals would be the @emph{only} indication of
+the key change. In this case setting @code{printKeyCancellation} to
+@code{#f} has no effect:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+To suppress the cancelling accidentals even when the key is
+changed to C@tie{}major or A@tie{}minor, override
+the visibility of the @code{KeyCancellation} grob instead:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeyCancellation.break-visibility = #all-invisible
+\key c \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
@c TODO Add visibility of cautionary accidentals before notes
-@strong{@emph{Automatic bars}}
+@subsubsubheading Automatic bars
@cindex automaticBars
@cindex bar lines, suppressing
@c TODO Add example
-@strong{@emph{Octavated clefs}}
+@subsubsubheading Transposed clefs
-@cindex octavated clefs, visibility of
-@cindex visibility of octavated clefs
-@cindex clefs, visibility of octavation
+@cindex transposed clefs, visibility of
+@cindex visibility of transposed clefs
+@cindex clefs, visibility of transposition
-The small octavation symbol on octavated clefs is produced by the
-@code{OctavateEight} layout object. Its visibility is automatically
+The small transposition symbol on transposed clefs is produced by the
+@code{ClefModifier} layout object. Its visibility is automatically
inherited from the @code{Clef} object, so it is not necessary to apply
-any required @code{break-visibility} overrides to the @code{OctavateEight}
-layout objects to suppress octavation symbols for invisible clefs.
+any required @code{break-visibility} overrides to the @code{ClefModifier}
+layout objects to suppress transposition symbols for invisible clefs.
For explicit clef changes, the @code{explicitClefVisibility}
-property controls both the clef symbol and any octavation symbol
+property controls both the clef symbol and any transposition symbol
associated with it.
@seealso
texts and the lines, and tuning their behavior is therefore also
done in the same way. It is done with a spanner, and the routine
responsible for drawing the spanners is
-@code{ly:line-interface::print}. This routine determines the
+@code{ly:line-spanner::print}. This routine determines the
exact location of the two @i{span points} and draws a line
between them, in the style requested.
@lilypond[relative=2,ragged-right,verbatim,quote]
d2 \glissando d'2
-\once \override Glissando #'style = #'dashed-line
+\once \override Glissando.style = #'dashed-line
d,2 \glissando d'2
-\override Glissando #'style = #'dotted-line
+\override Glissando.style = #'dotted-line
d,2 \glissando d'2
-\override Glissando #'style = #'zigzag
+\override Glissando.style = #'zigzag
d,2 \glissando d'2
-\override Glissando #'style = #'trill
+\override Glissando.style = #'trill
d,2 \glissando d'2
@end lilypond
@c TODO Complete
@lilypond[relative=2,ragged-right,verbatim,quote]
e2 \glissando f
-\once \override Glissando #'(bound-details right Y) = #-2
+\once \override Glissando.bound-details.right.Y = #-2
e2 \glissando f
@end lilypond
@lilypond[quote,verbatim,relative=1]
g4\< e' d' f\!
-\override Hairpin #'rotation = #'(20 -1 0)
+\override Hairpin.rotation = #'(20 -1 0)
g,,4\< e' d' f\!
@end lilypond
of the text too high.
@lilypond[quote,verbatim,relative=1]
-\override TextScript #'outside-staff-priority = ##f
+\override TextScript.outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
des^\markup { \rotate #30 "a D-Flat" }
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Modifying broken spanners::
* Unpure-pure containers::
@end menu
@lilypond[verbatim,quote,relative=2]
a-3
a
--\tweak #'X-offset #0
--\tweak #'Y-offset #0
+-\tweak X-offset #0
+-\tweak Y-offset #0
-3
a
--\tweak #'X-offset #-1
--\tweak #'Y-offset #1
+-\tweak X-offset #-1
+-\tweak Y-offset #1
-3
@end lilypond
@node Using the self-alignment-interface
@unnumberedsubsubsec Using the @code{self-alignment-interface}
-@emph{Self-aligning objects horizontally}
+@subsubsubheading Self-aligning objects horizontally
The horizontal alignment of an object which supports the
@code{self-alignment-interface} is controlled by the value of
@lilypond[quote,verbatim,relative=1]
a'
--\tweak #'self-alignment-X #-1
+-\tweak self-alignment-X #-1
^"left-aligned"
--\tweak #'self-alignment-X #0
+-\tweak self-alignment-X #0
^"center-aligned"
--\tweak #'self-alignment-X #RIGHT
+-\tweak self-alignment-X #RIGHT
^"right-aligned"
--\tweak #'self-alignment-X #-2.5
+-\tweak self-alignment-X #-2.5
^"aligned further to the right"
@end lilypond
-@emph{Self-aligning objects vertically}
+@subsubsubheading Self-aligning objects vertically
Objects may be aligned vertically in an analogous way to aligning
them horizontally if the @code{Y-offset} property is set to
@code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}},
@code{0}, and @code{1}, respectively.
-@emph{Self-aligning objects in both directions}
+@subsubsubheading Self-aligning objects in both directions
By setting both @code{X-offset} and @code{Y-offset}, an object may
be aligned in both directions simultaneously.
@lilypond[quote,verbatim,relative=2]
a
--\tweak #'self-alignment-X #0.5 % move horizontally left
--\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
--\tweak #'self-alignment-Y #-1 % move vertically up
+-\tweak self-alignment-X #0.5 % move horizontally left
+-\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
+-\tweak self-alignment-Y #-1 % move vertically up
-3 % third finger
@end lilypond
@code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
@code{time-signature}.
-By default, rehearsal marks and bar numbers will be horizontally
-centered above the object:
+Each type of object has its own default reference point, to which
+rehearsal marks are aligned:
@lilypond[verbatim,quote,relative=1]
-% The rehearsal mark will be centered above the Clef
-\override Score.RehearsalMark #'break-align-symbols = #'(clef)
+% The rehearsal mark will be aligned to the right edge of the Clef
+\override Score.RehearsalMark.break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
e1
-% The rehearsal mark will be centered above the Time Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
+% The rehearsal mark will be aligned to the left edge of the Time Signature
+\override Score.RehearsalMark.break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e2.
% The rehearsal mark will be centered above the Breath Mark
-\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
+\override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
line would be.
@lilypond[verbatim,quote,relative=1]
-% The rehearsal mark will be centered above the Key Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+% The rehearsal mark will be aligned to the right edge of the Key Signature
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e1
-% The rehearsal mark will be centered above the Clef
+% The rehearsal mark will be aligned to the right edge of the Clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef bass
\mark "↓"
% The rehearsal mark will be centered above the Bar Line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
multiple staves, this setting should be done for all the staves.
@lilypond[verbatim,quote,relative=1]
-% The RehearsalMark will be centered above the Key Signature
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
+% The RehearsalMark will be aligned with the right edge of the Key Signature
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e1
-% The RehearsalMark will be aligned with the left edge of the Key Signature
-\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
+% The RehearsalMark will be centered above the Key Signature
+\once \override Score.KeySignature.break-align-anchor-alignment = #CENTER
\mark "↓"
\key a \major
e1
-% The RehearsalMark will be aligned with the right edge of the Key Signature
-\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
+% The RehearsalMark will be aligned with the left edge of the Key Signature
+\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
\key a \major
\mark "↓"
e1
@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted right by 3.5 staff-spaces
-\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
-\once \override Score.KeySignature #'break-align-anchor = #3.5
+\override Score.RehearsalMark.break-align-symbols = #'(key-signature)
+\once \override Score.KeySignature.break-align-anchor = #3.5
\key a \major
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted left by 2 staff-spaces
-\once \override Score.KeySignature #'break-align-anchor = #-2
+\once \override Score.KeySignature.break-align-anchor = #-2
\key a \major
\mark "↓"
e1
@lilypond[verbatim,quote]
XinO = {
- \once \override NoteHead #'stencil = #ly:text-interface::print
- \once \override NoteHead #'text = \markup {
+ \once \override NoteHead.stencil = #ly:text-interface::print
+ \once \override NoteHead.text = \markup {
\combine
\halign #-0.7 \draw-circle #0.85 #0.2 ##f
\musicglyph #"noteheads.s2cross"
@lilypond[verbatim,quote,relative=1]
<<
- { e1~ e }
+ { e1~ 1 }
\\
{ r4 <g c,> <g c,> <g c,> }
>>
<<
{
\shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
- e1~ e
+ e1~ 1
}
\\
{ r4 <g c,> <g c,> <g c,> }
g2
% create a slur and move it to a new position
% the <> is just an empty chord to carry the slur termination
- -\tweak #'control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
+ -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
f,
}
{
e'2
% create a slur and move it to a new position
- -\tweak #'control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
+ -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
f,
}
}
Internals Reference:
@rinternals{TieColumn}.
+
+@node Modifying broken spanners
+@subsection Modifying broken spanners
+
+@menu
+* Using alterBroken::
+@end menu
+
+@node Using alterBroken
+@unnumberedsubsubsec Using @code{\alterBroken}
+
+@cindex spanners, modifying
+@cindex broken spanners, modifying
+@funindex \alterBroken
+
+When a spanner crosses a line break or breaks, each piece
+inherits the attributes of the original spanner. Thus, ordinary
+tweaking of a broken spanner applies the same modifications to
+each of its segments. In the example below, overriding
+@code{thickness} affects the slur on either side of the line
+break.
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+r2
+\once\override Slur.thickness = 10
+c8( d e f
+\break
+g8 f e d) r2
+@end lilypond
+
+Independently modifying the appearance of individual pieces
+of a broken spanner is possible with the @code{\alterBroken}
+command. This command can produce either an @code{\override}
+or a @code{\tweak} of a spanner property.
+
+The syntax for @code{\alterBroken} is
+
+@example
+[-]@code{\alterBroken} @var{property} @var{values} @var{item}
+@end example
+
+The argument @var{values} is a list of values, one for each
+broken piece. If @var{item} is a grob name like @code{Slur} or
+@code{Staff.PianoPedalBracket}, the result is an @code{\override}
+of the specified grob type. If @var{item} is a music expression
+such as @qq{(} or @qq{[} the result is the same music expression
+with an appropriate tweak applied.
+
+The leading hyphen must be used with the @code{\tweak} form. Do
+not add it when @code{\alterBroken} is used as an
+@code{\override}.
+
+In its @code{\override} usage, @code{\alterBroken} may be
+prefaced by @code{\once} or @code{\temporary} and reverted by
+using @code{\revert} with @var{property}.
+
+The following code applies an independent @code{\override} to
+each of the slur segments in the previous example:
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+r2
+\alterBroken thickness #'(10 1) Slur
+c8( d e f
+\break
+g8 f e d) r2
+@end lilypond
+
+The @code{\alterBroken} command may be used with any spanner
+object, including @code{Tie}, @code{PhrasingSlur}, @code{Beam}
+and @code{TextSpanner}. For example, an editor preparing a
+scholarly edition may wish to indicate the absence of part of a
+phrasing slur in a source by dashing only the segment which has
+been added. The following example illustrates how this can be
+done, in this case using the @code{\tweak} form of the command:
+
+@lilypond[verbatim,quote,ragged-right,relative=2]
+% The empty list is conveniently used below, because it is the
+% default setting of dash-definition, resulting in a solid curve.
+c2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e
+\break
+g2 e\)
+@end lilypond
+
+It is important to understand that @code{\alterBroken} will set
+each piece of a broken spanner to the corresponding value in
+@var{values}. When there are fewer values than pieces, any
+additional piece will be assigned the empty list. This may lead
+to undesired results if the layout property is not set to the
+empty list by default. In such cases, each segment should be
+assigned an appropriate value.
+
+@knownissues
+Line breaks may occur in different places following changes in
+layout. Settings chosen for @code{\alterBroken} may be unsuitable
+for a spanner that is no longer broken or is split into more
+segments than before. Explicit use of @code{\break} can guard
+against this situation.
+
+The @code{\alterBroken} command is ineffective for spanner
+properties accessed before line-breaking such as
+@code{direction}.
+
+@seealso
+Extending LilyPond:
+@rextend{Difficult tweaks}.
+
+
+@node Unpure-pure containers
+@subsection Unpure-pure containers
+
@cindex Scheme, pure containers
@cindex Scheme, unpure containers
@cindex pure containers, Scheme
@cindex unpure containers, Scheme
@cindex horizontal spacing, overriding
-
-@node Unpure-pure containers
-@subsection Unpure-pure containers
-
Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
Scheme function instead of a literal (i.e. a number or pair).
'(-0.5 . 0.5)))))
squareLineCircleSpace = {
- \override NoteHead #'stencil = #square-line-circle-space
+ \override NoteHead.stencil = #square-line-circle-space
}
smartSquareLineCircleSpace = {
\squareLineCircleSpace
- \override NoteHead #'Y-extent =
+ \override NoteHead.Y-extent =
#(ly:make-unpure-pure-container
ly:grob::stencil-height
(lambda (grob start end) (ly:grob::stencil-height grob)))
(parser location padding)
(number?)
#{
- \once \override TextScript #'padding = #padding
+ \once \override TextScript.padding = #padding
#})
-\relative c''' {
+\relative c'' {
c4^"piu mosso" b a b
\padText #1.8
- c4^"piu mosso" d e f
+ c4^"piu mosso" b a b
\padText #2.6
- c4^"piu mosso" fis a g
+ c4^"piu mosso" b a b
}
@end lilypond
(parser location padding tempotext)
(number? markup?)
#{
- \once \override Score.MetronomeMark #'padding = #padding
+ \once \override Score.MetronomeMark.padding = #padding
\tempo \markup { \bold #tempotext }
#})