Doc: NR 4.1.2: Setting alist keys properly.

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index e235c50a4ea6935d1e13e1cb4c6c00a0971ee412..906f9976a80446bbe8045a02867809c558975827 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -283,28 +283,52 @@ largest of:
 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