Guide, node Updating translation committishes..
@end ignore
-@c \version "2.15.10"
+@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
* Context layout order::
@end menu
-
@seealso
Learning Manual:
@rlearning{Contexts and engravers}.
@c TODO Should this be Modifying engravers or Modifying contexts?
-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
+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_heads_engraver} and the @code{Staff} context contains a
-@code{Key_signature_engraver}.
+@code{Key_engraver}.
For a full a description of each plug-in, see
@ifhtml
contain it. This can give rise to unexpected new staves or scores.
@seealso
-Usage Manual:
+Application Usage:
@rprogram{An extra staff appears}.
Installed Files:
@file{ly/engraver-init.ly}.
-
@node Explaining the Internals Reference
@section Explaining the Internals Reference
-
@menu
* Navigating the program reference::
* Layout interfaces::
@end ignore
@seealso
-Internals:
+Internals Reference:
@rinternals{Backend},
@rinternals{All layout objects},
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet}.
-
@knownissues
-
The back-end is not very strict in type-checking object properties.
Cyclic references in Scheme values for properties can cause hangs
or crashes, or both.
-
@node The set command
@subsection The @code{@bs{}set} command
@end ifnothtml
@seealso
-
Internals Reference:
-
@rinternals{Tunable context properties}.
-
@cindex grob properties
@cindex properties, grob
@funindex \override
@end ignore
@seealso
-
Internals Reference:
@rinternals{Backend}
+
@node The tweak command
@subsection The @code{\tweak} command
in determining how to adjust the input to make a @code{\tweak}
apply.
-
@seealso
Learning Manual:
@rlearning{Tweaking methods}.
-Extending:
+Extending LilyPond:
@rextend{Displaying music expressions}.
-
@knownissues
-
@cindex tweaks in a variable
+
The @code{\tweak} command cannot be used inside a variable.
@cindex tweaks in lyrics
The @code{\tweak} command will apply to only the first of several
generated ties in a chord.
+
@node set versus override
@subsection @code{\set} vs. @code{\override}
@strong{The direction property}
-The position or direction of many layout objects is controlled
-by the @code{direction} property.
+The position or direction of many layout objects is controlled 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 @w{@code{-1}},
-meaning @qq{down} or @qq{below}. The symbols @code{UP} and
-@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
-exist to specify the direction. These are all of the form
+The value of the @code{direction} property may be 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 @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 exist to specify the
+direction. These are of the form
-@noindent
-@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}
+@example
+@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+@end example
@noindent
-where @code{xxxNeutral} means @qq{use the default direction}.
+where @code{\xxxNeutral} means @qq{use the default} direction.
See @rlearning{Within-staff objects}.
-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 @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.
+In a few cases, arpeggio for example, the value of the @code{direction}
+property can specify whether the object is to be placed to the right or
+left of the parent. In 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.
@ignore
These all have side-axis set to #X
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)
c2( c)
@end lilypond
+In polyphonic music, it is generally better to specify an explicit
+@code{voice} than change an object's direction. For more information.
+See @ref{Multiple voices}.
+
+@seealso
+Learning Manual:
+@rlearning{Within-staff objects}.
+
+Notation Reference:
+@ref{Multiple voices}.
+
@node Distances and measurements
@subsection Distances and measurements
@code{staff-space}. For an explanation and an example of its use,
see @rlearning{Length and thickness of objects}.
-
@seealso
Learning Manual:
@rlearning{Length and thickness of objects}.
\startTextSpan with \stopTextSpan, nor is it necessary to close
hairpins with @code{\!}.
-
@seealso
Internals Reference:
@rinternals{TextSpanner},
property controls both the clef symbol and any octavation symbol
associated with it.
-
@seealso
Learning Manual:
-@rlearning{Visibility and color of objects}
+@rlearning{Visibility and color of objects}.
@node Line styles
* Vertical grouping of grobs::
* Modifying stencils::
* Modifying shapes::
+* Unpure-pure containers::
@end menu
-
@seealso
Learning Manual:
@rlearning{Tweaking output},
@ref{Explaining the Internals Reference},
@ref{Modifying properties}.
+Extending LilyPond:
+@rextend{Interfaces for programmers}.
+
Installed Files:
@file{scm/define-grobs.scm}.
Snippets:
@rlsr{Tweaks and overrides}.
-Extending:
-@rextend{Interfaces for programmers}.
-
Internals Reference:
@rinternals{All layout objects}.
for positioning rehearsal marks on such objects.
@seealso
-@ref{Using the break-alignable-interface},
+Notation Reference:
+@ref{Using the break-alignable-interface}.
+
+Extending LilyPond:
@rextend{Callback functions}.
@menu
@c TODO Add inserting Postscript or ref to later
-
@seealso
Notation Reference:
@ref{Graphic notation inside markup},
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
@section Using music functions
@ref{Predefined type predicates}. User-defined type predicates
are also allowed.
-
@seealso
-
Notation Reference:
@ref{Predefined type predicates}.
-Extending:
+Extending Lilypond:
@rextend{Music functions}.
Installed Files:
(number? string?)
#{
\once \override Score.MetronomeMark #'padding = #padding
- \tempo \markup { \bold $tempotext }
+ \tempo \markup { \bold #tempotext }
#})
\relative c'' {
projects / lilypond.git / blobdiff