eliminate collisions.
@end itemize
-A single key for a flexible vertical dimension variable can be set
-like this:
+To set or modify a single key for a dimension variable, use a
+nested declaration:
@example
\paper @{
- markup-system-spacing #'space = #5
+ system-system-spacing #'space = #10
@}
@end example
-Multiple keys for a single variable can be set simultaneously like
-this:
+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:
@example
\paper @{
- last-bottom-spacing =
+ system-system-spacing =
#'((padding . 1)
- (space . 1)
- (minimum-distance . 0)
- (stretchability . 5))
+ (space . 12)
+ (minimum-distance . 8)
+ (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 names of the flexible vertical dimension variables follow the
format @code{@var{upper}-@var{lower}-spacing}, where
@code{@var{upper}} and @code{@var{lower}} are the items to be