Re: [frogs] my contribution: barCheckNumber to endSpanners

[Carl D. Sorensen]

On 1/10/09 5:59 AM, "John Mandereau" <address@hidden> wrote:

> Graham Percival a écrit :
>> On Sat, Jan 10, 2009 at 08:12:49AM +0100, Frédéric Bron wrote:
>>>    - I have mainly copied documentation from the Notation Manual. Would be
>>>    better to enter the documentation only once because if the function
>>>    changes, we have to change the doc. at two locations.
>> 
>> Definitely -- but where were these docs from the NR?  Please give
>> specifics so that we can (probably) delete them from the NR.
> 
> 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.
> 
> I'm all for 1: there are already a lot in cross-references in our docs that
> are necessary, this is difficult enough to read so we should avoid needing
> them whenever possible.  The first solution makes information duplication in
> the output documentation only, not in the sources.
> 

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

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.

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

Frederic, this means that instead of having this kind of patch:

 #(define-music-function (parser location delta) (real?)
-
+  (_i "Falls and doits can be added to notes using the this command.
+  The direction of the fall or doit is indicated with a plus or minus (up
or down)
.
+  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))

Of course, this is still open to discussion, so don't jump on this right
now.

Thanks,

Carl