[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: A simple diagram of a .ly file?
From: |
Graham Percival |
Subject: |
Re: A simple diagram of a .ly file? |
Date: |
Fri, 6 Jan 2006 14:18:53 -0800 |
On 4-Jan-06, at 8:54 PM, Ray wrote:
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.
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).
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).
Color coding is a feature of editors. I know that emacs and vim do
syntax highlighting; I'm pretty sure that jedit uses it as well.
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."
Most people have said that since the lilypond syntax is so flexible, it
doesn't make sense to include such information; I take the opposite
view. We need to have _some_ discussion about the general syntax -- in
the tutorial section -- since so many people are confused by this.
There's a technical description of the syntax in 5.8, but we should
cover some of that material in the tutorial.
I've bumped this higher on my list of stuff to do.
If I can help in providing some new documentation along these lines
please let me
know.
Of course you can help! See
http://lilypond.org/web/devel/participating/documentation-adding
Just remember to be as specific as possible. "there isn't enough docs
about guitars" isn't very helpful; saying "a lot of guitar music uses
BLAH; it would help those users if you added blah blah foo to the
manual and included an example like { \blah \blah \foo }" is
_extremely_ helpful.
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.
That's been proposed, and one or two people have offered to do so, but
I haven't seen them yet. There's room for them in chapter 4, but I'd
prefer short pieces (or portions of pieces). And by "short", I mean
about eight or sixteen bars (depending on the complexity of the piece).
If the example is longer than that, people will be less likely to read
the whole thing carefully... besides, the shorter the example, the less
work you need to do in writing the annotations. :)
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.
It's been proposed... there's an index, and we may soon have a "command
index", with links to the manual. As for larger (presumably annotated)
examples... I'm not certain about that.
There's basically two sides to basic lilypond use: knowing what certain
commands do (say, looking up \repeat to figure out that you want
\repeat volta 2 (... or is that \repeat 2 volta ? :)), and knowing how
to fit them together. Putting them together is a general input file
thing, and should be discussed on its own.
5. Much more detailed syntax debugging, with a list of what the error
codes
mean.
That would be a big technical undertaking, which I can't see happening
in the near future.
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.
4.1 attempts to address this... again, did you notice it, or was it
lacking?
7. The MIDI info seems quite thin.
If you know any more info about MIDI, please let me know. :)
There are three categories of problems with the docs:
1. Stuff I'm aware of, and is on my list of things to fix.
2. Stuff I'm not aware of, but can either fix or put on my list of
things to fix.
3. Stuff I may or may not be aware of, but am not able to fix due to
my lack of knowledge. MIDI certainly qualifies for this, as does
everything in chapter 7.
Cheers,
- Graham Percival, Documentation Editor