Re: A quest through the docs

[Graham Percival]

On 26-Feb-06, at 11:24 PM, Don Blaheta wrote:
> 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.

Sorry, I was unclear.  I've added your example.  I just don't think 
that we need a paragraph explaining what each line does -- I think the 
example is clear enough as it is.

> > 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.

That's a good idea... but I'm still not certain we need it for this.  
"Distances are measured in staff spaces" is a fairly basic lilypond 
thing (at least, it's basic to doing tweaks), so I'd rather improve its 
visibility in the beginning stages, rather than sprinkling it 
everywhere.  It's like those "examples in the manual need {} and maybe 
\relative c''{} to be placed around the printed example to make it 
produce the music shown" warnings.  There's no point in printing that 
warning everywhere; we just need to make sure people see it at the 
beginning.

Cheers,
- Graham