Re: parser variables persist beyond { } scope

[Mark Polesky]

Han-Wen Nienhuys wrote:
> No.  In the specific case, I'd recommend making another music
> function that takes an argument, so you can pass the 15/16
> explicitly, without mucking with variables.

So it sounds like you believe that one way or another, the burden
should be on the user. Then do you think we should add a warning
in the docs, something like this?

"When the value of such a variable is changed in a .ly file, the
change is global, and unless explicitly reverted, the new value
will persist to the end of the file, affecting subsequent \score
blocks as well as external files added with the \include command.
This can lead to unintended consequences (if a variable is not
explicitly reverted). Especially in complex typesetting projects,
these types of errors can be difficult to track down."

Would this be something to add to LM 5.2.2 "Common errors"?

I suppose we could also explain (in the docs) how to devise (in
general) a custom music-function with the extra argument as you
described, but this is a little trickier than simply pointing
users to NR 6.1.3 "Paired substitution functions". Rewriting the
music-function involves not only finding the location of its
definition in the distribution files, but also manipulating the
scheme code -- far more advanced than explicitly reverting the
value, but much safer.

What do you think?

******************

By the way, the number of "parser variables" susceptible to this
situation may be quite small. I grepped "(ly:parser-lookup" and
found these 12 variables:

afterGraceFraction
musicQuotes
mode
output-count
output-suffix
parseStringResult
partCombineListener
pitchnames
toplevel-bookparts
toplevel-scores
showLastLength
showFirstLength

Of these 12, 5 were involved in examples (in the docs) showing how
to modify the value from a .ly file:

#(define afterGraceFraction (cons 15 16))
#(set! output-count 1)
#(define output-suffix "violin")
showFirstLength = R1*1
showLastLength = R1*5

- Mark