Doc: Added @funindex for within-system-spacing

[lilypond.git] / Documentation / notation / spacing.itely

@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.13.42"

@ignore
GDP TODO list

Negative numbers are allowed:
> Are you sure? The following works well
> \paper{
>   first-page-number = -2
> }
> and prints page number -1 on the second page, for example.


In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
states:

"@code{layout-set-staff-size} does not change the distance between
the
staff lines."

Could we add a sentence:
"Use instead the pair               fontSize = #@var{N}
            \override StaffSymbol #'staff-space = #(magstep
@var{N})
inside the Staff context to change the size of the font and the
distance between
staff lines accordingly."

Actually I found, that the @internalsref{StaffSymbol} at line 481
sends to an incomplete
documentation.  The property staff-space is not explained here.  I
thought Y-extent might be of
help, but it is in turn explained by x-space which again is
missing from the list.  Who has the
knowledge to fix this?


Clarify
http://code.google.com/p/lilypond/issues/detail?id=68

@end ignore


@node Spacing issues
@chapter Spacing issues

The global paper layout is determined by three factors: the page layout, the
line breaks, and the spacing.  These all influence each other.  The
choice of spacing determines how densely each system of music is set.
This influences where line breaks are chosen, and thus ultimately, how
many pages a piece of music takes.

Globally speaking, this procedure happens in four steps: first,
flexible distances (@q{springs}) are chosen, based on durations.  All
possible line breaking combinations are tried, and a @q{badness} score
is calculated for each.  Then the height of each possible system is
estimated.  Finally, a page breaking and line breaking combination is chosen
so that neither the horizontal nor the vertical spacing is too cramped
or stretched.

Two types of blocks can contain layout settings:
@code{\paper @{@dots{}@}} and @code{\layout @{@dots{}@}}.  The
@code{\paper} block contains page layout settings that are
expected to be the same for all scores in a book, such as the
paper height, or whether to print page numbers, etc.  See
@ref{Page layout}.  The @code{\layout} block contains score layout
settings, such as the number of systems to use, or the space
between staff-groups, etc.  See @ref{Score layout}.

@menu
* Page layout::
* Score layout::
* Breaks::
* Vertical spacing::
* Horizontal spacing::
* Fitting music onto fewer pages::
@end menu


@node Page layout
@section Page layout

This section discusses page layout options for the @code{\paper}
block.

@menu
* The \paper block::
* Paper size and automatic scaling::
* Fixed vertical spacing \paper variables::
* Flexible vertical spacing \paper variables::
* Horizontal spacing \paper variables::
* Other \paper variables::
@end menu


@node The \paper block
@subsection The @code{\paper} block

The @code{\paper} block can appear within a @code{\book} block,
but not within a @code{\score} block.  Settings in a @code{\paper}
block apply to the entire book, which may include multiple scores.
Settings that can appear in a @code{\paper} block include:

@itemize

@item
the @code{set-paper-size} scheme function,

@item
@code{\paper} variables used for customizing page layout, and

@item
markup definitions used for customizing the layout of headers,
footers, and titles.

@end itemize

The @code{set-paper-size} function is discussed in the next
section, @ref{Paper size and automatic scaling}.  The
@code{\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
@ref{Custom headers footers and titles}.

Most @code{\paper} variables will only work in a @code{\paper}
block.  The few that will also work in a @code{\layout} block are
listed in @ref{The \layout block}.

Except when specified otherwise, all @code{\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 @code{top-margin} to ten
millimeters:

@example
\paper @{
  top-margin = 10
@}
@end example

To set it to @code{0.5} inches, use the @code{\in} unit suffix:

@example
\paper @{
  top-margin = 0.5\in
@}
@end example

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

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

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

@seealso
Notation Reference:
@ref{Paper size and automatic scaling},
@ref{Custom headers footers and titles},
@ref{The \layout block}.

Installed Files:
@file{ly/paper-defaults-init.ly}.


@node Paper size and automatic scaling
@subsection Paper size and automatic scaling

@cindex paper size
@cindex page size

@funindex \paper

@menu
* Setting paper size::
* Automatic scaling to paper size::
@end menu


@node Setting paper size
@unnumberedsubsubsec Setting paper size

Two functions are available for changing the paper size:
@code{set-default-paper-size} and @code{set-paper-size}.
@code{set-default-paper-size} must be placed in the toplevel
scope, and @code{set-paper-size} must be placed in a @code{\paper}
block:

@example
#(set-default-paper-size "a4")
@end example

@example
\paper @{
  #(set-paper-size "a4")
@}
@end example

@noindent
In the toplevel scope, the @code{set-default-paper-size} function
can safely be called anywhere before the first @code{\paper}
block.  Within a @code{\paper} block, the safest place to call
@code{set-paper-size} is at the top, above the list of variable
declarations.  The reasons for this are discussed in
@ref{Automatic scaling to paper size}.

@code{set-default-paper-size} sets the size of all pages, whereas
@code{set-paper-size} only sets the size of the pages that the
@code{\paper} block applies to.  For example, if the @code{\paper}
block is at the top of the file, then it will apply the paper size
to all pages.  If the @code{\paper} block is inside a
@code{\book}, then the paper size will only apply to that book.

Common paper sizes are available, including @code{a4},
@code{letter}, @code{legal}, and @code{11x17} (also known as
tabloid).  Many more paper sizes are supported by default.  For
details, see @file{scm/paper.scm}, and search for the
definition of @code{paper-alist}.

@c TODO add a new appendix for paper sizes (auto-generated) -pm

@warning{The default paper size is @code{a4}.}

Extra sizes may be added by editing the definition of
@code{paper-alist} in the initialization file
@file{scm/paper.scm}, however they will be overridden on a
subsequent install.

@cindex orientation
@cindex landscape

If the symbol @code{'landscape} is supplied as an argument to
@code{set-default-paper-size}, pages will be rotated by 90
degrees, and wider line widths will be set accordingly.

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

@seealso
Notation Reference:
@ref{Automatic scaling to paper size}.

Installed Files:
@file{scm/paper.scm}.


@node Automatic scaling to paper size
@unnumberedsubsubsec Automatic scaling to paper size

If the paper size is changed with one of the scheme functions
(@code{set-default-paper-size} or @code{set-paper-size}), the
values of several @code{\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
@code{paper-height} or @code{paper-width} variables, even though
@code{paper-width} can influence other values (this is separate
from scaling and is discussed below).  The
@code{set-default-paper-size} and @code{set-paper-size} functions
are described in @ref{Setting paper size}.

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

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

@seealso
Notation Reference:
@ref{Fixed vertical spacing \paper variables},
@ref{Horizontal spacing \paper variables}.

Installed Files:
@file{ly/paper-defaults-init.ly},
@file{scm/paper.scm}.


@node Fixed vertical spacing \paper variables
@subsection Fixed vertical spacing @code{\paper} variables

@warning{Some @code{@bs{}paper} dimensions are automatically
scaled to the paper size, which may lead to unexpected behavior.
See @ref{Automatic scaling to paper size}.}

Default values (before scaling) are defined in
@file{ly/paper-defaults-init.ly}.

@table @code
@item paper-height
@funindex paper-height

The height of the page, unset by default.  Note that the automatic
scaling of some vertical dimensions is not affected by this.

@item top-margin
@funindex 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.

@item bottom-margin
@funindex 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.

@item ragged-bottom
@funindex ragged-bottom

If set to true, systems will not spread vertically down the page.
This does not affect the last page.  This should be set to true
for pieces that have only two or three systems per page, for
example orchestral scores.

@item ragged-last-bottom
@funindex ragged-last-bottom

If set to false, systems will spread vertically down the last
page.  Pieces that amply fill two pages or more should have this
set to true.  It also affects the last page of book parts, i.e.
parts of a book created with @code{\bookpart} blocks.

@end table

@seealso
Notation Reference:
@ref{Automatic scaling to paper size}.

Installed Files:
@file{ly/paper-defaults-init.ly}.

Snippets:
@rlsr{Spacing}.

@knownissues

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


@node Flexible vertical spacing \paper variables
@subsection Flexible vertical spacing @code{\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 @code{\paper} variables
(listed below) are available to fine-tune the stretching behavior
of these dimensions.

Note that the @code{\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 @code{\score} or
@code{\layout} block, and not inside a @code{\paper} block.  See
@ref{Flexible vertical spacing within systems}.

@menu
* Structure of flexible vertical spacing alists::
* List of flexible vertical spacing \paper variables::
@end menu


@node Structure of flexible vertical spacing alists
@unnumberedsubsubsec Structure of flexible vertical spacing alists

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

@itemize

@item
@code{basic-distance} -- the vertical distance, measured in
staff-spaces, between the @emph{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 @code{StaffSymbol}
-- even if a non-staff line (such as a @code{Lyrics} context) is
in the way.  Values for @code{basic-distance} that are less than
either @code{padding} or @code{minimum-distance} are not
meaningful, since the resulting distance will never be less than
either @code{padding} or @code{minimum-distance}.

@item
@code{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
@code{minimum-distance} that are less than @code{padding} are not
meaningful, since the resulting distance will never be less than
@code{padding.}

@c TODO: explain skylines somewhere and xref to it from here.

@item
@code{padding} -- the minimum required amount of unobstructed
vertical whitespace between the bounding boxes (or skylines) of
the two items, measured in staff-spaces.

@item
@code{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 @code{stretchability}
value lies only in its relation to the @code{stretchability}
values of the other dimensions.  For example, if one dimension has
twice the @code{stretchability} of another, it will stretch twice
as easily.  Values should be non-negative and finite.  The value
@code{+inf.0} triggers a @code{programming_error} and is ignored,
but @code{1.0e7} can be used for an almost infinitely stretchable
spring.  If unset, the default value is set to
@code{basic-distance}.  Note that the dimension's propensity to
@emph{compress} cannot be directly set by the user and is equal to
(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).

@end itemize

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

@itemize

@item
@code{basic-distance},

@item
@code{minimum-distance}, and

@item
@code{padding} plus the smallest distance necessary to eliminate
collisions.

@end itemize

Specific methods for modifying alists are discussed in
@ref{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:

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


@node List of flexible vertical spacing \paper variables
@unnumberedsubsubsec List of flexible vertical spacing @code{\paper} variables

The names of these variables follow the format
@code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
and @code{@var{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 @q{@code{markup}} refers to both
@emph{title markups} (@code{bookTitleMarkup} or
@code{scoreTitleMarkup}) and @emph{top-level markups} (see
@ref{File structure}).  All distances are measured in
staff-spaces.

Default settings are defined in @file{ly/paper-defaults-init.ly}.

@c TODO: Where do headers/footers fit in? -mp

@table @code
@item markup-system-spacing
@funindex markup-system-spacing

the distance between a (title or top-level) markup and the system
that follows it.

@item score-markup-spacing
@funindex score-markup-spacing

the distance between the last system of a score and the (title or
top-level) markup that follows it.

@item score-system-spacing
@funindex 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.

@item system-system-spacing
@funindex system-system-spacing

the distance between two systems in the same score.

@item markup-markup-spacing
@funindex markup-markup-spacing

the distance between two (title or top-level) markups.

@item last-bottom-spacing
@funindex 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).

@item top-system-spacing
@funindex 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.

@item top-markup-spacing
@funindex 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.
@end table

@seealso
Notation Reference:
@ref{Flexible vertical spacing within systems}.

Installed Files:
@file{ly/paper-defaults-init.ly}.

Snippets:
@rlsr{Spacing}.


@node Horizontal spacing \paper variables
@subsection Horizontal spacing @code{\paper} variables

@warning{Some @code{@bs{}paper} dimensions are automatically
scaled to the paper size, which may lead to unexpected behavior.
See @ref{Automatic scaling to paper size}.}

@menu
* \paper variables for widths and margins::
* \paper variables for two-sided mode::
* \paper variables for shifts and indents::
@end menu


@node \paper variables for widths and margins
@unnumberedsubsubsec @code{\paper} variables for widths and margins

Default values (before scaling) that are not listed here are
defined in @file{ly/paper-defaults-init.ly}.

@table @code

@item paper-width
@funindex paper-width

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

@item line-width
@funindex line-width

The horizontal extent of the staff lines in unindented, non-ragged
systems, equal to
@code{(paper-width@tie{}@minus{}@tie{}left-margin@tie{}@minus{}@tie{}right-margin)}
when unset.  If @code{line-width} is set, and both
@code{left-margin} and @code{right-margin} are unset, then the
margins will be updated to center the systems on the page
automatically.  Also see @code{check-consistency}.  This variable
can also be set in a @code{\layout} block.

@item left-margin
@funindex 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
@code{left-margin} is unset, and both @code{line-width} and
@code{right-margin} are set, then @code{left-margin} is set to
@code{(paper-width@tie{}@minus{}@tie{}line-width@tie{}@minus{}@tie{}right-margin)}.
If only @code{line-width} is set, then both margins are set to
@code{((paper-width@tie{}@minus{}@tie{}line-width)@tie{}/@tie{}2)},
and the systems are consequently centered on the page.  Also see
@code{check-consistency}.

@item right-margin
@funindex 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
@code{right-margin} is unset, and both @code{line-width} and
@code{left-margin} are set, then @code{right-margin} is set to
@code{(paper-width@tie{}@minus{}@tie{}line-width@tie{}@minus{}@tie{}left-margin)}.
If only @code{line-width} is set, then both margins are set to
@code{((paper-width@tie{}@minus{}@tie{}line-width)@tie{}/@tie{}2)},
and the systems are consequently centered on the page.  Also see
@code{check-consistency}.

@item check-consistency
@funindex check-consistency

If set to true, print a warning if @code{left-margin},
@code{line-width}, and @code{right-margin} do not exactly add up
to @code{paper-width}, and replace each of these (except
@code{paper-width}) with its default value (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.

@item ragged-right
@funindex ragged-right

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

@item ragged-last
@funindex 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: @code{#f}.  This variable can also be
set in a @code{\layout} block.

@end table

@seealso
Notation Reference:
@ref{Automatic scaling to paper size}.

Installed Files:
@file{ly/paper-defaults-init.ly}.


@node \paper variables for two-sided mode
@unnumberedsubsubsec @code{\paper} variables for two-sided mode

Default values (before scaling) are defined in
@file{ly/paper-defaults-init.ly}.

@table @code

@item two-sided
@funindex two-sided

@cindex gutter
@cindex binding gutter

If set to true, use @code{inner-margin}, @code{outer-margin} and
@code{binding-offset} to determine margins depending on whether
the page number is odd or even.  This overrides @code{left-margin}
and @code{right-margin}.

@item inner-margin
@funindex 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 @code{two-sided} set
to true.

@item outer-margin
@funindex 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 @code{two-sided} set
to true.

@item binding-offset
@funindex binding-offset

The amount @code{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 @code{two-sided} set to true.

@end table

@seealso
Notation Reference:
@ref{Automatic scaling to paper size}.

Installed Files:
@file{ly/paper-defaults-init.ly}.


@node \paper variables for shifts and indents
@unnumberedsubsubsec @code{\paper} variables for shifts and indents

Default values (before scaling) that are not listed here are
defined in @file{ly/paper-defaults-init.ly}.

@table @code

@item horizontal-shift
@funindex horizontal-shift

@c This default value is buried in the middle of page.scm.  -mp

The amount that all systems (including titles and system
separators) are shifted to the right.  Default: @code{0.0\mm}.

@item indent
@funindex 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.  This variable can also be set in a @code{\layout}
block.

@item short-indent
@funindex 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.  This variable can also be
set in a @code{\layout} block.

@end table

@seealso
Notation Reference:
@ref{Automatic scaling to paper size}.

Installed Files:
@file{ly/paper-defaults-init.ly}.

Snippets:
@rlsr{Spacing}.


@node Other \paper variables
@subsection Other @code{\paper} variables

@menu
* \paper variables for line breaking::
* \paper variables for page breaking::
* \paper variables for page numbering::
* Miscellaneous \paper variables::
@end menu


@node \paper variables for line breaking
@unnumberedsubsubsec @code{\paper} variables for line breaking

@c TODO: Mention that ly:optimal-breaking is on by default? -mp

@table @code

@item max-systems-per-page
@funindex max-systems-per-page

The maximum number of systems that will be placed on a page.  This
is currently supported only by the @code{ly:optimal-breaking} algorithm.
Default: unset.

@item min-systems-per-page
@funindex 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 @code{ly:optimal-breaking} algorithm.
Default: unset.

@item systems-per-page
@funindex systems-per-page

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

@item system-count
@funindex system-count

The number of systems to be used for a score.  Default: unset.
This variable can also be set in a @code{\layout} block.

@end table

@seealso
Notation Reference:
@ref{Line breaking}.


@node \paper variables for page breaking
@unnumberedsubsubsec @code{\paper} variables for page breaking

Default values not listed here are defined in
@file{ly/paper-defaults-init.ly}

@table @code

@item blank-after-score-page-force
@funindex blank-after-score-page-force

The penalty for having a blank page after the end of one score and
before the next.  By default, this is smaller than
@code{blank-page-force}, so that we prefer blank pages after
scores to blank pages within a score.

@item blank-last-page-force
@funindex blank-last-page-force

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

@item blank-page-force
@funindex blank-page-force

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

@item page-breaking
@funindex page-breaking

The page-breaking algorithm to use.  Choices are
@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
@code{ly:optimal-breaking}.

@item page-breaking-system-system-spacing
@funindex page-breaking-system-system-spacing

Tricks the page breaker into thinking that
@code{system-system-spacing} is set to something different than
it really is.  For example, if
@code{page-breaking-system-system-spacing #'padding} is set to something
substantially larger than @code{system-system-spacing #'padding}, then the
page-breaker will put fewer systems on each page.  Default: unset.

@item page-count
@funindex page-count

The number of pages to be used for a score, unset by default.

@end table

@seealso
Notation Reference:
@ref{Page breaking},
@ref{Optimal page breaking},
@ref{Optimal page turning},
@ref{Minimal page breaking}.

Installed Files:
@file{ly/paper-defaults-init.ly}.


@node \paper variables for page numbering
@unnumberedsubsubsec @code{\paper} variables for page numbering

Default values not listed here are defined in
@file{ly/paper-defaults-init.ly}

@table @code

@item auto-first-page-number
@funindex 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: @code{#f}.

@item first-page-number
@funindex first-page-number

The value of the page number on the first page.

@item print-first-page-number
@funindex print-first-page-number

If set to true, a page number is printed on the first page.

@item print-page-number
@funindex print-page-number

If set to false, page numbers are not printed.

@end table

@seealso
Installed Files:
@file{ly/paper-defaults-init.ly}.

@knownissues
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.


@node Miscellaneous \paper variables
@unnumberedsubsubsec Miscellaneous @code{\paper} variables

@table @code

@item page-spacing-weight
@funindex page-spacing-weight

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

@item print-all-headers
@funindex print-all-headers

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

@item system-separator-markup
@funindex system-separator-markup

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

@lilypond[quote,verbatim,noragged-right,line-width=30\mm]
#(set-default-paper-size "a8")

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

@end table


@seealso
Installed Files:
@file{ly/titling-init.ly}.

Snippets:
@rlsr{Spacing}.


@knownissues

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


@node Score layout
@section Score layout

This section discusses score layout options for the @code{\layout}
block.

@menu
* The \layout block::
* Setting the staff size::
@end menu


@node The \layout block
@subsection The @code{\layout} block

@funindex \layout

While the @code{\paper} block contains settings that relate to the
page formatting of the whole document, the @code{\layout} block
contains settings for score-specific layout.  To set score layout
options globally, enter them in a toplevel @code{\layout} block.
To set layout options for an individual score, enter them in a
@code{\layout} block inside the @code{\score} block, after the
music.  Settings that can appear in a @code{\layout} block
include:

@itemize
@item the @code{layout-set-staff-size} scheme function,
@item context modifications in @code{\context} blocks, and
@item @code{\paper} variables that affect score layout.
@end itemize

The @code{layout-set-staff-size} function is discussed in the next
section, @ref{Setting the staff size}.  Context modifications are
discussed in a separate chapter; see
@ref{Modifying context plug-ins} and
@ref{Changing context default settings}.  The @code{\paper}
variables that can appear in a @code{\layout} block are:

@itemize

@item
@code{line-width}, @code{ragged-right} and @code{ragged-last}
(see @ref{\paper variables for widths and margins})

@item
@code{indent} and @code{short-indent}
(see @ref{\paper variables for shifts and indents})

@item
@code{system-count}
(see @ref{\paper variables for line breaking})

@end itemize

Here is an example @code{\layout} block:

@example
\layout @{
  indent = 2\cm
  \context @{
    \StaffGroup
    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #8
  @}
  \context @{
    \Voice
    \override TextScript #'padding = #1
    \override Glissando #'thickness = #3
  @}
@}
@end example


@seealso
Notation Reference:
@ref{Changing context default settings}.

Snippets:
@rlsr{Spacing}.


@node Setting the staff size
@subsection Setting the staff size

@cindex font size, setting
@cindex staff size, setting
@funindex layout file

The default @strong{staff size} is set to 20 points.
This may be changed in two ways:

To set the staff size globally for all scores in a file (or
in a @code{book} block, to be precise), use @code{set-global-staff-size}.

@example
#(set-global-staff-size 14)
@end example

@noindent
This sets the global default size to 14pt staff height and scales all
fonts accordingly.

To set the staff size individually for each score, use
@example
\score@{
  @dots{}
  \layout @{
    #(layout-set-staff-size 15)
  @}
@}
@end example

The Feta font provides musical symbols at eight different
sizes.  Each font is tuned for a different staff size: at a smaller size
the font becomes heavier, to match the relatively heavier staff lines.
The recommended font sizes are listed in the following table:

@quotation
@multitable @columnfractions .15 .2 .22 .2

@item @b{font name}
@tab @b{staff height (pt)}
@tab @b{staff height (mm)}
@tab @b{use}

@item feta11
@tab 11.22
@tab 3.9
@tab pocket scores

@item feta13
@tab 12.60
@tab 4.4
@tab

@item feta14
@tab 14.14
@tab 5.0
@tab

@item feta16
@tab 15.87
@tab 5.6
@tab

@item feta18
@tab 17.82
@tab 6.3
@tab song books

@item feta20
@tab 20
@tab 7.0
@tab standard parts

@item feta23
@tab 22.45
@tab 7.9
@tab

@item feta26
@tab 25.2
@tab 8.9
@tab
@c modern rental material?

@end multitable
@end quotation

These fonts are available in any sizes.  The context property
@code{fontSize} and the layout property @code{staff-space} (in
@rinternals{StaffSymbol}) can be used to tune the size for individual
staves.  The sizes of individual staves are relative to the global size.


@seealso
Notation Reference:
@ref{Selecting notation font size}.

Snippets:
@rlsr{Spacing}.


@knownissues

@code{layout-set-staff-size} does not change the distance between the
staff lines.


@node Breaks
@section Breaks

@menu
* Line breaking::
* Page breaking::
* Optimal page breaking::
* Optimal page turning::
* Minimal page breaking::
* Explicit breaks::
* Using an extra voice for breaks::
@end menu


@node Line breaking
@subsection Line breaking

@cindex line breaks
@cindex breaking lines

Line breaks are normally determined automatically.  They are chosen
so that lines look neither cramped nor loose, and consecutive
lines have similar density.

To manually force a line break at a bar line, use the
@code{\break} command:

@lilypond[quote,ragged-right,relative=2,verbatim]
c4 c c c | \break
c4 c c c |
@end lilypond

By default, a @code{\break} in the middle of a measure is ignored,
and a warning is printed.  To force a line break in the middle of
a measure, add an invisible bar line with @w{@samp{\bar ""}}:

@lilypond[quote,ragged-right,relative=2,verbatim]
c4 c c
\bar "" \break
c |
c4 c c c |
@end lilypond

A @code{\break} occurring at a bar line is also ignored if the
previous measure ends in the middle of a note, such as when a
tuplet begins and ends in different measures.  To allow
@code{\break} commands to work in these situations, remove the
@code{Forbid_line_break_engraver} from the @code{Voice} context.
Note that manually forced line breaks have to be added in parallel
with the music:

@lilypond[quote,ragged-right,verbatim]
\new Voice \with {
  \remove Forbid_line_break_engraver
} \relative c'' {
  <<
    { c2. \times 2/3 { c4 c c } c2. | }
    { s1 | \break s1 | }
  >>
}
@end lilypond

Similarly, line breaks are normally forbidden when beams cross bar
lines.  This behavior can be changed by setting
@code{\override Beam #'breakable = ##t}:

@lilypond[quote,ragged-right,relative=2,verbatim]
\override Beam #'breakable = ##t
c2. c8[ c | \break
c8 c] c2. |
@end lilypond

The @code{\noBreak} command forbids a line break at the bar line
where it is inserted.

The most basic settings influencing line spacing are @code{indent}
and @code{line-width}.  They are set in the @code{\layout} block.
They control the indentation of the first line of music, and the
lengths of the lines.

If @code{ragged-right} is set to true in the @code{\layout} block,
then systems end at their natural horizontal length, instead of
being spread horizontally to fill the whole line.  This is useful
for short fragments, and for checking how tight the natural
spacing is.

@c TODO Check and add para on default for ragged-right

The option @code{ragged-last} is similar to @code{ragged-right},
but affects only the last line of the piece.

@example
\layout @{
  indent = 0\mm
  line-width = 150\mm
  ragged-last = ##t
@}
@end example



@cindex regular line breaks
@cindex four bar music.

For line breaks at regular intervals use @code{\break} separated by
skips and repeated with @code{\repeat}.  For example, this would
cause the following 28 measures (assuming 4/4 time) to be broken
every 4 measures, and only there:

@example
<<
  \repeat unfold 7 @{
    s1 \noBreak s1 \noBreak
    s1 \noBreak s1 \break
  @}
  @{ @var{the actual music@dots{}} @}
>>
@end example

@c TODO Check this
A linebreaking configuration can be saved as a @file{.ly} file
automatically.  This allows vertical alignments to be stretched to
fit pages in a second formatting run.  This is fairly new and
complicated.  More details are available in
@rlsr{Spacing}.


@predefined
@funindex \break
@code{\break},
@funindex \noBreak
@code{\noBreak}.
@endpredefined


@seealso
Notation Reference:
@ref{\paper variables for line breaking}.

Snippets:
@rlsr{Spacing}.

Internals Reference:
@rinternals{LineBreakEvent}.


@node Page breaking
@subsection Page breaking

The default page breaking may be overridden by inserting
@code{\pageBreak} or @code{\noPageBreak} commands.  These commands are
analogous to @code{\break} and @code{\noBreak}.  They should be
inserted at a bar line.  These commands force and forbid a page-break
from happening.  Of course, the @code{\pageBreak} command also forces
a line break.

The @code{\pageBreak} and @code{\noPageBreak} commands may also be
inserted at top-level, between scores and top-level markups.

There are also analogous settings to @code{ragged-right} and
@code{ragged-last} which have the same effect on vertical spacing:
@code{ragged-bottom} and @code{ragged-last-bottom}.  If set to
@code{##t} the systems on all pages or just the last page
respectively will not be justified vertically.  See
@ref{Fixed vertical spacing \paper variables}.

Page breaks are computed by the @code{page-breaking} function.  LilyPond
provides three algorithms for computing page breaks,
@code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
@code{ly:minimal-breaking}.  The default is @code{ly:optimal-breaking},
but the value can be changed in the @code{\paper} block:

@example
\paper @{
  page-breaking = #ly:page-turn-breaking
@}
@end example

@funindex \bookpart

When a book has many scores and pages, the page breaking problem may be
difficult to solve, requiring large processing time and memory.  To ease
the page breaking process, @code{\bookpart} blocks are used to divide
the book into several parts: the page breaking occurs separately on each
part.  Different page breaking functions may also be used in different
book parts.

@example
\bookpart @{
  \header @{
    subtitle = "Preface"
  @}
  \paper @{
     %% In a part consisting mostly of text,
     %% ly:minimal-breaking may be preferred
     page-breaking = #ly:minimal-breaking
  @}
  \markup @{ @dots{} @}
  @dots{}
@}
\bookpart @{
  %% In this part, consisting of music, the default optimal
  %% page breaking function is used.
  \header @{
    subtitle = "First movement"
  @}
  \score @{ @dots{} @}
  @dots{}
@}
@end example


@predefined
@funindex \pageBreak
@code{\pageBreak},
@funindex \noPageBreak
@code{\noPageBreak}.
@endpredefined


@seealso
Notation Reference:
@ref{\paper variables for page breaking}.

Snippets:
@rlsr{Spacing}.


@node Optimal page breaking
@subsection Optimal page breaking

@funindex ly:optimal-breaking

The @code{ly:optimal-breaking} function is LilyPond's default method of
determining page breaks.  It attempts to find a page breaking that minimizes
cramping and stretching, both horizontally and vertically.  Unlike
@code{ly:page-turn-breaking}, it has no concept of page turns.


@seealso
Snippets:
@rlsr{Spacing}.


@node Optimal page turning
@subsection Optimal page turning

@funindex ly:page-turn-breaking

Often it is necessary to find a page breaking configuration so that there is
a rest at the end of every second page.  This way, the musician can turn the
page without having to miss notes.  The @code{ly:page-turn-breaking} function
attempts to find a page breaking minimizing cramping and stretching, but with
the additional restriction that it is only allowed to introduce page turns
in specified places.

There are two steps to using this page breaking function.  First, you
must enable it in the @code{\paper} block, as explained in @ref{Page
breaking}.  Then you must tell the function where you would like to allow
page breaks.

There are two ways to achieve the second step.  First, you can specify each
potential page turn manually, by inserting @code{\allowPageTurn} into your
input file at the appropriate places.

If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
Voice context.  The @code{Page_turn_engraver} will scan the context for
sections without notes (note that it does not scan for rests; it scans for
the absence of notes.  This is so that single-staff polyphony with rests in one
of the parts does not throw off the @code{Page_turn_engraver}).  When it finds
a sufficiently long section without notes, the @code{Page_turn_engraver} will
insert an @code{\allowPageTurn} at the final bar line in that section, unless
there is a @q{special} bar line (such as a double bar), in which case the
@code{\allowPageTurn} will be inserted at the final @q{special} bar line in
the section.

@funindex minimumPageTurnLength
The @code{Page_turn_engraver} reads the context property
@code{minimumPageTurnLength} to determine how long a note-free section must
be before a page turn is considered.  The default value for
@code{minimumPageTurnLength} is @code{#(ly:make-moment 1 1)}.  If you want
to disable page turns, you can set it to something very large.

@example
\new Staff \with @{ \consists "Page_turn_engraver" @}
@{
  a4 b c d |
  R1 | % a page turn will be allowed here
  a4 b c d |
  \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
  R1 | % a page turn will not be allowed here
  a4 b r2 |
  R1*2 | % a page turn will be allowed here
  a1
@}
@end example

@funindex minimumRepeatLengthForPageTurn
The @code{Page_turn_engraver} detects volta repeats.  It will only allow a page
turn during the repeat if there is enough time at the beginning and end of the
repeat to turn the page back.  The @code{Page_turn_engraver} can also disable
page turns if the repeat is very short.  If you set the context property
@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
only allow turns in repeats whose duration is longer than this value.

The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
@code{\allowPageTurn}, may also be used at top-level, between scores and
top-level markups.


@predefined
@funindex \pageTurn
@code{\pageTurn},
@funindex \noPageTurn
@code{\noPageTurn},
@funindex \allowPageTurn
@code{\allowPageTurn}.
@endpredefined


@seealso
Snippets:
@rlsr{Spacing}.


@knownissues

There should only be one @code{Page_turn_engraver} in a score.  If there is more
than one, they will interfere with each other.


@node Minimal page breaking
@subsection Minimal page breaking

@funindex ly:minimal-breaking

The @code{ly:minimal-breaking} function performs minimal computations to
calculate the page breaking: it fills a page with as many systems as
possible before moving to the next one.  Thus, it may be preferred for
scores with many pages, where the other page breaking functions could be
too slow or memory demanding, or a lot of texts.  It is enabled using:

@example
\paper @{
  page-breaking = #ly:minimal-breaking
@}
@end example


@seealso
Snippets:
@rlsr{Spacing}.


@node Explicit breaks
@subsection Explicit breaks

Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
commands.  There are two commands to override this behavior:

@example
\override NonMusicalPaperColumn #'line-break-permission = ##f
\override NonMusicalPaperColumn #'page-break-permission = ##f
@end example

When @code{line-break-permission} is overridden to false, Lily will insert
line breaks at explicit @code{\break} commands and nowhere else.  When
@code{page-break-permission} is overridden to false, Lily will insert
page breaks at explicit @code{\pageBreak} commands and nowhere else.

@lilypond[quote,verbatim]
\paper {
  indent = #0
  ragged-right = ##t
  ragged-bottom = ##t
}

music = \relative c'' { c8 c c c }

\score {
  \new Staff {
    \repeat unfold 2 { \music } \break
    \repeat unfold 4 { \music } \break
    \repeat unfold 6 { \music } \break
    \repeat unfold 8 { \music } \pageBreak
    \repeat unfold 8 { \music } \break
    \repeat unfold 6 { \music } \break
    \repeat unfold 4 { \music } \break
    \repeat unfold 2 { \music }
  }
  \layout {
    \context {
      \Score
      \override NonMusicalPaperColumn #'line-break-permission = ##f
      \override NonMusicalPaperColumn #'page-break-permission = ##f
    }
  }
}
@end lilypond


@seealso
Snippets:
@rlsr{Spacing}.


@node Using an extra voice for breaks
@subsection Using an extra voice for breaks

Line- and page-breaking information usually appears within note entry directly.

@example
music = \relative c'' @{ c4 c c c @}

\score @{
  \new Staff @{
    \repeat unfold 2 @{ \music @} \break
    \repeat unfold 3 @{ \music @}
  @}
@}
@end example

This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
music entry with information that specifies how music should lay out
on the page.  You can keep music entry and line- and page-breaking
information in two separate places by introducing an extra voice to
contain the  breaks.  This extra voice
contains only skips together with @code{\break}, @code{pageBreak} and other
breaking layout information.

@lilypond[quote,verbatim]
music = \relative c'' { c4 c c c }

\score {
  \new Staff <<
    \new Voice {
      s1 * 2 \break
      s1 * 3 \break
      s1 * 6 \break
      s1 * 5 \break
    }
    \new Voice {
      \repeat unfold 2 { \music }
      \repeat unfold 3 { \music }
      \repeat unfold 6 { \music }
      \repeat unfold 5 { \music }
    }
  >>
}
@end lilypond

This pattern becomes especially helpful when overriding
@code{line-break-system-details} and the other useful but long properties of
@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.

@lilypond[quote,verbatim]
music = \relative c'' { c4 c c c }

\score {
  \new Staff <<
    \new Voice {
      \overrideProperty "Score.NonMusicalPaperColumn"
        #'line-break-system-details #'((Y-offset . 0))
      s1 * 2 \break

      \overrideProperty "Score.NonMusicalPaperColumn"
        #'line-break-system-details #'((Y-offset . 35))
      s1 * 3 \break

      \overrideProperty "Score.NonMusicalPaperColumn"
        #'line-break-system-details #'((Y-offset . 70))
      s1 * 6 \break

      \overrideProperty "Score.NonMusicalPaperColumn"
        #'line-break-system-details #'((Y-offset . 105))
      s1 * 5 \break
    }
    \new Voice {
      \repeat unfold 2 { \music }
      \repeat unfold 3 { \music }
      \repeat unfold 6 { \music }
      \repeat unfold 5 { \music }
    }
  >>
}
@end lilypond


@seealso
Notation Reference:
@ref{Vertical spacing}.

Snippets:
@rlsr{Spacing}.


@node Vertical spacing
@section Vertical spacing

@cindex vertical spacing
@cindex spacing, vertical

Vertical spacing is controlled by three things: the amount of
space available (i.e., paper size and margins), the amount of
space between systems, and the amount of space between
staves inside a system.

@menu
* Flexible vertical spacing within systems::
* Explicit staff and system positioning::
* Vertical collision avoidance::
@end menu


@node Flexible vertical spacing within systems
@subsection Flexible vertical spacing within systems

@cindex distance between staves
@cindex staff distance
@cindex space between staves
@cindex space inside systems

Three separate mechanisms control the flexible vertical spacing
within systems, one for each of the following categories:

@itemize

@item
@emph{ungrouped staves},

@item
@emph{grouped staves} (staves within a staff-group such as
@code{ChoirStaff}, etc.), and

@item
@emph{non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
etc.).

@end itemize

@c TODO: Clarify this.  This almost implies that non-staff lines
@c       have NO effect on the spacing between staves.  -mp

The height of each system is determined in two steps.  First, all
of the staves are spaced according to the amount of space
available.  Then, the non-staff lines are distributed between the
staves.

Note that the spacing mechanisms discussed in this section only
control the vertical spacing of staves and non-staff lines within
individual systems.  The vertical spacing between separate
systems, scores, markups, and margins is controlled by
@code{\paper} variables, which are discussed in
@ref{Flexible vertical spacing \paper variables}.

@menu
* Within-system spacing properties::
* Spacing of ungrouped staves::
* Spacing of grouped staves::
* Spacing of non-staff lines::
@end menu


@node Within-system spacing properties
@unnumberedsubsubsec Within-system spacing properties

@funindex staff-affinity
@funindex staffgroup-staff-spacing
@funindex staff-staff-spacing
@funindex nonstaff-unrelatedstaff-spacing
@funindex nonstaff-relatedstaff-spacing
@funindex nonstaff-nonstaff-spacing
@funindex default-staff-staff-spacing
@funindex minimum-Y-extent
@funindex extra-offset
@funindex self-alignment-X
@funindex X-offset
@funindex VerticalAxisGroup

The within-system vertical spacing mechanisms are controlled by
two sets of grob properties.  The first set is associated with the
@code{VerticalAxisGroup} grob, which is created by all staves and
non-staff lines.  The second set is associated with the
@code{StaffGrouper} grob, which can be created by staff-groups,
but only if explicitly called.  These properties are described
individually at the end of this section.

The names of these properties (except for @code{staff-affinity})
follow the format @code{@var{item1}-@var{item2}-spacing}, where
@code{@var{item1}} and @code{@var{item2}} are the items to be
spaced.  Note that @code{@var{item2}} is not necessarily below
@code{@var{item1}}; for example,
@code{nonstaff-relatedstaff-spacing} will measure upwards from the
non-staff line if @code{staff-affinity} is @code{#UP}.

Each distance is measured between the @emph{reference points} of
the two items.  The reference point for a staff is the vertical
center of its @code{StaffSymbol} (i.e. the middle line if
@code{line-count} is odd; the middle space if @code{line-count} is
even).  The reference points for individual non-staff lines are
given in the following table:

@multitable {Non-staff line} {Reference point}
@headitem Non-staff line @tab Reference point
@item @code{ChordNames}  @tab baseline
@item @code{NoteNames}   @tab baseline
@item @code{Lyrics}      @tab baseline
@item @code{Dynamics}    @tab vertical center
@item @code{FiguredBass} @tab highest point
@item @code{FretBoards}  @tab top line
@end multitable

In the following image, horizontal lines indicate the positions
of these reference points:

@lilypond[quote,noragged-right,line-width=110\mm]
#(define zero-space '((padding . -inf.0) (basic-distance . 0)))

alignToZero = \with {
  \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
  \override VerticalAxisGroup #'nonstaff-nonstaff-spacing = #zero-space
}
lowerCaseChords = \with {
  chordNameLowercaseMinor = ##t
}
staffAffinityDown = \with {
  \override VerticalAxisGroup #'staff-affinity = #DOWN
}
labelContext =
#(define-music-function
     (parser location context)
     (string?)
   #{ s1*0^\markup { \typewriter $context } #})

\layout {
  \context { \Dynamics    \alignToZero }
  \context { \FiguredBass \alignToZero }
  \context { \Lyrics      \alignToZero }
  \context { \NoteNames   \alignToZero }
  \context { \ChordNames  \alignToZero \lowerCaseChords }
  \context { \FretBoards  \alignToZero \staffAffinityDown }
  \context { \Score
    \override BarLine #'stencil = ##f
    \override DynamicText #'self-alignment-X = #-1
    \override FretBoard #'X-offset = #1.75
    \override InstrumentName #'minimum-Y-extent = #'(-2 . 2)
    \override InstrumentName #'extra-offset = #'(0 . -0.5)
    \override TextScript #'minimum-Y-extent = #'(-2 . 3)
    \override TimeSignature #'stencil = ##f
  }
}

%% These contexts have reference points at the baseline:
%%   ChordNames, NoteNames, and Lyrics
<<
  \new ChordNames { \chords { g1:m } }
  \new NoteNames { s1 | g1 | }
  \new RhythmicStaff {
    \set RhythmicStaff.instrumentName = #"baseline "
    \textLengthOn
    \labelContext "ChordNames" s1 |
    \labelContext "NoteNames"  s1 |
    \labelContext "Lyrics"     s1 |
  }
  \new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
>>

%% The reference point for Dynamics is its vertical center
<<
  \new RhythmicStaff {
    \set RhythmicStaff.instrumentName = #"vertical center "
    \labelContext "Dynamics" s1*3
  }
  \new Dynamics { s2\mp s\fp }
>>

%% The reference point for FiguredBass is its highest point
<<
  \new RhythmicStaff {
    \set RhythmicStaff.instrumentName = #"highest point "
    \labelContext "FiguredBass" s1
  }
  \new FiguredBass { \figuremode { <6 5>1 } }
>>

%% The reference point for FretBoards is the top line
\include "predefined-guitar-fretboards.ly"
<<
  \new FretBoards { \chordmode { e1 } }
  \new RhythmicStaff {
    \set RhythmicStaff.instrumentName = #"top line "
    \labelContext "FretBoards " s1
  }
>>
@end lilypond

Each of the vertical spacing grob properties (except
@code{staff-affinity}) uses the same alist structure as the
@code{\paper} spacing variables discussed in
@ref{Flexible vertical spacing \paper variables}.  Specific methods
for modifying alists are discussed in @ref{Modifying alists}.
Grob properties should be adjusted with an @code{\override} inside
a @code{\score} or @code{\layout} block, and not inside a
@code{\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 completely re-defines the property:

@example
\new Staff \with @{
  \override VerticalAxisGroup #'default-staff-staff-spacing
       #'basic-distance = #10
@} @{ @dots{} @}

\new Staff \with @{
  \override VerticalAxisGroup #'default-staff-staff-spacing =
    #'((basic-distance . 10)
       (minimum-distance . 9)
       (padding . 1)
       (stretchability . 10))
@} @{ @dots{} @}
@end example

To change any spacing settings globally, put them in the
@code{\layout} block:

@example
\layout @{
  \context @{
    \Staff
    \override VerticalAxisGroup #'default-staff-staff-spacing
         #'basic-distance = #10
  @}
@}
@end example

Standard settings for the vertical spacing grob properties are
listed in @rinternals{VerticalAxisGroup} and
@rinternals{StaffGrouper}.  Default overrides for specific types
of non-staff lines are listed in the relevant context descriptions
in @rinternals{Contexts}.


@subsubheading Properties of the @code{VerticalAxisGroup} grob

@code{VerticalAxisGroup} properties are typically adjusted with an
@code{\override} at the @code{Staff} level (or equivalent).

@table @code
@item staff-staff-spacing

Used to determine the distance between the current staff and the
staff just below it in the same system, even if one or more
non-staff lines (such as @code{Lyrics}) are placed between the two
staves.  Does not apply to the bottom staff of a system.

Initially, the @code{staff-staff-spacing} of a
@code{VerticalAxisGroup} is a Scheme function that applies the
properties of the @code{StaffGrouper} if the staff is part of a
group, or the @code{default-staff-staff-spacing} of the staff
otherwise.  This allows staves to be spaced differently when they
are grouped.  For uniform spacing regardless of grouping, this
function may be replaced by a flexible-spacing alist, using the
complete-redefinition form of override shown above.

@item default-staff-staff-spacing
A flexible-spacing alist defining the @code{staff-staff-spacing} used for
ungrouped staves, unless @code{staff-staff-spacing} has been explicitly
set with an @code{\override}.

@item staff-affinity
The direction of the staff to use for spacing the current
non-staff line.  Choices are @code{UP}, @code{DOWN}, and
@code{CENTER}.  If @code{CENTER}, the non-staff line will be
placed equidistant between the two nearest staves on either side,
unless collisions or other spacing constraints prevent this.
Adjacent non-staff lines should have non-increasing
@code{staff-affinity} from top to bottom, e.g. a non-staff line
set to @code{UP} should not immediately follow one that is set to
@code{DOWN}.  Non-staff lines at the top of a system should use
@code{DOWN}; those at the bottom should use @code{UP}.  Setting
@code{staff-affinity} for a staff causes it to be treated as a
non-staff line.  Setting @code{staff-affinity} to @code{#f} causes
a non-staff line to be treated as a staff.

@c TODO: verify last clause below ("even if other...")

@item nonstaff-relatedstaff-spacing
The distance between the current non-staff line and the nearest
staff in the direction of @code{staff-affinity}, if there are no
non-staff lines between the two, and @code{staff-affinity} is
either @code{UP} or @code{DOWN}.  If @code{staff-affinity} is
@code{CENTER}, then @code{nonstaff-relatedstaff-spacing} is used
for the nearest staves on @emph{both} sides, even if other
non-staff lines appear between the current one and either of the
staves.

@item nonstaff-nonstaff-spacing
The distance between the current non-staff line and the next
non-staff line in the direction of @code{staff-affinity}, if both
are on the same side of the related staff, and
@code{staff-affinity} is either @code{UP} or @code{DOWN}.

@item nonstaff-unrelatedstaff-spacing
The distance between the current non-staff line and the staff in
the opposite direction from @code{staff-affinity}, if there are no
other non-staff lines between the two, and @code{staff-affinity}
is either @code{UP} or @code{DOWN}.  This can be used, for
example, to require a minimum amount of padding between a
@code{Lyrics} line and the staff to which it does not belong.
@end table


@subsubheading Properties of the @code{StaffGrouper} grob

@code{StaffGrouper} properties are typically adjusted with an
@code{\override} at the @code{StaffGroup} level (or equivalent).

@table @code
@item staff-staff-spacing
The distance between consecutive staves within the current
staff-group.  The @code{staff-staff-spacing} property of an
individual staff's @code{VerticalAxisGroup} grob can be
overriden with different spacing settings for that staff.

@item staffgroup-staff-spacing
The distance between the last staff of the current staff-group and
the staff just below it in the same system, even if one or more
non-staff lines (such as @code{Lyrics}) exist between the two
staves.  Does not apply to the bottom staff of a system.  The
@code{staff-staff-spacing} property of an individual staff's
@code{VerticalAxisGroup} grob can be overriden with different
spacing settings for that staff.
@end table

@seealso
Notation Reference:
@ref{Flexible vertical spacing \paper variables},
@ref{Modifying alists}.

Internals Reference:
@rinternals{Contexts},
@rinternals{VerticalAxisGroup},
@rinternals{StaffGrouper}.

Installed Files:
@file{ly/engraver-init.ly},
@file{scm/define-grobs.scm}.


@node Spacing of ungrouped staves
@unnumberedsubsubsec Spacing of ungrouped staves

@emph{Staves} (such as @code{Staff}, @code{DrumStaff},
@code{TabStaff}, etc.) are contexts that can contain one or more
voice contexts, but cannot contain any other staves.

The following properties affect the spacing of @emph{ungrouped}
staves:

@itemize
@item @code{VerticalAxisGroup} properties:
@itemize
@item @code{default-staff-staff-spacing}
@item @code{staff-staff-spacing}
@end itemize
@end itemize

These grob properties are described individually above; see
@ref{Within-system spacing properties}.

Additional properties are involved for staves that are part of a
staff-group; see @ref{Spacing of grouped staves}.

The following example shows how the @code{default-staff-staff-spacing}
property can affect the spacing of ungrouped staves.
The same overrides applied to @code{staff-staff-spacing} would
have the same effect, but would also apply in cases where the staves
are combined in a group or groups.

@lilypond[verbatim,quote,staffsize=16]
\layout {
  \context {
    \Staff
    \override VerticalAxisGroup #'default-staff-staff-spacing =
      #'((basic-distance . 8)
         (minimum-distance . 7)
         (padding . 1))
  }
}

<<
  % The very low note here needs more room than 'basic-distance
  % can provide, so the distance between this staff and the next
  % is determined by 'padding.
  \new Staff { b,2 r | }

  % Here, 'basic-distance provides enough room, and there is no
  % need to compress the space (towards 'minimum-distance) to make
  % room for anything else on the page, so the distance between
  % this staff and the next is determined by 'basic-distance.
  \new Staff { \clef bass g2 r | }

  % By setting 'padding to a negative value, staves can be made to
  % collide.  The lowest acceptable value for 'basic-distance is 0.
  \new Staff \with {
    \override VerticalAxisGroup #'default-staff-staff-spacing =
      #'((basic-distance . 3.5)
         (padding . -10))
  } { \clef bass g2 r | }
  \new Staff { \clef bass g2 r | }
>>
@end lilypond

@seealso
Installed Files:
@file{scm/define-grobs.scm}.

Snippets:
@rlsr{Spacing}.

Internals Reference:
@rinternals{VerticalAxisGroup}.


@node Spacing of grouped staves
@unnumberedsubsubsec Spacing of grouped staves

In orchestral and other large scores, it is common to place staves
in groups.  The space between groups is typically larger than the
space between staves of the same group.

@emph{Staff-groups} (such as @code{StaffGroup}, @code{ChoirStaff},
etc.) are contexts that can contain one or more staves
simultaneously.

The following properties affect the spacing of staves inside
staff-groups:

@itemize
@item @code{VerticalAxisGroup} properties:
@itemize
@item @code{staff-staff-spacing}
@end itemize
@item @code{StaffGrouper} properties:
@itemize
@item @code{staff-staff-spacing}
@item @code{staffgroup-staff-spacing}
@end itemize
@end itemize

These grob properties are described individually above; see
@ref{Within-system spacing properties}.

The following example shows how properties of the
@code{StaffGrouper} grob can affect the spacing of grouped staves:

@lilypond[verbatim,quote,staffsize=16]
\layout {
  \context {
    \Score
    \override StaffGrouper #'staff-staff-spacing #'padding = #0
    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
  }
}

<<
  \new PianoStaff \with {
    \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
  } <<
    \new Staff { c'1 }
    \new Staff { c'1 }
  >>

  \new StaffGroup <<
    \new Staff { c'1 }
    \new Staff { c'1 }
  >>
>>
@end lilypond

@seealso
Installed Files:
@file{scm/define-grobs.scm}.

Snippets:
@rlsr{Spacing}.

Internals Reference:
@rinternals{VerticalAxisGroup},
@rinternals{StaffGrouper}.


@node Spacing of non-staff lines
@unnumberedsubsubsec Spacing of non-staff lines

@emph{Non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
etc.) are contexts whose layout objects are engraved like staves
(i.e. in horizontal lines within systems).  Specifically,
non-staff lines are non-staff contexts that create the
@code{VerticalAxisGroup} layout object.

The following properties affect the spacing of non-staff lines:

@itemize
@item @code{VerticalAxisGroup} properties:
@itemize
@item @code{staff-affinity}
@item @code{nonstaff-relatedstaff-spacing}
@item @code{nonstaff-nonstaff-spacing}
@item @code{nonstaff-unrelatedstaff-spacing}
@end itemize
@end itemize

These grob properties are described individually above; see
@ref{Within-system spacing properties}.

The following example shows how the
@code{nonstaff-nonstaff-spacing} property can affect the spacing
of consecutive non-staff lines.  Here, by setting the
@code{stretchability} key to a very high value, the lyrics are
able to stretch much more than usual:

@lilypond[verbatim,quote,staffsize=16]
\layout {
  \context {
    \Lyrics
    \override VerticalAxisGroup
      #'nonstaff-nonstaff-spacing #'stretchability = #1000
  }
}

\new StaffGroup
<<
  \new Staff \with {
    \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
  } { c'1 }
  \new Lyrics \with {
    \override VerticalAxisGroup #'staff-affinity = #UP
  } \lyricmode { up }
  \new Lyrics \with {
    \override VerticalAxisGroup #'staff-affinity = #CENTER
  } \lyricmode { center }
  \new Lyrics \with {
    \override VerticalAxisGroup #'staff-affinity = #DOWN
  } \lyricmode { down }
  \new Staff { c'1 }
>>
@end lilypond


@seealso
Installed Files:
@file{ly/engraver-init.ly},
@file{scm/define-grobs.scm}.

Snippets:
@rlsr{Spacing}.

@c @lsr{spacing,page-spacing.ly},
@c @lsr{spacing,alignment-vertical-spacing.ly}.

Internals Reference:
@rinternals{Contexts},
@rinternals{VerticalAxisGroup}.


@node Explicit staff and system positioning
@subsection Explicit staff and system positioning

One way to understand the flexible vertical spacing mechanisms
explained above is as a collection of settings that control the
amount of vertical padding between staves and systems.

It is possible to approach vertical spacing in a different way
using @code{NonMusicalPaperColumn #'line-break-system-details}.
While the flexible vertical spacing mechanisms specify vertical
padding, @code{NonMusicalPaperColumn #'line-break-system-details}
can specify exact vertical positions on the page.

@code{NonMusicalPaperColumn #'line-break-system-details} accepts
an associative list of three different settings:

@itemize
@item @code{X-offset}
@item @code{Y-offset}
@item @code{alignment-distances}
@end itemize

Grob overrides, including the overrides for @code{NonMusicalPaperColumn}
below, can occur in any of three different places in an input file:

@itemize
@item in the middle of note entry directly
@item in a @code{\context} block
@item in the @code{\with} block
@end itemize

When we override @code{NonMusicalPaperColumn}, we use the usual
@code{\override} command in @code{\context} blocks and in the
@code{\with} block.  On the other hand, when we override
@code{NonMusicalPaperColumn} in the middle of note entry,
use the special @code{\overrideProperty} command.  Here are some
example @code{NonMusicalPaperColumn} overrides with the special
@code{\overrideProperty} command:

@example
\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((X-offset . 20))

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((Y-offset . 40))

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((X-offset . 20)
                                 (Y-offset . 40))

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((alignment-distances . (15)))

\overrideProperty NonMusicalPaperColumn
  #'line-break-system-details #'((X-offset . 20)
                                 (Y-offset . 40)
                                 (alignment-distances . (15)))
@end example

To understand how each of these different settings work, we begin
by looking at an example that includes no overrides at all.

@c \book { } is required in these examples to ensure the spacing
@c overrides can be seen between systems. -np

@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          s1*5 \break
          s1*5 \break
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}
@end lilypond

This score isolates line- and page-breaking information in a dedicated
voice.  This technique of creating a breaks voice will help keep layout
separate from music entry as our example becomes more complicated.
See @ref{Using an extra voice for breaks}.

Explicit @code{\breaks} evenly divide the music into six measures per
line.  Vertical spacing results from LilyPond's defaults.  To set
the vertical startpoint of each system explicitly, we can set
the @code{Y-offset} pair in the @code{line-break-system-details}
attribute of the @code{NonMusicalPaperColumn} grob:

@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 0))
          s1*5 \break
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 40))
          s1*5 \break
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 80))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}
@end lilypond

Note that @code{line-break-system-details} takes an associative list of
potentially many values, but that we set only one value here.  Note,
too, that the @code{Y-offset} property here determines the exact vertical
position on the page at which each new system will render.

Now that we have set the vertical startpoint of each system
explicitly, we can also set the vertical distances between staves
within each system manually.  We do this using the @code{alignment-distances}
subproperty of @code{line-break-system-details}.

@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 20)
                                           (alignment-distances . (15)))
          s1*5 \break
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 60)
                                           (alignment-distances . (15)))
          s1*5 \break
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 100)
                                           (alignment-distances . (15)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new Staff {
        \repeat unfold 15 { d'4 d' d' d' }
      }
    >>
  }
}
@end lilypond

Note that here we assign two different values to the
@code{line-break-system-details} attribute of the
@code{NonMusicalPaperColumn} grob.  Though the
@code{line-break-system-details} attribute alist accepts many
additional spacing parameters (including, for example, a corresponding
@code{X-offset} pair), we need only set the @code{Y-offset} and
@code{alignment-distances} pairs to control the vertical startpoint of
every system and every staff.  Finally, note that @code{alignment-distances}
specifies the vertical positioning of staves but not of staff groups.

@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
  \score {
    <<
      \new Staff <<
        \new Voice {
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 0)
                                           (alignment-distances . (30 10)))
          s1*5 \break
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 60)
                                           (alignment-distances . (10 10)))
          s1*5 \break
          \overrideProperty #"Score.NonMusicalPaperColumn"
            #'line-break-system-details #'((Y-offset . 100)
                                           (alignment-distances . (10 30)))
          s1*5 \break
        }
        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
      >>
      \new StaffGroup <<
        \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
        \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
      >>
    >>
  }
}
@end lilypond

Some points to consider:

@itemize
@item When using @code{alignment-distances}, lyrics and other non-staff lines
do not count as a staff.

@item The units of the numbers passed to @code{X-offset},
@code{Y-offset} and @code{alignment-distances} are interpreted as multiples
of the distance between adjacent staff lines.  Positive values move staves
and lyrics up, negative values move staves and lyrics down.

@item Because the @code{NonMusicalPaperColumn #'line-break-system-details}
settings given here allow the positioning of staves and systems anywhere
on the page, it is possible to violate paper or margin boundaries or even
to print staves or systems on top of one another.  Reasonable values
passed to these different settings will avoid this.
@end itemize


@seealso
Snippets:
@rlsr{Spacing}.


@node Vertical collision avoidance
@subsection Vertical collision avoidance

@funindex outside-staff-priority
@funindex outside-staff-padding
@funindex outside-staff-horizontal-padding

Intuitively, there are some objects in musical notation that belong
to the staff and there are other objects that should be placed outside
the staff.  Objects belonging outside the staff include things such as
rehearsal marks, text and dynamic markings (from now on, these will
be called outside-staff objects).  LilyPond's rule for the
vertical placement of outside-staff objects is to place them as close
to the staff as possible but not so close that they collide with
another object.

LilyPond uses the @code{outside-staff-priority} property to determine
whether a grob is an outside-staff object: if @code{outside-staff-priority}
is a number, the grob is an outside-staff object.  In addition,
@code{outside-staff-priority} tells LilyPond in which order the objects
should be placed.

First, LilyPond places all the objects that do not belong outside
the staff.  Then it sorts the outside-staff objects according to their
@code{outside-staff-priority} (in increasing order).  One by one, LilyPond
takes the outside-staff objects and places them so that they do
not collide with any objects that have already been placed.  That
is, if two outside-staff grobs are competing for the same space, the one
with the lower @code{outside-staff-priority} will be placed closer to
the staff.

@lilypond[quote,ragged-right,relative=2,verbatim]
c4_"Text"\pp
r2.
\once \override TextScript #'outside-staff-priority = #1
c4_"Text"\pp % this time the text will be closer to the staff
r2.
% by setting outside-staff-priority to a non-number,
% we disable the automatic collision avoidance
\once \override TextScript #'outside-staff-priority = ##f
\once \override DynamicLineSpanner #'outside-staff-priority = ##f
c4_"Text"\pp % now they will collide
@end lilypond

The vertical padding between an outside-staff object and the
previously-positioned grobs can be controlled with
@code{outside-staff-padding}.

@lilypond[quote,ragged-right,relative=2,verbatim]
\once \override TextScript #'outside-staff-padding = #0
a'^"This text is placed very close to the note"
\once \override TextScript #'outside-staff-padding = #3
c^"This text is padded away from the previous text"
c^"This text is placed close to the previous text"
@end lilypond


By default, outside-staff objects are placed only to avoid
a horizontal collision with previously-positioned grobs.  This
can lead to situations in which objects are placed very close to each
other horizontally.  The vertical spacing between staves can
also be set so that outside staff objects are interleaved.
Setting @code{outside-staff-horizontal-padding}
causes an object to be offset vertically so that such a situation
doesn't occur.

@lilypond[quote,ragged-right,relative=2,verbatim]
% the markup is too close to the following note
c4^"Text"
c4
c''2
% setting outside-staff-horizontal-padding fixes this
R1
\once \override TextScript #'outside-staff-horizontal-padding = #1
c,,4^"Text"
c4
c''2
@end lilypond


@seealso
Snippets:
@rlsr{Spacing}.


@node Horizontal spacing
@section Horizontal spacing

@cindex horizontal spacing
@cindex spacing, horizontal

@menu
* Horizontal spacing overview::
* New spacing area::
* Changing horizontal spacing::
* Line length::
* Proportional notation::
@end menu


@node Horizontal spacing overview
@subsection Horizontal spacing overview

The spacing engine translates differences in durations into stretchable
distances (@q{springs}) of differing lengths.  Longer durations get
more space, shorter durations get less.  The shortest durations get a
fixed amount of space (which is controlled by
@code{shortest-duration-space} in the @rinternals{SpacingSpanner}
object).  The longer the duration, the more space it gets: doubling a
duration adds a fixed amount (this amount is controlled by
@code{spacing-increment}) of space to the note.

For example, the following piece contains lots of half, quarter, and
8th notes; the eighth note is followed by 1 note head width (NHW).
The quarter note is followed by 2 NHW, the half by 3 NHW, etc.

@lilypond[quote,verbatim,relative=1]
c2 c4. c8 c4. c8 c4. c8 c8
c8 c4 c4 c4
@end lilypond

Normally, @code{spacing-increment} is set to 1.2 staff space, which is
approximately the width of a note head, and
@code{shortest-duration-space} is set to 2.0, meaning that the
shortest note gets 2.4 staff space (2.0 times the
@code{spacing-increment}) of horizontal space.  This space is counted
from the left edge of the symbol, so the shortest notes are generally
followed by one NHW of space.

If one would follow the above procedure exactly, then adding a single
32nd note to a score that uses 8th and 16th notes, would widen up the
entire score a lot.  The shortest note is no longer a 16th, but a 32nd,
thus adding 1 NHW to every note.  To prevent this, the shortest
duration for spacing is not the shortest note in the score, but rather
the one which occurs most frequently.


The most common shortest duration is determined as follows: in every
measure, the shortest duration is determined.  The most common shortest
duration is taken as the basis for the spacing, with the stipulation
that this shortest duration should always be equal to or shorter than
an 8th note.  The shortest duration is printed when you run
@code{lilypond} with the @code{--verbose} option.

These durations may also be customized.  If you set the
@code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
this sets the base duration for spacing.  The maximum duration for this
base (normally an 8th), is set through @code{base-shortest-duration}.

@funindex common-shortest-duration
@funindex base-shortest-duration
@funindex stem-spacing-correction
@funindex spacing

Notes that are even shorter than the common shortest note are
followed by a space that is proportional to their duration relative to
the common shortest note.  So if we were to add only a few 16th notes
to the example above, they would be followed by half a NHW:

@lilypond[quote,verbatim,relative=2]
c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
@end lilypond


In the @emph{Essay on automated music engraving}, it was explained
that stem directions influence spacing (see
@ressay{Optical spacing}).  This is controlled with the
@code{stem-spacing-correction} property in the
@rinternals{NoteSpacing}, object.  These are generated for every
@rinternals{Voice} context.  The @code{StaffSpacing} object
(generated in @rinternals{Staff} context) contains the same
property for controlling the stem/bar line spacing.  The following
example shows these corrections, once with default settings, and
once with exaggerated corrections:

@lilypond[quote,ragged-right]
{
  c'4 e''4 e'4 b'4 |
  b'4 e''4 b'4 e''4 |
  \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
  \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
  c'4 e''4 e'4 b'4 |
  b'4 e''4 b'4 e''4 |
}
@end lilypond

Proportional notation is supported; see @ref{Proportional notation}.


@seealso
Snippets:
@rlsr{Spacing}.

Internals Reference:
@rinternals{SpacingSpanner},
@rinternals{NoteSpacing},
@rinternals{StaffSpacing},
@rinternals{NonMusicalPaperColumn}.

Essay on automated music engraving:
@ressay{Optical spacing}.


@knownissues

There is no convenient mechanism to manually override spacing.  The
following work-around may be used to insert extra space into a score,
adjusting the padding value as necessary.
@example
 \override Score.NonMusicalPaperColumn #'padding = #10
@end example

No work-around exists for decreasing the amount of space.


@node New spacing area
@subsection New spacing area

New sections with different spacing parameters can be started with
@code{newSpacingSection}.  This is useful when there are
sections with a different notions of long and short notes.

In the following example, the time signature change introduces a new
section, and hence the 16ths notes are spaced wider.

@lilypond[relative=1,verbatim,quote]
\time 2/4
c4 c8 c
c8 c c4 c16[ c c8] c4
\newSpacingSection
\time 4/16
c16[ c c8]
@end lilypond

The @code{\newSpacingSection} command creates a new
@code{SpacingSpanner} object, and hence new @code{\override}s
may be used in that location.


@seealso
Snippets:
@rlsr{Spacing}.

Internals Reference:
@rinternals{SpacingSpanner}.


@node Changing horizontal spacing
@subsection Changing horizontal spacing

Horizontal spacing may be altered with the
@code{base-shortest-duration} property.  Here
we compare the same music; once without altering
the property, and then altered.  Larger values
of @code{ly:make-moment} will produce smaller
music.  Note that @code{ly:make-moment} constructs
a duration, so @code{1 4} is a longer duration
than @code{1 16}.

@lilypond[verbatim,line-width=12\cm]
\score {
  \relative c'' {
    g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
    g4 e e2 | f4 d d2 | c4 e g g | c,1 |
    d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
    g4 e e2 | f4 d d2 | c4 e g g | c,1 |
  }
}
@end lilypond

@lilypond[verbatim,line-width=12\cm]
\score {
  \relative c'' {
    g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
    g4 e e2 | f4 d d2 | c4 e g g | c,1 |
    d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
    g4 e e2 | f4 d d2 | c4 e g g | c,1 |
  }
  \layout {
    \context {
      \Score
      \override SpacingSpanner
        #'base-shortest-duration = #(ly:make-moment 1 16)
    }
  }
}
@end lilypond


@snippets

By default, spacing in tuplets depends on various non-duration
factors (such as accidentals, clef changes, etc).  To disregard
such symbols and force uniform equal-duration spacing, use
@code{Score.SpacingSpanner #'uniform-stretching}.  This
property can only be changed at the beginning of a score,

@lilypond[quote,ragged-right,verbatim]
\score {
  <<
    \new Staff {
      \times 4/5 {
        c8 c8 c8 c8 c8
      }
      c8 c8 c8 c8
    }
    \new Staff {
      c8 c8 c8 c8
      \times 4/5 {
        c8 c8 c8 c8 c8
      }
    }
  >>
  \layout {
    \context {
      \Score
      \override SpacingSpanner #'uniform-stretching = ##t
    }
  }
}
@end lilypond

When @code{strict-note-spacing} is set, notes are spaced without
regard for clefs, bar lines, and grace notes,

@lilypond[quote,ragged-right,relative=2,verbatim]
\override Score.SpacingSpanner #'strict-note-spacing = ##t
\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c32] }
@end lilypond


@seealso
Snippets:
@rlsr{Spacing}.


@node Line length
@subsection Line length

@cindex page breaks
@cindex breaking pages

@funindex indent
@funindex line-width
@funindex ragged-right
@funindex ragged-last

@c Although line-width can be set in \layout, it should be set in paper
@c block, to get page layout right.
@c Setting indent in \paper block makes not much sense, but it works.

@c Bit verbose and vague, use examples?
The most basic settings influencing the spacing are @code{indent} and
@code{line-width}.  They are set in the @code{\layout} block.  They
control the indentation of the first line of music, and the lengths of
the lines.

If @code{ragged-right} is set to true in the @code{\layout} block, then
systems ends at their natural horizontal length, instead of being spread
horizontally to fill the whole line.  This is useful for
short fragments, and for checking how tight the natural spacing is.
The normal default setting is false, but if the score has only one
system the default value is true.

@cindex page layout
@cindex vertical spacing

The option @code{ragged-last} is similar to @code{ragged-right}, but
only affects the last line of the piece.  No restrictions are put on
that line.  The result is similar to formatting text paragraphs.  In a
paragraph, the last line simply takes its natural horizontal length.
@c Note that for text there are several options for the last line.
@c While Knuth TeX uses natural length, lead typesetters use the same
@c stretch as the previous line.  eTeX uses \lastlinefit to
@c interpolate between both these solutions.

@example
\layout @{
  indent = #0
  line-width = #150
  ragged-last = ##t
@}
@end example


@seealso
Snippets:
@rlsr{Spacing}.


@node Proportional notation
@subsection Proportional notation

LilyPond supports proportional notation, a type of horizontal spacing
in which each note consumes an amount of horizontal space exactly
equivalent to its rhythmic duration.  This type of proportional spacing
is comparable to horizontal spacing on top of graph paper.  Some late
20th- and early 21st-century scores use proportional notation to
clarify complex rhythmic relationships or to facilitate the placement
of timelines or other graphics directly in the score.

LilyPond supports five different settings for proportional notation,
which may be used together or alone:

@itemize
@item @code{proportionalNotationDuration}
@item @code{uniform-stretching}
@item @code{strict-note-spacing}
@item @code{\remove Separating_line_group_engraver}
@item @code{\override PaperColumn #'used = ##t}
@end itemize

In the examples that follow, we explore these five different
proportional notation settings and examine how these settings interact.

We start with the following one-measure example, which uses classical
spacing with ragged-right turned on.

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
  >>
}
@end lilypond

Notice that the half note which begins the measure takes up far less
than half of the horizontal space of the measure.  Likewise, the
sixteenth notes and sixteenth-note quintuplets (or twentieth notes)
which end the measure together take up far more than half the
horizontal space of the measure.

In classical engraving, this spacing may be exactly what we want
because we can borrow horizontal space from the half note and conserve
horizontal space across the measure as a whole.

On the other hand, if we want to insert a measured timeline or other
graphic above or below our score, we need proportional notation.  We
turn proportional notation on with the proportionalNotationDuration
setting.

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
  >>
 \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1 20)
    }
  }
}
@end lilypond

The half note at the beginning of the measure and the faster notes in
the second half of the measure now occupy equal amounts of horizontal
space.  We could place a measured timeline or graphic above or below
this example.

The @code{proportionalNotationDuration} setting is a context setting
that lives in @code{Score}.  Remember that context settings can appear
in one of three locations within our input file -- in a @code{\with}
block, in a @code{\context} block, or directly in music entry preceded
by the @code{\set} command.  As with all context settings, users can
pick which of the three different locations they would like to
set @code{proportionalNotationDuration} in to.

The @code{proportionalNotationDuration} setting takes a single argument,
which is the reference duration against that all music will be spaced.
The LilyPond Scheme function @code{make-moment} takes two arguments
-- a numerator and denominator which together express some fraction of
a whole note.  The call @code{#(ly:make-moment 1 20)} therefore produces
a reference duration of a twentieth note.  Values such as
@code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
@code{#(ly:make-moment 3 97)} are all possible as well.

How do we select the right reference duration to pass to
@code{proportionalNotationDuration}?  Usually by a process of trial
and error, beginning with a duration close to the fastest (or smallest)
duration in the piece.  Smaller reference durations space music loosely;
larger reference durations space music tightly.

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1 8)
    }
  }
}

\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1 16)
    }
  }
}

\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1 32)
    }
  }
}
@end lilypond

Note that too large a reference duration -- such as the eighth note,
above -- spaces music too tightly and can cause note head collisions.
Also that proportional notation in general takes up more horizontal
space than classical spacing.  Proportional spacing provides rhythmic
clarity at the expense of horizontal space.

Next we examine how to optimally space overlapping tuplets.

We start by examining what happens to our original example, with
classical spacing, when we add a second staff with a different type of
tuplet.

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
    \new RhythmicStaff {
      \times 8/9 {
        c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
      }
    }
  >>
}
@end lilypond

The spacing is bad because the evenly spaced notes of the bottom staff
do not stretch uniformly.  Classical engravings include very few complex
triplets and so classical engraving rules can generate this type of
result.  Setting @code{proportionalNotationDuration} fixes this.

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
    \new RhythmicStaff {
      \times 8/9 {
        c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
      }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1 20)
    }
  }
}
@end lilypond

But if we look very carefully we can see that notes of the second half
of the 9-tuplet space ever so slightly more widely than the notes
of the first half of the 9-tuplet.  To ensure uniform stretching, we
turn on @code{uniform-stretching}, which is a property of
@code{SpacingSpanner}.

@lilypond[quote,verbatim,ragged-right]
\score {
  <<
    \new RhythmicStaff {
      c'2
      c'16 c'16 c'16 c'16
      \times 4/5 {
        c'16 c'16 c'16 c'16 c'16
      }
    }
    \new RhythmicStaff {
      \times 8/9 {
        c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
      }
    }
  >>
  \layout {
    \context {
      \Score
      proportionalNotationDuration = #(ly:make-moment 1 20)
      \override SpacingSpanner #'uniform-stretching = ##t
    }
  }
}
@end lilypond

Our two-staff example now spaces exactly, our rhythmic
relationships are visually clear, and we can include a measured
timeline or graphic if we want.

Note that the LilyPond's proportional notation package expects
that all proportional scores set the SpacingSpanner's
'uniform-stretching attribute to ##t.  Setting
proportionalNotationDuration without also setting the
SpacingSpanner's 'uniform-stretching attribute to ##t will, for
example, cause Skips to consume an incorrect amount of horizontal
space.

The SpacingSpanner is an abstract grob that lives in the Score
context.  As with our settings of proportionalNotationDuration,
overrides to the SpacingSpanner can occur in any of three
different places in our input file – in the Score \with block, in
a Score \context block, or in note entry directly.

There is by default only one @code{SpacingSpanner} per @code{Score}.  This
means that, by default, @code{uniform-stretching} is either turned on for the
entire score or turned off for the entire score.  We can, however,
override this behavior and turn on different spacing features at
different places in the score.  We do this with the command
@code{\newSpacingSection}.  See @ref{New spacing area}, for more info.

Next we examine the effects of the @code{Separating_line_group_engraver} and
see why proportional scores frequently remove this engraver.  The following
example shows that there is a small amount of @qq{prefatory} space
just before the first note in each system.

@lilypond[quote,verbatim,ragged-right]
\paper {
  indent = #0
}

\new Staff {
  c'1
  \break
  c'1
}
@end lilypond


The amount of this prefatory space is the same whether after a time
signature, a key signature or a clef.  @code{Separating_line_group_engraver}
is responsible for this space.  Removing @code{Separating_line_group_engraver}
reduces this space to zero.

@lilypond[quote,verbatim,ragged-right]
\paper {
  indent = #0
}

\new Staff \with {
  \remove Separating_line_group_engraver
} {
  c'1
  \break
  c'1
}
@end lilypond

non-musical elements like time signatures, key signatures, clefs and
accidentals are problematic in proportional notation.  None of these
elements has rhythmic duration.  But all of these elements consume
horizontal space.  Different proportional scores approach these
problems differently.

It may be possible to avoid spacing problems with key signatures
simply by not having any.  This is a valid option since most
proportional scores are contemporary music.  The same may be true
of time signatures, especially for those scores
that include a measured timeline or other graphic.  But these scores
are exceptional and most proportional scores include at least some
time signatures.  Clefs and accidentals are even more essential.

So what strategies exist for spacing non-musical elements in a
proportional context?  One good option is the @code{strict-note-spacing}
property of @code{SpacingSpanner}.  Compare the two scores below:

@lilypond[quote,verbatim,ragged-right]
\new Staff {
  \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
  c''8
  c''8
  c''8
  \clef alto
  d'8
  d'2
}

\new Staff {
  \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
  \override Score.SpacingSpanner #'strict-note-spacing = ##t
  c''8
  c''8
  c''8
  \clef alto
  d'8
  d'2
}
@end lilypond

Both scores are proportional, but the spacing in the first score
is too loose because of the clef change.  The spacing of the second
score remains strict, however, because strict-note-spacing is
turned on.  Turning on strict-note-spacing causes the width of
time signatures, key signatures, clefs and accidentals to play no
part in the spacing algorithm.

In addition to the settings given here, there are other settings
that frequently appear in proportional scores.  These include:

@itemize
@item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}
@item @code{tupletFullLength = ##t}
@item @code{\override Beam #'breakable = ##t}
@item @code{\override Glissando #'breakable = ##t}
@item @code{\override TextSpanner #'breakable = ##t}
@item @code{\remove Forbid_line_break_engraver in the Voice context}
@end itemize

These settings space grace notes strictly, extend tuplet brackets to
mark both rhythmic start- and stop-points, and allow spanning elements
to break across systems and pages.  See the respective parts of the manual
for these related settings.


@seealso
Notation Reference:
@ref{New spacing area}.

Snippets:
@rlsr{Spacing}.


@node Fitting music onto fewer pages
@section Fitting music onto fewer pages

Sometimes you can end up with one or two staves on a second
(or third, or fourth...) page.  This is annoying, especially
if you look at previous pages and it looks like there is plenty
of room left on those.

When investigating layout issues, @code{annotate-spacing} is an
invaluable tool.  This command prints the values of various layout
spacing variables; for more details see the following section,
@ref{Displaying spacing}.

@menu
* Displaying spacing::
* Changing spacing::
@end menu


@node Displaying spacing
@subsection Displaying spacing

@funindex annotate-spacing
@cindex spacing, display of layout

To graphically display the dimensions of vertical layout variables
that may be altered for page formatting, set
@code{annotate-spacing} in the @code{\paper} block:

@c need to have \book{} otherwise we get the separate systems. -hwn
@lilypond[verbatim,quote]
#(set-default-paper-size "a6" 'landscape)
\book {
  \score { { c4 } }
  \paper { annotate-spacing = ##t }
}
@end lilypond


@noindent
All layout dimensions are displayed in staff-spaces, regardless
of the units specified in the @code{\paper} or @code{\layout} block.
In the above example, @code{paper-height} has a value of 59.75
@code{staff-spaces}, and the @code{staff-size} is 20 points (the
default value).  Note that:

@multitable {1 staff-space} {staff-size)/4 * (25.4/72.27) mm}

@item 1 point
@tab = (25.4/72.27) mm

@item 1 staff-space
@tab = (@code{staff-size})/4 pts
@item
@tab = (@code{staff-size})/4 * (25.4/72.27) mm

@end multitable

@noindent
In this case, one @code{staff-space} is approximately equal to
1.757mm.  Thus the @code{paper-height} measurement of 59.75
@code{staff-spaces} is equivalent to 105 millimeters, the height
of @code{a6} paper in landscape orientation.  The pairs
(@var{a},@var{b}) are intervals, where @var{a} is the lower
edge and @var{b} the upper edge of the interval.


@seealso
Notation Reference:
@ref{Setting the staff size}.

Snippets:
@rlsr{Spacing}.


@node Changing spacing
@subsection Changing spacing

The output of @code{annotate-spacing} reveals vertical dimensions
in great detail.  For details about modifying margins and other
layout variables, see @ref{Page layout}.

Other than margins, there are a few other options to save space:

@itemize
@item
Force systems to move as close together as possible (to fit as
many systems as possible onto a page) while being spaced so that
there is no blank space at the bottom of the page.

@example
\paper @{
  system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
  ragged-last-bottom = ##f
  ragged-bottom = ##f
@}
@end example

@item
Force the number of systems.  This can help in two ways.  Just
setting a value, even the same value as the number of systems
being typeset by default, will sometimes cause more systems to
be fitted onto each page, as an estimation step is then bypassed,
giving a more accurate fit to each page.  Also, forcing an actual
reduction in the number of systems may save a further page.  For
example, if the default layout has 11 systems, the following
assignment will force a layout with 10 systems.

@example
\paper @{
  system-count = #10
@}
@end example

@item
Avoid (or reduce) objects that increase the vertical size of a
system.  For example, volta repeats (or alternate repeats) require
extra space.  If these repeats are spread over two systems, they
will take up more space than one system with the volta repeats and
another system without.  For example, dynamics that @q{stick out} of
a system can be moved closer to the staff:

@lilypond[verbatim,quote,relative=1]
e4 c g\f c
e4 c g-\tweak #'X-offset #-2.7 -\tweak #'Y-offset #2.5 \f c
@end lilypond

@item
Alter the horizontal spacing via @code{SpacingSpanner}.  For more
details, see @ref{Changing horizontal spacing}.  The following
example illustrates the default spacing:

@lilypond[verbatim,quote]
\score {
  \relative c'' {
    g4 e e2 |
    f4 d d2 |
    c4 d e f |
    g4 g g2 |
    g4 e e2 |
  }
}
@end lilypond

@noindent
The next example modifies @code{common-shortest-duration} from a
value of @code{1/4} to @code{1/2}.  The quarter note is the most
common and shortest duration in this example, so by making this
duration longer, a @q{squeezing} effect occurs:

@lilypond[verbatim,quote]
\score {
  \relative c'' {
    g4 e e2 |
    f4 d d2 |
    c4 d e f |
    g4 g g2 |
    g4 e e2 |
  }
  \layout {
    \context {
      \Score
      \override SpacingSpanner
        #'common-shortest-duration = #(ly:make-moment 1 2)
    }
  }
}
@end lilypond

@noindent
The @code{common-shortest-duration} property cannot be modified
dynamically, so it must always be placed in a @code{\context}
block so that it applies to the whole score.

@end itemize


@seealso
Notation Reference:
@ref{Page layout},
@ref{Changing horizontal spacing}.

Snippets:
@rlsr{Spacing}.