Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.14.0"
@node Changing defaults
@chapter Changing defaults
Internally, LilyPond uses Scheme (a LISP dialect) to provide
infrastructure. Overriding layout decisions in effect accesses the
program internals, which requires Scheme input. Scheme elements are
-introduced in a @code{.ly} file with the hash mark
+introduced in a @file{.ly} file with the hash mark
@code{#}.@footnote{@rextend{Scheme tutorial}, contains a short tutorial
on entering numbers, lists, strings, and symbols in Scheme.}
Learning Manual:
@rlearning{Contexts and engravers}.
-Installed files:
-@file{ly/@/engraver@/-init@/.ly},
-@file{ly/@/performer@/-init@/.ly}.
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{ly/performer-init.ly}.
Snippets:
@rlsr{Contexts and engravers}.
staves. Each part that should be on its own staff, is preceded with
@code{\new Staff}.
-@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
+@lilypond[quote,verbatim,relative=2,ragged-right]
<<
\new Staff { c4 c }
\new Staff { d4 d }
store properties,
they also contain plug-ins called @q{engravers} that create notation
elements. For example, the @code{Voice} context contains a
-@code{Note_head_engraver} and the @code{Staff} context contains a
+@code{Note_heads_engraver} and the @code{Staff} context contains a
@code{Key_signature_engraver}.
For a full a description of each plug-in, see
example which removes @code{Time_signature_engraver} and
@code{Clef_engraver} from a @code{Staff} context,
-@lilypond[quote,relative=1,verbatim,fragment]
+@lilypond[quote,relative=1,verbatim]
<<
\new Staff {
f2 g
It is not possible to collect context changes in a variable and apply
them to a @code{\context} definition by referring to that variable.
-The @code{\RemoveEmptyStaffContext} will overwrite your current
+The @code{\Staff \RemoveEmptyStaves} will overwrite your current
@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\RemoveEmptyStaffContext}, you must do so
-after calling @code{\RemoveEmptyStaffContext}, ie
+staff which uses @code{\Staff \RemoveEmptyStaves}, you must do so
+after calling @code{\Staff \RemoveEmptyStaves}, ie
@example
\layout @{
\context @{
- \RemoveEmptyStaffContext
+ \Staff \RemoveEmptyStaves
\override Stem #'thickness = #4.0
@}
Suppose we want to move the fingering indication in the fragment
below:
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
We have been talking of @emph{the} @code{Fingering} object, but actually it
does not amount to much. The initialization file (see
@rlearning{Other sources of information})
-@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
+@file{scm/define-grobs.scm} shows the soul of the @q{object},
@example
(Fingering
(script-priority . 100)
(stencil . ,ly:text-interface::print)
(direction . ,ly:script-interface::calc-direction)
- (font-encoding . fetaNumber)
+ (font-encoding . fetaText)
(font-size . -5) ; don't overlap when next to heads.
(meta . ((class . Item)
(interfaces . (finger-interface
Recall that we wanted to change the position of the @b{2} in
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
Inserting this command before the Fingering object is created,
i.e., before @code{c2}, yields the following result:
-@lilypond[quote,relative=2,fragment,verbatim]
+@lilypond[quote,relative=2,verbatim]
\once \override Voice.Fingering #'padding = #3
c-2
\stemUp
* The override command::
* The tweak command::
* set versus override::
+* Modifying alists::
@end menu
applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
c4
\override Staff.Stem #'thickness = #4.0
c4
causing the default context @code{Voice} to be used. Adding
@code{\once} applies the change during one timestep only.
-@lilypond[quote,fragment,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
c4
\once \override Stem #'thickness = #4.0
c4
or beams, the @code{\override} command must be executed at the moment
when the object is created. In this example,
-@lilypond[quote,fragment,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
\override Slur #'thickness = #3.0
c8[( c
-\override Beam #'thickness = #0.6
+\override Beam #'beam-thickness = #0.6
c8 c])
@end lilypond
For example, multimeasure rests will be combined into a single bar
if the context property @code{skipBars} is set to @code{#t}:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
R1*2
\set Score.skipBars = ##t
R1*2
set in the current bottom context (typically @code{ChordNames},
@code{Voice}, @code{TabVoice}, or @code{Lyrics}).
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##f
<<
{
@code{Voice}, will have no effect, because skipBars is a property of
the @code{Score} context.
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
R1*2
\set skipBars = ##t
R1*2
Properties that have been set in enclosing contexts will
not be altered by an unset in an enclosed context:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##t
<<
{
Preceding a @code{\set} command by @code{\once} makes the
setting apply to only a single time-step:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
c4
\once \set fontSize = #4.7
c4
description. Grob descriptions are named in @code{StudlyCaps}
(starting with capital letters). They contain the
@q{default settings} for a particular kind of grob as an
-association list. See @file{scm/@/define@/-grobs@/.scm}
+association list. See @file{scm/define-grobs.scm}
to see the settings for each grob description. Grob descriptions
are modified with @code{\override}.
overriding the @code{thickness} property of the @code{Stem}
object:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
c4 c
\override Voice.Stem #'thickness = #3.0
c4 c
If no context is specified in an @code{\override}, the bottom
context is used:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
{ \override Staff.Stem #'thickness = #3.0
<<
{
The effects of @code{\override} can be undone by @code{\revert}:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
c4
\override Voice.Stem #'thickness = #3.0
c4 c
The effects of @code{\override} and @code{\revert} apply to all
grobs in the affected context from the current time forward:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
{
<<
{
@code{\once} can be used with @code{\override}
to affect only the current time step:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
{
<<
{
@node set versus override
@subsection @code{\set} vs. @code{\override}
-TODO -- This section is probably unnecessary now.
+@c TODO -- This section is probably unnecessary now.
@ignore
We have seen two methods of changing properties: @code{\set} and
@end ignore
+
+@node Modifying alists
+@subsection Modifying alists
+
+Some user-configurable properties are internally represented as
+@emph{alists} (association lists), which store pairs of
+@emph{keys} and @emph{values}. The structure of an alist is:
+
+@example
+'((@var{key1} . @var{value1})
+ (@var{key2} . @var{value2})
+ (@var{key3} . @var{value3})
+ @dots{})
+@end example
+
+If an alist is a grob property or @code{\paper} variable, its keys
+can be modified individually without affecting other keys.
+
+For example, to reduce the space between adjacent staves in a
+staff-group, use the @code{staff-staff-spacing} property of the
+@code{StaffGrouper} grob. The property is an alist with four
+keys: @code{basic-distance}, @code{minimum-distance},
+@code{padding}, and @code{stretchability}. The standard settings
+for this property are listed in the @qq{Backend} section of the
+Internals Reference (see @rinternals{StaffGrouper}):
+
+@example
+'((basic-distance . 9)
+ (minimum-distance . 7)
+ (padding . 1)
+ (stretchability . 5))
+@end example
+
+One way to bring the staves closer together is by reducing the
+value of the @code{basic-distance} key (@code{9}) to match the
+value of @code{minimum-distance} (@code{7}). To modify a single
+key individually, use a @emph{nested declaration}:
+
+@lilypond[quote,verbatim]
+% default space between staves
+\new PianoStaff <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+
+% reduced space between staves
+\new PianoStaff \with {
+ % this is the nested declaration
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
+} <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+@end lilypond
+
+Using a nested declaration will update the specified key (such as
+@code{basic-distance} in the above example) without altering any
+other keys already set for the same property.
+
+Now suppose we want the staves to be as close as possible without
+overlapping. The simplest way to do this is to set all four alist
+keys to zero. However, it is not necessary to enter four nested
+declarations, one for each key. Instead, the property can be
+completely re-defined with one declaration, as an alist:
+
+@lilypond[quote,verbatim]
+\new PianoStaff \with {
+ \override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 0)
+ (minimum-distance . 0)
+ (padding . 0)
+ (stretchability . 0))
+} <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+@end lilypond
+
+Note that any keys not explicitly listed in the alist definition
+will be reset to their @emph{default-when-unset} values. In the
+case of @code{staff-staff-spacing}, any unset key-values would be
+reset to zero (except @code{stretchability}, which takes the value
+of @code{basic-distance} when unset). Thus the following two
+declarations are equivalent:
+
+@example
+\override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 7))
+
+\override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 7)
+ (minimum-distance . 0)
+ (padding . 0)
+ (stretchability . 7))
+@end example
+
+One (possibly unintended) consequence of this is the removal of
+any standard settings that are set in an initialization file and
+loaded each time an input file is compiled. In the above example,
+the standard settings for @code{padding} and
+@code{minimum-distance} (defined in @file{scm/define-grobs.scm})
+are reset to their default-when-unset values (zero for both keys).
+Defining a property or variable as an alist (of any size) will
+always reset all unset key-values to their default-when-unset
+values. Unless this is the intended result, it is safer to update
+key-values individually with a nested declaration.
+
+@warning{Nested declarations will not work for context property
+alists (such as @code{beamExceptions}, @code{keySignature},
+@code{timeSignatureSettings}, etc.). These properties can only be
+modified by completely re-defining them as alists.}
+
+
@node Useful concepts and properties
@section Useful concepts and properties
other page layout details, and are by default specified in
millimeters. Distances may be specified in other units by
following the quantity by @code{\mm}, @code{\cm},
-@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27
-of an inch). Page layout distances can also be specified in
-scalable units (see the following paragraph) by appending
-@code{\staff-space} to the quantity.
-Page layout is described in detail in @ref{Page formatting}.
+@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27 of
+an inch). Page layout distances can also be specified in scalable
+units (see the following paragraph) by appending
+@code{\staff-space} to the quantity. Page layout is described in
+detail in @ref{Page layout}.
Scaled distances are always specified in units of the staff-space
or, rarely, the half staff-space. The staff-space is the distance
@rlearning{Length and thickness of objects}.
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Setting the staff size}.
This is a markup that is evaluated to yield the stencil. It is used
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
\override TextSpanner #'(bound-details left text)
= \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
if @code{to-barline} is true and a bar line occurs before the next
note.
-@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,relative=2]
\endSpanners
c2 \startTextSpan c2 c2
\endSpanners
where there is no line break, or after a line break.
Alternatively, these eight combinations may be specified
-by pre-defined functions, defined in @file{scm/@/output@/-lib@/.scm},
+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:
@end multitable
The example below shows the use of the vector form to control the
-visibility of barlines:
+visibility of bar lines:
@lilypond[quote,verbatim,relative=1,ragged-right]
f4 g a b
@cindex clefs, visibility of octavation
The small octavation symbol on octavated clefs is produced by the
-@code{OctavateEight} layout object. Its visibility is controlled
-independently from that of the @code{Clef} object, so it is
-necessary to apply any required @code{break-visibility} overrides
-to both the @code{Clef} and the @code{OctavateEight} layout objects
-to fully suppress such clef symbols at the start of each line.
+@code{OctavateEight} 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.
For explicit clef changes, the @code{explicitClefVisibility}
property controls both the clef symbol and any octavation symbol
@ref{Modifying properties}.
Installed Files:
-@file{scm/@/define@/-grobs@/.scm}.
+@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
}
@end lilypond
-@seealso
-
-TODO: add missing @@ref's here.
+@c TODO: add appropriate @@ref's here.