Re: [frogs] my contribution: barCheckNumber to endSpanners

["Carl D. Sorensen" <c_sorensen@xxxxxxx>]

On 1/10/09 12:12 AM, "Frédéric Bron" <frederic.bron@xxxxxxx> wrote:

> Please find my contribution from barCheckNumber to endSpanners.
> 
> Some remarks:
> 
> - I cannot check if my modifications do not break anything because it seems
> that (_i ...) is not recognized (and is removed from the distribution?).
> for example I obtain the following message:
> Processing `barNumberCheck_exemple.ly'
> Parsing...d:/Softs/LilyPond/usr/share/lilypond/current/ly/music-functions-init
> .ly:129:3: In procedure string? in expression (string?):
> d:/Softs/LilyPond/usr/share/lilypond/current/ly/music-functions-init.ly:129:3:
> Wrong number of arguments to #<primitive-procedure string?>
> I imagine I would need a kind of a compilation to remove the (_i ...)

The problem here is that you've added a (string?) to the function.  I think
that if you remove your added (string?),  it will compile.

> - there are plenty of tabulations in music-functions-init.ly
> <http://music-functions-init.ly>  and indentation is some times 2 spaces, some
> times 3...

Don't worry right now about whether indentation is 2 spaces or three spaces..
And don't worry too much about removing tab characters from the file, but if
you find them it's good to get rid of them.

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

I've responded to this in another email to devel, because Graham wanted to
have a discussion about this.  Let me explain a bit more here.

In my opinion, docstrings for music functions should be a *short*
(approximately one line) description of what the function does.  The
material from the NR is a longer description of how to use the function.

To put all the documentation in the functions themselves, I think we need to
have two different docstrings, a description-string and a usage-string.  For
now, we don't have the infrastructure to support both, so I propose that the
docstrings for now should be description-strings.

So the description string for falls and doits should read something like

(_i "Create a fall or doit of length @code{delta}.")

I'm sorry to ask you to redo so much work, but could you create a different
branch on git (so you don't throw away your current work) and make your
docstrings description-strings?

> - I do not know if the doc string should go after of before (ly:music?); is
> this code part of the function signature?

Officially, the docstring is the final argument to the
define-music-function-macro.

I think of the docstring as the first item in the function body.  It comes
after the list of arguments (parser location custom-arg1 custom-arg2) and
the list of types for the user-defined arguments
(type-of-arg1? type-of-arg2?).

Thanks for your great work,

Carl


---

----
Join the Frogs!