Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@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}.
@node Score - the master of all contexts
@unnumberedsubsubsec Score - the master of all contexts
-This is the top level notation context. No other context can
-contain a Score context. By default the Score context handles
+This is the top level notation context. No other context can
+contain a Score context. By default the Score context handles
the administration of time signatures and makes sure that items
such as clefs, time signatures, and key-signatures are aligned
across staves.
A Score context is instantiated implicitly when a
@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
-processed, or explicitly when a @code{\new Score} command is
-executed.
+processed.
@node Top-level contexts - staff containers
@unnumberedsubsubsec Top-level contexts - staff containers
@strong{@emph{StaffGroup}}
Groups staves while adding a bracket on the left side, grouping
-the staves together. The bar lines of the contained staves are
+the staves together. The bar lines of the contained staves are
connected vertically. @code{StaffGroup} only consists of a collection
of staves, with a bracket in front and spanning bar lines.
@node Creating contexts
@subsection Creating contexts
-@c TODO \new Score and \score
@c TODO more complete descriptions rather than learning style
For scores with only one voice and one staff, contexts are
staves. Each part that should be on its own staff, is preceded with
@code{\new Staff}.
-@lilypond[quote,verbatim,relative=2,ragged-right,fragment]
+@lilypond[quote,verbatim,relative=2,ragged-right]
<<
\new Staff { c4 c }
\new Staff { d4 d }
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
example which removes @code{Time_signature_engraver} and
@code{Clef_engraver} from a @code{Staff} context,
-@lilypond[quote,relative=1,verbatim,fragment]
+@lilypond[quote,relative=1,verbatim]
<<
\new Staff {
f2 g
@cindex polymetric scores
@cindex Time signatures, multiple
-@lilypond[quote,relative=1,ragged-right,verbatim,fragment]
-\new Score \with {
- \remove "Timing_translator"
- \remove "Default_bar_line_engraver"
-} <<
+@lilypond[quote,verbatim]
+\score {
+ <<
+ \new Staff \with {
+ \consists "Timing_translator"
+ \consists "Default_bar_line_engraver"
+ } {
+ \time 3/4
+ c4 c c c c c
+ }
\new Staff \with {
\consists "Timing_translator"
\consists "Default_bar_line_engraver"
} {
- \time 3/4
+ \time 2/4
c4 c c c c c
}
- \new Staff \with {
- \consists "Timing_translator"
- \consists "Default_bar_line_engraver"
- } {
- \time 2/4
- c4 c c c c c
- }
>>
+\layout {
+ \context {
+ \Score
+ \remove "Timing_translator"
+ \remove "Default_bar_line_engraver"
+ }
+ }
+}
@end lilypond
@knownissues
It is not possible to collect context changes in a variable and apply
them to a @code{\context} definition by referring to that variable.
-The @code{\RemoveEmptyStaffContext} will overwrite your current
+The @code{\Staff \RemoveEmptyStaves} will overwrite your current
@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\RemoveEmptyStaffContext}, you must do so
-after calling @code{\RemoveEmptyStaffContext}, ie
+staff which uses @code{\Staff \RemoveEmptyStaves}, you must do so
+after calling @code{\Staff \RemoveEmptyStaves}, ie
@example
\layout @{
\context @{
- \RemoveEmptyStaffContext
+ \Staff \RemoveEmptyStaves
\override Stem #'thickness = #4.0
@}
Suppose we want to move the fingering indication in the fragment
below:
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
on @code{FingeringEvent} and one on @code{Fingering}.
The page on @code{FingeringEvent} describes the properties of the music
-expression for the input @code{-2}. The page contains many links
+expression for the input @w{@code{-2}}. The page contains many links
forward. For example, it says
@quotation
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
(script-priority . 100)
(stencil . ,ly:text-interface::print)
(direction . ,ly:script-interface::calc-direction)
- (font-encoding . fetaNumber)
+ (font-encoding . fetaText)
(font-size . -5) ; don't overlap when next to heads.
(meta . ((class . Item)
(interfaces . (finger-interface
Recall that we wanted to change the position of the @b{2} in
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
Inserting this command before the Fingering object is created,
i.e., before @code{c2}, yields the following result:
-@lilypond[quote,relative=2,fragment,verbatim]
+@lilypond[quote,relative=2,verbatim]
\once \override Voice.Fingering #'padding = #3
c-2
\stemUp
* The override command::
* The tweak command::
* set versus override::
+* Modifying alists::
@end menu
applies to the current staff. Other staves will keep their normal
appearance. Here we see the command in action:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
c4
\override Staff.Stem #'thickness = #4.0
c4
causing the default context @code{Voice} to be used. Adding
@code{\once} applies the change during one timestep only.
-@lilypond[quote,fragment,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
c4
\once \override Stem #'thickness = #4.0
c4
or beams, the @code{\override} command must be executed at the moment
when the object is created. In this example,
-@lilypond[quote,fragment,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
\override Slur #'thickness = #3.0
c8[( c
-\override Beam #'thickness = #0.6
+\override Beam #'beam-thickness = #0.6
c8 c])
@end lilypond
@node The set command
-@subsection The @code{\set} command
+@subsection The @code{@bs{}set} command
@cindex properties
@funindex \set
For example, multimeasure rests will be combined into a single bar
if the context property @code{skipBars} is set to @code{#t}:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
R1*2
\set Score.skipBars = ##t
R1*2
set in the current bottom context (typically @code{ChordNames},
@code{Voice}, @code{TabVoice}, or @code{Lyrics}).
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##f
<<
{
@code{Voice}, will have no effect, because skipBars is a property of
the @code{Score} context.
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
R1*2
\set skipBars = ##t
R1*2
Properties that have been set in enclosing contexts will
not be altered by an unset in an enclosed context:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##t
<<
{
Preceding a @code{\set} command by @code{\once} makes the
setting apply to only a single time-step:
-@lilypond[quote,verbatim,relative=2,fragment]
+@lilypond[quote,verbatim,relative=2]
c4
\once \set fontSize = #4.7
c4
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}.
overriding the @code{thickness} property of the @code{Stem}
object:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
c4 c
\override Voice.Stem #'thickness = #3.0
c4 c
If no context is specified in an @code{\override}, the bottom
context is used:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
{ \override Staff.Stem #'thickness = #3.0
<<
{
The effects of @code{\override} can be undone by @code{\revert}:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
c4
\override Voice.Stem #'thickness = #3.0
c4 c
The effects of @code{\override} and @code{\revert} apply to all
grobs in the affected context from the current time forward:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
{
<<
{
@code{\once} can be used with @code{\override}
to affect only the current time step:
-@lilypond[quote, verbatim, relative=2, fragment]
+@lilypond[quote,verbatim,relative=2]
{
<<
{
@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
@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
+staff-group, use the @code{staff-staff-spacing} property of the
+@code{StaffGrouper} grob. The property is an alist with four
+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
+'((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{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
+\new PianoStaff <<
+ \new Staff { \clef treble c''1 }
+ \new Staff { \clef bass c1 }
+>>
+
+% reduced space between staves
+\new PianoStaff \with {
+ % this is the nested declaration
+ \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{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
+keys to zero. However, it is not necessary to enter four nested
+declarations, one for each key. Instead, the property can be
+completely re-defined with one declaration, as an alist:
+
+@lilypond[quote,verbatim]
+\new PianoStaff \with {
+ \override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 0)
+ (minimum-distance . 0)
+ (padding . 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{staff-staff-spacing}, any unset key-values would be
+reset to zero (except @code{stretchability}, which takes the value
+of @code{basic-distance} when unset). Thus the following two
+declarations are equivalent:
+
+@example
+\override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 7))
+
+\override StaffGrouper #'staff-staff-spacing =
+ #'((basic-distance . 7)
+ (minimum-distance . 0)
+ (padding . 0)
+ (stretchability . 7))
+@end example
+
+One (possibly unintended) consequence of this is the removal of
+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},
+@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
@item @code{\markup} commands
@item @code{\tag} commands
@item string markups, e.g. -"string"
-@item fingering instructions, e.g. @code{-1}
-@item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
+@item fingering instructions, e.g. @w{@code{-1}}
+@item articulation shortcuts, e.g. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
@end itemize
Direction indicators affect only the next note:
by the @code{direction} property.
The value of the @code{direction} property may be
-set to @code{1}, meaning @qq{up} or @qq{above}, or to @code{-1},
+set to @code{1}, meaning @qq{up} or @qq{above}, or to @w{@code{-1}},
meaning @qq{down} or @qq{below}. The symbols @code{UP} and
-@code{DOWN} may be used instead of @code{1} and @code{-1}
+@code{DOWN} may be used instead of @code{1} and @w{@code{-1}}
respectively. The default direction may be specified by setting
@code{direction} to @code{0} or @code{CENTER}. Alternatively,
in many cases predefined commands
In a few cases, arpeggio being the only common example, the value
of the @code{direction} property specifies whether the object
is to be placed to the right or left of the parent object. In
-this case @code{-1} or @code{LEFT} means @qq{to the left} and
+this case @w{@code{-1}} or @code{LEFT} means @qq{to the left} and
@code{1} or @code{RIGHT} means @qq{to the right}. @code{0}
or @code{CENTER} means @qq{use the default} direction, as before.
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}.
their appearance and behaviour. Some of these properties are common
to all spanners; others are restricted to a sub-set of the spanners.
-All spanners support the @code{spanner-interface}. A few, esentially
+All spanners support the @code{spanner-interface}. A few, essentially
those that draw a straight line between the two objects, support in
addition the @code{line-spanner-interface}.
For some layout objects, the @code{minimum-length} property becomes
effective only if the @code{set-spacing-rods} procedure is called
explicitly. To do this, the @code{springs-and-rods} property should
-be set to @code{ly:spanner::set-spacing-rods}. For example,
+be set to @code{ly:spanner::set-spacing-rods}. For example,
the minimum length of a glissando has no effect unless the
@code{springs-and-rods} property is set:
@end lilypond
This property is not effective for all spanners. For example,
-seting it to @code{#t} has no effect on slurs or phrasing slurs
+setting it to @code{#t} has no effect on slurs or phrasing slurs
or on other spanners for which terminating on the bar line would
not be meaningful.
specified by the @code{left-broken} and @code{right-broken}
sub-lists of @code{bound-details}. For example:
-@lilypond[relative=2,ragged-right,verbatim,fragment]
+@lilypond[relative=2,ragged-right,verbatim,quote]
\override Glissando #'breakable = ##t
\override Glissando #'(bound-details right-broken Y) = #-3
c1 \glissando \break
@item attach-dir
This determines where the line starts and ends in the X-direction,
-relative to the bound object. So, a value of @code{-1} (or
+relative to the bound object. So, a value of @w{@code{-1}} (or
@code{LEFT}) makes the line start/end at the left side of the note
head it is attached to.
This is a markup that is evaluated to yield the stencil. It is used
to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
\override TextSpanner #'(bound-details left text)
= \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
or @code{stencil-offset} will move the symbol at the edge vertically
relative to the end point of the line:
-@lilypond[relative=1,fragment,verbatim]
+@lilypond[relative=1,quote,verbatim]
\override TextSpanner
#'(bound-details left stencil-align-dir-y) = #-2
\override TextSpanner
@end lilypond
Note that negative values move the text @emph{up}, contrary to the
-effect that might be expected, as a value of @code{-1} or
+effect that might be expected, as a value of @w{@code{-1}} or
@code{DOWN} means align the @emph{bottom} edge of the text with
the spanner line. A value of @code{1} or @code{UP} aligns
the top edge of the text with the spanner line.
if @code{to-barline} is true and a bar line occurs before the next
note.
-@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,relative=2]
\endSpanners
c2 \startTextSpan c2 c2
\endSpanners
value of @code{1}, is drawn after the staff lines (default
@code{layer} value @code{0}), so overwriting them. To change this,
the @code{Clef} object must be given in a lower value of
-@code{layer}, say @code{-1}, so that it is drawn earlier:
+@code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
@lilypond[quote,verbatim,relative=2]
\override Staff.Clef #'color = #white
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
Here is an example showing the different line styles available,
and how to tune them.
-@lilypond[relative=2,ragged-right,verbatim,fragment]
+@lilypond[relative=2,ragged-right,verbatim,quote]
d2 \glissando d'2
\once \override Glissando #'style = #'dashed-line
d,2 \glissando d'2
override these:
@c TODO Complete
-@lilypond[relative=2,ragged-right,verbatim,fragment]
+@lilypond[relative=2,ragged-right,verbatim,quote]
e2 \glissando f
\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando f
@end lilypond
-The value for @code{Y} is set to @code{-2} for the right end
+The value for @code{Y} is set to @w{@code{-2}} for the right end
point. The left side may be similarly adjusted by specifying
@code{left} instead of @code{right}.
@ref{Modifying properties}.
Installed Files:
-@file{scm/@/define@/-grobs@/.scm}.
+@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
@node Aligning objects
@subsection Aligning objects
-Graphical objects which support the @code{self-alignment-interface} and/or
-the @code{side-position-interface} can be
-aligned to a previously placed object in a variety of ways. For a list of these objects, see
+Graphical objects which support the @code{self-alignment-interface}
+and/or the @code{side-position-interface} can be aligned to a previously
+placed object in a variety of ways. For a list of these objects, see
@rinternals{self-alignment-interface} and @rinternals{side-position-interface}.
All graphical objects have a reference point, a horizontal extent and a
vertical extent. The horizontal extent is a pair of numbers
giving the displacements from the reference point of the left and
-right edges, displacements to the left being negative. The
-vertical extent is a pair of numbers giving the displacement from
-the reference point to the bottom and top edges, displacements down
-being negative.
+right edges, displacements to the left being negative. The vertical
+extent is a pair of numbers giving the displacement from the reference
+point to the bottom and top edges, displacements down being negative.
An object's position on a staff is given by the values of the
@code{X-offset} and @code{Y-offset} properties. The value of
-@code{X-offset} gives the displacement from the x coordinate of
+@code{X-offset} gives the displacement from the X coordinate of
the reference point of the parent object, and the value of
@code{Y-offset} gives the displacement from the center line of the
-staff. The values of @code{X-offset} and
-@code{Y-offset} may be set directly or may be set to be calculated
-by procedures in order to achieve alignment with the parent object
-in several ways.
+staff. The values of @code{X-offset} and @code{Y-offset} may
+be set directly or may be set to be calculated by procedures in order
+to achieve alignment with the parent object.
@warning{Many objects have special positioning considerations which
cause any setting of @code{X-offset} or @code{Y-offset} to be
ignored or modified, even though the object supports the
-@code{self-alignment-interface}.}
+@code{self-alignment-interface}. Overriding the @code{X-offset}
+or @code{Y-offset} properties to a fixed value causes the respective
+@code{self-alignment} property to be disregarded.}
-For example, an accidental can be repositioned
-vertically by setting @code{Y-offset} but any changes to
-@code{X-offset} have no effect.
+For example, an accidental can be repositioned vertically by setting
+@code{Y-offset} but any changes to @code{X-offset} have no effect.
-Rehearsal marks may be aligned with
-breakable objects such as bar lines, clef symbols, time signature
-symbols and key signatures. There are special properties to be
-found in the @code{break-aligned-interface} for positioning rehearsal
-marks on such objects.
+Rehearsal marks may be aligned with breakable objects such as bar
+lines, clef symbols, time signature symbols and key signatures. There
+are special properties to be found in the @code{break-aligned-interface}
+for positioning rehearsal marks on such objects.
+
+@seealso
+@ref{Using the break-alignable-interface},
+@rextend{Callback functions}.
@menu
-* Setting @code{X-offset} and @code{Y-offset} directly::
-* Using the @code{side-position-interface}::
-* Using the @code{self-alignment-interface}::
-* Using the @code{break-alignable-interface}::
+* Setting X-offset and Y-offset directly::
+* Using the side-position-interface::
+* Using the self-alignment-interface::
+* Using the break-alignable-interface::
@end menu
-@node Setting @code{X-offset} and @code{Y-offset} directly
+@node Setting X-offset and Y-offset directly
@unnumberedsubsubsec Setting @code{X-offset} and @code{Y-offset} directly
Numerical values may be given to the @code{X-offset} and @code{Y-offset}
@c TODO write more
-@node Using the @code{side-position-interface}
+@node Using the side-position-interface
@unnumberedsubsubsec Using the @code{side-position-interface}
An object which supports the @code{side-position-interface} can be
@c TODO Add examples
-@node Using the @code{self-alignment-interface}
+@node Using the self-alignment-interface
@unnumberedsubsubsec Using the @code{self-alignment-interface}
@emph{Self-aligning objects horizontally}
real value, in units of half the total X extent of the
object. Negative values move the object to the right, positive
to the left. A value of @code{0} centers the object on the
-reference point of its parent, a value of @code{-1} aligns the
+reference point of its parent, a value of @w{@code{-1}} aligns the
left edge of the object on the reference point of its parent,
and a value of @code{1} aligns the right edge of the object on the
reference point of its parent. The symbols @code{LEFT},
-@code{CENTER} and @code{RIGHT} may be used instead of the values
-@code{-1, 0, 1} respectively.
+@code{CENTER}, and @code{RIGHT} may be used instead of the values
+@w{@code{-1}}, @code{0}, and @code{1}, respectively.
Normally the @code{\override} command would be used to modify the
value of @code{self-alignment-X}, but the @code{\tweak} command
This may make adjusting the value of some objects tricky.
The units are just half the vertical extent of the object, which
is usually quite small, so quite large numbers may be required.
-A value of @code{-1} aligns the lower edge of the object with
+A value of @w{@code{-1}} aligns the lower edge of the object with
the reference point of the parent object, a value of @code{0}
aligns the center of the object with the reference point of the
parent, and a value of @code{1} aligns the top edge of the object
with the reference point of the parent. The symbols @code{DOWN},
-@code{CENTER}, @code{UP} may be substituted for @code{-1, 0, 1}
-respectively.
+@code{CENTER}, and @code{UP} may be substituted for @w{@code{-1}},
+@code{0}, and @code{1}, respectively.
@emph{Self-aligning objects in both directions}
@c TODO The align-interface, BassFigureAlignment and VerticalAlignment
-@node Using the @code{break-alignable-interface}
+@node Using the break-alignable-interface
@unnumberedsubsubsec Using the @code{break-alignable-interface}
@cindex align to objects
centered above the object:
@lilypond[verbatim,quote,relative=1]
-e1
-% the RehearsalMark will be centered above the Clef
+% The rehearsal mark will be centered above the Clef
\override Score.RehearsalMark #'break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
-e
-% the RehearsalMark will be centered above the TimeSignature
+e1
+% The rehearsal mark will be centered above the Time Signature
\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e2.
+% The rehearsal mark will be centered above the Breath Mark
+\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
+\key a \major
+\clef treble
+\time 4/4
+e1
+\breathe
+\mark "↓"
@end lilypond
A list of possible target alignment objects may be specified. If
line would be.
@lilypond[verbatim,quote,relative=1]
-e1
-% the RehearsalMark will be centered above the Key Signature
+% The rehearsal mark will be centered above the Key Signature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
-e
-% the RehearsalMark will be centered above the Clef
+e1
+% The rehearsal mark will be centered above the Clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
-\key a \minor
+\key a \major
\clef bass
\mark "↓"
-e,
+gis,,1
+% The rehearsal mark will be centered above the Bar Line
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.explicitClefVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e''1
@end lilypond
The alignment of the rehearsal mark relative to the notation object
multiple staves, this setting should be done for all the staves.
@lilypond[verbatim,quote,relative=1]
-% The RehearsalMark will be centered above the KeySignature
+% The RehearsalMark will be centered above the Key Signature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e1
-% The RehearsalMark will be aligned with the left edge of the KeySignature
+% The RehearsalMark will be aligned with the left edge of the Key Signature
\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
\mark "↓"
\key a \major
-e
-% The RehearsalMark will be aligned with the right edge of the KeySignature
+e1
+% The RehearsalMark will be aligned with the right edge of the Key Signature
\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
\key a \major
\mark "↓"
-e
+e1
@end lilypond
-The rehearsal mark can also be offset to the right or left of the left edge
-by an arbitrary amount. The units are staff-spaces:
+The rehearsal mark can also be offset to the right or left of the left
+edge by an arbitrary amount. The units are staff-spaces:
@lilypond[verbatim,quote,relative=1]
-% The RehearsalMark will be aligned with the left edge of the KeySignature
+% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted right by 3.5 staff-spaces
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\once \override Score.KeySignature #'break-align-anchor = #3.5
\key a \major
\mark "↓"
-e
-% The RehearsalMark will be aligned with the left edge of the KeySignature
+e1
+% The RehearsalMark will be aligned with the left edge of the Key Signature
% and then shifted left by 2 staff-spaces
\once \override Score.KeySignature #'break-align-anchor = #-2
\key a \major
\mark "↓"
-e
+e1
@end lilypond
@cindex slurs, modifying
@cindex ties, modifying
-@cindex Bézier curves
-@cindex Bézier control points
+@cindex Bézier curves, control points
+@cindex control points, Bézier curves
Ties, slurs and phrasing slurs are drawn as third-order Bézier
curves. If the shape of the tie or slur which is calculated
@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{TieColumn} can be overridden to set start line and direction as
+required.
+@seealso
+Internals Reference:
+@rinternals{TieColumn}.
@node Using music functions
@c TODO -- add @seealso, etc. to these subsections
-Where tweaks need to be reused with different music expressions, it
-is often convenient to make the tweak part of a music function.
-In this section, we discuss only @emph{substitution} functions, where
-the object is to substitute a variable into a piece of LilyPond
-input code. Other more complex functions are described in
-@rextend{Music functions}.
+Where tweaks need to be reused with different music expressions,
+it is often convenient to make the tweak part of a @emph{music
+function}. In this section, we discuss only @emph{substitution}
+functions, where the object is to substitute a variable into a
+piece of LilyPond input code. Other more complex functions are
+described in @rextend{Music functions}.
@menu
* Substitution function syntax::
-* Common argument types::
* Substitution function examples::
@end menu
@example
function =
-#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
- (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
- #@{
- @emph{...music...}
- #@})
+#(define-music-function
+ (parser location @var{arg1} @var{arg2} @dots{})
+ (@var{type1?} @var{type2?} @dots{})
+ #@{
+ @var{@dots{}music@dots{}}
+ #@})
@end example
@noindent
where
@multitable @columnfractions .33 .66
-@item @var{vari} @tab @var{i}th variable
-@item @var{vari-type?} @tab type of @var{i}th variable
-@item @var{...music...} @tab normal LilyPond input, using
- variables as @code{#$var1}, etc.
-@end multitable
-
-Common variable types are described in @ref{Common argument types}.
-A more complete description of variable types is found in
-@rextend{Music function syntax}.
+@item @code{@var{argN}}
+@tab @var{n}th argument
-The @code{parser} and @code{location} arguments are mandatory,
-and are used in some advanced situations as described in
-@rextend{Music function syntax}. For substitution functions, just be sure
-to include them.
+@item @code{@var{typeN?}}
+@tab a scheme @emph{type predicate} for which @code{@var{argN}}
+must return @code{#t}.
-@seealso
+@item @code{@var{@dots{}music@dots{}}}
+@tab normal LilyPond input, using @code{$} to reference arguments
+(eg. @samp{$arg1}).
+@end multitable
-Notation Reference:
-@ref{Common argument types}.
-Extending LilyPond:
-@rextend{Music function syntax}.
+The @code{parser} and @code{location} arguments are mandatory, and
+are used in some advanced situations as described in the
+@q{Extending} manual (see @rextend{Music functions}). For
+substitution functions, just be sure to include them.
-@node Common argument types
-@subsection Common argument types
+The list of type predicates is also required. Some of the most
+common type predicates used in music functions are:
-In order to allow for error checking, the type of each argument
-that is passed to a music function must be defined. Some of the
-common types of variables are shown in the table below.
+@example
+boolean?
+cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:music?
+markup?
+number?
+pair?
+string?
+symbol?
+@end example
-The following input types may be used as variables in a music
-function. This list is not exhaustive;
-more information about possible variable types
-can be found in @rextend{Music function syntax}.
+@noindent
+For a list of available type predicates, see
+@ref{Predefined type predicates}. User-defined type predicates
+are also allowed.
-@multitable @columnfractions .33 .66
-@headitem Input type @tab @var{vari-type?} notation
-@item Integer @tab @code{integer?}
-@item Float (decimal number) @tab @code{number?}
-@item Text string @tab @code{string?}
-@item Markup @tab @code{markup?}
-@item Music expression @tab @code{ly:music?}
-@item A Scheme pair @tab @code{pair?}
-@end multitable
@seealso
-Extending LilyPond:
-@rextend {Music function syntax}.
+Notation Reference:
+@ref{Predefined type predicates}.
+
+Extending:
+@rextend{Music functions}.
Installed Files:
@file{lily/music-scheme.cc},
-@file{scm/c++.scm}.
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
@node Substitution function examples
@subsection Substitution function examples
-This section introduces some substitution function examples. These
-are not intended to be exhaustive, but rather to demonstrate some
-of the possibilities of simple substitution functions.
+This section introduces some substitution function examples.
+These are not intended to be exhaustive, but rather to demonstrate
+some of the possibilities of simple substitution functions.
In the first example, a function is defined that simplifies
setting the padding of a TextScript:
@lilypond[quote,verbatim,ragged-right]
-padText = #(define-music-function (parser location padding) (number?)
- #{
- \once \override TextScript #'padding = #$padding
- #})
+padText =
+#(define-music-function
+ (parser location padding)
+ (number?)
+ #{
+ \once \override TextScript #'padding = $padding
+ #})
\relative c''' {
c4^"piu mosso" b a b
In addition to numbers, we can use music expressions such
as notes for arguments to music functions:
-@lilypond[quote,verbatim,ragged-right]
-custosNote = #(define-music-function (parser location note)
- (ly:music?)
- #{
- \once \override Voice.NoteHead #'stencil =
- #ly:text-interface::print
- \once \override Voice.NoteHead #'text =
- \markup \musicglyph #"custodes.mensural.u0"
- \once \override Voice.Stem #'stencil = ##f
- $note
- #})
+@c TODO: use a better example (the music argument is redundant).
-{ c' d' e' f' \custosNote g' }
+@lilypond[quote,verbatim,ragged-right]
+custosNote =
+#(define-music-function
+ (parser location note)
+ (ly:music?)
+ #{
+ \once \override Voice.NoteHead #'stencil =
+ #ly:text-interface::print
+ \once \override Voice.NoteHead #'text =
+ \markup \musicglyph #"custodes.mensural.u0"
+ \once \override Voice.Stem #'stencil = ##f
+ $note
+ #})
+
+\relative c' { c4 d e f \custosNote g }
@end lilypond
Substitution functions with multiple arguments can be defined:
@lilypond[quote,verbatim,ragged-right]
-tempoPadded = #(define-music-function (parser location padding tempotext)
- (number? string?)
-#{
- \once \override Score.MetronomeMark #'padding = $padding
- \tempo \markup { \bold $tempotext }
-#})
+tempoPadded =
+#(define-music-function
+ (parser location padding tempotext)
+ (number? string?)
+ #{
+ \once \override Score.MetronomeMark #'padding = $padding
+ \tempo \markup { \bold $tempotext }
+ #})
\relative c'' {
\tempo \markup { "Low tempo" }
}
@end lilypond
-@seealso
-
+@c TODO: add appropriate @@ref's here.
projects / lilypond.git / blobdiff