Structure of flexible vertical spacing alists

Each of the flexible vertical spacing \paper variables is an alist (association list) containing four keys:

• basic-distance – the vertical distance, measured in staff spaces, between the reference points of the two items, when no collisions would result, and no stretching or compressing is in effect. The reference point of a (title or top-level) markup is its highest point, and the reference point of a system is the vertical center of the nearest StaffSymbol – even if a non-staff line (such as a Lyrics context) is in the way. Values for basic-distance that are less than either padding or minimum-distance are not meaningful, since the resulting distance will never be less than either padding or minimum-distance.
• minimum-distance – the smallest allowable vertical distance, measured in staff spaces, between the reference points of the two items, when compressing is in effect. Values for minimum-distance that are less than padding are not meaningful, since the resulting distance will never be less than padding.
• padding – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff spaces.
• stretchability – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result). When positive, the significance of a particular dimension’s stretchability value lies only in its relation to the stretchability values of the other dimensions. For example, if one dimension has twice the stretchability of another, it will stretch twice as easily. Values should be non-negative and finite. The value +inf.0 triggers a programming_error and is ignored, but 1.0e7 can be used for an almost infinitely stretchable spring. If unset, the default value is set to basic-distance. Note that the dimension’s propensity to compress cannot be directly set by the user and is equal to (basic-distance − minimum-distance).

If a page has a ragged bottom, the resulting distance is the largest of:

• basic-distance,
• minimum-distance, and
• padding plus the smallest distance necessary to eliminate collisions.

For multi-page scores with a ragged bottom on the last page, the last page uses the same spacing as the preceding page, provided there is enough space for that.

Specific methods for modifying alists are discussed in Modifying alists. The following example demonstrates the two ways these alists can be modified. The first declaration updates one key value individually, and the second completely redefines the variable:

\paper {
  system-system-spacing.basic-distance = 8
  score-system-spacing =
    #'((basic-distance . 12)
       (minimum-distance . 6)
       (padding . 1)
       (stretchability . 12))
}

<< Back to Documentation Index

LilyPond Notation Reference v2.25.15 (development-branch).