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 [EMAIL PROTECTED] 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: [EMAIL PROTECTED] WWW: http://www.s3.kth.se/~mabe =============================================
_______________________________________________ lilypond-user mailing list [EMAIL PROTECTED] http://lists.gnu.org/mailman/listinfo/lilypond-user
