Re: Reorganizing the contents of the \paper block

[Trevor Bača]

On 2/8/07, Graham Percival <address@hidden> wrote:
> Han-Wen Nienhuys wrote:
> > Trevor Bača escreveu:
> >> Wow. I really like this. Anyone else?
> >
> > I don't.
>
> I don't like it either, but for different reasons.
>
> - how do identifiers work?  Where do we define them?  Does it make sense
> for an identifier to be bound up in the "File" or "Book" or "Staff"
> contexts?

Right. Han-Wen makes this point, too, later in the thread, and I think
I'm finally getting it. Putting forth a strict File { Book { Score {
Staff { Voice } } } } model only works if our input files are limited
to *static* data definitions or "pure" expressions (more or less like
XML).

Our input files do, in fact, contain static data definitions, or
"pure" expressions, as Han-Wen writes ...

> Some parts of the input resemble 'pure' expressions
> (ie. data), for example \markup and music expressions,
> but also \book and \score.

... but -- crucially -- our input files also contain dynamic commands
(ie, expressions with side effects).

Music expressions and markup may very well be the most *interesting*
parts of an input file, but they are not the *only* parts of an input
file, and this is where the File { Book { Score ... }  } model won't
work.


> - explicitly adding everything is fine for big files, but we have about
> 300 bugs and we'll have another 200 during the next year.  I really
> don't want to add extra fluff to them... and that says nothing about the
> docs.

True. I still think this is a tricky question. I write a number of
snippet and bugs and it would definitely be more effort to wrap each
one in \score, etc. 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 ...


> You said that university people had problem with file structure... were
> you teaching this course with the new-ish chapters 3-5?  Did you point
> them at the templates?  IMO, if you've read 3.1 - 3.3, 4.1 - 4.2, and a
> couple of the templates in Appendix D, it's clear how lilypond files
> work.  If not, we should improve those docs instead of making a
> radically new file structure.

I  agree now (after going through all this) that a radically new file
structure won't help.

However, I also think that chatpers 3 - 5 are quite well written and
don't need any serious updates.

And yet, as Carl points out (and I agree), the fact is that most users
(probably even experienced users) don't walk around with a solid
mental picture of file structure (or score model -- and I suppose
those two things are different) in their heads, CS:

"... notes exist in Voices which exist in Staffs
which exist in Scores.

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

I think if you asked 100 users who had created "normal" music (i.e.,
music that doesn't require any special constructs, but can be based on
templates and examples), 50 or less could articulate that relationship.

And even fewer could articulate that Scores exist in Books which exist
in Paper."

/CS

I think Carl is right on this. But if chapters 3 - 5 actually are
sufficient (and I think they are, minus maybe a couple of smallish
additions here and there) then what's going on? If we have well
written descriptions of file structure (and score structure), then why
do users keep bringing so many structure-related questions to the
table (which we can see, for example, in Mats's need to keep repeating
basic skeleton structure over and over in his didactic mail for new
users)? Are users willfully ignoring 3 - 5? Or is something else going
on here?

The answer must be that the parts of the docs and the list that users
actually use all the time when they're writing music don't reinforce
file or score structure. IOW, we detail file and score structure well
in chapters 3 - 5, but the parts of the manual and the list that
people use all the time (how do I add articulations? how do I move
slur points around? can I change whether accidentals are forced to
print or not?, etc etc) don't do anything to reinforce these
structures and, in fact, render the structures mostly invisible.

I dunno. I don't wanna type more stuff (explicit \score and \book and
whatever) all the time, but I'm pretty convinced that both file
structure and score structure will remain confusing for new and even
experienced users right up until the point that we do make such a
requirement.


--
Trevor Bača
address@hidden