Re: Proposed manual change

[Graham Percival]

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.


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.

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.

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


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

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?

Cheers,
- Graham