Documentation suggestion (was: strange behaviour of \layout block variable)

[Urs Liska]

I have the following documentation suggestion concerning layout variables.
As it isn't really a 'short snippet' It'll probably need to be 
overworked somewhat, but I hope it is a solid start.
I'm not really sure if I found the right place in the NR to put it in.

I'd suggest not to add a tracker item until David had a look at it and 
told us if it is correct enough to be used ;-)

HTH
Urs


#####################################################

in

3.1.5. File structure

first bulleted paragraph

replace

"If more than one such definition of the same type is entered at the top 
level any definitions in the later expressions have precedence."

with

"If more than one such definition of the same type is entered at the top 
level the definitions are combined but in conflicting situations the 
later definitions take precedence

? Maybe add a reference to:


In

4.2.1 The \layout block

after the example, add the following:

Multiple \layout blocks can be entered as toplevel expressions. This can 
for example be useful if different settings are stored in separated 
files and included optionally. Internally a \layout block makes a copy 
of the current \layout configuration, applies any changes defined within 
the block and saves the result as the new current configuration. From 
the user's perspective the \layout blocks are combined, but in 
conflicting situations (when the same property is changed in different 
blocks) the later definitions take precedence.

If you write the following block after the one from the preceding example:

\layout {
  \context {
    \Voice
    \override TextScript #'color = #magenta
    \override Glissando #'thickness = #1.5
  }
}

the #'padding and #'color overrides for TextScript are combined, but the 
later Glissando #'thickness override replaces/hides the earlier one.


One can assign \layout blocks to variables and reuse them later, but 
this works slightly but significantly different from writing them literally.

If you define a variable like:

layoutVariable = \layout {
  \context {
    \Voice
    \override NoteHead #'font-size = #4
  }
}

it copies the current \layout configuration and adds the NoteHead 
#'font-size override, but it doesn't save it as the new current 
configuration. Be aware that the 'current configuration' is read when 
the variable is defined and not when it is used, so the content of the 
variable is dependent on its position in the source.

One can then use the variable inside another \layout block, e.g.

\layout {
  \layoutVariable
  \context {
    \Voice
    \NoteHead #'color = #red
}

Different from the syntax of the preceding examples this does *not* make 
a copy of the current configuration but uses the content of 
\layoutVariable as the base configuration for the further additions. 
This essentially means that any changes defined between the definition 
and the use of the variable are lost.

If \layoutVariable is defined (or included) immediately before being 
used, its content is just added to the current configuration. So in our 
example the \layout would consist of:

    TextScript #'padding = #1
    TextScript #'color = #magenta
    Glissando #'thickness = #1.5
    NoteHead #' font-size = #4
    NoteHead #' color = #red

plus the indent and the StaffGroup override.

But if the variable had already been defined before the first \layout 
block the current configuration would now  only contain

    NoteHead #' font-size= #4 % (written in the variable definition)
    NoteHead #' color = #red % (added after the use of the variable)


If carefully planned the use of \layout variables can be a valuable tool 
to structure the layout design of sources, and also to reset the \layout 
configuration to a known state.



########################################


Am 21.05.2012 09:58, schrieb David Kastrup:
> Urs Liska<address@hidden>  writes:
>
> > Thank you David,
> > I think I got it now and will find a solution how to deal with it
> > correctly and efficiently.
> >
> > Best
> > Urs
> >
> > Am 21.05.2012 07:20, schrieb David Kastrup:
> > > Urs Liska<address@hidden>   writes:
> > >
> > > > Do I understand correctly that if I write
> > > > \layout { ... }
> > > > I actually take
> > > >
> > > > "$defaultlayout"
> [...]
>
> If you have absorbed this and played with it, could you try putting
> together a suggestion for a documentation change that would have done
> the job of giving the necessary documentation for you?  My explanations
> tend to give a lot of technical details that are not helpful for getting
> a job done and need to get sorted out before being useful.