Re: regression tests

[Reinhold Kainhofer]

Am Dienstag, 11. September 2007 schrieb Graham Percival:
> Jan Nieuwenhuizen wrote:
> > Ok.  There it says
> >
> >    if there is any regtests which is useful as documentation and there
> >    is no corresponding snippet in LSR
> >
> > Although I agree that would be nice, currently that statement is
> > ridiculous.  It is way too early for that?  We have about 600
> > regression tests, and there are only about 220 lsr snippets.
>
> And only about 10% regtests are useful *as documentation*.  60 easily
> fits inside 220.  If we missed a few, we can add them.
>
> Most of the regtests are easily covered by the manual.  Especially now
> that we're adding new regtests whenever we fix a bug (which is quite
> appropriate)

Don't underestimate the value of actual code (where you can copy-paste from) 
compared to a documentation, where you need to turn the knowledge into actual 
code yourself.

It's so much more convenient to take a working example of something even 
simply and follow the ideas there, tweaking the file until you find out what 
you are looking for.

> Power-users know how to read the program reference.  They can see the
> features there.

Actually, to me (and I regard myself a power user) the program reference is 
only a very last resort before completely giving up when I don't find any 
snippet in the regressions tests or the tips & tricks pages. 

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.


> Look, the regression tests are not _intended_ as documentation, and they
> _should not_ be intended as documentation.  

But they ARE useful documentation for power users.

> 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 mainly because of the noise on mailing lists (you'll need to read lots 
of messages until you hit the one -- if it exists -- that treats your 
problem), the fact that you don't have the output of lilypond code in 
postings readily visible, and the fact that messages get out of date with new 
versions, but are found by a search just as well.

> that's why I've really been pushing LSR.

I completely agree with you on that.


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:

- http://www.nabble.com/parenthesize-t2475322.html (parenthesize needs chord)

- http://www.mail-archive.com/lilypond-user%40gnu.org/msg14115.html (\voiceOne 
and \voiceTwo set direction for dotted rests, so when combining rests, you'll 
need to override the dot direction manually. Otherwise you'll get a rest with 
two dots!)

- 
http://lilypond.org/doc/v2.10/input/regression/collated-files#parenthesize.ly 
(parenthesized staccatos)

- http://lilypond.org/doc/v2.10/input/regression/collated-files#span-bar.ly 
(showing bar lines also/only between staves)

Cheers,
Reinhold
-- 
------------------------------------------------------------------
Reinhold Kainhofer, Vienna University of Technology, Austria
email: address@hidden, http://reinhold.kainhofer.com/
 * Financial and Actuarial Mathematics, TU Wien, http://www.fam.tuwien.ac.at/
 * K Desktop Environment, http://www.kde.org, KOrganizer maintainer
 * Chorvereinigung "Jung-Wien", http://www.jung-wien.at/