Re: Reorganizing the contents of the \paper block

[Graham Percival]

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.


Carl:
> 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.

Cheers,
- Graham