Re: Quit [now definitely O/T]

[Carl Sorensen]

David,

I appreciate your persistence in this.  I think that you are having part of
the difficulty in this conversation because it's on -user, not on -devel.

The modifications to anything except input files (which use lilypond code
and embedded scheme) really involve knowledge that's primarily discussed on
-devel.



On 11/11/09 1:36 PM, "David Kastrup" <address@hidden> wrote:

> Kieren MacMillan <address@hidden> writes:
> 
>> 
>> c.f. 
>> <http://lilypond.org/doc/v2.13/Documentation/contributor/Code-style#Code-styl
>> e>
>> What needs to be added/improved? Once again, I'm sincerely asking,
>> since you obviously still have questions about Lilypond coding style
>> that weren't answered by that page (and surrounding ones).
> 
> Uh, have you read it?  It worries about things like indentation, says to
> prefer C++ over Python (but Python please in "PEP 8" whatever that fancy
> acronym is supposed to be), and some identifier names.

I agree.  But at least for now, the coding style rules for LilyPond are the
GNU coding style without modifications.  Hence, the limited stuff that seems
to not make much sense.

> It does not say
> what kind of code to put where for what reason.
> 
> That is: it tells you minor details about how source should be formatted
> once you know perfectly what you are doing and which part of the code is
> appropriate to use.  Namely it tells you about the difference between
> something that compiles and fits in with the rest of the _code_.  It
> does not tell you what language/classes/operations to use to implement
> what kind of task.

That's right.  This kind of documentation does not exist.  Several years ago
I couldn't understand LilyPond at all, so I started trying such a document.
It didn't get very far and it wasn't very accurate (but it did get a
reference in Erik's thesis as the only available description).

I'm still not sure I'm up to speed.  I have some knowledge, but probably
just enough to be dangerous.  I could write a little bit better description,
but probably not a really *good* one.

> 
>>   <http://lilypond.org/web/images/thesis-erik-sandberg.pdf>
>> Same question as above.
> 
> The thesis is a thesis.  It is unclear what state of Lilypond it
> documents, and what the current state of Lilypond embeds from what is in
> the thesis.
> 
> And some thesis on the web is not a good substitute for programming
> docs.  Because it does not evolve with the program.

I agree, but the fact is that the thesis *is* currently the best description
we have of LilyPond's overall architecture.  And it is current, and will
likely be current at least through all of 2.x.  Details have changed, but
not the overall structure.

>> 
>>> The internals documentation should likely spell out the layers of C+
>>> +, Scheme, Music macros and what one can hope to reasonably implement
>>> in what layer.  What new functionality requires equivalence of new
>>> engravers or performers, can one implement them in Scheme, does one
>>> need C++, and what exactly does one _do_ when creating them?

I agree that this information is needed.  It doesn't belong in the internals
documentation, which is a dictionary, as described before.  It probably
belongs in the Contributors' Guide, or a separate Program Architecture
manual.

Would you be willing to create an outline of a Program Architecture manual?
It could have headings that relate to your questions, and then we could fill
in the answers, roughly at first and later in greater detail.

>> 
>> The introductory page
>> <http://lilypond.org/doc/v2.13/Documentation/contributor/Overview-of-LilyPond
>> -architecture#Overview-of-LilyPond-architecture>
>> does spell this out, I believe.
> 
> I don't see this.  Mostly, it points to sources for reference.  That's
> useful to some degree.  But if people write sources with only sources
> for reference, any design inherent in the first generation of the
> sources is going to become less and less discernible with successive
> layers of code.

As a matter of fact, Han-Wen is consistent in telling us to "Use the Source,
Luke", rather than referring to other materials. So referring to the source
is important, but need not be exclusive.

> 
> More educational than studying how existing code is written would be to
> study how the code is _supposed_ to be written.  Some self-contained
> example with well-defined functionality that sits well in the scheme of
> things.  If people can't make their own code as simple and
> self-contained (or see existing "real" code much uglier), that is an
> incentive for improving the state of their and preexisting "real" code.

I think this is a great idea -- a sort of Learning Manual for programming.
Aimed not at users, but at developers.  Something that works through a
simple engraver, and describes the key components that are used.

I don't know that we have anybody who knows enough and has the time and
interest to write such a beast, but it would probably help increase the
number of developers on the project.  I've cross-posted this tho -devel;
let's see if there's any interest in pursuing this.

I'm certain that if somebody started writing such a manual and asked for
feedback on -devel, the feedback would come.

Thanks,

Carl