Re: [frogs] Should _all_ lilypond functions be listed in music-functions-init.ly?

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

On 1/10/09 4:57 PM, "Ian Hulin" <ian@xxxxxxxxxxxx> wrote:

> Hi Carl,
> I understand your answers but I find the distinction a bit confusing for
> lilypond users.  
> 
> If we're producing a list in an appendix of the documentation of the syntax
> for bits of Lilypond, if the user's trying to look up how to code it in a
> source file for a piece, is he/she going to care about the distinction between
> an identifier and core language component.

Probably not, at first.  But an identifier can be redefined, and a core
language component can't, so there is a difference that the advanced user
will eventually need to know.

And this appendix is specifically for identifiers.  (It would probably be
clearer if it said predefined identifiers, instead of just identifiers).

>   
> The user wants to know what the syntax is make his/her code work.  If we're
> putting effort in here to add docstrings for identifiers which are currently
> missing, shouldn't the long-term aim (of which this job was one small step) be
> to make this appendix list the syntax for all the things which are provided
> "out of the box" for the user when he installs Lilypond?
> 
> I.e. \gibbon, \vole and \aardvark would all be there with their syntax
> definitions whether they were defined as Scheme or in c++.
> 

I think this is a potentially good idea.  But it will require major
modifications to the doc generation system, which I'm not capable of doing
right now.  If some frog wants to take that on as a challenge, I'm totally
fine with it.  But I'm not ready to assign it to anybody.

> We're already doing some things to allow us to document the grace-note
> identifiers.

Yes -- but if we didn't have a relatively straightforward way to do it, I
wouldn't be asking anybody to do it now; I'd just be saying to leave it for
later.

> 
> Shouldn't we have a low-priority bug to say that some parts of the language
> are getting omitted from being documented in NR B.14?
> 

I'm totally OK with a low-priority enhancement request to create an
automatic documenter for the entire language.  But the place that the
documentation goes wouldn't be in NR B.14.  It would be a new volume of
documentation, the Language Reference.  It would include parser-defined
keywords, predefined identifiers, and predefined markup functions, at a
minumum.

I want to keep the distinction between identifiers and parser-defined
keywords if only because I have to use different tools to change them
(parser-defined keywords need C++ compilation, identifiers don't).

So if you want to send an enhancement request to bug-lilypond, go ahead.
And if you want to work on this as a project, even better!

Thanks,

Carl

> Carl D. Sorensen wrote:
>>  
>> 
>> 
>> On 1/10/09 9:36 AM, "Ian Hulin" <ian@xxxxxxxxxxxx> <mailto:ian@xxxxxxxxxxxxx>
>> wrote:
>> 
>>   
>>  
>>>  
>>> Hi all,
>>> I've found some functions that don't have an entry in
>>> music-functions-init.  So they haven't got docstrings entries so they
>>> don't appear in the NR Appendix.
>>> 
>>> Question 1 : Do all functions need a entry in this file?
>>>     
>>>  
>>  
>> 
>> Answer:  No.  Only those that are defined as identifiers.
>> 
>>   
>>  
>>>  
>>> Question 2: How do we find out what code needs to go in the function
>>> body if we do need to put it in?
>>>     
>>>  
>>  
>> 
>> Answer:  If it's not defined as a scheme function somewhere, we don't add
>> docstrings.
>> 
>>   
>>  
>>>  
>>> Question 3: Should I ask on lilypond-bugs about the ones I currently
>>> know are missing (addlyrics, tolyrics and lyricmode).so we could get a
>>> tracker raised for this,
>>> 
>>>     
>>>  
>>  
>> 
>> Answer:  You don't need to ask.  But if you did, the place to ask would be
>> -devel.  Then, if you got the answer that the docstrings should be added,
>> you'd post a short message saying so to bug-lilypond, and Valentin would add
>> it to the tracker.
>> 
>> The answer as to why these functions aren't listed can only be found if you
>> have the full source tree.  git grep addlyrics returns
>> 
>> lily/lily-lexer.cc:  {"addlyrics", ADDLYRICS},
>> 
>> which shows that addlyrics is defined in the parser as a component of the
>> LilyPond language, rather than as an identifier.
>> 
>> Similarly for lyricsto
>> 
>> lily/lily-lexer.cc:  {"lyricsto", LYRICSTO},
>> 
>> and lyricmode
>> 
>> lily/lily-lexer.cc:  {"lyricmode", LYRICMODE},
>> 
>> 
>> So you can see that all three of these are actually a part of the lilypond
>> language, rather than identifiers.
>> 
>> So there's no place to put a doc string for these; they're core parts of the
>> language.
>> 
>> Thanks for your questions, and I hope my answers are helpful.
>> 
>> Carl
>> 


---

----
Join the Frogs!