Re: Fill in section "\set vs \override" (issue 21820045)

[dak]

Reviewers: Trevor Daniels, benrg, Keith,

Message:
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.

Description:
Fill in section "\set vs \override"

Please review this at https://codereview.appspot.com/21820045/

Affected files (+53, -13 lines):
  M Documentation/notation/changing-defaults.itely


Index: Documentation/notation/changing-defaults.itely
diff --git a/Documentation/notation/changing-defaults.itely  
b/Documentation/notation/changing-defaults.itely
index  
6174456582fabd04769dee2d03b51e98e9a7febf..3dc39edd9b88e1a238ea2d8bad24895ce4887551  
100644
--- a/Documentation/notation/changing-defaults.itely
+++ b/Documentation/notation/changing-defaults.itely
@@ -2401,20 +2401,60 @@ one encountered in the input file.
 @node set versus override
 @subsection @code{\set} vs. @code{\override}

address@hidden TODO -- This section is probably unnecessary now.
-
address@hidden
-We have seen two methods of changing properties: @code{\set} and
address@hidden  There are actually two different kinds of
-properties.
-
address@hidden is a special property: it is equivalent to
-entering @code{\override @dots{} #'font-size} for all pertinent
-objects.  Since this is a common change, the special
-property (modified with @code{\set}) was created.
-
address@hidden ignore
address@hidden TODO Should't a bunch of that be explained earlier?

address@hidden \set
address@hidden \override
+Both @code{\set} and @code{\override} manipulate properties
+associated with contexts.  In either case, properties heed the
+hierarchy of contexts: properties not set in a context itself show
+the values of the respective parent context.
+
+Values and lifetime of context properties are dynamic and only
+available when music is being interpreted, @q{iterated}.  At the
+time of context creation, properties are initialized from the
+corresponding context definition and possible context
+modifications.  Afterwards, changes are achieved with
+property-setting commands in the music itself.
+
+Now grob definitions are a special category of context properties.
+Since their structure, bookkeeping and use is different from
+ordinary context properties, they are accessed with a different
+set of commands, and treated separately in the documentation.
+
+As opposed to plain context properties, grob definitions are
+subdivided into grob properties.  A @qq{grob} (graphical object)
+is usually created by an engraver at the time of interpreting a
+music expression and receives its initial properties from the
+current grob definition of the engraver's context.  The engraver
+(or other @q{backend} parts of LilyPond) may subsequently add or
+change properties to the grob, but that does not affect the
+context's grob definition.
+
+What we call @q{grob properties} in the context of user-level
+tweaking are actually the properties of a context's grob
+definition.  In contrast to ordinary context properties, grob
+definitions have the bookkeeping required to keep track of its
+parts, the individual grob properties (and even subproperties of
+them) separately so that it is possible to define those parts in
+different contexts and have the overall grob definition at the
+time of grob creation be assembled from pieces provided in
+different contexts among the current context and its parents.
+
+Grob definitions are manipulated using @code{\override} and
address@hidden and have a name starting with a capital letter
+(like @samp{NoteHead}) whereas ordinary context properties are
+manipulated using @code{\set} and @code{\unset} and are named
+starting with a lowercase letter.
+
address@hidden tweak, relation to @code{\override}
address@hidden \tweak
address@hidden \overrideProperty
+The special commands @code{\tweak} and @code{\overrideProperty}
+change grob properties bypassing context properties completely.
+Instead they catch grobs as they are being created and then
+directly set properties on them when they originate from a tweaked
+music event or are of a particular kind, respectively.

 @node Modifying alists
 @subsection Modifying alists