Guide, node Updating translation committishes..
@end ignore
-@c \version "2.13.36"
+@c \version "2.16.0"
@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
-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
+@code{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
+@code{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
+which must always be placed in a @code{\paper} block.
+
+If the @code{set-default-paper-size} function is used in the toplevel
+scope, it must come before the 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.
-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}.
+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}.
-@c TODO add a new appendix for paper sizes (auto-generated) -pm
+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}.
-@warning{The default paper size is @code{a4}.}
+@c An appendix entry exists for paper sizes but is not auto-generated
-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.
+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,
-@cindex orientation
-@cindex landscape
+@example
+#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))
-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.
+\paper @{
+ #(set-paper-size "my size")
+@}
+@end example
+
+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
+
+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.
@example
#(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.
-
+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:
-@seealso
-Installed Files:
-@file{scm/@/paper@/.scm}.
-
-Snippets:
-@rlsr{Spacing}.
+@example
+#(set-default-paper-size "a6landscape")
+@end example
+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.
-@node Page formatting
-@subsection Page formatting
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size},
+@ref{Predefined paper sizes}.
-@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 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}). 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 false. 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}.
-@node Flexible vertical dimensions
-@unnumberedsubsubsec Flexible vertical dimensions
+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.
+
+
+@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
+@node Structure of flexible vertical spacing alists
+@unnumberedsubsubsec Structure of flexible vertical spacing alists
-Each of these variables is an alist (association list) containing
-four @emph{keys}:
+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.
+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.
-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:
+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 @{
- 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
-
-@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{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{\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:
-
-@table @code
+@menu
+* \paper variables for widths and margins::
+* \paper variables for two-sided mode::
+* \paper variables for shifts and indents::
+@end menu
-@item binding-offset
-@funindex binding-offset
-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}.
+@node \paper variables for widths and margins
+@unnumberedsubsubsec @code{\paper} variables for widths and margins
-@item horizontal-shift
-@funindex horizontal-shift
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
-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}.
+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
-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 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.
-@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{\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{\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. This variable can also be set in a @code{\layout}
+block.
-@end ignore
+@item short-indent
+@funindex short-indent
+
+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. This variable can also be
+set in a @code{\layout} block.
+
+@end table
+
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-@item blank-last-page-force
-@funindex blank-last-page-force
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-The penalty for ending the score on an odd-numbered page.
-Default: @code{0}.
+Snippets:
+@rlsr{Spacing}.
-@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}.
+@node Other \paper variables
+@subsection Other @code{\paper} variables
-@item check-consistency
-@funindex check-consistency
+@menu
+* \paper variables for line breaking::
+* \paper variables for page breaking::
+* \paper variables for page numbering::
+* Miscellaneous \paper variables::
+@end menu
-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 \paper variables for line breaking
+@unnumberedsubsubsec @code{\paper} variables for line breaking
-The value of the page number on the first page. Default:
-@code{#1}.
+@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 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{\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-line-breaking} and @code{ly:optimal-breaking}
+(the default).
+
@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.
+
+@end table
+
+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}).
+
+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 values are penalties, i.e. the higher the value the less likely
+will be the associated action relative to other choices.
+
+@table @code
+
+@item blank-page-penalty
+@funindex blank-page-penalty
+
+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-line page breaking}.
+
+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
+
+@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
+
+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.
+
+@cindex page numbers, suppress
+@item print-page-number
+@funindex print-page-number
+
+If set to false, page numbers are not printed.
+
+@end table
+
+@seealso
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+@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.
+
+
+@node Miscellaneous \paper variables
+@unnumberedsubsubsec Miscellaneous @code{\paper} variables
+
+@table @code
@item page-spacing-weight
@funindex page-spacing-weight
The relative importance of page (vertical) spacing and line
(horizontal) spacing. High values will make page spacing more
-important. Default: @code{#10}.
+important. Default: @code{10}.
@item print-all-headers
@funindex print-all-headers
-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}.
+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 print-first-page-number
-@funindex print-first-page-number
+@item system-separator-markup
+@funindex system-separator-markup
-If set to true, a page number is printed on the first page.
-Default: @code{##f}.
+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:
-@item print-page-number
-@funindex print-page-number
+@lilypond[quote,verbatim,noragged-right,line-width=30\mm]
+#(set-default-paper-size "a8")
+
+\book {
+ \paper {
+ system-separator-markup = \slashSeparator
+ }
+ \header {
+ tagline = ##f
+ }
+ \score {
+ \relative c'' { c1 \break c1 \break c1 }
+ }
+}
+@end lilypond
-If set to false, page numbers are not printed. Default:
-@code{##t}.
+@end table
-@item ragged-bottom
-@funindex ragged-bottom
+@seealso
+Installed Files:
+@file{ly/titling-init.ly}.
-If set to true, systems will not spread vertically across the
-page. This does not affect the last page. Default: @code{##f}.
+Snippets:
+@rlsr{Spacing}.
-This should be set to true for pieces that have only two or three
-systems per page, for example orchestral scores.
+@knownissues
+The default page header puts the page number and the @code{instrument}
+field from the @code{\header} block on a line.
-@item ragged-last
-@funindex ragged-last
-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}.
+@node Score layout
+@section Score layout
-@item ragged-last-bottom
-@funindex ragged-last-bottom
+This section discusses score layout options for the @code{\layout}
+block.
-If set to false, systems will spread vertically across the last
-page. Default: @code{##t}.
+@menu
+* The \layout block::
+* Setting the staff size::
+@end menu
-Pieces that amply fill two pages or more should have this set to
-true.
-It also affects the last page of book parts, ie parts of a book created
-with @code{\bookpart} blocks.
+@node The \layout block
+@subsection The @code{\layout} block
-@item ragged-right
-@funindex ragged-right
+@funindex \layout
-If set to true, systems will not fill the line width. Instead,
-systems end at their natural horizontal length. 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:
-If the score has only one system, the default value is @code{##t}.
+@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
-@item system-separator-markup
-@funindex system-separator-markup
+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
-A markup object that is inserted between systems. This is often
-used for orchestral scores. Default: unset.
+@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
-The markup command @code{\slashSeparator} is provided as a sensible
-default, for 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.
-@lilypond[quote,ragged-right]
-#(set-default-paper-size "a6" 'landscape)
-\book {
- \score {
- \relative c' { c1 \break c1 }
- }
- \paper {
- system-separator-markup = \slashSeparator
- }
-}
-@end lilypond
+For example, if this block:
-@item system-count
-@funindex system-count
+@example
+\layout @{
+ \context @{
+ \Voice
+ \override TextScript #'color = #magenta
+ \override Glissando #'thickness = #1.5
+ @}
+@}
+@end example
-The number of systems to be used for a score.
-Default: unset.
+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.
-@item systems-per-page
-@funindex systems-per-page
+@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.
-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.
+If a variable is defined like this:
-@item two-sided
-@funindex two-sided
+@example
+layoutVariable = \layout @{
+ \context @{
+ \Voice
+ \override NoteHead #'font-size = #4
+ @}
+@}
+@end example
-@cindex gutter
-@cindex binding gutter
+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.
-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}.
+The variable can then be used inside another @code{\layout} block,
+for example:
-@end table
+@example
+\layout @{
+ \layoutVariable
+ \context @{
+ \Voice
+ \override NoteHead #'color = #red
+ @}
+@}
+@end example
+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.
-@seealso
-Snippets:
-@rlsr{Spacing}.
+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
-@knownissues
+plus the @code{indent} and the @code{StaffGrouper} overrides.
-The default page header puts the page number and the @code{instrument}
-field from the @code{\header} block on a line.
+But if the variable had already been defined before the first
+@code{\layout} block the current configuration would now contain
+only
-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.
+@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.
-@node Music layout
-@section Music layout
+@seealso
+Notation Reference:
+@ref{Changing context default settings}.
-@menu
-* Setting the staff size::
-* Score layout::
-@end menu
+Snippets:
+@rlsr{Spacing}.
@node 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
@rinternals{StaffSymbol}) can be used to tune the size for individual
staves. The sizes of individual staves are relative to the global size.
-
@seealso
Notation Reference:
@ref{Selecting notation font size}.
Snippets:
@rlsr{Spacing}.
-
@knownissues
-
@code{layout-set-staff-size} does not change the distance between the
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
* Optimal page breaking::
* Optimal page turning::
* Minimal page breaking::
+* One-line page breaking::
* Explicit breaks::
* Using an extra voice for breaks::
@end menu
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} occurring at a bar line is also ignored if the
+previous measure ends in the middle of a note, such as when a
+tuplet begins and ends in different measures. To allow
+@code{\break} commands to work in these situations, remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context.
+Note that manually forced line breaks have to be added in parallel
+with the music:
+
+@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
@code{\noBreak}.
@endpredefined
-
@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
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}.
+@code{#t} the systems on all pages or just the last page
+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{}
@code{\noPageBreak}.
@endpredefined
-
@seealso
+Notation Reference:
+@ref{\paper variables for page breaking}.
+
Snippets:
@rlsr{Spacing}.
cramping and stretching, both horizontally and vertically. Unlike
@code{ly:page-turn-breaking}, it has no concept of page turns.
-
@seealso
Snippets:
@rlsr{Spacing}.
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
+@code{minimumPageTurnLength} is @code{(ly:make-moment 1 1)}. If you want
to disable page turns, you can set it to something very large.
@example
@code{\allowPageTurn}, may also be used at top-level, between scores and
top-level markups.
-
@predefined
@funindex \pageTurn
@code{\pageTurn},
@code{\allowPageTurn}.
@endpredefined
-
@seealso
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
Snippets:
@rlsr{Spacing}.
-
@knownissues
-
There should only be one @code{Page_turn_engraver} in a score. If there is more
than one, they will interfere with each other.
@example
\paper @{
- #(define page-breaking ly:minimal-breaking)
+ page-breaking = #ly:minimal-breaking
@}
@end example
-
@seealso
Snippets:
@rlsr{Spacing}.
+@node One-line page breaking
+@subsection 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. This page breaking function does not
+typeset titles or margins; only the score will be displayed.
+
+The page width will be 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 will be ignored, although
+@code{left-margin} and @code{right-margin} will
+still be honored. The height of the page will
+be left unmodified.
@node Explicit breaks
@subsection Explicit breaks
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
}
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
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 }
}
>>
}
@end lilypond
-
@seealso
Notation Reference:
@ref{Vertical spacing}.
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
+@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
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::
@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
but only if explicitly called. These properties are described
individually at the end of this section.
-Except for the @code{staff-affinity} property (of the
-@code{VerticalAxisGroup} grob), each of these grob properties 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}.
-
-The @emph{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:
+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
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 #'inter-staff-spacing = #zero-space
- \override VerticalAxisGroup #'inter-loose-line-spacing = #zero-space
+ \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
+ \override VerticalAxisGroup #'nonstaff-nonstaff-spacing = #zero-space
}
lowerCaseChords = \with {
chordNameLowercaseMinor = ##t
#(define-music-function
(parser location context)
(string?)
- #{ s1*0^\markup { \typewriter $context } #})
+ #{ s1*0^\markup { \typewriter #context } #})
\layout {
\context { \Dynamics \alignToZero }
\context { \FiguredBass \alignToZero }
\context { \Lyrics \alignToZero }
- \context { \NoteNames \alignToZero }
- \context { \ChordNames \alignToZero \lowerCaseChords }
+ \context { \NoteNames \alignToZero \staffAffinityDown }
+ \context { \ChordNames \alignToZero
+ \staffAffinityDown
+ \lowerCaseChords }
\context { \FretBoards \alignToZero \staffAffinityDown }
\context { \Score
\override BarLine #'stencil = ##f
\override DynamicText #'self-alignment-X = #-1
\override FretBoard #'X-offset = #1.75
+ \override InstrumentName #'minimum-Y-extent = #'(-2 . 2)
+ \override InstrumentName #'extra-offset = #'(0 . -0.5)
\override TextScript #'minimum-Y-extent = #'(-2 . 3)
\override TimeSignature #'stencil = ##f
}
\new RhythmicStaff {
\set RhythmicStaff.instrumentName = #"baseline "
\textLengthOn
- \labelContext "ChordNames" s1 |
- \labelContext "NoteNames" s1 |
+ \labelContext "ChordNames " s1 |
+ \labelContext "NoteNames " s1 |
\labelContext "Lyrics" s1 |
}
\new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
\set RhythmicStaff.instrumentName = #"vertical center "
\labelContext "Dynamics" s1*3
}
- \new Dynamics { s2\mp s\fp }
+ \new Dynamics { s1\mp s\fp }
>>
%% The reference point for FiguredBass is its highest point
>>
@end lilypond
-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.
+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}. 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 #'next-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'default-staff-staff-spacing
+ #'basic-distance = #10
@} @{ @dots{} @}
\new Staff \with @{
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((padding . 1)
- (space . 10)
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((basic-distance . 10)
(minimum-distance . 9)
+ (padding . 1)
(stretchability . 10))
@} @{ @dots{} @}
@end example
\layout @{
\context @{
\Staff
- \override VerticalAxisGroup #'next-staff-spacing #'space = #10
+ \override VerticalAxisGroup #'default-staff-staff-spacing
+ #'basic-distance = #10
@}
@}
@end example
-The global defaults for the following grob properties are defined
-in @file{scm/define-grobs.scm}:
-
-@itemize
-@item @code{StaffGrouper} properties:
-@itemize
-@item @code{between-staff-spacing}
-@item @code{after-last-staff-spacing}
-@end itemize
-@item @code{VerticalAxisGroup} properties:
-@itemize
-@item @code{default-next-staff-spacing}
-@item @code{non-affinity-spacing}
-@end itemize
-@end itemize
-
-Default overrides for specific types of non-staff lines can be
-found in the relevant context definitions in
-@file{ly/engraver-init.ly}.
+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}.
@subsubheading Properties of the @code{VerticalAxisGroup} grob
@code{\override} at the @code{Staff} level (or equivalent).
@table @code
-@item next-staff-spacing
-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. For a grouped staff, if
-@code{next-staff-spacing} is set, it will be used instead of the
-relevant @code{StaffGrouper} property
-(@code{between-staff-spacing} or @code{after-last-staff-spacing}).
-If unset, the @code{default-next-staff-spacing} property is used,
-unless the staff is part of a staff-group and the appropriate
-@code{StaffGrouper} property is set.
-
-@item default-next-staff-spacing
-The value to use for @code{next-staff-spacing} when it is unset,
-for ungrouped staves and for grouped staves that do not have the
-relevant @code{StaffGrouper} property set
-(@code{between-staff-spacing} or @code{after-last-staff-spacing}).
+@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
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} to @code{#f} will cause a non-staff line to
-be treated as a staff. Conversely, setting @code{staff-affinity}
-(to @code{UP}, @code{DOWN}, or @code{CENTER}) for a staff will
-cause it to be treated as a non-staff line.
-
-@c TODO: verify last clause below ("even if other...")
+@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 inter-staff-spacing
+@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{inter-staff-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.
-
-@item inter-loose-line-spacing
+@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 reference staff, and
+are on the same side of the related staff, and
@code{staff-affinity} is either @code{UP} or @code{DOWN}.
-@item non-affinity-spacing
+@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}
@code{\override} at the @code{StaffGroup} level (or equivalent).
@table @code
-@item between-staff-spacing
+@item staff-staff-spacing
The distance between consecutive staves within the current
-staff-group. The @code{next-staff-spacing} property of an
-individual staff's @code{VerticalAxisGroup} grob will be used
-instead for any staves in the staff-group that have it set. If
-both @code{between-staff-spacing} and @code{next-staff-spacing}
-are unset, the @code{default-next-staff-spacing} property of each
-staff's @code{VerticalAxisGroup} grob is used.
-
-@item after-last-staff-spacing
+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{next-staff-spacing} property of an individual staff's
-@code{VerticalAxisGroup} grob will be used instead for any staves
-in the staff-group that have it set. If both
-@code{after-last-staff-spacing} and @code{next-staff-spacing} are
-unset, the @code{default-next-staff-spacing} property of each
-staff's @code{VerticalAxisGroup} grob is used.
+@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
+@seealso
+Notation Reference:
+@ref{Flexible vertical spacing \paper variables},
+@ref{Modifying alists}.
+
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
+
@node Spacing of ungrouped staves
@unnumberedsubsubsec Spacing of ungrouped staves
@itemize
@item @code{VerticalAxisGroup} properties:
@itemize
-@item @code{next-staff-spacing}
+@item @code{default-staff-staff-spacing}
+@item @code{staff-staff-spacing}
@end itemize
@end itemize
Additional properties are involved for staves that are part of a
staff-group; see @ref{Spacing of grouped staves}.
-The following example shows how the @code{next-staff-spacing}
-property can affect the spacing of ungrouped staves:
+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,quote,staffsize=16]
\layout {
\context {
\Staff
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((padding . 1)
- (space . 8)
- (minimum-distance . 7))
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((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 #'next-staff-spacing =
- #'((padding . -10)
- (space . 3.5))
+ \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
@itemize
@item @code{VerticalAxisGroup} properties:
@itemize
-@item @code{next-staff-spacing}
-@item @code{default-next-staff-spacing}
+@item @code{staff-staff-spacing}
@end itemize
@item @code{StaffGrouper} properties:
@itemize
-@item @code{between-staff-spacing}
-@item @code{after-last-staff-spacing}
+@item @code{staff-staff-spacing}
+@item @code{staffgroup-staff-spacing}
@end itemize
@end itemize
\layout {
\context {
\Score
- \override StaffGrouper #'between-staff-spacing #'padding = #0
- \override StaffGrouper #'between-staff-spacing #'space = #1
+ \override StaffGrouper #'staff-staff-spacing #'padding = #0
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
}
}
<<
\new PianoStaff \with {
- \override StaffGrouper #'after-last-staff-spacing #'space = #20
+ \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
} <<
\new Staff { c'1 }
\new Staff { c'1 }
>>
@end lilypond
+@seealso
+Installed Files:
+@file{scm/define-grobs.scm}.
+
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
+
@node Spacing of non-staff lines
@unnumberedsubsubsec Spacing of non-staff lines
@item @code{VerticalAxisGroup} properties:
@itemize
@item @code{staff-affinity}
-@item @code{inter-staff-spacing}
-@item @code{inter-loose-line-spacing}
-@item @code{non-affinity-spacing}
+@item @code{nonstaff-relatedstaff-spacing}
+@item @code{nonstaff-nonstaff-spacing}
+@item @code{nonstaff-unrelatedstaff-spacing}
@end itemize
@end itemize
@ref{Within-system spacing properties}.
The following example shows how the
-@code{inter-loose-line-spacing} property can affect the spacing of
-consecutive non-staff lines. Here, by setting 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:
\context {
\Lyrics
\override VerticalAxisGroup
- #'inter-loose-line-spacing #'stretchability = #1000
+ #'nonstaff-nonstaff-spacing #'stretchability = #1000
}
}
\new StaffGroup
<<
\new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing = #'((space . 30))
+ \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
} { c'1 }
\new Lyrics \with {
\override VerticalAxisGroup #'staff-affinity = #UP
>>
@end lilypond
-
@seealso
Installed Files:
@file{ly/engraver-init.ly},
Internals Reference:
@rinternals{Contexts},
-@rinternals{VerticalAxisGroup},
-@rinternals{StaffGrouper},
-@rinternals{VerticalAlignment},
-@rinternals{Axis_group_engraver}.
+@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 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 {
passed to these different settings will avoid this.
@end itemize
-
@seealso
Snippets:
@rlsr{Spacing}.
previously-positioned grobs can be controlled with
@code{outside-staff-padding}.
-@lilypond[quote,ragged-right,relative=2,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
\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''2
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
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.
+@code{lilypond} with the @option{--verbose} option.
These durations may also be customized. If you set the
@code{common-shortest-duration} in @rinternals{SpacingSpanner}, then
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
+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
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
@end example
@code{SpacingSpanner} object, and hence new @code{\override}s
may be used in that location.
-
@seealso
Snippets:
@rlsr{Spacing}.
\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
@end lilypond
-
@seealso
Snippets:
@rlsr{Spacing}.
@}
@end example
-
@seealso
Snippets:
@rlsr{Spacing}.
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
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.
}
@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:
to break across systems and pages. See the respective parts of the manual
for these related settings.
-
@seealso
Notation Reference:
@ref{New spacing area}.
@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.
(@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 @{
- system-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
@end itemize
-
@seealso
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Changing horizontal spacing}.
Snippets:
projects / lilypond.git / blobdiff