<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- header_tag -->
<html lang="en">
<head>
<title>Page formatting - GNU LilyPond Notation Reference</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="description" content="GNU LilyPond Notation Reference">
<meta name="generator" content="makeinfo 4.11">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Paper-and-pages.html#Paper-and-pages" title="Paper and pages">
<link rel="prev" href="Paper-size.html#Paper-size" title="Paper size">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1999--2007 by the authors
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections. A copy of the license is
included in the section entitled ``GNU Free Documentation
License''.
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
hr { border:0; height:1; color: #000000; background-color: #000000; }
/* hr {
border: none;
height: 1px;
color: #666666;
background-color: #666666;
}
body {
border-left: 1px solid #666666;
border-right: 1px solid #666666;
color: #332d28;
margin-right: auto;
margin-left: auto;
width: 60em;
list-style-type: square;
font-family: Arial,Helvetica,sans-serif;
padding-right: 1em;
padding-left: 1em;
}
a {
border-bottom: 1px dashed #344242;
text-decoration: none;
color: #344242;
}
a:link {
text-decoration: none;
}
a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
a:active {
border-bottom: 1px solid #00cccc;
color: #00cccc;
}
a:hover {
border-bottom: 1px solid #1d7b85;
color: #1d7b85;
}
blockquote {
border: 1px solid #cccccc;
padding: 3px;
width: 40em;
}
.node {
border-left: 1px solid #666666;
margin: -0.5em 0px 1em;
padding: 2px 1px 0px;
font-style: italic;
}
.node a {
border: none;
text-decoration: underline;
font-style: normal;
font-weight: bold;
}
.verbatim {
font-family: "Courier New",Courier,monospace;
}
.unnumberedsubsubsec {
font-size: large;
color: #1d7b85;
}
.subsubheading {
font-size: large;
color: #3b220d;
}
.contents {
border: 1px dashed #339999;
margin: 3px 2em;
list-style-type: square;
padding-right: 1em;
width: 40em;
background-color: #fcfff9;
}
.contents a {
border-bottom: 1px dashed #423d34;
text-decoration: none;
color: #423d34;
}
.contents a:visited {
border-bottom: 1px dashed #666666;
color: #666666;
}
.contents a:active {
border-bottom: 1px solid #f0d86d;
color: #f0d86d;
}
.contents a:hover {
border-bottom: 1px solid #3b220d;
color: #3b220d;
}
.menu {
border-left: 1px dashed #339999;
margin: 3px 2em 1em;
list-style-type: square;
padding-left: 1.4em;
width: 40em;
}
.unnumbered {
}
h2 {
font-size: x-large;
color: #1d7b85;
}
*/
--></style>
</head>
<BODY BGCOLOR=WHITE TEXT=BLACK>
<div class="node">
<p>
<a name="Page-formatting"></a>
Previous: <a rel="previous" accesskey="p" href="Paper-size.html#Paper-size">Paper size</a>,
Up: <a rel="up" accesskey="u" href="Paper-and-pages.html#Paper-and-pages">Paper and pages</a>
<hr>
</div>
<h4 class="subsection">4.1.2 Page formatting</h4>
<p><a name="index-page-formatting-2468"></a><a name="index-margins-2469"></a><a name="index-header_002c-page-2470"></a><a name="index-footer_002c-page-2471"></a>
LilyPond will do page layout, set margins, and add headers and
footers to each page.
<p>The default layout responds to the following settings in the
<code>\paper</code> block.
<p><a name="index-g_t_005cpaper-2472"></a><a name="index-g_t_005cpaper-2473"></a>
<blockquote>
<a name="index-first_002dpage_002dnumber-2474"></a>
<a name="index-first_002dpage_002dnumber-2475"></a>
<dl>
<dt><code>first-page-number</code><dd>The value of the page number of the first page. Default is 1.
<p><a name="index-print_002dfirst_002dpage_002dnumber-2476"></a><a name="index-print_002dfirst_002dpage_002dnumber-2477"></a>
<br><dt><code>print-first-page-number</code><dd>If set to true, will print the page number in the first page. Default is
false.
<p><a name="index-print_002dpage_002dnumber-2478"></a><a name="index-print_002dpage_002dnumber-2479"></a>
<br><dt><code>print-page-number</code><dd>If set to false, page numbers will not be printed. Default is true.
<p><a name="index-paper_002dwidth-2480"></a><a name="index-paper_002dwidth-2481"></a>
<br><dt><code>paper-width</code><dd>The width of the page. The default is taken from the current paper size,
see <a href="Paper-size.html#Paper-size">Paper size</a>.
<p><a name="index-paper_002dheight-2482"></a><a name="index-paper_002dheight-2483"></a>
<br><dt><code>paper-height</code><dd>The height of the page. The default is taken from the current paper size,
see <a href="Paper-size.html#Paper-size">Paper size</a>.
<p><a name="index-top_002dmargin-2484"></a><a name="index-top_002dmargin-2485"></a>
<br><dt><code>top-margin</code><dd>Margin between header and top of the page. Default is 5mm.
<p><a name="index-bottom_002dmargin-2486"></a><a name="index-bottom_002dmargin-2487"></a>
<br><dt><code>bottom-margin</code><dd>Margin between footer and bottom of the page. Default is 6mm.
<p><a name="index-left_002dmargin-2488"></a><a name="index-left_002dmargin-2489"></a>
<br><dt><code>left-margin</code><dd>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 <code>paper-width</code> and <code>line-width</code> to center the
score on the paper.
<p><a name="index-line_002dwidth-2490"></a><a name="index-line_002dwidth-2491"></a>
<br><dt><code>line-width</code><dd>The length of the systems. Default is <code>paper-width</code> minus 20mm.
<p><a name="index-head_002dseparation-2492"></a><a name="index-head_002dseparation-2493"></a>
<br><dt><code>head-separation</code><dd>Distance between the top-most music system and the page header. Default
is 4mm.
<p><a name="index-foot_002dseparation-2494"></a><a name="index-foot_002dseparation-2495"></a>
<br><dt><code>foot-separation</code><dd>Distance between the bottom-most music system and the page
footer. Default is 4mm.
<p><a name="index-page_002dtop_002dspace-2496"></a><a name="index-page_002dtop_002dspace-2497"></a>
<br><dt><code>page-top-space</code><dd>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.
<p><a name="index-ragged_002dbottom-2498"></a><a name="index-ragged_002dbottom-2499"></a>
<br><dt><code>ragged-bottom</code><dd>If set to true, systems will not be spread vertically across the page. This
does not affect the last page. Default is false.
<p>This should be set to true for pieces that have only two or three
systems per page, for example orchestral scores.
<p><a name="index-ragged_002dlast_002dbottom-2500"></a><a name="index-ragged_002dlast_002dbottom-2501"></a>
<br><dt><code>ragged-last-bottom</code><dd>If set to false, systems will be spread vertically to fill the last
page. Default is true.
<p>Pieces that amply fill two pages or more should have this set to
true.
<p><a name="index-system_002dcount-2502"></a><a name="index-system_002dcount-2503"></a>
<br><dt><code>system-count</code><dd>This variable, if set, specifies into how many lines a score should be
broken. Unset by default.
<p><a name="index-between_002dsystem_002dspace-2504"></a><a name="index-between_002dsystem_002dspace-2505"></a>
<br><dt><code>between-system-space</code><dd>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.
<p>Increasing this will provide a more even appearance of the page at the
cost of using more vertical space.
<p><a name="index-between_002dsystem_002dpadding-2506"></a><a name="index-between_002dsystem_002dpadding-2507"></a>
<br><dt><code>between-system-padding</code><dd>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.
<p>Increasing this will put systems whose bounding boxes almost touch
farther apart.
<p><a name="index-page_002dbreaking_002dbetween_002dsystem_002dpadding-2508"></a><a name="index-page_002dbreaking_002dbetween_002dsystem_002dpadding-2509"></a>
<br><dt><code>page-breaking-between-system-padding</code><dd>This variable tricks the page breaker into thinking that
<code>between-system-padding</code> is set to something different than it
really is. For example, if this variable is set to something substantially
larger than <code>between-system-padding</code>, then the page-breaker will put
fewer systems on each page.
<p><a name="index-horizontal_002dshift-2510"></a><a name="index-horizontal_002dshift-2511"></a>
<br><dt><code>horizontal-shift</code><dd>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.
<p><a name="index-after_002dtitle_002dspace-2512"></a><a name="index-after_002dtitle_002dspace-2513"></a>
<br><dt><code>after-title-space</code><dd>Amount of space between the title and the first system. Default is 5mm.
<p><a name="index-before_002dtitle_002dspace-2514"></a><a name="index-before_002dtitle_002dspace-2515"></a>
<br><dt><code>before-title-space</code><dd>Amount of space between the last system of the previous piece and the
title of the next. Default is 10mm.
<p><a name="index-between_002dtitle_002dspace-2516"></a><a name="index-between_002dtitle_002dspace-2517"></a>
<br><dt><code>between-title-space</code><dd>Amount of space between consecutive titles (e.g., the title of the
book and the title of a piece). Default is 2mm.
<p><a name="index-printallheaders-2518"></a><a name="index-printallheaders-2519"></a>
<br><dt><code>printallheaders</code><dd>Setting this to #t will print all headers for each \score in the
output. Normally only the piece and opus \headers are printed.
<p><a name="index-systemSeparatorMarkup-2520"></a><a name="index-systemSeparatorMarkup-2521"></a>
<br><dt><code>systemSeparatorMarkup</code><dd>This contains a markup object, which will be inserted between
systems. This is often used for orchestral scores. Unset by default.
<p>The markup command <code>\slashSeparator</code> is provided as a sensible
default, for example
<p class="noindent"><p>
<a href="../20/lily-82c417f7.ly">
<img align="middle"
border="0" src="../20/lily-82c417f7.png" alt="[image of music]">
</a>
</p>
<p><a name="index-blank_002dpage_002dforce-2522"></a><a name="index-blank_002dpage_002dforce-2523"></a>
<br><dt><code>blank-page-force</code><dd>The penalty for having a blank page in the middle of a
score. This is not used by <code>ly:optimal-breaking</code> since it will
never consider blank pages in the middle of a score. Default value
is 10.
<p><a name="index-blank_002dlast_002dpage_002dforce-2524"></a><a name="index-blank_002dlast_002dpage_002dforce-2525"></a>
<br><dt><code>blank-last-page-force</code><dd>The penalty for ending the score on an odd-numbered page.
Default value is 0.
<p><a name="index-page_002dspacing_002dweight-2526"></a><a name="index-page_002dspacing_002dweight-2527"></a>
<br><dt><code>page-spacing-weight</code><dd>The relative importance of page (vertical) spacing and line (horizontal)
spacing. High values will make page spacing more important. Default
value is 10.
<p><a name="index-auto_002dfirst_002dpage_002dnumber-2528"></a><a name="index-auto_002dfirst_002dpage_002dnumber-2529"></a>
<br><dt><code>auto-first-page-number</code><dd>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.
</dl>
</blockquote>
<p class="noindent">
<h5 class="subsubheading">Selected Snippets</h5>
<p>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.
<p>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.
<p>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
<pre class="example">\paper {
#(define bottom-margin (* 2 cm))
}
</pre>
<p>Example:
<pre class="example">\paper{
paper-width = 2\cm
top-margin = 3\cm
bottom-margin = 3\cm
ragged-last-bottom = ##t
}
</pre>
<p>This second example centers page numbers at the bottom of every page.
<pre class="example">\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 } }
}
</pre>
<p>You can also define these values in Scheme. In that case <code>mm</code>,
<code>in</code>, <code>pt</code>, and <code>cm</code> are variables defined in
<samp><span class="file">paper-defaults.ly</span></samp> with values in millimeters. That is why the
value must be multiplied in the example
<pre class="example">\paper {
#(define bottom-margin (* 2 cm))
}
</pre>
<p>The header and footer are created by the functions <code>make-footer</code>
and <code>make-header</code>, defined in <code>\paper</code>. The default
implementations are in <samp><span class="file">ly/paper-defaults.ly</span></samp> and
<samp><span class="file">ly/titling-init.ly</span></samp>.
<p>The page layout itself is done by two functions in the
<code>\paper</code> block, <code>page-music-height</code> and
<code>page-make-stencil</code>. 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.
<p class="noindent">
<h5 class="subsubheading">Known issues and warnings</h5>
<p>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 <code>left-margin</code> and <code>line-width</code>.
<p>The default page header puts the page number and the <code>instrument</code>
field from the <code>\header</code> block on a line.
<p>The titles (from the <code>\header{}</code> section) are treated as a
system, so <code>ragged-bottom</code> and <code>ragged-last-bottom</code> will
add space between the titles and the first system of the score.
<!-- footer_tag --><br><hr>
<div class="node">
<p>
Previous: <a rel="previous" accesskey="p" href="Paper-size.html#Paper-size">Paper size</a>,
Up: <a rel="up" accesskey="u" href="Paper-and-pages.html#Paper-and-pages">Paper and pages</a>
</div>
<div style="background-color: #e8ffe8; padding: 2; border: #c0ffc0 1px solid;">
<p>
<font size="-1">
This page is for LilyPond-2.11.57 (development-branch).
<br>
<address>
Report errors to <a href="http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs">http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs</a>. </address>
<br>
Your <a href="http://lilypond.org/web/devel/participating/documentation-adding">suggestions for the documentation</a> are welcome.
</font>
</p>
</div>
</BODY></html>
