4.3.2 Page breaking

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


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

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 three algorithms for computing page breaks, 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.

See also

Notation Reference: \paper variables for page breaking.

Snippets: Spacing.


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.

See also

Snippets: Spacing.


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
}

See also

Snippets: Spacing.


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. This page breaking function does not typeset titles or margins; only the score will be displayed.

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


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
}

With 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 very short, the Page_turn_engraver can also be used to disable page turns by setting a value for the context property minimumRepeatLengthForPageTurn where as Page_turn_engraver only allows turns in repeats whose duration is longer than this value.

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.

See also

Notation Reference: \paper variables for line breaking.

Snippets: Spacing.

Known issues and warnings

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


Other languages: deutsch, español, français, italiano, 日本語.
About automatic language selection.

LilyPond — Notation Reference v2.19.10 (development-branch).