Learning Lilypond internals

[Andrew Bernard]

Although I have long experience in software development, the Lilypond source is a body of work that I have never really been able to comprehend. This is a pity as I always wanted to help with development. Now, when I have technical issues need knowledge of internals, such as my recent effort relating to noteheads, there is a handful of deeply learned people who come to my assistance, and I am grateful. What I want to ask today is this. The solutions seem to pull commands out of thin air with deep understanding, and I have no idea how to find out this stuff for my self. The internals reference manual is hardly discursive in nature. So Jean, Valentin, Harm (still here?), how have you come to acquire this deep knowledge? I don't know how or where to start.

So much of my modernist work needs internals knowledge, and even though I have built up a large library of extension code in Lilypond and Scheme, I am still all at sea.

Any advice? I know Scheme and C++ very well. It's the functions and what they do that I don't understand enough. Here's an example.

LY_DEFINE (ly_stencil_outline, "ly:stencil-outline",
           2, 0, 0, (SCM stil, SCM outline),
           R"(
Return a stencil with the stencil _expression_ (inking) of stencil @var{stil} but
with outline and dimensions from stencil @var{outline}.

I can understand what dimensions means but what is the 'outline' of a stencil, and how is it used? Just one example of my profound ignorance.

Andrew