Info about \set and \override.

diff --git a/ChangeLog b/ChangeLog
index 32f5d951c93c2f4d2ff4b7f298b6c623ed626d91..fbef4a8fd7985e122101ba188eb8b7512dc3f0c4 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -6,7 +6,8 @@
 
 2006-05-09  Graham Percival  <gpermus@gmail.com>
        
-       * Documentation/user/changing-defaults.itely: general editing.
+       * Documentation/user/changing-defaults.itely: general editing,
+       info about \set and \override.
 
        * Documentation/user/tweaking.itely, advanced-notation.itely:
        fixes from Dave Luttinen, thanks!

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 27876ddd0816babe2a2d6bff70485c725d04203d..6f508899869af62270e31ecd498d90a8c00881ea 100644 (file)
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -1177,6 +1177,7 @@ we will look in more detail at how to use the command in practice.
 * Layout interfaces::           
 * Determining the grob property::  
 * Objects connected to the input::  
+* \set vs. \override::          
 * Difficult tweaks::            
 @end menu
 
@@ -1539,6 +1540,57 @@ will not change color.  See @ref{Displaying music expressions} for
 details.
 
 
+@node \set vs. \override
+@subsection \set vs. \override
+
+We have seen two methods of changing properties: @code{\set} and
+@code{\override}.  There are actually two different kinds of
+properties.
+
+Contexts can have properties, which are usually named in
+@code{studlyCaps}.  They mostly control the translation from
+music to notatino, eg. @code{localKeySignature} (for determining
+whether to print accidentals), @code{measurePosition} (for
+determining when to print a barline).  Context properties can 
+change value over time while interpreting a piece of music;
+@code{measurePosition} is an obvious example of
+this.  Context properties are modified with @code{\set}.
+
+There is a special type of context property: the element
+description. These properties are named in @code{StudlyCaps}
+(starting with capital letters).  They contain the
+``default settings'' for said graphical object as an
+association list.  See @file{scm/@/define@/-grobs@/.scm}
+to see what kind of settings there are.  Element descriptions
+may be modified with @code{\override}.
+
+@code{\override} is actually a shorthand;
+
+@example
+\override @var{context}.@var{name} #'@var{property} = #@var{value}
+@end example
+
+@noindent
+is more or less equivalent to
+
+@c  leave this long line -gp
+@example
+\set @var{context}.@var{name} #'@var{property} = #(cons (cons '@var{property} @var{value}) <previous value of @var{context})
+@end example
+
+The value of @code{context} (the alist) is used to initalize
+the properties of individual grobs.  Grobs also have
+properties, named in scheme style, with
+@code{dashed-words}.  The values of grob properties change
+during the formatting process: formatting basically amounts
+to computing properties using callback functions.
+
+@code{fontSize} is a special property: it is equivalent to
+entering @code{\override ... #'font-size} for all pertinent
+objects.  Since this is a common change, the special
+property (modified with @code{\set}) was created.
+
+
 @node Difficult tweaks
 @subsection Difficult tweaks