+
+@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.}
+
+