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.
* Breaks::
* Vertical spacing::
* Horizontal spacing::
+* 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 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
+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 quotation
-@commonprop
+@snippets
The header and footer are created by the functions make-footer and
-make-header, defined in \paper. The default implementations are in
+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
+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,
+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
+millimeters. That is why the value 2 cm must be multiplied in the
example
@example
page given the system to put on it.
-@refbugs
+@knownissues
The option right-margin is defined but doesn't set the right margin
yet. The value for the right margin has to be defined adjusting the
This manual: @ref{Selecting notation font size}.
+@knownissues
+
+@code{layout-set-staff-size} does not change the distance between the
+staff lines.
+
+
@node Score layout
@subsection Score layout
@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)
}
@end lilypond
-@c need to have \book{} otherwise we get the separate systems. -hwn
+@c TODO: really bad vagueness due to bug in annotate-spacing. -gp
@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
* Page breaking::
* Optimal page breaking::
* Optimal page turning::
+* Minimal page breaking::
* Explicit breaks::
* Using an extra voice for breaks::
@end menu
This makes the following 28 measures (assuming 4/4 time) be broken every
4 measures, and only there.
-@refcommands
+@predefined
@code{\break}, and @code{\noBreak}.
@funindex \break
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
+@knownissues
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
-This can be avoided by removing the @code{Forbid_line_break_engraver}
-and adding the line breaks in another voice:
+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,verbatim]
-\new Staff <<
- \new Voice \with {
- \remove Forbid_line_break_engraver
- } {
- c'4 c'2 c'2 c'2 c'4
- }
- \new Voice {
- s1 \break s1
- }
->>
+\new Voice \with {
+ \remove Forbid_line_break_engraver
+} {
+ 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
@subsection Page breaking
-The default page breaking may be overriden by inserting
+The default page breaking may be overridden by inserting
@code{\pageBreak} or @code{\noPageBreak} commands. These commands are
analogous to @code{\break} and @code{\noBreak}. They should be
inserted at a bar line. These commands force and forbid a page-break
from happening. Of course, the @code{\pageBreak} command also forces
a line break.
-Page breaks are computed by the @code{page-breaking} function.
-LilyPond provides two algorithms for computing page
-breaks, @code{ly:optimal-breaking} and @code{ly:page-turn-breaking}. The
-default is @code{ly:optimal-breaking}, but the value can be changed in
-the @code{\paper} block:
+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
+@predefined
@funindex \pageBreak
@code{\pageBreak}
@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.
-@refbugs
+The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
+@code{\allowPageTurn}, may also be used at top-level, between scores and
+top-level markups.
+
+@predefined
-There should only be one @code{Page_turn_engraver} in a score. If there is more
+@funindex \pageTurn
+@code{\pageTurn}
+@funindex \noPageTurn
+@code{\noPageTurn}
+@funindex \allowPageTurn
+@code{\allowPageTurn}
+
+@knownissues
+
+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 preferred 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
\override NonMusicalPaperColumn #'page-break-permission = ##f
@end example
-When @code{line-break-permission} is overriden to false, Lily will insert
+When @code{line-break-permission} is overridden to false, Lily will insert
line breaks at explicit @code{\break} commands and nowhere else. When
-@code{page-break-permission} is overriden to false, Lily will insert
+@code{page-break-permission} is overridden to false, Lily will insert
page breaks at explicit @code{\pageBreak} commands and nowhere else.
@lilypond[quote,verbatim]
* Vertical spacing inside a system::
* Vertical spacing between systems::
* Explicit staff and system positioning::
-* Two-pass vertical spacing::
+* Two-pass vertical spacing::
* Vertical collision avoidance::
@end menu
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.
+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
+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
+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
+@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,
+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:
ragged-last-bottom = ##f
}
-\score {
+\new Score \with
+{
+ \override VerticalAlignment #'max-stretch = #ly:align-interface::calc-max-stretch
+}
+{
\new GrandStaff
<<
\new StaffGroup
@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-elegant: 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
@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
+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}.
@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}.
+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:
The @code{ragged-bottom} property adds space between systems, while
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
+To allow this behavior, 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.
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
+their horizontal distance from the previously-positioned 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
@subsection Horizontal spacing overview
The spacing engine translates differences in durations into stretchable
-distances (@q{springs}) of differring lengths. Longer durations get
+distances (@q{springs}) of differing lengths. Longer durations get
more space, shorter durations get less. The shortest durations get a
fixed amount of space (which is controlled by
@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
@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
@internalsref{SeparatingGroupSpanner}.
-@refbugs
+@knownissues
There is no convenient mechanism to manually override spacing. The
following work-around may be used to insert extra space into a score.
@end lilypond
-@commonprop
+@snippets
By default, spacing in tuplets depends on various non-duration
factors (such as accidentals, clef changes, etc). To disregard
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
+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
+clarify complex rhythmic relationships or to facilitate the placement
of timelines or other graphics directly in the score.
LilyPond supports five different settings for proportional notation,
this example.
The @code{proportionalNotationDuration} setting is a context setting that
-lives in @context{Score}. Recall that context settings appear in one of
+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
+preceded 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}.
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
+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.
@end lilypond
Note that too large a reference duration -- such as the eighth note,
-above -- spaces music too tightly and can cause notehead collisions.
+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.
>>
@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.
+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.
-The @code{SpacingSpanner} is an abstract grob that lives in the
-@context{Score} context. As with our settings of
-@code{proportionalNotationDuration},
-overrides to the @code{SpacingSpanner} can occur in any of three different
-places in our input file -- in the Score @code{\with} block, in a
-Score @code{\context} block, or in note entry directly.
+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
@end lilypond
Nonmusical elements like time signatures, key signatures, clefs and
-accidentals are problemmatic in proportional notation. None of these
+accidentals are problematic 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.
}
@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 @code{strict-note-spacing} is turned
-on. Turning on @code{strict-note-spacing} causes the width of time
-signatures, key signatures and clefs to play no part in the spacing
-algorithm. Accidentals are a different matter, however. By default, all
-accidentals consume a little extra space, as the following pair of
-scores shows.
-
-@lilypond[quote,verbatim,ragged-right]
-\new Staff {
- \set Score.proportionalNotationDuration = #(ly:make-moment 1 32)
- c'16
- c'16
- c'16
- c'16
- c'16
- c'16
- c'16
- c'16
-}
-
-\new Staff {
- \set Score.proportionalNotationDuration = #(ly:make-moment 1 32)
- c'16
- cis'16
- c'16
- c'16
- c'16
- c'16
- c'16
- c'16
-}
-@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.
-Both scores are proportional but the second score exhibits spacing
-irregularities due to accidentals. Turning on @code{strict-note-spacing}
-does not work for accidentals. Instead,
-we override the @code{X-extent} of all accidentals to zero and then move the
-accidentals to the left of the notes they modify.
-
-@lilypond[quote,verbatim,ragged-right]
-\new Staff {
- \set Score.proportionalNotationDuration = #(ly:make-moment 1 32)
- \override Accidental #'X-extent = #'(0 . 0)
- \override Accidental #'extra-offset = #'(-1 . 0)
- c'16
- cis'16
- c'16
- c'16
- c'16
- c'16
- c'16
- c'16
-}
-@end lilypond
-
-In addition to the settings given here, there are other settings that
-frequently appear in proportional scores. These include:
+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}
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
+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.
+
+@example
+#(set-default-paper-size "a6" 'landscape)
+@end example
+
+The default @strong{staff size} is set to 20 points.
+This may be changed in two ways:
+
+@example
+#(set-global-staff-size 14)
+
+\paper @{
+#(set-global-staff-size 16)
+@}
+@end example
+
+@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.
+
+@example
+\layout @{
+indent = #0
+line-width = #150
+ragged-last = ##t
+@}
+@end example
+
+@node Page breaks
+@subsection Page breaks
+
+The default page breaking may be overridden by inserting
+@code{\pageBreak} or @code{\noPageBreak} commands.
+These commands are analogous to the @code{\break} and
+@code{\noBreak} commands discussed 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
+
+@item
+Alter the horizontal spacing via @code{SpacingSpanner}. See
+@ruser{Changing horizontal spacing}, for more details. Here's
+an example first showing the default behavior:
+
+@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
+
+@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[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