11.4.4 Explicit staff and system positioning

One way to understand the VerticalAxisGroup and \paper settings explained in the previous two sections is as a collection of different settings that primarily concern the amount of vertical padding different staves and systems running down the page.

It is possible to approach vertical spacing in a different way using NonMusicalPaperColumn #'line-break-system-details. Where VerticalAxisGroup and \paper settings specify vertical padding, NonMusicalPaperColumn #'line-break-system-details specifies exact vertical positions on the page.

NonMusicalPaperColumn #'line-break-system-details accepts an associative list of five different settings:

• X-offset
• Y-offset
• alignment-offsets
• alignment-extra-space
• fixed-alignment-extra-space

Grob overrides, including the overrides for NonMusicalPaperColumn below, can occur in any of three different places in an input file:

• in the middle of note entry directly
• in a \context block
• in the \with block

When we override NonMusicalPaperColumn, we use the usual \override command in \context blocks and in the \with block. On the other hand, when we override NonMusicalPaperColumn in the middle of note entry, use the special \overrideProperty command. Here are some example NonMusicalPaperColumn overrides with the special \overrideProperty command:

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((X-offset . 20))

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((Y-offset . 40))

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))

\override NonMusicalPaperColumn
  #'line-break-system-details #'((alignment-offsets . (0 -15)))

\override NonMusicalPaperColumn
  #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
                                 (alignment-offsets . (0 -15)))

To understand how each of these different settings work, we begin by looking at an example that includes no overrides at all.

This score isolates line- and page-breaking information in a dedicated voice. This technique of creating a breaks voice will help keep layout separate from music entry as our example becomes more complicated. See Using an extra voice for breaks.

Explicit \breaks evenly divide the music into six measures per line. Vertical spacing results from LilyPond's defaults. To set the vertical startpoint of each system explicitly, we can set the Y-offset pair in the line-break-system-details attribute of the NonMusicalPaperColumn grob:

Note that line-break-system-details takes an associative list of potentially many values, but that we set only one value here. Note, too, that the Y-offset property here determines the exact vertical position on the page at which each new system will render.

Now that we have set the vertical startpoint of each system explicitly, we can also set the vertical startpoint of each staff within each system manually. We do this using the alignment-offsets subproperty of line-break-system-details.

Note that here we assign two different values to the line-break-system-details attribute of the NonMusicalPaperColumn grob. Though the line-break-system-details attribute alist accepts many additional spacing parameters (including, for example, a corresponding X-offset pair), we need only set the Y-offset and alignment-offsets pairs to control the vertical startpoint of every system and every staff. Finally, note that alignment-offsets specifies the vertical positioning of staves but not of staff groups.

Some points to consider:

• When using alignment-offsets, lyrics count as a staff.
• The units of the numbers passed to X-offset, Y-offset and alignment-offsets are interpreted as multiples of the distance between adjacent staff lines. Positive values move staves and lyrics up, negative values move staves and lyrics down.
• Because the NonMusicalPaperColumn #'line-break-system-details settings given here allow the positioning of staves and systems anywhere on the page, it is possible to violate paper or margin boundaries or even to print staves or systems on top of one another. Reasonable values passed to these different settings will avoid this.