]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/extending/programming-interface.itely
Run update-with-convert-ly
[lilypond.git] / Documentation / extending / programming-interface.itely
index 7848b0f1bd20f854b9882b7deb75edb40d7a75e9..87430c6a19ccb47c3534d4125f6d3a8010955aa4 100644 (file)
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.12.0"
+@c \version "2.15.17"
 
 @node Interfaces for programmers
 @chapter Interfaces for programmers
@@ -18,7 +18,10 @@ not familiar with Scheme, you may wish to read our
 @ref{Scheme tutorial}.
 
 @menu
+* Lilypond code blocks::
+* Scheme functions::
 * Music functions::
+* Event functions::
 * Markup functions::
 * Contexts for programmers::
 * Callback functions::
@@ -26,63 +29,272 @@ not familiar with Scheme, you may wish to read our
 * Difficult tweaks::
 @end menu
 
+@node Lilypond code blocks
+@section Lilypond code blocks
 
-@node Music functions
-@section Music functions
+Lilypond code blocks look like
+@example
+  #@{ @var{Lilypond code} #@}
+@end example
+They can be used anywhere where you can write Scheme code: the Scheme
+reader actually is changed for accommodating LilyPond code blocks.  When
+the LilyPond code block is being read, it is parsed superficially and
+replaced by a call to the LilyPond @code{parser} which is executed at
+runtime to interpret the LilyPond code block.
 
-@emph{Music functions} are scheme procedures that can create music
-expressions automatically, and can be used to greatly simplify the
-input file.
+The point of the superficial parsing is the interpretation of @code{$}
+signs which can be used for splicing in expressions from the surrounding
+lexical Scheme context (like @code{let} variables and function
+parameters).  @code{$} can be used in the following ways:
+
+@table @code
+@item $$
+just passes a single @code{$} to the LilyPond parser.
+@item $@var{form}
+will evaluate the Scheme form at runtime and splice its value as an
+identifier @code{\form} into the LilyPond parser.  Depending on the
+value type, it may be interpreted as several different syntactic
+entities.
+@item #$@var{form}
+will evaluate the Scheme form at runtime and splice its value as a
+Scheme expression into the LilyPond parser.
+@item #@var{form}
+Forms in Scheme expressions started with @code{#} are read and parsed
+recursively for @code{$} signs.  Those are treated as follows:
+@item #@dots{}$@var{variable}
+splices the value of the variable into the surrounding expression.
+@item #@dots{}($ @var{form} @dots{})
+splices the value of the form into the surrounding expression.  As
+opposed to a LilyPond level @code{$@var{form}}, you need to separate the
+form with a blank, making @code{$} be recognizable as a separate Scheme
+symbol.
+@end table
+
+A LilyPond code block may contain anything that you can use on the right
+side of an assignment.  In addition, an empty LilyPond block corresponds
+to a void music expression, and a LilyPond block containing multiple
+music events gets turned into a sequential music expression.
+
+@node Scheme functions
+@section Scheme functions
+@cindex Scheme functions (LilyPond syntax)
+
+@emph{Scheme functions} are Scheme procedures that can create Scheme
+expressions from input written in LilyPond syntax.  They can be called
+in pretty much all places where using @code{#} for specifying a value in
+Scheme syntax is allowed.  While Scheme has functions of its own, this
+chapter is concerned with @emph{syntactic} functions, functions that
+receive arguments specified in LilyPond syntax.
 
 @menu
-* Music function syntax::
-* Simple substitution functions::
-* Intermediate substitution functions::
-* Mathematics in functions::
-* Functions without arguments::
-* Void functions::
+* Scheme function definitions::
+* Scheme function usage::
+* Void scheme functions::
 @end menu
 
+@node Scheme function definitions
+@subsection Scheme function definitions
+@funindex define-scheme-function
 
-@node Music function syntax
-@subsection Music function syntax
-
-The general form for music functions is:
+The general form for defining scheme functions is:
 
 @example
 function =
-#(define-music-function
+#(define-scheme-function
      (parser location @var{arg1} @var{arg2} @dots{})
      (@var{type1?} @var{type2?} @dots{})
-   @var{music})
+   @var{body})
 @end example
 
 @noindent
 where
 
 @multitable @columnfractions .33 .66
+@item @code{parser}
+@tab needs to be literally @code{parser} in order to give LilyPond code
+blocks (@code{#@{}@dots{}@code{#@}}) access to the parser.
+
 @item @code{@var{argN}}
 @tab @var{n}th argument
 
 @item @code{@var{typeN?}}
-@tab a scheme @emph{type predicate} for which @code{@var{argN}}
-must return @code{#t}.
-
-@item @code{@var{music}}
-@tab A music expression, optionally written in scheme, with any
-LilyPond code enclosed in hashed braces
-(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}).  Within LilyPond code
-blocks, use @code{$} to reference function arguments (eg.,
-@samp{$arg1}) or to start an inline scheme expression containing
-function arguments (eg., @w{@samp{$(cons arg1 arg2)}}).
-
+@tab a Scheme @emph{type predicate} for which @code{@var{argN}}
+must return @code{#t}.  Some of these predicates are specially
+recognized by the parser, see below.  There is also a special form
+@code{(@emph{predicate?} @emph{default})} for specifying optional
+arguments.  If the actual argument is missing when the function is being
+called, the default value is substituted instead.  Default values are
+evaluated at definition time (including LilyPond code blocks!), so if
+you need a default calculated at runtime, instead write a special value
+you can easily recognize.  If you write the predicate in parentheses but
+don't follow it with a default value, @code{#f} is used as the default.
+Default values are not verified with @emph{predicate?} at either
+definition or run time: it is your responsibility to deal with the
+values you specify.  Default values that happen to be music expressions
+are copied while setting @code{origin} to the @code{location} parameter.
+
+@item @code{@var{body}}
+@tab A sequence of Scheme forms evaluated in order, the last one being
+used as the return value of the scheme function.  It may contain
+LilyPond code blocks enclosed in hashed braces
+(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), like described in @ref{Lilypond
+code blocks}.  Within LilyPond code blocks, use @code{$} to reference
+function arguments (eg., @samp{$arg1}) or to start an inline Scheme
+expression containing function arguments (eg., @w{@samp{$(cons arg1
+arg2)}}).  If your function returns a music expression, it is cloned and
+given the correct @code{origin}.
 @end multitable
 
 @noindent
+Some type predicates are specially handled by the parser since it
+can't recognize the arguments reliably otherwise.  Currently these are
+@code{ly:pitch?} and @code{ly:duration?}.
+
+Suitability of arguments for all other predicates is determined by
+actually calling the predicate after Lilypond has already converted
+them into a Scheme expression.  As a consequence, the argument can be
+specified in Scheme syntax if desired (introduced with @code{#} or as
+the result of calling a scheme function), but Lilypond will also
+convert a number of Lilypond constructs into Scheme before actually
+checking the predicate on them.  Currently, those include music,
+simple strings (with or without quotes), full markups and markup
+lists, score, book, bookpart, context definition and output definition
+blocks.
+
+For some kinds of expression (like most music not enclosed in braces)
+Lilypond needs to look further than the expression itself in order to
+determine its end.  When such an expression is considered for an
+optional argument by evaluating its predicate, Lilypond can't ``back
+up'' when it decides the expression does not fit the parameter, and
+complains.  So in some contexts involving optional arguments, you may
+need extra braces to make them acceptable to Lilypond.
+
+This also applies for music arguments preceding @code{ly:duration?}
+arguments.  It may also affect the last argument of a scheme function
+that is used as the last part of another expression, since otherwise
+Lilypond won't know whether following postevents or durations apply to
+the argument of the Scheme function, or to the containing music
+expression.
+
 For a list of available type predicates, see
-@ruser{Predefined type predicates}.  User-defined type predicates
-are also allowed.
+@ruser{Predefined type predicates}.
+
+@seealso
+
+Notation Reference:
+@ruser{Predefined type predicates}.
+
+Installed Files:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
+
+@node Scheme function usage
+@subsection Scheme function usage
+
+Scheme functions can be called pretty much anywhere where a Scheme
+expression starting with @code{#} can be written.  You call a scheme
+function by writing its name preceded by @code{\}, followed by its
+arguments.  The last argument can't be an optional argument.  If there
+are several optional arguments in a row, they are filled with values
+left to right.  Once an optional argument can't match input, it and all
+immediately following optional arguments are replaced with their default
+values, and the matching continues with the next non-optional argument.
+
+Apart from places where a Scheme value is required, there are a few
+places where @code{#} expressions are currently accepted and evaluated
+for their side effects but otherwise ignored.  Mostly those are the
+places where an assignment would be acceptable as well.
+
+Since it is a bad idea to return values that can be misinterpreted in
+some context, you should use normal scheme functions only for those
+cases where you always return a useful value, and use void scheme
+functions (@pxref{Void scheme functions}) otherwise.
+
+@node Void scheme functions
+@subsection Void scheme functions
+@funindex define-void-function
+@funindex \void
+
+Sometimes a procedure is executed in order to perform an action rather
+than return a value.  Some programming languages (like C and Scheme)
+use functions for either concept and just discard the returned value
+(usually by allowing any expression to act as statement, ignoring the
+result).  This is clever but error-prone: most C compilers nowadays
+offer warnings for various non-``void'' expressions being discarded.
+For many functions executing an action, the Scheme standards declare
+the return value to be unspecified.  Lilypond's Scheme interpreter
+Guile has a unique ``unspecified'' value that it usually (such when
+using @code{set!} directly on a variable) but unfortunately not
+consistently returns in such cases.
+
+Defining a Lilypond function with @code{define-void-function} makes
+sure that this special value (the only value satisfying the predicate
+@code{void?}) will be returned.
+
+@example
+noPointAndClick =
+#(define-void-function
+     (parser location)
+     ()
+   (ly:set-option 'point-and-click #f))
+...
+\noPointAndClick   % disable point and click
+@end example
+
+If you want to evaluate an expression only for its side-effect and
+don't want any value it may return interpreted, you can do so by
+prefixing it with @code{\void}:
+
+@example
+\void #(hashq-set! some-table some-key some-value)
+@end example
+
+That way, you can be sure that Lilypond will not assign meaning to the
+returned value regardless of where it encounters it.  This will also
+work for music functions such as @code{\displayMusic}.
+
+@node Music functions
+@section Music functions
+
+@cindex music functions
+
+@emph{Music functions} are Scheme procedures that can create music
+expressions automatically, and can be used to greatly simplify the
+input file.
+
+@menu
+* Music function definitions::
+* Music function usage::
+* Simple substitution functions::
+* Intermediate substitution functions::
+* Mathematics in functions::
+* Functions without arguments::
+* Void music functions::
+@end menu
+
+
+@node Music function definitions
+@subsection Music function definitions
+@cindex defining music functions
+@funindex define-music-function
+
+The general form for defining music functions is:
 
+@example
+function =
+#(define-music-function
+     (parser location @var{arg1} @var{arg2} @dots{})
+     (@var{type1?} @var{type2?} @dots{})
+   @var{body})
+@end example
+
+@noindent
+quite in analogy to @ref{Scheme function definitions}.  More often than
+not, @var{body} will be a @ref{Lilypond code blocks, Lilypond code block}.
+
+For a list of available type predicates, see
+@ruser{Predefined type predicates}.
 
 @seealso
 
@@ -95,6 +307,42 @@ Installed Files:
 @file{scm/lily.scm}.
 
 
+@node Music function usage
+@subsection Music function usage
+Music functions may currently be used in three places.  Depending on
+where they are used, restrictions apply in order to be able to parse
+them unambiguously.  The result a music function returns must be
+compatible with the context in which it is called.
+
+@itemize
+@item
+At top level in a music expression.  There are no special restrictions
+on the argument list.
+
+@item
+As a post-event, explicitly started with a direction indicator (one of
+@code{-}, @code{^}, @w{and @code{_}}).  All trailing arguments of the
+music function with the predicate @code{ly:music?} will get parsed also
+as post-events (if the last argument is a scheme function, this will
+hold for trailing @code{ly:music?} arguments of the scheme function
+instead).  Note that returning a post-event will be acceptable for music
+functions called as normal music, leading to a result roughly equivalent
+to
+@example
+s 1*0-\fun
+@end example
+
+@item
+As a chord constituent.  All trailing arguments of the music function
+with the predicate @code{ly:music?} will get parsed also as chord
+constituents.
+@end itemize
+
+@noindent
+The special rules for trailing arguments make it possible to write
+polymorphic functions like @code{\tweak} that can be applied to
+different constructs.
+
 @node Simple substitution functions
 @subsection Simple substitution functions
 
@@ -111,7 +359,7 @@ Intermediate substitution functions involve a mix of Scheme code
 and LilyPond code in the music expression to be returned.
 
 Some @code{\override} commands require an argument consisting of
-a pair of numbers (called a @code{cons cell} in Scheme).
+a pair of numbers (called a @emph{cons cell} in Scheme).
 
 The pair can be directly passed into the music function,
 using a @code{pair?} variable:
@@ -233,31 +481,35 @@ lilypond -d display-bar-numbers FILENAME.ly
 @end example
 
 
-@node Void functions
-@subsection Void functions
-
-A music function must return a music expression, but sometimes we
-may want to have a function that does not involve music (such as
-turning off Point and Click).  To do this, we return a @code{void}
-music expression.
-
-That is why the form that is returned is the
-@w{@code{(make-music @dots{})}}.  With the @code{'void} property
-set to @code{#t}, the parser is told to actually disregard this
-returned music expression.  Thus the important part of the void
-music function is the processing done by the function, not the
-music expression that is returned.
-
-@example
-noPointAndClick =
-#(define-music-function
-     (parser location)
-     ()
-   (ly:set-option 'point-and-click #f)
-   (make-music 'SequentialMusic 'void #t))
-...
-\noPointAndClick   % disable point and click
-@end example
+@node Void music functions
+@subsection Void music functions
+
+A music function must return a music expression.  If you want to
+execute a function only for its side effect, you should use
+@code{define-void-function}.  But there may be cases where you
+sometimes want to produce a music expression, and sometimes not (like
+in the previous example).  Returning a @code{void} music expression
+via @code{#@{ #@}} will achieve that.
+
+@node Event functions
+@section Event functions
+@funindex define-event-function
+@cindex event functions
+
+To use a music function in the place of an event, you need to write a
+direction indicator before it.  But sometimes, this does not quite match
+the syntax of constructs you want to replace.  For example, if you want
+to write dynamics commands, those are usually attached without direction
+indicator, like @code{c'\pp}.  Here is a way to write arbitrary
+dynamics:
+@lilypond[quote,verbatim,raggedright]
+dyn=#(define-event-function (parser location arg) (markup?)
+         (make-dynamic-script arg))
+\relative c' { c\dyn pfsss }
+@end lilypond
+You could do the same using a music function, but then you always would
+have to write a direction indicator before calling it, like
+@code{@w{c-\dyn pfsss}}.
 
 
 @node Markup functions
@@ -289,13 +541,16 @@ providing a LilyPond-like syntax.  For example,
 @noindent
 is equivalent to:
 @example
-\markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
-                  \larger \line @{ foo bar baz @} @}
+#@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
+                  \larger \line @{ foo bar baz @} @} #@}
 @end example
 
 @noindent
 This example demonstrates the main translation rules between regular
-LilyPond markup syntax and Scheme markup syntax.
+LilyPond markup syntax and Scheme markup syntax.  Using @code{#@{
+@dots{} #@}} for entering in LilyPond syntax will often be most
+convenient, but we explain how to use the @code{markup} macro to get a
+Scheme-only solution.
 
 @quotation
 @multitable @columnfractions .3 .3
@@ -370,7 +625,7 @@ The @code{raise-markup} function first creates the stencil for the
 @code{text example} string, and then it raises that Stencil by 0.5
 staff space.  This is a rather simple example; more complex examples
 are in the rest
-of this section, and in @file{scm/@/define@/-markup@/-commands@/.scm}.
+of this section, and in @file{scm/define-markup-commands.scm}.
 
 
 @node New markup command definition
@@ -401,22 +656,22 @@ New markup commands can be defined using the
 
 The arguments are
 
-@table @var
-@item command-name
+@table @code
+@item @var{command-name}
 the markup command name
 @item layout
 the @q{layout} definition.
 @item props
 a list of associative lists, containing all active properties.
-@item argi
+@item @var{argi}
 @var{i}th command argument
-@item argi-type?
+@item @var{argi-type?}
 a type predicate for the i@var{th} argument
 @end table
 
-If the command uses properties from the @var{props} arguments, the
-@code{#:properties} keyword can be used, to specify which properties are
-used, and their default values.
+If the command uses properties from the @code{props} arguments,
+the @code{#:properties} keyword can be used to specify which
+properties are used along with their default values.
 
 Arguments are distinguished according to their type:
 @itemize
@@ -427,17 +682,19 @@ Arguments are distinguished according to their type:
 @code{list?}, @code{number?}, @code{boolean?}, etc.
 @end itemize
 
-There is no limitation on the order of arguments (after the standard
-@var{layout} and @var{props} arguments).  However, markup functions
-taking a markup as their last argument are somewhat special as you can
-apply them to a markup list, and the result is a markup list where the
-markup function (with the specified leading arguments) has been applied
-to every element of the original markup list.
+There is no limitation on the order of arguments (after the
+standard @code{layout} and @code{props} arguments).  However,
+markup functions taking a markup as their last argument are
+somewhat special as you can apply them to a markup list, and the
+result is a markup list where the markup function (with the
+specified leading arguments) has been applied to every element of
+the original markup list.
 
-Since replicating the leading arguments for applying a markup function
-to a markup list is cheap mostly for Scheme arguments, you avoid
-performance pitfalls by just using Scheme arguments for the leading
-arguments of markup functions that take a markup as their last argument.
+Since replicating the leading arguments for applying a markup
+function to a markup list is cheap mostly for Scheme arguments,
+you avoid performance pitfalls by just using Scheme arguments for
+the leading arguments of markup functions that take a markup as
+their last argument.
 
 @node On properties
 @unnumberedsubsubsec On properties
@@ -496,7 +753,8 @@ Then, the padding between the two boxes is considered too small, so we
 override it too:
 
 @lilypond[quote,verbatim,ragged-right]
-\markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
+\markup \override #'(box-padding . 0.4) \box
+     \override #'(box-padding . 0.6) \box A
 @end lilypond
 
 Repeating this lengthy markup would be painful.  This is where a markup
@@ -504,6 +762,16 @@ command is needed.  Thus, we write a @code{double-box} markup command,
 taking one argument (the text).  This draws the two boxes, with some
 padding.
 
+@lisp
+#(define-markup-command (double-box layout props text) (markup?)
+  "Draw a double box around text."
+  (interpret-markup layout props
+    #@{\markup \override #'(box-padding . 0.4) \box
+            \override #'(box-padding . 0.6) \box @{ $text @}#@}))
+@end lisp
+
+or, equivalently 
+
 @lisp
 #(define-markup-command (double-box layout props text) (markup?)
   "Draw a double box around text."
@@ -515,10 +783,10 @@ padding.
 @code{text} is the name of the command argument, and @code{markup?} its
 type: it identifies it as a markup.  The @code{interpret-markup}
 function is used in most of markup commands: it builds a stencil, using
-@code{layout}, @code{props}, and a markup.  Here, this markup is built
-using the @code{markup} scheme macro, see @ref{Markup construction in Scheme}.
-The transformation from @code{\markup} expression to scheme
-markup expression is straight-forward.
+@code{layout}, @code{props}, and a markup.  In the second case, this
+markup is built using the @code{markup} scheme macro, see @ref{Markup
+construction in Scheme}.  The transformation from @code{\markup}
+expression to scheme markup expression is straight-forward.
 
 The new command can be used as follow:
 
@@ -530,11 +798,24 @@ It would be nice to make the @code{double-box} command customizable:
 here, the @code{box-padding} values are hard coded, and cannot be
 changed by the user.  Also, it would be better to distinguish the
 padding between the two boxes, from the padding between the inner box
-and the text. So we will introduce a new property,
-@code{inter-box-padding}, for the padding between the two boxes. The
+and the text.  So we will introduce a new property,
+@code{inter-box-padding}, for the padding between the two boxes.  The
 @code{box-padding} will be used for the inner padding.  The new code is
 now as follows:
 
+@lisp
+#(define-markup-command (double-box layout props text) (markup?)
+  #:properties ((inter-box-padding 0.4)
+                (box-padding 0.6))
+  "Draw a double box around text."
+  (interpret-markup layout props
+    #@{\markup \override #`(box-padding . ,$inter-box-padding) \box
+               \override #`(box-padding . ,$box-padding) \box
+               @{ $text @} #@}))
+@end lisp
+
+Again, the equivalent version using the markup macro would be:
+
 @lisp
 #(define-markup-command (double-box layout props text) (markup?)
   #:properties ((inter-box-padding 0.4)
@@ -564,8 +845,9 @@ customized:
                 (box-padding 0.6))
   "Draw a double box around text."
   (interpret-markup layout props
-    (markup #:override `(box-padding . ,inter-box-padding) #:box
-            #:override `(box-padding . ,box-padding) #:box text)))
+    #{\markup \override #`(box-padding . ,$inter-box-padding) \box
+              \override #`(box-padding . ,$box-padding) \box
+              { $text } #}))
 
 \markup \double-box A
 \markup \override #'(inter-box-padding . 0.8) \double-box A
@@ -577,7 +859,7 @@ customized:
 
 A good way to start writing a new markup command, is to take example on
 a builtin one.  Most of the markup commands provided with LilyPond can be
-found in file @file{scm/@/define@/-markup@/-commands@/.scm}.
+found in file @file{scm/define-markup-commands.scm}.
 
 For instance, we would like to adapt the @code{\draw-line} command, to
 draw a double line instead.  The @code{\draw-line} command is defined as
@@ -666,6 +948,16 @@ a single stencil, the former returns a list of stencils.
 In the following example, a @code{\paragraph} markup list command is
 defined, which returns a list of justified lines, the first one being
 indented.  The indent width is taken from the @code{props} argument.
+
+@example
+#(define-markup-list-command (paragraph layout props args) (markup-list?)
+   #:properties ((par-indent 2))
+   (interpret-markup-list layout props
+     #@{\markuplist \justified-lines @{ \hspace #$par-indent $args @} #@}))
+@end example
+
+
+The version using just Scheme is more complex:
 @example
 #(define-markup-list-command (paragraph layout props args) (markup-list?)
    #:properties ((par-indent 2))
@@ -681,16 +973,16 @@ Besides the usual @code{layout} and @code{props} arguments, the
 First, the function gets the indent width, a property here named
 @code{par-indent}, from the property list @code{props}.  If the
 property is not found, the default value is @code{2}.  Then, a
-list of justified lines is made using the
-@code{make-justified-lines-markup-list} function, which is related
-to the @code{\justified-lines} built-in markup list command.  A
-horizontal space is added at the beginning using the
-@code{make-hspace-markup} function.  Finally, the markup list is
+list of justified lines is made using the built-in markup list command
+@code{\justified-lines}, which is related to the
+@code{make-justified-lines-markup-list} function.  A
+horizontal space is added at the beginning using @code{\hspace} (or the
+@code{make-hspace-markup} function).  Finally, the markup list is
 interpreted using the @code{interpret-markup-list} function.
 
 This new markup list command can be used as follows:
 @example
-\markuplines @{
+\markuplist @{
   \paragraph @{
     The art of music typography is called \italic @{(plate) engraving.@}
     The term derives from the traditional process of music printing.
@@ -726,10 +1018,10 @@ syntax for this is
 \applyContext @var{function}
 @end example
 
-@var{function} should be a Scheme function that takes a single
-argument: the context in which the @code{\applyContext} command is
-being called.  The following code will print the current bar
-number on the standard output during the compile:
+@code{@var{function}} should be a Scheme function that takes a
+single argument: the context in which the @code{\applyContext}
+command is being called.  The following code will print the
+current bar number on the standard output during the compile:
 
 @example
 \applyContext
@@ -748,18 +1040,19 @@ number on the standard output during the compile:
 @funindex \applyOutput
 
 
-The most versatile way of tuning an object is @code{\applyOutput}.  Its
-syntax is
+The most versatile way of tuning an object is @code{\applyOutput} which
+works by inserting an event into the specified context
+(@rinternals{ApplyOutputEvent}).  Its syntax is
 @example
 \applyOutput @var{context} @var{proc}
 @end example
 
 @noindent
-where @var{proc} is a Scheme function, taking three arguments.
+where @code{@var{proc}} is a Scheme function, taking three arguments.
 
-When interpreted, the function @var{proc} is called for every layout
-object found in the context @var{context}, with the following
-arguments:
+When interpreted, the function @code{@var{proc}} is called for
+every layout object found in the context @code{@var{context}} at
+the current time step, with the following arguments:
 @itemize
 @item the layout object itself,
 @item the context where the layout object was created, and
@@ -770,20 +1063,20 @@ arguments:
 In addition, the cause of the layout object, i.e., the music
 expression or object that was responsible for creating it, is in the
 object property @code{cause}.  For example, for a note head, this is a
-@rinternals{NoteHead} event, and for a @rinternals{Stem} object,
-this is a @rinternals{NoteHead} object.
+@rinternals{NoteHead} event, and for a stem object,
+this is a @rinternals{Stem} object.
 
 Here is a function to use for @code{\applyOutput}; it blanks
-note-heads on the center-line:
+note-heads on the center-line and next to it:
 
 @lilypond[quote,verbatim,ragged-right]
 #(define (blanker grob grob-origin context)
    (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
-            (eq? (ly:grob-property grob 'staff-position) 0))
+            (< (abs (ly:grob-property grob 'staff-position)) 2))
        (set! (ly:grob-property grob 'transparent) #t)))
 
 \relative c' {
-  e4 g8 \applyOutput #'Voice #blanker b d2
+  a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
 }
 @end lilypond
 
@@ -958,33 +1251,36 @@ of the broken tie is repositioned.
 
 @lilypond[quote,verbatim,ragged-right]
 #(define (my-callback grob)
-  (let* (
-         ; have we been split?
-         (orig (ly:grob-original grob))
+   (let* (
+          ;; have we been split?
+          (orig (ly:grob-original grob))
 
-         ; if yes, get the split pieces (our siblings)
-         (siblings (if (ly:grob? orig)
-                     (ly:spanner-broken-into orig) '() )))
+          ;; if yes, get the split pieces (our siblings)
+          (siblings (if (ly:grob? orig)
+                        (ly:spanner-broken-into orig)
+                        '())))
 
-   (if (and (>= (length siblings) 2)
-             (eq? (car (last-pair siblings)) grob))
-     (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
+     (if (and (>= (length siblings) 2)
+              (eq? (car (last-pair siblings)) grob))
+         (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
 
 \relative c'' {
   \override Tie #'after-line-breaking =
   #my-callback
-  c1 ~ \break c2 ~ c
+  c1 ~ \break
+  c2 ~ c
 }
 @end lilypond
 
 @noindent
 When applying this trick, the new @code{after-line-breaking} callback
-should also call the old one @code{after-line-breaking}, if there is
-one.  For example, if using this with @code{Hairpin},
-@code{ly:hairpin::after-line-breaking} should also be called.
+should also call the old one, if such a default exists.  For example,
+if using this with @code{Hairpin}, @code{ly:spanner::kill-zero-spanned-time}
+should also be called.
 
 
-@item Some objects cannot be changed with @code{\override} for
+@item
+Some objects cannot be changed with @code{\override} for
 technical reasons.  Examples of those are @code{NonMusicalPaperColumn}
 and @code{PaperColumn}.  They can be changed with the
 @code{\overrideProperty} function, which works similar to @code{\once