X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fchanging-defaults.itely;h=ace19d19fb5c51bf893c8743b4cf6d51cd42d1d7;hb=26a079ca2393d053315ef8dbef626c897dc9645a;hp=98163ce3e832905ababb6389b77f66ff87637a16;hpb=a42aaa559b71ce5776795fa11a7e1df9110d85b7;p=lilypond.git

diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely
index 98163ce3e8..ace19d19fb 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.20"
+@c \version "2.16.0"
 
 @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}.
@@ -565,12 +564,11 @@ words = \lyricmode { These words fol -- low the mel -- o -- dy }
 
 @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
@@ -674,98 +672,335 @@ time signature.
 
 @knownissues
 
-Usually the order in which the engravers are specified
-does not matter, but in a few special cases the order
-is important, for example where one engraver writes
-a property and another reads it, or where one engraver
-creates a grob and another must process it.  The order in
-which the engravers are specified is the order in which
-they are called to carry out their processing.
+The order in which the engravers are specified is the order in
+which they are called to carry out their processing.  Usually the
+order in which the engravers are specified does not matter, but in
+a few special cases the order is important, for example where one
+engraver writes a property and another reads it, or where one
+engraver creates a grob and another must process it.
+
+The following orderings are important:
+
+@itemize
+@item
+the @code{Bar_engraver} must normally be first,
+
+@item
+the @code{New_fingering_engraver} must come before the
+@code{Script_column_engraver},
+
+@item
+the @code{Timing_translator} must come before the
+@code{Bar_number_engraver}.
+
+@end itemize
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.
 
-The following orderings are important: the
-@code{Bar_engraver} must normally be first, and
-the @code{New_fingering_engraver} must come before
-the @code{Script_column_engraver}.  There may be others
-with ordering dependencies.
 
 @node Changing context default settings
 @subsection Changing context default settings
 
+@cindex default context properties, changing
+@cindex context properties, changing defaults
+
+Context and grob properties can be changed with @code{\set}
+and @code{\override} commands, as described in
+@ref{Modifying properties}.  These commands create music events,
+making the changes take effect at the point in time the music
+is being processed.
+
+In contrast, this section explains how to change the @emph{default}
+values of context and grob properties at the time the context is
+created.  There are two ways of doing this.  One modifies the default
+values in all contexts of a particular type, the other modifies the
+default values in just one particular instance of a context.
+
+@menu
+* Changing all contexts of the same type::
+* Changing just one specific context::
+* Order of precedence::
+@end menu
+
+@node Changing all contexts of the same type
+@unnumberedsubsubsec Changing all contexts of the same type
+
+@cindex \context in \layout block
+@funindex \context
+@funindex \layout
+
 The context settings which are to be used by default in
-@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
-in a @code{\layout} block, as illustrated in the following example.
+@code{Score}, @code{Staff}, @code{Voice} and other contexts may be
+specified in a @code{\context} block within any @code{\layout} block.
 The @code{\layout} block should be placed within the @code{\score}
-block to which it is to apply, but outside any music.
+block to which it is to apply, after the music.
+
+@example
+\layout @{
+  \context @{
+    \Voice
+    [context settings for all Voice contexts]
+  @}
+  \context @{
+    \Staff
+    [context settings for all Staff contexts]
+  @}
+@}
+@end example
+
+The following types of settings may be specified:
 
-Note that the @code{\set} command itself and the context must be
-omitted when the context default values are specified in this way:
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
 
 @lilypond[quote,verbatim]
 \score {
   \relative c'' {
-    a4^"Really small, thicker stems, no time signature" a a a
-    a a a a
+    a4^"Thicker stems" a a a
+    a4 a a\ff a
   }
   \layout {
     \context {
       \Staff
-      fontSize = #-4
       \override Stem #'thickness = #4.0
-      \remove "Time_signature_engraver"
     }
   }
 }
 @end lilypond
 
-In this example, the @code{\Staff} command specifies that the
-subsequent specifications are to be applied to all staves within
-this score block.
-
-Modifications can be made to the @code{Score} context or all
-@code{Voice} contexts in a similar way.
+@item
+Directly setting a context property
 
-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"
+\score {
+  \relative c'' {
+    a4^"Smaller font" a a a
+    a4 a a\ff a
+  }
+  \layout {
+    \context {
+      \Staff
+      fontSize = #-4
+    }
+  }
 }
+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp} or a music
+expression like @code{\accidentalStyle "dodecaphonic"}
 
-bla = \with {
-  fontSize = #3
-  \override Stem #'thickness = #-2.0
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    a4^"Dynamics above" a a a
+    a4 a a\ff a
+  }
+  \layout {
+    \context {
+      \Voice
+      \dynamicUp
+    }
+    \context {
+      \Staff
+      \accidentalStyle "dodecaphonic"
+    }
+  }
 }
+@end lilypond
 
-melody = \relative c'' {
-  a4 a a a |
-  a4 a a a |
+@item
+A user-defined variable containing a @code{\with} block; for details
+of the @code{\with} block see
+@ref{Changing just one specific context}.
+
+@lilypond[quote,verbatim]
+StaffDefaults = \with {
+  fontSize = #-4
 }
 
 \score {
-  <<
-    \new Staff <<
-      \melody
-      s1*0^"Small, thicker stems, no time signature"
-    >>
-    \new Staff \bla <<
-      \melody
-      s1*0^"Different"
-    >>
-  >>
+  \new Staff {
+    \relative c'' {
+      a4^"Smaller font" a a a
+      a4 a a a
+    }
+  }
   \layout {
     \context {
       \Staff
-      \blubb
+      \StaffDefaults
+    }
+  }
+}
+@end lilypond
+
+@end itemize
+
+Property-setting commands can be placed in a @code{\layout} block
+without being enclosed in a @code{\context} block.  Such settings
+are equivalent to including the same property-setting commands at
+the start of every context of the type specified.  If no context
+is specified @emph{every} bottom-level context is affected, see
+@ref{Bottom-level contexts - voices}.  The syntax of a
+property-setting command in a @code{\layout} block is the same as
+the same command written in the music stream.
+
+@lilypond[quote,verbatim]
+\score {
+  \new Staff {
+    \relative c'' {
+      a4^"Smaller font" a a a
+      a4 a a a
+    }
+  }
+  \layout {
+    \accidentalStyle "dodecaphonic"
+    \set fontSize = #-4
+    \override Voice.Stem #'thickness = #4.0
+  }
+}
+@end lilypond
+
+
+@node Changing just one specific context
+@unnumberedsubsubsec Changing just one specific context
+
+@cindex \with
+@funindex \with
+
+The context properties of just one specific context instance can be
+changed in a @code{\with} block.  All other context instances of the
+same type retain the default settings built into LilyPond and modified
+by any @code{\layout} block within scope.  The @code{\with} block
+must be placed immediately after the @code{\new} @var{context-type}
+command:
+
+@example
+\new Staff
+\with @{
+  [context settings for this context instance only]
+@} @{
+...
+@}
+@end example
+
+The following types of settings may be specified:
+
+@itemize
+@item
+An @code{\override} command, but with the context name omitted
+
+@lilypond[quote,verbatim]
+\score {
+  \new Staff {
+    \new Voice
+    \with {
+      \override Stem #'thickness = #4.0
+    }
+    {
+      \relative c'' {
+        a4^"Thick stems" a a a
+        a4 a a a
+      }
     }
   }
 }
 @end lilypond
 
-@c TODO: add \with in here.
+@item
+Directly setting a context property
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \relative c'' {
+        a4^"Default font" a a a
+        a4 a a a
+      }
+    }
+    \new Staff
+    \with {
+      fontSize = #-4
+    } {
+      \relative c'' {
+        a4^"Smaller font" a a a
+        a4 a a a
+      }
+    }
+  >>
+}
+@end lilypond
+
+@item
+A predefined command such as @code{\dynamicUp}
+
+@lilypond[quote,verbatim]
+\score {
+  <<
+    \new Staff {
+      \new Voice {
+        \relative c'' {
+          a4^"Dynamics below" a a a
+          a4 a a\ff a
+        }
+      }
+    }
+    \new Staff
+    \with { \accidentalStyle "dodecaphonic" }
+    {
+      \new Voice
+      \with { \dynamicUp }
+      {
+        \relative c'' {
+          a4^"Dynamics above" a a a
+          a4 a a\ff a
+        }
+      }
+    }
+  >>
+}
+@end lilypond
+
+@end itemize
+
+@node Order of precedence
+@unnumberedsubsubsec Order of precedence
+
+The value of a property which applies at a particular time is
+determined as follows:
+
+@itemize
+@item
+if an @code{\override} or @code{\set} command in the input stream is
+in effect that value is used,
+
+@item
+otherwise the default value taken from a @code{\with} statement
+on the context initiation statement is used,
+
+@item
+otherwise the default value taken from the most recent appropriate
+@code{\context} block in the @code{\layout} blocks is used,
+
+@item
+otherwise the LilyPond built-in default is used.
+@end itemize
+
+@seealso
+Learning Manual:
+@rlearning{Modifying context properties}.
 
+Notation Reference:
+@ref{Contexts explained},
+@ref{Bottom-level contexts - voices},
+@ref{The set command},
+@ref{The override command},
+@ref{The \layout block}.
 
 
 @node Defining new contexts
@@ -1009,19 +1244,53 @@ 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.
 
+@cindex alignAboveContext
+@cindex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
+
+Sometimes a context is required to exist for just a brief period, a
+good example being the staff context for an ossia.  This is usually
+achieved by introducing the context definition at the appropriate
+place in parallel with corresponding section of the main music.
+By default, the temporary context will be placed below all the
+existing contexts.  To reposition it above the context called
+@qq{main}, it should be defined like this:
+
+@example
+@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+@end example
+
+A similar situation arises when positioning a temporary lyrics
+context within a multi-staved layout such as a @code{ChoirStaff},
+for example, when adding a second verse to a repeated section.
+By default the temporary lyrics context will be placed beneath the
+lower staves.  By defining the temporary lyrics context with
+@code{alignBelowContext} it can be positioned correctly beneath
+the (named) lyrics context containing the first verse.
+
+Examples showing this repositioning of temporary contexts can be
+found elsewhere --- see @rlearning{Nesting music expressions},
+@ref{Modifying single staves} and @ref{Techniques specific to lyrics}.
+
 @seealso
-Usage Manual:
+Learning Manual:
+@rlearning{Nesting music expressions}.
+
+Notation Reference:
+@ref{Modifying single staves},
+@ref{Techniques specific to lyrics}.
+
+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 +1743,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 +1890,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 +2055,10 @@ and the program reference.
 @end ignore
 
 @seealso
-
 Internals Reference:
 @rinternals{Backend}
 
+
 @node The tweak command
 @subsection The @code{\tweak} command
 
@@ -1811,11 +2074,12 @@ accomplished with the @code{\tweak} command, which has the following
 syntax:
 
 @example
-\tweak #'@code{grob-property} #@code{value}
+\tweak @var{layout-object} #'@var{grob-property} @var{value}
 @end example
 
-The @code{\tweak} command applies to the object that immediately
-follows @code{value} in the music stream.
+Specifying @var{layout-object} is optional.
+The @code{\tweak} command applies to the music object that immediately
+follows @var{value} in the music stream.
 
 @ignore
 In some cases, it is possible to take a short-cut for tuning
@@ -1915,23 +2179,33 @@ c-\tweak #'thickness #5 ( d e f)
 For the @code{\tweak} command to work, it must
 remain immediately adjacent to the object to which it is
 to apply after the input file has been converted to a music stream.
-At times, LilyPond may insert additional items into the music stream
-during the parsing process.  For example, when a note that is not
-explicitly part of a chord will be placed in a chord by LilyPond,
-so notes to be modified with @code{\tweak} must be placed inside
-a chord construct:
+Tweaking a whole chord does not do anything since its music event
+only acts as a container, and all layout objects are created from events
+inside of the @code{EventChord}:
 
 @lilypond[relative=2,verbatim,quote]
 \tweak #'color #red c4
-<\tweak #'color #red c>4
+\tweak #'color #red <c e>4
+<\tweak #'color #red c e>4
+@end lilypond
+
+The simple @code{\tweak} command cannot be used to modify any object
+that is not directly created from the input.  In particular
+it will not affect stems, automatic
+beams or accidentals, since these are generated later by
+@code{NoteHead} layout objects rather than by music elements in the
+input stream.
+
+Such indirectly created layout objects can be tweaked using the explicit
+form of the @code{\tweak} command:
+
+@lilypond[relative=2,verbatim,quote]
+\tweak Stem #'color #red
+\tweak Beam #'color #green c8 e
+<c e \tweak Accidental #'font-size #-3 ges>4
 @end lilypond
 
-The @code{\tweak} command cannot be used to modify any item
-that does not appear explicitly in the input file.  In particular
-it cannot be used to modify stems,
-beams or accidentals directly, since these are generated later by
-note heads, rather than by music elements in the input stream.
-Nor can @code{\tweak} be used to modify clefs or time
+@code{\tweak} cannot be used to modify clefs or time
 signatures, since these become separated from any preceding
 @code{\tweak} command in the input stream by the automatic
 insertion of extra elements required to specify the context.
@@ -1956,28 +2230,21 @@ 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
-The @code{\tweak} commands cannot be used in @code{\lyricmode}.
-
 @cindex tweaking control points
 @cindex control points, tweaking
 
-The @code{\tweak} command will apply to only the first of several
-generated ties in a chord.
+The @code{\tweak} command cannot be used to modify the control
+points of just one of several ties in a chord, other than the first
+one encountered in the input file.
 
 @node set versus override
 @subsection @code{\set} vs. @code{\override}
@@ -2274,31 +2541,30 @@ c2^( c)
 
 @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
@@ -2309,7 +2575,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)
@@ -2320,6 +2586,17 @@ 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
@@ -2369,7 +2646,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 +2981,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},
@@ -2862,7 +3137,7 @@ 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:
 
-@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
 @headitem form                       @tab form                    @tab break  @tab break    @tab break
 
@@ -3047,10 +3322,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 +3451,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 +3463,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 +3516,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},
+Notation Reference:
+@ref{Using the break-alignable-interface}.
+
+Extending LilyPond:
 @rextend{Callback functions}.
 
 @menu
@@ -3592,7 +3869,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 +3967,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
@@ -3739,7 +4118,8 @@ must return @code{#t}.
 @item @code{@var{@dots{}music@dots{}}}
 @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
+value or music function argument or music inside of music lists) to
+reference arguments
 (eg. @samp{#arg1}).
 @end multitable
 
@@ -3769,13 +4149,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:
@@ -3815,20 +4193,17 @@ padText =
 In addition to numbers, we can use music expressions such
 as notes for arguments to music functions:
 
-@c TODO: use a better example (the music argument is redundant).
-
 @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
+     \tweak NoteHead #'stencil #ly:text-interface::print
+     \tweak NoteHead #'text
+        \markup \musicglyph #"custodes.mensural.u0"
+     \tweak Stem #'stencil ##f
+     #note
    #})
 
 \relative c' { c4 d e f \custosNote g }
@@ -3840,7 +4215,7 @@ Substitution functions with multiple arguments can be defined:
 tempoPadded =
 #(define-music-function
      (parser location padding tempotext)
-     (number? string?)
+     (number? markup?)
    #{
      \once \override Score.MetronomeMark #'padding = #padding
      \tempo \markup { \bold #tempotext }
@@ -3849,7 +4224,7 @@ tempoPadded =
 \relative c'' {
   \tempo \markup { "Low tempo" }
   c4 d e f g1
-  \tempoPadded #4.0 #"High tempo"
+  \tempoPadded #4.0 "High tempo"
   g4 f e d c1
 }
 @end lilypond