Re: lilypond programming manual

[Carl Sorensen]

On 9/28/09 1:14 PM, "Graham Percival" <address@hidden> wrote:

> On Sun, Sep 27, 2009 at 06:53:26PM -0600, Carl Sorensen wrote:
>> 
>> On 9/27/09 11:55 AM, "John Mandereau" <address@hidden> wrote:
>> 
>>> Le dimanche 27 septembre 2009 à 17:37 +0100, Graham Percival a écrit :
>>> Certainly.  However, when we decide time has come to significantly
>>> expand this appendix and it gets too big to remain an appendix, we'll
>>> have to reword the reading guidelines so the reader doesn't feel he
>>> should even read this chapter, e.g. by recommending that "all this
>>> manual should be read from cover to cover, except the last chapter
>>> "Scheme tutorial", that can be read later to make better use of Chapters
>>> 5 and 6 of the Notation Reference, for example."
>> 
>> I think that my preference would actually to create a LilyPond Programming
>> manual, with the Scheme Tutorial and a rewritten NR6.  I don't think that
>> NR6 is actually Notation Reference.  That particular chapter has seemed to
>> me to be out of place anyway.
> 
> I like this idea; we could even make the IR into a series of
> appendices for this programming manual.
> 
> The immediate question is whether we should bother doing it now.
> I'm not talking about actually writing it -- we definitely can't
> do anything other than moving doc sections around and slightly
> changing the IR generation from scheme.  So
> 1) do we set everything up, and have a half-baked manual?
> (which is admittedly still no less useful than the current
> situation)
> 
> 2) do we keep the status quo, and deal with the moving files
> around later?
> 
> My preference is for #1; I've been dealing with build issues for
> the past few weeks, so it's relatively fresh in my mind.  Also, it
> gives everybody (especially translators) a more stable foundation.

+1.  While we're in flux, let's get the right organization.

I've got a halfway done rewrite of NR6; it never got finished because I
couldn't get a logical structure that worked.  I think that's mostly because
we really need to handle programming (creating LilyPond extensions using
Scheme constructs, rather than LilyPond constructs) separately from notation
(which is using LilyPond constructs to get the desired notation).

However, I don't think that the IR should become an appendix to the
programming manual.  Many tweaks are done in the form of \override (LilyPond
syntax) and need information about grobs and properties from the IR.

I think we need to be careful about the name of this manual.  There are two
different kinds of LilyPond programming -- writing LilyPond source code and
writing LilyPond extensions in .ly files.  I think the programming manual is
aimed at LilyPond extensions, not LilyPond source (the source programming
info is in the Contributors' Guide).  So I'd like to figure out a manual
name that captures the thought of extending (which is also apt because the E
in guile stands for "extensions".  Could the title be something like
"Extension Reference"  or "Extending LilyPond", or "Application Extension",
or "LilyPond Extension"?

Thanks,

Carl

> 
> Cheers,
> - Graham
> 
> 
>