Re: Quit [now definitely O/T]

[David Kastrup]

Kieren MacMillan <address@hidden> writes:

> Hi David,
>
> [By the way, since it's apparently open season on posting style
> criticism: your consistent lack of salutation and valediction in your
> posts makes you seem rude, curt, and above all patronizing.]

Perfectly accurate.

>> "Reasonable" entails a collective effort not to repeat avoidable work
>> and frustration.
>
> e.g., the GDP and the 000s of hours Graham P personally has put in to
> improving the docs...?

Where does the GDP document the meaning of the acronym "GDP"?

>> presumably _is_ something like coding style
>
> c.f. 
> <http://lilypond.org/doc/v2.13/Documentation/contributor/Code-style#Code-style>
> 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.  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.

>> or idea behind Lilypond
>
> c.f.
>   
> <http://lilypond.org/doc/v2.13/Documentation/contributor/Overview-of-LilyPond-architecture#Overview-of-LilyPond-architecture>

I have found the contributor's guide by now (not mentioned in the web
resources AFAICS).  It gives some sort of outline, but lacks examples
that walk the prospective programmer through the skeleton of what he
needs to do.

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

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.

-- 
David Kastrup