LilyPond Notation Reference: 4.3.2 Page breaking

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < Line breaking ]	[ Up : Breaks ]	[ Manual page breaking > ]

4.3.2 Page breaking

This section describes the different page breaking methods, and how to modify them.

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < Page breaking ]	[ Up : Page breaking ]	[ Optimal page breaking > ]

Manual page breaking

The default page breaking may be overridden by inserting \pageBreak or \noPageBreak commands. These commands are analogous to \break and \noBreak. They should be inserted at a bar line. These commands force and forbid a page break from happening at that bar line. Of course, the \pageBreak command also forces a line break.

The \pageBreak and \noPageBreak commands may also be inserted at top-level, between scores and top-level markups.

Within a score, automatic page breaks are prevented within music lying between \autoPageBreaksOff and \autoPageBreaksOn commands. Manual page breaks are unaffected by these commands.

There are also analogous settings to ragged-right and ragged-last which have the same effect on vertical spacing. If ragged-bottom is set to #t the systems will not be justified vertically. When ragged-last-bottom is set to #t, as it is by default, empty space is allowed at the bottom of the final page (or the final page in each \bookpart). See Fixed vertical spacing \paper variables.

Page breaks are computed by the page-breaking function. LilyPond provides several algorithms for computing page breaks, including ly:optimal-breaking, ly:page-turn-breaking and ly:minimal-breaking. The default is ly:optimal-breaking, but the value can be changed in the \paper block:

\paper {
  page-breaking = #ly:page-turn-breaking
}

When a book has many scores and pages, the page breaking problem may be difficult to solve, requiring large processing time and memory. To ease the page breaking process, \bookpart blocks are used to divide the book into several parts: the page breaking occurs separately on each part. Different page breaking functions may also be used in different book parts.

\bookpart {
  \header {
    subtitle = "Preface"
  }
  \paper {
     %% In a part consisting mostly of text,
     %% ly:minimal-breaking may be preferred
     page-breaking = #ly:minimal-breaking
  }
  \markup { … }
  …
}
\bookpart {
  %% In this part, consisting of music, the default optimal
  %% page breaking function is used.
  \header {
    subtitle = "First movement"
  }
  \score { … }
  …
}

Predefined commands

\pageBreak, \noPageBreak, \autoPageBreaksOn, \autoPageBreaksOff.

Known issues and warnings

The \once prefix is ineffective with \autoPageBreaksOn and \autoPageBreaksOff. If auto page breaking is off and is then turned on to permit a page break, it must remain on for a few bars (the precise number of bars depends on the score) before being turned off, else the opportunity to break the page will not be taken.

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < Manual page breaking ]	[ Up : Page breaking ]	[ Minimal page breaking > ]

Optimal page breaking

The ly:optimal-breaking function is LilyPond’s default method of determining page breaks. It attempts to find a page breaking that minimizes cramping and stretching, both horizontally and vertically. Unlike ly:page-turn-breaking, it has no concept of page turns.

Minimal page breaking

The ly:minimal-breaking function performs minimal computations to calculate the page breaking: it fills a page with as many systems as possible before moving to the next one. Thus, it may be preferred for scores with many pages, where the other page breaking functions could be too slow or memory demanding, or a lot of texts. It is enabled using:

\paper {
  page-breaking = #ly:minimal-breaking
}

One-page page breaking

The ly:one-page-breaking function is a special-purpose page breaking algorithm that automatically adjusts the page height to fit the music, so that everything fits on a single page. The paper-height variable in the paper block is ignored, but other settings work as usual. In particular, the spacing between the last system (or top level markup) and the footer can be customized with last-bottom-spacing in the paper block. The width of the page is left unmodified by default but can be set with paper-width in the paper block.

Known issues and warnings

ly:one-page-breaking is not currently compatible with \bookpart.

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < One-page page breaking ]	[ Up : Page breaking ]	[ One-line-auto-height page breaking > ]

One-line page breaking

The ly:one-line-breaking function is a special-purpose page breaking algorithm that puts each score on its own page, and on a single line. No titles or margins are typeset; only the score is displayed.

The page width is adjusted so that the longest score fits on one line. In particular, paper-width, line-width and indent variables in the \paper block are ignored, although left-margin and right-margin are still honored. The height of the page is left unmodified.

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < One-line page breaking ]	[ Up : Page breaking ]	[ Optimal page turning > ]

One-line-auto-height page breaking

The ly:one-line-auto-height-breaking function works just like ly:one-line-breaking except the page height is automatically modified to fit the height of the music. Specifically, the paper-height variable in the \paper block is set so that it spans the height of the tallest score plus the top-margin and bottom-margin.

Note that the top-system-spacing setting will affect the vertical position of the music. Set it to #f in a paper block to simply place the music between the top and bottom margins.

[ << Spacing issues ]	[Top][Contents][Index]	[ Changing defaults >> ]
[ < One-line-auto-height page breaking ]	[ Up : Page breaking ]	[ Vertical spacing > ]

Optimal page turning

Often it is necessary to find a page breaking configuration so that there is a rest at the end of every second page. This way, the musician can turn the page without having to miss notes. The ly:page-turn-breaking function attempts to find a page breaking minimizing cramping and stretching, but with the additional restriction that it is only allowed to introduce page turns in specified places.

There are two steps to using this page breaking function. First, you must enable it in the \paper block, as explained in Page breaking. Then you must tell the function where you would like to allow page breaks.

There are two ways to achieve the second step. First, you can specify each potential page turn manually, by inserting \allowPageTurn into your input file at the appropriate places.

If this is too tedious, you can add a Page_turn_engraver to a Staff or Voice context. The Page_turn_engraver will scan the context for sections without notes (note that it does not scan for rests; it scans for the absence of notes. This is so that single-staff polyphony with rests in one of the parts does not throw off the Page_turn_engraver). When it finds a sufficiently long section without notes, the Page_turn_engraver will insert an \allowPageTurn at the final bar line in that section, unless there is a ‘special’ bar line (such as a double bar), in which case the \allowPageTurn will be inserted at the final ‘special’ bar line in the section.

The Page_turn_engraver reads the context property minimumPageTurnLength to determine how long a note-free section must be before a page turn is considered. The default value for minimumPageTurnLength is (ly:make-moment 1/1). If you want to disable page turns, set it to something ‘very large’.

\new Staff \with { \consists Page_turn_engraver }
{
  a4 b c d |
  R1 | % a page turn will be allowed here
  a4 b c d |
  \set Staff.minimumPageTurnLength = #(ly:make-moment 5/2)
  R1 | % a page turn will not be allowed here
  a4 b r2 |
  R1*2 | % a page turn will be allowed here
  a1
}

When using volta repeats, the Page_turn_engraver will only allow a page turn during the repeat if there is enough time at the beginning and end of the repeat to turn the page back. If the repeat is too short then the Page_turn_engraver can be used to disable page turns by setting an appropriate value for the context property minimumRepeatLengthForPageTurn. In this case the Page_turn_engraver will only allows turns in repeats whose duration is longer than the value specified.

The page turning commands, \pageTurn, \noPageTurn and \allowPageTurn, may also be used at top-level, in top-level markups and between scores.

Predefined commands

\pageTurn, \noPageTurn, \allowPageTurn.

Known issues and warnings

Use only one Page_turn_engraver per score. If there are more, they will interfere with each other.

4.3.2 Page breaking

Manual page breaking

Predefined commands

See also

Known issues and warnings

Optimal page breaking

See also

Minimal page breaking

See also

One-page page breaking

Known issues and warnings

One-line page breaking

One-line-auto-height page breaking

Optimal page turning

Predefined commands

See also

Known issues and warnings

See also

LilyPond — Notation Reference v2.24.4 (stable-branch).