David Bobroff wrote:
If I may, I'd like to say something about the documentation in general.
From an end-user standpoint I'd have to say that the docs are the weakest
part of Lilypond.  I don't mean to say that they're bad.  I'm sure it is
all very well documented.  What I find problematic is that the docs go from
a fairly simple example of HOW THINGS WORK straight to a gory-details
nuts-and-bolts description of the minute workings of the program.  I don't
have a problem with that, either.  What I find lacking is much of anything
in-between.  For example:

\property Score.MultiMeasureRest \override #'expand-limit = #9

...was exactly what I needed to adjust the block rest behavior.  I didn't
need several paragraphs of dense description of how this mechanism works.
That I can save for later.

Now please, I'm not "complaining".  I think Lilypond is great.  It appeals
to me for many reasons.  I just think a "middle ground" level of docs would
be of great value to the new users as well as the "sometimes" users.  I
fall into this category.  I'll have a project, learn a bunch of Lilypond
tricks....and then forget them all before I have another project.  Should I
read the docs more?  Sure.  But knowing a bunch of specific operations
beforehand make it easier to generalize and make use of the nuts-and-bolts
docs.

I kind of agree, but my first priority (I've probably said for over a year that I will do this as soon as I get some time) is to rewrite the "fine tuning" sections of the manual. The point is that it would take too large space to include an example of every possible application of every property. Remember that most of the properties are common to a number of different graphical objects, whereas the documentation of each property currently is only written once (and then duplicated in the autogenerated part of the manual). Also, there are typically several ways to apply the same setting. Consider the setting shown above as an example. If you want the same setting in the full score or even in a "global.ly" file that you include in several scores, it would be better to put it within the paper section: \paper{ ... MultiMeasureRest \override #'expand-limit = #9 } whereas the version given above is more appropriate if you want to have different settings in different bars or in different staves, for example. My conclusion is that it's essential for most users to have an idea of the general principles of how to set a property. However, I agree that the current manual does not manage completely to describe these fairly simple principles in a clear way.

/Mats




_______________________________________________ Lilypond-user mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/lilypond-user

Reply via email to