> 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?
In contrast to Jean, I have a different point of view. I think it would be *very* valuable to have documentation strings of *all* functions that might be useful in the long run (of course, it is debatable which functions these are exactly). A lot of code is written in Guile and C++, which is sometimes very hard to read for non-C++ programmers. So... > 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. ... I'm very grateful for your offer. > As a start, here are my suggestions for the two functions in > question: [...] Thanks, see https://gitlab.com/lilypond/lilypond/-/merge_requests/2294 > If someone else is already working improving this Section, you may > let me know - I'd love to join in. You will be mostly a lone fighter, sorry :-| > Otherwise, as my understanding of the internals is still > fragmentary, I'd need some help getting things right. I could just > continue to send improvement suggestions as mentioned in [2] to this > mailinglist (or lilypond-devel?) and someone corrects me if I get > things wrong? Or is someone willing to "proofread" some suggestions > of mine in advance so I do not add too much noise to the > mailinglists? I could also give larger-scale structural improvement > suggestion as a start for debate if you would consider this > appropriate from a "newbie" to the mailinglists. I think the best way to contribute is to get an account on GitLab, clone the 'lilypond' git repository and submit Merging Requests, closely following the formatting of other documentation strings. All documentation that goes into the IR uses Texinfo syntax. And yes, larger-scale stuff should be discussed first on 'lilypond-devel'. Werner
