Misleading documentation for \applyOutput?

[David Kastrup]

Hi,

the documentation for applyOutput states

`applyContext' - PROC (procedure)
     Modify context properties with Scheme procedure PROC.

After digging back and forth through documentation and scratching my
head, I have come to the conclusion that \applyContext is the
_canonical_ way to actually execute arbitrary Scheme code while
_processing_ a music list.  Music functions, on contrast, behave more
like macros: they are executed while _parsing_ music lists, not while
processing them.

If you take a look at lilypond-extending, it states:


    2.3.1 Context evaluation
    ------------------------

    Contexts can be modified during interpretation with Scheme code.  The
    syntax for this is
    \applyContext FUNCTION

       `FUNCTION' should be a Scheme function that takes a single argument:
    the context in which the `\applyContext' command is being called.  The
    following code will print the current bar number on the standard output
    during the compile:

    \applyContext
      #(lambda (x)
        (format #t "\nWe were called in barnumber ~a.\n"
         (ly:context-property x 'currentBarNumber)))

Again the documentation talks about "modified during interpretation".
But the example goes on to show code being executed for _displaying_
information.

What's the deal here?  Why this completely misleading characterization,
documentation and description?  What's with the name of the command?
With the documentation that makes it hard to remember and understand the
difference to \applyOutput, something utterly different?

-- 
David Kastrup