On 9/11/07, Valentin Villenave <[EMAIL PROTECTED]> wrote:
> 2007/9/11, Reinhold Kainhofer <[EMAIL PROTECTED]>:
>
> > The program reference is (by definition) so closely tied to the internals of
> > lilypond that you'll need a lot of experience with lilypond (to know about
> > grobs, interfaces, events, etc.), that it's quite hard to turn things into
> > real code. I mostly use trial-and-error then until I get the correct
> > position
> > to set one flag or so.
> > With the regression test snippets you already have the correct code and can
> > copy it.
>
> Don't blame me for quoting myself, but I just wanted to mention a line
> from my previous mail (which has been lost in this thread), and Jan's
> answer:
>
> > > > How about, for example, http://lilypond.org/web/devel/
> > >
> > > That page could serve as a frontend to different versions, just like
> > >
> > > http://lilypond.org/web/documentation
>
> I do think, like Graham, that regtests do not belong in Documentation.
> You want to cope with "actual code": I understand that, and nodoby
> will prevent you from accessing the regtests.
>
> However, they are *not* Documentation. They do not contain verbose
> explanations, they're not redacted, nor corrected, nor formatted, nor
> organized, by any Documentation guy (excepted when the Documentation
> guy happens to be the bug-tracking guy too :)
>
> The Reference is *pure* Documentation stuff, as it's intended for
> people who'd wish to fully understand the complete LilyPond process.
> When you want an easy, quick solution, without necessarily
> understanding how, why, when, where etc. it works; here's the LSR.
>
> What you're looking for isn't in the LSR? Don't think "oh crap, the
> LSR isn't any good, I'll never come back again"; just browse every
> other non-Documentation sources (archives, regtests etc), and add it
> to the LSR, so the next guy can be given a quick solution.
>
> That's why I fully agree with Graham having reduced the amount of
> links on the http://lilypond.org/doc/v2.11/Documentation/ page
> (actually I suggested the current layout).
>
> I do think there *has* to be a link to the regtests, but as said
> before we need to find another place. It can be on web/devel, it can
> be elsewhere. I just wanted to point out that it would make this
> precise page more complete than it is now.
>
> > > I wish that more users searched the mailist archives, but they don't.
> > > Useful tips sent to the mailist are essentially lost knowledge;
> > > that's why I've really been pushing LSR.
>
> Excellent point. Avoiding lost knowledge; that's what we try to do.
>
> > A while ago, while I was working on some choir pieces, I collected some
> > links
> > and snippets that I frequently need. Most are from LSR, but e.g. the
> > following don't seem to have made it to the LSR:
>
> ...Then how comes you haven't added these yourself yet? This is
> precisely what Graham wants to avoid in the future, by removing the
> link of the main Documentation page.
>
> OK, I've added the last three of your four snippets.
> I let you add the first one, about dotted rests not fully merging;
> IMHO it could be reported on Google tracker too, as I think the dots
> should be merged in such a case...
Hi everybody,
Can I step in here for a moment, too? The tension about the regtests
seems to come from these two things, both of which are equally true:
1. the regtests are ugly (and redacted, corrected, formatted ...
exactly as Valentin points out),
2. BUT the regtests give examples of *settings* that are not
(currently) available elsewhere.
So you put these two observations together and you get exactly the
tension you'd expect: the professional documenters and translators
among us recoil at the fact that the regtests don't make
professional-looking docs, while others among us mourn the loss of
honest-to-goodness working examples of a large number of *settings*.
So what to do?
First, drop this particular thread during the GDP ;-) Scoping doc work
is battling a hydra, and Graham's doing an admirable job of making
sure that GDP has an actual chance of finishing.
That said, when it comes time to scope such a project (next year or
later), what I think is *really* needed -- and which addresses both #1
and #2 above -- is precisely what Kieren's pointing to: a greatly
fleshed-out version of the programming reference. How fleshed-out? I
think we can specify exactly, based on the following two criteria (and
I'm thinking of the grob listing here when I write this, not
necessarily the other parts of the program reference):
Criterion 1: There's a *complete* enumeration of acceptable values for
each property, and
Criterion 2: There's a working, one-line example of each value for
each property of each grob
At the very very least you'd think that the grob listing would already
have criterion #1, and, in fact, we see people on the list asking for
just such lists of values on a fairly regular basis.
As an example, this would change the first part of the entry for the
Clef grob from this ...
%%% BEFORE %%%
Clef
Clef objects are created by: Clef_engraver
Standard settings:
stencil (unknown):
ly:clef::print
The symbol to print.
non-musical (boolean):
#t
True if the grob belongs to a NonMusicalPaperColumn.
avoid-slur (symbol):
'inside
Method of handling slur collisions. Choices are around,
inside, outside. If unset, scripts and slurs ignore each other. around
only moves the script if there is a collision; outside always moves
the script.
font-family (symbol):
'music
The font family is the broadest category for selecting text
fonts. Options include: sans, roman.
break-align-symbol (symbol):
'clef
This key is used for aligning and spacing breakable items.
%%% END BEFORE %%%
... to this ...
%%% AFTER %%%
Clef
Clef objects are created by: Clef_engraver
Settings:
property: stencil.
type: unknown.
description: The symbol to print.
acceptable values:
ly:clef::print (default)
ly:clef::box
ly:clef::circle
ly:clef::outline
property: non-musical.
type: boolean.
description: True if the grob belongs to a NonMusicalPaperColumn
acceptable values:
#t (default)
#f
property: avoid-slur
type: symbol
description: Method of handling slur collisions.
Choices are around, inside, outside.
If unset, scripts and slurs ignore each other.
around only moves the script if there is a collision;
outside always moves the script.
acceptable values:
'()
'around
'inside (default)
'outside
property: break-align-symbol
type: symbol
description: This key is used for aligning and spacing breakable items.
acceptable values:
'clef (default)
'time-signature
'key
'bar
'flamingo
%%% END AFTER %%%
(The enumerations here are made up, btw.)
That what fill a massive blind spot.
Satisfying criterion #2 is harder and means that each value in each
enumeration list gets a minimal example.
But how unbelievably useful to visually scan a single page and see the
different effects of, for example, boxed vs circled vs printed vs
rounded vs transparent clefs, or of around-slur vs inside-slur vs
outside-slur vs unset-slur clefs, or ...
--
Trevor Bača
[EMAIL PROTECTED]
_______________________________________________
lilypond-devel mailing list
lilypond-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-devel
