Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.42"
+@c \version "2.15.20"
@node Changing defaults
@chapter Changing defaults
options available in LilyPond. It is written as a HTML document,
which is available
@c leave the @uref as one long line.
-@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/internals/,on@/-line},
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
-@code{#}.@footnote{@rextend{Scheme tutorial}, contains a short tutorial
-on entering numbers, lists, strings, and symbols in Scheme.}
+introduced in a @file{.ly} file with the hash
+mark@tie{}@code{#}.@footnote{@rextend{Scheme tutorial}, contains a
+short tutorial on entering numbers, lists, strings, and symbols in
+Scheme.}
@menu
* Modifying context plug-ins::
* Changing context default settings::
* Defining new contexts::
-* Aligning contexts::
+* Context layout order::
@end menu
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
Modifications can be made to the @code{Score} context or all
@code{Voice} contexts in a similar way.
-@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.
+Context changes can be placed in a variable and applied to a
+@code{\context} definition by prepending the modification with
+@code{\with}:
+@lilypond[quote,verbatim]
+blubb = \with {
+ fontSize = #-4
+ \override Stem #'thickness = #4.0
+ \remove "Time_signature_engraver"
+}
-The @code{\Staff \RemoveEmptyStaves} will overwrite your current
-@code{\Staff} settings. If you wish to change the defaults for a
-staff which uses @code{\Staff \RemoveEmptyStaves}, you must do so
-after calling @code{\Staff \RemoveEmptyStaves}, ie
+bla = \with {
+ fontSize = #3
+ \override Stem #'thickness = #-2.0
+}
-@example
-\layout @{
- \context @{
- \Staff \RemoveEmptyStaves
+melody = \relative c'' {
+ a4 a a a |
+ a4 a a a |
+}
- \override Stem #'thickness = #4.0
- @}
-@}
-@end example
+\score {
+ <<
+ \new Staff <<
+ \melody
+ s1*0^"Small, thicker stems, no time signature"
+ >>
+ \new Staff \bla <<
+ \melody
+ s1*0^"Different"
+ >>
+ >>
+ \layout {
+ \context {
+ \Staff
+ \blubb
+ }
+ }
+}
+@end lilypond
@c TODO: add \with in here.
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
}
\context { \Staff
@example
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+\override Flag #'transparent = ##t
@end example
All these plug-ins have to cooperate, and this is achieved with a
squashedPosition = #0
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
+ \override Flag #'transparent = ##t
\alias Voice
@}
@end example
@end example
-@node Aligning contexts
-@subsection Aligning contexts
+@node Context layout order
+@subsection Context layout order
-New contexts may be aligned above or below existing contexts. This
-could be useful in setting up a vocal staff (@rlearning{Vocal ensembles}) and
-in ossia,
+@cindex contexts, layout order
+@funindex \accepts
+@funindex \denies
-@c TODO Better example needed. Ref LM, and expand on it.
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered in the input file. When
+contexts are nested, the outer context will include inner nested
+contexts as specified in the input file, provided the inner contexts
+are included in the outer context's @qq{accepts} list. Nested
+contexts which are not included in the outer context's @qq{accepts}
+list will be repositioned below the outer context rather than nested
+within it.
-@cindex ossia
-@funindex alignAboveContext
-@funindex alignBelowContext
+The @qq{accepts} list of a context can be changed with the
+@code{\accepts} and @code{\denies} commands. @code{\accepts} adds a
+context to the @qq{accepts} list and @code{\denies} removes a context
+from the list. For example, it would not normally be desirable for
+chord names to be nested within a @code{Staff} context, so the
+@code{ChordNames} context is not included by default in the @qq{accepts}
+list of the @code{Staff} context, but if this were to be required it can
+be done:
-@lilypond[quote,ragged-right]
-ossia = { f4 f f f }
-\score{
- \relative c' \new Staff = "main" {
- c4 c c c
- <<
- \new Staff \with { alignAboveContext = #"main" } \ossia
- { d8 f d f d f d f }
- >>
+@lilypond[verbatim,quote]
+\score {
+ \new Staff {
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
}
@end lilypond
-@cindex nested contexts
-@cindex contexts, nested
-
-@funindex \accepts
-@funindex \denies
-
-Contexts like @code{PianoStaff} can contain other contexts
-nested within them. Contexts which are acceptable for nesting
-are defined by the @qq{accepts} list of a context. Contexts
-which are not in this list are placed below the outer context
-in the printed score.
-For example, the @code{PianoStaff} context is defined by default
-to accept @code{Staff} and @code{FiguredBass} contexts within
-it, but not (for example) a @code{Lyrics} context. So in the
-following structure the lyrics are placed below the piano staff
-rather than between the two staves:
-
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
+@lilypond[verbatim,quote]
+\score {
\new Staff {
- \clef "bass"
- { c,1 }
+ c' d' e' f'
+ \chords { d1:m7 b1:min7.5- }
}
->>
+ \layout {
+ \context {
+ \Staff
+ \accepts "ChordNames"
+ }
+ }
+}
@end lilypond
-The @qq{accepts} list of a context can be modified to include
-additional nested contexts, so if we wanted the lyrics to appear
-between the two staves we could use:
+@code{\denies} is mainly used when a new context is being based on
+another, but the required nesting differs. For example, the
+@code{VaticanaStaff} context is based on the @code{Staff} context, but
+with the @code{VaticanaVoice} context substituted for the @code{Voice}
+context in the @qq{accepts} list.
+
+Note that a context will be silently created implicitly if a command
+is encountered when there is no suitable context available to
+contain it. This can give rise to unexpected new staves or scores.
+
+@seealso
+Usage Manual:
+@rprogram{An extra staff appears}.
+
+Installed Files:
+@file{ly/engraver-init.ly}.
-@lilypond[verbatim,quote,relative=1]
-\new PianoStaff \with { \accepts Lyrics }
-<<
- \new Staff { e4 d c2 }
- \addlyrics { Three blind mice }
- \new Staff {
- \clef "bass"
- { c,1 }
- }
->>
-@end lilypond
-The opposite of @code{\accepts} is @code{\denies}; this removes a
-context from the @qq{accepts} list.
@node Explaining the Internals Reference
@section Explaining the Internals Reference
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
@end example
@var{value} is a Scheme object, which is why it must be preceded by
-the @code{#} character.
+the @code{#}@tie{}character.
Contexts properties are usually named in
@code{studlyCaps}. They mostly control the translation from
@cindex internal documentation
For many properties, regardless of the data type of the property, setting the
-property to false ( @code{##f} ) will result in turning it off, causing
+property to false (@code{#f}) will result in turning it off, causing
LilyPond to ignore that property entirely. This is particularly useful for
turning off grob properties which may otherwise be causing problems.
@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
@menu
* Input modes::
* Direction and placement::
-* Context layout order::
* Distances and measurements::
* Staff symbol properties::
* Spanners::
@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.
TrillPitchGroup - not tried
@end ignore
-These indications affect all notes until they are cancelled.
+These indications affect all notes until they are canceled.
@lilypond[verbatim,quote,relative=2]
c2( c)
@end lilypond
-@node Context layout order
-@subsection Context layout order
-
-@cindex contexts, layout order
-
-Contexts are normally positioned in a system from top to bottom
-in the order in which they are encountered in the input file. When
-contexts are nested, the outer context will include inner nested
-contexts as specified in the input file, provided the inner contexts
-are included in the outer context's @qq{accepts} list. Nested
-contexts which are not included in the outer context's @qq{accepts}
-list will be repositioned below the outer context rather than nested
-within it.
-
-Note that a context will be silently created implicitly if a command
-is encountered when there is no suitable context available to
-contain it. This can give rise to unexpected new staves or scores.
-
-The default order in which contexts are laid out and the
-@qq{accepts} list can be changed, see @ref{Aligning contexts}.
-
-@seealso
-Usage Manual:
-@rprogram{An extra staff appears}.
-
-
@node Distances and measurements
@subsection Distances and measurements
@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.
@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.
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
@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
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}.
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Unpure-pure containers::
@end menu
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}
@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}.
+
+@cindex Scheme, pure containers
+@cindex Scheme, unpure containers
+@cindex pure containers, Scheme
+@cindex unpure containers, Scheme
+@cindex horizontal spacing, overriding
+
+@node Unpure-pure containers
+@subsection Unpure-pure containers
+
+Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
+calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
+Scheme function instead of a literal (i.e. a number or pair).
+
+For certain grobs, the @code{Y-extent} is based on the @code{stencil}
+property, overriding the stencil property of one of these will
+require an additional @code{Y-extent} override with an unpure-pure
+container. When a function overrides a @code{Y-offset} and/or
+@code{Y-extent} it is assumed that this will trigger line breaking
+calculations too early during compilation. So the function is not
+evaluated at all (usually returning a value of @samp{0} or
+@samp{'(0 . 0)}) which can result in collisions. A @q{pure} function
+will not affect properties, objects or grob suicides and therefore will
+always have its Y-axis-related evaluated correctly.
+
+Currently, there are about thirty functions that are already considered
+@q{pure} and Unpure-pure containers are a way to set functions not on
+this list as @q{pure}. The @q{pure} function is evaluated @emph{before}
+any line-breaking and so the horizontal spacing can be adjusted
+@q{in time}. The @q{unpure} function is then evaluated @emph{after}
+line breaking.
+
+@warning{As it is difficult to always know which functions are on this
+list we recommend that any @q{pure} functions you create do not use
+@code{Beam} or @code{VerticalAlignment} grobs.}
+
+An unpure-pure container is constructed as follows;
+
+@code{(ly:make-unpure-pure-container f0 f1)}
+
+where @code{f0} is a function taking @var{n} arguments (@var{n >= 1})
+and the first argument must always be the grob. This is the function
+that gives the actual result. @var{f1} is the function being labeled
+as @q{pure} that takes @var{n + 2} arguments. Again, the first argument
+must always still be the grob but the second and third are @q{start}
+and @q{end} arguments.
+
+@var{start} and @var{end} are, for all intents and purposes, dummy
+values that only matter for @code{Spanners} (i.e @code{Hairpin} or
+@code{Beam}), that can return different height estimations based on a
+starting and ending column.
+
+The rest are the other arguments to the first function (which
+may be none if @var{n = 1}).
+
+The results of the second function are used as an approximation of the
+value needed which is then used by the first function to get the real
+value which is then used for fine-tuning much later during the spacing
+process.
+
+@lilypond[verbatim,quote,ragged-right]
+#(define (square-line-circle-space grob)
+(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
+ (notename (ly:pitch-notename pitch)))
+ (if (= 0 (modulo notename 2))
+ (make-circle-stencil 0.5 0.0 #t)
+ (make-filled-box-stencil '(0 . 1.0)
+ '(-0.5 . 0.5)))))
+
+squareLineCircleSpace = {
+ \override NoteHead #'stencil = #square-line-circle-space
+}
+
+smartSquareLineCircleSpace = {
+ \squareLineCircleSpace
+ \override NoteHead #'Y-extent =
+ #(ly:make-unpure-pure-container
+ ly:grob::stencil-height
+ (lambda (grob start end) (ly:grob::stencil-height grob)))
+}
+
+\new Voice \with { \remove "Stem_engraver" }
+\relative c'' {
+ \squareLineCircleSpace
+ cis4 ces cisis c
+ \smartSquareLineCircleSpace
+ cis4 ces cisis c
+}
+@end lilypond
+
+In the first measure, without the unpure-pure container, the spacing
+engine does not know the width of the note head and lets it collide with
+the accidentals. In the second measure, with unpure-pure containers,
+the spacing engine knows the width of the note heads and avoids the
+collision by lengthening the line accordingly.
+
+Usually for simple calculations nearly-identical functions for both the
+@q{unpure} and @q{pure} parts can be used, by only changing the number
+of arguments passed to, and the scope of, the function.
+@warning{If a function is labeled as @q{pure} and it turns out not to
+be, the results can be unexpected.}
@node Using music functions
must return @code{#t}.
@item @code{@var{@dots{}music@dots{}}}
-@tab normal LilyPond input, using @code{$} to reference arguments
-(eg. @samp{$arg1}).
+@tab normal LilyPond input, using @code{$} (in places where only
+Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
+value or music function argument) to reference arguments
+(eg. @samp{#arg1}).
@end multitable
-
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
@example
boolean?
cheap-list? @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:duration?
ly:music?
+ly:pitch?
markup?
number?
pair?
(parser location padding)
(number?)
#{
- \once \override TextScript #'padding = $padding
+ \once \override TextScript #'padding = #padding
#})
\relative c''' {
(parser location padding tempotext)
(number? string?)
#{
- \once \override Score.MetronomeMark #'padding = $padding
- \tempo \markup { \bold $tempotext }
+ \once \override Score.MetronomeMark #'padding = #padding
+ \tempo \markup { \bold #tempotext }
#})
\relative c'' {
}
@end lilypond
-@seealso
-
-TODO: add missing @@ref's here.
+@c TODO: add appropriate @@ref's here.
projects / lilypond.git / blobdiff