Re: constructive criticism

[Mats Bengtsson]

> I have often clicked a link to find more about a subject instead of 
> infact finding more about that subject I find scheme stuff.
>
>
> These issues are not exactly bugs but style issues and matters of 
> opinion, ie a programmer will think that more information about tremolos 
> should be the scheme stuff, and a nonprogrammer would hope for more 
> examples or different types of tremolos.

In principle I agree, but in reality this would lead to a manual that's
1000 pages long if you really want to include example of all possible
settings of all possible properties. Most of what you call "scheme
stuff" is just lists of properties that can be set. The only "Scheme"
about it is that the values are expressed in Scheme syntax.
I would not separate between programmer/nonprogrammer but between
basic/advanced user of LilyPond since setting properties is the main
method to influence the layout in LilyPond.

The step from basic to advanced user is clearly a major threshold but
does not involve learning all about Scheme but rather to learn the
mechanisms to set properties and the syntax used. The sections on
"Setting Variables" and "Fine Tuning layout" in the Tutorial try
to explain these aspects.
I also sketched a slightly more elaborate instruction in an email
some months ago, thinking that it might a good addition to the manual
but haven't yet received any response on if it is useful or not.
See http://mail.gnu.org/archive/html/lilypond-user/2003-10/msg00195.html

A first step to improve the usability of the "programmer reference"
(which in my opinion is a misnomer) would be to give more explicit
explanations of the possible values for each property.
One problem is that the set of possible values may be different for the
same property depending on what kind of object you set it on, but in
most cases that's not a problem.

   /Mats