Re: Bug: Repeated chords (via "q") are not rendered when using ly:book-process.

[Jean Abou Samra]

> 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