RE: regression tests

[Carl D. Sorensen]

> -----Original Message-----
> From: Kieren MacMillan [mailto:address@hidden 
> Sent: Tuesday, September 11, 2007 11:16 AM
> To: Carl D. Sorensen
> Cc: Graham Percival; lily-devel
> Subject: Re: regression tests
> 
> Hi Carl,
> 
> > If I understand correctly, the program reference already 
> contains the 
> > complete list of user-settable properties for each grob.
> 
> Not in a single page.

This could conceivably be done, because each grob has its full interface
defined (see grob-interfaces.scm), and it would be possible to collect
the descriptions for each of the properties in the interface under the
heading of a grob.  I think it could be done in Scheme, just like the
program reference already is created.

> 
> > you can't say that the default value of property "foo" is "bar".   
> > It might
> > be "bar" when applied to the "grackle" grob, and "baz" when 
> applied to 
> > the "frobozz" grob.
> 
> But that's precisely my point!  =\
> 
> Q.  What is the default X-offset value of a LyricText grob?
> A.  Not easy to find!  ;-)
> 
> Because there is no (easy) way of finding these values, it 
> requires more trial-and-error on the part of the user.
> 
> > Thus, there is only one internal documentation point for 
> "size", not 
> > one point for each grob that uses size.
> 
> Yes, but these values are (i.e., must be) set for each grob
> *somewhere* (in .ly or .scm or .cc files), right?
> And if they're intentionally left "unset", what does that 
> really mean? That (e.g.) an Accidental doesn't have a 
> minimum-X-extent?

The values are not ever really set.  The way the default values get
assigned is when routine needs a value of a property it calls
chain-assoc-get with the name of the property and a default value.  If
the property is not found, the default is assigned.  Speaking for the
example that I know best, which is fret-diagrams, the various properties
of the fret-diagram are called from at least six different Scheme
functions (e.g. draw-dots, draw-strings, draw-frets, etc.).  Although it
would be relatively easy to search through the .scm files looking for
calls to chain-assoc-get with the property size, it would be quite
difficult to determine which grob each call references.  That is, there
is a call from fret-diagrams.scm for the fret-diagram size, but there
are also calls from other .scm functions to set the sizes of other
grobs.  As the code is currently constructed, there's only a property
name, not a grob name associated with the call.

It's very difficult to say that something is impossible.  After all,
lots of the Lilypond team members have accomplished things that I would
have said were impossible.  But from what I know of the code, I don't
think the infrastructure exists to make the page you want automatically.

However, I think that the page you request is a _very_ desirable page to
have.  And I could conceive of changing the chain-assoc-get calls to
include both a grob and a property, expressly for the purpose of
allowing generation of such a page.  There would still be some issues.
For example, in fret-diagrams, there are two different default dot
sizes.  If the finger labels are on the strings or are non-existent, the
default size is small.  OTOH, if the labels are on the dots, the default
size is larger.  And one can only see the difference by reviewing the
structure of the code that contains the chain-assoc-get call, not by
examining the call itself.  So I think it's pretty close to impossible
generate the list of default values.

I don't want to dismiss your idea.  I'd like to see such a thing happen.
I think it would even be OK to list two default values for dot-size in
fret-diagrams.  At least then I'd only have two choices to choose from,
rather than an infinite set....

> 
> If feasible (i.e., scriptable, so it's automatically done at 
> make- docs time), we should offer users a single page (for 
> each grob) which includes ALL settable properties and their 
> default values (for that grob).

For me, right now, with the current lilypond architecture, I think the
page is infeasible.  With a change in the chain-assoc-get interface to
include a dummy argument that's just used for creating the
documentation, I think it could be feasible.

Carl