RE: Patches for improved fret-diagrams

[Carl D. Sorensen]

> -----Original Message-----
> From: Han-Wen Nienhuys [mailto:address@hidden 
> Sent: Monday, April 09, 2007 8:55 PM
> > The main concern I have about this is documenting the 
> possible values 
> > for 'details.  Do you have an idea for how this 
> documentation might be 
> > done?  If we replace all of the individual fret-diagram properties 
> > with a single 'details property, would the 'details property be (a) 
> > specific for fret diagrams, or (b) a general property that 
> could apply 
> > to any grob that might have lots of properties?  Of course 
> (b) is the 
> > most reasonable thing to do.
> 
> it's (b), as we already have details for beam, stem and slur.
> 


In reviewing the documentation generation code, I'd like to propose (a),
instead of (b).

Here are my thought processes:

1.  'details is currently documented as an 'internal' property.
According to my reading of the internal properties, it appears that the
internal properties are generally set by code, rather than by the user
(e.g. the whole set of ancient music notation properties).

2.  There currently is no documentation available to the _user_ on the
details property (the documentation says to check*.cc files, which the
user doesn't have -- only the developer).

3.  'details is a catch-all, and documenting it to say "in fret
diagrams, do this; in slurs do something else" is inconvenient.

4.  If I define 'fret-diagram-details as a "User backend Property", then
I can put in the further documentation of the 'fret-diagram-details with
that object, e.g. 

{snippet of possible code from define-grob-properties.scm)

     (fret-diagram-details ,list? "An alist of detailed grob properties
     for fret diagrams.  Each alist entry consists of a
     (@code{property} . @code{value}) pair.
     The properties which can be included in fret-diagram-details
     include the following:
     @itemize @bullet
@item
@code{barre-type} -- Type of barre indication used.
Choices include @code{curved} and @code{straight}.
@item
@code{dot-color} -- Color of dots.  Options include
@code{black} and @code{white}.
@item
@code{dot-radius} -- Radius of dots.
@item
@code{finger-code} -- Code for the type of fingering indication used.
Options include @code{none}, @code{in-dot}, and
@code{below-string}.
@item
@code{fret-count} -- The number of frets.
@item
@code{label-dir} -- Side to which the fret label is attached.
@code{-1}, @code{#LEFT}, or @code{#DOWN} for left or down;
@code{1}, @code{#RIGHT}, or @code{#UP} for right or up.
@item
@code{number-type} -- Type of numbers to use in fret label.  Choices
include @code{roman-lower}, @code{roman-upper}, and @code{arabic}.
@item{string-count} -- The number of strings.
@item
@code{xo-font-magnification} -- Magnification used for mute and
open string indicators.
@item
@code{mute-string} -- Character string to be used to indicate muted
string.
@item
@code{open-string} -- Character string to be used to indicate open
string.
@item
@code{orientation} -- Orientation of fret-diagram.  Options include
@code{normal} and @code{landscape}
@end itemize")

The interface to the fret-diagram grob would then be greatly diminished,
to 

(ly:add-interface
 'fret-diagram-interface
 "A fret diagram"
 '(align-dir fret-diagram-details size
  string-fret-finger-combinations thickness))

And the complete properties documentation would show up in the
automatically-generated fret-diagram-interface page.

What do you think?

Carl