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

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((X-offset . 20))

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((Y-offset . 40))

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

\once \override NonMusicalPaperColumn.line-break-system-details =
  #'((alignment-distances . (15)))

\once \override 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 start point 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 {
          \once \override
            Score.NonMusicalPaperColumn
                 .line-break-system-details = #'((Y-offset . 0))
          s1*5 \break
          \once \override
            Score.NonMusicalPaperColumn
                 .line-break-system-details = #'((Y-offset . 40))
          s1*5 \break
          \once \override
            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
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details = #'((extra-offset . (0 . 10)))
          s1*5 \break
          \once \override
            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 start point 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 {
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 20)
                 (alignment-distances . (10)))
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 60)
                 (alignment-distances . (15)))
          s1*5 \break
          \once \override
            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 start point 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 {
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 0)
                 (alignment-distances . (30 10)))
          s1*5 \break
          \once \override
            Score
            .NonMusicalPaperColumn
            .line-break-system-details
            = #'((Y-offset . 60)
                 (alignment-distances . (10 10)))
          s1*5 \break
          \once \override
            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.