Re: LilyPond concept glossary?

[Trevor Daniels]

Trevor Daniels wrote Thursday, July 30, 2009 9:16 PM
> Mark Polesky wrote Thursday, July 30, 2009 7:06 PM
> > It would be nice to have some central place that explains some
> > "internals" concepts. Here are examples of things that a new 
> > developer
> > might have to ask about, or perhaps spend a long time 
> > disentangling:
> >
> > grob
> > prob
> > smob
> > output-def
> > callback
> > simple-closure
> >
> > It would be nice to have a LilyPond-specific glossary, that users 
> > could
> > also use. For example, a user might get "glyph" and "stencil" 
> > confused.
> > I still get "command" "keyword" "identifier" and "variable" 
> > confused.
> > I still don't know the difference between "parser" and "lexer". 
> > You get
> > the idea.
> >
> > Any thoughts?
>
> It would be a helpful addition.  The best place would
> be another appendix to the NR.  The only alternative
> would be the CG, but this would not be helpful to users.
> As it's a glossary, including terms which users don't
> ever need would not a problem, I think.  (The LM is too
> simplistic for this, the MG is for musical terms and the
> AU is not appropriate.)
>
> Maybe Technical glossary would be a better term?
>
> But we need to wait for more comments before taking any
> action.

OK, we've now had a few comments, all in favour.
So I'll go ahead and add a stub.  So where?

Three prefer the NR (me, Reinhold, Graham)
Two prefer the CG (Valentin, Ian)

Mark hasn't stated a preference.

Of the three preferring the NR two prefer an
Appendix and one the main body (Graham).

On the grounds that developers should be very
familiar with material in the NR it is not a
hardship for them to look there for information,
especially as we can reference the NR from the
CG.  But it would be unreasonable to expect users
trying out a Scheme function for their score
to look in the CG, especially as (at present)
we have no macro to reference the CG from the
NR (maybe a good thing).

Another point in favour of the NR is so we
can reference it in warnings about parser
variables, for example, rather than repeating
the explanation in several places.

So I'll put the stub as a new NR Appendix.

No one has commented on the heading.  I prefer
Technical glossary over Concepts glossary to
avoid confusion with the concepts index (cindex),
although I admit this term isn't used visibly
in the user documentation.

Any further thoughts?

Trevor