Re: (doc help) set vs. override

[Han-Wen Nienhuys]

Graham Percival wrote:
> Here's what I came up with.  It's probably inaccurate and misleading, 
> because I don't understand what I'm talking about.  If you can correct 
> this, please do.  Please do *not* attempt to explain it.  Just change 
> the text below so that I can add it to the manual.
> - Graham
>
> ----
> @node \set, \override, and \tweak
> @section \set, \override, and \tweak
>
> There are three different commands which modify properties.
>
> @itemize @bullet
>
> @item @code{\set} changes properties of a context, and can modify
> more than one graphical object.  For example, @code{fontSize} is
> a context property (and therefore modified with @code{\set})
> because it changes the behavior of several types of grobs
> (noteheads, rests, etc).
>
> @item @code{\override} changes properties which are specific to
> one graphical object.  For example,
>
> @item @code{\tweak} changes properties of an object which results
> directly from input.  For example, @code{\tweak #'color #red} will
> change the color of the next object.
>
> @end itemize
>
> As a rule of thumb, if you can figure out a single type of Grob that
> the tweak would modify, then it probably requires an @code{\override}.

I'm not sure how you should  change it, but the above is probably too 
broadly and inaccurately explained to be of much practical use.

Here's the breakdown:

Contexts can have properties, they are usually named  in studlyCaps. 
They mostly control the translation from music to notatino, eg. 
localKeySignature (for determining whether to print accidentals), 
measurePosition (for determining when to print a barline).

Context properties can change value over time while interpreting a piece 
of music; measurePosition is an obvious example of this.


There is a special type of context property: this is the element 
description. These properties are named in StudlyCaps (starting with 
capital letters). They contain the "default settings" for said graphical 
object, as an association list.

See scm/define-grobs.scm to see what kind of settings there are. 
\override changes this initialization list;

 \override Foo #'bar = #baz

is more or less equivalent to

  \set Foo = #(cons (cons 'bar baz) <previous value of Foo> )

The value of Foo (the alist) is used to initialize the properties of 
individual grobs. Grobs also have properties, named in scheme style, 
with dashed-words. The values of grob properties change during the 
formatting process: formatting basically amounts to computing properties 
using callback functions.


Since element descriptions are really context properties, they have the 
same inheritance mechanism, and may change over the interpretation of a 
piece.

These are the general mechanisms.


Both \tweak and fontSize are specialized hacks that use custom Engravers 
to do their jobs.

* \tweak is intended to change individual elements of chords, because

 \override NoteHead ...
 < c e g >

would change all NoteHeads. Outside of chords, using \tweak may lead to 
surprises. Eg. it won't work for individual notes, eg

  \tweak #'color #red c4

will not change the note at all; this is due to the structuring of the 
music expression. "c4" really is

 <c> 4

(try \displayMusic to see how it is represented).

Using tweak works if you do

 < \tweak ... c > 4


* fontSize is a special property: it's processed by Font_size_engraver, 
and it's rather unique in its effect. Since it's an exception, better 
not take that as the norm. The effect of fontSize is equivalent to doing 
\override ... #'font-size for all pertinent objects. It got its own 
property, since it's such a common change.

--

Han-Wen Nienhuys - address@hidden - http://www.xs4all.nl/~hanwen

LilyPond Software Design
 -- Code for Music Notation
http://www.lilypond-design.com