>> I suppose it would make sense to have an additional main section in
>> the Docs explaining how LilyPond (the software) works, as opposed
>> to LilyPond (the description language).
>>
>> This could feature things like $, #, #@ and whatever, how the
>> parser works, how translation and engravers work and such stuff.
>
> A lot of those things are pretty well documented here:
> https://extending-lilypond.gitlab.io/en/index.html and here
> https://lilypond.org/doc/v2.25/Documentation/extending/. I think
> it's been discussed in the past whether those docs could be merged,
> but I don't recall the reason they had been kept separate. Having
> them separate definitely makes it harder to find answers to specific
> questions, as each covers things omitted by the other.
Everything is a matter of time, dedication, and energy. A merge would
be definitely useful, but this is a really huge undertaking.
> There are aspects of Lilypond that are not that deeply documented
> yet, of which the parser is one. Others are IMO iteration, pure
> positioning/line breaking, and event dispatch. Mostly the topics
> that lack documentation are also areas where the functionality is
> not that well exposed via Scheme to customization by end users.
I agree.
> Personally I think a valuable direction to extend documentation
> would be to cover more of the public Scheme functions with
> meaningful docstrings so that they show up in the Internals
> reference (which would include the toplevel handlers). I've
> frequently found that I wasted time writing code to do something in
> Scheme when I could have just used a built-in function if only I had
> known it existed.
Whenever you stumble upon an underdocumented function please submit an
improved version!
Werner
