Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.39"
+@c \version "2.13.42"
@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}.
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
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}.
@emph{keys} and @emph{values}. The structure of an alist is:
@example
-#((@var{key1} . @var{value1})
+'((@var{key1} . @var{value1})
(@var{key2} . @var{value2})
(@var{key3} . @var{value3})
@dots{})
can be modified individually without affecting other keys.
For example, to reduce the space between adjacent staves in a
-system, use the @code{staff-staff-spacing} property of the
+staff-group, use the @code{staff-staff-spacing} property of the
@code{StaffGrouper} grob. The property is an alist with four
-keys: @code{padding}, @code{space}, @code{minimum-distance}, and
-@code{stretchability}. Three of the four keys have initialized
-default values, which are defined (along with all the other grob
-properties) in the file @file{scm/define-grobs.scm}:
+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
-(staff-staff-spacing . ((padding . 1)
- (space . 9)
- (minimum-distance . 7)))
+'((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{space} key (@code{9}) to match the value of
-@code{minimum-distance} (@code{7}). To modify a single key
-individually, use a nested declaration:
+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
% reduced space between staves
\new PianoStaff \with {
- \override StaffGrouper #'staff-staff-spacing #'space = #7
+ % 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
-(@code{space} in the above example) without altering any other
-keys already set for the same property.
+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. In that case, it is not necessary to set each key
-individually with nested declarations. Instead, the property can
-be completely re-defined with one declaration, as an 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 =
- #'((padding . 0)
- (space . 0)
+ #'((basic-distance . 0)
(minimum-distance . 0)
+ (padding . 0)
(stretchability . 0))
} <<
\new Staff { \clef treble c''1 }
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{space} when unset). Thus the following two declarations
-are equivalent:
+of @code{basic-distance} when unset). Thus the following two
+declarations are equivalent:
@example
\override StaffGrouper #'staff-staff-spacing =
- #'((space . 7))
+ #'((basic-distance . 7))
\override StaffGrouper #'staff-staff-spacing =
- #'((padding . 0)
- (space . 7)
+ #'((basic-distance . 7)
(minimum-distance . 0)
+ (padding . 0)
(stretchability . 7))
@end example
One (possibly unintended) consequence of this is the removal of
-any @emph{initialized} default values that are set in an
-initialization file and loaded each time an input file is
-compiled. In the above example, the initialized default values
-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.
+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},
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}.
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:
@ref{Modifying properties}.
Installed Files:
-@file{scm/@/define@/-grobs@/.scm}.
+@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.