Re: [Lilypond-auto] Issue 2870 in lilypond: \single \omit and \hide need user-level documentation and examples

[lilypond]

Updates:
        Summary: \single \omit and \hide need user-level documentation and 
examples

Comment #5 on issue 2870 by address@hidden: \single \omit and \hide need  
user-level documentation and examples
http://code.google.com/p/lilypond/issues/detail?id=2870

Let me give you a short technical rundown:
"grobs", graphical objects, are items carrying properties that are created  
in the engraving stage of LilyPond.

A grob is created by engravers, through a call of ly:engraver-make-grob  
specifying an engraver instance, a grob type, and a cause (the cause being  
either a "stream event" that is a direct or indirect consequence of a music  
event, or another grob).

The initial values for a grob are derived from several sources.  First,  
every grob has its own global defaults (which are established using  
\grobdescriptions in the definition of the global context).  Then every  
active context has its own sets of overriding grob properties (which you  
can query with ly:context-grob-definition).  You can change a context's  
idea of its overriding grob properties with \override, either for the whole  
life of the context in a context modification (those are the things  
starting with \with), or at individual times in the music stream with  
\override and \revert.  Whenever an active context does not have an  
override of its own for some grob property, its parent context (and  
ultimately the Global context) will provide it.  So that's the normal  
template where grobs get their values by ly:engraver-make-grob.

However, it is not the whole story.  After the values have been initialized  
in this manner, LilyPond will consult the cause of a grob.  If the cause is  
a stream event containing a 'tweaks field, any tweaks mentioned in there  
will get applied to the grob.  So the information in overrides travels  
through the context, while the information in tweaks travels directly  
through the music causing a grob.

As a result, tweaks have far fewer side-effects.  If LilyPond loses track  
of the connection between music and grob, however, a tweak may have no  
effect at all.

\single will convert one or more overrides into a \tweak on the following  
music object.  Since ly/property-init.ly contains a lot of override  
definitions, this is rather handy to have them available for use as a  
\tweak without having to think up new names for them.

contexts manage their grob property overrides as a sort of stack, \revert  
pops the latest override from this stack.  Since a \tweak has no way of  
knowing the value "underneath" a stack element in a context's override  
stack at the time it is ultimately called, one can't turn a \revert into a  
tweak.

Hope this helps.