Re: Misleading documentation for \applyOutput?

[Trevor Daniels]

David

The documentation of \applyContext has not been touched
for several years (other than moving it around between
manuals.)  It may well be quite out-of-date.  This state
of affairs is because no one interested in documentation
understands it well enough and with enough confidence
to rewrite it :(  The same could probably be said of much
in Extending.

Trevor

----- Original Message ----- 
From: "David Kastrup" <address@hidden>
To: <address@hidden>
Sent: Tuesday, August 30, 2011 4:21 PM
Subject: Misleading documentation for \applyOutput?


> 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
>
>
> _______________________________________________
> lilypond-devel mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/lilypond-devel