@funindex last-bottom-spacing
the distance from the last system or top-level markup on a page to
-the bottom of the printable area (i.e. the top of the bottom
+the bottom of the printable area (i.e., the top of the bottom
margin).
@item top-system-spacing
@funindex top-system-spacing
-the distance from the top of the printable area (i.e. the bottom
+the distance from the top of the printable area (i.e., the bottom
of the top margin) to the first system on a page, when there is no
(title or top-level) markup between the two.
@item top-markup-spacing
@funindex top-markup-spacing
-the distance from the top of the printable area (i.e. the bottom
+the distance from the top of the printable area (i.e., the bottom
of the top margin) to the first (title or top-level) markup on a
page, when there is no system between the two.
@end table
When specified in a @code{\paper} block this defines the horizontal
extent available for the staff lines in un-indented systems. If left
unspecified, the paper's @code{line-width} is determined from
-@code{(paper-width@tie{}@minus{}@tie{}left-margin@tie{}@minus{}@tie{}right-margin)}
+@code{(paper-width@tie{}@minus{}@tie{}left-margin@tie{}@minus{}@tie{}right-margin)}.
If the paper's @code{line-width} is specified, and both
-@code{left-margin} and @code{right-margin} are not, then the
-margins will be updated to center the systems on the page
-automatically. Also see @code{check-consistency}.
+@code{left-margin} and @code{right-margin} are not, then the margins
+will be updated to center the systems on the page automatically. Also
+see @code{check-consistency}.
@code{line-width}s for individual scores can be specified in the
scores' @code{\layout} blocks. These values control the width of the
The page-breaking algorithm to use. Choices are
@code{ly:minimal-breaking}, @code{ly:page-turn-breaking},
-@code{ly:one-line-breaking}, @code{ly:one-line-auto-height-breaking},
-and @code{ly:optimal-breaking} (the default).
+@code{ly:one-page-breaking}, @code{ly:one-line-breaking},
+@code{ly:one-line-auto-height-breaking}, and @code{ly:optimal-breaking}
+(the default).
@item page-breaking-system-system-spacing
@funindex page-breaking-system-system-spacing
even-numbered page. The values of the following three variables may
be increased to make these actions less likely.
-The values are penalties, i.e. the higher the value the less likely
+The values are penalties, i.e., the higher the value the less likely
will be the associated action relative to other choices.
@table @code
@ref{Optimal page breaking},
@ref{Optimal page turning},
@ref{Minimal page breaking},
-@ref{One-line page breaking}.
+@ref{One-page page breaking},
+@ref{One-line page breaking},
+@ref{One-line-auto-height page breaking}.
Installed Files:
@file{ly/paper-defaults-init.ly}.
@subheading Automatic font weight at different sizes
-The Feta font provides musical symbols at eight different
-sizes. Each font is tuned for a different staff size: at a smaller size
-the font becomes heavier, to match the relatively heavier staff lines.
-The recommended font sizes are listed in the following table:
+The Emmentaler font provides the set of @emph{Feta} musical glyphs in
+eight different sizes; each one tuned for a different staff size. The
+smaller the glyph size, the @qq{heavier} it becomes, so as to match the
+relatively thicker staff lines. Recommended glyphs sizes are listed in
+the following table:
@multitable @columnfractions .15 .2 .22 .2
@item @b{font name} @tab @b{staff height (pt)} @tab @b{staff height (mm)} @tab @b{use}
@seealso
Notation Reference:
-@ref{Selecting notation font size}.
+@ref{Selecting notation font size},
+@ref{The Emmentaler font}.
Snippets:
@rlsr{Spacing}.
}
@end lilypond
-By default, a @code{\break} in the middle of a measure is ignored,
-and a warning is printed. To force a line break in the middle of
-a measure, add an invisible bar line with @w{@samp{\bar ""}}:
+By default, a @code{\break} command inserted in the @q{middle} of a
+measure will be ignored (and a warning message will be output during the
+compilation of the LilyPond file). Adding an invisible bar line
+-- @w{@samp{\bar ""}} -- before the @code{\break} command will force the
+issue:
@lilypond[quote,ragged-right,verbatim]
\relative c'' {
c4 c c
- \bar "" \break
+ \bar ""
+ \break
c |
c4 c c c |
}
@end lilypond
-A @code{\break} occurring at a bar line is also ignored if the
-previous measure ends in the middle of a note, such as when a
-tuplet begins and ends in different measures. To allow
-@code{\break} commands to work in these situations, remove the
-@code{Forbid_line_break_engraver} from the @code{Voice} context.
-Note that manually forced line breaks have to be added in parallel
-with the music:
+A @code{\break} command that occurrs at a bar line will also ignored if
+the previous measure ends in the middle of a note (e.g., when a tuplet
+begins in one measure and ends in another). In this case remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context and,
+use a simultaneous music construction inserting the @code{\break} at the
+appropriate place in the second @q{voice}:
@lilypond[quote,ragged-right,verbatim]
\new Voice \with {
}
@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}:
+Similarly, by default, line breaks are ignored when beams cross bar
+lines. Use the @code{\override Beam.breakable = ##t} command to force
+this:
@lilypond[quote,ragged-right,verbatim]
\relative c'' {
}
@end lilypond
-The @code{\noBreak} command forbids a line break at the bar line
+The @code{\noBreak} command will prevent a line break at the bar line
where it is inserted.
Within a score, automatic line breaking is prevented within music
* Manual page breaking::
* Optimal page breaking::
* Minimal page breaking::
+* One-page page breaking::
* One-line page breaking::
* One-line-auto-height page breaking::
* Optimal page turning::
@rlsr{Spacing}.
+@node One-page page breaking
+@unnumberedsubsubsec One-page page breaking
+
+@funindex ly:one-page-breaking
+
+The @code{ly:one-page-breaking} function is a special-purpose
+page breaking algorithm that automatically adjusts the page height to
+fit the music, so that everything fits on a single page. The
+@code{paper-height} variable in the paper block is ignored, but other
+settings work as usual. In particular, the spacing between the last
+system (or top level markup) and the footer can be customized with
+@code{last-bottom-spacing} in the paper block. The width of the page
+is left unmodified by default but can be set with @code{paper-width}
+in the paper block.
+
+@knownissues
+@code{ly:one-page-breaking} is not currently compatible with
+@code{\bookpart}.
+
+
@node One-line page breaking
@unnumberedsubsubsec One-line page breaking
@end example
@funindex minimumRepeatLengthForPageTurn
-With volta repeats, the @code{Page_turn_engraver} 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. If the
-repeat is very short, the @code{Page_turn_engraver} can also be
-used to disable page turns by setting a value for the context
-property @code{minimumRepeatLengthForPageTurn} where as
-@code{Page_turn_engraver} only allows 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, in
-top-level markups and between scores.
+
+When using volta repeats, the @code{Page_turn_engraver} 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. If the repeat is too
+short then the @code{Page_turn_engraver} can be used to @emph{disable}
+page turns by setting an appropriate value for the context property
+@code{minimumRepeatLengthForPageTurn}. In this case the
+@code{Page_turn_engraver} will only allows turns in repeats whose
+duration is longer than the value specified.
+
+The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
+@code{\allowPageTurn}, may also be used at top-level, in top-level
+markups and between scores.
@predefined
@funindex \pageTurn
Each distance is measured between the @emph{reference points} of
the two items. The reference point for a staff is the vertical
-center of its @code{StaffSymbol} (i.e. the middle line if
+center of its @code{StaffSymbol} (i.e., the middle line if
@code{line-count} is odd; the middle space if @code{line-count} is
even). The reference points for individual non-staff lines are
given in the following table:
placed equidistant between the two nearest staves on either side,
unless collisions or other spacing constraints prevent this.
Adjacent non-staff lines should have non-increasing
-@code{staff-affinity} from top to bottom, e.g. a non-staff line
+@code{staff-affinity} from top to bottom, e.g., a non-staff line
set to @code{UP} should not immediately follow one that is set to
@code{DOWN}. Non-staff lines at the top of a system should use
@code{DOWN}; those at the bottom should use @code{UP}. Setting
@emph{Non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
etc.) are contexts whose layout objects are engraved like staves
-(i.e. in horizontal lines within systems). Specifically,
+(i.e., in horizontal lines within systems). Specifically,
non-staff lines are non-staff contexts that contain the
@rinternals{Axis_group_engraver}.
can specify exact vertical positions on the page.
@code{NonMusicalPaperColumn.line-break-system-details} accepts
-an associative list of three different settings:
+an associative list of four different settings:
@itemize
@item @code{X-offset}
@item @code{Y-offset}
+@item @code{extra-offset}
@item @code{alignment-distances}
@end itemize
}
@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{Breaks}.
+This score isolates both line-breaking 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. Also see @ref{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:
+By using explicit @code{\break} commands, the music is divided into five
+measures per line. Vertical spacing is from LilyPond's own defaults but
+the vertical startpoint of each system is set explicitly using the
+@code{Y-offset} pair in the @code{line-break-system-details} attribute
+of the @code{NonMusicalPaperColumn} grob:
@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
too, that the @code{Y-offset} property here determines the exact vertical
position on the page at which each new system will render.
+In contrast to the absolute positioning available through
+@code{Y-offset} and @code{X-offset}, relative positioning is possible
+with the @code{extra-offset} property of
+@code{line-break-system-details}. Placement is relative to the
+default layout or to the absolute positioning created by setting
+@code{X-offset} and @code{Y-offset}. The property @code{extra-offset}
+accepts a @code{pair} consisting of displacements along the X-axis and
+Y-axis.
+
+@lilypond[verbatim,quote,staffsize=16]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+ \score {
+ <<
+ \new Staff <<
+ \new Voice {
+ s1*5 \break
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((extra-offset . (0 . 10)))
+ s1*5 \break
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((extra-offset . (0 . 10)))
+ s1*5 \break
+ }
+ \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+ >>
+ \new Staff {
+ \repeat unfold 15 { d'4 d' d' d' }
+ }
+ >>
+ }
+}
+@end lilypond
+
Now that we have set the vertical startpoint of each system
explicitly, we can also set the vertical distances between staves
within each system manually. We do this using the @code{alignment-distances}
do not count as a staff.
@item The units of the numbers passed to @code{X-offset},
-@code{Y-offset} and @code{alignment-distances} 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.
+@code{Y-offset}, @code{extra-offset} and @code{alignment-distances} 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
\relative { c''2 c4. c8 | c4. c16[ c] c4. c8 | c8 c c4 c c }
@end lilypond
+As explained in the @emph{Essay on automated music engraving}, stem
+directions will influence spacing (see @ressay{Optical spacing}) and can
+be adjusted using the @code{stem-spacing-correction} property of the
+@rinternals{NoteSpacing} object (which are generated for every
+@rinternals{Voice} context).
+
+The @code{StaffSpacing} object (generated in @rinternals{Staff} context)
+contains the same property for controlling the stem/bar line spacing.
-In the @emph{Essay on automated music engraving}, it was explained
-that stem directions influence spacing (see
-@ressay{Optical spacing}). This is controlled with the
-@code{stem-spacing-correction} property in the
-@rinternals{NoteSpacing}, object. These are generated for every
-@rinternals{Voice} context. The @code{StaffSpacing} object
-(generated in @rinternals{Staff} context) contains the same
-property for controlling the stem/bar line spacing. The following
-example shows these corrections, once with default settings, and
-once with exaggerated corrections:
+The following example shows this; once with the default settings and
+once with an exaggerated adjustment:
@lilypond[quote,ragged-right]
\fixed c' {