Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.19.22"
@ignore
GDP TODO list
> and prints page number -1 on the second page, for example.
-In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
-states:
-
-"@code{layout-set-staff-size} does not change the distance between
-the
-staff lines."
-
-Could we add a sentence:
-"Use instead the pair fontSize = #@var{N}
- \override StaffSymbol #'staff-space = #(magstep
-@var{N})
-inside the Staff context to change the size of the font and the
-distance between
-staff lines accordingly."
-
-Actually I found, that the @internalsref{StaffSymbol} at line 481
-sends to an incomplete
-documentation. The property staff-space is not explained here. I
-thought Y-extent might be of
-help, but it is in turn explained by x-space which again is
-missing from the list. Who has the
-knowledge to fix this?
-
-
Clarify
http://code.google.com/p/lilypond/issues/detail?id=68
so that neither the horizontal nor the vertical spacing is too cramped
or stretched.
-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 chapter can
-be placed in either.
+Two types of blocks can contain layout settings:
+@code{\paper @{@dots{}@}} and @code{\layout @{@dots{}@}}. The
+@code{\paper} block contains page layout settings that are expected
+to be the same for all scores in a book or bookpart, such as the
+paper height, or whether to print page numbers, etc. See
+@ref{Page layout}. The @code{\layout} block contains score layout
+settings, such as the number of systems to use, or the space
+between staff-groups, etc. See @ref{Score layout}.
@menu
-* Paper and pages::
-* Music layout::
+* Page layout::
+* Score layout::
* Breaks::
* Vertical spacing::
* Horizontal spacing::
@end menu
-@node Paper and pages
-@section Paper and pages
+@node Page layout
+@section Page layout
-This section deals with the boundaries that define the area
-within which music can be printed.
+This section discusses page layout options for the @code{\paper}
+block.
@menu
-* Paper size::
-* Page formatting::
+* The paper block::
+* Paper size and automatic scaling::
+* Fixed vertical spacing paper variables::
+* Flexible vertical spacing paper variables::
+* Horizontal spacing paper variables::
+* Other paper variables::
@end menu
-@node Paper size
-@subsection Paper size
+@node The paper block
+@subsection The @code{@bs{}paper} block
+
+@code{\paper} blocks may be placed in three different places to form
+a descending hierarchy of @code{\paper} blocks:
+
+@itemize
+
+@item
+At the top of the input file, before all @code{\book},
+@code{\bookpart}, and @code{\score} blocks.
+
+@item
+Within a @code{\book} block but outside all the @code{\bookpart} and
+@code{\score} blocks within that book.
+
+@item
+Within a @code{\bookpart} block but outside all @code{\score} blocks
+within that bookpart.
+
+@end itemize
+
+A @code{\paper} block cannot be placed within a @code{\score} block.
+
+The values of the fields filter down this hierarchy, with the values
+set higher in the hierarchy persisting unless they are over-ridden
+by a value set lower in the hierarchy.
+
+Several @code{\paper} blocks can appear at each of the levels, for
+example as parts of several @code{\include}d files. If so, the
+fields at each level are merged, with values encountered last taking
+precedence if duplicated fields appear.
+
+Settings that can appear in a @code{\paper} block include:
+
+@itemize
+
+@item
+the @code{set-paper-size} scheme function,
+
+@item
+@code{\paper} variables used for customizing page layout, and
+
+@item
+markup definitions used for customizing the layout of headers,
+footers, and titles.
+
+@end itemize
+
+The @code{set-paper-size} function is discussed in the next
+section, @ref{Paper size and automatic scaling}. The
+@code{\paper} variables that deal with page layout are discussed
+in later sections. The markup definitions that deal with headers,
+footers, and titles are discussed in
+@ref{Custom titles headers and footers}.
+
+Most @code{\paper} variables will only work in a @code{\paper}
+block. The few that will also work in a @code{\layout} block are
+listed in @ref{The layout block,,The @code{@bs{}layout} block}.
+
+Except when specified otherwise, all @code{\paper} variables that
+correspond to distances on the page are measured in millimeters,
+unless a different unit is specified by the user. For example,
+the following declaration sets @code{top-margin} to ten
+millimeters:
+
+@example
+\paper @{
+ top-margin = 10
+@}
+@end example
+
+To set it to @code{0.5} inches, use the @code{\in} unit suffix:
+
+@example
+\paper @{
+ top-margin = 0.5\in
+@}
+@end example
+
+The available unit suffixes are @code{\mm}, @code{\cm},
+@code{\in}, and @code{\pt}. These units are simple values for
+converting from millimeters; they are defined in
+@file{ly/paper-defaults-init.ly}. For the sake of clarity, when
+using millimeters, the @code{\mm} is typically included in the
+code, even though it is not technically necessary.
+
+It is also possible to define @code{\paper} values using Scheme.
+The Scheme equivalent of the above example is:
+
+@example
+\paper @{
+ #(define top-margin (* 0.5 in))
+@}
+@end example
+
+@seealso
+Notation Reference:
+@ref{Paper size and automatic scaling},
+@ref{Custom titles headers and footers},
+@ref{The layout block,,The @code{@bs{}layout} block}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+
+@node Paper size and automatic scaling
+@subsection Paper size and automatic scaling
@cindex paper size
@cindex page size
-Two functions are available for changing the paper size:
-@code{set-default-paper-size} and @code{set-paper-size}.
-@code{set-default-paper-size} must be placed in the toplevel
-scope, and @code{set-paper-size} must be placed in a @code{\paper}
-block:
+@funindex \paper
+
+@menu
+* Setting the paper size::
+* Automatic scaling to paper size::
+@end menu
+
+
+@node Setting the paper size
+@unnumberedsubsubsec Setting the paper size
+
+@q{A4} is the default value when no explicit paper size is set. However,
+there are two functions that can be used to change it:
+
+@table @code
+@item set-default-paper-size
@example
-#(set-default-paper-size "a4")
+#(set-default-paper-size "quarto")
@end example
+which must always be placed at the toplevel scope, and
+
+@item set-paper-size
+
@example
\paper @{
- #(set-paper-size "a4")
+ #(set-paper-size "tabloid")
@}
@end example
-@noindent
-@code{set-default-paper-size} sets the size of all pages, whereas
-@code{set-paper-size} only sets the size of the pages that the
-@code{\paper} block applies to. For example, if the @code{\paper}
-block is at the top of the file, then it will apply the paper size
-to all pages. If the @code{\paper} block is inside a
-@code{\book}, then the paper size will only apply to that book.
-
-Common paper sizes are available, including @code{a4},
-@code{letter}, @code{legal}, and @code{11x17} (also known as
-tabloid). Many more paper sizes are supported by default. For
-details, see @file{scm/@/paper@/.scm}, and search for the
-definition of @code{paper-alist}.
+which must always be placed in a @code{\paper} block.
+@end table
-@c TODO add a new appendix for paper sizes (auto-generated) -pm
+If the @code{set-default-paper-size} function is used in the toplevel
+scope, it must come before any @code{\paper} block.
+@code{set-default-paper-size} sets the paper size for all pages,
+whereas @code{set-paper-size} only sets the paper size for the pages
+that the @code{\paper} block applies to. For example, if the
+@code{\paper} block is at the top of the file, then it will apply the
+paper size to all pages. If the @code{\paper} block is inside a
+@code{\book}, then the paper size will only apply to that book.
-@warning{The default paper size is @code{a4}.}
+When the @code{set-paper-size} function is used, it must be
+placed @emph{before} any other functions used within the same
+@code{\paper} block. See @ref{Automatic scaling to paper size}.
-Extra sizes may be added by editing the definition of
-@code{paper-alist} in the initialization file
-@file{scm/@/paper@/.scm}, however they will be overridden on a
-subsequent install.
+Paper sizes are defined in @file{scm/paper.scm}, and while it is
+possible to add custom sizes, they will be overwritten on subsequent
+software updates. The available paper sizes are listed in
+@ref{Predefined paper sizes}.
-@cindex orientation
-@cindex landscape
+@c An appendix entry exists for paper sizes but is not auto-generated
-If the symbol @code{'landscape} is supplied as an argument to
-@code{set-default-paper-size}, pages will be rotated by 90
-degrees, and wider line widths will be set accordingly.
+The following command can be used in the file to add a custom paper size
+which can then be used with @code{set-default-paper-size} or
+@code{set-paper-size} as appropriate,
@example
-#(set-default-paper-size "a6" 'landscape)
+#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))
+
+\paper @{
+ #(set-paper-size "my size")
+@}
@end example
-Setting the paper size will adjust a number of @code{\paper}
-variables, such as margins. To use a particular paper size with
-altered @code{\paper} variables, set the paper size before setting
-the variables.
+The units @code{in} (inches), @code{cm} (centimeters) and @code{mm}
+(millimeters) can all be used.
+@cindex paper size, orientation
+@cindex page, orientation
+@cindex paper size, landscape
-@seealso
-Installed Files:
-@file{scm/@/paper@/.scm}.
+If the symbol @code{'landscape} is added to the paper size function,
+pages will be rotated by 90 degrees, and wider line widths will be set
+accordingly.
-Snippets:
-@rlsr{Spacing}.
+@example
+#(set-default-paper-size "a6" 'landscape)
+@end example
+Swapping the paper dimensions @emph{without} having the print rotated
+(like when printing to postcard size, or creating graphics for inclusion
+rather than a standalone document) can be achieved by appending
+@samp{landscape} to the name of the paper size itself:
-@node Page formatting
-@subsection Page formatting
+@example
+#(set-default-paper-size "a6landscape")
+@end example
-@funindex \paper
+When the paper size ends with an explicit @samp{landscape} or
+@samp{portrait}, the presence of a @code{'landscape} symbol @emph{only}
+affects print orientation, not the paper dimensions used for layout.
-Margins, headers, and footers and other layout variables are
-automatically set according to the paper size.
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size},
+@ref{Predefined paper sizes}.
-Default margin values are accessible in
-@file{ly/@/paper@/-defaults@/-init@/.ly}. They apply to the default
-paper size (a4, unless specified differently) and are scaled
-accordingly for other paper sizes.
+Installed Files:
+@file{scm/paper.scm}.
+
+
+@node Automatic scaling to paper size
+@unnumberedsubsubsec Automatic scaling to paper size
+
+If the paper size is changed with one of the scheme functions
+(@code{set-default-paper-size} or @code{set-paper-size}), the
+values of several @code{\paper} variables are automatically scaled
+to the new size. To bypass the automatic scaling for a particular
+variable, set the variable after setting the paper size. Note
+that the automatic scaling is not triggered by setting the
+@code{paper-height} or @code{paper-width} variables, even though
+@code{paper-width} can influence other values (this is separate
+from scaling and is discussed below). The
+@code{set-default-paper-size} and @code{set-paper-size} functions
+are described in @ref{Setting the paper size}.
+
+The vertical dimensions affected by automatic scaling are
+@code{top-margin} and @code{bottom-margin} (see
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables}).
+The horizontal
+dimensions affected by automatic scaling are @code{left-margin},
+@code{right-margin}, @code{inner-margin}, @code{outer-margin},
+@code{binding-offset}, @code{indent}, and @code{short-indent} (see
+@ref{Horizontal spacing paper variables,,Horizontal spacing @code{@bs{}paper} variables}).
+
+The default values for these dimensions are set in
+@file{ly/paper-defaults-init.ly}, using internal variables named
+@code{top-margin-default}, @code{bottom-margin-default}, etc.
+These are the values that result at the default paper size
+@code{a4}. For reference, with @code{a4} paper the
+@code{paper-height} is @code{297\mm} and the @code{paper-width} is
+@code{210\mm}.
-This section lists and describes a number of paper variables that
-may be altered.
+@seealso
+Notation Reference:
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables},
+@ref{Horizontal spacing paper variables,,Horizontal spacing @code{@bs{}paper} variables}.
-@menu
-* Vertical dimensions::
-* Horizontal dimensions::
-* Other layout variables::
-@end menu
+Installed Files:
+@file{ly/paper-defaults-init.ly},
+@file{scm/paper.scm}.
-@node Vertical dimensions
-@unnumberedsubsubsec Vertical dimensions
+@node Fixed vertical spacing paper variables
+@subsection Fixed vertical spacing @code{@bs{}paper} variables
+@warning{Some @code{@bs{}paper} dimensions are automatically
+scaled to the paper size, which may lead to unexpected behavior.
+See @ref{Automatic scaling to paper size}.}
-@subsubheading Fixed vertical dimensions
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
@table @code
@item paper-height
@funindex paper-height
-The height of the page. Default: the height of the current paper
-size. For details, see @ref{Paper size}.
+The height of the page, unset by default. Note that the automatic
+scaling of some vertical dimensions is not affected by this.
@item top-margin
@funindex top-margin
The margin between the top of the page and the top of the
-printable area. Default: @code{5\mm}.
+printable area. If the paper size is modified, this dimension's
+default value is scaled accordingly.
@item bottom-margin
@funindex bottom-margin
The margin between the bottom of the printable area and the bottom
-of the page. Default: @code{6\mm}.
+of the page. If the paper size is modified, this dimension's
+default value is scaled accordingly.
+
+@item ragged-bottom
+@funindex ragged-bottom
+
+If this is set to true,
+systems will be set at their natural spacing, neither compressed
+nor stretched vertically to fit the page.
+
+@item ragged-last-bottom
+@funindex ragged-last-bottom
+
+If this is set to false, then the last page,
+and the last page in each section created with a @code{\bookpart} block,
+will be vertically justified in the same way as the earlier pages.
@end table
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+Snippets:
+@rlsr{Spacing}.
+
+@knownissues
+The titles (from the @code{\header} block) are treated as a
+system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
+add space between the titles and the first system of the score.
+
+Explicitly defined paper-sizes will override any user-defined top or
+bottom margin settings.
+
-@subsubheading Flexible vertical dimensions
+@node Flexible vertical spacing paper variables
+@subsection Flexible vertical spacing @code{@bs{}paper} variables
In most cases, it is preferable for the vertical distances between
certain items (such as margins, titles, systems, and separate
(listed below) are available to fine-tune the stretching behavior
of these dimensions.
-Each of these variables is an associative list containing four
-@emph{keys}:
+Note that the @code{\paper} variables discussed in this section do
+not control the spacing of staves within individual systems.
+Within-system spacing is controlled by grob properties, with
+settings typically entered inside a @code{\score} or
+@code{\layout} block, and not inside a @code{\paper} block. See
+@ref{Flexible vertical spacing within systems}.
+
+@menu
+* Structure of flexible vertical spacing alists::
+* List of flexible vertical spacing paper variables::
+@end menu
+
+
+@node Structure of flexible vertical spacing alists
+@unnumberedsubsubsec Structure of flexible vertical spacing alists
+
+Each of the flexible vertical spacing @code{\paper} variables is
+an alist (association list) containing four @emph{keys}:
@itemize
-@item @code{padding} -- the minimum required amount of
-unobstructed vertical whitespace between two items. This can be
-thought of as the minimum height of an unobstructed (invisible)
-rectangle that extends from the leftmost to the rightmost point of
-the combined items.
-
-@item @code{space} -- the default vertical distance between the
-@emph{reference points} of the two items, when no collisions would
-result, and no stretching or compressing is in effect. The
-reference point of a title or markup is its highest point, and the
-reference point of a system is the middle line of the nearest
-staff. Values for @code{space} that are less than either
-@code{padding} or @code{minimum-distance} are not meaningful,
-since the resulting space will never be less than either
-@code{padding} or @code{minimum-distance}.
-
-@item @code{minimum-distance} -- the minimum required vertical
-distance between the reference points of the two items, when
-compressing is in effect. Values for @code{minimum-distance} that
-are less than @code{padding} are not meaningful, since the
-resulting space will never be less than @code{padding.}
-
-@item @code{stretchability} -- the stretchable space's propensity
-to stretch. If zero, the space will not stretch (unless
-collisions would result). When positive, the significance of a
-particular dimension's @code{stretchability} value lies only in
-its relation to the @code{stretchability} values of the other
-dimensions. For example, if one dimension has twice the
-@code{stretchability} of another, it will stretch twice as easily.
-Values should be non-negative and finite. The value @code{+inf.0}
-triggers a @code{programming_error} and is ignored, but
-@code{1.0e7} can be used for an almost infinitely stretchable
-spring. If unset, the default value is set to @code{space}. Note
-that the stretchable space's propensity to @emph{compress} cannot
-be directly set by the user and is equal to
-(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
+
+@item
+@code{basic-distance} -- the vertical distance, measured in
+staff-spaces, between the @emph{reference points} of the two
+items, when no collisions would result, and no stretching or
+compressing is in effect. The reference point of a (title or
+top-level) markup is its highest point, and the reference point of
+a system is the vertical center of the nearest @code{StaffSymbol}
+-- even if a non-staff line (such as a @code{Lyrics} context) is
+in the way. Values for @code{basic-distance} that are less than
+either @code{padding} or @code{minimum-distance} are not
+meaningful, since the resulting distance will never be less than
+either @code{padding} or @code{minimum-distance}.
+
+@item
+@code{minimum-distance} -- the smallest allowable vertical
+distance, measured in staff-spaces, between the reference points
+of the two items, when compressing is in effect. Values for
+@code{minimum-distance} that are less than @code{padding} are not
+meaningful, since the resulting distance will never be less than
+@code{padding.}
+
+@c TODO: explain skylines somewhere and xref to it from here.
+
+@item
+@code{padding} -- the minimum required amount of unobstructed
+vertical whitespace between the bounding boxes (or skylines) of
+the two items, measured in staff-spaces.
+
+@item
+@code{stretchability} -- a unitless measure of the dimension's
+relative propensity to stretch. If zero, the distance will not
+stretch (unless collisions would result). When positive, the
+significance of a particular dimension's @code{stretchability}
+value lies only in its relation to the @code{stretchability}
+values of the other dimensions. For example, if one dimension has
+twice the @code{stretchability} of another, it will stretch twice
+as easily. Values should be non-negative and finite. The value
+@code{+inf.0} triggers a @code{programming_error} and is ignored,
+but @code{1.0e7} can be used for an almost infinitely stretchable
+spring. If unset, the default value is set to
+@code{basic-distance}. Note that the dimension's propensity to
+@emph{compress} cannot be directly set by the user and is equal to
+(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).
@end itemize
largest of:
@itemize
-@item @code{space},
-@item @code{minimum-distance}, and
-@item @code{padding} plus the smallest distance necessary to
-eliminate collisions.
+
+@item
+@code{basic-distance},
+
+@item
+@code{minimum-distance}, and
+
+@item
+@code{padding} plus the smallest distance necessary to eliminate
+collisions.
+
@end itemize
-A single key for a flexible vertical dimension variable can be set
-like this:
+For multi-page scores with a ragged bottom on the last page, the last
+page uses the same spacing as the preceding page, provided there is
+enough space for that.
+
+Specific methods for modifying alists are discussed in
+@ref{Modifying alists}. The following example demonstrates the
+two ways these alists can be modified. The first declaration
+updates one key-value individually, and the second completely
+redefines the variable:
@example
\paper @{
- after-title-spacing #'space = #5
+ system-system-spacing.basic-distance = #8
+ score-system-spacing =
+ #'((basic-distance . 12)
+ (minimum-distance . 6)
+ (padding . 1)
+ (stretchability . 12))
@}
@end example
-Multiple keys for a single variable can be set simultaneously like
-this:
-@example
-\paper @{
- bottom-system-spacing =
- #'((padding . 1)
- (space . 1)
- (minimum-distance . 0)
- (stretchability . 5))
-@}
-@end example
+@node List of flexible vertical spacing paper variables
+@unnumberedsubsubsec List of flexible vertical spacing @code{@bs{}paper} variables
-The flexible vertical dimension variables are:
+The names of these variables follow the format
+@code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
+and @code{@var{lower}} are the items to be spaced. Each distance
+is measured between the reference points of the two items (see the
+description of the alist structure above). Note that in these
+variable names, the term @q{@code{markup}} refers to both
+@emph{title markups} (@code{bookTitleMarkup} or
+@code{scoreTitleMarkup}) and @emph{top-level markups} (see
+@ref{File structure}). All distances are measured in
+staff-spaces.
-@table @code
+Default settings are defined in @file{ly/paper-defaults-init.ly}.
+
+@c TODO: Where do headers/footers fit in? -mp
-@item after-title-spacing
-@funindex after-title-spacing
+@table @code
+@item markup-system-spacing
+@funindex markup-system-spacing
-the space between a title (or top-level markup) and the system
+the distance between a (title or top-level) markup and the system
that follows it.
-@item before-title-spacing
-@funindex before-title-spacing
+@item score-markup-spacing
+@funindex score-markup-spacing
-the space between a system and the title (or top-level markup)
-that follows it.
+the distance between the last system of a score and the (title or
+top-level) markup that follows it.
-@item between-scores-system-spacing
-@funindex between-scores-system-spacing
+@item score-system-spacing
+@funindex score-system-spacing
-the space between two systems if they are in different scores,
-with no title between them.
+the distance between the last system of a score and the first
+system of the score that follows it, when no (title or top-level)
+markup exists between them.
-@item between-system-spacing
-@funindex between-system-spacing
+@item system-system-spacing
+@funindex system-system-spacing
-the space between two systems in the same score.
+the distance between two systems in the same score.
-@item between-title-spacing
-@funindex between-title-spacing
+@item markup-markup-spacing
+@funindex markup-markup-spacing
-the space between two titles (or top-level markups).
+the distance between two (title or top-level) markups.
-@item bottom-system-spacing
-@funindex bottom-system-spacing
+@item last-bottom-spacing
+@funindex last-bottom-spacing
-the space from the last system (or the last top-level markup) to
-the bottom of the printable area (ie. the top of the bottom
+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
margin).
@item top-system-spacing
@funindex top-system-spacing
-the space from the top of the printable area (ie. the bottom of
-the top margin) to the first system. This only takes effect if
-there is no title at the top of the page (in which case
-@code{top-title-spacing} is used instead).
-
-@item top-title-spacing
-@funindex top-title-spacing
+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.
-the space from the top of the printable area (ie. the bottom of
-the top margin) to the title.
+@item top-markup-spacing
+@funindex top-markup-spacing
+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
-
-@snippets
-
-The header and footer are created by the functions
-@code{make-footer} and @code{make-header}, defined in
-@code{\paper}. The default implementations are in
-@file{ly/paper-defaults.ly} and @file{ly/titling-init.ly}.
-
-The page layout itself is done by two functions in the
-@code{\paper} block, @code{page-music-height} and
-@code{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 @code{\paper} block 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 value @w{@code{2 cm}} must be multiplied in the
-example:
-
-@example
-\paper @{
- #(define bottom-margin (* 2 cm))
-@}
-@end example
-
-
-Example:
-
-@example
-\paper @{
- paper-width = 2\cm
- top-margin = 3\cm
- bottom-margin = 3\cm
- ragged-last-bottom = ##t
-@}
-@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
-
@seealso
Notation Reference:
-@ref{Vertical spacing between systems}.
+@ref{Flexible vertical spacing within systems}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
Snippets:
@rlsr{Spacing}.
-@node Horizontal dimensions
-@unnumberedsubsubsec Horizontal dimensions
+@node Horizontal spacing paper variables
+@subsection Horizontal spacing @code{@bs{}paper} variables
+@warning{Some @code{@bs{}paper} dimensions are automatically
+scaled to the paper size, which may lead to unexpected behavior.
+See @ref{Automatic scaling to paper size}.}
-There are a few variables that determine the horizontal dimensions
-on a page:
+@menu
+* paper variables for widths and margins::
+* paper variables for two-sided mode::
+* paper variables for shifts and indents::
+@end menu
-@table @code
-@item binding-offset
-@funindex binding-offset
+@node paper variables for widths and margins
+@unnumberedsubsubsec @code{@bs{}paper} variables for widths and margins
-The amount @code{inner-margin} is increased
-to make sure nothing will be hidden by the binding.
-Works only with @code{two-sided} set to true. Default:
-@code{0}.
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
-@item horizontal-shift
-@funindex horizontal-shift
-
-The amount that all systems (including titles and system
-separators) are shifted to the right. Default: @code{0.0}.
+@table @code
-@item indent
-@funindex indent
+@item paper-width
+@funindex paper-width
-The level of indentation for the first system in a score.
-Default: @code{15\mm}.
+The width of the page, unset by default. While @code{paper-width}
+has no effect on the automatic scaling of some horizontal
+dimensions, it does influence the @code{line-width} variable. If
+both @code{paper-width} and @code{line-width} are set, then
+@code{left-margin} and @code{right-margin} will also be updated.
+Also see @code{check-consistency}.
-@item inner-margin
-@funindex inner-margin
+@item line-width
+@funindex line-width
-The margin all pages have at the inner side if they are part
-of a book. Works only with @code{two-sided} set to true.
-Default: @code{10\mm}.
+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)}.
+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{line-width}s for individual scores can be specified in the
+scores' @code{\layout} blocks. These values control the width of the
+lines produced on a score-by-score basis. If @code{line-width} is not
+specified for a score, it defaults to the paper's @code{line-width}.
+Setting a score's @code{line-width} has no effect on the paper margins.
+Staff lines, of a length determined by the score's @code{line-width},
+are left-aligned within the paper area defined by the paper's
+@code{line-width}. If the score and paper @code{line-width}s are equal,
+the staff lines will extend exactly from the left margin to the right
+margin, but if the score's @code{line-width} is greater than the
+paper's @code{line-width} the staff lines will run over into the right
+margin.
@item left-margin
@funindex left-margin
-The margin between the left edge of the page and the beginning of
-each system. Default: @code{10\mm}.
+The margin between the left edge of the page and the start of the
+staff lines in unindented systems. If the paper size is modified,
+this dimension's default value is scaled accordingly. If
+@code{left-margin} is unset, and both @code{line-width} and
+@code{right-margin} are set, then @code{left-margin} is set to
+@code{(paper-width@tie{}@minus{}@tie{}line-width@tie{}@minus{}@tie{}right-margin)}.
+If only @code{line-width} is set, then both margins are set to
+@code{((paper-width@tie{}@minus{}@tie{}line-width)@tie{}/@tie{}2)},
+and the systems are consequently centered on the page. Also see
+@code{check-consistency}.
-@item line-width
-@funindex line-width
+@item right-margin
+@funindex right-margin
-The width of music systems. Default: @code{paper-width} minus
-@code{left-margin} and @code{right-margin}.
+The margin between the right edge of the page and the end of the
+staff lines in non-ragged systems. If the paper size is modified,
+this dimension's default value is scaled accordingly. If
+@code{right-margin} is unset, and both @code{line-width} and
+@code{left-margin} are set, then @code{right-margin} is set to
+@code{(paper-width@tie{}@minus{}@tie{}line-width@tie{}@minus{}@tie{}left-margin)}.
+If only @code{line-width} is set, then both margins are set to
+@code{((paper-width@tie{}@minus{}@tie{}line-width)@tie{}/@tie{}2)},
+and the systems are consequently centered on the page. Also see
+@code{check-consistency}.
-@item outer-margin
-@funindex outer-margin
+@item check-consistency
+@funindex check-consistency
-The margin all pages have at the outer side if they are part
-of a book. Works only with @code{two-sided} set to true.
-Default: @code{20\mm}.
+If this is true (the default value), print a warning if
+@code{left-margin}, @code{line-width}, and @code{right-margin} do not
+exactly add up to @code{paper-width}, and replace each of these
+(except @code{paper-width}) with their default values (scaled to the
+paper size if necessary). If set to false, ignore any
+inconsistencies and allow systems to run off the edge of the page.
-@item paper-width
-@funindex paper-width
+@item ragged-right
+@funindex ragged-right
-The width of the page. Default: the width of the current paper
-size. For details, see @ref{Paper size}.
+If set to true, systems will not fill the line width. Instead,
+systems end at their natural horizontal length. Default:
+@code{#t} for scores with only one system, and @code{#f} for
+scores with two or more systems. This variable can also be set in
+a @code{\layout} block.
-@item right-margin
-@funindex right-margin
+@item ragged-last
+@funindex ragged-last
-The margin between the right edge of the page and the end of
-each system. Default: @code{10\mm}.
+If set to true, the last system in the score will not fill the
+line width. Instead the last system ends at its natural
+horizontal length. Default: @code{#f}. This variable can also be
+set in a @code{\layout} block.
-@item short-indent
-@funindex short-indent
+@end table
-The level of indentation for all systems in a score besides the
-first system. Default: @code{0}.
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-@end table
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-If some values are not set, defaults will be taken. Their exact
-value is adjusted, depending on the paper size specified. Currently,
-the following values are affected by this scaling:
+@knownissues
+Explicitly defined paper-sizes will override any user-defined left or
+right margin settings.
-@itemize
-@item @var{left-margin}
-@item @var{right-margin}
-@item @var{top-margin}
-@item @var{bottom-margin}
-@item @var{head-separation}
-@item @var{foot-separation}
-@item @var{indent}
-@item @var{short-indent}
-@end itemize
-The settings for @code{line-width}, @code{left-margin},
-@code{right-margin} and @code{paper-width} depend on
-each other, but they do not have to be specified
-completely.
+@node paper variables for two-sided mode
+@unnumberedsubsubsec @code{@bs{}paper} variables for two-sided mode
-@example
-\paper @{
- left-margin = 30\mm
-@}
-@end example
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
-In this example, only @code{left-margin} is set. The value for
-@code{right-margin} will remain default, @code{line-width} is
-calculated automatically.
+@table @code
-@example
-\paper @{
- line-width = 150\mm
-@}
-@end example
+@item two-sided
+@funindex two-sided
-Here @code{left-margin} and @code{right-margin} will be set
-to the same value. Therefore, @code{line-width} is subtracted
-from @code{paper-width} and divided by two. That means systems
-are centered on the page, if only @code{line-width} is
-specified.
+@cindex gutter
+@cindex binding gutter
-Some checks occur to ensure the values are set correctly.
-If the values do not match or systems would run off the page,
-a warning is printed and default values are set.
+If set to true, use @code{inner-margin}, @code{outer-margin} and
+@code{binding-offset} to determine margins depending on whether
+the page number is odd or even. This overrides @code{left-margin}
+and @code{right-margin}.
-@example
-\paper @{
- paper-width = 210\mm
- left-margin = 20\mm
- right-margin = 30\mm
- line-width = 100\mm
-@}
-@end example
+@item inner-margin
+@funindex inner-margin
-These checks can be avoided by setting @code{check-consistency}
-to false.
+The margin all pages have at the inner side if they are part of a
+book. If the paper size is modified, this dimension's default
+value is scaled accordingly. Works only with @code{two-sided} set
+to true.
-@example
-\paper @{
- paper-width = 210\mm
- left-margin = 20\mm
- line-width = 200\mm
- check-consistency = ##f
-@}
-@end example
+@item outer-margin
+@funindex outer-margin
+
+The margin all pages have at the outer side if they are part of a
+book. If the paper size is modified, this dimension's default
+value is scaled accordingly. Works only with @code{two-sided} set
+to true.
+
+@item binding-offset
+@funindex binding-offset
-@warning{If @code{paper-width} is manually set, @code{line-width},
-@code{left-margin}, @code{indent}, and @code{short-indent} may
-have to be adjusted as well.}
+The amount @code{inner-margin} is increased to make sure nothing
+will be hidden by the binding. If the paper size is modified,
+this dimension's default value is scaled accordingly. Works only
+with @code{two-sided} set to true.
+
+@end table
@seealso
-Snippets:
-@rlsr{Spacing}.
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@node Other layout variables
-@unnumberedsubsubsec Other layout variables
+@node paper variables for shifts and indents
+@unnumberedsubsubsec @code{@bs{}paper} variables for shifts and indents
-These variables can be used to adjust page layout in general.
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
@table @code
-@item auto-first-page-number
-@funindex auto-first-page-number
+@item horizontal-shift
+@funindex horizontal-shift
-The page breaking algorithm is affected by the first page number
-being odd or even. If set to true, the page breaking algorithm
-will decide whether to start with an odd or even number. This
-will result in the first page number remaining as is or being
-increased by one. Default: @code{##f}.
+@c This default value is buried in the middle of page.scm. -mp
-@ignore
+The amount that all systems (including titles and system
+separators) are shifted to the right. Default: @code{0.0\mm}.
-TODO: this variable is used, but I don't know what it does. -pm
-@item blank-after-score-page-force
-@funindex blank-after-score-page-force
+@item indent
+@funindex indent
-Default: @code{2}.
+The level of indentation for the first system in a score. If the
+paper size is modified, this dimension's default value is scaled
+accordingly. The space within @code{line-width} available for
+the first system is reduced by this amount. @code{indent} may also
+be specified in @code{\layout} blocks to set indents on a
+score-by-score basis.
-@end ignore
+@item short-indent
+@funindex short-indent
-@item blank-last-page-force
-@funindex blank-last-page-force
+The level of indentation for all systems in a score besides the
+first system. If the paper size is modified, this dimension's
+default value is scaled accordingly. The space within
+@code{line-width} available for systems other than the first is
+reduced by this amount. @code{short-indent} may also be specified in
+@code{\layout} blocks to set short indents on a score-by-score
+basis.
-The penalty for ending the score on an odd-numbered page.
-Default: @code{0}.
+@end table
-@item blank-page-force
-@funindex blank-page-force
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-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:
-@code{5}.
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@item check-consistency
-@funindex check-consistency
+Snippets:
+@rlsr{Spacing}.
-If set to true, check whether @code{left-margin}, @code{right-margin} and
-@code{line-width} fit each other. Also make sure that their combination
-does not exceed the available @code{paper-width}. Default: @code{##t}.
-@item first-page-number
-@funindex first-page-number
+@node Other paper variables
+@subsection Other @code{@bs{}paper} variables
-The value of the page number on the first page. Default:
-@code{#1}.
+@menu
+* paper variables for line breaking::
+* paper variables for page breaking::
+* paper variables for page numbering::
+* Miscellaneous paper variables::
+@end menu
+
+
+@node paper variables for line breaking
+@unnumberedsubsubsec @code{@bs{}paper} variables for line breaking
+
+@table @code
@item max-systems-per-page
@funindex max-systems-per-page
currently supported only by the @code{ly:optimal-breaking} algorithm.
Default: unset.
-@item page-breaking-between-system-spacing
-@funindex page-breaking-between-system-spacing
+@item systems-per-page
+@funindex systems-per-page
+
+The number of systems that should be placed on each page.
+This is currently supported only by the @code{ly:optimal-breaking} algorithm.
+Default: unset.
+
+@item system-count
+@funindex system-count
+
+The number of systems to be used for a score. Default: unset.
+This variable can also be set in a @code{\layout} block.
+
+@end table
+
+@seealso
+Notation Reference:
+@ref{Line breaking}.
+
+
+@node paper variables for page breaking
+@unnumberedsubsubsec @code{@bs{}paper} variables for page breaking
+
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
+
+@table @code
+
+@item page-breaking
+@funindex page-breaking
+
+The page-breaking algorithm to use. Choices are
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking},
+@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
Tricks the page breaker into thinking that
-@code{between-system-spacing} is set to something different than
+@code{system-system-spacing} is set to something different than
it really is. For example, if
-@code{page-breaking-between-system-spacing #'padding} is set to something
-substantially larger than @code{between-system-spacing #'padding}, then the
+@code{page-breaking-system-system-spacing #'padding} is set to something
+substantially larger than @code{system-system-spacing #'padding}, then the
page-breaker will put fewer systems on each page. Default: unset.
@item page-count
@funindex page-count
-The number of pages to be used for a score. Default: unset.
+The number of pages to be used for a score, unset by default.
-@item page-limit-inter-system-space
-@funindex page-limit-inter-system-space
+@end table
-If set to true, limits space between systems on a page with a lot
-of space left. Default: @code{##f}. For details, see
-@ref{Vertical spacing between systems}.
+The following variables are effective only when @code{page-breaking}
+is set to @code{ly:page-turn-breaking}. Page breaks are then chosen
+to minimize the number of page turns. Since page turns are required
+on moving from an odd-numbered page to an even-numbered one, a
+layout in which the last page is odd-numbered will usually be
+favoured. Places where page turns are preferred can be indicated
+manually by inserting @code{\allowPageTurn} or automatically by
+including the @code{Page_turn_engraver} (see @ref{Optimal page turning}).
-@item page-limit-inter-system-space-factor
-@funindex page-limit-inter-system-space-factor
+If there are insufficient choices available for making suitable page
+turns, LilyPond may insert a blank page either within a score, between
+scores (if there are two or more scores), or by ending a score on an
+even-numbered page. The values of the following three variables may
+be increased to make these actions less likely.
-The factor used by @code{page-limit-inter-system-space}. Default:
-@code{1.4}. For details, see
-@ref{Vertical spacing between systems}.
+The values are penalties, i.e., the higher the value the less likely
+will be the associated action relative to other choices.
-@item page-spacing-weight
-@funindex page-spacing-weight
+@table @code
-The relative importance of page (vertical) spacing and line
-(horizontal) spacing. High values will make page spacing more
-important. Default: @code{#10}.
+@item blank-page-penalty
+@funindex blank-page-penalty
-@item print-all-headers
-@funindex print-all-headers
+The penalty for having a blank page in the middle of a score. If
+@code{blank-page-penalty} is large and @code{ly:page-turn-breaking} is
+selected, then LilyPond will be less likely to insert a page in the
+middle of a score. Instead, it will space out the music further to
+fill the blank page and the following one. Default: 5.
+
+@item blank-last-page-penalty
+@funindex blank-last-page-penalty
+
+The penalty for ending the score on an even-numbered page. If
+@code{blank-last-page-penalty} is large and
+@code{ly:page-turn-breaking} is selected, then LilyPond will be less
+likely to produce a score in which the last page is even-numbered.
+Instead, it will adjust the spacing in order to use one page more or
+one page less. Default: 0.
+
+@item blank-after-score-page-penalty
+@funindex blank-after-score-page-penalty
+
+The penalty for having a blank page after the end of one score and
+before the next. By default, this is smaller than
+@code{blank-page-penalty}, so that blank pages after scores are
+inserted in preference to blank pages within a score. Default: 2.
+
+@end table
+
+
+@seealso
+Notation Reference:
+@ref{Page breaking},
+@ref{Optimal page breaking},
+@ref{Optimal page turning},
+@ref{Minimal 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}.
+
+
+@node paper variables for page numbering
+@unnumberedsubsubsec @code{@bs{}paper} variables for page numbering
+
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
+
+@table @code
+
+@cindex page numbers, auto-numbering
+@item auto-first-page-number
+@funindex auto-first-page-number
+
+The page breaking algorithm is affected by the first page number
+being odd or even. If set to true, the page breaking algorithm
+will decide whether to start with an odd or even number. This
+will result in the first page number remaining as is or being
+increased by one. Default: @code{#f}.
+
+@cindex page numbers, specify the first
+@item first-page-number
+@funindex first-page-number
-If set to true, this will print all headers for each \score in the
-output. Normally only the piece and opus header variables are
-printed. Default: @code{##f}.
+The value of the page number on the first page.
@item print-first-page-number
@funindex print-first-page-number
If set to true, a page number is printed on the first page.
-Default: @code{##f}.
+@cindex page numbers, suppress
@item print-page-number
@funindex print-page-number
-If set to false, page numbers are not printed. Default:
-@code{##t}.
+If set to false, page numbers are not printed.
-@item ragged-bottom
-@funindex ragged-bottom
+@cindex page numbers in roman numerals
+@item page-number-type
+@funindex page-number-type
-If set to true, systems will not spread vertically across the
-page. This does not affect the last page. Default: @code{##f}.
+The type of numerals used for page numbers. Choices include
+@code{roman-lower}, @code{roman-upper} and @code{arabic}.
+Default: @code{'arabic}.
-This should be set to true for pieces that have only two or three
-systems per page, for example orchestral scores.
+@end table
-@item ragged-last
-@funindex ragged-last
+@seealso
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-If set to true, the last system in the score will not fill the
-line width. Instead the last system ends at its natural
-horizontal length. Default: @code{##f}.
+@knownissues
+Odd page numbers are always on the right. If you want the
+music to start on page 1 there must be a blank page on the back
+of the cover page so that page 1 is on the right hand side.
-@item ragged-last-bottom
-@funindex ragged-last-bottom
-If set to false, systems will spread vertically across the last
-page. Default: @code{##t}.
+@node Miscellaneous paper variables
+@unnumberedsubsubsec Miscellaneous @code{@bs{}paper} variables
-Pieces that amply fill two pages or more should have this set to
-true.
+@table @code
-It also affects the last page of book parts, ie parts of a book created
-with @code{\bookpart} blocks.
+@item page-spacing-weight
+@funindex page-spacing-weight
-@item ragged-right
-@funindex ragged-right
+The relative importance of page (vertical) spacing and line
+(horizontal) spacing. High values will make page spacing more
+important. Default: @code{10}.
-If set to true, systems will not fill the line width. Instead,
-systems end at their natural horizontal length. Default:
-@code{##f}.
+@item print-all-headers
+@funindex print-all-headers
-If the score has only one system, the default value is @code{##t}.
+If set to true, this will print all headers for each @code{\score}
+in the output. Normally only the @code{piece} and @code{opus}
+header variables are printed. Default: @code{#f}.
@item system-separator-markup
@funindex system-separator-markup
-A markup object that is inserted between systems. This is often
-used for orchestral scores. Default: unset.
+A markup object that is inserted between systems, often used for
+orchestral scores. Default: unset. The @code{\slashSeparator}
+markup, defined in @file{ly/titling-init.ly}, is provided as a
+sensible default, for example:
-The markup command @code{\slashSeparator} is provided as a sensible
-default, for example
+@lilypond[quote,verbatim,noragged-right,line-width=30\mm]
+#(set-default-paper-size "a8")
-@lilypond[quote,ragged-right]
-#(set-default-paper-size "a6" 'landscape)
\book {
- \score {
- \relative c' { c1 \break c1 }
- }
\paper {
system-separator-markup = \slashSeparator
}
+ \header {
+ tagline = ##f
+ }
+ \score {
+ \relative { c''1 \break c1 \break c1 }
+ }
}
@end lilypond
-@item system-count
-@funindex system-count
+@end table
-The number of systems to be used for a score.
-Default: unset.
+@seealso
+Installed Files:
+@file{ly/titling-init.ly}.
-@item systems-per-page
-@funindex systems-per-page
+Snippets:
+@rlsr{Spacing}.
-The number of systems that should be placed on each page.
-This is currently supported only by the @code{ly:optimal-breaking} algorithm.
-Default: unset.
+@knownissues
+The default page header puts the page number and the @code{instrument}
+field from the @code{\header} block on a line.
-@item two-sided
-@funindex two-sided
-@cindex gutter
-@cindex binding gutter
+@node Score layout
+@section Score layout
+
+This section discusses score layout options for the @code{\layout}
+block.
+
+@menu
+* The layout block::
+* Setting the staff size::
+@end menu
+
+
+@node The layout block
+@subsection The @code{@bs{}layout} block
+
+@funindex \layout
-If set to true, use @code{inner-margin}, @code{outer-margin} and
-@code{binding-offset} to determine margins depending on whether
-the page number is odd or even. This overrides @code{left-margin}
-and @code{right-margin}. Default: @code{##f}.
+While the @code{\paper} block contains settings that relate to the
+page formatting of the whole document, the @code{\layout} block
+contains settings for score-specific layout. To set score layout
+options globally, enter them in a toplevel @code{\layout} block.
+To set layout options for an individual score, enter them in a
+@code{\layout} block inside the @code{\score} block, after the
+music. Settings that can appear in a @code{\layout} block
+include:
-@end table
+@itemize
+@item the @code{layout-set-staff-size} scheme function,
+@item context modifications in @code{\context} blocks, and
+@item @code{\paper} variables that affect score layout.
+@end itemize
+The @code{layout-set-staff-size} function is discussed in the next
+section, @ref{Setting the staff size}. Context modifications are
+discussed in a separate chapter; see
+@ref{Modifying context plug-ins} and
+@ref{Changing context default settings}.
-@seealso
-Snippets:
-@rlsr{Spacing}.
+The @code{\paper} variables that can appear in a @code{\layout}
+block, with default values taken from the @code{\paper} block are:
+@itemize
-@knownissues
+@item
+@code{line-width}, @code{ragged-right} and @code{ragged-last}
+(see @ref{paper variables for widths and margins,,@code{@bs{}paper} variables for widths and margins})
-The default page header puts the page number and the @code{instrument}
-field from the @code{\header} block on a line.
+@item
+@code{indent} and @code{short-indent}
+(see @ref{paper variables for shifts and indents,,@code{@bs{}paper} variables for shifts and indents})
-The titles (from the @code{\header@{@}} section) are treated as a
-system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
-add space between the titles and the first system of the score.
+@item
+@code{system-count}
+(see @ref{paper variables for line breaking,,@code{@bs{}paper} variables for line breaking})
+@end itemize
-@node Music layout
-@section Music layout
+Here is an example @code{\layout} block:
-@menu
-* Setting the staff size::
-* Score layout::
-@end menu
+@example
+\layout @{
+ indent = 2\cm
+ \context @{
+ \StaffGroup
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #8
+ @}
+ \context @{
+ \Voice
+ \override TextScript.padding = #1
+ \override Glissando.thickness = #3
+ @}
+@}
+@end example
+Multiple @code{\layout} blocks can be entered as toplevel expressions.
+This can, for example, be useful if different settings are stored in
+separate files and included optionally. Internally, when
+a @code{\layout} block is evaluated, a copy of the current
+@code{\layout} configuration is made, then any changes defined within
+the block are applied and the result is saved as the new current
+configuration. From the user's perspective the @code{\layout} blocks
+are combined, but in conflicting situations (when the same property
+is changed in different blocks) the later definitions take precedence.
-@node Setting the staff size
-@subsection Setting the staff size
+For example, if this block:
-@cindex font size, setting
-@cindex staff size, setting
-@funindex layout file
+@example
+\layout @{
+ \context @{
+ \Voice
+ \override TextScript.color = #magenta
+ \override Glissando.thickness = #1.5
+ @}
+@}
+@end example
+
+is placed after the one from the preceding example the @code{'padding}
+and @code{'color} overrides for @code{TextScript} are combined, but
+the later @code{'thickness} override for @code{Glissando} replaces
+(or hides) the earlier one.
-The default @strong{staff size} is set to 20 points.
-This may be changed in two ways:
+@code{\layout} blocks may be assigned to variables for reuse later,
+but the way this works is slightly but significantly different from
+writing them literally.
-To set the staff size globally for all scores in a file (or
-in a @code{book} block, to be precise), use @code{set-global-staff-size}.
+If a variable is defined like this:
@example
-#(set-global-staff-size 14)
+layoutVariable = \layout @{
+ \context @{
+ \Voice
+ \override NoteHead.font-size = #4
+ @}
+@}
@end example
-@noindent
-This sets the global default size to 14pt staff height and scales all
-fonts accordingly.
+it will hold the current @code{\layout} configuration with the
+@code{NoteHead.font-size} override added, but this combination
+is @emph{not} saved as the new current configuration. Be aware
+that the @q{current configuration} is read when the variable is
+defined and not when it is used, so the content of the variable
+is dependent on its position in the source.
+
+The variable can then be used inside another @code{\layout} block,
+for example:
-To set the staff size individually for each score, use
@example
-\score@{
- ...
- \layout@{
- #(layout-set-staff-size 15)
+\layout @{
+ \layoutVariable
+ \context @{
+ \Voice
+ \override NoteHead.color = #red
@}
@}
@end example
-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:
+A @code{\layout} block containing a variable, as in the example above,
+does @emph{not} copy the current configuration but instead uses the
+content of @code{\layoutVariable} as the base configuration for the
+further additions. This means that any changes defined between the
+definition and the use of the variable are lost.
-@quotation
-@multitable @columnfractions .15 .2 .22 .2
+If @code{layoutVariable} is defined (or @code{\include}d) immediately
+before being used, its content is just the current configuration plus
+the overrides defined within it. So in the example above showing the
+use of @code{\layoutVariable} the final @code{\layout} block would
+consist of:
+
+@example
+ TextScript.padding = #1
+ TextScript.color = #magenta
+ Glissando.thickness = #1.5
+ NoteHead.font-size = #4
+ NoteHead.color = #red
+@end example
-@item @b{font name}
-@tab @b{staff height (pt)}
-@tab @b{staff height (mm)}
-@tab @b{use}
-
-@item feta11
-@tab 11.22
-@tab 3.9
-@tab pocket scores
-
-@item feta13
-@tab 12.60
-@tab 4.4
-@tab
-
-@item feta14
-@tab 14.14
-@tab 5.0
-@tab
-
-@item feta16
-@tab 15.87
-@tab 5.6
-@tab
-
-@item feta18
-@tab 17.82
-@tab 6.3
-@tab song books
-
-@item feta20
-@tab 20
-@tab 7.0
-@tab standard parts
-
-@item feta23
-@tab 22.45
-@tab 7.9
-@tab
-
-@item feta26
-@tab 25.2
-@tab 8.9
-@tab
-@c modern rental material?
+plus the @code{indent} and the @code{StaffGrouper} overrides.
-@end multitable
-@end quotation
+But if the variable had already been defined before the first
+@code{\layout} block the current configuration would now contain
+only
-These fonts are available in any sizes. The context property
-@code{fontSize} and the layout property @code{staff-space} (in
-@rinternals{StaffSymbol}) can be used to tune the size for individual
-staves. The sizes of individual staves are relative to the global size.
+@example
+ NoteHead.font-size = #4 % (written in the variable definition)
+ NoteHead.color = #red % (added after the use of the variable)
+@end example
+If carefully planned, @code{\layout} variables can be a valuable tool
+to structure the layout design of sources, and also to reset the
+@code{\layout} configuration to a known state.
@seealso
Notation Reference:
-@ref{Selecting notation font size}.
+@ref{Changing context default settings}.
Snippets:
@rlsr{Spacing}.
-@knownissues
+@node Setting the staff size
+@subsection Setting the staff size
-@code{layout-set-staff-size} does not change the distance between the
-staff lines.
+@cindex font size, setting
+@cindex staff size, setting
+@funindex layout file
+@funindex magnification->font-size
+@funindex magstep
+@funindex set-global-staff-size
+@funindex layout-set-staff-size
+The default @strong{staff size} is 20 points, which corresponds to
+a staff height of 7.03mm (one point is equal to 100/7227 of an
+inch, or 2540/7227 mm). The staff size may be changed in three
+ways:
-@node Score layout
-@subsection Score layout
+@enumerate
-@funindex \layout
+@item
+To set the staff size globally for all scores in a file (or in a
+@code{\book} block, to be precise), use
+@code{set-global-staff-size}:
+
+@example
+#(set-global-staff-size 14)
+@end example
+
+@noindent
+The above example sets the global default staff size to 14pt
+(4.92mm) and scales all fonts accordingly.
-While @code{\paper} contains settings that relate to the page formatting
-of the whole document, @code{\layout} contains settings for score-specific
-layout.
+@item
+To set the staff size for a single score within a book, use
+@code{layout-set-staff-size} inside that score's @code{\layout}
+block:
@example
-\layout @{
- indent = 2.0\cm
- \context @{ \Staff
- \override VerticalAxisGroup #'minimum-Y-extent = #'(-6 . 6)
- @}
- \context @{ \Voice
- \override TextScript #'padding = #1.0
- \override Glissando #'thickness = #3
+\score @{
+ @dots{}
+ \layout @{
+ #(layout-set-staff-size 14)
@}
@}
@end example
+@item
+To set the staff size for a single staff within a system, use the
+@code{\magnifyStaff} command. For example, traditionally engraved
+chamber music scores with piano often used 7mm piano staves while
+the other staves were typically between 3/5 and 5/7 as large
+(between 60% and 71%). To achieve the 5/7 proportion, use:
+
+@example
+\score @{
+ <<
+ \new Staff \with @{
+ \magnifyStaff #5/7
+ @} @{ @dots{} @}
+ \new PianoStaff @{ @dots{} @}
+ >>
+@}
+@end example
+
+If you happen to know which @code{fontSize} you wish to use, you
+could use the following form:
+
+@example
+\score @{
+ <<
+ \new Staff \with @{
+ \magnifyStaff #(magstep -3)
+ @} @{ @dots{} @}
+ \new PianoStaff @{ @dots{} @}
+ >>
+@}
+@end example
+
+To emulate the look of traditional engraving, it is best to avoid
+reducing the thickness of the staff lines.
+
+@end enumerate
+
+
+@subheading Automatic font weight at different sizes
+
+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}
+@item feta11 @tab 11.22 @tab 3.9 @tab pocket scores
+@item feta13 @tab 12.60 @tab 4.4 @tab
+@item feta14 @tab 14.14 @tab 5.0 @tab
+@item feta16 @tab 15.87 @tab 5.6 @tab
+@item feta18 @tab 17.82 @tab 6.3 @tab song books
+@item feta20 @tab 20 @tab 7.0 @tab standard parts
+@item feta23 @tab 22.45 @tab 7.9 @tab
+@item feta26 @tab 25.2 @tab 8.9 @tab @c modern rental material?
+@end multitable
@seealso
Notation Reference:
-@ref{Changing context default settings}.
+@ref{Selecting notation font size},
+@ref{The Emmentaler font}.
Snippets:
@rlsr{Spacing}.
+@knownissues
+@code{layout-set-staff-size} does not change the distance between the
+staff lines.
+
@node Breaks
@section Breaks
@menu
* Line breaking::
* Page breaking::
-* Optimal page breaking::
-* Optimal page turning::
-* Minimal page breaking::
-* Explicit breaks::
-* Using an extra voice for breaks::
@end menu
@node Line breaking
@subsection Line breaking
-@cindex line breaks
+@funindex \break
+@funindex \noBreak
+@funindex \autoBreaksOff
+@funindex \autoBreaksOn
+@funindex \autoLineBreaksOff
+@funindex \autoLineBreaksOn
+@cindex manual line breaks
@cindex breaking lines
-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.
+Line breaks are normally determined automatically. They are
+chosen so that lines look neither cramped nor loose, and
+consecutive lines have similar density.
+
+To manually force a line break at a bar line, use the
+@code{\break} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ c4 c c c | \break
+ c4 c c c |
+}
+@end lilypond
+
+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
+ c |
+ c4 c c c |
+}
+@end lilypond
+
+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 {
+ \remove "Forbid_line_break_engraver"
+} \relative {
+ <<
+ { c''2. \tuplet 3/2 { c4 c c } c2. | }
+ { s1 | \break s1 | }
+ >>
+}
+@end lilypond
+
+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'' {
+ \override Beam.breakable = ##t
+ c2. c8[ c | \break
+ c8 c] c2. |
+}
+@end lilypond
+
+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
+lying between @code{\autoLineBreaksOff} and @code{\autoLineBreaksOn}
+commands. If automatic page breaks should also be prevented, the
+commands @code{\autoBreaksOff} and @code{\autoBreaksOn} should be
+used. Manual breaks are unaffected by these commands. Note that
+inhibiting automatic line breaks may cause music to run over the
+right margin if it cannot all be contained within one line.
+
+Automatic line breaks (but not page breaks) may be enabled at single
+bar lines by using @code{\once \autoLineBreaksOn} at a bar line.
+This identifies a permitted rather than a forced line break.
The most basic settings influencing line spacing are @code{indent}
and @code{line-width}. They are set in the @code{\layout} block.
@example
\layout @{
-indent = #0
-line-width = #150
-ragged-last = ##t
+ indent = 0\mm
+ line-width = 150\mm
+ ragged-last = ##t
@}
@end example
-
-
@cindex regular line breaks
@cindex four bar music.
-For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}. For example, this would
-cause the following 28 measures (assuming 4/4 time) to be broken
-every 4 measures, and only there:
+For line breaks at regular intervals use @code{\break} separated
+by skips and repeated with @code{\repeat}. For example, this
+would cause the following 28 measures (assuming 4/4 time) to be
+broken every 4 measures, and only there:
@example
-<< \repeat unfold 7 @{
- s1 \noBreak s1 \noBreak
- s1 \noBreak s1 \break @}
- @emph{the real music}
+<<
+ \repeat unfold 7 @{
+ s1 \noBreak s1 \noBreak
+ s1 \noBreak s1 \break
+ @}
+ @{ @var{the actual music@dots{}} @}
>>
@end example
-@c TODO Check this
-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
-@rlsr{Spacing}.
-
@predefined
-@funindex \break
@code{\break},
-@funindex \noBreak
-@code{\noBreak}.
+@code{\noBreak},
+@code{\autoBreaksOff},
+@code{\autoBreaksOn},
+@code{\autoLineBreaksOff},
+@code{\autoLineBreaksOn}.
@endpredefined
+@snippets
+
+@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
+{using-an-extra-voice-for-breaks.ly}
@seealso
-Internals Reference:
-@rinternals{LineBreakEvent}.
+Notation Reference:
+@ref{paper variables for line breaking}
+@ref{The layout block}.
Snippets:
@rlsr{Spacing}.
+Internals Reference:
+@rinternals{LineBreakEvent}.
@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
+Placing @code{\autoLineBreaksOff} or @code{\autoBreaksOff} before
+any music will cause error messages to appear. Always place these
+commands after some music.
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-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}.
-Note that manually forced line breaks have to be added in parallel
-with the music.
+@node Page breaking
+@subsection Page breaking
-@lilypond[quote,ragged-right,verbatim]
-\new Voice \with {
- \remove Forbid_line_break_engraver
-} {
- c4 c2 << c2 {s4 \break } >> % now the break is allowed
- c2 c4
-}
-@end lilypond
+This section describes the different page breaking methods, and
+how to modify them.
-Similarly, line breaks are normally forbidden when beams cross bar
-lines. This behavior can be changed by setting
-@code{\override Beam #'breakable = ##t}.
+@menu
+* 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::
+@end menu
-@node Page breaking
-@subsection Page breaking
+@node Manual page breaking
+@unnumberedsubsubsec Manual page breaking
+
+@funindex \pageBreak
+@funindex \noPageBreak
+@funindex \autoPageBreaksOn
+@funindex \autoPageBreaksOff
+@cindex page breaking, manual
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.
+@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 at that bar line. Of course, the
+@code{\pageBreak} command also forces a line break.
The @code{\pageBreak} and @code{\noPageBreak} commands may also be
inserted at top-level, between scores and top-level markups.
-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 @ref{Vertical spacing}.
+Within a score, automatic page breaks are prevented within music
+lying between @code{\autoPageBreaksOff} and @code{\autoPageBreaksOn}
+commands. Manual page breaks are unaffected by these commands.
-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:
+There are also analogous settings to @code{ragged-right} and
+@code{ragged-last} which have the same effect on vertical spacing.
+If @code{ragged-bottom} is set to @code{#t} the systems will not
+be justified vertically. When @code{ragged-last-bottom} is set
+to @code{#t}, as it is by default, empty space is allowed at the
+bottom of the final page (or the final page in each
+@code{\bookpart}). See
+@ref{Fixed vertical spacing paper variables,,Fixed vertical spacing @code{@bs{}paper} variables}.
+
+Page breaks are computed by the @code{page-breaking} function.
+LilyPond provides several algorithms for computing page breaks,
+including @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@{
- #(define page-breaking ly:page-turn-breaking)
+\paper @{
+ page-breaking = #ly:page-turn-breaking
@}
@end example
@funindex \bookpart
-When a book has many scores and pages, the page breaking problem may be
-difficult to solve, requiring large processing time and memory. To ease
-the page breaking process, @code{\bookpart} blocks are used to divide
-the book into several parts: the page breaking occurs separately on each
-part. Different page breaking functions may also be used in different
-book parts.
+When a book has many scores and pages, the page breaking problem
+may be difficult to solve, requiring large processing time and
+memory. To ease the page breaking process, @code{\bookpart}
+blocks are used to divide the book into several parts: the page
+breaking occurs separately on each part. Different page breaking
+functions may also be used in different book parts.
@example
\bookpart @{
\paper @{
%% In a part consisting mostly of text,
%% ly:minimal-breaking may be preferred
- #(define page-breaking ly:minimal-breaking)
+ page-breaking = #ly:minimal-breaking
@}
\markup @{ @dots{} @}
@dots{}
@predefined
-@funindex \pageBreak
@code{\pageBreak},
-@funindex \noPageBreak
-@code{\noPageBreak}.
+@code{\noPageBreak},
+@code{\autoPageBreaksOn},
+@code{\autoPageBreaksOff}.
@endpredefined
-
@seealso
+Notation Reference:
+@ref{paper variables for page breaking}.
+
Snippets:
@rlsr{Spacing}.
+@knownissues
+
+The @code{\once} prefix is ineffective with @code{\autoPageBreaksOn}
+and @code{\autoPageBreaksOff}. If auto page breaking is off and is
+then turned on to permit a page break, it must remain on for a few
+bars (the precise number of bars depends on the score) before being
+turned off, else the opportunity to break the page will not be taken.
@node Optimal page breaking
-@subsection Optimal page breaking
+@unnumberedsubsubsec Optimal page breaking
@funindex ly:optimal-breaking
-The @code{ly:optimal-breaking} function is LilyPond's default method of
-determining page breaks. It attempts to find a page breaking that minimizes
-cramping and stretching, both horizontally and vertically. Unlike
-@code{ly:page-turn-breaking}, it has no concept of page turns.
+The @code{ly:optimal-breaking} function is LilyPond's default
+method of determining page breaks. It attempts to find a page
+breaking that minimizes cramping and stretching, both horizontally
+and vertically. Unlike @code{ly:page-turn-breaking}, it has no
+concept of page turns.
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
+@node Minimal page breaking
+@unnumberedsubsubsec 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 @{
+ page-breaking = #ly:minimal-breaking
+@}
+@end example
@seealso
Snippets:
@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
+
+@funindex ly:one-line-breaking
+
+The @code{ly:one-line-breaking} function is a special-purpose
+page breaking algorithm that puts each score on its own page, and
+on a single line. No titles or margins are typeset; only the score is
+displayed.
+
+The page width is adjusted so that the longest score fits on
+one line. In particular, @code{paper-width}, @code{line-width}
+and @code{indent} variables in the @code{\paper} block are ignored,
+although @code{left-margin} and @code{right-margin} are still honored.
+The height of the page is left unmodified.
+
+
+@node One-line-auto-height page breaking
+@unnumberedsubsubsec One-line-auto-height page breaking
+
+@funindex ly:one-line-auto-height-breaking
+
+The @code{ly:one-line-auto-height-breaking} function works just like
+@code{ly:one-line-breaking} except the page height is automatically
+modified to fit the height of the music. Specifically, the
+@code{paper-height} variable in the @code{\paper} block is set so that
+it spans the height of the tallest score plus the @code{top-margin} and
+@code{bottom-margin}.
+
+Note that the @code{top-system-spacing} setting will affect the
+vertical position of the music. Set it to @code{##f} in a paper block
+to simply place the music between the top and bottom margins.
+
+
@node Optimal page turning
-@subsection Optimal page turning
+@unnumberedsubsubsec Optimal page turning
@funindex ly:page-turn-breaking
-Often it is necessary to find a page breaking configuration so that there is
-a rest at the end of every second page. This way, the musician can turn the
-page without having to miss notes. The @code{ly:page-turn-breaking} function
-attempts to find a page breaking minimizing cramping and stretching, but with
-the additional restriction that it is only allowed to introduce page turns
-in specified places.
-
-There are two steps to using this page breaking function. First, you
-must enable it in the @code{\paper} block, 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
-potential page turn manually, by inserting @code{\allowPageTurn} into your
-input file at the appropriate places.
-
-If this is too tedious, you can add a @code{Page_turn_engraver} to a Staff or
-Voice context. The @code{Page_turn_engraver} will scan the context for
-sections without notes (note that it does not scan for rests; it scans for
-the absence of notes. This is so that single-staff polyphony with rests in one
-of the parts does not throw off the @code{Page_turn_engraver}). When it finds
-a sufficiently long section without notes, the @code{Page_turn_engraver} will
-insert an @code{\allowPageTurn} at the final 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.
+Often it is necessary to find a page breaking configuration so
+that there is a rest at the end of every second page. This way,
+the musician can turn the page without having to miss notes. The
+@code{ly:page-turn-breaking} function attempts to find a page
+breaking minimizing cramping and stretching, but with the
+additional restriction that it is only allowed to introduce page
+turns in specified places.
+
+There are two steps to using this page breaking function. First,
+you must enable it in the @code{\paper} block, 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 potential page turn manually, by inserting
+@code{\allowPageTurn} into your input file at the appropriate
+places.
+
+If this is too tedious, you can add a @code{Page_turn_engraver} to
+a Staff or Voice context. The @code{Page_turn_engraver} will scan
+the context for sections without notes (note that it does not scan
+for rests; it scans for the absence of notes. This is so that
+single-staff polyphony with rests in one of the parts does not
+throw off the @code{Page_turn_engraver}). When it finds a
+sufficiently long section without notes, the
+@code{Page_turn_engraver} will insert an @code{\allowPageTurn} at
+the final 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
-to disable page turns, you can set it to something very large.
+@code{minimumPageTurnLength} to determine how long a note-free
+section must be before a page turn is considered. The default
+value for @code{minimumPageTurnLength} is
+@code{(ly:make-moment 1/1)}. If you want to disable page turns,
+set it to something @q{very large}.
@example
\new Staff \with @{ \consists "Page_turn_engraver" @}
a4 b c d |
R1 | % a page turn will be allowed here
a4 b c d |
- \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
+ \set Staff.minimumPageTurnLength = #(ly:make-moment 5/2)
R1 | % a page turn will not be allowed here
a4 b r2 |
R1*2 | % a page turn will be allowed here
@end example
@funindex minimumRepeatLengthForPageTurn
-The @code{Page_turn_engraver} detects volta repeats. It will only allow a page
-turn during the repeat if there is enough time at the beginning and end of the
-repeat to turn the page back. The @code{Page_turn_engraver} can also disable
-page turns if the repeat is very short. If you set the context property
-@code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
-only allow turns in repeats whose duration is longer than this value.
-The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
-@code{\allowPageTurn}, may also be used at top-level, between scores and
-top-level markups.
+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
@code{\allowPageTurn}.
@endpredefined
+@seealso
+Notation Reference:
+@ref{paper variables for line breaking}.
+
+Snippets:
+@rlsr{Spacing}.
+
+@knownissues
+Use only one @code{Page_turn_engraver} per score. If there are
+more, they will interfere with each other.
+
@seealso
+Notation Reference:
+@ref{Vertical spacing}.
+
Snippets:
@rlsr{Spacing}.
-@knownissues
+@node Vertical spacing
+@section Vertical spacing
+
+@cindex vertical spacing
+@cindex spacing, vertical
+
+Vertical spacing is controlled by three things: the amount of
+space available (i.e., paper size and margins), the amount of
+space between systems, and the amount of space between staves
+inside a system.
+
+@menu
+* Flexible vertical spacing within systems::
+* Explicit staff and system positioning::
+* Vertical collision avoidance::
+@end menu
+
+
+@node Flexible vertical spacing within systems
+@subsection Flexible vertical spacing within systems
-There should only be one @code{Page_turn_engraver} in a score. If there is more
-than one, they will interfere with each other.
+@cindex distance between staves
+@cindex staff distance
+@cindex space between staves
+@cindex space inside systems
+Three separate mechanisms control the flexible vertical spacing
+within systems, one for each of the following categories:
+
+@itemize
+
+@item
+@emph{ungrouped staves},
-@node Minimal page breaking
-@subsection Minimal page breaking
+@item
+@emph{grouped staves} (staves within a staff-group such as
+@code{ChoirStaff}, etc.), and
-@funindex ly:minimal-breaking
+@item
+@emph{non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
+etc.).
-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:
+@end itemize
-@example
-\paper @{
- #(define page-breaking ly:minimal-breaking)
-@}
-@end example
+@c TODO: Clarify this. This almost implies that non-staff lines
+@c have NO effect on the spacing between staves. -mp
+The height of each system is determined in two steps. First, all
+of the staves are spaced according to the amount of space
+available. Then, the non-staff lines are distributed between the
+staves.
-@seealso
-Snippets:
-@rlsr{Spacing}.
+Note that the spacing mechanisms discussed in this section only
+control the vertical spacing of staves and non-staff lines within
+individual systems. The vertical spacing between separate
+systems, scores, markups, and margins is controlled by
+@code{\paper} variables, which are discussed in
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables}.
+@menu
+* Within-system spacing properties::
+* Spacing of ungrouped staves::
+* Spacing of grouped staves::
+* Spacing of non-staff lines::
+@end menu
-@node Explicit breaks
-@subsection Explicit breaks
-Lily sometimes rejects explicit @code{\break} and @code{\pageBreak}
-commands. There are two commands to override this behavior:
+@node Within-system spacing properties
+@unnumberedsubsubsec Within-system spacing properties
+
+@funindex staff-affinity
+@funindex staffgroup-staff-spacing
+@funindex staff-staff-spacing
+@funindex nonstaff-unrelatedstaff-spacing
+@funindex nonstaff-relatedstaff-spacing
+@funindex nonstaff-nonstaff-spacing
+@funindex default-staff-staff-spacing
+@funindex minimum-Y-extent
+@funindex extra-offset
+@funindex self-alignment-X
+@funindex X-offset
+@funindex VerticalAxisGroup
+
+The within-system vertical spacing mechanisms are controlled by
+two sets of grob properties. The first set is associated with the
+@code{VerticalAxisGroup} grob, which is created by all staves and
+non-staff lines. The second set is associated with the
+@code{StaffGrouper} grob, which can be created by staff-groups,
+but only if explicitly called. These properties are described
+individually at the end of this section.
+
+The names of these properties (except for @code{staff-affinity})
+follow the format @code{@var{item1}-@var{item2}-spacing}, where
+@code{@var{item1}} and @code{@var{item2}} are the items to be
+spaced. Note that @code{@var{item2}} is not necessarily below
+@code{@var{item1}}; for example,
+@code{nonstaff-relatedstaff-spacing} will measure upwards from the
+non-staff line if @code{staff-affinity} is @code{UP}.
+
+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
+@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:
+
+@multitable {Non-staff line} {Reference point}
+@headitem Non-staff line @tab Reference point
+@item @code{ChordNames} @tab baseline
+@item @code{NoteNames} @tab baseline
+@item @code{Lyrics} @tab baseline
+@item @code{Dynamics} @tab mid-height of @q{m}
+@item @code{FiguredBass} @tab highest point
+@item @code{FretBoards} @tab top line
+@end multitable
-@example
-\override NonMusicalPaperColumn #'line-break-permission = ##f
-\override NonMusicalPaperColumn #'page-break-permission = ##f
-@end example
+In the following image, horizontal lines indicate the positions
+of these reference points:
-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 overridden to false, Lily will insert
-page breaks at explicit @code{\pageBreak} commands and nowhere else.
+@lilypond[quote,noragged-right,line-width=110\mm]
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
-@lilypond[quote,verbatim]
-\paper {
- indent = #0
- ragged-right = ##t
- ragged-bottom = ##t
+alignToZero = \with {
+ \override VerticalAxisGroup.nonstaff-relatedstaff-spacing = #zero-space
+ \override VerticalAxisGroup.nonstaff-nonstaff-spacing = #zero-space
+ \override VerticalAxisGroup.staff-affinity = #DOWN
+ \remove Text_engraver % avoid having two
+ \consists Text_engraver
+}
+lowerCaseChords = \with {
+ chordNameLowercaseMinor = ##t
}
+labelContext =
+#(define-music-function
+ (context)
+ (string?)
+ #{ s1*0^\markup { \upright {\typewriter #context } } #})
-\score {
- \new Staff {
- \repeat unfold 2 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 8 { c'8 c'8 c'8 c'8 } \pageBreak
- \repeat unfold 8 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 6 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 4 { c'8 c'8 c'8 c'8 } \break
- \repeat unfold 2 { c'8 c'8 c'8 c'8 }
- }
- \layout {
- \context {
- \Score
- \override NonMusicalPaperColumn #'line-break-permission = ##f
- \override NonMusicalPaperColumn #'page-break-permission = ##f
- }
+\layout {
+ \context { \Dynamics \alignToZero }
+ \context { \FiguredBass \alignToZero }
+ \context { \Lyrics \alignToZero }
+ \context { \NoteNames \alignToZero }
+ \context { \ChordNames \alignToZero \lowerCaseChords }
+ \context { \FretBoards \alignToZero }
+ \context { \Score
+ \omit BarLine
+ \override DynamicText.self-alignment-X = #-1
+ \override FretBoard.X-offset = #1.75
+ \override InstrumentName.minimum-Y-extent = #'(-1 . 2)
+ \textLengthOn
+ \omit TimeSignature
}
}
-@end lilypond
+%% These contexts have reference points at the baseline:
+%% ChordNames, NoteNames, and Lyrics
+<<
+ \new ChordNames { \chords { \labelContext "ChordNames" g1:m } }
+ \new NoteNames { s1 |\labelContext "NoteNames" g1 | }
+ \new Lyrics { \lyrics { \skip 1*2 | \labelContext "Lyrics" ghijk1 | } }
+ \new RhythmicStaff \with { instrumentName = #"baseline " } s1*3
+>>
+
+%% The reference point for Dynamics is the midline of 'm' in the font
+<<
+ \new Dynamics { \labelContext "Dynamics" s1\mp s\fp }
+ \new RhythmicStaff \with { instrumentName = #"mid-height " } s1*3
+>>
-@seealso
-Snippets:
-@rlsr{Spacing}.
+%% The reference point for FiguredBass is its highest point
+<<
+ \new FiguredBass { \labelContext "FiguredBass" \figuremode { <6 5>1 } }
+ \new RhythmicStaff \with { instrumentName = #"highest point " } s1
+>>
+%% The reference point for FretBoards is the top line
+\include "predefined-guitar-fretboards.ly"
+<<
+ \new FretBoards { \labelContext "FretBoards" \chordmode { e1 } }
+ \new RhythmicStaff \with { instrumentName = #"top line " } s1
+>>
+@end lilypond
-@node Using an extra voice for breaks
-@subsection Using an extra voice for breaks
+Each of the vertical spacing grob properties (except
+@code{staff-affinity}) uses the same alist structure as the
+@code{\paper} spacing variables discussed in
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables}.
+Specific methods
+for modifying alists are discussed in @ref{Modifying alists}.
+Grob properties should be adjusted with an @code{\override} inside
+a @code{\score} or @code{\layout} block, and not inside a
+@code{\paper} block.
-Line- and page-breaking information usually appears within note entry directly.
+The following example demonstrates the two ways these alists can
+be modified. The first declaration updates one key-value
+individually, and the second completely re-defines the property:
@example
-\score @{
- \new Staff @{
- \repeat unfold 2 @{ c'4 c'4 c'4 c'4 @}
- \break
- \repeat unfold 3 @{ c'4 c'4 c'4 c'4 @}
+\new Staff \with @{
+ \override VerticalAxisGroup.default-staff-staff-spacing.basic-distance = #10
+@} @{ @dots{} @}
+
+\new Staff \with @{
+ \override VerticalAxisGroup.default-staff-staff-spacing =
+ #'((basic-distance . 10)
+ (minimum-distance . 9)
+ (padding . 1)
+ (stretchability . 10))
+@} @{ @dots{} @}
+@end example
+
+To change any spacing settings globally, put them in the
+@code{\layout} block:
+
+@example
+\layout @{
+ \context @{
+ \Staff
+ \override VerticalAxisGroup.default-staff-staff-spacing.basic-distance = #10
@}
@}
@end example
-This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
-music entry with information that specifies how music should lay out
-on the page. You can keep music entry and line- and page-breaking
-information in two separate places by introducing an extra voice to
-contain the breaks. This extra voice
-contains only skips together with @code{\break}, @code{pageBreak} and other
-breaking layout information.
+Standard settings for the vertical spacing grob properties are
+listed in @rinternals{VerticalAxisGroup} and
+@rinternals{StaffGrouper}. Default overrides for specific types
+of non-staff lines are listed in the relevant context descriptions
+in @rinternals{Contexts}.
-@lilypond[quote,verbatim]
-\score {
- \new Staff <<
- \new Voice {
- s1 * 2 \break
- s1 * 3 \break
- s1 * 6 \break
- s1 * 5 \break
- }
- \new Voice {
- \repeat unfold 2 { c'4 c'4 c'4 c'4 }
- \repeat unfold 3 { c'4 c'4 c'4 c'4 }
- \repeat unfold 6 { c'4 c'4 c'4 c'4 }
- \repeat unfold 5 { c'4 c'4 c'4 c'4 }
- }
- >>
-}
-@end lilypond
-This pattern becomes especially helpful when overriding
-@code{line-break-system-details} and the other useful but long properties of
-@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
+@subsubheading Properties of the @code{VerticalAxisGroup} grob
-@lilypond[quote,verbatim]
-\score {
- \new Staff <<
- \new Voice {
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
- s1 * 2 \break
-
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 35))
- s1 * 3 \break
-
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 70))
- s1 * 6 \break
-
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 105))
- s1 * 5 \break
- }
- \new Voice {
- \repeat unfold 2 { c'4 c'4 c'4 c'4 }
- \repeat unfold 3 { c'4 c'4 c'4 c'4 }
- \repeat unfold 6 { c'4 c'4 c'4 c'4 }
- \repeat unfold 5 { c'4 c'4 c'4 c'4 }
- }
- >>
-}
-@end lilypond
+@code{VerticalAxisGroup} properties are typically adjusted with an
+@code{\override} at the @code{Staff} level (or equivalent).
+@table @code
+@item staff-staff-spacing
+
+Used to determine the distance between the current staff and the
+staff just below it in the same system, even if one or more
+non-staff lines (such as @code{Lyrics}) are placed between the two
+staves. Does not apply to the bottom staff of a system.
+
+Initially, the @code{staff-staff-spacing} of a
+@code{VerticalAxisGroup} is a Scheme function that applies the
+properties of the @code{StaffGrouper} if the staff is part of a
+group, or the @code{default-staff-staff-spacing} of the staff
+otherwise. This allows staves to be spaced differently when they
+are grouped. For uniform spacing regardless of grouping, this
+function may be replaced by a flexible-spacing alist, using the
+complete-redefinition form of override shown above.
+
+@item default-staff-staff-spacing
+A flexible-spacing alist defining the @code{staff-staff-spacing} used for
+ungrouped staves, unless @code{staff-staff-spacing} has been explicitly
+set with an @code{\override}.
+
+@item staff-affinity
+The direction of the staff to use for spacing the current
+non-staff line. Choices are @code{UP}, @code{DOWN}, and
+@code{CENTER}. If @code{CENTER}, the non-staff line will be
+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
+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
+@code{staff-affinity} for a staff causes it to be treated as a
+non-staff line. Setting @code{staff-affinity} to @code{#f} causes
+a non-staff line to be treated as a staff. Setting
+@code{staff-affinity} to @code{UP}, @code{CENTER}, or @code{DOWN}
+causes a staff to be spaced as a non-staff line.
+
+@item nonstaff-relatedstaff-spacing
+The distance between the current non-staff line and the nearest
+staff in the direction of @code{staff-affinity}, if there are no
+non-staff lines between the two, and @code{staff-affinity} is
+either @code{UP} or @code{DOWN}. If @code{staff-affinity} is
+@code{CENTER}, then @code{nonstaff-relatedstaff-spacing} is used
+for the nearest staves on @emph{both} sides, even if other
+non-staff lines appear between the current one and either of the
+staves. This means that the placement of a non-staff line depends
+on both the surrounding staves and the surrounding non-staff lines.
+Setting the @code{stretchability} of one of these types of spacing to
+a small value will make that spacing dominate. Setting the
+@code{stretchability} to a large value will make that spacing have
+little effect.
+
+@item nonstaff-nonstaff-spacing
+The distance between the current non-staff line and the next
+non-staff line in the direction of @code{staff-affinity}, if both
+are on the same side of the related staff, and
+@code{staff-affinity} is either @code{UP} or @code{DOWN}.
+
+@item nonstaff-unrelatedstaff-spacing
+The distance between the current non-staff line and the staff in
+the opposite direction from @code{staff-affinity}, if there are no
+other non-staff lines between the two, and @code{staff-affinity}
+is either @code{UP} or @code{DOWN}. This can be used, for
+example, to require a minimum amount of padding between a
+@code{Lyrics} line and the staff to which it does not belong.
+@end table
-@seealso
-Notation Reference:
-@ref{Vertical spacing}.
-Snippets:
-@rlsr{Spacing}.
+@subsubheading Properties of the @code{StaffGrouper} grob
+@code{StaffGrouper} properties are typically adjusted with an
+@code{\override} at the @code{StaffGroup} level (or equivalent).
-@node Vertical spacing
-@section Vertical spacing
+@table @code
+@item staff-staff-spacing
+The distance between consecutive staves within the current
+staff-group. The @code{staff-staff-spacing} property of an
+individual staff's @code{VerticalAxisGroup} grob can be
+overriden with different spacing settings for that staff.
+
+@item staffgroup-staff-spacing
+The distance between the last staff of the current staff-group and
+the staff just below it in the same system, even if one or more
+non-staff lines (such as @code{Lyrics}) exist between the two
+staves. Does not apply to the bottom staff of a system. The
+@code{staff-staff-spacing} property of an individual staff's
+@code{VerticalAxisGroup} grob can be overriden with different
+spacing settings for that staff.
+@end table
-@cindex vertical spacing
-@cindex spacing, vertical
+@seealso
+Notation Reference:
+@ref{Flexible vertical spacing paper variables,,Flexible vertical spacing @code{@bs{}paper} variables},
+@ref{Modifying alists}.
-Vertical spacing is controlled by three things: the amount of
-space available (i.e., paper size and margins), the amount of
-space between systems, and the amount of space between
-staves inside a system.
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
-@menu
-* Vertical spacing inside a system::
-* Vertical spacing between systems::
-* Explicit staff and system positioning::
-* Vertical collision avoidance::
-@end menu
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
-@node Vertical spacing inside a system
-@subsection Vertical spacing inside a system
+@node Spacing of ungrouped staves
+@unnumberedsubsubsec Spacing of ungrouped staves
-@cindex distance between staves
-@cindex staff distance
-@cindex space between staves
-@cindex space inside systems
+@emph{Staves} (such as @code{Staff}, @code{DrumStaff},
+@code{TabStaff}, etc.) are contexts that can contain one or more
+voice contexts, but cannot contain any other staves.
-The height of each system is determined in two steps. First, all of the
-staves are spaced according to the amount of space available. Then, the
-non-staff lines (eg. lyrics or chords) are distributed between the
-staves.
+The following properties affect the spacing of @emph{ungrouped}
+staves:
-@unnumberedsubsubsec Spacing between staves
-Spacing between staves is controlled by the @var{next-staff-spacing}
-property of the @var{VerticalAxisGroup} grob. This property is an alist
-with four elements: @var{space}, @var{minimum-distance}, @var{padding}
-and @var{stretchability}:
@itemize
-@item
-@var{space} is the size of the stretchable space between the center line
-of one staff to the center line of the next staff.
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{default-staff-staff-spacing}
+@item @code{staff-staff-spacing}
+@end itemize
+@end itemize
-@item
-@var{minimum-distance} provides a lower bound on the final distance
-between the center line of one staff to the center line of the next
-staff. That is, if a page has many systems and needs to be compressed,
-the distance from this staff to the next will never be compressed to
-less than @var{minimum-distance}.
+These grob properties are described individually above; see
+@ref{Within-system spacing properties}.
-@item
-@var{padding} is the amount of whitespace that must be present between
-the bottom of one staff and the top of the next. It differs from
-@var{minimum-distance} in that the effect of @var{padding} depends on
-the height of objects in the staff. For example, @var{padding} is more
-likely to come into effect for staves with notes that are far below the
-staff.
+Additional properties are involved for staves that are part of a
+staff-group; see @ref{Spacing of grouped staves}.
-@item
-@var{stretchability} controls the stretchable space's propensity to
-stretch when the system is stretched. Large values will cause a
-system to stretch more, while a value of zero will prevent the
-space from stretching at all. If unset, @var{stretchability}
-defaults to @code{space - minimum-distance}.
-@end itemize
+The following example shows how the @code{default-staff-staff-spacing}
+property can affect the spacing of ungrouped staves.
+The same overrides applied to @code{staff-staff-spacing} would
+have the same effect, but would also apply in cases where the staves
+are combined in a group or groups.
-@lilypond[verbatim]
-#(set-global-staff-size 16)
-\new StaffGroup <<
- % Since space is small and there is no minimum-distance, the distance
- % between this staff and the next will be determined by padding.
- \new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 1) (padding . 1))
- }
- { \clef bass c, }
- % Since space is small and nothing sticks out very far, the distance
- % between this staff and the next will be determined by minimum-distance.
- \new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 1) (minimum-distance . 12))
+@lilypond[verbatim,quote,staffsize=16]
+\layout {
+ \context {
+ \Staff
+ \override VerticalAxisGroup.default-staff-staff-spacing =
+ #'((basic-distance . 8)
+ (minimum-distance . 7)
+ (padding . 1))
}
- { \clef bass c, }
- % By setting padding to a negative value, staves can be made to collide.
+}
+
+<<
+ % The very low note here needs more room than 'basic-distance
+ % can provide, so the distance between this staff and the next
+ % is determined by 'padding.
+ \new Staff { b,2 r | }
+
+ % Here, 'basic-distance provides enough room, and there is no
+ % need to compress the space (towards 'minimum-distance) to make
+ % room for anything else on the page, so the distance between
+ % this staff and the next is determined by 'basic-distance.
+ \new Staff { \clef bass g2 r | }
+
+ % By setting 'padding to a negative value, staves can be made to
+ % collide. The lowest acceptable value for 'basic-distance is 0.
\new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 4) (padding . -10))
- }
- { \clef bass c, }
- \new Staff { \clef bass c, }
+ \override VerticalAxisGroup.default-staff-staff-spacing =
+ #'((basic-distance . 3.5)
+ (padding . -10))
+ } { \clef bass g2 r | }
+ \new Staff { \clef bass g2 r | }
>>
@end lilypond
+@seealso
+Installed Files:
+@file{scm/define-grobs.scm}.
+
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{VerticalAxisGroup}.
+
+
+@node Spacing of grouped staves
+@unnumberedsubsubsec Spacing of grouped staves
+
+In orchestral and other large scores, it is common to place staves
+in groups. The space between groups is typically larger than the
+space between staves of the same group.
+
+@emph{Staff-groups} (such as @code{StaffGroup}, @code{ChoirStaff},
+etc.) are contexts that can contain one or more staves
+simultaneously.
+
+The following properties affect the spacing of staves inside
+staff-groups:
+
+@itemize
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{staff-staff-spacing}
+@end itemize
+@item @code{StaffGrouper} properties:
+@itemize
+@item @code{staff-staff-spacing}
+@item @code{staffgroup-staff-spacing}
+@end itemize
+@end itemize
+
+These grob properties are described individually above; see
+@ref{Within-system spacing properties}.
+
+The following example shows how properties of the
+@code{StaffGrouper} grob can affect the spacing of grouped staves:
+
+@lilypond[verbatim,quote,staffsize=16]
+\layout {
+ \context {
+ \Score
+ \override StaffGrouper.staff-staff-spacing.padding = #0
+ \override StaffGrouper.staff-staff-spacing.basic-distance = #1
+ }
+}
-In orchestral and other large scores, it is common to place staves in
-groups. The space between groups is typically larger than the space
-between staves of the same group. This spacing can be tweaked with the
-@var{StaffGrouper} grob: the default value of @var{next-staff-spacing}
-for @var{VerticalAxisGroup} is a callback function which operates by
-searching for a @var{StaffGrouper} grob containing the staff. If it
-finds a @var{StaffGrouper} grob and the staff in question is in the
-middle of a group, it reads the @var{between-staff-spacing} property of
-@var{StaffGrouper} and returns it. If the staff in question is the last
-staff of a group, the callback reads the @var{after-last-staff-spacing}
-property of @var{StaffGrouper} and returns it. If the callback did not
-find a @var{StaffGrouper} grob, it reads
-@var{default-next-staff-spacing} from its @var{VerticalAxisGroup} and
-returns that.
-
-@lilypond[verbatim]
-#(set-global-staff-size 16)
<<
\new PianoStaff \with {
- \override StaffGrouper #'between-staff-spacing #'space = #1
- \override StaffGrouper #'between-staff-spacing #'padding = #0
- \override StaffGrouper #'after-last-staff-spacing #'space = #20
- }
- <<
- \new Staff c'1
- \new Staff c'1
+ \override StaffGrouper.staffgroup-staff-spacing.basic-distance = #20
+ } <<
+ \new Staff { c'1 }
+ \new Staff { c'1 }
>>
- \new StaffGroup \with {
- \override StaffGrouper #'between-staff-spacing #'space = #1
- \override StaffGrouper #'between-staff-spacing #'padding = #0
- }
- <<
- \new Staff c'1
- \new Staff c'1
+ \new StaffGroup <<
+ \new Staff { c'1 }
+ \new Staff { c'1 }
>>
>>
@end lilypond
+@seealso
+Installed Files:
+@file{scm/define-grobs.scm}.
-@unnumberedsubsubsec Spacing of non-staff lines
+Snippets:
+@rlsr{Spacing}.
-After the positions of the staves are determined, the non-staff lines
-are distributed between the staves. Each of these lines has a
-@var{staff-affinity} property which controls its vertical alignment.
-For example,
+Internals Reference:
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
-@example
-\new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
-@end example
-@noindent creates a lyrics context that will be placed close to the
-staff below it. Setting @var{staff-affinity} to something which is not
-a number (@code{#f}, for example) will cause that line to be treated
-like a staff. Conversely, setting @var{staff-affinity} for a staff will
-cause it to be treated like a non-staff.
+@node Spacing of non-staff lines
+@unnumberedsubsubsec Spacing of non-staff lines
-Non-staff lines admit three properties to control their spacing. Each
-of the these properties is an alist of the same format as
-@var{next-staff-spacing}, above.
-@itemize
-@item
-If the nearest line in the @var{staff-affinity} direction is a staff
-then @var{inter-staff-spacing} gives the spacing between the non-staff
-and the staff. If @var{staff-affinity} is @code{CENTER}, then
-@var{inter-staff-spacing} is used for both directions.
+@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,
+non-staff lines are non-staff contexts that contain the
+@rinternals{Axis_group_engraver}.
-@item
-If the nearest line in the @var{staff-affinity} direction is a non-staff
-then @var{inter-loose-line-spacing} gives the spacing between the two
-non-staff lines.
+The following properties affect the spacing of non-staff lines:
-@item
-If the nearest line in the opposite direction to @var{staff-affinity} is
-a staff then @var{non-affinity-spacing} gives the spacing between the
-non-staff and the staff. This can be used, for example, to require
-a minimum amount of padding between a Lyrics line and the staff
-to which it does not belong.
+@itemize
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{staff-affinity}
+@item @code{nonstaff-relatedstaff-spacing}
+@item @code{nonstaff-nonstaff-spacing}
+@item @code{nonstaff-unrelatedstaff-spacing}
+@end itemize
@end itemize
-@lilypond[verbatim]
-#(set-global-staff-size 16)
+These grob properties are described individually above; see
+@ref{Within-system spacing properties}.
+
+The following example shows how the
+@code{nonstaff-nonstaff-spacing} property can affect the spacing
+of consecutive non-staff lines. Here, by setting the
+@code{stretchability} key to a very high value, the lyrics are
+able to stretch much more than usual:
+
+@lilypond[verbatim,quote,staffsize=16]
\layout {
\context {
\Lyrics
- % By default, Lyrics are placed close together. Here, we allow them to
- % be stretched more widely.
- \override VerticalAxisGroup
- #'inter-loose-line-spacing #'stretchability = #1000
+ \override VerticalAxisGroup.nonstaff-nonstaff-spacing.stretchability = #1000
}
}
\new StaffGroup
<<
\new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing = #'((space . 30)) }
- { c'1 }
+ \override VerticalAxisGroup.staff-staff-spacing = #'((basic-distance . 30))
+ } { c'1 }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #UP }
- \lyricmode { up }
+ \override VerticalAxisGroup.staff-affinity = #UP
+ } \lyricmode { up }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #CENTER }
- \lyricmode { center }
+ \override VerticalAxisGroup.staff-affinity = #CENTER
+ } \lyricmode { center }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #DOWN }
- \lyricmode { down }
- \new Staff
- { c'1 }
+ \override VerticalAxisGroup.staff-affinity = #DOWN
+ } \lyricmode { down }
+ \new Staff { c'1 }
>>
@end lilypond
@seealso
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
Snippets:
@rlsr{Spacing}.
@c @lsr{spacing,alignment-vertical-spacing.ly}.
Internals Reference:
-@rinternals{VerticalAxisGroup},
-@rinternals{VerticalAlignment},
-@rinternals{Axis_group_engraver}.
-
-@knownissues
-Adjacent non-staff lines should have non-increasing
-@var{staff-affinity} from top-to-bottom. For example, the behavior of
-@example
-<<
- \new Staff c
- \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
- \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #UP @}
- \new Staff c
->>
-@end example
-is undefined.
-
-A non-staff line at the bottom of a system should have
-@var{staff-affinity} set to @code{UP}. Similarly, a non-staff
-line at the top of a system should have @var{staff-affinity} set
-to @code{DOWN}.
-
-@node Vertical spacing between systems
-@subsection Vertical spacing between systems
-
-The mechanisms that control spacing between systems are similar to those
-that control spacing between staves within a system (see
-@ref{Vertical spacing inside a system}). The main difference is that
-the variables to control spacing between systems are set in the
-@code{\paper} block, rather than as grob properties. These paper block
-variables are @var{between-system-spacing},
-@var{between-scores-system-spacing}, @var{after-title-spacing},
-@var{before-title-spacing}, @var{between-title-spacing},
-@var{top-system-spacing}, @var{top-title-spacing} and
-@var{bottom-system-spacing}. Note that these variables ignore non-staff
-lines. For example, @var{between-system-spacing} controls the spacing
-from the middle staff line of the bottom staff from one system to
-the middle staff line of the top staff of the next system, whether
-or not there are lyrics below the upper system.
-See @ref{Vertical dimensions} for a description of each of these
-variables.
-
-There are two more @code{\paper} block variables that affect vertical
-spacing: if @var{ragged-bottom} is set to @code{##t} then no pages will
-be stretched (which means that neither the space between systems nor the
-space within systems will be stretched). If @var{ragged-last-bottom}
-is set to @code{##t} then the last page will not be stretched.
-
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup}.
@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.
+One way to understand the flexible vertical spacing mechanisms
+explained above is as a collection of settings that control the
+amount of vertical padding between staves and systems.
-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.
+It is possible to approach vertical spacing in a different way
+using @code{NonMusicalPaperColumn.line-break-system-details}.
+While the flexible vertical spacing mechanisms specify vertical
+padding, @code{NonMusicalPaperColumn.line-break-system-details}
+can specify exact vertical positions on the page.
-@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
-list of three different settings:
+@code{NonMusicalPaperColumn.line-break-system-details} accepts
+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
@code{\overrideProperty} command:
@example
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+ #'((X-offset . 20))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((Y-offset . 40))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 40))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+ #'((X-offset . 20)
+ (Y-offset . 40))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((alignment-distances . (15)))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+ #'((alignment-distances . (15)))
-\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
- (alignment-distances . (15)))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+ #'((X-offset . 20)
+ (Y-offset . 40)
+ (alignment-distances . (15)))
@end example
To understand how each of these different settings work, we begin
@c \book { } is required in these examples to ensure the spacing
@c overrides can be seen between systems. -np
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
}
@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}.
+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[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
<<
\new Staff <<
\new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 0))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 40))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 40))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 80))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 60))
s1*5 \break
}
\new Voice { \repeat unfold 15 { c'4 c' c' c' } }
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}
subproperty of @code{line-break-system-details}.
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
<<
\new Staff <<
\new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 20)
- (alignment-distances . (15)))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 20)
+ (alignment-distances . (10)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 60)
- (alignment-distances . (15)))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 60)
+ (alignment-distances . (15)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 100)
- (alignment-distances . (15)))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 85)
+ (alignment-distances . (20)))
s1*5 \break
}
\new Voice { \repeat unfold 15 { c'4 c' c' c' } }
every system and every staff. Finally, note that @code{alignment-distances}
specifies the vertical positioning of staves but not of staff groups.
-@lilypond[quote]
+@lilypond[verbatim,quote,staffsize=16]
\header { tagline = ##f }
\paper { left-margin = 0\mm }
\book {
<<
\new Staff <<
\new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0)
- (alignment-distances . (30 10)))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 0)
+ (alignment-distances . (30 10)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 60)
- (alignment-distances . (10 10)))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 60)
+ (alignment-distances . (10 10)))
s1*5 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 100)
- (alignment-distances . (10 30)))
+ \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+ #'((Y-offset . 100)
+ (alignment-distances . (10 30)))
s1*5 \break
}
\new Voice { \repeat unfold 15 { c'4 c' c' c' } }
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}
+@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
-
@seealso
Snippets:
@rlsr{Spacing}.
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
+A listing of outside-staff-priorities may be found in
+@rlearning{The outside-staff-priority property}.
-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,verbatim]
+\relative c'' {
+ 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
-@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"
+The vertical padding around outside-staff objects
+can be controlled with @code{outside-staff-padding}.
+
+@lilypond[quote,ragged-right,verbatim,staffsize=18]
+\relative {
+ \once \override TextScript.outside-staff-padding = #0
+ a'4-"outside-staff-padding = #0"
+ \once \override TextScript.outside-staff-padding = #3
+ d-"outside-staff-padding = #3"
+ c-"default outside-staff-padding"
+ b-"default outside-staff-padding"
+ R1
+}
@end lilypond
-By default, outside-staff objects are placed only to avoid
+By default, outside-staff objects are placed so they avoid
a horizontal collision with previously-positioned grobs. This
-can lead to situations in which objects are placed very close to each
-other horizontally. The vertical spacing between staves can
-also be set so that outside staff objects are interleaved.
-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
-c4^"Text"
-c4
-c''2
-% setting outside-staff-horizontal-padding fixes this
-R1
-\once \override TextScript #'outside-staff-horizontal-padding = #1
-c,,4^"Text"
-c4
-c''2
-@end lilypond
+can lead to situations in which objects are placed close to each
+other horizontally.
+As shown in the example below, setting @code{outside-staff-horizontal-padding}
+increases the horizontal spacing required, and in this case moves the text up
+to prevent it from getting too close to the ledger lines.
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+ c''4^"Word" c c''2
+ R1
+ \once \override TextScript.outside-staff-horizontal-padding = #1
+ c,,4^"Word" c c''2
+}
+@end lilypond
@seealso
Snippets:
@menu
* Horizontal spacing overview::
-* New spacing area::
+* New spacing section::
* Changing horizontal spacing::
-* Line length::
+* Line width::
* Proportional notation::
@end menu
fixed amount of space (which is controlled by
@code{shortest-duration-space} in the @rinternals{SpacingSpanner}
object). The longer the duration, the more space it gets: doubling a
-duration adds a fixed amount (this amount is controlled by
-@code{spacing-increment}) of space to the note.
+duration adds @code{spacing-increment} of space to the note.
For example, the following piece contains lots of half, quarter, and
8th notes; the eighth note is followed by 1 note head width (NHW).
The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-@lilypond[quote,fragment,verbatim,relative=1]
-c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
+@lilypond[quote,verbatim]
+\relative c' {
+ c2 c4. c8
+ c4. c8 c4. c8
+ c8 c c4 c c
+}
@end lilypond
Normally, @code{spacing-increment} is set to 1.2 staff space, which is
measure, the shortest duration is determined. The most common shortest
duration is taken as the basis for the spacing, with the stipulation
that this shortest duration should always be equal to or shorter than
-an 8th note. The shortest duration is printed when you run
-@code{lilypond} with the @code{--verbose} option.
+an 8th note.
These durations may also be customized. If you set the
@code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
the common shortest note. So if we were to add only a few 16th notes
to the example above, they would be followed by half a NHW:
-@lilypond[quote,fragment,verbatim,relative=2]
-c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
+@lilypond[quote,verbatim]
+\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).
-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 @code{StaffSpacing} object (generated in @rinternals{Staff} context)
+contains the same property for controlling the stem/bar line spacing.
+
+The following example shows this; once with the default settings and
+once with an exaggerated adjustment:
@lilypond[quote,ragged-right]
-{
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4 |
- \override Staff.NoteSpacing #'stem-spacing-correction = #1.5
- \override Staff.StaffSpacing #'stem-spacing-correction = #1.5
- c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4 |
+\fixed c' {
+ c4 e'4 e4 b4 |
+ b4 e'4 b4 e'4 |
+ \override Staff.NoteSpacing.stem-spacing-correction = #1.5
+ \override Staff.StaffSpacing.stem-spacing-correction = #1.5
+ c4 e'4 e4 b4 |
+ b4 e'4 b4 e'4 |
}
@end lilypond
Proportional notation is supported; see @ref{Proportional notation}.
-
@seealso
+Essay on automated music engraving:
+@ressay{Optical spacing}.
+
Snippets:
@rlsr{Spacing}.
@rinternals{StaffSpacing},
@rinternals{NonMusicalPaperColumn}.
-
@knownissues
-
There is no convenient mechanism to manually override spacing. The
following work-around may be used to insert extra space into a score,
adjusting the padding value as necessary.
+
@example
- \override Score.NonMusicalPaperColumn #'padding = #10
+ \override Score.NonMusicalPaperColumn.padding = #10
@end example
No work-around exists for decreasing the amount of space.
-@node New spacing area
-@subsection New spacing area
+@node New spacing section
+@subsection New spacing section
-New sections with different spacing parameters can be started with
-@code{newSpacingSection}. This is useful when there are
-sections with a different notions of long and short notes.
+@funindex \newSpacingSection
+@cindex new spacing section
+@cindex spacing section, new
+@cindex notes, spacing horizontally
-In the following example, the time signature change introduces a new
-section, and hence the 16ths notes are spaced wider.
+New sections with different spacing parameters can be started with the
+@code{newSpacingSection} command. This is useful for sections with
+different notions of @q{long} and @q{short} notes. The
+@code{\newSpacingSection} command creates a new @code{SpacingSpanner}
+object at that musical moment.
-@lilypond[relative,fragment,verbatim,quote]
-\time 2/4
-c4 c8 c
-c8 c c4 c16[ c c8] c4
-\newSpacingSection
-\time 4/16
-c16[ c c8]
+In the following example the time signature change introduces a new
+section, and the 16ths notes are automatically spaced slightly wider
+apart.
+
+@lilypond[verbatim,quote]
+\relative c' {
+ \time 2/4
+ c4 c8 c
+ c8 c c4 c16[ c c8] c4
+ \newSpacingSection
+ \time 4/16
+ c16[ c c8]
+}
@end lilypond
-The @code{\newSpacingSection} command creates a new
-@code{SpacingSpanner} object, and hence new @code{\override}s
-may be used in that location.
+If the automatic spacing adjustments do not give the required spacing,
+manual @code{\override}s may be applied to its properties. These must
+be applied at the same musical moment as the @code{\newSpacingSection}
+command itself and will then affect the spacing of all the following
+music until the properties are changed in a new spacing section, for
+example:
+
+@lilypond[verbatim,quote]
+\relative c' {
+ \time 4/16
+ c16[ c c8]
+ \newSpacingSection
+ \override Score.SpacingSpanner.spacing-increment = #2
+ c16[ c c8]
+ \newSpacingSection
+ \revert Score.SpacingSpanner.spacing-increment
+ c16[ c c8]
+}
+@end lilypond
@seealso
@lilypond[verbatim,line-width=12\cm]
\score {
- \relative c'' {
- g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ \relative {
+ g'4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
@lilypond[verbatim,line-width=12\cm]
\score {
- \relative c'' {
- g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ \relative {
+ g'4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
g4 e e2 | f4 d d2 | c4 e g g | c,1 |
\layout {
\context {
\Score
- \override SpacingSpanner
- #'base-shortest-duration = #(ly:make-moment 1 16)
+ \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1/16)
}
}
}
By default, spacing in tuplets depends on various non-duration
factors (such as accidentals, clef changes, etc). To disregard
such symbols and force uniform equal-duration spacing, use
-@code{Score.SpacingSpanner #'uniform-stretching}. This
+@code{Score.SpacingSpanner.uniform-stretching}. This
property can only be changed at the beginning of a score,
@lilypond[quote,ragged-right,verbatim]
\score {
<<
\new Staff {
- \times 4/5 {
- c8 c8 c8 c8 c8
- }
- c8 c8 c8 c8
+ \tuplet 5/4 { c8 c c c c } c8 c c c
}
\new Staff {
- c8 c8 c8 c8
- \times 4/5 {
- c8 c8 c8 c8 c8
- }
+ c8 c c c \tuplet 5/4 { c8 c c c c }
}
>>
\layout {
\context {
\Score
- \override SpacingSpanner #'uniform-stretching = ##t
+ \override SpacingSpanner.uniform-stretching = ##t
}
}
}
When @code{strict-note-spacing} is set, notes are spaced without
regard for clefs, bar lines, and grace notes,
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-\override Score.SpacingSpanner #'strict-note-spacing = ##t
-\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
+@lilypond[quote,ragged-right,fragment,verbatim]
+\override Score.SpacingSpanner.strict-note-spacing = ##t
+\new Staff \relative {
+ c''8[ c \clef alto c \grace { c16 c } c8 c c] c32[ c] }
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
-@node Line length
-@subsection Line length
+@node Line width
+@subsection Line width
@cindex page breaks
@cindex breaking pages
@}
@end example
-
@seealso
Snippets:
@rlsr{Spacing}.
@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}
+@item @code{\remove "Separating_line_group_engraver"}
+@item @code{\override PaperColumn.used = ##t}
@end itemize
In the examples that follow, we explore these five different
We start with the following one-measure example, which uses classical
spacing with ragged-right turned on.
+@c The initial pitch is not necessary as long as RhythmicStaff is
+@c not preceded by other material in the score, but we don't want
+@c to explain that.
@lilypond[quote,verbatim,ragged-right]
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
}
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\context {
\Score
- proportionalNotationDuration = #(ly:make-moment 1 20)
+ proportionalNotationDuration = #(ly:make-moment 1/20)
}
}
}
which is the reference duration against that all music will be spaced.
The LilyPond Scheme function @code{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 whole note. The call @code{(ly:make-moment 1/20)} therefore produces
a reference duration of a twentieth note. Values such as
-@code{#(ly:make-moment 1 16)}, @code{#(ly:make-moment 1 8)}, and
-@code{#(ly:make-moment 3 97)} are all possible as well.
+@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
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\context {
\Score
- proportionalNotationDuration = #(ly:make-moment 1 8)
+ proportionalNotationDuration = #(ly:make-moment 1/8)
}
}
}
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\context {
\Score
- proportionalNotationDuration = #(ly:make-moment 1 16)
+ proportionalNotationDuration = #(ly:make-moment 1/16)
}
}
}
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
>>
\layout {
\context {
\Score
- proportionalNotationDuration = #(ly:make-moment 1 32)
+ proportionalNotationDuration = #(ly:make-moment 1/32)
}
}
}
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
\new RhythmicStaff {
- \times 8/9 {
- c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
- }
+ \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
}
>>
}
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
\new RhythmicStaff {
- \times 8/9 {
- c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
- }
+ \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
}
>>
\layout {
\context {
\Score
- proportionalNotationDuration = #(ly:make-moment 1 20)
+ proportionalNotationDuration = #(ly:make-moment 1/20)
}
}
}
\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
- }
+ c2 16 16 16 16 \tuplet 5/4 { 16 16 16 16 16 }
}
\new RhythmicStaff {
- \times 8/9 {
- c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
- }
+ \tuplet 9/8 { c8 8 8 8 8 8 8 8 8 }
}
>>
\layout {
\context {
\Score
- proportionalNotationDuration = #(ly:make-moment 1 20)
- \override SpacingSpanner #'uniform-stretching = ##t
+ proportionalNotationDuration = #(ly:make-moment 1/20)
+ \override SpacingSpanner.uniform-stretching = ##t
}
}
}
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.
+@code{\newSpacingSection}. See @ref{New spacing section}, 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
+example shows that there is a small amount of @qq{prefatory} space
just before the first note in each system.
@lilypond[quote,verbatim,ragged-right]
@end lilypond
-The amount of this preferatory space is the same whether after a time
+The amount of this prefatory 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.
}
\new Staff \with {
- \remove Separating_line_group_engraver
+ \remove "Separating_line_group_engraver"
} {
c'1
\break
}
@end lilypond
-Nonmusical elements like time signatures, key signatures, clefs and
+non-musical elements like time signatures, key signatures, clefs and
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
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
+So what strategies exist for spacing non-musical 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
+ \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
+ c''8 8 8 \clef alto d'2 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
+ \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
+ \override Score.SpacingSpanner.strict-note-spacing = ##t
+ c''8 8 8 \clef alto d'2 2
}
@end lilypond
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}
+@item @code{\override SpacingSpanner.strict-grace-spacing = ##t}
+@item @code{\set 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
to break across systems and pages. See the respective parts of the manual
for these related settings.
-
@seealso
Notation Reference:
-@ref{New spacing area}.
+@ref{New spacing section}.
Snippets:
@rlsr{Spacing}.
@section 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
+(or third, or fourth@dots{}) page. This is annoying, especially
if you look at previous pages and it looks like there is plenty
of room left on those.
that may be altered for page formatting, set
@code{annotate-spacing} in the @code{\paper} block:
-@c need to have \book{} otherwise we get the separate systems. -hwn
-@lilypond[verbatim,quote]
-#(set-default-paper-size "a6" 'landscape)
+@lilypond[verbatim,quote,papersize=a6landscape]
\book {
\score { { c4 } }
\paper { annotate-spacing = ##t }
(@var{a},@var{b}) are intervals, where @var{a} is the lower
edge and @var{b} the upper edge of the interval.
-
@seealso
Notation Reference:
@ref{Setting the staff size}.
The output of @code{annotate-spacing} reveals vertical dimensions
in great detail. For details about modifying margins and other
-layout variables, see @ref{Page formatting}.
+layout variables, see @ref{Page layout}.
Other than margins, there are a few other options to save space:
@example
\paper @{
- between-system-spacing = #'((padding . 0) (space . 0.1))
+ system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
ragged-last-bottom = ##f
ragged-bottom = ##f
@}
@}
@end example
+@item
+Force the number of pages. For example, the following
+assignment will force a layout with 2 pages.
+
+@example
+\paper @{
+ page-count = #2
+@}
+@end example
+
@item
Avoid (or reduce) objects that 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. For example, dynamics that @q{stick out} of
-a system can be moved closer to the staff:
-
-@lilypond[verbatim,quote,relative=1]
-e4 c g\f c
-e4 c g-\tweak #'X-offset #-2.7 -\tweak #'Y-offset #2.5 \f c
+system. For example, volta brackets for alternative repeat endings
+require extra space. If these endings are spread over two systems,
+they take up more space than if they were on the same system.
+As another example, dynamics that @q{stick out} of a system
+can be moved closer to the staff:
+
+@lilypond[verbatim,quote]
+\relative e' {
+ e4 c g\f c
+ e4 c g-\tweak X-offset #-2.7 \f c
+}
@end lilypond
@item
@lilypond[verbatim,quote]
\score {
- \relative c'' {
- g4 e e2 |
+ \relative {
+ g'4 e e2 |
f4 d d2 |
c4 d e f |
g4 g g2 |
@lilypond[verbatim,quote]
\score {
- \relative c'' {
- g4 e e2 |
+ \relative {
+ g'4 e e2 |
f4 d d2 |
c4 d e f |
g4 g g2 |
\layout {
\context {
\Score
- \override SpacingSpanner
- #'common-shortest-duration = #(ly:make-moment 1 2)
+ \override SpacingSpanner.common-shortest-duration =
+ #(ly:make-moment 1/2)
}
}
}
@end itemize
-
@seealso
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Changing horizontal spacing}.
Snippets:
projects / lilypond.git / blobdiff