David Elaine Alt finds that a major obstacle to understanding lilypond is
the lack of a comprehensive (and/or comprehensible) object model. The
question was asked: Does anyone really understand what a Voice is?
I think there are two levels at which object models need to be understood:
the user level and the developer level. Users only need to know *what*
the object is; developers need to know *how* the object is implemented as
well.
I think I have a decent lilypond object model from the user level, and a
partial model (with some holes remaining) at the developer level.
I thought I'd raise the issues here, with the idea that maybe we can
develop some useful descriptions of the lilypond object model that can
help users.
There is a description of contexts and engravers in the Learning Manual
(Section 3.3), another one in the Notation Reference (Section 5.1), and a
third in the Contributor's Guide (Section 10.1). Rather than try to edit
any of those, I'd like to propose my mental model. Maybe we can get to
something simpler that will help explain things (but maybe not).
So here we go -- comments and suggestions are welcome.
%%% Start of model
Contexts are LilyPond objects that contain properties, music expressions,
and translators. Some contexts, like Score and Staff, can contain other
contexts as well. Other contexts, like Voice, are bottom contexts and
cannot contain other
contexts.
Contexts are responsible for controlling the output (printed or midi) of
the music they contain. They do this by calling translators in the
environment of the context properties.
Translators are program elements that convert music expressions to output.
Engravers are translators that create printed output. Performers are
translators that create midi output.
Translators examine the music expressions that are contained in the
context, and create output elements. For the case of engravers (which
create graphical output), the output elements are grobs. The grobs have
properties that are used to create their appearance on the page.
After all the grobs are created, the spacing engine takes over and tries
to make an esthetically pleasing layout that fits in all the grobs. These
are then committed to the page.
If we want to change the layout, we need to change the properties of
either grobs or contexts. Changing these properties affects how the
layout engine tries to pack the grobs together.
%%%% End of model