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,
+Globally spoken, this procedure happens in three 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.
+possible line breaking combinations are tried, and the one with the
+best results -- a layout that has uniform density and requires as
+little stretching or cramping as possible -- is chosen.
+
+After spacing and linebreaking, the systems are distributed across
+pages, taking into account the size of the page, and the size of the
+titles.
@menu
* Paper and pages::
The value of the page number of the first page. Default is@tie{}1.
@funindex printfirst-page-number
-@item print-first-page-number
+@item printfirst-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.
+If set to false, page numbers will not be printed.
@funindex paper-width
@item paper-width
-The width of the page. The default is taken from the current paper size,
-see @ref{Paper size}.
+The width of the page.
@funindex paper-height
@item paper-height
-The height of the page. The default is taken from the current paper size,
-see @ref{Paper size}.
+The height of the page.
@funindex top-margin
@item top-margin
-Margin between header and top of the page. Default is@tie{}5mm.
+Margin between header and top of the page.
@funindex bottom-margin
@item bottom-margin
-Margin between footer and bottom of the page. Default is@tie{}6mm.
+Margin between footer and bottom of the page.
@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.
+Margin between the left side of the page and the beginning of the music.
@funindex line-width
@item line-width
-The length of the systems. Default is @code{paper-width} minus @tie{}20mm.
+The length of the systems.
@funindex head-separation
@item head-separation
-Distance between the top-most music system and the page header. Default
-is@tie{}4mm.
+Distance between the top-most music system and the page header.
@funindex foot-separation
@item foot-separation
-Distance between the bottom-most music system and the page
-footer. Default is@tie{}4mm.
+Distance between the bottom-most music system and the page footer.
@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.
+printable area.
@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.
+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.
@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.
+If set to false, systems will be spread vertically to fill the last page.
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.
+broken.
@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.
+and the center of the top staff of the next system.
Increasing this will provide a more even appearance of the page at the
cost of using more vertical space.
@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.
+top-most of the next system.
Increasing this will put systems whose bounding boxes almost touch
farther apart.
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.
+for instrument names at the left.
@funindex after-title-space
@item after-title-space
-Amount of space between the title and the first system. Default is@tie{}5mm.
+Amount of space between the title and the first system.
-@funindex before-title-space
+@funindex after-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.
+title of the next.
@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.
+book and the title of a piece).
@funindex printallheaders
@item printallheaders
@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.
+systems. This is often used for orchestral scores.
The markup command @code{\slashSeparator} is provided as a sensible
default, for example
}
@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 1.
-
-@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
@menu
* Horizontal spacing overview::
-* New spacing area::
* Changing horizontal spacing::
* Line length::
@end menu
No work-around exists for decreasing the amount of space.
+@c FIXME: include this in 2.9; currently removed for 2.8 -gp
+@ignore
@node New spacing area
@subsection New spacing area
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]
+@li lypond[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
-
+@e nd lilypond
+@end ignore
@node Changing horizontal spacing
@subsection Changing horizontal spacing
@menu
* Line breaking::
* Page breaking::
-* Optimal page breaking::
-* Optimal page turning::
@end menu
@node Line breaking
@seealso
-Internals: @internalsref{LineBreakEvent}.
+Internals: @internalsref{BreakEvent}.
A linebreaking configuration can now be saved as a @code{.ly} file
automatically. This allows vertical alignments to be stretched to
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:
+Page breaks are computed by the @code{page-breaking} function in the
+@code{\paper} block.
+
+To force a new page for a new piece (in a collection of pieces or a
+piece in several movements), use @code{breakbefore} in the header.
@example
-\paper@{
- #(define page-breaking ly:page-turn-breaking)
+\header@{
+ breakbefore = ##t
+ piece = ""
@}
@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{\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
-The @code{Page_turn_engraver} does not respect time-scaled music. For example, the
-following example does not behave as expected:
-
-@example
-\new Staff \with @{ \consists "Page_turn_engraver" @}
-@{
- a4 b c d |
- R1 | % a page turn will be allowed here
- a4 b \times 2/3 @{c d e@} |
- R1 | % a page turn will NOT be allowed here
- a1
-@}
-@end example
-
-There should only be one @code{Page_turn_engraver} in a score. If there is more
-than one, they will interfere with each other.
+The @code{breakbefore=##t} header requires that there is a @code{piece}
+header as well. It may be used as a normal header, or left blank
+(@code{=""}) as in the example above, but it must be present.
@node Displaying spacing