Re: Creating LilyPond Object Models

[Thomas Morley]

2015-04-23 1:29 GMT+02:00 Carl Sorensen <address@hidden>:
> 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?

Speaking as a user, I always thought about a "Voice" like a
_musician_, never had problems with that thinking.

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

Great!

>
> In my mind, this model explains how LilyPond works well enough that I can
> make happen what I need to make happen.
>
> If I've got something wrong, please let me know.  If you have questions
> about this model, please let me know.
>
> If you think this model isn't complete enough, please help me to
> understand why.

There are a few other possible things coming into play. Toplevel
settings like global-staff-size etc or paper-settings (fixed and
variable) like two-sided or system-system-spacing etc

>
> Thanks,
>
> Carl
>



Thanks,
  Harm