Re: Reorganizing the contents of the \paper block

[Trevor Bača]

On 2/7/07, David Rogers <address@hidden> wrote:
> On Wed, 7 Feb 2007 16:45:26 -0600, Trevor Bača wrote:
> > And now I see why Han-Wen keeps inviting a name change of the \paper
> > and \layout buckets (while implicitly discouraging the moving around
> > of settings between those two buckets): the buckets show the *scope*
> > of the different settings, which isn't really an attribute that can be
> > easily changed.
> >
> > OK. I get it. Now I see why the task is a renaming task rather than a
> > moving-around task.
> >
> > Hm ... more thinking ...
>
>
> The way this is typed in an input file has to make sense to the user. The user 
> should not be required to think like a computer. It has taken you, an obvious 
> expert, months and months to get his head around this. I never got it at all 
> until you explained it.
>
> The correct answer is (I believe) exactly as you proposed earlier. Talking 
> about Lilypond's internal logic is IMHO counterproductive. In fact, internally, 
> I suspect Lilypond should stay the same - it just needs to allow the user to 
> use it effectively by making (or even just *allowing*) the logical separation 
> between paper, headers, and music, which you already outlined.

Hi David, hi list,

I'm *definitely* in favor of clarifying the daylights out of what's
going on here with the different settings. They're *so* powerful but
very much in need of doc clarification.

However, I really do think we can have our cake (clear delineation of
functionality in a user-centric way that fits the problem domain of
engraving score) and eat it too (preserve the CSS-style overrides of
settings that Han-Wen has been explaining).

(BTW, the reason I've been cluttering up everyone's inbox here with so
much of this is that I've given myself the task of rewriting both the
vertical spacing docs in chapter 11 and also the proportional spacing
stuff, too. And, as it turns out, those things both hinge crucially on
two concepts -- the settings that started this thread, and also line-
and page-breaking. So this is all part of peeling back the onion to
hopefully get a good an even more accurate set of docs for vertical
and horizontal spacing.)

So how to have our cake and eat it too?

What if we start (and hear me out here because I know it sounds weird)
with abolishing the distinction between \paper and \layout altogether.
Just forget they ever existed. And let's instead create a generic
\settings block where we can make any of the 30 or 40 settings that
currently live today in either \paper or \layout. Oh, and we'll allow
ourselves to instantiate a \settings block at any of the three lexical
levels of scope allowed for in an .ly file -- at score-level, at
book-level, and at top-level:

%%% BEGIN GENERIC SETTINGS BLOCK %%%

\settings { } % these are top-level settings

\book {

  \settings {  } % these are book-level settings

  \score {
     \new Staff { c'4 }
     \settings { } % these are score-level settings
  }

}

%%% END %%%


Now with this structure it's at least 100% clear how the three
different possible \settings blocks all interact with each other:

1. lily first checks for a value at score-level; if found, use that
value, otherwise ...
2. check for the value at book-level; if found, use that value, otherwise ...
3. check for the value at top-level; if found, use that value,
otherwise use the system default value.

Pefectly clean, perfectly clear. And the term \settings doesn't
confuse anyone by making us wonder how it is that the different
settings can relate to each other. They're just settings. Big bags of
settings. Some deal with padding between systems, some deal with the
text used to render the composer's name.

But what about the (semantic) grouping that I started this thread
with? Doesn't it still make sense to group, for example, these ...

 ragged-bottom
 ragged-last-bottom
 system-count
 between-system-space
 between-system-padding
 horizontal-shift

... settings together somehow? I mean, these things actually do
pertain to each other at a logical level, right?

Yes, definitely. But maybe this logical, user-centric division can be
handled perfectly cleanly just in the docs? The docs for settings can
then look something like this (and this is obviously just a sketch,
some pseudocode for the actual docs that I'll clean up long before
sending to Graham):

"LilyPond supports 47 different different page layout and setup
settings. These settings divide into 5 different functional areas.
These five functional areas are:

* page dimensions
* page margins
* headers and footers
* the layout of systems
* the location of line- and page-breaks

In addition, LilyPond input files support three different places where
these different settings can be made. These three levels where
settings can be made are:

* score level
* book level
* top level

Some settings can be made only at score level and book level. Other
settings can be made at all three levels. In the detailed descriptions
that follow, we note whether a setting can be set at 2 or 3 levels.

< insert descriptions of all settings here, according to the five
functional areas given above >."


So how does this sound?

This gives strong logical and user-centric ordering in the docs while
keeping the cascading-lookup mechanism in place in the code.

Note that this is not a zero-code proposal, however: the idea of
collapsing \paper and \layout is a pretty serious structural change,
even though I think it makes extremely good sense.

[Sidenote: if this proposal to collapse \paper and \alyout does make
sense, then we'll have to decide what to do with the fact that there's
a second, equally important use for \layout blocks, which is the
overriding of context attributes ... which is a wholly separate thing
from making the different settings talked about in this thread, as
described in 9.2.6. This sort of thing:

\layout {
 ...
 \context {
   \Staff

   \set fontSize = #-2
   \override Stem #'thickness = #4.0
   \remove "Time_signature_engraver"
 }
}

Perhaps if we wind up wanting to collapse \layout and \paper, then we
can simply rip \context blocks out and leave them as free-standing
elements within a \score. But this is a sidenote until we consider
whether collapsing \paper and \layout even makes sense.]







--
Trevor Bača
address@hidden