lilypond-user
[Top][All Lists]
Advanced

[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





reply via email to

[Prev in Thread] Current Thread [Next in Thread]