]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/changing-defaults.itely
NR: General tidy up - @seealso @knownissue spacing
[lilypond.git] / Documentation / notation / changing-defaults.itely
index 7a294693fee8f31043d3e37acb2d209d2db1f887..235d5c615846b7fca123cf81fe337b9417f65c4b 100644 (file)
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.13.42"
+@c \version "2.15.20"
 
 @node Changing defaults
 @chapter Changing defaults
@@ -30,15 +30,16 @@ 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
 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
@@ -63,10 +64,9 @@ This section describes what contexts are, and how to modify them.
 * Modifying context plug-ins::
 * Changing context default settings::
 * Defining new contexts::
-* Aligning contexts::
+* Context layout order::
 @end menu
 
-
 @seealso
 Learning Manual:
 @rlearning{Contexts and engravers}.
@@ -723,25 +723,45 @@ this score block.
 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.
 
@@ -786,6 +806,7 @@ to indicate improvisation in jazz pieces,
   squashedPosition = #0
   \override NoteHead #'style = #'slash
   \override Stem #'transparent = ##t
+  \override Flag #'transparent = ##t
   \alias Voice
 }
 \context { \Staff
@@ -853,6 +874,7 @@ The notes look like a slash, and have no stem,
 @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
@@ -875,6 +897,7 @@ Put together, we get
   squashedPosition = #0
   \override NoteHead #'style = #'slash
   \override Stem #'transparent = ##t
+  \override Flag #'transparent = ##t
   \alias Voice
 @}
 @end example
@@ -926,84 +949,76 @@ Then the output at the start of this subsection can be entered as
 @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.
 
-@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
+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
+Application Usage:
+@rprogram{An extra staff appears}.
+
+Installed Files:
+@file{ly/engraver-init.ly}.
 
-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
 
-
 @menu
 * Navigating the program reference::
 * Layout interfaces::
@@ -1043,7 +1058,7 @@ This fragment points to two parts of the program reference: a page
 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
@@ -1456,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
 
@@ -1488,7 +1500,7 @@ command, which has the following syntax:
 @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
@@ -1606,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
@@ -1765,7 +1774,7 @@ properties.  To tweak those, use commands in the form
 @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.
 
@@ -1774,10 +1783,10 @@ and the program reference.
 @end ignore
 
 @seealso
-
 Internals Reference:
 @rinternals{Backend}
 
+
 @node The tweak command
 @subsection The @code{\tweak} command
 
@@ -1938,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
@@ -1961,10 +1968,11 @@ 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}
 
-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
@@ -2098,7 +2106,6 @@ modified by completely re-defining them as alists.}
 @menu
 * Input modes::
 * Direction and placement::
-* Context layout order::
 * Distances and measurements::
 * Staff symbol properties::
 * Spanners::
@@ -2242,8 +2249,8 @@ but a direction indicator is @strong{always} required before
 @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:
@@ -2261,9 +2268,9 @@ 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 @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
@@ -2279,7 +2286,7 @@ 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 @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.
 
@@ -2292,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)
@@ -2304,32 +2311,6 @@ 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
 
@@ -2378,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}.
@@ -2636,7 +2616,7 @@ it is hardcoded to 0.
 
 @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.
 
@@ -2681,7 +2661,7 @@ c4^\startTextSpan c c c \stopTextSpan
 @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.
@@ -2714,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},
@@ -2824,7 +2803,7 @@ In the example above the white clef, with a default @code{layer}
 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
@@ -2916,7 +2895,7 @@ default setting of this property:
 @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
@@ -3047,20 +3026,18 @@ occur only at explicit @code{\bar} commands.
 @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
 associated with it.
 
-
 @seealso
 Learning Manual:
-@rlearning{Visibility and color of objects}
+@rlearning{Visibility and color of objects}.
 
 
 @node Line styles
@@ -3104,7 +3081,7 @@ e2 \glissando f
 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}.
 
@@ -3187,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},
@@ -3199,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}.
 
@@ -3252,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
@@ -3339,12 +3319,12 @@ the @code{self-alignment-X} property, provided the object's
 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
@@ -3373,13 +3353,13 @@ value of @code{Y-offset} is just one variable taken into account.
 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}
 
@@ -3602,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},
@@ -3623,8 +3602,8 @@ Notation Reference:
 
 @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
@@ -3649,7 +3628,7 @@ where @code{\tieDown} would not help.
 
 @lilypond[verbatim,quote,relative=1]
 <<
-  { e1 ~ e }
+  { e1~ e }
 \\
   { r4 <g c,> <g c,> <g c,> }
 >>
@@ -3682,23 +3661,127 @@ to which the start of the tie (or slur) is attached.
   {
     \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,> }
+  { 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
@@ -3746,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
@@ -3762,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?
@@ -3775,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:
@@ -3806,7 +3890,7 @@ padText =
      (parser location padding)
      (number?)
    #{
-     \once \override TextScript #'padding = $padding
+     \once \override TextScript #'padding = #padding
    #})
 
 \relative c''' {
@@ -3848,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'' {
@@ -3860,6 +3944,4 @@ tempoPadded =
 }
 @end lilypond
 
-@seealso
-
-TODO: add missing @@ref's here.
+@c TODO: add appropriate @@ref's here.