Re: An overview of the system

[Erik Sandberg]

On Sunday 11 December 2005 07.33, Don Blaheta wrote:
> It all started with wanting to just move over a few pieces of text, but
> finally I sat down and worked my way through the labyrinth of figuring
> out how the system works.  The problem is that there are a lot of
> high-level concepts, like "grob" or "engraver", that are never really
> explained all in one easily-findable place in the docs (well, not that I
> found), so it's hard to understand the finicky stuff.  Like, why use
> \set sometimes and \override other times.  Anyway, I think I figured all
> that out, and in the course of taking notes I have something that might
> fit well into the LP docs somewhere.  I've interspersed the prose with
> asterisked comments and questions that highlight things that are bugs in
> the docs or that I still didn't quite understand (or both).
>
> Hopefully someone else finds this helpful....
>
>
> A context is an environment into which you enter your music; it can be
> created anonymously (\new) or named (\context).  If you create a new
> context, either anonymously or with a new name, it puts that context
> right where you are in the enclosing context, and effectively puts your
> cursor at the beginning of that brand-new context.  If on the other hand
> you open a context that has the same name as a previously created
> context, you are not creating a new context, but rather sending your
> cursor back to insert at the end of that existing, named context.
> * Voice claims it can't contain other contexts; but it can contain other
>   Voice contexts.

no. You can write
\context Voice=A { c d \context Voice=B {e f} g}

but this will make B a sibling of voice A.

The behaviour is made more clear with this example:

\context Staff=A \context Voice=V {c d \context Staff=B {e f } g}

> Each syntactic thing you can do for actual music entry---i.e. most of
> what you type inside \score other than managing contexts---is
> interpreted as a musical expression, much as 3+4 might be interpreted as
> a mathematical expression.  As each expression is read in, it is
> classified as an Event (atomic events, e.g. NoteEvent) or a Music (for
> expressions composed of other expressions?).  This music expression is
> then handed off to an engraver.
> * what is a Music really?

"Everything is Music". Events is a special case of Music (those that don't 
happen to have child expressions). The most useful way to describe it is as a 
tree. Each Music is a tree, which often consists of several subtrees, which 
also are Music. Music is also called "music expression"

There's one thing that can be confusing:
In some cases, a .ly file can contain a call to a music functions:
{ c d \quoteDuring #"foo" s4 e }
The "\quoteDuring #"foo" s4" is a music function call. When parsing this file 
into a music expression, the \quoteDuring expression is substituted for the 
function's return value in the Music tree. (the function returns a magical 
expression that somehow fills in notes the way you expect)

In 2.7+, everything is Music (the class Event has been removed). 

> * what is the difference between SkipEvent (e.g. s4) and SkipMusic (e.g.
>   \skip 4)?

try this:
\new StaffGroup<<
{s2 \new Staff {c4}}
{\skip 2 \new Staff {c4} }
>>
s2 creates a new staff, \skip doesn't.

> * Typo in OverrideProperty SYNTAX def ("propery"); and syntax has
>   changed from
>   \property Ctxt.Obj \override #'prop = #newval
>   to
>   \override [Ctxt.]Obj #'prop = #newval
thanks, fixed
> * Is OutputPropertySetMusic what is now \set?  Or PropertySet?
no, it's \outputproperty. it's rather complicated stuff, look for examples in 
regressino tests
> * No SYNTAX for a lot of events e.g. FingerEvent, BarCheck
> * Could we see the subclasses of each music expression type?
there is only one class in 2.7, Music.
> * In Music properties, no indication *which* types of expr each property
>   can belong to
Any property can belong to any music type, it's just that they may be ignored. 
Iterators and translators decide that. If you need to know more, you can 
either copy what others already did, or you can read the source code for 
hints (usually, only gurus tweak Music properties, and most gurus know how to 
read source code)

In general, i'd advice you to look directly in the .scm files (scm/* wherever 
lilypond's data files are), rather than the online docs. The .scm files 
sometimes contain additional hints.

> Engravers are LilyPond entities that accept music expressions of
> interest to them and produce graphical layout objects ("grobs").  Most
> engravers will only care about certain types of music expressions; the
> NoteHeadEngraver won't care about a LyricEvent, for instance.  Each kind
> of engraver comes by default in certain kinds of contexts, but this can
> be modified with \remove and \consists.  The engraver works by looking
> at the properties of the specific music expression it was given (the
> pitch, duration, etc) and the properties of the current context.

Note also that Engraver is a subclass of Translator; engravers are used for 
graphical output. Performers are used for midi output, they are a different 
subclass of Translaotr.

> Each context has a variety of properties that keep track of where the
> engraving process is---what measure it's in, whether it's in the middle
> of a triplet, etc.---as well as some general properties of the context,
> like the stanza number or whether to beam.  

BTW, the time keeping properties are usually stored centrally in the Score 
context; the other contexts "inherit" those property settings. (You can also 
tweak this to be set per staff, look for Timing_translator in regression 
tests)

> So as each musical expression is read in, it is passed to all engravers
> in currently active contexts that will accept that type of event/music,
> and these engravers look at the expressions and at the contexts'
> properties, and generate grobs.  [See: grob-interface]
> * Are musics "passed" only when they're done?
> * What happens to events that are "inside" the musics?
Only events are sent to translators. There are some exceptions, but they will 
be eliminated soon so please ignore them.

Each event is sent once only.
> * In what order are the contexts visited---inside out?
Bottom up. Events are sent to Voice context, which forwards the events to 
Staff if they can't be swallowed.

> The created grobs have properties that can be modified just as for
> contexts, except with \override instead of \set---the idea is that the
> engraver would calculate values for each grob property, but you might
> want to override its choices by some offset amount.  Here, unlike with
> \set, you *must* say which kind of object you're overriding for (and
> possibly also which context it's in).  (\revert to delete change)  These
> properties control exactly where and how an object is laid out.
> * When a 'direction property is labelled "Up or down, left or right?",
>   and its value is a number, this is confusing.
-1 generally means down/left iirc (think time and octave)
> * Again, not always clear which properties go with which grobs
>
> Once all the grobs are created, actually *printing* the engraved music
> is a trivial walk of the grobs, since they have all their relative size
> and shape and position information.

no, that's where the actual typesetting happens. It's the *really* difficult 
part. Grobs are translated into Stencils, and I think the Stencil->graphics 
conversion is the easy part.

Hope this helps.

-- 
Erik