Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.39"
+@c \version "2.13.42"
@ignore
GDP TODO list
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, 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{\paper} block
+
+The @code{\paper} block can appear within a @code{\book} block,
+but not within a @code{\score} block. Settings in a @code{\paper}
+block apply to the entire book, which may include multiple scores.
+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 headers footers and titles}.
+
+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}.
+
+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 headers footers and titles},
+@ref{The \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
+@funindex \paper
+
+@menu
+* Setting paper size::
+* Automatic scaling to paper size::
+@end menu
+
+
+@node Setting paper size
+@unnumberedsubsubsec Setting paper 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
@end example
@noindent
+In the toplevel scope, the @code{set-default-paper-size} function
+can safely be called anywhere before the first @code{\paper}
+block. Within a @code{\paper} block, the safest place to call
+@code{set-paper-size} is at the top, above the list of variable
+declarations. The reasons for this are discussed in
+@ref{Automatic scaling to paper size}.
+
@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}
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
+details, see @file{scm/paper.scm}, and search for the
definition of @code{paper-alist}.
@c TODO add a new appendix for paper sizes (auto-generated) -pm
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
+@file{scm/paper.scm}, however they will be overridden on a
subsequent install.
@cindex orientation
#(set-default-paper-size "a6" 'landscape)
@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.
-
-
@seealso
-Installed Files:
-@file{scm/@/paper@/.scm}.
-
-Snippets:
-@rlsr{Spacing}.
-
-
-@node Page formatting
-@subsection Page formatting
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-@funindex \paper
+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 paper size}.
+
+The vertical dimensions affected by automatic scaling are
+@code{top-margin} and @code{bottom-margin} (see
+@ref{Fixed vertical spacing \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}).
+
+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}.
-Margins, headers, and footers and other layout variables are
-automatically set according to the paper size.
+@seealso
+Notation Reference:
+@ref{Fixed vertical spacing \paper variables},
+@ref{Horizontal spacing \paper variables}.
-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{ly/paper-defaults-init.ly},
+@file{scm/paper.scm}.
-This section lists and describes a number of paper variables that
-may be altered.
-@menu
-* Fixed vertical dimensions::
-* Flexible vertical dimensions::
-* Horizontal dimensions::
-* Other layout variables::
-@end menu
+@node Fixed vertical spacing \paper variables
+@subsection Fixed vertical spacing @code{\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}.}
-@node Fixed vertical dimensions
-@unnumberedsubsubsec 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 set to true, systems will not spread vertically down the page.
+This does not affect the last page. This should be set to true
+for pieces that have only two or three systems per page, for
+example orchestral scores.
+
+@item ragged-last-bottom
+@funindex ragged-last-bottom
+
+If set to false, systems will spread vertically down the last
+page. Pieces that amply fill two pages or more should have this
+set to true. It also affects the last page of book parts, i.e.
+parts of a book created with @code{\bookpart} blocks.
+
@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.
+
-@node Flexible vertical dimensions
-@unnumberedsubsubsec Flexible vertical dimensions
+@node Flexible vertical spacing \paper variables
+@subsection Flexible vertical spacing @code{\paper} variables
In most cases, it is preferable for the vertical distances between
certain items (such as margins, titles, systems, and separate
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
+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
-@subsubheading Structure of spacing alists for @code{\paper} variables
-Each of these variables is an alist (association list) containing
-four @emph{keys}:
+@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, measured in
-staff-spaces. 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, measured in
+@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{space} 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}.
+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 minimum required vertical
+@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.}
-@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}
+@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{space}. Note
-that the dimension's propensity to @emph{compress} cannot be
-directly set by the user and is equal to
-(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
+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
If a page has a ragged bottom, the resulting distance is the
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
Specific methods for modifying alists are discussed in
-@ref{Modifying alists}. The flexible vertical @code{\paper}
-dimensions variables can only be set within a @code{\paper} block.
-
-The following example demonstrates the two ways these alists can
-be modified. The first declaration updates one key-value
-individually, and the second complete re-defines the variable:
+@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 @{
- system-system-spacing #'space = #8
-
+ system-system-spacing #'basic-distance = #8
score-system-spacing =
- #'((padding . 1)
- (space . 12)
+ #'((basic-distance . 12)
(minimum-distance . 6)
+ (padding . 1)
(stretchability . 12))
@}
@end example
-The initialized default settings for these variables are defined
-in @file{ly/paper-defaults-init.ly}.
-
-@subsubheading Flexible vertical dimension @code{\paper} variables
+@node List of flexible vertical spacing \paper variables
+@unnumberedsubsubsec List of flexible vertical spacing @code{\paper} variables
The names of these variables follow the format
@code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
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}).
+@ref{File structure}). All distances are measured in
+staff-spaces.
+
+Default settings are defined in @file{ly/paper-defaults-init.ly}.
+
+@c TODO: Where do headers/footers fit in? -mp
@table @code
@item markup-system-spacing
page, when there is no system between the two.
@end table
+@seealso
+Notation Reference:
+@ref{Flexible vertical spacing within systems}.
-@snippets
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-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}.
+Snippets:
+@rlsr{Spacing}.
-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:
+@node Horizontal spacing \paper variables
+@subsection Horizontal spacing @code{\paper} variables
-@example
-\paper @{
- #(define bottom-margin (* 2 cm))
-@}
-@end example
+@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}.}
+@menu
+* \paper variables for widths and margins::
+* \paper variables for two-sided mode::
+* \paper variables for shifts and indents::
+@end menu
-Example:
-@example
-\paper @{
- paper-width = 2\cm
- top-margin = 3\cm
- bottom-margin = 3\cm
- ragged-last-bottom = ##t
-@}
-@end example
+@node \paper variables for widths and margins
+@unnumberedsubsubsec @code{\paper} variables for widths and margins
-This second example centers page numbers at the bottom of every page.
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
-@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
+@table @code
-@seealso
-Notation Reference:
-@ref{Flexible vertical spacing within systems}.
+@item paper-width
+@funindex paper-width
-Snippets:
-@rlsr{Spacing}.
+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 line-width
+@funindex line-width
-@node Horizontal dimensions
-@unnumberedsubsubsec Horizontal dimensions
+The horizontal extent of the staff lines in unindented, non-ragged
+systems, equal to
+@code{(paper-width@tie{}@minus{}@tie{}left-margin@tie{}@minus{}@tie{}right-margin)}
+when unset. If @code{line-width} is set, and both
+@code{left-margin} and @code{right-margin} are unset, then the
+margins will be updated to center the systems on the page
+automatically. Also see @code{check-consistency}. This variable
+can also be set in a @code{\layout} block.
+@item left-margin
+@funindex left-margin
-There are a few variables that determine the horizontal dimensions
-on a page:
+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}.
-@table @code
+@item right-margin
+@funindex right-margin
-@item binding-offset
-@funindex binding-offset
+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}.
-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}.
+@item check-consistency
+@funindex check-consistency
-@item horizontal-shift
-@funindex horizontal-shift
+If set to true, 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 its default value (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.
-The amount that all systems (including titles and system
-separators) are shifted to the right. Default: @code{0.0}.
+@item ragged-right
+@funindex ragged-right
-@item indent
-@funindex indent
+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.
-The level of indentation for the first system in a score.
-Default: @code{15\mm}.
+@item ragged-last
+@funindex ragged-last
-@item inner-margin
-@funindex inner-margin
+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.
-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}.
+@end table
-@item left-margin
-@funindex left-margin
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-The margin between the left edge of the page and the beginning of
-each system. Default: @code{10\mm}.
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@item line-width
-@funindex line-width
-The width of music systems. Default: @code{paper-width} minus
-@code{left-margin} and @code{right-margin}.
+@node \paper variables for two-sided mode
+@unnumberedsubsubsec @code{\paper} variables for two-sided mode
+
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
+
+@table @code
+
+@item two-sided
+@funindex two-sided
+
+@cindex gutter
+@cindex binding gutter
+
+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}.
+
+@item inner-margin
+@funindex inner-margin
+
+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.
@item outer-margin
@funindex outer-margin
-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}.
+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 paper-width
-@funindex paper-width
+@item binding-offset
+@funindex binding-offset
-The width of the page. Default: the width of the current paper
-size. For details, see @ref{Paper size}.
+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
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@item right-margin
-@funindex right-margin
-The margin between the right edge of the page and the end of
-each system. Default: @code{10\mm}.
+@node \paper variables for shifts and indents
+@unnumberedsubsubsec @code{\paper} variables for shifts and indents
+
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
+
+@table @code
+
+@item horizontal-shift
+@funindex horizontal-shift
+
+@c This default value is buried in the middle of page.scm. -mp
+
+The amount that all systems (including titles and system
+separators) are shifted to the right. Default: @code{0.0\mm}.
+
+@item indent
+@funindex indent
+
+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. This variable can also be set in a @code{\layout}
+block.
@item short-indent
@funindex short-indent
The level of indentation for all systems in a score besides the
-first system. Default: @code{0}.
+first system. If the paper size is modified, this dimension's
+default value is scaled accordingly. This variable can also be
+set in a @code{\layout} block.
@end table
-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:
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-@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
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-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.
+Snippets:
+@rlsr{Spacing}.
-@example
-\paper @{
- left-margin = 30\mm
-@}
-@end example
-In this example, only @code{left-margin} is set. The value for
-@code{right-margin} will remain default, @code{line-width} is
-calculated automatically.
+@node Other \paper variables
+@subsection Other @code{\paper} variables
-@example
-\paper @{
- line-width = 150\mm
-@}
-@end example
+@menu
+* \paper variables for line breaking::
+* \paper variables for page breaking::
+* \paper variables for page numbering::
+* Miscellaneous \paper variables::
+@end menu
-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.
-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.
+@node \paper variables for line breaking
+@unnumberedsubsubsec @code{\paper} variables for line breaking
-@example
-\paper @{
- paper-width = 210\mm
- left-margin = 20\mm
- right-margin = 30\mm
- line-width = 100\mm
-@}
-@end example
+@c TODO: Mention that ly:optimal-breaking is on by default? -mp
-These checks can be avoided by setting @code{check-consistency}
-to false.
+@table @code
-@example
-\paper @{
- paper-width = 210\mm
- left-margin = 20\mm
- line-width = 200\mm
- check-consistency = ##f
-@}
-@end example
+@item max-systems-per-page
+@funindex max-systems-per-page
-@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 maximum number of systems that will be placed on a page. This
+is currently supported only by the @code{ly:optimal-breaking} algorithm.
+Default: unset.
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@item min-systems-per-page
+@funindex min-systems-per-page
+The minimum number of systems that will be placed on a page. This
+may cause pages to be overfilled if it is made too large. This is
+currently supported only by the @code{ly:optimal-breaking} algorithm.
+Default: unset.
+
+@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.
-@node Other layout variables
-@unnumberedsubsubsec Other layout variables
+@end table
-These variables can be used to adjust page layout in general.
+@seealso
+Notation Reference:
+@ref{Line breaking}.
-@table @code
-@item auto-first-page-number
-@funindex auto-first-page-number
+@node \paper variables for page breaking
+@unnumberedsubsubsec @code{\paper} variables for page breaking
-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}.
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
-@ignore
+@table @code
-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
-Default: @code{2}.
-
-@end ignore
+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-force}, so that we prefer blank pages after
+scores to blank pages within a score.
@item blank-last-page-force
@funindex blank-last-page-force
The penalty for ending the score on an odd-numbered page.
-Default: @code{0}.
@item blank-page-force
@funindex blank-page-force
The penalty for having a blank page in the middle of a
score. This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score. Default:
-@code{5}.
-
-@item check-consistency
-@funindex check-consistency
-
-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
-
-The value of the page number on the first page. Default:
-@code{#1}.
-
-@item max-systems-per-page
-@funindex max-systems-per-page
-
-The maximum number of systems that will be placed on a page. This
-is currently supported only by the @code{ly:optimal-breaking} algorithm.
-Default: unset.
+never consider blank pages in the middle of a score.
-@item min-systems-per-page
-@funindex min-systems-per-page
+@item page-breaking
+@funindex page-breaking
-The minimum number of systems that will be placed on a page. This
-may cause pages to be overfilled if it is made too large. This is
-currently supported only by the @code{ly:optimal-breaking} algorithm.
-Default: unset.
+The page-breaking algorithm to use. Choices are
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
+@code{ly:optimal-breaking}.
@item page-breaking-system-system-spacing
@funindex page-breaking-system-system-spacing
@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-spacing-weight
-@funindex page-spacing-weight
+@end table
-The relative importance of page (vertical) spacing and line
-(horizontal) spacing. High values will make page spacing more
-important. Default: @code{#10}.
+@seealso
+Notation Reference:
+@ref{Page breaking},
+@ref{Optimal page breaking},
+@ref{Optimal page turning},
+@ref{Minimal page breaking}.
-@item print-all-headers
-@funindex print-all-headers
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+
+@node \paper variables for page numbering
+@unnumberedsubsubsec @code{\paper} variables for page numbering
+
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
+
+@table @code
-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}.
+@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}.
+
+@item first-page-number
+@funindex first-page-number
+
+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}.
@item print-page-number
@funindex print-page-number
-If set to false, page numbers are not printed. Default:
-@code{##t}.
-
-@item ragged-bottom
-@funindex ragged-bottom
+If set to false, page numbers are not printed.
-If set to true, systems will not spread vertically across the
-page. This does not affect the last page. Default: @code{##f}.
-
-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{\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'' { c1 \break c1 \break c1 }
+ }
}
@end lilypond
-@item system-count
-@funindex system-count
-
-The number of systems to be used for a score.
-Default: unset.
-
-@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 two-sided
-@funindex two-sided
-
-@cindex gutter
-@cindex binding gutter
-
-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}.
-
@end table
@seealso
+Installed Files:
+@file{ly/titling-init.ly}.
+
Snippets:
@rlsr{Spacing}.
The default page header puts the page number and the @code{instrument}
field from the @code{\header} block on a line.
-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.
+@node Score layout
+@section Score layout
-@node Music layout
-@section Music layout
+This section discusses score layout options for the @code{\layout}
+block.
@menu
+* The \layout block::
* Setting the staff size::
-* Score layout::
@end menu
+@node The \layout block
+@subsection The @code{\layout} block
+
+@funindex \layout
+
+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:
+
+@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}. The @code{\paper}
+variables that can appear in a @code{\layout} block are:
+
+@itemize
+
+@item
+@code{line-width}, @code{ragged-right} and @code{ragged-last}
+(see @ref{\paper variables for widths and margins})
+
+@item
+@code{indent} and @code{short-indent}
+(see @ref{\paper variables for shifts and indents})
+
+@item
+@code{system-count}
+(see @ref{\paper variables for line breaking})
+
+@end itemize
+
+Here is an example @code{\layout} block:
+
+@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
+
+
+@seealso
+Notation Reference:
+@ref{Changing context default settings}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
@node Setting the staff size
@subsection Setting the staff size
To set the staff size individually for each score, use
@example
\score@{
- ...
- \layout@{
- #(layout-set-staff-size 15)
+ @dots{}
+ \layout @{
+ #(layout-set-staff-size 15)
@}
@}
@end example
staff lines.
-@node Score layout
-@subsection Score layout
-
-@funindex \layout
-
-While @code{\paper} contains settings that relate to the page formatting
-of the whole document, @code{\layout} contains settings for score-specific
-layout.
-
-@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
- @}
-@}
-@end example
-
-
-@seealso
-Notation Reference:
-@ref{Changing context default settings}.
-
-Snippets:
-@rlsr{Spacing}.
-
-
@node Breaks
@section Breaks
Line breaks are normally determined automatically. They are chosen
so that lines look neither cramped nor loose, and consecutive
-lines have similar density. Occasionally you might want to
-override the automatic breaks; you can do this by specifying
-@code{\break}. This will force a line break at this point. However,
-line breaks can only occur at the end of @q{complete} bars, i.e.,
-where there are no notes or tuplets left @q{hanging} over the bar
-line. If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar ""},
-although again there must be no notes left hanging over in any of
-the staves at this point, or it will be ignored.
-
-The opposite command, @code{\noBreak}, forbids a line break at the
-bar line where it is inserted.
+lines have similar density.
+
+To manually force a line break at a bar line, use the
+@code{\break} command:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c c | \break
+c4 c c c |
+@end lilypond
+
+By default, a @code{\break} in the middle of a measure is ignored,
+and a warning is printed. To force a line break in the middle of
+a measure, add an invisible bar line with @w{@samp{\bar ""}}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c
+\bar "" \break
+c |
+c4 c c c |
+@end lilypond
+
+A @code{\break} occuring at a bar line is also ignored if the
+previous measure ends in the middle of a note, such as when a
+tuplet begins and ends in different measures. To allow
+@code{\break} commands to work in these situations, remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context.
+Note that manually forced line breaks have to be added in parallel
+with the music:
+
+@lilypond[quote,ragged-right,verbatim]
+\new Voice \with {
+ \remove Forbid_line_break_engraver
+} \relative c'' {
+ <<
+ { c2. \times 2/3 { c4 c c } c2. | }
+ { s1 | \break s1 | }
+ >>
+}
+@end lilypond
+
+Similarly, line breaks are normally forbidden when beams cross bar
+lines. This behavior can be changed by setting
+@code{\override Beam #'breakable = ##t}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+\override Beam #'breakable = ##t
+c2. c8[ c | \break
+c8 c] c2. |
+@end lilypond
+
+The @code{\noBreak} command forbids a line break at the bar line
+where it is inserted.
The most basic settings influencing line spacing are @code{indent}
and @code{line-width}. They are set in the @code{\layout} block.
@example
\layout @{
-indent = #0
-line-width = #150
-ragged-last = ##t
+ indent = 0\mm
+ line-width = 150\mm
+ ragged-last = ##t
@}
@end example
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
+A linebreaking configuration can be saved as a @file{.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
@seealso
-Internals Reference:
-@rinternals{LineBreakEvent}.
+Notation Reference:
+@ref{\paper variables for line breaking}.
Snippets:
@rlsr{Spacing}.
-
-@knownissues
-
-Line breaks can only occur if there is a @q{proper} bar line. A note
-which is hanging over a bar line is not proper, such as
-
-@lilypond[quote,ragged-right,relative=2,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.
-
-@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
-
-Similarly, line breaks are normally forbidden when beams cross bar
-lines. This behavior can be changed by setting
-@code{\override Beam #'breakable = ##t}.
+Internals Reference:
+@rinternals{LineBreakEvent}.
@node Page breaking
@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}.
+respectively will not be justified vertically. See
+@ref{Fixed vertical spacing \paper variables}.
Page breaks are computed by the @code{page-breaking} function. LilyPond
provides three algorithms for computing page breaks,
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
\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{}
@seealso
+Notation Reference:
+@ref{\paper variables for page breaking}.
+
Snippets:
@rlsr{Spacing}.
@example
\paper @{
- #(define page-breaking ly:minimal-breaking)
+ page-breaking = #ly:minimal-breaking
@}
@end example
ragged-bottom = ##t
}
+music = \relative c'' { c8 c c c }
+
\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 }
- }
+ \repeat unfold 2 { \music } \break
+ \repeat unfold 4 { \music } \break
+ \repeat unfold 6 { \music } \break
+ \repeat unfold 8 { \music } \pageBreak
+ \repeat unfold 8 { \music } \break
+ \repeat unfold 6 { \music } \break
+ \repeat unfold 4 { \music } \break
+ \repeat unfold 2 { \music }
+ }
\layout {
\context {
\Score
Line- and page-breaking information usually appears within note entry directly.
@example
+music = \relative c'' @{ c4 c c c @}
+
\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 @}
+ \repeat unfold 2 @{ \music @} \break
+ \repeat unfold 3 @{ \music @}
@}
@}
@end example
breaking layout information.
@lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
\score {
\new Staff <<
\new Voice {
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 }
+ \repeat unfold 2 { \music }
+ \repeat unfold 3 { \music }
+ \repeat unfold 6 { \music }
+ \repeat unfold 5 { \music }
}
>>
}
@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
@lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
\score {
\new Staff <<
\new Voice {
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 }
+ \repeat unfold 2 { \music }
+ \repeat unfold 3 { \music }
+ \repeat unfold 6 { \music }
+ \repeat unfold 5 { \music }
}
>>
}
within systems, one for each of the following categories:
@itemize
-@item @emph{ungrouped staves},
-@item @emph{grouped staves} (staves within a staff-group such as
+
+@item
+@emph{ungrouped staves},
+
+@item
+@emph{grouped staves} (staves within a staff-group such as
@code{ChoirStaff}, etc.), and
-@item @emph{non-staff lines} (such as @code{Lyrics},
-@code{ChordNames}, etc.).
+
+@item
+@emph{non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
+etc.).
+
@end itemize
@c TODO: Clarify this. This almost implies that non-staff lines
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 dimensions}.
+@ref{Flexible vertical spacing \paper variables}.
@menu
* Within-system spacing properties::
of these reference points:
@lilypond[quote,noragged-right,line-width=110\mm]
-#(define zero-space '((padding . -inf.0) (space . 0)))
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
alignToZero = \with {
\override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
Each of the vertical spacing grob properties (except
@code{staff-affinity}) is stored as an alist (association list),
and each uses the same alist structure as the @code{\paper}
-spacing variables discussed in @ref{Flexible vertical dimensions}.
-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.
+spacing variables discussed in
+@ref{Flexible vertical spacing \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.
The following example demonstrates the two ways these alists can
be modified. The first declaration updates one key-value
@example
\new Staff \with @{
- \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
@} @{ @dots{} @}
\new Staff \with @{
\override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . 1)
- (space . 10)
+ #'((basic-distance . 10)
(minimum-distance . 9)
+ (padding . 1)
(stretchability . 10))
@} @{ @dots{} @}
@end example
\layout @{
\context @{
\Staff
- \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
@}
@}
@end example
@end table
@seealso
-Installed files:
+Installed Files:
@file{ly/engraver-init.ly},
@file{scm/define-grobs.scm}.
\context {
\Staff
\override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . 1)
- (space . 8)
- (minimum-distance . 7))
+ #'((basic-distance . 8)
+ (minimum-distance . 7)
+ (padding . 1))
}
}
\new StaffGroup <<
- % The very low note here needs more room than 'space can
- % provide, so the distance between this staff and the next is
- % determined by 'padding.
+ % 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, 'space 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 'space.
+ % 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 'space is 0.
+ % collide. The lowest acceptable value for 'basic-distance is 0.
\new Staff \with {
\override VerticalAxisGroup #'staff-staff-spacing =
- #'((padding . -10)
- (space . 3.5))
+ #'((basic-distance . 3.5)
+ (padding . -10))
} { \clef bass g2 r | }
\new Staff { \clef bass g2 r | }
>>
\context {
\Score
\override StaffGrouper #'staff-staff-spacing #'padding = #0
- \override StaffGrouper #'staff-staff-spacing #'space = #1
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
}
}
<<
\new PianoStaff \with {
- \override StaffGrouper #'staffgroup-staff-spacing #'space = #20
+ \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
} <<
\new Staff { c'1 }
\new Staff { c'1 }
\new StaffGroup
<<
\new Staff \with {
- \override VerticalAxisGroup #'staff-staff-spacing = #'((space . 30))
+ \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
} { c'1 }
\new Lyrics \with {
\override VerticalAxisGroup #'staff-affinity = #UP
@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 three different settings:
@itemize
@item @code{X-offset}
#'line-break-system-details #'((Y-offset . 40))
\overrideProperty NonMusicalPaperColumn
- #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
+ #'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 #'((X-offset . 20) (Y-offset . 40)
+ #'line-break-system-details #'((X-offset . 20)
+ (Y-offset . 40)
(alignment-distances . (15)))
@end example
@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 {
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 {
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 {
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 {
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 @{
- system-system-spacing = #'((padding . 0) (space . 0.1))
+ system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
ragged-last-bottom = ##f
ragged-bottom = ##f
@}
@seealso
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Changing horizontal spacing}.
Snippets:
projects / lilypond.git / blobdiff