This influences where line breaks are chosen, and thus ultimately, how
many pages a piece of music takes.
-Globally spoken, this procedure happens in three steps: first,
+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 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.
+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::
The value of the page number of the first page. Default is@tie{}1.
@funindex printfirst-page-number
-@item 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.
+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 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 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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
+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.
@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.
+top-most of the next system. Default is@tie{}4mm.
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.
+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.
+Amount of space between the title and the first system. Default is@tie{}5mm.
-@funindex after-title-space
+@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.
+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).
+book and the title of a piece). Default is@tie{}2mm.
@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.
+systems. This is often used for orchestral scores. Unset by default.
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
* Vertical spacing of piano staves::
* Vertical spacing between systems::
* Controlling spacing of individual systems::
+* Two-pass vertical spacing::
@end menu
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, the systems are stretched according to the
+data in the page layout file.
+@end enumerate
+
+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 spacing, horizontal
@menu
-* Horizontal spacing overview::
-* New spacing area::
-* Changing horizontal spacing::
-* Line length::
+* Horizontal spacing overview::
+* New spacing area::
+* Changing horizontal spacing::
+* Line length::
@end menu
In the following example, the time signature change introduces a new
section, and hence the 16ths notes are spaced wider.
-FIXME: wait until we're definitely adding NEWS items. -gp
-
-@lilypond[relative,fragment,verbatim]
+@lilypond[relative,fragment,verbatim,quote]
\time 2/4
c4 c8 c
c8 c c4 c16[ c c8] c4
-%\newSpacingSection
+\newSpacingSection
\time 4/16
c16[ c c8]
@end lilypond
@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.
+
+@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 4)
+ }
+ }
+}
+@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
@menu
* Line breaking::
* Page breaking::
+* Optimal page breaking::
+* Optimal page turning::
@end menu
@node Line breaking
@seealso
-Internals: @internalsref{BreakEvent}.
+Internals: @internalsref{LineBreakEvent}.
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 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.
+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
-\header@{
- breakbefore = ##t
- piece = ""
+\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{\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{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.
+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.
@node Displaying spacing
projects / lilypond.git / blobdiff