X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=235d5c615846b7fca123cf81fe337b9417f65c4b;hb=80340bdefc128536c79733d8c6f3467d91b01f72;hp=34f73d15baf860d6a03d6eb647901f68b20fe76e;hpb=3b8f430efd506ccd6ae8235be0f08468c0da937d;p=lilypond.git

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 34f73d15ba..235d5c6158 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.15.10"
+@c \version "2.15.20"
 
 @node Changing defaults
 @chapter Changing defaults
@@ -30,7 +30,7 @@ Reference}.  That manual lists all the variables, functions and
 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
@@ -67,7 +67,6 @@ This section describes what contexts are, and how to modify them.
 * Context layout order::
 @end menu
 
-
 @seealso
 Learning Manual:
 @rlearning{Contexts and engravers}.
@@ -1010,18 +1009,16 @@ 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:
+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::
@@ -1474,22 +1471,19 @@ such as
 @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
 
@@ -1624,12 +1618,9 @@ Translation @expansion{} Tunable context properties.
 @end ifnothtml
 
 @seealso
-
 Internals Reference:
-
 @rinternals{Tunable context properties}.
 
-
 @cindex grob properties
 @cindex properties, grob
 @funindex \override
@@ -1792,10 +1783,10 @@ and the program reference.
 @end ignore
 
 @seealso
-
 Internals Reference:
 @rinternals{Backend}
 
+
 @node The tweak command
 @subsection The @code{\tweak} command
 
@@ -1956,18 +1947,16 @@ determining what may be modified by a @code{\tweak} command, or
 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
@@ -1979,6 +1968,7 @@ The @code{\tweak} commands cannot be used in @code{\lyricmode}.
 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}
 
@@ -2309,7 +2299,7 @@ TrillPitchAccidental - not tried
 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)
@@ -2369,7 +2359,6 @@ convert from a font size change to the equivalent change in
 @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}.
@@ -2705,7 +2694,6 @@ When using @code{\endSpanners} it is not necessary to close
 \startTextSpan with \stopTextSpan, nor is it necessary to close
 hairpins with @code{\!}.
 
-
 @seealso
 Internals Reference:
 @rinternals{TextSpanner},
@@ -3047,10 +3035,9 @@ For explicit clef changes, the @code{explicitClefVisibility}
 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
@@ -3177,9 +3164,9 @@ appearance of the printed score.
 * Vertical grouping of grobs::
 * Modifying stencils::
 * Modifying shapes::
+* Unpure-pure containers::
 @end menu
 
-
 @seealso
 Learning Manual:
 @rlearning{Tweaking output},
@@ -3189,15 +3176,15 @@ Notation Reference:
 @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}.
 
@@ -3242,7 +3229,10 @@ 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},
+Internals Reference:
+@ref{Using the break-alignable-interface}.
+
+Exending LilyPond:
 @rextend{Callback functions}.
 
 @menu
@@ -3592,7 +3582,6 @@ Any of the glyphs in the feta Font can be supplied to the
 
 @c TODO Add inserting Postscript or ref to later
 
-
 @seealso
 Notation Reference:
 @ref{Graphic notation inside markup},
@@ -3691,6 +3680,109 @@ required.
 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
@@ -3737,11 +3829,12 @@ where
 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
@@ -3753,7 +3846,9 @@ common type predicates used in music functions are:
 @example
 boolean?
 cheap-list?  @emph{(use instead of }@q{list?}@emph{ for faster processing)}
+ly:duration?
 ly:music?
+ly:pitch?
 markup?
 number?
 pair?
@@ -3766,13 +3861,11 @@ For a list of available type predicates, see
 @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:
@@ -3797,7 +3890,7 @@ padText =
      (parser location padding)
      (number?)
    #{
-     \once \override TextScript #'padding = $padding
+     \once \override TextScript #'padding = #padding
    #})
 
 \relative c''' {
@@ -3839,8 +3932,8 @@ tempoPadded =
      (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'' {