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

[Ian Hulin <ian@xxxxxxxxxxxx>]

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

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

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?

Cheers,
Ian

Carl D. Sorensen wrote:

On 1/10/09 9:36 AM, "Ian Hulin" <ian@xxxxxxxxxxxx> 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!

______________________________________________        
This email has been scanned by Netintelligence        
http://www.netintelligence.com/email
  

No virus found in this incoming message.
Checked by AVG - http://www.avg.com 
Version: 8.0.176 / Virus Database: 270.10.5/1886 - Release Date: 10/01/2009 18:01