> Thank you so much, that did the trick. > > The naming of lilypond scheme functions can be really unintuitive > sometimes. At the very least, the internals reference could use > some major extensions making clear what the functions do and how, > with examples. Via [1], it would have been impossible for me to > understand what scorify-music does or that I need this function > over ly:make-score. Am I missing some other place where this is > already documented in more detail? > > If not, I'd be happy to start investing my time to contribute to > the Internals reference documentation, especially Section 4 "Scheme > functions". In addition to better explanatory texts this section > could benefit from more crosslinks and examples - or maybe the > examples should be in a different (new) section to keep this > reference concise. I'd be happy to discuss this further.
Not that improvements like this are not welcome, but if you want my honest opinion, documenting public functions to the degree that one could use them just from the manual is a lost cause. There are way too many of them (740 functions in the current Internals Reference, but many more exist which are undocumented). I think we just have to accept that, these functions being largely the deep guts of LilyPond exposed for anyone to use, you have to be a bit familiar with the source code in order to use them correctly. I think the best we can do is high-level extending documentation — like what I've tried to do in https://extending-lilypond.gitlab.io — supplemented by a dose of "read the source code" for advanced usage. Note that I didn't know about scorify-music before you sent this bug report. I just knew that chord repeats are expanded by a music function in toplevel-music-functions, and I did a bit of grepping in order to find the call site. Best, Jean
signature.asc
Description: This is a digitally signed message part
