Fill in section "\set vs \override"

Fill in section "\set vs \override"

[Trevor Daniels, 2013-11-06 13:41:54]

LGTM.

I think it's OK at the end of this section as a sort of technical addendum for
those users who will appreciate a more comprehensive and accurate explanation. 
Maybe a link to it from the Overview?

[benrg, 2013-11-07 00:04:43]

As someone who barely understands LilyPond's internals I appreciate this
explanation, but it still leaves me confused. It seems to be saying that grob
properties are an additional hierarchical override system below the level of
context properties, but I don't see why that's needed when context properties
already behave in a similar way. Also, the assignment of properties to the
context or grob "genders" seems somewhat arbitrary; I don't see why
tempoHideNote should be a context property and BarNumber.break-visibility a grob
property, for example.

Especially now that there is a unified dot syntax, could \set and \override be
made synonyms that work out internally what kind of property to set, making the
distinction an internal detail that most people could ignore?

(This is a clarification request, not a feature request. I find it helpful if
documentation mentions which features of a design are historical accidents that
wouldn't exist if everything were reimplemented from scratch.)

[Keith, 2013-11-07 07:25:09]

On 2013/11/07 00:04:43, benrg wrote:
> I don't see why tempoHideNote should be a context property 
> and BarNumber.break-visibility a grob property, for example.

In that example, it would probably have been better design if tempoHideNote were
a property of MetronomeMark, because it applies conceptually to only that
graphical object.

Often, though, the distinction between context properties and grob properties
comes from the fact that each context creates many grobs.  \set... tells the
context how to behave, while \override... tells the context to relay an
instruction to each of a particular type of grob that it makes

\set Score.currentBarNumber = 3   
% because the Score holds a single counter

\set Score.barNumberVisibility = #(every-nth-bar-number-visible 5) 
% tells Score to create a BarNumber every fifth measure
% (maybe barNumberFrequency would be a better name)

\override Score.BarNumber.break-visibility = #end-of-line-invisible
% Each individual BarNumber is created with this rule and applies
% it after line-breaking to decide what to print

\override Score.BarNumber.color = #blue
% an example that obviously applies to the individual graphical objects

There is one case where the conceptual difference between context property and
grob property is clear, but the naming makes things confusing. 
http://code.google.com/p/lilypond/issues/detail?id=2812

Maybe the text need not describe the implementation of context- and grob-
properties so much, but it is in any case a good addition to the docs.

[dak, 2013-11-10 09:46:27]

On 2013/11/07 00:04:43, benrg wrote:
> As someone who barely understands LilyPond's internals I appreciate this
> explanation, but it still leaves me confused. It seems to be saying that grob
> properties are an additional hierarchical override system below the level of
> context properties, but I don't see why that's needed when context properties
> already behave in a similar way.

Not similar enough.  Grob definitions implement a stack in several respects.

> Also, the assignment of properties to the
> context or grob "genders" seems somewhat arbitrary; I don't see why
> tempoHideNote should be a context property and BarNumber.break-visibility a
grob
> property, for example.

So what?  If you find something that logically is tied to grob to be implemented
as a plain context property or the other way round, feel free to report this.

This section can't possibly explain the raison d'être for every single property.

> Especially now that there is a unified dot syntax, could \set and \override be
> made synonyms that work out internally what kind of property to set, making
the
> distinction an internal detail that most people could ignore?

No.  Internals of grob definitions are sufficiently different that this is not
feasible without a major redesign of the data structures.  And while it is
popular to shout "then do a major redesign" and they actually do happen, they
take years and more shouting will not change that.

> (This is a clarification request, not a feature request. I find it helpful if
> documentation mentions which features of a design are historical accidents
that
> wouldn't exist if everything were reimplemented from scratch.)

They are most certainly not a "historical accident".  They were closer at some
point of time, but performance was prohibitive, so they quite intentionally
diverged.