11.1.2 Page formatting

LilyPond will do page layout, set margins, and add headers and footers to each page.

The default layout responds to the following settings in the \paper block.

first-page-number

The value of the page number of the first page. Default is 1.

print-first-page-number

If set to true, will print the page number in the first page. Default is false.

print-page-number

If set to false, page numbers will not be printed. Default is true.

paper-width

The width of the page. The default is taken from the current paper size, see Paper size.

paper-height

The height of the page. The default is taken from the current paper size, see Paper size.

top-margin

Margin between header and top of the page. Default is 5mm.

bottom-margin

Margin between footer and bottom of the page. Default is 6mm.

left-margin

Margin between the left side of the page and the beginning of the music. Unset by default, which means that the margins is determined based on the paper-width and line-width to center the score on the paper.

line-width

The length of the systems. Default is paper-width minus  20mm.

head-separation

Distance between the top-most music system and the page header. Default is 4mm.

foot-separation

Distance between the bottom-most music system and the page footer. Default is 4mm.

page-top-space

Distance from the top of the printable area to the center of the first staff. This only works for staves which are vertically small. Big staves are set with the top of their bounding box aligned to the top of the printable area. Default is 12mm.

ragged-bottom

If set to true, systems will not be spread vertically across the page. This does not affect the last page. Default is false.

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

ragged-last-bottom

If set to false, systems will be spread vertically to fill the last page. Default is true.

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

system-count

This variable, if set, specifies into how many lines a score should be broken. Unset by default.

between-system-space

This dimensions determines the distance between systems. It is the ideal distance between the center of the bottom staff of one system and the center of the top staff of the next system. Default is 20mm.

Increasing this will provide a more even appearance of the page at the cost of using more vertical space.

between-system-padding

This dimension is the minimum amount of white space that will always be present between the bottom-most symbol of one system, and the top-most of the next system. Default is 4mm.

Increasing this will put systems whose bounding boxes almost touch farther apart.

horizontal-shift

All systems (including titles and system separators) are shifted by this amount to the right. Page markup, such as headers and footers are not affected by this. The purpose of this variable is to make space for instrument names at the left. Default is 0.

after-title-space

Amount of space between the title and the first system. Default is 5mm.

before-title-space

Amount of space between the last system of the previous piece and the title of the next. Default is 10mm.

between-title-space

Amount of space between consecutive titles (e.g., the title of the book and the title of a piece). Default is 2mm.

printallheaders

Setting this to #t will print all headers for each \score in the output. Normally only the piece and opus \headers are printed.

systemSeparatorMarkup

This contains a markup object, which will be inserted between systems. This is often used for orchestral scores. Unset by default.

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

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 value is 10.

blank-last-page-force

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

page-spacing-weight

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

auto-first-page-number

The page breaking algorithm is affected by the first page number being odd or even. If this variable is set to #t, 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.

Example:

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

You can also define these 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 must be multiplied in the example

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

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.

Bugs

The option right-margin is defined but doesn't set the right margin yet. The value for the right margin has to be defined adjusting the values of left-margin and line-width.

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.