Re: A quest through the docs

[Don Blaheta]

Quoth Graham Percival:
> The only line that might need explanation is the line-width.  These 
> commands obvious set values

Sure.  But sometimes we set values like this:

    indent = #0

and sometimes we set them like this:

    \set stanza = "1."

or this:

    \set Score.markFormatter = #format-mark-numbers

and sometimes we set them like this:

    \override LyricText #'font-shape = #'italic

or this:

    \override Staff.Stem #'transparent = ##t

And before you explain the differences between the three to five ways of
setting values, yes, I understand, but it's not immediately obvious when
meeting a new value for the first time which kind it is.  And the
quickest way to convey that information is with a simple three-line
example.

I mean, here's the thing: now that I *know* how ragged-right et al work,
I can look at 10.5.7 and see that it's "obvious" from that page how they
work.  And yet, when I first read that page, I didn't get it.

> but it doesn't make sense to sprinkle two dozen explanations about 
> staff-spaces throughout the manual.

That was a secondary point, but if your objection is to sprinkling
explanations, why not just sprinkle hyperlinks?  Add a parenthetical
"(measured in _staff space_)" after the word "line-width" on 10.5.7, and
have _staff space_ link to wherever it's explained.

> I'd say that three times (not counting the tutorial and chapter 4) is
> the absolute maximum number of times we should repeat info.

No need to repeat explanations, I think, thanks to hyperlinks.  But why
the objection to adding examples?  I think nearly every leaf-level page
in the manual could do with at least one example.

-- 
-=-Don address@hidden<http://www.blahedo.org/>-=-
Very few profundities can be expressed in less than 80 characters.