From 20db6d712e1d52bad2646ad6fd7a3004f991cd81 Mon Sep 17 00:00:00 2001 From: Mark Polesky Date: Tue, 2 Nov 2010 12:16:57 -0700 Subject: [PATCH] Doc: NR 5.3: New node "Modifying alists". --- .../notation/changing-defaults.itely | 113 ++++++++++++++++++ Documentation/notation/spacing.itely | 50 ++------ 2 files changed, 125 insertions(+), 38 deletions(-) diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index d0f11e7c84..8c4ea21884 100644 --- 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 diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely index a7891d723e..5848a90a9b 100644 --- a/Documentation/notation/spacing.itely +++ b/Documentation/notation/spacing.itely @@ -292,54 +292,28 @@ largest of: 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 -- 2.39.2