[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Followup: I am a Lily confused about .ly file structure
From: |
Mats Bengtsson |
Subject: |
Re: Followup: I am a Lily confused about .ly file structure |
Date: |
Wed, 15 Dec 2004 19:24:11 +0100 |
User-agent: |
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.7.3) Gecko/20040913 |
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
=============================================