An overview of the system

[Don Blaheta]

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.

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?
* what is the difference between SkipEvent (e.g. s4) and SkipMusic (e.g.
  \skip 4)?
* Typo in OverrideProperty SYNTAX def ("propery"); and syntax has
  changed from 
  \property Ctxt.Obj \override #'prop = #newval
  to
  \override [Ctxt.]Obj #'prop = #newval
* Is OutputPropertySetMusic what is now \set?  Or PropertySet?
* No SYNTAX for a lot of events e.g. FingerEvent, BarCheck
* Could we see the subclasses of each music expression type?
* In Music properties, no indication *which* types of expr each property
  can belong to

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.  

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.  These properties can be
modified with \set, and the changes remain to the end of the context,
affecting how that context's engravers do their job.  (To make changes
not last that long, you can \set them to something else, \unset them, or
use \once to make them only last for one time step in the first place.)
[see also: 9.1.2 Changing context properties on the fly ff.]
* 7.3.6 Switching the melody associated with a lyrics line; doesn't
  currently have its own node

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?
* In what order are the contexts visited---inside out?

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.
* 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.


-- 
-=-Don address@hidden<http://www.blahedo.org/>-=-
"On a day such as this you should insist on more than the truth" --Pere Ubu