Increasing this will put systems whose bounding boxes almost touch
farther apart.
+@funindex page-breaking-between-system-padding
+@item page-breaking-between-system-padding
+This variable tricks the page breaker into thinking that
+@code{between-system-padding} is set to something different than it
+really is. For example, if this variable is set to something substantially
+larger than @code{between-system-padding}, then the page-breaker will put
+fewer systems on each page.
@funindex horizontal-shift
@item horizontal-shift
@end table
@end quotation
+
+@commonprop
+
+The header and footer are created by the functions make-footer and
+make-header, defined in \paper. The default implementations are in
+ly/paper-defaults.ly and ly/titling-init.ly.
+
+The page layout itself is done by two functions in the \paper block,
+page-music-height and page-make-stencil. The former tells the
+line-breaking algorithm how much space can be spent on a page, the
+latter creates the actual page given the system to put on it.
+
+You can define paper block values in Scheme. In that case mm, in, pt,
+and cm are variables defined in paper-defaults.ly with values in
+millimeters. That is why the value 2 cm must be multiplied in the
+example
+
+@example
+\paper @{
+ #(define bottom-margin (* 2 cm))
+@}
+@end example
+
+
Example:
@example
@}
@end example
+This second example centers page numbers at the bottom of every page.
+
+@example
+\paper @{
+ print-page-number = ##t
+ print-first-page-number = ##t
+ oddHeaderMarkup = \markup \fill-line @{ " " @}
+ evenHeaderMarkup = \markup \fill-line @{ " " @}
+ oddFooterMarkup = \markup @{ \fill-line @{
+ \bold \fontsize #3 \on-the-fly #print-page-number-check-first
+ \fromproperty #'page:page-number-string @} @}
+ evenFooterMarkup = \markup @{ \fill-line @{
+ \bold \fontsize #3 \on-the-fly #print-page-number-check-first
+ \fromproperty #'page:page-number-string @} @}
+@}
+@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
@seealso
-This manual: @ref{Changing context default settings}
+This manual: @ref{Changing context default settings}.
@node Displaying spacing
* Page breaking::
* Optimal page breaking::
* Optimal page turning::
+* Minimal page breaking::
* Explicit breaks::
* Using an extra voice for breaks::
@end menu
Internals: @internalsref{LineBreakEvent}.
-A linebreaking configuration can now be saved as a @code{.ly} file
+A linebreaking configuration can 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. More details are available in
@lsrdir{spacing}
-
@refbugs
Line breaks can only occur if there is a @q{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
+c4 c2 << c2 {s4 \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
-
+This can be avoided by removing the @code{Forbid_line_break_engraver}.
+Note that manually forced line breaks have to be added in parallel
+with the music.
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,verbatim]
\new Voice \with {
- \remove "Forbid_line_break_engraver"
+ \remove Forbid_line_break_engraver
} {
- c4 c2 c2 \break % now the break is allowed
- c2 c4
+ c4 c2 << c2 {s4 \break } >> % now the break is allowed
+ c2 c4
}
@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}.
@node Page breaking
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:
+The @code{\pageBreak} and @code{\noPageBreak} commands may also be
+inserted at top-level, between scores and top-level markups.
+
+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@{
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 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
@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.
+
+@refcommands
+
+@funindex \pageTurn
+@code{\pageTurn}
+@funindex \noPageTurn
+@code{\noPageTurn}
+@funindex \allowPageTurn
+@code{\allowPageTurn}
+
@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 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 prefered 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 @{
+ #(define page-breaking ly:minimal-breaking)
+@}
+@end example
@node Explicit breaks
@subsection Explicit breaks
for example, the staff can be made larger at the bottom by setting
it to @code{(-6 . 4)}.
+After page breaks are determined, the vertical spacing within each
+system is reevaluated in order to fill the page more evenly; if a page
+has space left over, systems are stretched in order to fill that space.
+The amount of stretching can be configured though the @code{max-stretch}
+property of the @internalsref{VerticalAlignment} grob. To disable this
+stretching entirely, set @code{max-stretch} to zero.
+
+In some situations, you may want to stretch most of a system while
+leaving some parts fixed. For example, if a piano part occurs in the
+middle of an orchestral score, you may want to leave the piano staves
+close to each other while stretching the rest of the score. The
+@code{keep-fixed-while-stretching} property of
+@internalsref{VerticalAxisGroup} can be used to achieve this. When set
+to @code{##t}, this property keeps its staff (or line of lyrics) from
+moving relative to the one directly above it. In the example above,
+you would override @code{keep-fixed-while-stretching} to @code{##t} in
+the second piano staff:
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+#(set-global-staff-size 14.0)
+
+\book {
+\paper {
+ ragged-last-bottom = ##f
+}
+
+\score {
+\new GrandStaff
+<<
+ \new StaffGroup
+ <<
+ \new Staff {c' d' e' f'}
+ \new Staff {c' d' e' f'}
+ \new Staff {c' d' e' f'}
+ >>
+
+ \new PianoStaff
+ <<
+ \new Staff {c' d' e' f'}
+ \new Staff \with {
+ \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
+ }
+ {c' d' e' f'}
+ >>
+
+ \new StaffGroup
+ <<
+ \new Staff {c' d' e' f'}
+ \new Staff {c' d' e' f'}
+ >>
+>>
+}
+}
+@end lilypond
@seealso
@}
@end example
+When only a couple of flat systems are placed on a page, the resulting
+vertical spacing may be non-eleguant: one system at the top of the page,
+and the other at the bottom, with a huge gap between them. To avoid this
+situation, the space added between the systems can be limited. This
+feature is activated by setting to @code{#t} the
+@code{page-limit-inter-system-space} variable in the @code{\paper}
+block. The paper variable @code{page-limit-inter-system-space-factor}
+determines how much the space can be increased: for instance, the value
+@code{1.3} means that the space can be 30% larger than what it would be
+on a ragged-bottom page.
+
+In the following example, if the inter system space were not limited,
+the second system of page 1 would be placed at the page bottom. By
+activating the space limitation, the second system is placed closer to
+the first one. By setting @code{page-limit-inter-system-space-factor} to
+@code{1}, the spacing would the same as on a ragged-bottom page, like
+the last one.
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+\book {
+ \paper {
+ page-limit-inter-system-space = ##t
+ page-limit-inter-system-space-factor = 1.3
+
+ oddFooterMarkup = \markup "page bottom"
+ evenFooterMarkup = \markup "page bottom"
+ oddHeaderMarkup = \markup \fill-line {
+ "page top" \fromproperty #'page:page-number-string }
+ evenHeaderMarkup = \markup \fill-line {
+ "page top" \fromproperty #'page:page-number-string }
+ }
+ \new Staff << \repeat unfold 4 { g'4 g' g' g' \break }
+ { s1*2 \pageBreak } >>
+}
+@end lilypond
@node Explicit staff and system positioning
@subsection Explicit staff and system positioning
@node Two-pass vertical spacing
@subsection Two-pass vertical spacing
+Warning: two-pass vertical spacing is deprecated and will be removed in
+a future version of LilyPond. Systems are now stretched automatically
+in a single pass. See @ref{Vertical spacing inside a system}.
+
In order to automatically stretch systems so that they should fill the
space left on a page, a two-pass technique can be used:
\new Staff <<
%% Include this score tweaks:
\scoreTweak "scoreA"
- { \clef french c''1 \break c''1 }
+ { \clef french c''1 \break c''1 }
>>
\new Staff { \clef soprano g'1 g'1 }
\new Staff { \clef mezzosoprano e'1 e'1 }
which may be used together or alone:
@itemize
-proportionalNotationDuration
-uniform-stretching
-strict-note-spacing
-\remove Separating_line_group_engraver
-\override PaperColumn #'used = ##t
+@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
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.
+@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