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
_______________________________________________
lilypond-user mailing list
lilypond-user@gnu.org
http://lists.gnu.org/mailman/listinfo/lilypond-user
