Re: Break_Align_Order-3

[Mats Bengtsson]

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