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
+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::
+* Displaying spacing::
* Breaks::
* Vertical spacing::
* Horizontal spacing::
-* Displaying spacing::
-* Vertical collision avoidance::
+* Page layout MOVED FROM LM::
@end menu
@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. Default is true.
@funindex paper-width
@item paper-width
-The width of the page. The default is taken from the current paper size,
+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,
+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.
+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.
+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
+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.
+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
+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.
+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
+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. 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.
+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.
+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.
+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.
+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. Default is@tie{}4mm.
+top-most of the next system. Default is@tie{}4mm.
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
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.
+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.
+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.
+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.
+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. Unset by default.
+systems. This is often used for orchestral scores. Unset by default.
The markup command @code{\slashSeparator} is provided as a sensible
default, for example
@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
+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
@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
+spacing. High values will make page spacing more important. Default
value is 10.
@funindex auto-first-page-number
@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
This manual: @ref{Selecting notation font size}.
+@refbugs
+
+@code{layout-set-staff-size} does not change the distance between the
+staff lines.
+
+
@node Score layout
@subsection Score layout
@seealso
-This manual: @ref{Changing context default settings}
+This manual: @ref{Changing context default settings}.
+
+
+@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
+
+
+@c need to have \book{} otherwise we get the separate systems. -hwn
+@lilypond[verbatim]
+#(set-default-paper-size "a6" 'landscape)
+
+\book {
+ \score { { c4 } }
+ \paper { annotate-spacing = ##t }
+}
+@end lilypond
+
+
+@c TODO: really bad vagueness due to bug in annotate-spacing. -gp
+@noindent
+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 Breaks
* 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}
-
+@c @lsrdir{spacing}
@refbugs
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@{
@end example
The old page breaking algorithm is called
-@code{optimal-page-breaks}. If you are having trouble with the new page
+@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 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
+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.
@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
+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 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
+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
+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
+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 @q{special} barline (such as a double bar), in which case the
-@code{\allowPageTurn} will be inserted at the final @q{special} barline in
+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
+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
@end example
@funindex minimumRepeatLengthForPageTurn
-The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
+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
+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.
+
+@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
+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
@menu
* Vertical spacing inside a system::
* Vertical spacing between systems::
-* Controlling spacing of individual systems::
+* Explicit staff and system positioning::
* Two-pass vertical spacing::
+* Vertical collision avoidance::
@end menu
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. By default,
+@code{max-stretch} is set to zero, disabling stretching. To enable
+stretching, a sane value for @code{max-stretch}
+is @code{ly:align-interface::calc-max-stretch}.
+
+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
+}
+
+\new Score \with
+{
+ \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
+}
+{
+\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
Internals: Vertical alignment of staves is handled by the
-@internalsref{VerticalAlignment} object. The context parameters
+@internalsref{VerticalAlignment} object. The context parameters
specifying the vertical extent are described in connection with
the @internalsref{Axis_group_engraver}.
-Example files: @lsr{spacing,page-spacing.ly},
-@lsr{spacing,alignment-vertical-spacing.ly}.
+Example files: @c @lsr{spacing,page-spacing.ly},
+@c @lsr{spacing,alignment-vertical-spacing.ly}.
@node Vertical spacing between systems
@}
@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.
-@node Controlling spacing of individual systems
-@subsection Controlling spacing of individual systems
+@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
-It is also possible to change the distance between for each system
-individually. This is done by including the command
+@node Explicit staff and system positioning
+@subsection Explicit staff and system positioning
+
+One way to understand the @code{VerticalAxisGroup} and @code{\paper}
+settings explained in the previous two sections is as a collection of
+different settings that primarily concern the amount of vertical padding
+different staves and systems running down the page.
+
+It is possible to approach vertical spacing in a different way using
+@code{NonMusicalPaperColumn #'line-break-system-details}. Where
+@code{VerticalAxisGroup} and @code{\paper} settings specify vertical padding,
+@code{NonMusicalPaperColumn #'line-break-system-details} specifies exact
+vertical positions on the page.
+
+@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
+list of five different settings:
+
+@itemize
+@item @code{X-offset}
+@item @code{Y-offset}
+@item @code{alignment-offsets}
+@item @code{alignment-extra-space}
+@item @code{fixed-alignment-extra-space}
+@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
-#"Score.NonMusicalPaperColumn"
-#'line-break-system-details
-#'((fixed-alignment-extra-space . 15))
+\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))
+
+\override NonMusicalPaperColumn
+ #'line-break-system-details #'((alignment-offsets . (0 -15)))
+
+\override NonMusicalPaperColumn
+ #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
+ (alignment-offsets . (0 -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,
+To understand how each of these different settings work, we begin
+by looking at an example that includes no overrides at all.
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ s1 * 6 \break
+ s1 * 6 \break
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+>>
+@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[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 40))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 80))
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+>>
+@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.
-@lilypond[ragged-right, fragment, relative=2, staffsize=13]
-\new PianoStaff <<
+Now that we have set the vertical startpoint of each system
+explicitly, we can also set the vertical startpoint of each staff
+within each system manually. We do this using the @code{alignment-offsets}
+subproperty of @code{line-break-system-details}.
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 20)
+ (alignment-offsets . (0 -15)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 60)
+ (alignment-offsets . (0 -15)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 100)
+ (alignment-offsets . (0 -15)))
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
\new Staff {
- c1\break
-
- \overrideProperty
- #"Score.NonMusicalPaperColumn"
- #'line-break-system-details
- #'((fixed-alignment-extra-space . 15))
-
- c\break
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
}
- \new Staff { c c }
>>
@end lilypond
-The distance for @code{fixed-alignment-extra-space} may also be
-negative.
+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-offsets} pairs to control the vertical startpoint of
+every system and every staff. Finally, note that @code{alignment-offsets}
+specifies the vertical positioning of staves but not of staff groups.
+
+@lilypond[quote,ragged-right]
+\new Score <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0)
+ (alignment-offsets . (0 -30 -40)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 60)
+ (alignment-offsets . (0 -10 -20)))
+ s1 * 6 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 100)
+ (alignment-offsets . (0 -10, -40)))
+ s1 * 6 \break
+ }
+ \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
+ >>
+ \new StaffGroup <<
+ \new Staff {
+ \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+ }
+ \new Staff {
+ \repeat unfold 18 { e'4 e'4 e'4 e'4 }
+ }
+ >>
+>>
+@end lilypond
+
+Some points to consider:
+
+@itemize
+@item When using @code{alignment-offsets}, lyrics count as a staff.
+
+@item The units of the numbers passed to @code{X-offset},
+@code{Y-offset} and @code{alignment-offsets} 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
@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:
@end enumerate
The @code{ragged-bottom} property adds space between systems, while
-the two-pass technique adds space between staffs inside a system.
+the two-pass technique adds space between staves 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
\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 }
lilypond <file>.ly
@end example
+
+@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,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
+
+TODO: this example doesn't work any more ?
+
+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
+
+
+
@node Horizontal spacing
@section Horizontal Spacing
* New spacing area::
* Changing horizontal spacing::
* Line length::
+* Proportional notation::
@end menu
@end lilypond
-In the introduction (see @ref{Engraving}), it was explained that stem
+In the introduction (see @rlearning{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
@end example
-@node Displaying spacing
-@section Displaying spacing
+@node Proportional notation
+@subsection Proportional notation
-@funindex annotate-spacing
-@cindex Spacing, display of properties
+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 faciliate the placement
+of timelines or other graphics directly in the score.
-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 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
-@lilypond[verbatim]
-#(set-default-paper-size "a6" 'landscape)
+In the examples that follow, we explore these five different
+proportional notation settings and examine how these settings interact.
-\book {
- \score { { c4 } }
- \paper { annotate-spacing = ##t }
+We start with the following one-measure example, which uses classical
+spacing with ragged-right turned on.
+
+@lilypond[quote,verbatim,ragged-right]
+\new 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]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+} <<
+ \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
+
+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}. Recall that context settings appear in one of
+three locations in our input file -- in a @code{\with} block, in a
+@code{\context} block, or directly in music entry
+preceeded 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}.
+
+The @code{proportionalNotationDuration} setting takes a single argument,
+which is the reference duration against which all music will be
+spaced. The LilyPond Scheme function 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. The values
+@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]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 8)
+} <<
+ \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 Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 16)
+} <<
+ \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 Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 32)
+} <<
+ \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
+
+Note that too large a reference duration -- such as the eighth note,
+above -- spaces music too tightly and can cause note head collisions.
+Note also that proportional notation in general takes up more
+horizontal space that does 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]
+\new 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 notes of the bottom staff do not
+stretch uniformly. Classical engraving includes very few complex
+triplets and so classical engraving rules can generate this type of
+result. Setting @code{proportionalNotationDuration} remedies this
+situation considerably.
+
+@lilypond[quote,verbatim,ragged-right]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+} <<
+ \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
+
+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 do 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]
+\new Score \with {
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+ \override SpacingSpanner #'uniform-stretching = ##t
+} <<
+ \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
+
+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{preferatory} 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
-@c need to have \book{} otherwise we get the separate systems. -hwn
+
+The amount of this preferatory 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
+
+Nonmusical elements like time signatures, key signatures, clefs and
+accidentals are problemmatic 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 nonmusical 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.
+
+
+
+@node Page layout MOVED FROM LM
+@section Page layout MOVED FROM LM
+
+@menu
+* Introduction to layout::
+* Global sizes::
+* Line breaks::
+* Page breaks::
+* Fitting music onto fewer pages::
+@end menu
+
+@node Introduction to layout
+@subsection Introduction to layout
+
+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.
+
+Settings which influence layout may be placed in two blocks.
+The @code{\paper @{...@}} block is placed outside any
+@code{\score @{...@}} blocks and contains settings that
+relate to the entire document. The @code{\layout @{...@}}
+block is placed within a @code{\score @{...@}} block and
+contains settings for that particular score. If you have
+only one @code{\score @{...@}} block the two have the same
+effect. In general the commands shown in this section can
+be placed in either.
+
+Much more detail on the options for tweaking the laying out
+of music are contained in @ruser{Spacing issues}.
+
+@node Global sizes
+@subsection Global sizes
+
+TODO Check all these examples
+
+The default @strong{paper size} which LilyPond assumes in laying
+out the music is A4. This may be changed in two ways:
+
+@example
+#(set-default-paper-size "a6")
+
+\paper @{
+#(set-paper-size "letter")
+@}
+@end example
@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.
+The first command sets the size of all pages. The second command
+sets the size of the pages to which the \paper block applies -- if
+the \paper block is at the top of the file, then it will apply
+to all pages. Support for the following paper sizes is available:
+a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid).
+Setting the paper size automatically sets suitable margins and
+line length.
+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, e.g.
-@node Vertical collision avoidance
-@section Vertical collision avoidance
+@example
+#(set-default-paper-size "a6" 'landscape)
+@end example
-@funindex outside-staff-priority
-@funindex outside-staff-padding
-@funindex outside-staff-horizontal-padding
+The default @strong{staff size} is set to 20 points.
+This may be changed in two ways:
-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.
+@example
+#(set-global-staff-size 14)
-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.
+\paper @{
+#(set-global-staff-size 16)
+@}
+@end example
-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.
+@noindent
+The first command sets the size in all pages. The second command
+sets the size in the pages to which the \paper block applies -\96 if
+the \paper block is at the top of the file, then it will apply
+to all pages. All the fonts are automatically scaled to suit
+the new value of the staff size.
+
+@node Line breaks
+@subsection Line breaks
+
+Line breaks are normally determined automatically. They are chosen
+so that lines look neither cramped nor loose, and 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. However,
+line breaks can only occur at the end of @q{complete} bars, i.e.,
+where there are no notes or tuplets left @q{hanging} over the bar
+line. 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 ""},
+although again there must be no notes left hanging over in any of
+the staves at this point, or it will be ignored.
+
+The opposite command, @code{\noBreak}, 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.
+
+The option @code{ragged-last} is similar to @code{ragged-right},
+but affects only the last line of the piece.
-@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
+@example
+\layout @{
+indent = #0
+line-width = #150
+ragged-last = ##t
+@}
+@end example
+
+@node Page breaks
+@subsection Page breaks
+
+The default page breaking may be overriden by inserting
+@code{\pageBreak} or @code{\noPageBreak} commands.
+These commands are analogous to the @code{\break} and
+@code{\noBreak} commands discused above and force or forbid
+a page-break at the point where they are inserted.
+Of course, the @code{\pageBreak} command also forces a line break.
+Like @code{\break}, the @code{\pageBreak} command is effective only
+at the end of a @q{complete} bar as defined above. For more
+details see @ruser{Page breaking} and following sections.
+
+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.
+
+For more details see @ruser{Vertical spacing}.
+
+@node Fitting music onto fewer pages
+@subsection 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 commands; see @ruser{Displaying spacing}, for more
+details. From the output of @code{annotate-spacing}, we can
+see which margins we may wish to alter.
+
+Other than margins, there are a few other options to save space:
+
+@itemize
+@item
+You may tell LilyPond to place systems as close together as
+possible (to fit as many systems as possible onto a page), but
+then to space those systems out so that there is no blank
+space at the bottom of the page.
+
+@example
+\paper @{
+ between-system-padding = #0.1
+ between-system-space = #0.1
+ ragged-last-bottom = ##f
+ ragged-bottom = ##f
+@}
+@end example
+
+@item
+You may force the number of systems (i.e., if LilyPond wants
+to typeset some music with 11 systems, you could force it to
+use 10).
+
+@example
+\paper @{
+ system-count = #10
+@}
+@end example
+
+@item
+Avoid (or reduce) objects which 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.
+
+Another example is moving dynamics which @q{stick out} of
+a system, as in the second bar here:
+
+@lilypond[verbatim,quote,fragment,ragged-right,relative=1]
+e4 c g\f c
+\override DynamicText #'extra-offset = #'( -2.2 . 2.0)
+e4 c g\f c
@end lilypond
-The vertical padding between an outside-staff object and the
-previously-positioned grobs can be controlled with
-@code{outside-staff-padding}.
+@item
+Alter the horizontal spacing via @code{SpacingSpanner}. See
+@ruser{Changing horizontal spacing}, for more details. Here's
+an example first showing the default behaviour:
-@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"
+@lilypond[verbatim,quote,ragged-right]
+\score {
+ \relative c'' {
+ g4 e e2 |
+ f4 d d2 |
+ c4 d e f |
+ g4 g g2 |
+ g4 e e2 |
+ }
+}
@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.
+@noindent
+and now with @code{common-shortest-duration} increased from the
+value of @code{1/4} (a quarter note is the most common in this
+example) to @code{1/2}:
-@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
+@lilypond[verbatim,quote,ragged-right]
+\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
+Note that this override cannot be modified dynamically, so it must
+always be placed in a @code{\context@{..@}} block so that it applies
+to the whole score.
+
+TODO Add description of using \context in this way earlier if it is
+not already anywhere -td
+
+@end itemize
+
+
+
projects / lilypond.git / blobdiff