LilyPond Notation Reference: 4.1 Page layout

4.1 Page layout

This section discusses page layout options for the \paper block.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.1.1 The `\paper` block

\paper blocks may be placed in three different places to form a descending hierarchy of \paper blocks:

At the top of the input file, before all \book, \bookpart, and \score blocks.
Within a \book block but outside all the \bookpart and \score blocks within that book.
Within a \bookpart block but outside all \score blocks within that bookpart.

A \paper block cannot be placed within a \score block.

The values of the fields filter down this hierarchy, with the values set higher in the hierarchy persisting unless they are over-ridden by a value set lower in the hierarchy.

Several \paper blocks can appear at each of the levels, for example as parts of several \included files. If so, the fields at each level are merged, with values encountered last taking precedence if duplicated fields appear.

Settings that can appear in a \paper block include:

the set-paper-size scheme function,
\paper variables used for customizing page layout, and
markup definitions used for customizing the layout of headers, footers, and titles.

The set-paper-size function is discussed in the next section, Paper size and automatic scaling. The \paper variables that deal with page layout are discussed in later sections. The markup definitions that deal with headers, footers, and titles are discussed in Custom titles headers and footers.

Most \paper variables will only work in a \paper block. The few that will also work in a \layout block are listed in The \layout block.

Except when specified otherwise, all \paper variables that correspond to distances on the page are measured in millimeters, unless a different unit is specified by the user. For example, the following declaration sets top-margin to ten millimeters:

\paper {
  top-margin = 10
}

To set it to 0.5 inches, use the \in unit suffix:

\paper {
  top-margin = 0.5\in
}

The available unit suffixes are \mm, \cm, \in, and \pt. These units are simple values for converting from millimeters; they are defined in ‘ly/paper-defaults-init.ly’. For the sake of clarity, when using millimeters, the \mm is typically included in the code, even though it is not technically necessary.

It is also possible to define \paper values using Scheme. The Scheme equivalent of the above example is:

\paper {
  #(define top-margin (* 0.5 in))
}

4.1.2 Paper size and automatic scaling

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Setting the paper size

‘A4’ is the default value when no explicit paper size is set. However, there are two functions that can be used to change it:

set-default-paper-size

#(set-default-paper-size "quarto")

which must always be placed at the toplevel scope, and

set-paper-size

\paper {
  #(set-paper-size "tabloid")
}

which must always be placed in a \paper block.

If the set-default-paper-size function is used in the toplevel scope, it must come before any \paper block. set-default-paper-size sets the paper size for all pages, whereas set-paper-size only sets the paper size for the pages that the \paper block applies to. For example, if the \paper block is at the top of the file, then it will apply the paper size to all pages. If the \paper block is inside a \book, then the paper size will only apply to that book.

When the set-paper-size function is used, it must be placed before any other functions used within the same \paper block. See Automatic scaling to paper size.

Paper sizes are defined in ‘scm/paper.scm’, and while it is possible to add custom sizes, they will be overwritten on subsequent software updates. The available paper sizes are listed in Predefined paper sizes.

The following command can be used in the file to add a custom paper size which can then be used with set-default-paper-size or set-paper-size as appropriate,

#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))

\paper {
  #(set-paper-size "my size")
}

The units in (inches), cm (centimeters) and mm (millimeters) can all be used.

If the symbol 'landscape is added to the paper size function, pages will be rotated by 90 degrees, and wider line widths will be set accordingly.

#(set-default-paper-size "a6" 'landscape)

Swapping the paper dimensions without having the print rotated (like when printing to postcard size, or creating graphics for inclusion rather than a standalone document) can be achieved by appending ‘landscape’ to the name of the paper size itself:

#(set-default-paper-size "a6landscape")

When the paper size ends with an explicit ‘landscape’ or ‘portrait’, the presence of a 'landscape symbol only affects print orientation, not the paper dimensions used for layout.

Automatic scaling to paper size

If the paper size is changed with one of the scheme functions (set-default-paper-size or set-paper-size), the values of several \paper variables are automatically scaled to the new size. To bypass the automatic scaling for a particular variable, set the variable after setting the paper size. Note that the automatic scaling is not triggered by setting the paper-height or paper-width variables, even though paper-width can influence other values (this is separate from scaling and is discussed below). The set-default-paper-size and set-paper-size functions are described in Setting the paper size.

The vertical dimensions affected by automatic scaling are top-margin and bottom-margin (see Fixed vertical spacing \paper variables). The horizontal dimensions affected by automatic scaling are left-margin, right-margin, inner-margin, outer-margin, binding-offset, indent, and short-indent (see Horizontal spacing \paper variables).

The default values for these dimensions are set in ‘ly/paper-defaults-init.ly’, using internal variables named top-margin-default, bottom-margin-default, etc. These are the values that result at the default paper size a4. For reference, with a4 paper the paper-height is 297\mm and the paper-width is 210\mm.

4.1.3 Fixed vertical spacing `\paper` variables

Note: Some \paper dimensions are automatically scaled to the paper size, which may lead to unexpected behavior. See Automatic scaling to paper size.

Default values (before scaling) are defined in ‘ly/paper-defaults-init.ly’.

paper-height: The height of the page, unset by default. Note that the automatic scaling of some vertical dimensions is not affected by this.
top-margin: The margin between the top of the page and the top of the printable area. If the paper size is modified, this dimension’s default value is scaled accordingly.
bottom-margin: The margin between the bottom of the printable area and the bottom of the page. If the paper size is modified, this dimension’s default value is scaled accordingly.
ragged-bottom: If this is set to true, systems will be set at their natural spacing, neither compressed nor stretched vertically to fit the page.
ragged-last-bottom: If this is set to false, then the last page, and the last page in each section created with a \bookpart block, will be vertically justified in the same way as the earlier pages.

Known issues and warnings

The titles (from the \header block) are treated as a system, so ragged-bottom and ragged-last-bottom will add space between the titles and the first system of the score.

Explicitly defined paper-sizes will override any user-defined top or bottom margin settings.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4.1.4 Flexible vertical spacing `\paper` variables

In most cases, it is preferable for the vertical distances between certain items (such as margins, titles, systems, and separate scores) to be flexible, so that they stretch and compress nicely according to each situation. A number of \paper variables (listed below) are available to fine-tune the stretching behavior of these dimensions.

Note that the \paper variables discussed in this section do not control the spacing of staves within individual systems. Within-system spacing is controlled by grob properties, with settings typically entered inside a \score or \layout block, and not inside a \paper block. See Flexible vertical spacing within systems.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Structure of flexible vertical spacing alists

Each of the flexible vertical spacing \paper variables is an alist (association list) containing four keys:

basic-distance – the vertical distance, measured in staff-spaces, between the reference points of the two items, when no collisions would result, and no stretching or compressing is in effect. The reference point of a (title or top-level) markup is its highest point, and the reference point of a system is the vertical center of the nearest StaffSymbol – even if a non-staff line (such as a Lyrics context) is in the way. Values for basic-distance that are less than either padding or minimum-distance are not meaningful, since the resulting distance will never be less than either padding or minimum-distance.
minimum-distance – the smallest allowable vertical distance, measured in staff-spaces, between the reference points of the two items, when compressing is in effect. Values for minimum-distance that are less than padding are not meaningful, since the resulting distance will never be less than padding.
padding – the minimum required amount of unobstructed vertical whitespace between the bounding boxes (or skylines) of the two items, measured in staff-spaces.
stretchability – a unitless measure of the dimension’s relative propensity to stretch. If zero, the distance will not stretch (unless collisions would result). When positive, the significance of a particular dimension’s stretchability value lies only in its relation to the stretchability values of the other dimensions. For example, if one dimension has twice the stretchability of another, it will stretch twice as easily. Values should be non-negative and finite. The value +inf.0 triggers a programming_error and is ignored, but 1.0e7 can be used for an almost infinitely stretchable spring. If unset, the default value is set to basic-distance. Note that the dimension’s propensity to compress cannot be directly set by the user and is equal to (basic-distance - minimum-distance).

If a page has a ragged bottom, the resulting distance is the largest of:

basic-distance,
minimum-distance, and
padding plus the smallest distance necessary to eliminate collisions.

For multi-page scores with a ragged bottom on the last page, the last page uses the same spacing as the preceding page, provided there is enough space for that.

Specific methods for modifying alists are discussed in Modifying alists. The following example demonstrates the two ways these alists can be modified. The first declaration updates one key-value individually, and the second completely redefines the variable:

\paper {
  system-system-spacing.basic-distance = #8
  score-system-spacing =
    #'((basic-distance . 12)
       (minimum-distance . 6)
       (padding . 1)
       (stretchability . 12))
}

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

List of flexible vertical spacing `\paper` variables

The names of these variables follow the format upper-lower-spacing, where upper and lower are the items to be spaced. Each distance is measured between the reference points of the two items (see the description of the alist structure above). Note that in these variable names, the term ‘markup’ refers to both title markups (bookTitleMarkup or scoreTitleMarkup) and top-level markups (see File structure). All distances are measured in staff-spaces.

Default settings are defined in ‘ly/paper-defaults-init.ly’.

markup-system-spacing: the distance between a (title or top-level) markup and the system that follows it.
score-markup-spacing: the distance between the last system of a score and the (title or top-level) markup that follows it.
score-system-spacing: the distance between the last system of a score and the first system of the score that follows it, when no (title or top-level) markup exists between them.
system-system-spacing: the distance between two systems in the same score.
markup-markup-spacing: the distance between two (title or top-level) markups.
last-bottom-spacing: the distance from the last system or top-level markup on a page to the bottom of the printable area (i.e., the top of the bottom margin).
top-system-spacing: the distance from the top of the printable area (i.e., the bottom of the top margin) to the first system on a page, when there is no (title or top-level) markup between the two.
top-markup-spacing: the distance from the top of the printable area (i.e., the bottom of the top margin) to the first (title or top-level) markup on a page, when there is no system between the two.

4.1.5 Horizontal spacing `\paper` variables

Note: Some \paper dimensions are automatically scaled to the paper size, which may lead to unexpected behavior. See Automatic scaling to paper size.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

`\paper` variables for widths and margins

Default values (before scaling) that are not listed here are defined in ‘ly/paper-defaults-init.ly’.

paper-width

The width of the page, unset by default. While paper-width has no effect on the automatic scaling of some horizontal dimensions, it does influence the line-width variable. If both paper-width and line-width are set, then left-margin and right-margin will also be updated. Also see check-consistency.

line-width

When specified in a \paper block this defines the horizontal extent available for the staff lines in un-indented systems. If left unspecified, the paper’s line-width is determined from (paper-width - left-margin - right-margin). If the paper’s line-width is specified, and both left-margin and right-margin are not, then the margins will be updated to center the systems on the page automatically. Also see check-consistency.

line-widths for individual scores can be specified in the scores’ \layout blocks. These values control the width of the lines produced on a score-by-score basis. If line-width is not specified for a score, it defaults to the paper’s line-width. Setting a score’s line-width has no effect on the paper margins. Staff lines, of a length determined by the score’s line-width, are left-aligned within the paper area defined by the paper’s line-width. If the score and paper line-widths are equal, the staff lines will extend exactly from the left margin to the right margin, but if the score’s line-width is greater than the paper’s line-width the staff lines will run over into the right margin.

left-margin

The margin between the left edge of the page and the start of the staff lines in unindented systems. If the paper size is modified, this dimension’s default value is scaled accordingly. If left-margin is unset, and both line-width and right-margin are set, then left-margin is set to (paper-width - line-width - right-margin). If only line-width is set, then both margins are set to ((paper-width - line-width) / 2), and the systems are consequently centered on the page. Also see check-consistency.

right-margin

The margin between the right edge of the page and the end of the staff lines in non-ragged systems. If the paper size is modified, this dimension’s default value is scaled accordingly. If right-margin is unset, and both line-width and left-margin are set, then right-margin is set to (paper-width - line-width - left-margin). If only line-width is set, then both margins are set to ((paper-width - line-width) / 2), and the systems are consequently centered on the page. Also see check-consistency.

check-consistency

If this is true (the default value), print a warning if left-margin, line-width, and right-margin do not exactly add up to paper-width, and replace each of these (except paper-width) with their default values (scaled to the paper size if necessary). If set to false, ignore any inconsistencies and allow systems to run off the edge of the page.

ragged-right

If set to true, systems will not fill the line width. Instead, systems end at their natural horizontal length. Default: #t for scores with only one system, and #f for scores with two or more systems. This variable can also be set in a \layout block.

ragged-last

If set to true, the last system in the score will not fill the line width. Instead the last system ends at its natural horizontal length. Default: #f. This variable can also be set in a \layout block.

Known issues and warnings

Explicitly defined paper-sizes will override any user-defined left or right margin settings.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

`\paper` variables for two-sided mode

Default values (before scaling) are defined in ‘ly/paper-defaults-init.ly’.

two-sided: If set to true, use inner-margin, outer-margin and binding-offset to determine margins depending on whether the page number is odd or even. This overrides left-margin and right-margin.
inner-margin: The margin all pages have at the inner side if they are part of a book. If the paper size is modified, this dimension’s default value is scaled accordingly. Works only with two-sided set to true.
outer-margin: The margin all pages have at the outer side if they are part of a book. If the paper size is modified, this dimension’s default value is scaled accordingly. Works only with two-sided set to true.
binding-offset: The amount inner-margin is increased to make sure nothing will be hidden by the binding. If the paper size is modified, this dimension’s default value is scaled accordingly. Works only with two-sided set to true.

`\paper` variables for shifts and indents

Default values (before scaling) that are not listed here are defined in ‘ly/paper-defaults-init.ly’.

horizontal-shift: The amount that all systems (including titles and system separators) are shifted to the right. Default: 0.0\mm.
indent: The level of indentation for the first system in a score. If the paper size is modified, this dimension’s default value is scaled accordingly. The space within line-width available for the first system is reduced by this amount. indent may also be specified in \layout blocks to set indents on a score-by-score basis.
short-indent: The level of indentation for all systems in a score besides the first system. If the paper size is modified, this dimension’s default value is scaled accordingly. The space within line-width available for systems other than the first is reduced by this amount. short-indent may also be specified in \layout blocks to set short indents on a score-by-score basis.

4.1.6 Other `\paper` variables

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

`\paper` variables for line breaking

max-systems-per-page: The maximum number of systems that will be placed on a page. This is currently supported only by the ly:optimal-breaking algorithm. Default: unset.
min-systems-per-page: The minimum number of systems that will be placed on a page. This may cause pages to be overfilled if it is made too large. This is currently supported only by the ly:optimal-breaking algorithm. Default: unset.
systems-per-page: The number of systems that should be placed on each page. This is currently supported only by the ly:optimal-breaking algorithm. Default: unset.
system-count: The number of systems to be used for a score. Default: unset. This variable can also be set in a \layout block.

`\paper` variables for page breaking

Default values not listed here are defined in ‘ly/paper-defaults-init.ly’

page-breaking: The page-breaking algorithm to use. Choices are ly:minimal-breaking, ly:page-turn-breaking, ly:one-page-breaking, ly:one-line-breaking, ly:one-line-auto-height-breaking, and ly:optimal-breaking (the default).
page-breaking-system-system-spacing: Tricks the page breaker into thinking that system-system-spacing is set to something different than it really is. For example, if page-breaking-system-system-spacing.padding is set to something substantially larger than system-system-spacing.padding, then the page-breaker will put fewer systems on each page. Default: unset.
page-count: The number of pages to be used for a score, unset by default.

The following variables are effective only when page-breaking is set to ly:page-turn-breaking. Page breaks are then chosen to minimize the number of page turns. Since page turns are required on moving from an odd-numbered page to an even-numbered one, a layout in which the last page is odd-numbered will usually be favoured. Places where page turns are preferred can be indicated manually by inserting \allowPageTurn or automatically by including the Page_turn_engraver (see Optimal page turning).

If there are insufficient choices available for making suitable page turns, LilyPond may insert a blank page either within a score, between scores (if there are two or more scores), or by ending a score on an even-numbered page. The values of the following three variables may be increased to make these actions less likely.

The values are penalties, i.e., the higher the value the less likely will be the associated action relative to other choices.

blank-page-penalty: The penalty for having a blank page in the middle of a score. If blank-page-penalty is large and ly:page-turn-breaking is selected, then LilyPond will be less likely to insert a page in the middle of a score. Instead, it will space out the music further to fill the blank page and the following one. Default: 5.
blank-last-page-penalty: The penalty for ending the score on an even-numbered page. If blank-last-page-penalty is large and ly:page-turn-breaking is selected, then LilyPond will be less likely to produce a score in which the last page is even-numbered. Instead, it will adjust the spacing in order to use one page more or one page less. Default: 0.
blank-after-score-page-penalty: The penalty for having a blank page after the end of one score and before the next. By default, this is smaller than blank-page-penalty, so that blank pages after scores are inserted in preference to blank pages within a score. Default: 2.

`\paper` variables for page numbering

Default values not listed here are defined in ‘ly/paper-defaults-init.ly’

auto-first-page-number: The page breaking algorithm is affected by the first page number being odd or even. If set to true, the page breaking algorithm will decide whether to start with an odd or even number. This will result in the first page number remaining as is or being increased by one. Default: #f.
first-page-number: The value of the page number on the first page.
print-first-page-number: If set to true, a page number is printed on the first page.
print-page-number: If set to false, page numbers are not printed.
page-number-type: The type of numerals used for page numbers. Choices include roman-lower, roman-upper and arabic. Default: 'arabic.

Known issues and warnings

Odd page numbers are always on the right. If you want the music to start on page 1 there must be a blank page on the back of the cover page so that page 1 is on the right hand side.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

Miscellaneous `\paper` variables

page-spacing-weight

The relative importance of page (vertical) spacing and line (horizontal) spacing. High values will make page spacing more important. Default: 10.

print-all-headers

If set to true, this will print all headers for each \score in the output. Normally only the piece and opus header variables are printed. Default: #f.

system-separator-markup

A markup object that is inserted between systems, often used for orchestral scores. Default: unset. The \slashSeparator markup, defined in ‘ly/titling-init.ly’, is provided as a sensible default, for example:

#(set-default-paper-size "a8")

\book {
  \paper {
    system-separator-markup = \slashSeparator
  }
  \header {
    tagline = ##f
  }
  \score {
    \relative { c''1 \break c1 \break c1 }
  }
}

footnote-separator-markup

A markup object that is inserted above the footnote texts at the bottom of the page. Default: a centered horizontal line, defined in ‘ly/paper-defaults-init.ly’.

Known issues and warnings

The default page header puts the page number and the instrument field from the \header block on a line.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

This document was generated by gub on July 13, 2020 using texi2html 1.82.

Andere talen: català, deutsch, español, français, italiano, 日本語.
Gebruik van automatische taalkeuze.

4.1.1 The `\paper` block
4.1.2 Paper size and automatic scaling
4.1.3 Fixed vertical spacing `\paper` variables
4.1.4 Flexible vertical spacing `\paper` variables
4.1.5 Horizontal spacing `\paper` variables
4.1.6 Other `\paper` variables

`\paper` variables for line breaking
`\paper` variables for page breaking
`\paper` variables for page numbering
Miscellaneous `\paper` variables

4.1 Page layout

4.1.1 The `\paper` block

See also

4.1.2 Paper size and automatic scaling

Setting the paper size

See also

Automatic scaling to paper size

See also

4.1.3 Fixed vertical spacing `\paper` variables

See also

Known issues and warnings

4.1.4 Flexible vertical spacing `\paper` variables

Structure of flexible vertical spacing alists

List of flexible vertical spacing `\paper` variables

See also

4.1.5 Horizontal spacing `\paper` variables

`\paper` variables for widths and margins

See also

Known issues and warnings

`\paper` variables for two-sided mode

See also

`\paper` variables for shifts and indents

See also

4.1.6 Other `\paper` variables

`\paper` variables for line breaking

See also

`\paper` variables for page breaking

See also

`\paper` variables for page numbering

See also

Known issues and warnings

Miscellaneous `\paper` variables

See also

Known issues and warnings

Structure of flexible vertical spacing alists
List of flexible vertical spacing `\paper` variables

`\paper` variables for widths and margins
`\paper` variables for two-sided mode
`\paper` variables for shifts and indents

4.1 Page layout

4.1.1 The \paper block

See also

4.1.2 Paper size and automatic scaling

Setting the paper size

See also

Automatic scaling to paper size

See also

4.1.3 Fixed vertical spacing \paper variables

See also

Known issues and warnings

4.1.4 Flexible vertical spacing \paper variables

Structure of flexible vertical spacing alists

List of flexible vertical spacing \paper variables

See also

4.1.5 Horizontal spacing \paper variables

\paper variables for widths and margins

See also

Known issues and warnings

\paper variables for two-sided mode

See also

\paper variables for shifts and indents

See also

4.1.6 Other \paper variables

\paper variables for line breaking

See also

\paper variables for page breaking

See also

\paper variables for page numbering

See also

Known issues and warnings

Miscellaneous \paper variables

See also

Known issues and warnings

4.1.1 The `\paper` block

4.1.3 Fixed vertical spacing `\paper` variables

4.1.4 Flexible vertical spacing `\paper` variables

List of flexible vertical spacing `\paper` variables

4.1.5 Horizontal spacing `\paper` variables

`\paper` variables for widths and margins

`\paper` variables for two-sided mode

`\paper` variables for shifts and indents

4.1.6 Other `\paper` variables

`\paper` variables for line breaking

`\paper` variables for page breaking

`\paper` variables for page numbering

Miscellaneous `\paper` variables