A quest through the docs

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

A quest through the docs

Don Blaheta
I wanted to find out how to, for some snippets in a book, make the last
line of the snippet not expand to its maximum width.

I went to the table of contents briefly and found nothing, so I turned
to the index.  Nothing under "last", but I tried to do a browser find on
"last", which turned up "ragged-last-bottom".  The name seemed promising
but it wasn't what I wanted, so I went back to the index.
"ragged-right" was the next thing, and although I didn't want every line
ragged, I thought maybe I could insert some manual overrides, so I
clicked on it.

This took me to 10.5.7 "Line length", which lists not only ragged-right
but also raggedlast, which *is* what I wanted, although it wasn't listed
in the index.

But then, I wasn't sure how to use it.  Going "up" to 10.5 "Music
layout" didn't tell me much, so I went all the way over to the Program
reference to see if I could figure out what grob or whatever it would be
attached to.  I rooted around a bit as I always have to in the program
reference, didn't find it at first, noticed the "index" option but it
wasn't in there either.  So then I went through each of the different
"properties" lists in the back end looking for anything "ragged", but I
couldn't find anything.

So I went back to 10.5.7 and thought, hm, maybe raggedlast just a plain
old variable (or whatever it's called) like indent, and not attached to
any of the objects.  Sure enough, that's exactly how it works.

Anyway, so I have a few specific suggestions arising from this latest
documentation quest:

* "raggedlast" should be "ragged-last-right" for consistency with the
  others...

* ...and it should be in the index in any case.

* The top two levels of the Program reference should be on a single
  page, or else the summaries on the top page should include the words
  "grob", "context", "engraver", etc in the appropriate places, because
  I can never remember which top-level section each thing goes in.

* The program reference index should have all the items currently in the
  third level of the program reference: all the individual contexts,
  properties, grobs, engravers, etc, etc.

* 10.5.7 should have an example layout block like the following:
  \layout {
    indent = #0
    line-width = #150
    raggedlast = ##t
  }
  and explain that it removes the first line's indent, sets the width to
  150 times the width of a staff space (right?), and turns on raggedlast
  mode.

--
-=-Don Blaheta-=-=-[hidden email]-=-=-=-<http://www.blahedo.org/>-=-
"Do you know what I love about corporate CEOs? Their commitment to
honesty.  I like to think we owe the free market for that. In a more
regulated system, they might lie sometimes." --Bob Romashko


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Graham Percival-2

On 24-Feb-06, at 8:49 PM, Don Blaheta wrote:

> * "raggedlast" should be "ragged-last-right" for consistency with the
>   others...

Or at least ragged-last.  Han-Wen?

> * ...and it should be in the index in any case.

I've indexed it.

> * The top two levels of the Program reference should be on a single
>   page, or else the summaries on the top page should include the words

I don't know how to do this; I might look at the program reference
stuff in the summer.

> * 10.5.7 should have an example layout block like the following:
>   \layout {
>     indent = #0
>     line-width = #150
>     raggedlast = ##t
>   }
>   and explain that it removes the first line's indent, sets the width
> to
>   150 times the width of a staff space (right?), and turns on
> raggedlast
>   mode.

I'll include an example, but I think that by this point in the manual,
it's pretty obvious what things do.

Cheers,
- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Han-Wen Nienhuys
Graham Percival wrote:
>> * "raggedlast" should be "ragged-last-right" for consistency with the
>>   others...
>
>
> Or at least ragged-last.  Han-Wen?
>

This is already fixed in .36

--
  Han-Wen Nienhuys - [hidden email] - http://www.xs4all.nl/~hanwen


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Don Blaheta
In reply to this post by Graham Percival-2
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
> >   }
> >   and explain that it removes the first line's indent, sets the width
> > to
> >   150 times the width of a staff space (right?), and turns on
> > raggedlast
> >   mode.
>
> I'll include an example, but I think that by this point in the manual,
> it's pretty obvious what things do.

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

--
-=-Don Blaheta-=-=-[hidden email]-=-=-=-<http://www.blahedo.org/>-=-
Documentation is the castor oil of programming.  Managers know it must
be good because the programmers hate it so much.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Graham Percival-2

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.

Cheers,
- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

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 Blaheta-=-=-[hidden email]-=-=-=-<http://www.blahedo.org/>-=-
Very few profundities can be expressed in less than 80 characters.


_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Graham Percival-2

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Erik Sandberg
In reply to this post by Graham Percival-2
Citerar Graham Percival <[hidden email]>:

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



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: A quest through the docs

Graham Percival-2

On 2-Mar-06, at 5:46 AM, Erik Sandberg wrote:

> Citerar Graham Percival <[hidden email]>:
>> The only line that might need explanation is the line-width.  These
>> commands obvious set values; setting a value to #0 is pretty obvious,
>
> 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.

I suppose we could do a global search and replace on all "staff-spaces"
to replace it with @ref{}s... but we'd have to manually go through and
add those terms whenever appropriate.  IMO, it's not worth it -- and
I'm certainly not interested in doing this myself.  I'd still have
doubts even if somebody else did all the work and sent in a patch --
too many hyperlinks in the middle of text breaks up the flow, and
actually makes it harder to read.

I added some text to "scheme tutorial".  I was looking for a place to
add it in "Changing defaults -> \override", but I discovered that it
was already mentioned.

I'm not throwing out the idea of making this info more prominent in a
future doc reorganization, but any such reorg would be two or more
months away.

Cheers,
- Graham



_______________________________________________
lilypond-devel mailing list
[hidden email]
http://lists.gnu.org/mailman/listinfo/lilypond-devel