Re: A comment about the documentation

[Peter Toye]

Pierre,

Merci beaucoup.

This partly solves the problem - but only for that particular snippet  How many other snippets are there which rely on undocumented public functions? And how many undocumented functions are there which don't appear in any snippets?

The problem is that if some functionality in a programming system needs a search through thousands of lines of code to discover it, it won't be used. I thought that the LP ethos was to make its extreme flexibility available to the general user (OK, they need to know programming and list processing as well). But to hide functionality away, however unintentionally, seems to contradict this. I agree that there is a large body of people who are only too willing to help (three on this thread alone), and maybe the number of queries you all get does not add much to the workload, but personally I much prefer sitting down with a manual and working it out myself. As an ex-professional programmer I'm quite used to learning syntax, but the details of how to match function to functionality has always been a problem - one really needs a telepathic I/O device.

For LP objects this problem is touched upon in the Learning Manual, where ways of finding the correct section in the Internals Reference are discussed.

Best regards,

Peter
mailto:lilypond@ptoye.com
www.ptoye.com

-------------------------
Friday, January 1, 2021, 5:01:27 PM, Pierre Perol-Schneider wrote:

I've added the github link in the snippet defs.
Cheers,
Pierre

Le ven. 1 janv. 2021 à 17:46, Peter Toye <lilypond@ptoye.com> a écrit :

Carl,

Thanks. The problem is that map-some-music is obviously a very useful function if you're trying to write code that performs an action at many places in a music _expression_, but there's no pointer to it. How the snippet writer found it I've obviously no idea (maybe they also wrote map-some-music). As it happens I wanted to do exactly what the snippet writer wanted so cutting and pasting were easy.

Another thing I want to do is to work out how to write a function that adds an octave beneath each note in a music _expression_ to save a lot of time writing two-note chords.  I'm sure make-some-music will help here. But if I hadn't found the snippet, how would I ever have known where to look in the source - there's a lot of it?

I hate to say it but I think the documentation is failing here, but can't see how to mend it easily. To start with, maybe a list of all the publicly available functions and their descriptions, but I suspect it would be far too long and need constant updating, which is not something that the LP documenters like for obvious reasons. Could it be mechanised?

Best regards,

Peter
mailto:lilypond@ptoye.com
www.ptoye.com

-------------------------
Friday, January 1, 2021, 4:06:59 PM, Carl Sorensen wrote:

On Fri, Jan 1, 2021 at 8:59 AM Peter Toye <lilypond@ptoye.com> wrote:

Christian, Thanks Christian. How one is meant to know this I have no idea. Maybe it was meant to be in the missing 3rd chapter of the Extending manual.

No, one is meant to search the source.  There are many scheme functions in the source that are used internally, but are not documented externally.  Advanced users will search the source code for these functions.  In the case of the LSR, you have examples of their use.  So you know the name of the function, and you can search the source to find the code.

If you are working on a machine (e.g. windows) that doesn't give you ready access to the source files, you can always go to the repository at GitLab or Savannah and search the source online.

Best wishes,

Carl