Re: A simple diagram of a .ly file?

[Graham Percival]

On 6-Jan-06, at 6:53 PM, Don Blaheta wrote:

> Quoth Graham Percival:
> > Did you read "chapter 4: putting it all together"?  Section 4.2 is
> > specifically aimed at solving this issue... this is an honest 
> > question,
> > not a rhetorical one.  If section 4.2 wasn't understandable, I should
> > work on that.  If you didn't notice 4.2, then I should work on
> > improving its visibility (say, by having a link to it from within the
> > tutorial).
>
> I don't know about Ray, but I can say that for myself, I never really
> noticed Section 4 there; because the manual is not really structured as
> a read-straight-through document (yes, I know you can get it in that
> form, but the default is clickable-ToC), I sort of bounced around.

Ok.  I'll add links from the tutorial or something.

> But I've just now read it, and it *really* doesn't address this 
> concern,
> which is also a problem I've had.  That chapter is still all about
> tweaking templates.

Only one section is.  Another is on general lilypond usage (which could 
apply to templates), but the third is about overlapping notation, which 
has nothing to do with templates.

>   I realise that everyone learns differently, but
> when I was first figuring LP out I would've really appreciated 
> something
> that just gave the layout of a file, almost like a BNF grammar (but
> don't call it that or you'll scare people away).  E.g.

Have you read 5.7?  That's where the BNF-type thing should go.  If 5.7 
isn't technical / strict enough for you, please send me more info to 
include in it.

>   Every Lilypond document has three parts: a header, other definitions,
>   and the score, in that order.  The header looks like this:

... although this type of definition would be useful, I'm torn on 
whether to include it in the tutorial.  It would certainly help some 
people... but I also winced when I read it, since it's incorrect.

Now, it's quite common in North American schools to teach incorrect, 
but useful, information.  I remember being by a teacher that you 
"couldn't do 5-4" (I think I was 6 years old) and pointed out that the 
weatherman talked about "minus 1", so why not?  It isn't uncommon to be 
told "ok, remember how a few years ago you learned that foo?  Well, 
that's not actually right; actually, bar happens".  That even happened 
in high school (such as 16-year old).  Some of it was unintentional 
(like the math teacher that claimed that there were three kinds of 
numbers: positive, negative, and absolute.  Absolute numbers aren't 
positive, apparently).

I don't know if this kind of educational philosophy is practiced in 
Europe.  I certainly hope not, since I think it's terrible.  :(   
However, it does make things easier for some students (and certainly 
for the teachers)


I'll add some info like this, but I'll make it clear that "a lilypond 
file _usually_ has three parts", that this is a simplification, and 
that users should consult section x.y for an accurate description.

> I meant to just type a short example, but it looks like what I've
> written is just about right for the first page of the section I'm
> envisioning.  Feel free to use it as you like....

I will.

> > There are three categories of problems with the docs:
> > 1.  Stuff I'm aware of, and is on my list of things to fix.
>
> Is your list public or semi-public?  That might help.  Could we maybe
> use the wiki for some of this?

It's not worth a wiki.  Contributed material should be sent to me 
and/or lilypond-devel, and I'm the only person who should be editing my 
list of things I need to fix.  :)

I'll send a list of things out in a bit over a week.  There are a bunch 
of things I want to fix before inviting people to compare the manual 
with my list of stuff to do (and that's what will happen as soon as I 
post such a list :)

Cheers,
- Graham