Doc: NR 5.3: New node "Modifying alists".

[lilypond.git] / Documentation / notation / changing-defaults.itely

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index d0f11e7c84e9e3057876f4ab5a960f7a0d1fe27d..8c4ea218843b2698f4875697a6c7d3d93cc9607b 100644 (file)
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -1340,6 +1340,7 @@ LP-specific?
 * The override command::
 * The tweak command::
 * set versus override::
+* Modifying alists::
 @end menu
 
 
@@ -1977,6 +1978,118 @@ property (modified with @code{\set}) was created.
 
 @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