A simple diagram of a .ly file?

[Ray]

First off, I think Lilypond is amazing and I had very few problems installing
it or using it, despite a relatively limited musical knowledge.  I'm an
amateur songwriter with no ambitions of ever going pro but wanted to print out
my music as a gift for my mom at Christmas.  We're talking very simple stuff:
a melody, lyrics, and the markup guitar chords at (approximately) the right 
time.

Through the tutorial I quickly gained fluency in the make up of an .ly file,
but I found that as the file got larger it got harder and harder to keep track
of. Furthermore, when any kind of bug appeared it was almost impossible to
sleuth out...as there is almost no documentation (that I could find, anyway)
dealing with the syntax or _general_ form of a .ly document.  I don't see this
as a failing per se, but perhaps it might be something that folks could push
for as time permits?  Alternatively, additional templates might be nice, ones
that address non-classical music forms.

In my case, I found it hard not to compare Lilypond to HTML...they both seem
essentially like markup languages and they both have "header" files.  Getting
the hang of Lilypond _should_ be relatively easy.  But having a visual sense
of the .ly "body" is much, much harder.  In the example files it's hard to
discern what are the variables and what are the Lilypond syntax codes (color
coding the examples would be a great boon for anyone trying to figure them
out).  And there doesn't seem to be any kind of simple discussion about how
to organize a file, such as:

"A .ly file has 3 basic parts.  The header, the body, and the score.  In the
header, info about the piece is given (composer, title, etc.) as well as any
other useful info the program may need but which doesn't relate to the notes
themselves.  The body is where the notes and the lyrics are set down.  The
score is where the "printing" (whether to paper or MIDI) is done.  Variables
are written in the 'body' part and then used later as part of the score."


I'm not even sure I'm right about what I've just written, actually, but it's
what I'm gleaning from the current examples, most of which are fine for
explaining the particular microscopic issue but which don't place it in a
macroscopic context.  After about 2 weeks of solid sleuthing and head
scratching,  I am still having a heck of a time getting my .ly file to print
a pdf and a MIDI file at the same time, and I haven't had any luck in using
the "score" section.  I can get a nice pdf if I comment out my score part,
but then it won't play MIDI.  I also have had a heck of a time with getting
my lyrics to match the right notes.  I tried using the "\lyrics" line but
couldn't get the syntax to work.

Also, what the tutorial needs is some kind of sense of how these smaller
pieces fit into a larger whole.  It's easy enough to see that "{a2 b1 c4is
(d8 e16)}" will write appropriate notes.  It's much harder to know what's
going wrong when they _don't_ appear that way as part of a larger song.

Please don't take this as a vent or that I'm upset---I'm not:  I could never
write music like this without Lilypond and really want to become more fluent
in writing it so that it doesn't take me so long to write songs down.  If I
can help in providing some new documentation along these lines please let me
know.

As an enthusiastic beginner learning the ropes, what I would love to see is:

1.  An annotated deconstruction of a well known song (melody and vocals). 
Preferably several---a classic rock piece, a classical piece, and a more
complex piece would work nicely.
2.  Color-coded examples throughout, so that the variable names and the .ly
codes are more easily distinguishable.
3.  A dictionary of syntax codes, linked (again) directly to larger examples
so that we can see how they work.  Saying "\score { . . . } doesn't really
help us if what's inside the brackets is a multi-nested set of commands.
4.  The tutorial examples reused in larger pieces so that we can more clearly
see how the small pieces become part of a larger whole.
5.  Much more detailed syntax debugging, with a list of what the error codes
mean.
6.  Perhaps, some clearer discussion about how to best _organize_ a song so
that as one writes, changes lyrics, switches notes around, the piece needs as
little rewriting as possible.
7.  The MIDI info seems quite thin.

If anyone out there knows answers or if this info already exists and I've
just been missing it, please post and tell me about it.  I'd love to get more
fluent with this neat program and look forward to helping improve it.

Happy New Year 2006 to all!