Re: [frogs] my contribution: barCheckNumber to endSpanners

[Graham Percival]

On Sat, Jan 10, 2009 at 07:30:23AM -0700, Carl D. Sorensen wrote:
> 
> On 1/10/09 5:59 AM, "John Mandereau" <address@hidden> wrote:
> 
> > I propose to adopt either of the following solutions:
> > 
> > 1. Define a macro for each predefined command: the docstring of each
> > function \foo would be stored in a macro named @musicFunctionFoo, which
> > would be used both in the Identifiers page and throughout the manual in
> > "Predefined commands" sections.
> > 
> > 2. For each music function, add link from "See also" sections to the
> > Identifiers page, with HTML/PDF anchors made with @nodes.

Umm.  I didn't realize this stuff was more end-user documentation;
I thought this was all scheme-tweaking things.

> I propose something different.  I think the current NR documentation is
> right, with a usage description in the section of the NR, and a short
> description from the docstring in the appendix that lists all music
> functions.

Yes.  I really don't want to redo all the work from GDP.

>  The reason I use the Identifiers page is that it's a quick read
> of available functions -- if it gets longer because we have usage
> instructions it won't be as useful to scan quickly.

Yes and no.  I glanced at that page, and I think that this is a
fine example:

----
 addChordShape - key-symbol (symbol) tuning (pair)
shape-definition (unknown)

    Add chord shape shape-definition to the chord-shape-table hash
with the key (cons key-symbol tuning). 
----

It tells a programmer what they need to know, without being too
long.


> If we want to move to having this documentation all in the music functions
> (which may be a good idea, but will require some substantial rewriting of
> the documentation building system, IMO), we should have *two* documentation
> strings in the music function: 1) a description string, which is like the
> current docstrings, and 2) a usage string, which is like the current text
> from the NR.

I don't think this is necessary, and it'll make doc writing even
harder.  Normal user should be able to contribute to the docs by
editing texinfo files.  I really don't want to drag scm files into
it.

For programmer-specific docs, of course scm-file modification is
fine.

> For the meantime, I think we should just keep description strings in the
> docstrings, and the usage in the NR.

Yes.

> +  The number @var{delta} indicates the pitch interval that the fall or doit
> will extend beyond the main note.")
>    (make-music 'BendAfterEvent    'delta-step delta))
> 
> the patch should look something like this:
> 
>  #(define-music-function (parser location delta) (real?)
> +  (_i "Create a fall or doit of length @code{delta}.")
>    (make-music 'BendAfterEvent    'delta-step delta))

I wouldn't mind having the info about delta quoted above.  But
yeah, this second version of the patch looks better.

Cheers,
- Graham