[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: regression tests

From: Trevor Bača
Subject: Re: regression tests
Date: Tue, 11 Sep 2007 11:25:05 -0500

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,
> > >
> > > That page could serve as a frontend to different versions, just like
> > >
> > >
> 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 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 objects are created by: Clef_engraver

Standard settings:

    stencil (unknown):

        The symbol to print.
    non-musical (boolean):

        True if the grob belongs to a NonMusicalPaperColumn.
    avoid-slur (symbol):

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

        The font family is the broadest category for selecting text
fonts. Options include: sans, roman.
    break-align-symbol (symbol):

        This key is used for aligning and spacing breakable items.

%%% END BEFORE %%%

... to this ...

%%% AFTER %%%


Clef objects are created by: Clef_engraver


    property: stencil.
    type: unknown.
    description: The symbol to print.
    acceptable values:
        ly:clef::print (default)

    property: non-musical.
    type: boolean.
    description: True if the grob belongs to a NonMusicalPaperColumn
    acceptable values:
        #t (default)

    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:
        'inside (default)

    property: break-align-symbol
    type: symbol
    description: This key is used for aligning and spacing breakable items.
    acceptable values:
        'clef (default)

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]