[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Reorganizing the contents of the \paper block

From: Graham Percival
Subject: Re: Reorganizing the contents of the \paper block
Date: Fri, 09 Feb 2007 16:30:47 -0800
User-agent: Thunderbird (Macintosh/20061207)

Trevor Bača wrote:
OTOH, I really do believe that the reason most
users walk around without a solid model of file structure (or score
structure) in their heads isn't because chapters 3 - 5 (which are
*amazingly* helpful and huge improvement over the previous manual,
which was essentially silent on these points) are in some way
deficient, but instead because the vast majority of actual lily code
which users (both new and experienced) look at simply doesn't
*reinforce* that file structure. See below ...

I disagree. (sidenote: there's info about file structure in chapter 10 as well, which is linked to in chapter 3 I believe).

Let's do this logically:
1)  experienced users understand the structure.
2) the purpose of the documentation is to allow an interested, reasonably intelligent, inexperienced user to do everything an experienced user can do. 3) interested, reasonably intelligent, inexperienced users do not understand the structure.
4)  the documentation is flawed.

I have no difficulty admitting that the docs are flawed ("flawed" = "not perfect"). If #3 is true -- and I admit that I do not currently believe* that is _is_ true -- then the docs should be improved. By now, everybody knows how to do this.

* I don't have a lot of evidence to back this up -- but then again, I doubt that other people have evidence to counter this claim.

I think if you asked 100 novice users of LilyPond about that
relationship, fewer than 5 could articulate it.

Trevor again:
Are users willfully ignoring 3 - 5?

My belief?  Yes.

Look, LilyPond is complicated. Before a new user starts doing serious work, he should read AT LEAST chapters 2, 3, 4, 5, 6, any relevant sections in 7 and 8, 10.1, 10.2, 11.1, appendix D, and know that appendix G and H exist.

That doesn't include any fancy things like \override, scheme, or changing the spacing. All that documentation -- probably about 100 pages of printed material -- just to properly write basic music syntax with the default output, without shooting himself in the foot by doing things incorrectly.

That's a lot of stuff to read. A _lot_. I've been experiencing similar pains: in the past year, I've written non-trivial programs (with little or no previous experience) in ChucK, perl, java, C++, python, and QT (not a language, but still requires a lot of doc-reading). I've had to read a lot of documentation, and sometimes I've wanted to scream -- if I know how to something in perl, why should I spend an hour reading the python tutorial to figure out how to do in it that language?!

But there really isn't another option. Programming languages are complicated. Fully-featured layout languages are complicated. You can't do anything (serious) in LaTeX without having a heavily-used pdf of "the short guide to LaTeX" on your desktop.

I don't blame users for ignoring chapters 3-5... but at the same time, I'm not going to wring my hands in sympathy for them. The information is there. Could it be improved? Sure. All documentation suggestions are welcome. Would it be easier for new users if every lilypond example were constructed in the same way? Yes, definitely. When I started writing Appendix D, I tried to make each template with the same style. But there's a lot of examples that need to be updated, and I don't have much time.

If anybody wants to volunteer to do a clean-up of the manual and LSR snippets -- I mean, cleaning up the LSR snippets to a higher level than I think the LSR maintainer should do -- then I will enthusiastically accept your help. Budget at least 50 hours for this task.

- Graham

reply via email to

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