Re: parser variables persist beyond { } scope

[Ian Hulin]

Mark Polesky wrote:
> 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 youidea
> 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?
To me, as a newbie looking at the Scheme code, I think these are kludges 
and therefore suck.
If you are going to write document the restriction as a "Common Error" 
and in LM 5.2.2 there should be big TODO comments in the code and a 
tracker to say that some (or all) of these variables need to be scoped 
by \score blocks, as Mark suggested.
See comments below for further info.
> ******************
>
> 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
<** Graham and Trevor alert**>
At the very least, these need documenting in the CG, along with some 
comments on what they are for.
I was able to work out output-count and output-suffix from the code in 
print-book-with, but I wouldn't have a clue where to look for where they 
are defined/where they are used in the code beyond what Mark has 
produced here.
Any offers to lighten the Frogs' darkness?
</** Graham and Trevor alert**>

OK, here's the reason I feel strongly on this:

I've been looking at the low-level trackers regarding output filenames.

In the lilypond code we assume that there is only one output filename of 
each type which is produced when compiling a lilypond source (and the 
files it \includes).

Each lilypond source file has to have at least one \source block, and if 
the user doesn't code it, the compiler assumes an implicit one during 
compilation.

The compiler assumes that the filename part of the source file, or if 
specified, the --output argument value is what we use for producing the 
set of files for the \score block.  So foobar.ly produces foobar.pdf (or 
foobar.svg or foobar.png) and maybe foobar.mid/foobar.midi.

However there's a real problem that opens up once we allow more than one 
\score block in each source file:  while the graphical back-ends (pdf, 
svg, png} etc. append the output for each \score to the original, the 
\midi block produces a separate file, which is the reason for the 
output-count and output-suffix parser variables.  This is so the 
print-book-with Scheme function in lily-library.scm can play around with 
them and add a sequential number to to each filename for the midi files 
produced.

I think the sequence number idea using parser variables was a 
rough-and-ready solution to prevent successive \midi blocks within a 
\score from over-writing the midi block from a previous \score.
However the assumption that 
parser-variables-only-apply-to-things-at-outermost-score-level was left 
in place.

I've been trying to look at this problem but to allow either a property 
within the \midi block or a function to allow users to specify a 
specific filename for that \score section or specify the output-suffix 
for that section, and before I went on holiday was that print-book-with 
function was only called once per compilation, so it seemed I was up 
against a brick wall without guidance from a grown-up developer, and I 
believed properties attached to \score within a \bookpart were 
inheritable and scoped, and Han-Wen appears to be saying they're not.

I think they need to be, hence why I agree with Mark's original proposal.

I reckon output-suffix (at least) needs to be a \score property that is 
saved at the beginning of processing a \score block, and restored at the 
end of the expression governed by the \score. Potentially maybe some of 
the others need this but I can't comment without knowing what they do.

Sorry if this looks like a top-posting, but the overall issue Mark 
raised here has shed light on something I've been struggling with, and 
maybe has exposed a design assumption that wasn't clear beyond the 
original lilypond developers.

Cheers,
Ian Hulin