Re: regression tests

[Trevor Bača]

On 9/11/07, Valentin Villenave <address@hidden> wrote:
> 2007/9/11, Reinhold Kainhofer <address@hidden>:
>
> > 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
address@hidden