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: Don Blaheta
Subject: Re: A simple diagram of a .ly file?
Date: Fri, 6 Jan 2006 20:53:35 -0600
User-agent: Mutt/1.2.5.1i

Quoth Graham Percival:
> 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.
> 
> 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.

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.  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.

  Every Lilypond document has three parts: a header, other definitions,
  and the score, in that order.  The header looks like this:
  
  \header {
    ...
  }
  
  and contains lines giving the title, composer, and so on (see section
  X.Y).  The other definitions can actually be empty, but many lilypond
  users like defining the melody or harmony at this point, to make their
  file more modular and easily organised.  (See section Z.W for how to
  make and access these definitions.)  Finally, the score.  A score looks
  like this:

  \score {
    \midi { ... }
    \layout { ... }
    ...
  }

  The \midi block can be left blank, or it can contain tempo information
  (or it can be omitted entirely if you don't want MIDI output).  The
  layout block contains global information about staff layout (see
  section U.V).  In the main body of the \score block comes the actual
  music, which can be typed in directly or can refer back to music entered
  in the "other definitions" section in the middle of the file.  See
  sections S-T for how to enter the music itself.

  Finally, it is recommended that at the top of the file, before even
  the \header block, you include two lines to let the lilypond
  interpreter know what style of input you are using:

  \version "2.6.0"
  \include "english.ly"
  
  The first line gives your current lilypond version; if you ever
  upgrade, lilypond will be able to warn you about changes you need to
  make.  The language definition need not match your native language or
  those of the lyrics in the file, but indicates how you refer to
  different notes: what the English-speaking world calls "B flat" and
  notates "bf" in lilypond, the German-speaking world calls "B", and the
  French-speaking world calls "si", so lilypond needs to know which
  naming system you're using.  See section Q.R for a list of valid choices.

The important thing to remember is that for anything but a detailed
program reference, you can give the big picture without telling the
whole story all at once.  Yes, lilypond will let you omit \layout
sometimes, but if you say that, then you have to talk about when and
why.  And then the reader gets confused, and you've not helped much.
Sure, you can arrange your file in a variety of ways, but it doesn't
hurt to say it "has three parts...", because it *can* and that will work
just fine until the user understands enough to want to rearrange it.

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....

> 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?

-- 
-=-Don address@hidden<http://www.blahedo.org/>-=-
UNIX is user friendly. It's just very selective about who its friends are.




reply via email to

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