Documentation of Architecture / Design?

[Douglas A Linhardt]

All,

I've recently gotten involved in the lilypond cause (2 bug fixes submitted, a
couple of features underway).  My problem is I don't have a firm understanding
of how everything comes together.  I've read through the Programmer's Reference
(PR), but it isn't what I'm looking for.

I think what's needed is a document describing the following things:

- What's a grob, and how is one used?

- What's a smob, and how is one used?

- When is each C++ class constructed and used (sort of in the PR)
        Music classes
        Contexts
        Engravers
        Layout Objects
        Grob Interfaces
        Iterators (hven't found them at all in the PR)
        (Others ?)
                
- How do the classes interact with each other
        A UML diagram would be nice)

- Which properties are accessible from the class types
        Can you get to Context properties from a Music object?
        Can you get to Music properties from a Context object?

- What is the relationship between C++ classes and Scheme objects?

- How do Scheme procedures get called from C++ functions?

- How do C++ functions get called from Scheme procedures?

- What is the flow of control in the program?
        Does the parser make Scheme procedure calls or C++ function calls?
        How do the front-end and back-end get started?
        How do the front-end and back-end communicate?

- Where is the functionality associated with KEYWORDs?  What
Contexts/Properties/Music/etc. are available when they are processed?
        \override
        \stemDown
        \relative
        \notes
        \autochange
        (etc.)

- How do you decide if something is a Music, Context, or Grob property?
        Why is part-combine-status a Music property when it seems (IMHO)
        to be related to the Staff context?

        I'm adding a property to affect how \autochange works.  It seems to
        me that it should be a context property, but the Scheme autochange
        procecure has a Music argument.  Does this mean I should use
        a Music property?


I can (and have) searched the code for this kind of information, but with
limited (almost non-existent) comments, it's VERY difficult to get a foothold.
Also, the PR sometimes doesn't add much clarity:

        — Function: Context_specced_music_iterator::constructor
                Construct a Context_specced_music_iterator music iterator

I would not be surprised if some eager potential developers turned away because
of these deficiencies.

I don't know the system well enough to answer even half of these questions.  I
could start a document by filling in what I've learned so far, but my answers
would have to be checked, and there are lots of things that would need to be
filled in by others.

I think most of this could be discussed at the Context/Music/Grob level without
drilling down to the individual classes, so maintenance of the document would be
minimal unless major re-architecture occurs.

Is anybody interested in helping out on this if I get the ball rolling?

Doug