lilypond-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Proposed manual change


From: Carl Sorensen
Subject: Re: Proposed manual change
Date: Thu, 17 Dec 2009 20:07:08 -0700



On 12/17/09 5:55 PM, "Graham Percival" <address@hidden> wrote:

> On Thu, Dec 17, 2009 at 05:04:05PM -0700, Carl Sorensen wrote:
>> The simplest form of music function, the simple substitution function,
>> requires virtually no knowledge of scheme, as all of the output is created
>> in .ly code.  Granted, there is a Scheme wrapper, but the Scheme wrapper is
>> a constant.  All that is needed is to decide upon the variable types, figure
>> out the type checks, and put the .ly code in the appropriate place.   I
>> believe this level of sophistication is available to the advance LilyPond
>> user who is not a Scheme programmer.  I propose that this section go into
>> the NR.
> 
> Tricky!
> 
> My first thought is that I wish we had somebody dedicated to
> working on the scheme stuff; I'd love to leave this up to a
> trusted person and thereafter ignore the debate.  But since that's
> probably not happening within the next 6 months, I guess I'd
> better plunge in.

Actually, I think that my next project is to put a little bit of work into
Extending LilyPond (EL).  This summer I started a rewrite and rearranging of
NR 6, but is was such a huge job I never got anywhere.

With the EL in the rough shape it's in, I can start working in whatever
order I want; it's so bad that messing it up for a while won't be a problem.

> 
> 
> My second thought is that I have no complaint about it being in
> the NR; it's not intended to be sequential, so having the scheme
> tutorial in Extending (and not in the NR) isn't a problem for
> having scheme stuff in the NR.

Don't consider this proposal to be a change in EL.  Consider it to be adding
a section to the NR.  I think that this section belongs in the NR.  The EL
will take care of itself later.

> 
> My third thought is that we don't know what kind of a manual
> Extending should be... is it sequential?  If so, then the gap
> between the tutorial and whatever comes after the "scheme wrapper"
> stuff might be a bit jarring.

I think I know what EL should be.  There should be a tutorial similar to the
LM, that teaches how to get started in LilyPond advanced programming, how to
navigate the IR, gives some description of the architecture as it relates to
creating tweaks, etc.  Call this EL1 -- LilyPond programming tutorial.

The rest of the EL is a collection of tips and tricks, or samples of useful
code.  Think LSR or NR for programming.  It's probably more like the LSR
than the NR, because I can't imagine we'd ever be able to create an
exhaustive list of what can be done in Scheme, but I'm picturing sections
for a certain type of work (probably with some snippets from the LSR used to
explain them).

> 
> My fourth through sixth thoughts relate to the difference between
> the LM and NR, and perhaps Extending should follow the same mold.
> But this circles back to "what kind of manual do we want Extending
> to be".

EL is a combination of LM and NR, because the size of the manual will be
much smaller than the combined LM and NR.  If we need to, we can separate
out the two pieces of EL.  But I don't think we need to.


> 
> 
> *sigh*
> We don't have enough clarity about the advanced docs.  My
> preference is to leave it where it is for now -- even if some
> scheme material ends up back in the NR, I think it would need to
> be somewhat rewritten.

Have you looked at the patch?  I think that what I've written can go in the
NR right where I put it.  I haven't brought it up to documentation standards
yet, but I'm willing to do so if we can agree that it would be a good thing.
And if you don't think the writing level is appropriate for the NR, I'll be
happy to get it into shape.

BTW, 2/3 of the people who care most about it already agree (me and Trevor
-- maybe it's 1/2 if we add Jon to the mix).
> 
> How important is this?  I could postpone the website work for yet
> another week and look into this seriously.  But the big problem is
> that even once we're decided what should be done, the advanced
> docs will need 5-10 hours of work to get the sections arranged and
> the flow between them working.  And I have nobody remotely
> qualified for this; there's two new doc contributors in the
> pipeline, but they're still at the level of being told not to
> merge sections and subsections, and forgetting to close} texinfo
> commands.  Best-case scenario is that they might tackle it in 4
> months.  Could we just dump this question into the tracker?

My suggestion is to leave the EL in the tracker, but move ahead on the NR.

The motivation behind this is *not* to get the EL in shape (although I have
that goal as well).  The motivation is to get *something* in the NR so that
when a user wants to come up with a shortcut syntax for some complicated
tweak that goes into the music stream we can say "write a simple
substitution music function -- See NR 5.x".

Thanks,

Carl





reply via email to

[Prev in Thread] Current Thread [Next in Thread]