[Lilypond-auto] Issue 2560 in lilypond: Documentation suggestion (was: strange behaviour of \layout block variable)

[lilypond]

Status: Accepted
Owner: ----
Labels: Type-Documentation

New issue 2560 by address@hidden: Documentation suggestion (was:  
strange behaviour of \layout block variable)
http://code.google.com/p/lilypond/issues/detail?id=2560

Suggestion by Urs Liska:
http://lists.gnu.org/archive/html/bug-lilypond/2012-05/msg00139.html
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.
########################################

This is based oh this thread:
http://lists.gnu.org/archive/html/bug-lilypond/2012-05/msg00125.html