Re: How to procede with \override/\revert business

[Trevor Daniels]

David Kastrup wrote Sunday, October 28, 2012 4:34 PM

> <URL:http://code.google.com/p/lilypond/issues/detail?id=2934>.
> 
> If we are going through with this one, it means that the
> override/revert/overrideProperty syntax presented to users is
> fundamentally different from before.

I think this is a price worth paying to gain the easier syntax.
It's hard for long-standing users, but we need to look ahead
and consider the (hopefully larger number of) future users.
For them it will be far easier to understand (although we'll
need to rename X-offset and friends to simplify the documentation.)

> It also means a hard cut in syntax for \overrideProperty: the old syntax
> will no longer work.  The builtin commands \override and \revert, much
> more often used, will have a grace period where both old and new syntax
> will work fine.  Fading the old syntax out can likely be done in "baby
> steps" meaning deprecating for 2.18, warning for 2.20, removing support
> for 2.22.

I think this is acceptable.  \overrideProperty is rarely used.  This
schedule is likely to extend over some years if past schedules are
an indication, so it lets existing users down quite gently.  I guess
we change the docs right away though, or at least as soon as we
can.  Maybe we should move to 3.0 when support is removed.

> In terms of compatibility, this is not the hottest sale: several music
> functions change interface incompatibly.  To a much more understandable
> form.  I am not enthused about the tweak-like commands that name a
> manipulated property at the front, ostensibly a grob path at the end as
> an alternative to tweaked music.
> 
> \alterBroken, with issue
> <URL:http://code.google.com/p/lilypond/issues/detail?id=2932> is
> probably the worst offender here.  On the other hand, this favors the
> use as a tweak rather than an override, and for that the syntax is
> clearly fine.

\alterBroken is not documented in the main body of the NR, so is
probably used only by the cognoscenti, who should not be fazed
by the change.

> The incompatible changes are unsavory, but they concern rarely used
> music functions.  Indeed, issue 2934 only tackled \overrideProperty of
> those, the rest having been brought in line in other issues, and
> \override/\revert maintaining backwards compatibility right now.

That's the saving grace.

> So I'd aim for getting 2.16.1 closed on Wednesday or so.  At that time,
> the next countdown will just have ended.  I'd want to flush this syntax
> change in at that time.  There is still the option to just put in the
> \overrideProperty change first, but then it will have incompatible
> syntax with \override/\revert.  Which is not totally tragic since it has
> been inconsistent for all but the last week.

Either way looks acceptable to me.
 
> However, if we want to go through with this kind of change, we will also
> need quite a bit of documentation, and it seems rather pointless to
> document a inconsistent interfaces when the actual target is to have
> both builtin as well as music-function-implemented commands be presented
> with a uniform interface.

We need to thank Graham for his insistance that documentation text
should not 'talk through the code'.  Because of that, convert-ly should
automatically fix the bulk of the documention.  Of course the sections
discussing the commands explicitly will need attention, but that's fairly
straight-forward given the naming conventions for Contexts, Grobs
and properties.
 
> There is also something to be said for compressing all the path-related
> interface changes into a single convert-ly rule so that we don't have to
> distinguish 2.17.6 syntax, 2.17.7 syntax, 2.17.8 syntax in a major way.

Agreed.

> David Kastrup

Trevor