[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: A quest through the docs
From: |
Don Blaheta |
Subject: |
Re: A quest through the docs |
Date: |
Mon, 27 Feb 2006 01:24:21 -0600 |
User-agent: |
Mutt/1.2.5.1i |
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.