Understanding Lilypond

[David Sumbler]

As I start to gain experience in setting music in Lilypond I am trying
to understand more about how it works internally.  As well as personal
satisfaction, this obviously has a practical aim: it will make it easier
for me to modify or correct things without having to ask so many
questions on this forum, and will also perhaps eventually mean that I
can help by answering others' questions.

However, despite having read the documentation - some of it several
times - I do find understanding some aspects of the structure of
Lilypond extremely difficult.  One of the manuals likens a Lilypond file
to source code in a computer language, but I find that understanding the
structure of a coding language is perfectly straightforward compared to
getting my head around Lilypond.  (I have learnt several languages over
the years, although not, I admit, Lisp or Scheme; however, I have no
reason to suppose that understanding their structure is any more
difficult than other languages).

For instance, in Lilypond there is a sensible difference in the default
handling of time- and key-signatures.  Using the \key command a key is
defined for the current Staff.  But using the \time command sets the
time signature for every staff.  If a different time signature is
required for a particular staff, then timeSignatureFraction has to be
changed.

>From the Internals Reference I see that the 2 layout objects
KeySignature and TimeSignature both exist, by default, in a Staff
context, which makes perfect sense.

Clearly, though, when the \time command is used, then not only is
Staff.timeSignatureFraction set, but so also is some other variable in a
higher context.

What I can't seem to find (although it may well be in the documentation
somewhere) is a clear explanation of this.  Can somebody point me in the
right direction?

David