programming-interface.itely: Improve `\applyOutput' documentation.

diff --git a/Documentation/extending/programming-interface.itely b/Documentation/extending/programming-interface.itely
index ed3e496991081b29135a9b31cb81404390230407..6dec5b0d2afc1dcca3e444dbe660dc341908cb04 100644 (file)
--- a/Documentation/extending/programming-interface.itely
+++ b/Documentation/extending/programming-interface.itely
@@ -748,8 +748,9 @@ 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
@@ -758,8 +759,8 @@ syntax is
 where @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:
+object found in the context @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 +771,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