Doc fixes for \applyOutput ... ok to push?

[David Kastrup]

The main reason I did not just push this as-is is that the changed
example, though much more illustrative, is butt-ugly and does not appear
to lead to sensible output with regard to the accidentals.  Suggestions
for improvement welcome.

I think it important to clarify that \applyOutput does not filter a
whole context, but just a single moment, and how it does that.

If you want to check this out, you can run
git am
(apply patches from mailbox)
on this message.  The recipe for experimenting with changes in the file
seems to be (for info, assuming installation done as root)

rm  Documentation/out-www/extending.texi
make info
sudo make install-info

diff --git a/Documentation/extending/programming-interface.itely 
b/Documentation/extending/programming-interface.itely
index ed3e496..a2db652 100644
--- 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,8 +771,8 @@ 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
address@hidden event, and for a @rinternals{Stem} object,
-this is a @rinternals{NoteHead} object.
address@hidden 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:
@@ -783,7 +784,7 @@ note-heads on the center-line:
        (set! (ly:grob-property grob 'transparent) #t)))
 
 \relative c' {
-  e4 g8 \applyOutput #'Voice #blanker b d2
+  b'4 g8 \applyOutput #'Voice #blanker <<b bes>> bes2
 }
 @end lilypond
 


-- 
David Kastrup