LilyPond Notation Reference: 4.1.2 Page formatting

[ << Spacing issues ]	[Top][Contents][Index][ ? ]			[ Changing defaults >> ]
[ < Paper size ]		[ Up : Paper and pages ]	[ Fixed vertical dimensions > ]

4.1.2 Page formatting

Margins, headers, and footers and other layout variables are automatically set according to the paper size.

Default margin values are accessible in ‘ly/paper-defaults-init.ly’. They apply to the default paper size (a4, unless specified differently) and are scaled accordingly for other paper sizes.

This section lists and describes a number of paper variables that may be altered.

[ << Spacing issues ]	[Top][Contents][Index][ ? ]			[ Changing defaults >> ]
[ < Page formatting ]		[ Up : Page formatting ]	[ Flexible vertical dimensions > ]

Fixed vertical dimensions

paper-height: The height of the page. Default: the height of the current paper size. For details, see Paper size.
top-margin: The margin between the top of the page and the top of the printable area. Default: 5\mm.
bottom-margin: The margin between the bottom of the printable area and the bottom of the page. Default: 6\mm.

[ << Spacing issues ]	[Top][Contents][Index][ ? ]			[ Changing defaults >> ]
[ < Fixed vertical dimensions ]		[ Up : Page formatting ]	[ Horizontal dimensions > ]

Flexible vertical dimensions

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.

Structure of spacing alists for `\paper` variables

Each of these variables is an alist (association list) containing four keys:

padding – the minimum required amount of unobstructed vertical whitespace between two items, measured in staff-spaces. This can be thought of as the minimum height of an unobstructed (invisible) rectangle that extends from the leftmost to the rightmost point of the combined items.
space – the default 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 space 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 minimum required 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.
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 space. Note that the dimension’s propensity to compress cannot be directly set by the user and is equal to (space - minimum-distance).

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

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

Specific methods for modifying alists are discussed in Modifying alists. The flexible vertical \paper dimensions variables can only be set within a \paper block.

The following example demonstrates the two ways these alists can be modified. The first declaration updates one key-value individually, and the second complete re-defines the variable:

\paper {
  system-system-spacing #'space = #8

  score-system-spacing =
    #'((padding . 1)
       (space . 12)
       (minimum-distance . 6)
       (stretchability . 12))
}

The initialized default settings for these variables are defined in ‘ly/paper-defaults-init.ly’.

Flexible vertical dimension `\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).

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.

Selected Snippets

The header and footer are created by the functions make-footer and make-header, defined in \paper. The default implementations are in ‘ly/paper-defaults.ly’ and ‘ly/titling-init.ly’.

The page layout itself is done by two functions in the \paper block, page-music-height and page-make-stencil. The former tells the line-breaking algorithm how much space can be spent on a page, the latter creates the actual page given the system to put on it.

You can define \paper block values in Scheme. In that case mm, in, pt, and cm are variables defined in ‘paper-defaults.ly’ with values in millimeters. That is why the value 2 cm must be multiplied in the example:

\paper {
 #(define bottom-margin (* 2 cm))
}

Example:

\paper {
  paper-width = 2\cm
  top-margin = 3\cm
  bottom-margin = 3\cm
  ragged-last-bottom = ##t
}

This second example centers page numbers at the bottom of every page.

\paper {
  print-page-number = ##t
  print-first-page-number = ##t
  oddHeaderMarkup = \markup \fill-line { " " }
  evenHeaderMarkup = \markup \fill-line { " " }
  oddFooterMarkup = \markup { \fill-line {
     \bold \fontsize #3 \on-the-fly #print-page-number-check-first
     \fromproperty #'page:page-number-string } }
  evenFooterMarkup = \markup { \fill-line {
     \bold \fontsize #3 \on-the-fly #print-page-number-check-first
     \fromproperty #'page:page-number-string } }
}

Horizontal dimensions

There are a few variables that determine the horizontal dimensions on a page:

binding-offset: The amount inner-margin is increased to make sure nothing will be hidden by the binding. Works only with two-sided set to true. Default: 0.
horizontal-shift: The amount that all systems (including titles and system separators) are shifted to the right. Default: 0.0.
indent: The level of indentation for the first system in a score. Default: 15\mm.
inner-margin: The margin all pages have at the inner side if they are part of a book. Works only with two-sided set to true. Default: 10\mm.
left-margin: The margin between the left edge of the page and the beginning of each system. Default: 10\mm.
line-width: The width of music systems. Default: paper-width minus left-margin and right-margin.
outer-margin: The margin all pages have at the outer side if they are part of a book. Works only with two-sided set to true. Default: 20\mm.
paper-width: The width of the page. Default: the width of the current paper size. For details, see Paper size.
right-margin: The margin between the right edge of the page and the end of each system. Default: 10\mm.
short-indent: The level of indentation for all systems in a score besides the first system. Default: 0.

If some values are not set, defaults will be taken. Their exact value is adjusted, depending on the paper size specified. Currently, the following values are affected by this scaling:

left-margin
right-margin
top-margin
bottom-margin
head-separation
foot-separation
indent
short-indent

The settings for line-width, left-margin, right-margin and paper-width depend on each other, but they do not have to be specified completely.

\paper {
  left-margin = 30\mm
}

In this example, only left-margin is set. The value for right-margin will remain default, line-width is calculated automatically.

\paper {
  line-width = 150\mm
}

Here left-margin and right-margin will be set to the same value. Therefore, line-width is subtracted from paper-width and divided by two. That means systems are centered on the page, if only line-width is specified.

Some checks occur to ensure the values are set correctly. If the values do not match or systems would run off the page, a warning is printed and default values are set.

\paper {
  paper-width = 210\mm
  left-margin = 20\mm
  right-margin = 30\mm
  line-width = 100\mm
}

These checks can be avoided by setting check-consistency to false.

\paper {
  paper-width = 210\mm
  left-margin = 20\mm
  line-width = 200\mm
  check-consistency = ##f
}

Note: If paper-width is manually set, line-width, left-margin, indent, and short-indent may have to be adjusted as well.

Other layout variables

These variables can be used to adjust page layout in general.

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.

blank-last-page-force

The penalty for ending the score on an odd-numbered page. Default: 0.

blank-page-force

The penalty for having a blank page in the middle of a score. This is not used by ly:optimal-breaking since it will never consider blank pages in the middle of a score. Default: 5.

check-consistency

If set to true, check whether left-margin, right-margin and line-width fit each other. Also make sure that their combination does not exceed the available paper-width. Default: ##t.

first-page-number

The value of the page number on the first page. Default: #1.

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.

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. Default: unset.

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.

print-first-page-number

If set to true, a page number is printed on the first page. Default: ##f.

print-page-number

If set to false, page numbers are not printed. Default: ##t.

ragged-bottom

If set to true, systems will not spread vertically across the page. This does not affect the last page. Default: ##f.

This should be set to true for pieces that have only two or three systems per page, for example orchestral scores.

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.

ragged-last-bottom

If set to false, systems will spread vertically across the last page. Default: ##t.

Pieces that amply fill two pages or more should have this set to true.

It also affects the last page of book parts, ie parts of a book created with \bookpart blocks.

ragged-right

If set to true, systems will not fill the line width. Instead, systems end at their natural horizontal length. Default: ##f.

If the score has only one system, the default value is ##t.

system-separator-markup

A markup object that is inserted between systems. This is often used for orchestral scores. Default: unset.

The markup command \slashSeparator is provided as a sensible default, for example

system-count

The number of systems to be used for a score. 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.

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. Default: ##f.

Known issues and warnings

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

The titles (from the \header{} section) 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.

[ << Spacing issues ]	[Top][Contents][Index][ ? ]			[ Changing defaults >> ]
[ < Horizontal dimensions ]		[ Up : Page formatting ]	[ Music layout > ]

他の言語: deutsch, español, français

4.1.2 Page formatting

Fixed vertical dimensions

Flexible vertical dimensions

Structure of spacing alists for `\paper` variables

Flexible vertical dimension `\paper` variables

Selected Snippets

See also

Horizontal dimensions

See also

Other layout variables

See also

Known issues and warnings

LilyPond — Notation Reference

4.1.2 Page formatting

Fixed vertical dimensions

Flexible vertical dimensions

Structure of spacing alists for \paper variables

Flexible vertical dimension \paper variables

Selected Snippets

See also

Horizontal dimensions

See also

Other layout variables

See also

Known issues and warnings

LilyPond — Notation Reference

Structure of spacing alists for `\paper` variables

Flexible vertical dimension `\paper` variables