Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.39"
+@c \version "2.14.0"
@node Changing defaults
@chapter Changing defaults
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 @code{.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.}
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}.
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
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
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}.
@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
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
% 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 }
@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
@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 }
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},
other page layout details, and are by default specified in
millimeters. Distances may be specified in other units by
following the quantity by @code{\mm}, @code{\cm},
-@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27
-of an inch). Page layout distances can also be specified in
-scalable units (see the following paragraph) by appending
-@code{\staff-space} to the quantity.
-Page layout is described in detail in @ref{Page formatting}.
+@code{\in}@tie{}(inches), or @code{\pt}@tie{}(points, 1/72.27 of
+an inch). Page layout distances can also be specified in scalable
+units (see the following paragraph) by appending
+@code{\staff-space} to the quantity. Page layout is described in
+detail in @ref{Page layout}.
Scaled distances are always specified in units of the staff-space
or, rarely, the half staff-space. The staff-space is the distance
@rlearning{Length and thickness of objects}.
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Setting the staff size}.
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:
@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
@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
@ref{Modifying properties}.
Installed Files:
-@file{scm/@/define@/-grobs@/.scm}.
+@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
@cindex slurs, modifying
@cindex ties, modifying
-@cindex Bézier curves
-@cindex Bézier control points
-
-Ties, slurs and phrasing slurs are drawn as third-order Bézier
-curves. If the shape of the tie or slur which is calculated
-automatically is not optimum, the shape may be modified manually by
-explicitly specifying the four control points required to define
-a third-order Bézier curve.
-
-Third-order or cubic Bézier curves are defined by four control
-points. The first and fourth control points are precisely the
-starting and ending points of the curve. The intermediate two
-control points define the shape. Animations showing how the curve
-is drawn can be found on the web, but the following description
-may be helpful. The curve starts from the first control point
-heading directly towards the second, gradually bending over to
-head towards the third and continuing to bend over to head towards
-the fourth, arriving there travelling directly from the third
-control point. The curve is entirely contained in the
-quadrilateral defined by the four control points.
-
-Here is an example of a case where the tie is not optimum, and
-where @code{\tieDown} would not help.
+@cindex Bézier curves, control points
+@cindex control points, Bézier curves
+
+If the shape of the tie or slur which is calculated automatically is not
+optimum, the shape may be modified manually by explicitly specifying the
+control points required to define the curve needed.
+
+Ties, slurs and phrasing slurs are drawn as @q{third-order} Bézier
+curves which are are defined by four control points. The first and
+fourth control points are the start and end points of the curve
+respectively, and the two intermediate control points define the
+overall shape.
+
+Animations showing how the curve is drawn can be found on the web, but
+the following description may be helpful. The curve starts from the
+first control point moving towards the second. As the curve nears and
+passes through the second control point it begins to arc towards the
+third. The curve continues on towards the the third control point,
+again starting to arc as it nears and passes through the third so as to
+finish the curve smoothly at the fourth and final control point. The
+whole curve is contained in the quadrilateral defined by the four
+control points.
+
+Here is an example of a case where the tie is not optimum (and where the
+@code{\tieDown} command would not help).
@lilypond[verbatim,quote,relative=1]
<<
- { e1 ~ e }
+ { e1~ e }
\\
{ r4 <g c,> <g c,> <g c,> }
>>
{
\once \override Tie
#'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
- e1 ~ e1
+ e1 ~ e
}
\\
- { r4 <g c,> <g c,> <g c,>4 }
+ { r4 <g c,> <g c,> <g c,> }
>>
@end lilypond
@knownissues
-
It is not possible to modify shapes of ties or slurs by changing
-the @code{control-points} property if there are more than one at
-the same musical moment, not even by using the @code{\tweak}
-command. However, the @code{tie-configuration} property of
-@code{TieColumn} can be overridden to set start line and direction
-of ties as required.
-
+the @code{control-points} property if there are multiple ties or slurs
+at the same musical moment -- the @code{\tweak} command will also not
+work in this case. However, the @code{tie-configuration} property of
+@code{tie-column-interface} can be overridden to set start line and
+direction of ties as required.
+@seealso
+Internals Reference:
+@rinternals{tie-column-interface}.
@node Using music functions
}
@end lilypond
-@seealso
-
-TODO: add missing @@ref's here.
+@c TODO: add appropriate @@ref's here.
projects / lilypond.git / blobdiff