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.