Summary of \relative { q } ... analysis. (was: Plans for changing chord repeat implementations)

[David Kastrup]

Ok, since I am about to doing another user interface change, I present a
summary of the proposed way of tackling it, and the reasons behind it.
There are basically three different approaches of how to make q work,
all with advantages and drawbacks.

1) do it in the parser, like the last duration of notes is maintained in
the parser.  This is essentially what it done right now.  At the current
point of time, a _reference_ to the last chord is kept.  This is also
entered into the ChordRepeat event for the sake of relative.

Using the reference is _bad_ since any music function is allowed to
change its arguments, and the reference would change alongside.
However, this reference is _also_ used inside of \relative to make sure
that a chord repetition will have the same octave as its
already-converted preceding chord.  This only works as long as no
construct creates a _copy_ of the music expression, in which case
\relative stops working.

So the reference has to go for two reasons: it is a bad idea to be
affected by arbitrary processing changes.  And the one change that it
_needs_ to be affected from, that when using \relative, is not reliable.
The first problem means _copying_ the required data, in this case
basically the list of pitches.  The second problem is not solvable
cleanly except if \relative reestablishes the chord/predecessor
relations since the input might have been arbitrarily juggled around
since q has been input.  Creating a copied chord or a list of pitches
for every chord has a performance impact, and _if_ we are going to have
\relative redo the work anyway, this impact will not just be wasted in
case we were not actually using q after all, but also _when_ we were
using it, but inside of \relative.

2) do it in a specific music function either explicitly called, or
called automatically at an appropriate time.

This is totally straightforward and controllable.  It also means that it
is ok to work with a reference to the previous chord since no arbitrary
processing stages (like in the parser) will intervene between taking the
reference and using it.  It also means that we can _replace_ the
ChordRepeat event with an EventChord, meaning that any subsequent
processing never gets to see a chord repetition.

That means that "legacy" music functions of the user don't require
changes to accommodate chord repetitions: it is easy to make sure that
they never get to see them.  After \relative seems to be a good time to
call \q automatically (one could be cute and call it \absolute instead,
meaning that a user wanting to use q should have had his music passed
through either \relative or \absolute).

3) do the chord repetition right before iteration time (iteration itself
is too time-centric rather than order-centric to work well).  I think
that is too late since it means that \transpose and other stuff will not
get material to work with when they encounter q before their first
chord: the repeated chord will be expanded at a time where it won't be
transposed anymore.  In a nutshell, we q should not be expanded _before_
\relative, but not _after_ \transpose either.  So we could run it after
every \relative, and before every \transpose (and similar commands), and
at iteration time.  And so on.  Every time will have a performance
impact.

Strictly speaking, if we run at iteration time, we don't need to run
after \relative.  Why \relative?  Because that is a time and processing
order that people already are comfortable associating with input context
(in this case, relative pitch tracking).

I don't think we can get around either 2) or 3).  Having q work without
asking even in absolute mode would require either option 1) (in a manner
that can be overriden by \relative later) or 3), and 1) needs to work on
explicitly created lists of pitches or chord copies, whereas 2) and 3)
don't need that.

Possibly I am just paranoid about the transpose problem: people can
likely accept that { <c e g> \transpose c d { q } } does not transpose.
And it is not like there is a place where inserting \q could make it
work.

So the question is: where should q be automatically called in order to
be relevant just before iteration?  Something like
toplevel-music-handler?  Does that catch everything?

Having an explicit function \q _available_ will be useful since it means
you can prevent user music functions from seeing ChordRepeat at all.
But _if_ there is a good point where one can call it reliably
automatically before iteration, we could save the necessity for calling
it explicitly for absolute music (and the necessity of putting a call
inside of \relative).

Suggestions?

-- 
David Kastrup