Re: Reorganizing the contents of the \paper block

[Trevor Bača]

On 2/8/07, Mats Bengtsson <address@hidden> wrote:
> Carl D. Sorensen wrote:
> > On a related note, I think it would be cleaner to _always_ require users to put in the 
> necessary scope levels, i.e. don't have lilypond put the \book block in by default.  It 
> would make it a bit harder to get started, but would make it much easier to move from the 
> "beginning user" stage to doing complicated scores.
> >
> Honestly, how many of you have ever used several \book blocks in the
> same file (which is the only reason ever to to use an explicit \book block)?
> Therefore, I don't think it's a good idea to make the \book compulsory.
> On the other hand, I have argued a number of times that we should make
> \score{...} compulsory. Primarily for the benefit of beginners, since it
> makes it much more clear what lines in a file that really result in any
> output and which are just macro definitions. I have seen many question
> on the mailing list that are related to the fact that people don't realize
> what becomes a \score and what doesn't.
> Also, for more experienced users it give a natural starting point when you
> look at a .ly file that you wrote yourself some year ago or that
> somebody else
> has written, just like I always start by looking or the main() function
> when
> looking at a C or C++ program.
> Then, again, I don't think it would be a good idea to force people to
> enter all scope levels. Then even the simplest example file would look like
> \score{
>   \new Staff {
>     \new Voice {
>       c'1
>     }
>   }
> }

I'm still mulling over the detailed and helpful answers everyone's
been sending to the main thread, but while doing I'd like to chime in
on this sidepoint, too.

Just in the last couple of months I've had the opportunity to teach
LilyPond to university composers in both California and Texas. The
experience has been extremely insightful, of course, because I've been
forced to answer questions that I'd forgotten having when I started
out. It's also been helpful because the audience for those couple of
classes have been *extremely* insightful adults --  all of them with
the knowledge and perspectives of professional composers and very many
of them with a substantial programming background as well.

And the conclusion from the teaching of Lily that I've done so far is
that *BY FAR AND AWAY* the greatest points of confusion all concern
file structure.

I can't prove that this confusion results from the implicit-ness of so
many of our examples in the docs on the list, etc, but I strongly
suspect this is the case.

A perfect case in point are some of the examples in the docs I've had
to check while writing the main part of this thread about the scoping
and meaning differences between \paper and \layout. Consider just the
very first words of chapter 11, which concern the rather concrete
concept of physical dimensions of paper:

"To change the paper size, there are two commands,

#(set-default-paper-size "a4")
\paper {
 #(set-paper-size "a4")
}

The first command sets the size of all pages. The second command sets
the size of the pages that the \paper block applies to – if the \paper
block is at the top of the file, then it will apply to all pages. If
the \paper block is inside a \book, then the paper size will only
apply to that book."

This is actually extraordinarily difficult to cope with when you first
start using the program. Why? Because you don't know where these two
different commands *are supposed to physically sit in the input file*.
What is this book block the explanation referes to (but which doesn't
appear in the example and which nobody seems to use)? And what is this
top level? Is the example I'm looking at here at top level? It
certainly looks that way, but how can I be sure?

(I know that the text is perfectly clear once you're an experienced
user; but put yourself in the shoes of a new user and it really is
difficult to visualize the implicit scoping levels that the docs
everywhere refer to and the examples everywhere omit.)

So what to do?

Forcing all input files to be "fullly qualified" will probably lead to
a religious war (although, if it matters, I'll go on record as being
in favor of such a move -- if you really need to abbreviate files all
the time you're probably able to whip up a 4-line shell script to do
so).

OTOH, fully qualifying at least the most important examples in the
docs -- especiallly where we're talking about settings that can and do
live in more than one scope or input construct -- seems to be an
obvious good step.

Even so, I think even with fully qualified examples we still need some
language that makes it easy to say things like "Set the command
#(set-paper-size "a4") inside either a book-level \paper block or a
top-level \paper block. Set the command command
#(set-default-paper-size "a4") at top level outside of any input block
whatsoever." I think sentences lke that probably blow right over the
heads of most readers both because there's no mental picture of what a
"book-level \paper block" is and because we don't have a fixed,
easy-to-speak phase for "book-level \paper block" (which is a pretty
abstract concept if you step back for a moment).

So, anyway, I think that one of the big challenges in our
communication (whether docs or list or whatever) is being able to
easily say with written language just *WHERE* a setting can be made --
inside of what construct or context and at which of three levels of
scope.

* * *

One last point. The difficulty of talking about *where* in the
structure of an input file a setting is to occur, might be
considerably lessened if we combine the suggestion to collapse \paper
and \layout into a single \settings block together with a second
suggestion to qualify the \settings blocks by the three different
levels of scope in which they occur. For example:

%%% BEGIN %%%

\global-settings { }

\book {

 \book-settings { }

  \score {

       \new Staff { }
       \score-settings { }

   }

}

%%% END %%%


The language is actually then considerably clearer: no more \paper (at
two scoping levels) and \layout (at three scoping levels). Just
\score-settings, \book-settings and \global-settings naming unique
slots for input entry. Furthermore, examples in the docs or on the
list like \paper { whatever } will no longer be ambiguous as to level
of scope. We will have either \book-settings { whatever } or
\global-settings { whatever } instead.



--
Trevor Bača
address@hidden