Re: Followup: I am a Lily confused about .ly file structure

[Mats Bengtsson]

Basically, I agree with what you are saying. At the same time,
it's impossible to write a manual that describes every feature
on a level that is directly understandable to a person who has
never heard about the program. So, clearly we have to assume some
basic understanding of the general concepts, at least in the
later chapters of the manual. The Tutorial should ideally
provide a sufficient introduction to be able to follow the
rest of the manual. However, there's one part of the manual
that is written on an even higher level, namely the program
reference, which requires a fairly good understanding of
the chapter of "Changing defaults" to be fully useful.
I think these three levels of difficulty in the manual make
sense for such as complex program as LilyPond, where it is
impossible to describe every possible combination of features
in full detail.

I'm glad that you started the discussion with concrete examples
before sending the criticism below, which I personally
found too abstract to be able grasp what you actually meant.

Anyway, to stay concrete, the LilyPond program and the manual
is developed by a number of enthusiasts who do this on their
spare time without getting paid. So, if you have ideas on how
to improve the manual and are willing to spend some hours work
on it, you are welcome.
You don't say what version of the manual you read. Actually, the
manual has changed (and hopefully improved) a lot from version 2.2
to 2.4, so if you read the manual for version 2.2 you'll find something
better when you upgrade to version 2.4. One thing that happened after
the release of version 2.2 was that we finally found a volounteer
who was willing to spend time and effort on being main responsible
for the documentation.

   /Mats

John Sellers wrote:
> Note that NOTHING has meaning without a context, and many of the 
> examples in the Lilypond documentation describe things without 
> explicitly stating what general context the code fragment applies.  I do 
> NOT mean 'context' as used in Lilypond, but the context that constrains 
> the possible meaning of any code fragment.  For example, making a 
> particular statement in a court of law may have a very different outcome 
> then if you are being robbed by a murderer with a gun to your head.  The 
> meaning and implications of the statement are constrained by the context 
> within which it is said.
>
> The documentation writer see things perfectly clear because he/she knows 
> the context of  appropriate use of a particular  code example and so the 
> Tutorial seems perfectly clear and well written...which in fact it is, 
> if you are an experienced lilypond programmer.  The reader, however, may 
> not have a clue about the context that applies to a code example as 
> there are many possible different contexts at various points within any 
> .ly file.  IF ONE IS LOOKING AT CODE EXAMPLE FOR AN UNFAMILIAR CONCEPT 
> FOR THE FIRST TIME, THERE IS NO WAY TO BE SURE OF THE CORRECT CONTEXT OF 
> USE THAT CONCEPT UNLESS THE CORRECT CONTEXT OF USE IS SPECIFICALLY 
> CONVEYED TO THE READER BY SOME MECHANISM.
>
> So what is that machanism?
>
> John Sellers wrote:
>
> > I have gotten my feet wet with LilyPond, but I'm going nuts every time 
> > want do do something new.  [SNIP] (see previous e-mail, just sent to 
> > same as this e-mail)
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> lilypond-user mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/lilypond-user

--
=============================================
        Mats Bengtsson
        Signal Processing
        Signals, Sensors and Systems
        Royal Institute of Technology
        SE-100 44  STOCKHOLM
        Sweden
        Phone: (+46) 8 790 8463                         
        Fax:   (+46) 8 790 7260
        Email: address@hidden
        WWW: http://www.s3.kth.se/~mabe
=============================================