Re: missing lilypond-tex-metrics.tex

[joe ferguson]

With several decades' of programming behind me, one of the first things 
I look for in studying a new language is concise descriptions of the 
syntax of the language and of the structure of well-formed programs. 
It's also nice to get direction from experienced writers in the language 
as to style, since that can make heaps of difference in conveying your 
intent to other humans (or even to yourself, a few months later.) 
Lilypond uses many meta characters that define structure in various 
contexts, but the whole pile of delimiters and their context constraints 
can be quite confusing.

I would applaud anyone who would tackle the documentation update, 
bringing along the experience of a technical writer. There are actually 
three areas of expertise involved here: Writing, Programming, and Music. 
I would hope that the product of the rewrite (or additional section, 
which I think would be preferable) would get thorough reviewing from the 
programmer's and musician's points of view. I would be willing to review 
from the programmer's viewpoint. I leave the other views to the 
respective experts.

Aaron Mehl wrote:

> > I think we use "should be" and "must" fairly
> > interchangeably.
> >    
>  As a techwriter/user this confuses me. should be is
> a much weaker expression, like it doesn't have to but
> if you want.. must says that it is a requirement to
> have on of these.
>
>  
>
> > > then it says:
> > > "A .ly file contains any number of toplevel
> > > expressions, where a toplevel expression is one of
> > >      
> > the
> >    
> >
> > > following"
> > >
> > > well this is vague. because if some top level
> > >      
> > elements
> >    
> >
> > > are left out the file won't parse while if others
> > >      
> > are
> >    
> >
> > > left out it will.
> > >      
> > Well... but only _requirement_ is that there's some
> > music in
> >    
>
> You mean to say that if I write a lilypond file
> with a header and a'4 it will parse? I am trying here
> to clarify what the intent of the documentation is
> here, not be picky per se.
>
> A user doesn't want to know what he may or should do,
> but what he needs to get this up and running. What I
> mean is beating around the bush doesn't help. If this
> is a page detailing lilypond file structure it should
> do that specifically not with shoulds and mights. If
> there are different possiblilies they need to be laid
> out.
> I in fact recall that for structure there was never a
> one stop shop (on page) that in a straight forward
> manner detailed what is the structure (in detail) of a
> lilypond  file. I infact thought for years that the
> [that = this] format of almost all lilypond files I
> saw on the mailing list and the site was a requirement
> of Lilypond, as opposed to a feature.
>  
>
> > the file.  And even then I'm not certain that
> > lilypond will give
> > a parse error.
> >
> > If a file won't parse, then something else is wrong.
> >    
>
>  
>
> > > the example given doesn't use a \score {} block,
> > >      
> > so I
> >    
> >
> > > must assume that lilypond no longer requires a
> > >      
> > score
> >    
> >
> > > block?
> > >      
> > Correct.
> >
> >    
> >
> > > I see a layout block has this replaced the
> > >      
> > \paper{} ?
> >
> > Kind-of.  See the "Paper output" section in "Output
> > formats".
> >
> >    
> >
> > > I am in the mean time still trying to make a
> > >      
> > layout
> >    
> >
> > > with no includes and lyrics.
> > >      
> > In addition to reading the manual, you might want to
> > look at
> > some examples from Mutopia or LSR.
> >
> > - Graham
> >
> >
> >    
>
>
>                 
> __________________________________ 
> Discover Yahoo! 
> Stay in touch with email, IM, photo sharing and more. Check it out! 
> http://discover.yahoo.com/stayintouch.html
>
>
> _______________________________________________
> lilypond-user mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-user
>
>  

--
Joe Ferguson