X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=7f1bb0f0a0b790d8c051b4f97b2d947ad6968797;hb=2055f35c47a045a50a01ff4dba8524322cfc3b48;hp=040095ff6f3fde9c8945b50af56a3a683cfdf2fd;hpb=1b832d794f1444033f10465971e97d33f76fe310;p=lilypond.git diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index 040095ff6f..7f1bb0f0a0 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.13.39" +@c \version "2.14.0" @node Changing defaults @chapter Changing defaults @@ -36,7 +36,7 @@ and is also included with the LilyPond documentation package. Internally, LilyPond uses Scheme (a LISP dialect) to provide infrastructure. Overriding layout decisions in effect accesses the program internals, which requires Scheme input. Scheme elements are -introduced in a @file{@/.ly} file with the hash mark +introduced in a @file{.ly} file with the hash mark @code{#}.@footnote{@rextend{Scheme tutorial}, contains a short tutorial on entering numbers, lists, strings, and symbols in Scheme.} @@ -71,9 +71,9 @@ This section describes what contexts are, and how to modify them. Learning Manual: @rlearning{Contexts and engravers}. -Installed files: -@file{ly/@/engraver@/-init@/.ly}, -@file{ly/@/performer@/-init@/.ly}. +Installed Files: +@file{ly/engraver-init.ly}, +@file{ly/performer-init.ly}. Snippets: @rlsr{Contexts and engravers}. @@ -568,7 +568,7 @@ Notation contexts (like @code{Score} and @code{Staff}) not only store properties, they also contain plug-ins called @q{engravers} that create notation elements. For example, the @code{Voice} context contains a -@code{Note_head_engraver} and the @code{Staff} context contains a +@code{Note_heads_engraver} and the @code{Staff} context contains a @code{Key_signature_engraver}. For a full a description of each plug-in, see @@ -1199,7 +1199,7 @@ can be modified. We have been talking of @emph{the} @code{Fingering} object, but actually it does not amount to much. The initialization file (see @rlearning{Other sources of information}) -@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object}, +@file{scm/define-grobs.scm} shows the soul of the @q{object}, @example (Fingering @@ -1624,7 +1624,7 @@ There is a special type of context property: the grob description. Grob descriptions are named in @code{StudlyCaps} (starting with capital letters). They contain the @q{default settings} for a particular kind of grob as an -association list. See @file{scm/@/define@/-grobs@/.scm} +association list. See @file{scm/define-grobs.scm} to see the settings for each grob description. Grob descriptions are modified with @code{\override}. @@ -1964,7 +1964,7 @@ generated ties in a chord. @node set versus override @subsection @code{\set} vs. @code{\override} -TODO -- This section is probably unnecessary now. +@c TODO -- This section is probably unnecessary now. @ignore We have seen two methods of changing properties: @code{\set} and @@ -1999,19 +1999,22 @@ can be modified individually without affecting other keys. For example, to reduce the space between adjacent staves in a staff-group, use the @code{staff-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; these are listed in the @qq{Backend} section of -the Internals Reference (see @rinternals{StaffGrouper}): +keys: @code{basic-distance}, @code{minimum-distance}, +@code{padding}, and @code{stretchability}. The standard settings +for this property are listed in the @qq{Backend} section of the +Internals Reference (see @rinternals{StaffGrouper}): @example -'((space . 9) (minimum-distance . 7) (padding . 1)) +'((basic-distance . 9) + (minimum-distance . 7) + (padding . 1) + (stretchability . 5)) @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 @emph{nested declaration}: +value of the @code{basic-distance} key (@code{9}) to match the +value of @code{minimum-distance} (@code{7}). To modify a single +key individually, use a @emph{nested declaration}: @lilypond[quote,verbatim] % default space between staves @@ -2023,7 +2026,7 @@ individually, use a @emph{nested declaration}: % reduced space between staves \new PianoStaff \with { % this is the nested declaration - \override StaffGrouper #'staff-staff-spacing #'space = #7 + \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7 } << \new Staff { \clef treble c''1 } \new Staff { \clef bass c1 } @@ -2031,8 +2034,8 @@ individually, use a @emph{nested declaration}: @end lilypond Using a nested declaration will update the specified key (such as -@code{space} in the above example) without altering any other keys -already set for the same property. +@code{basic-distance} 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 @@ -2043,9 +2046,9 @@ completely re-defined with one declaration, as an alist: @lilypond[quote,verbatim] \new PianoStaff \with { \override StaffGrouper #'staff-staff-spacing = - #'((padding . 0) - (space . 0) + #'((basic-distance . 0) (minimum-distance . 0) + (padding . 0) (stretchability . 0)) } << \new Staff { \clef treble c''1 } @@ -2057,31 +2060,30 @@ 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{staff-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: +of @code{basic-distance} when unset). Thus the following two +declarations are equivalent: @example \override StaffGrouper #'staff-staff-spacing = - #'((space . 7)) + #'((basic-distance . 7)) \override StaffGrouper #'staff-staff-spacing = - #'((padding . 0) - (space . 7) + #'((basic-distance . 7) (minimum-distance . 0) + (padding . 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. +any standard settings that are set in an initialization file and +loaded each time an input file is compiled. In the above example, +the standard settings 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}, @@ -2865,7 +2867,7 @@ beginning of a line. Or to be more precise, before a line break, where there is no line break, or after a line break. Alternatively, these eight combinations may be specified -by pre-defined functions, defined in @file{scm/@/output@/-lib@/.scm}, +by pre-defined functions, defined in @file{scm/output-lib.scm}, where the last three columns indicate whether the layout objects will be visible in the positions shown at the head of the columns: @@ -2914,7 +2916,7 @@ default setting of this property: @end multitable The example below shows the use of the vector form to control the -visibility of barlines: +visibility of bar lines: @lilypond[quote,verbatim,relative=1,ragged-right] f4 g a b @@ -3045,11 +3047,10 @@ occur only at explicit @code{\bar} commands. @cindex clefs, visibility of octavation The small octavation symbol on octavated clefs is produced by the -@code{OctavateEight} layout object. Its visibility is controlled -independently from that of the @code{Clef} object, so it is -necessary to apply any required @code{break-visibility} overrides -to both the @code{Clef} and the @code{OctavateEight} layout objects -to fully suppress such clef symbols at the start of each line. +@code{OctavateEight} layout object. Its visibility is automatically +inherited from the @code{Clef} object, so it is not necessary to apply +any required @code{break-visibility} overrides to the @code{OctavateEight} +layout objects to suppress octavation symbols for invisible clefs. For explicit clef changes, the @code{explicitClefVisibility} property controls both the clef symbol and any octavation symbol @@ -3198,7 +3199,7 @@ Notation Reference: @ref{Modifying properties}. Installed Files: -@file{scm/@/define@/-grobs@/.scm}. +@file{scm/define-grobs.scm}. Snippets: @rlsr{Tweaks and overrides}. @@ -3783,9 +3784,9 @@ Extending: @rextend{Music functions}. Installed Files: -@file{lily/@/music@/-scheme@/.cc}, -@file{scm/@/c++@/.scm}, -@file{scm/@/lily@/.scm}. +@file{lily/music-scheme.cc}, +@file{scm/c++.scm}, +@file{scm/lily.scm}. @node Substitution function examples @@ -3858,6 +3859,4 @@ tempoPadded = } @end lilypond -@seealso - -TODO: add missing @@ref's here. +@c TODO: add appropriate @@ref's here.