Re: metronome-mark-alignment

[David Kastrup]

Daniel Rosen <address@hidden> writes:

> As far as the Extending manual goes, though... I could be wrong, but
> it seems to assume a basic working knowledge of how computer programs
> and programming languages work that I simply don't have. Going through
> it, I think to myself that I would need to have one-on-one tutoring
> sessions with someone in order to really understand it. Take 1.2.1
> (http://lilypond.org/doc/v2.19/Documentation/extending/lilypond-scheme-syntax)
> as an example. This paragraph
>
>> The hash mark # method of embedding Scheme is a natural fit for this system.
>> Once the lexer sees a hash mark, it calls the Scheme reader to read one full 
>> Scheme
>> expression (this can be an identifier, an expression enclosed in 
>> parentheses, or several
>> other things). After the Scheme expression is read, it is stored
>> away as the value for an
>> SCM_TOKEN in the grammar. Once the parser knows how to make use of this 
>> token, it
>> calls Guile for evaluating the Scheme expression. Since the parser
>> usually requires a bit
>> of lookahead from the lexer to make its parsing decisions, this separation 
>> of reading
>> and evaluation between lexer and parser is exactly what is needed to keep the
>> execution of LilyPond and Scheme expressions in sync. For this reason, you 
>> should use
>> the hash mark # for calling Scheme whenever this is feasible.
>
> mostly goes over my head.

That is entirely my fault.  The problem was that there was no
satisfactory/exhaustive explanation of the technicalities surrounding
use of # vs $ that are caused by making LilyPond more powerful than its
underlying implementation and tools strictly allow for.  That has side
effects, and being able to think about such side effects requires
knowing what one is dealing with.

Many manual passages that I wrote up have been significantly rewritten
by people who tend to have human communication at least on par with
their ability of conversing with computers.  This one hasn't.  I'll
readily admit that it is bad.  It not being there, however, will likely
be worse at least for some readers.

> Of course, it may be that the manual isn't meant to be aimed at a
> complete novice like myself; but if it is, then it definitely needs an
> overhaul.

Sure, like most of what I write.  But there are not many people around
for overhauling.

-- 
David Kastrup