[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Misleading documentation for \applyOutput?

From: Trevor Daniels
Subject: Re: Misleading documentation for \applyOutput?
Date: Tue, 30 Aug 2011 16:47:57 +0100


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.


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


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:

     #(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_

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]