Merge branch 'master' of git://git.sv.gnu.org/lilypond

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

@c -*- coding: utf-8; mode: texinfo; -*-
@c This file is part of lilypond.tely

@c A menu is needed before every deeper *section nesting of @node's; run
@c     M-x texinfo-all-menus-update
@c to automatically fill in these menus before saving changes

@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 (``springs'') are chosen, based on durations.  All
possible line breaking combinations are tried, and a ``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.

@menu
* Paper and pages::             
* Music layout::                
* Vertical spacing::            
* Horizontal spacing::          
* Breaks::                      
* Displaying spacing::          
* Vertical collision avoidance::  
@end menu


@node Paper and pages
@section Paper and pages

This section deals with the boundaries that define the area
that music can be printed inside.

@menu
* Paper size::                  
* Page formatting::             
@end menu


@node Paper size
@subsection Paper size

@cindex paper size
@cindex page size
@funindex papersize

To change the paper size, there are two commands,
@example
#(set-default-paper-size "a4")
\paper @{
  #(set-paper-size "a4")
@}
@end example

The first command sets the size of all pages.  The second command sets the
size
of the pages that the @code{\paper} block applies to -- if the @code{\paper}
block is at the top of the file, then it will apply to all pages.  If the
@code{\paper} block is inside a @code{\book}, then the paper size will only
apply to that book.

Support for the following paper sizes are included by default,
@code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
@code{11x17} (also known as tabloid).

Extra sizes may be added by editing the definition for
@code{paper-alist} in the initialization file @file{scm/paper.scm}.

@cindex orientation
@cindex landscape

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

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

Setting the paper size will adjust a number of @code{\paper} variables
(such as margins).  To use a particular paper size with altered
@code{\paper} variables, set the paper size before setting the variables.


@node Page formatting
@subsection Page formatting

@cindex page formatting
@cindex margins
@cindex header, page
@cindex footer, page

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

The default layout responds to the following settings in the
@code{\paper} block.

@funindex \paper

@quotation
@table @code
@funindex first-page-number
@item first-page-number
The value of the page number of the first page.  Default is@tie{}1.

@funindex printfirst-page-number
@item print-first-page-number
If set to true, will print the page number in the first page.  Default is
false.

@funindex print-page-number
@item print-page-number
If set to false, page numbers will not be printed. Default is true.

@funindex paper-width
@item paper-width
The width of the page. The default is taken from the current paper size,
see @ref{Paper size}. 

@funindex paper-height
@item paper-height
The height of the page. The default is taken from the current paper size,
see @ref{Paper size}. 

@funindex top-margin
@item top-margin
Margin between header and top of the page. Default is@tie{}5mm.

@funindex bottom-margin
@item bottom-margin
Margin between footer and bottom of the page. Default is@tie{}6mm.

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

@funindex line-width
@item line-width
The length of the systems. Default is @code{paper-width} minus @tie{}20mm.

@funindex head-separation
@item head-separation
Distance between the top-most music system and the page header. Default
is@tie{}4mm. 

@funindex foot-separation
@item foot-separation
Distance between the bottom-most music system and the page
footer. Default is@tie{}4mm.

@funindex page-top-space
@item page-top-space
Distance from the top of the printable area to the center of the first
staff. This only works for staves which are vertically small. Big staves
are set with the top of their bounding box aligned to the top of the
printable area. Default is@tie{}12mm.

@funindex ragged-bottom
@item ragged-bottom
If set to true, systems will not be spread vertically across the page.  This
does not affect the last page. Default is false.

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

@funindex ragged-last-bottom
@item ragged-last-bottom
If set to false, systems will be spread vertically to fill the last
page. Default is true.

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

@funindex system-count
@item system-count
This variable, if set, specifies into how many lines a score should be
broken. Unset by default.

@funindex between-system-space
@item between-system-space
This dimensions determines the distance between systems.  It is the
ideal distance between the center of the bottom staff of one system
and the center of the top staff of the next system. Default is@tie{}20mm.

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

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

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


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

@funindex after-title-space
@item after-title-space
Amount of space between the title and the first system. Default is@tie{}5mm.

@funindex before-title-space
@item before-title-space
Amount of space between the last system of the previous piece and the
title of the next. Default is@tie{}10mm.

@funindex between-title-space
@item between-title-space
Amount of space between consecutive titles (e.g., the title of the
book and the title of a piece). Default is@tie{}2mm.

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

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

The markup command @code{\slashSeparator} is provided as a sensible
default,  for example

@lilypond[ragged-right]
#(set-default-paper-size "a6" 'landscape)
\book {
  \score {
    \relative { c1 \break c1 }
  }
  \paper {
    systemSeparatorMarkup = \slashSeparator
  }
}
@end lilypond

@funindex blank-page-force
@item 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. Default value
is 10.

@funindex blank-last-page-force
@item blank-last-page-force
The penalty for ending the score on an odd-numbered page.
Default value is 0.

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

@funindex auto-first-page-number
@item auto-first-page-number
The page breaking algorithm is affected by the first page number being
odd or even.  If this variable is set to #t, the page breaking algorithm
will decide whether to start with an odd or even number.  This will 
result in the first page number remaining as is or being increased by one.

@end table
@end quotation

Example:

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

You can also define these values in Scheme.  In that case @code{mm},
@code{in}, @code{pt}, and @code{cm} are variables defined in
@file{paper-defaults.ly} with values in millimeters.  That is why the
value must be multiplied in the example

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

The header and footer are created by the functions @code{make-footer}
and @code{make-header}, defined in @code{\paper}.  The default
implementations are in @file{ly/@/paper@/-defaults@/.ly} and
@file{ly/@/titling@/-init@/.ly}.

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


@refbugs

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

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

The titles (from the @code{\header@{@}} section) 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 Music layout
@section Music layout

@menu
* Setting the staff size::   
* Score layout::                
@end menu


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

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

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@{
  ...
  \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
@internalsref{StaffSymbol}) can be used to tune the size for individual
staves.  The sizes of individual staves are relative to the global size.

@example

@end example

@seealso

This manual: @ref{Selecting notation font size}.


@node Score layout
@subsection Score layout

@funindex \layout

While @code{\paper} contains settings that relate to the page formatting
of the whole document, @code{\layout} contains settings for score-specific
layout.

@example
\layout @{
  indent = 2.0\cm
  \context @{ \Staff
    \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
  @}
  \context @{ \Voice
    \override TextScript #'padding = #1.0
    \override Glissando #'thickness = #3
  @}
@}
@end example


@seealso

This manual: @ref{Changing context default settings}


@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
* Vertical spacing inside a system::  
* Vertical spacing of piano staves::  
* Vertical spacing between systems::  
* Controlling spacing of individual systems::  
* Two-pass vertical spacing::
@end menu


@node Vertical spacing inside a system
@subsection Vertical spacing inside a system

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

The height of each system is determined automatically.  To prevent
staves from bumping into each other, some minimum distances are set.
By changing these, you can put staves closer together.  This
reduces the amount of space each system requires, and may result
in having more systems per page.

Normally staves are stacked vertically.  To make staves maintain a
distance, their vertical size is padded.  This is done with the
property @code{minimum-Y-extent}.  When applied to a
@internalsref{VerticalAxisGroup}, it controls the size of a horizontal
line, such as a staff or a line of lyrics.  @code{minimum-Y-extent}
takes a pair of numbers, so
if you want to make it smaller than its default @code{#'(-4 . 4)}
then you could set

@example
\override Staff.VerticalAxisGroup #'minimum-Y-extent = #'(-3 . 3)
@end example

@noindent
This sets the vertical size of the current staff to 3 staff spaces on
either side of the center staff line.  The value @code{(-3 . 3)} is
interpreted as an interval, where the center line is the 0, so the
first number is generally negative.  The numbers need not match;
for example, the staff can be made larger at the bottom by setting
it to @code{(-6 . 4)}.


@seealso

Internals: Vertical alignment of staves is handled by the
@internalsref{VerticalAlignment} object. The context parameters
specifying the vertical extent are described in connection with
the @internalsref{Axis_group_engraver}.

Example files: @inputfileref{input/regression/,page-spacing.ly},
@inputfileref{input/regression/,alignment-vertical-spacing.ly}.


@node Vertical spacing of piano staves
@subsection Vertical spacing of piano staves

The distance between staves of a @internalsref{PianoStaff} cannot be
computed during formatting.  Rather, to make cross-staff beaming work
correctly, that distance has to be fixed beforehand.

The distance of staves in a @code{PianoStaff} is set with the
@code{forced-distance} property of the
@internalsref{VerticalAlignment} object, created in
@internalsref{PianoStaff}.

It can be adjusted as follows
@example
\new PianoStaff \with @{
  \override VerticalAlignment #'forced-distance = #7
@} @{
  ...
@}
@end example

@noindent
This would bring the staves together at a distance of 7 staff spaces,
measured from the center line of each staff.

The difference is demonstrated in the following example,
@lilypond[quote,verbatim]
\relative c'' <<
  \new PianoStaff \with {
    \override VerticalAlignment #'forced-distance = #7
  } <<
    \new Staff { c1 }
    \new Staff { c }
  >>
  \new PianoStaff <<
    \new Staff { c }
    \new Staff { c }
  >>
>>
@end lilypond


@seealso

Example files: @inputfileref{input/regression/,alignment-vertical-spacing.ly}.


@node Vertical spacing between systems
@subsection Vertical spacing between systems

Space between systems are controlled by four @code{\paper} variables,

@example
\paper @{
  between-system-space = 1.5\cm
  between-system-padding = #1
  ragged-bottom=##f
  ragged-last-bottom=##f
@}
@end example


@node Controlling spacing of individual systems
@subsection Controlling spacing of individual systems

It is also possible to change the distance between for each system
individually.  This is done by including the command

@example
\overrideProperty
#"Score.NonMusicalPaperColumn"
#'line-break-system-details
#'((fixed-alignment-extra-space . 15))
@end example

@noindent
at the line break before the system to be changed. The distance
@code{15} is distributed over all staves that have a fixed distance
alignment.  For example,

@lilypond[ragged-right, fragment, relative=2, staffsize=13]
\new PianoStaff <<
  \new Staff {
    c1\break
  
    \overrideProperty
    #"Score.NonMusicalPaperColumn"
    #'line-break-system-details
    #'((fixed-alignment-extra-space . 15))

    c\break
  }
  \new Staff { c c }
>>
@end lilypond

The distance for @code{fixed-alignment-extra-space} may also be
negative.


@node Two-pass vertical spacing
@subsection Two-pass vertical spacing

In order to automatically stretch systems so that they should fill the
space left on a page, a two-pass technique can be used:

@enumerate
@item In the first pass, the amount of vertical space used to increase
the height of each system is computed and dumped to a file.
@item In the second pass, spacing inside the systems are
stretched according to the data in the page layout file.
@end enumerate

The @code{ragged-bottom} property adds space between systems, while
the two-pass technique adds space between staffs inside a system.

To allow this behaviour, a @code{tweak-key} variable has to be set in
each score @code{\layout} block, and the tweaks included in each score
music, using the @code{\scoreTweak} music function.

@quotation
@verbatim
%% include the generated page layout file:
\includePageLayoutFile

\score {
  \new StaffGroup <<
    \new Staff <<
      %% Include this score tweaks:
      \scoreTweak "scoreA"
      { \clef french c''1 \break c''1 } 
    >>
    \new Staff { \clef soprano g'1 g'1 }
    \new Staff { \clef mezzosoprano e'1 e'1 }
    \new Staff { \clef alto g1 g1 }
    \new Staff { \clef bass c1 c1 }
  >>
  \header {
    piece = "Score with tweaks"
  }
  %% Define how to name the tweaks for this score:
  \layout { #(define tweak-key "scoreA") }
}
@end verbatim
@end quotation

For the first pass, the @code{dump-tweaks} option should be set to
generate the page layout file.

@example
lilypond -b null -d dump-tweaks <file>.ly
lilypond <file>.ly
@end example

@node Horizontal spacing
@section Horizontal Spacing

@cindex horizontal spacing
@cindex spacing, horizontal

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


@node Horizontal spacing overview
@subsection Horizontal spacing overview

The spacing engine translates differences in durations into stretchable
distances (``springs'') of differring 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 @internalsref{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,fragment,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 @internalsref{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,fragment,verbatim,relative=2]
c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
@end lilypond


In the introduction (see @ref{Engraving}), it was explained that stem
directions influence spacing.  This is controlled with the
@code{stem-spacing-correction} property in the
@internalsref{NoteSpacing}, object.  These are generated for every
@internalsref{Voice} context.  The @code{StaffSpacing} object
(generated in @internalsref{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

Internals: @internalsref{SpacingSpanner}, @internalsref{NoteSpacing},
@internalsref{StaffSpacing}, @internalsref{SeparationItem}, and
@internalsref{SeparatingGroupSpanner}.


@refbugs

There is no convenient mechanism to manually override spacing.  The
following work-around may be used to insert extra space into a score.
@example
 \once \override Score.SeparationItem #'padding = #1
@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,fragment,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
@internalsref{SpacingSpanner} object, and hence new @code{\override}s
may be used in that location.


@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[relative,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[relative,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


@commonprop

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,relative=2,fragment,verbatim]
\new Score \with {
  \override SpacingSpanner #'uniform-stretching = ##t
} <<
  \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
    }
  }
>>
@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,fragment,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


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

@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


@node Breaks
@section Breaks

@menu
* Line breaking::               
* Page breaking::               
* Optimal page breaking::       
* Optimal page turning::        
@end menu

@node Line breaking
@subsection Line breaking

@cindex line breaks
@cindex breaking lines

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

Occasionally you might want to override the automatic breaks; you can
do this by specifying @code{\break}.  This will force a line break at
this point.  Line breaks can only occur at places where there are bar
lines.  If you want to have a line break where there is no bar line,
you can force an invisible bar line by entering @code{\bar
""}.  Similarly, @code{\noBreak} forbids a line break at a
point.


@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}:
@example
<< \repeat unfold 7 @{
         s1 \noBreak s1 \noBreak
         s1 \noBreak s1 \break @}
   @emph{the real music}
>>
@end example

@noindent
This makes the following 28 measures (assuming 4/4 time) be broken every
4 measures, and only there.

@refcommands

@code{\break}, and @code{\noBreak}.
@funindex \break
@funindex \noBreak

@seealso

Internals: @internalsref{LineBreakEvent}.

A linebreaking configuration can now be saved as a @code{.ly} file
automatically.  This allows vertical alignments to be stretched to
fit pages in a second formatting run.  This is fairly new and
complicated; see @inputfileref{input/regression/,page-layout-twopass.ly}
for details.

@refbugs

Line breaks can only occur if there is a ``proper'' bar line.  A note
which is hanging over a bar line is not proper, such as

@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
c4 c2 c2 \break   % this does nothing
c2 c4 |           % a break here would work
c4 c2 c4 ~ \break % as does this break
c4 c2 c4
@end lilypond

To allow line breaks on such bar lines, the
@code{Forbid_line_break_engraver} can be removed from @code{Voice}
context, like so


@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
\new Voice \with {
  \remove "Forbid_line_break_engraver"
} {
  c4 c2 c2 \break   % now the break is allowed
  c2 c4
}
@end lilypond



@node Page breaking
@subsection Page breaking

The default page breaking may be overriden 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.

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

@example
\paper@{
  #(define page-breaking ly:page-turn-breaking)
@}
@end example

The old page breaking algorithm is called
@code{optimal-page-breaks}. If you are having trouble with the new page
breakers, you can enable the old one as a workaround.

@refcommands

@funindex \pageBreak
@code{\pageBreak}
@funindex \noPageBreak
@code{\noPageBreak}


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


@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. 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 barline in that section, unless
there is a ``special'' barline (such as a double bar), in which case the
@code{\allowPageTurn} will be inserted at the final ``special'' barline 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.

@refbugs

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 Displaying spacing
@section Displaying spacing

@funindex annotate-spacing
@cindex Spacing, display of properties

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


@lilypond[verbatim]
#(set-default-paper-size "a6" 'landscape)

\book {
  \score { { c4 } }
  \paper { annotate-spacing = ##t }
}
@end lilypond

@c need to have \book{} otherwise we get  the separate systems. -hwn

@noindent
@c  FIXME: really bad vagueness due to bug in annotate-spacing.  -gp
Some unit dimensions are measured in staff spaces, while others
are measured in millimeters.
The pairs
(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
@var{b} the upper edge of the interval.


@node Vertical collision avoidance
@section 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,fragment,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,fragment,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 without regard to
their horizontal distance from the previously-posititioned grobs.  This
can lead to situations in which objects are placed very close to each
other horizontally.  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,fragment,verbatim]
% the markup is too close to the following note
c2^"Text"
c''2
% setting outside-staff-horizontal-padding fixes this
R1
\once \override TextScript #'outside-staff-horizontal-padding = #1
c,,2^"Text"
c''2
@end lilypond