Re: parser variables persist beyond { } scope

[Trevor Daniels]

Mark Polesky wrote Friday, July 31, 2009 7:10 PM
> 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"?

No, I don't think this is a *common* error.
I've never seen it mentioned on -user.  And
it's too obscure for the LM anyway.

What we could do is add a full explanation of
parser (or global) variables in NR 6.8 "Difficult
tweaks", together with your warning, and reference
that from each of the examples in the docs that
uses them.  This accords with the established
style of the NR.  Your handy lists, below, could
also be included.

If you're happy with this, and there are no adverse
comments over the next couple of days, I'll initiate
it.  I will need some help from you to hone the text
though.

> 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

Trevor