[ << Notation manual tables ]	[Top][Contents][Index]	[ Cheat sheet >> ]
[ < Context modification identifiers ]	[ Up : Notation manual tables ]	[ Naming conventions > ]

---

A.24 Paper variables

The following paper variables are predefined by LilyPond. Default values that are scaled to paper size are given for the default paper size, A4. The mentioned xxx-default variables are paper variables, too.

Some values like mm or pt are constants and thus essentially read-only; changing them would confuse LilyPond thoroughly.

Most paper variables can be either set in \paper or in \layout, see The \layout block.

annotate-spacing (boolean) ¶

If this value is set to #t, dimensions of vertical layout variables that may be altered for page formatting are graphically displayed. Default: #f.

auto-first-page-number (boolean) ¶

The page-breaking algorithm is affected by the first page number being odd or even. If set to #t, the algorithm decides whether to start with an odd or even number. This results in the first page number remaining as is or being increased by one. Default: #f.

binding-offset (number) ¶

This amount gets added to inner-margin so that nothing is hidden by the binding. Has only an effect if two-sided is set to #t. Default: binding-offset-default (5mm, scaled to paper size).

blank-after-score-page-penalty (number) ¶

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 LilyPond prefers blank pages after scores to blank pages within a score. Default: 2.

blank-last-page-penalty (number) ¶

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

blank-page-penalty (number) ¶

The penalty for having a blank page in the middle of a score. Note that this is not used by ly:optimal-breaking, which never considers blank pages in the middle of a score. Default: 5.

blot-diameter (non-negative number) ¶

This value globally defines the smallest ‘round’ feature LilyPond uses while constructing almost all non-glyph elements like beams or stems. Essentially, it sets up how round the corners and line ends are. It only makes sense to change the value if you use a different music glyph font with crisper corners, say. Default: 0.4pt.

book-title (procedure) ¶

Internal. This is what LilyPond actually uses for handling bookTitleMarkup.

book-title-properties (association list (list of pairs)) ¶

Internal.

bookpart-level-page-numbering (boolean) ¶

If set to #t, restart page numbering for each \bookpart block. Otherwise all pages in the document are enumerated continuously. Default: #f.

bookTitleMarkup (markup) ¶

The titling markup within a \book, using standard fields from the \header block. The default value is defined in file titling-init.ly.

bottom-margin (non-negative number) ¶

The margin between the bottom of the printable area and the bottom of the page. Default: bottom-margin-default (10mm, scaled to paper size).

bp (positive number) ¶

The big point unit, also called desktop publishing point (DTP point). It is 1/72 of an inch, approx. 0.353mm (0.0138in).

check-consistency (boolean) ¶

If set to #t, print a warning if the left margin, line width, and right margin do not exactly add up to paper-width, and replace each of these (except paper-width) with its default value (scaled to the paper size if necessary). If set to #f, ignore any inconsistencies and allow systems to run off the edge of the page. Default: #t.

clip-regions (association list (list of pairs)) ¶

A list of rhythm location pairs to output fragments of a score.

clip-regions
= #(list (cons (make-rhythmic-location 2 0 1)
               (make-rhythmic-location 4 0 1))
         (cons (make-rhythmic-location 5 1 2)
               (make-rhythmic-location 7 3 4)))

The above example defines two regions: the first is from the beginning of bar 2 to the beginning of bar 4, the second starts after a half note duration in bar 5 and ends after the third quarter in bar 7.

Has only an effect if LilyPond’s command-line option -dclip-systems is active. Default: unset.

cm (positive number) ¶

The centimeter unit, approx. 0.39in.

debug-beam-scoring (boolean) ¶

If set to #t, print demerits together with their cause, followed by the number of configurations that have been scored before concluding. Default: #f.

Example:

L 18.95 C 655.12 c19/625 → demerits for stem lengths (‘L’) and collisions (‘C’), scored 19 out of 625 initially considered configurations.

Possible demerit causes: collision (‘C’), inappropriate stem length (‘L’), beam direction different from damping direction (‘Sd’), difference between beam slope and musical slope (‘Sm’), deviation from ideal slope (‘Si’), horizontal inter-quants (‘H’), forbidden quants (‘Fl’/‘Fs’).

Demerits are configurable, see beam-interface for a list of tunable parameters.

debug-slur-scoring (boolean) ¶

If set to #t, print demerits together with their cause, followed by the sum of all demerits and the index of the slur configuration finally chosen. Default: #f.

Example:

slope=2.00, R edge=10.51, variance=0.03 TOTAL=12.54 idx=4 → demerits for slope, distance of the right edge to the attachment point, variance of distance between note heads and slur. Total demerits: 12.54, index of the chosen configuration: 4.

Possible demerit causes: distance of the left/right slur edge to the attachment points (‘L edge’/‘R edge’), inappropriate slope (‘slope’), distance variations between note heads and slur (‘variance’), distances for heads that are between the slur and an imaginary line between the attachment points (‘encompass’), too small distance between slur and tie extrema (‘extra’).

Demerits are configurable, see slur-interface for a list of tunable parameters.

debug-tie-scoring (boolean) ¶

If set to #t, print the basic configuration of ties, followed by demerits and their corresponding causes and the total sum of demerits. Default: unset.

Example:

0 (0.23) u: vdist=1.08 lhdist=1.79 tie/stem dir=8.00 TOTAL=10.87 → offset from the center of the staff according tie specification: 0 staff-spaces, vertical distance of the tie’s center in y-direction to the bottom (or top) of the tie: 0.23, direction: up. Demerits for vertical and horizontal distance to note head, same direction of stem and tie. Total demerits: 10.87.

Possible demerit causes: wrong tie direction (‘wrong dir’), vertical distance to note heads (‘vdist’), horizontal distance to left or right note head (‘lhdist’/‘rhdist’), same direction of stem and tie (‘tie/stem dir’), position and direction of tie not matching, e.g., tie is in the upper half of the staff but has direction DOWN (‘tie/pos dir’), tie is too short (‘minlength’), tip of tie collides with staff line (‘tipline’), collision with dot (‘dot collision’), center of tie is too close to a staff line (‘line center’), y-position (edge or center) of currently considered tie is less than the y-position of the previous tie (‘monoton edge’/ ‘monoton cent’), edge or center of tie is too close to the one considered previously (‘tietie center’/‘tietie edge’), unsymmetrical horizontal positioning with respect to the note heads (‘length symm’), unsymmetrical vertical positioning with respect to the note heads (‘pos symmetry’).

Demerits are configurable, see tie-interface for a list of tunable parameters.

dimension-variables (list) ¶

Internal.

evenFooterMarkup (markup) ¶

The footer markup used for even-numbered pages. If not set, oddFooterMarkup is used instead. The default value is defined in file titling-init.ly.

evenHeaderMarkup (markup) ¶

The header markup used for even-numbered pages. If not set, oddHeaderMarkup is used instead. The default value is defined in file titling-init.ly.

first-page-number (integer) ¶

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

footnote-footer-padding (number) ¶

The padding between the footer and the bottom-most footnote. Default: 0.5mm.

footnote-number-raise (number) ¶

This controls how high the annotation numbers of both footnotes and in-notes are raised relative to the footnote or in-note text. Default: 0.5mm.

footnote-numbering-function (procedure) ¶

This variable holds the name of the function that formats both footnote and in-note numbers (without positioning it). LilyPond provides two predefined functions (in file output-lib.scm): numbered-footnotes (‘1’, ‘2’, etc.) and symbol-footnotes (‘*’, ‘†’, etc.). Default: numbered-footnotes.

The function takes an integer as an argument (starting with value 0) and returns the appropriate markup. You can create your own function, for example,

footnote-numbering-function =
#(lambda (x)
  #{ \markup \concat { "[" #(number->string (1+ x)) "]" } #})

footnote-padding (number) ¶

The padding between two footnotes. Default: 0.5mm.

footnote-separator-markup (markup) ¶

Markup to separate the music from the footnotes, usually a horizontal line. The default value is defined in file paper-defaults-init.ly.

horizontal-shift (number) ¶

If set, the main content block of all pages (but not headers and footers) is shifted horizontally. Positive values shift to the right (on both even and odd pages). Default: 0mm.

in (positive number) ¶

The inch unit, equal to 2.54cm.

in-note-padding (number) ¶

The padding between two in-notes. Default: 0.5mm.

in-note-system-padding (number) ¶

The padding between an in-note and the associated music system. Default: 0.5mm.

incipit-width (positive number) ¶

The width of an incipit as created by the \incipit command. Must be smaller than or equal to indent. Default: (indent / 2).

indent (non-negative number) ¶

The indentation of the first system in a score. The space within the line-width available for the first system is reduced by this amount. Default: indent-default (15mm, scaled to paper size).

inner-margin (non-negative number) ¶

The margin all pages have at the inner side if they are part of a book. Has only an effect if two-sided is set to #t. If unset, inner-margin-default (15mm, scaled to paper size) is used in computations. Default: unset.

is-last-bookpart (boolean) ¶

To be documented.

label-alist-table (list) ¶

Internal. LilyPond uses this to construct a table of contents.

label-page-table (association list (list of pairs)) ¶

Internal. LilyPond uses this to implement the \with-link functionality and to construct a table of contents.

landscape (boolean) ¶

Internal. Use set-default-paper-size or set-paper-size to set the paper orientation.

last-bottom-spacing (association list (list of pairs)) ¶

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). The default value is defined in file paper-defaults-init.ly.

left-margin (non-negative number) ¶

The margin between the left edge of the page and the start of the staff lines in unindented systems. If left-margin is not set, 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. If unset, left-margin-default (15mm, scaled to paper size) is used in computations. Default: unset.

If two-sided is set to #t, this value is ignored. Also see check-consistency.

line-thickness (positive number) ¶

This value globally defines the default line thickness LilyPond uses while constructing many non-glyph elements like lines or boxes. The actual line thickness is usually specified as a factor of this base value, either as a default value, or overridden by the user. The default depends on the staff space and is computed as (0.328571 + 0.0342857 * staff-space) (see function calc-line-thickness in file paper.scm), which is synchronized with the Emmentaler font.

line-width (positive number) ¶

The horizontal extent of the staff lines in unindented, non-ragged systems, equal to (paper-width - left-margin - right-margin) if not set. If line-width is set, and both left-margin and right-margin are not set, then the margins are updated to center the systems on the page automatically. Also see check-consistency. Default: unset.

As a feature of LilyPond, if the command-line option -dcrop is set, the dimensions of the cropped output file are always rounded up to integer (PostScript) big points; this might cause a little bit of whitespace at the right margin. To avoid that, set line-width to an integer big point value like 450\bp.

make-footer (procedure) ¶

Internal. This is what LilyPond actually uses for for handling evenFooterMarkup and oddFooterMarkup.

make-header (procedure) ¶

Internal. This is what LilyPond actually uses for for handling evenHeaderMarkup and oddHeaderMarkup.

markup-markup-spacing (association list (list of pairs)) ¶

The distance between two (title or top-level) markups. The default value is defined in file paper-defaults-init.ly.

markup-system-spacing (association list (list of pairs)) ¶

The distance between a (title or top-level) markup and the system that follows it. The default value is defined in file paper-defaults-init.ly.

max-systems-per-page (non-negative, exact integer) ¶

The maximum number of systems that are placed on a page. This is currently supported only by the ly:optimal-breaking algorithm. Default: unset.

min-systems-per-page (non-negative, exact integer) ¶

The minimum number of systems that are 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.

mm (positive number) ¶

The millimeter unit, approx. 0.039in.

number-footnote-table (list) ¶

Internal. LilyPond uses this to manage footnotes and footnote numbers.

oddFooterMarkup (markup) ¶

The footer markup used for odd-numbered pages. The default value is defined in file titling-init.ly.

oddHeaderMarkup (markup) ¶

The header markup used for odd-numbered pages. The default value is defined in file titling-init.ly.

orphan-penalty (number) ¶

To be documented. See lily/page-breaking.cc. Default is 100000.

outer-margin (non-negative number) ¶

The margin all pages have at the outer side if they are part of a book. Has only an effect if two-sided is set to #t. If unset, outer-margin-default (15mm, scaled to paper size) is used in computations. Default: unset.

output-filename (string) ¶

If set, use this value as the output file name for LilyPond output. See also output-suffix. The default is the input file name (without the file extension).

output-scale (positive number) ¶

Internal. This value globally defines the output scale LilyPond uses while creating output. Use set-global-staff-size or layout-set-staff-size to change the scaling. Default: 1.7573, which corresponds to a 20pt staff size.

output-suffix (string) ¶

If set, use this value as the output file name suffix for LilyPond output, appended to the output name with a dash inbetween. See also output-filename. The default is no output suffix if there is only a single book block (either implicit or explicit), and a running integer starting with value 1 otherwise.

page-breaking (procedure) ¶

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. Default: ly:optimal-breaking.

page-breaking-system-system-spacing (association list (list of pairs)) ¶

This 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 puts fewer systems on each page. Default: unset.

page-count (non-negative, exact integer) ¶

The number of pages to be used for a score. Default: unset.

page-number-type (symbol) ¶

The type of numerals used for page numbers. Choices include arabic, roman-ij-lower, roman-ij-upper, roman-lower, and roman-upper. Default: arabic.

page-post-process (procedure) ¶

If this function is defined (within the \paper block), LilyPond uses it to post-process pages, for example, to extract the table of contents and writing the information to an auxiliary file. The call happens after page breaking has been performed.

The syntax is

#(define (page-post-process layout pages) ... )

page-spacing-weight (number) ¶

When using the ly:optimal-breaking algorithm for page breaking, LilyPond has to make trade-offs between horizontal and vertical stretching so that the overall spacing is more acceptable. This parameter controls the relative importance of (vertical) page spacing and (horizontal) line spacing. High values makes page spacing more important. Default: 10.

paper-height (positive number) ¶

The height of the page. Note that the automatic scaling of some vertical dimensions is not affected if you set this value directly. Default: 297mm (A4 paper height).

paper-width (positive number) ¶

The width of the page. While setting paper-width directly 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 also get updated. Also see check-consistency. Default: 210mm (A4 paper width).

papersizename (string) ¶

Internal. Use set-default-paper-size or set-paper-size to set the paper size.

print-all-headers (boolean) ¶

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

print-first-page-number (boolean) ¶

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

print-page-number (boolean) ¶

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

property-defaults (association list (list of pairs)) ¶

This variable holds some settings that are used for top-level markups and as fallback values if nothing else is specified, for example, the standard fonts or the baseline skip. The default value is defined in file paper-defaults-init.ly.

pt (positive number) ¶

The point unit, equal to approx. 0.351mm (0.0139in).

ragged-bottom (boolean) ¶

If set to #t, systems are set at at their natural spacing, neither compressed nor stretched vertically to fit the page. Default: #f.

ragged-last (boolean) ¶

If set to #t, the last system in the score does not fill the line width. Instead, the last system ends at its natural horizontal length. Default: #f.

ragged-last-bottom (boolean) ¶

If set to #f, then the last page, and the last page in each section created with a \bookpart block, is vertically justified in the same way as the earlier pages. Default: #t.

ragged-right (boolean) ¶

If set to #t, systems don’t 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.

reset-footnotes-on-new-page (boolean) ¶

If set to #t, footnote and in-note numbers are reset on each page break. For footnotes and in-notes numbered consecutively across page breaks, set to #f. Default: #t.

right-margin (non-negative number) ¶

The margin between the right edge of the page and the end of the staff lines in non-ragged systems. If right-margin is not set, 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. If unset, right-margin-default (15mm, scaled to paper size) is used in computations. Default: unset.

If two-sided is set to #t, this value is ignored. Also see check-consistency.

score-markup-spacing (association list (list of pairs)) ¶

The distance between the last system of a score and the (title or top-level) markup that follows it. The default value is defined in file paper-defaults-init.ly.

score-system-spacing (association list (list of pairs)) ¶

The distance between the last system of a score and the first system of the score that follows it, if no (title or top-level) markup exists between them. The default value is defined in file paper-defaults-init.ly.

score-title (procedure) ¶

Internal. This is what LilyPond actually uses for handling scoreTitleMarkup.

score-title-properties (association list (list of pairs)) ¶

Internal.

scoreTitleMarkup (markup) ¶

The titling markup of a score within a \book, using standard fields from the \header block. The default value is defined in file titling-init.ly.

short-indent (non-negative number) ¶

The level of indentation for all systems in a score besides the first system. The space within the line-width available for systems other than the first one is reduced by this amount. Default: short-indent-default (0mm).

staff-height (positive number) ¶

Internal. Use set-global-staff-size or layout-set-staff-size to set the staff height. Default: 20pt.

staff-space (positive number) ¶

Internal. One staff height contains four staff spaces. Use set-global-staff-size or layout-set-staff-size to set this value. Default: 5pt.

system-count (non-negative, exact integer) ¶

The number of systems to be used for a score. Default: unset.

system-separator-markup (markup) ¶

A markup object that is inserted between systems, often used for orchestral scores. The \slashSeparator markup, defined in file titling-init.ly, is provided as a sensible standard value. Default: unset.

system-system-spacing (association list (list of pairs)) ¶

The distance between two systems in the same score. The default value is defined in file paper-defaults-init.ly.

systems-per-page (non-negative, exact integer) ¶

The number of systems that should be placed on a page. This is currently supported only by the ly:optimal-breaking algorithm. Default: unset.

tagline (markup) ¶

This markup gets placed at the bottom of the last page (via oddFooterMarkup). The default value is defined in file titling-init.ly.

text-font-size (positive number) ¶

This value globally defines the standard text size for markups. The default depends on the staff height and is computed as (staff-height / 20 * 11).

tocFormatMarkup (procedure) ¶

How the top-level entries of the table of contents are formatted (if there are several hierarchical levels). This variable holds a function like make-bold-markup. The default value is defined in file toc-init.ly.

tocIndentMarkup (markup) ¶

How the outline’s hierarchy in the table of contents is made apparent. This markup is printed zero, one, or several times depending on the level of each entry. The default value is defined in file toc-init.ly.

tocItemMarkup (markup) ¶

How an item in the table of contents is formatted. The default value of this markup is defined in file toc-init.ly.

tocTitleMarkup (markup) ¶

How the title of the table of contents is formatted. The default value of this markup is defined in file toc-init.ly.

top-margin (non-negative number) ¶

The margin between the top of the page and the top of the printable area. Default: top-margin-default (10mm, scaled to paper size).

top-markup-spacing (association list (list of pairs)) ¶

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. The default value is defined in file paper-defaults-init.ly.

top-system-spacing (association list (list of pairs)) ¶

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. The default value is defined in file paper-defaults-init.ly.

two-sided (boolean) ¶

If set to #t, use inner-margin, outer-margin and binding-offset to determine margins depending on whether the page number is odd or even. left-margin and right-margin are then ignored. Default: #f.