* The override command::
* The tweak command::
* set versus override::
+* Modifying alists::
@end menu
@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
+system, use the @code{between-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}:
+
+@example
+(between-staff-spacing . ((padding . 1)
+ (space . 9)
+ (minimum-distance . 7)))
+@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:
+
+@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 {
+ \override StaffGrouper #'between-staff-spacing #'space = #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.
+
+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:
+
+@lilypond[quote,verbatim]
+\new PianoStaff \with {
+ \override StaffGrouper #'between-staff-spacing =
+ #'((padding . 0)
+ (space . 0)
+ (minimum-distance . 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{between-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:
+
+@example
+\override StaffGrouper #'between-staff-spacing =
+ #'((space . 7))
+
+\override StaffGrouper #'between-staff-spacing =
+ #'((padding . 0)
+ (space . 7)
+ (minimum-distance . 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.
+
+@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
eliminate collisions.
@end itemize
-
-@subsubheading Modifying spacing alists for @code{\paper} variables
-
-To set or modify a single key for a dimension variable, use a
-nested declaration:
+Specific methods for modifying alists are discussed in
+@ref{Modifying alists}. The flexible vertical @code{\paper}
+dimensions variables can only be set within a @code{\paper} block.
+The following example demonstrates the two ways these alists can
+be modified:
@example
\paper @{
- system-system-spacing #'space = #10
-@}
-@end example
-
-This will update the specified key without altering any other keys
-already set for the same variable. To completely re-define a
-variable with one declaration, define it as an alist:
+ % updating one key-value individually
+ system-system-spacing #'space = #8
-@example
-\paper @{
- system-system-spacing =
+ % completely re-defining a variable
+ score-system-spacing =
#'((padding . 1)
(space . 12)
- (minimum-distance . 8)
+ (minimum-distance . 6)
(stretchability . 12))
@}
@end example
-However, note that any keys not listed in an alist definition will
-still be overwritten; they will be reset to zero (except
-@code{stretchability}, which takes the value of @code{space}).
-Thus the following two declarations are equivalent:
-
-@example
-system-system-spacing =
- #'((space . 10))
-
-system-system-spacing =
- #'((padding . 0)
- (space . 10)
- (minimum-distance . 0)
- (stretchability . 10))
-@end example
-
-One possibly unintended consequence of the above example is the
-removal of the default values for @code{padding} and
-@code{minimum-distance}. Defining a variable as an alist (of any
-size) will always reset all its default key-values. Default
-settings for the flexible vertical @code{\paper} dimensions are
-defined in @file{ly/paper-defaults-init.ly}.
+The initialized default settings for these variables are defined
+in @file{ly/paper-defaults-init.ly}.
@subsubheading Flexible vertical dimension @code{\paper} variables
projects / lilypond.git / commitdiff