LilyPond Notation Reference: 4.4.2 Explicit staff and system positioning

### 4.4.2 Explicit staff and system positioning

One way to understand the flexible vertical spacing mechanisms explained above is as a collection of settings that control the amount of vertical padding between staves and systems.

It is possible to approach vertical spacing in a different way using `NonMusicalPaperColumn.line-break-system-details`. While the flexible vertical spacing mechanisms specify vertical padding, `NonMusicalPaperColumn.line-break-system-details` can specify exact vertical positions on the page.

`NonMusicalPaperColumn.line-break-system-details` accepts an associative list of four different settings:

- `X-offset`
- `Y-offset`
- `extra-offset`
- `alignment-distances`

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))

>     \overrideProperty NonMusicalPaperColumn.line-break-system-details
>       #'((alignment-distances . (15)))

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

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

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               s1*5 \break
>               s1*5 \break
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

This score isolates both line-breaking 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. Also see Breaks.

By using explicit `\break` commands, the music is divided into five measures per line. Vertical spacing is from LilyPond’s own defaults but the vertical startpoint of each system is set explicitly using the `Y-offset` pair in the `line-break-system-details` attribute of the `NonMusicalPaperColumn` grob:

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               \overrideProperty
>                 Score.NonMusicalPaperColumn
>                      .line-break-system-details #'((Y-offset . 0))
>               s1*5 \break
>               \overrideProperty
>                 Score.NonMusicalPaperColumn
>                      .line-break-system-details #'((Y-offset . 40))
>               s1*5 \break
>               \overrideProperty
>                 Score.NonMusicalPaperColumn
>                      .line-break-system-details #'((Y-offset . 60))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

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.

In contrast to the absolute positioning available through `Y-offset` and `X-offset`, relative positioning is possible with the `extra-offset` property of `line-break-system-details`. Placement is relative to the default layout or to the absolute positioning created by setting `X-offset` and `Y-offset`. The property `extra-offset` accepts a `pair` consisting of displacements along the X-axis and Y-axis.

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               s1*5 \break
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details #'((extra-offset . (0 . 10)))
>               s1*5 \break
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details #'((extra-offset . (0 . 10)))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

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

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details
>                   #'((Y-offset . 20)
>                      (alignment-distances . (10)))
>               s1*5 \break
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details
>                   #'((Y-offset . 60)
>                      (alignment-distances . (15)))
>               s1*5 \break
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details
>                   #'((Y-offset . 85)
>                      (alignment-distances . (20)))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new Staff {
>             \repeat unfold 15 { d'4 d' d' d' }
>           }
>         >>
>       }
>     }

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-distances` pairs to control the vertical startpoint of every system and every staff. Finally, note that `alignment-distances` specifies the vertical positioning of staves but not of staff groups.

>     \header { tagline = ##f }
>     \paper { left-margin = 0\mm }
>     \book {
>       \score {
>         <<
>           \new Staff <<
>             \new Voice {
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details
>                   #'((Y-offset . 0)
>                      (alignment-distances . (30 10)))
>               s1*5 \break
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details
>                   #'((Y-offset . 60)
>                      (alignment-distances . (10 10)))
>               s1*5 \break
>               \overrideProperty
>                 Score
>                 .NonMusicalPaperColumn
>                 .line-break-system-details
>                   #'((Y-offset . 100)
>                      (alignment-distances . (10 30)))
>               s1*5 \break
>             }
>             \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
>           >>
>           \new StaffGroup <<
>             \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
>             \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
>           >>
>         >>
>       }
>     }

Some points to consider:

- When using `alignment-distances`, lyrics and other non-staff lines do not count as a staff.
- The units of the numbers passed to `X-offset`, `Y-offset`, `extra-offset` and `alignment-distances` 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.

#### See also

Snippets: Spacing.

#### LilyPond — Notation Reference v2.22.2 (stable-branch).