Re: A quest through the docs

[Erik Sandberg]

Citerar Graham Percival <address@hidden>:

> 
> On 25-Feb-06, at 9:39 PM, Don Blaheta wrote:
> 
> > Quoth Graham Percival:
> >> On 24-Feb-06, at 8:49 PM, Don Blaheta wrote:
> >>> * 10.5.7 should have an example layout block like the following:
> >>>   \layout {
> >>>     indent = #0
> >>>     line-width = #150
> >>>     raggedlast = ##t
> >>>   }
> >
> > The problem with arguing "by this point in the manual" is that the
> > manual is not always read sequentially, and people may or may not have
> > read the appropriate other bits recently.  Another problem is that 
> > while
> > it may be obvious when you read something what it does, reconstructing
> > the fragment is not always as obvious. :P
> 
> The only line that might need explanation is the line-width.  These 
> commands obvious set values; setting a value to #0 is pretty obvious, 
> and we use ##t and ##f all over the place.  As for line-width, the only 
> thing to explain is that the value is in staff-spaces... but we use 
> such values all over the manual.  I've added an explanation of it in 
> chapter 4, and I'm looking for a good place somewhere in chapter 10... 
> but it doesn't make sense to sprinkle two dozen explanations about 
> staff-spaces throughout the manual.  I'd say that three times (not 
> counting the tutorial and chapter 4) is the absolute maximum number of 
> times we should repeat info.

This could be an area where extensive use of hyperlinks could be useful (the
word line-width is linked to a page containing a description, which says that
line-width is measured in staff-spaces, where staff-spaces is linked to a page
that introduces the concept of staff-space). I don't know how much work it
would require to add such machinery though, and I don't know how useful it
would be either.

Erik