Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.14.0"
@ignore
GDP TODO list
staff lines accordingly."
Actually I found, that the @internalsref{StaffSymbol} at line 481
-sends to an uncomplete
-documentation. The property staff-space is not explained here. I
+sends to an incomplete
+documentation. The property staff-space is not explained here. I
thought Y-extent might be of
help, but it is in turn explained by x-space which again is
-missing from the list. Who has the
+missing from the list. Who has the
knowledge to fix this?
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
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+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}.
@seealso
+Notation Reference:
+@ref{Fixed vertical spacing \paper variables},
+@ref{Horizontal spacing \paper variables}.
+
Installed Files:
-@file{scm/@/paper@/.scm}.
+@file{ly/paper-defaults-init.ly},
+@file{scm/paper.scm}.
-Snippets:
-@rlsr{Spacing}.
+@node Fixed vertical spacing \paper variables
+@subsection Fixed vertical spacing @code{\paper} variables
-@node Page formatting
-@subsection Page formatting
+@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}.}
-Margins, headers, and footers and other layout variables are
-automatically set according to the paper size.
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
-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.
+@table @code
+@item paper-height
+@funindex paper-height
-This section lists and describes a number of paper variables that
-may be altered.
+The height of the page, unset by default. Note that the automatic
+scaling of some vertical dimensions is not affected by this.
-@menu
-* Vertical dimensions::
-* Horizontal dimensions::
-* Other layout variables::
-@end menu
+@item top-margin
+@funindex top-margin
+The margin between the top of the page and the top of the
+printable area. If the paper size is modified, this dimension's
+default value is scaled accordingly.
-@node Vertical dimensions
-@unnumberedsubsubsec Vertical dimensions
+@item bottom-margin
+@funindex bottom-margin
-These variables are used to set different vertical dimensions on a
-page:
+The margin between the bottom of the printable area and the bottom
+of the page. If the paper size is modified, this dimension's
+default value is scaled accordingly.
-@funindex \paper
+@item ragged-bottom
+@funindex ragged-bottom
-@table @code
+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 after-title-spacing
-@funindex after-title-spacing
-
-Specifies how to calculate the space between a title (or top-level markup)
-and the system that follows it. This is an associative list with five
-components:
-@itemize @bullet
-@item @var{space} -- the amount of stretchable space between the baseline
-of a title and the center of the staff that follows it;
-@item @var{padding} -- the minimum amount of whitespace that must be
-present between a title and the staff that follows it;
-@item @var{stretchability} -- the ease with which the stretchable
-space increases when a page is stretched.
-If this is zero, the distance to the next staff will not stretch at all;
-@item @var{minimum-distance} -- the minimum distance to place between
-the baseline of a title and the center of the staff that follows it. This differs
-from @var{padding} in that the height of a staff has no effect on
-the application of @var{minimum-distance} (whereas the height of a
-staff is crucial for @var{padding}).
-@end itemize
+@item ragged-last-bottom
+@funindex ragged-last-bottom
-If a page has a ragged bottom, @var{space} is not stretched. In particular, the
-resulting distance on such a page is the largest of
-@itemize @bullet
-@item @var{space},
-@item @var{minimum-distance}, and
-@item @var{padding} plus the smallest distance necessary to eliminate overlap.
-@end itemize
+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.
-@item before-title-spacing
-@funindex before-title-spacing
+@end table
-Specifies the spacing between a system and the title (or top-level markup) that
-follows it.
-The distances are measured from the center of the last staff in the system to
-the baseline of the title that follows it. See @var{after-title-spacing}.
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-@item between-scores-system-spacing
-@funindex between-scores-system-spacing
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-Specifies the spacing between two systems if they are in different scores, but
-there is no title between them. See @var{after-title-spacing}.
+Snippets:
+@rlsr{Spacing}.
-@item between-system-spacing
-@funindex between-system-spacing
+@knownissues
-Specifies the spacing between the center of the bottom staff of one system
-and the center of the top staff of the following system. See @var{after-title-spacing}.
+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.
-@item between-title-spacing
-@funindex between-title-spacing
-Specifies the spacing between two titles (or top-level markups).
-The distances are measured from the baseline of the first title to the baseline
-of the second. See @var{after-title-spacing}.
+@node Flexible vertical spacing \paper variables
+@subsection Flexible vertical spacing @code{\paper} variables
-@item bottom-margin
-@funindex bottom-margin
+In most cases, it is preferable for the vertical distances between
+certain items (such as margins, titles, systems, and separate
+scores) to be flexible, so that they stretch and compress nicely
+according to each situation. A number of @code{\paper} variables
+(listed below) are available to fine-tune the stretching behavior
+of these dimensions.
-The margin between footer and bottom of the page. Default:
-@code{6\mm}.
+Note that the @code{\paper} variables discussed in this section do
+not control the spacing of staves within individual systems.
+Within-system spacing is controlled by grob properties, with
+settings typically entered inside a @code{\score} or
+@code{\layout} block, and not inside a @code{\paper} block. See
+@ref{Flexible vertical spacing within systems}.
-@item bottom-system-spacing
-@funindex bottom-system-spacing
+@menu
+* Structure of flexible vertical spacing alists::
+* List of flexible vertical spacing \paper variables::
+@end menu
-Specifies the spacing from the center of the last staff (or the
-baseline of the last top-level markup) to the bottom of the
-printable area (ie. the top of the bottom margin).
-See @var{after-title-spacing}.
-@item top-title-spacing
-@funindex top-title-spacing
+@node Structure of flexible vertical spacing alists
+@unnumberedsubsubsec Structure of flexible vertical spacing alists
-Specifies the spacing from the top of the printable area (ie.
-the bottom of the top margin) to the baseline of the title.
-See @var{after-title-spacing}.
+Each of the flexible vertical spacing @code{\paper} variables is
+an alist (association list) containing four @emph{keys}:
-@item top-system-spacing
-@funindex top-system-spacing
+@itemize
-Specifies the spacing from the top of the printable area (ie.
-the bottom of the top margin) to the center of the first staff.
-This only takes effect if there is no title at the top of the
-page (in which case @var{top-title-spacing} is used instead).
-See @var{after-title-spacing}.
+@item
+@code{basic-distance} -- the vertical distance, measured in
+staff-spaces, between the @emph{reference points} of the two
+items, when no collisions would result, and no stretching or
+compressing is in effect. The reference point of a (title or
+top-level) markup is its highest point, and the reference point of
+a system is the vertical center of the nearest @code{StaffSymbol}
+-- even if a non-staff line (such as a @code{Lyrics} context) is
+in the way. Values for @code{basic-distance} that are less than
+either @code{padding} or @code{minimum-distance} are not
+meaningful, since the resulting distance will never be less than
+either @code{padding} or @code{minimum-distance}.
-@item paper-height
-@funindex paper-height
+@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.}
-The height of the page. Default: the height of the current paper
-size. For details, see @ref{Paper size}.
+@c TODO: explain skylines somewhere and xref to it from here.
-@item top-margin
-@funindex top-margin
+@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.
-The margin between header and top of the page. Default:
-@code{5\mm}.
+@item
+@code{stretchability} -- a unitless measure of the dimension's
+relative propensity to stretch. If zero, the distance will not
+stretch (unless collisions would result). When positive, the
+significance of a particular dimension's @code{stretchability}
+value lies only in its relation to the @code{stretchability}
+values of the other dimensions. For example, if one dimension has
+twice the @code{stretchability} of another, it will stretch twice
+as easily. Values should be non-negative and finite. The value
+@code{+inf.0} triggers a @code{programming_error} and is ignored,
+but @code{1.0e7} can be used for an almost infinitely stretchable
+spring. If unset, the default value is set to
+@code{basic-distance}. Note that the dimension's propensity to
+@emph{compress} cannot be directly set by the user and is equal to
+(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).
-@end table
+@end itemize
+If a page has a ragged bottom, the resulting distance is the
+largest of:
-@snippets
+@itemize
-The header and footer are created by the functions make-footer and
-make-header, defined in \paper. The default implementations are in
-ly/paper-defaults.ly and ly/titling-init.ly.
+@item
+@code{basic-distance},
-The page layout itself is done by two functions in the \paper block,
-page-music-height and page-make-stencil. The former tells the
-line-breaking algorithm how much space can be spent on a page, the
-latter creates the actual page given the system to put on it.
+@item
+@code{minimum-distance}, and
-You can define paper block values in Scheme. In that case mm, in, pt,
-and cm are variables defined in paper-defaults.ly with values in
-millimeters. That is why the value 2 cm must be multiplied in the
-example
+@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 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 @{
- #(define bottom-margin (* 2 cm))
+ system-system-spacing #'basic-distance = #8
+ score-system-spacing =
+ #'((basic-distance . 12)
+ (minimum-distance . 6)
+ (padding . 1)
+ (stretchability . 12))
@}
@end example
-Example:
+@node List of flexible vertical spacing \paper variables
+@unnumberedsubsubsec List of flexible vertical spacing @code{\paper} variables
-@example
-\paper @{
- paper-width = 2\cm
- top-margin = 3\cm
- bottom-margin = 3\cm
- ragged-last-bottom = ##t
-@}
-@end example
+The names of these variables follow the format
+@code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
+and @code{@var{lower}} are the items to be spaced. Each distance
+is measured between the reference points of the two items (see the
+description of the alist structure above). Note that in these
+variable names, the term @q{@code{markup}} refers to both
+@emph{title markups} (@code{bookTitleMarkup} or
+@code{scoreTitleMarkup}) and @emph{top-level markups} (see
+@ref{File structure}). All distances are measured in
+staff-spaces.
-This second example centers page numbers at the bottom of every page.
+Default settings 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
+@c TODO: Where do headers/footers fit in? -mp
-You can also define these values in Scheme. In that case @code{mm},
-@code{in}, @code{pt}, and @code{cm} are variables defined in
-@file{paper@/-defaults@/-init@/.ly} with values in millimeters. That is why the
-value must be multiplied in the example
+@table @code
+@item markup-system-spacing
+@funindex markup-system-spacing
-@example
-\paper @{
- #(define bottom-margin (* 2 cm))
-@}
-@end example
+the distance between a (title or top-level) markup and the system
+that follows it.
+
+@item score-markup-spacing
+@funindex score-markup-spacing
+
+the distance between the last system of a score and the (title or
+top-level) markup that follows it.
+
+@item score-system-spacing
+@funindex score-system-spacing
-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@/-init@/.ly} and
-@file{ly/@/titling@/-init@/.ly}.
+the distance between the last system of a score and the first
+system of the score that follows it, when no (title or top-level)
+markup exists between them.
-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.
+@item system-system-spacing
+@funindex system-system-spacing
+the distance between two systems in the same score.
+
+@item markup-markup-spacing
+@funindex markup-markup-spacing
+
+the distance between two (title or top-level) markups.
+
+@item last-bottom-spacing
+@funindex last-bottom-spacing
+
+the distance from the last system or top-level markup on a page to
+the bottom of the printable area (i.e. the top of the bottom
+margin).
+
+@item top-system-spacing
+@funindex top-system-spacing
+
+the distance from the top of the printable area (i.e. the bottom
+of the top margin) to the first system on a page, when there is no
+(title or top-level) markup between the two.
+
+@item top-markup-spacing
+@funindex top-markup-spacing
+
+the distance from the top of the printable area (i.e. the bottom
+of the top margin) to the first (title or top-level) markup on a
+page, when there is no system between the two.
+@end table
@seealso
Notation Reference:
-@ref{Vertical spacing between systems}.
+@ref{Flexible vertical spacing within systems}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
Snippets:
@rlsr{Spacing}.
-@node Horizontal dimensions
-@unnumberedsubsubsec Horizontal dimensions
-
+@node Horizontal spacing \paper variables
+@subsection Horizontal spacing @code{\paper} variables
-There are a few variables that determine the horizontal dimensions
-on a page:
+@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}.}
-@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 right-margin
+@funindex 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 check-consistency
+@funindex check-consistency
+
+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 ragged-right
+@funindex ragged-right
+
+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 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}. This variable can also be
+set in a @code{\layout} block.
+
+@end table
+
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
+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.
-@item right-margin
-@funindex right-margin
+@end table
+
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
-The margin between the right edge of the page and the end of
-each system. Default: @code{10\mm}.
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+
+@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
-@node Other layout variables
-@unnumberedsubsubsec Other layout variables
+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.
-These variables can be used to adjust page layout in general.
+@item system-count
+@funindex system-count
-@table @code
+The number of systems to be used for a score. Default: unset.
+This variable can also be set in a @code{\layout} block.
-@item auto-first-page-number
-@funindex auto-first-page-number
+@end table
-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}.
+@seealso
+Notation Reference:
+@ref{Line breaking}.
-@ignore
-FIXME: this variable is used, but I don't know what it does. -pm
+@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 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
+never consider blank pages in the middle of a score.
-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 page-breaking
+@funindex page-breaking
-@item first-page-number
-@funindex first-page-number
+The page-breaking algorithm to use. Choices are
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
+@code{ly:optimal-breaking}.
-The value of the page number on the first page. Default:
-@code{#1}.
-
-@item 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.
-
-@item 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 page-breaking-between-system-padding
-@funindex page-breaking-between-system-padding
+@item page-breaking-system-system-spacing
+@funindex page-breaking-system-system-spacing
Tricks the page breaker into thinking that
-@code{between-system-padding} is set to something different than
-it really is. For example, if this variable is set to something
-substantially larger than @code{between-system-padding}, then the
+@code{system-system-spacing} is set to something different than
+it really is. For example, if
+@code{page-breaking-system-system-spacing #'padding} is set to something
+substantially larger than @code{system-system-spacing #'padding}, then the
page-breaker will put fewer systems on each page. Default: unset.
@item page-count
@funindex page-count
-The number of pages to be used for a score. Default: unset.
+The number of pages to be used for a score, unset by default.
-@item page-limit-inter-system-space
-@funindex page-limit-inter-system-space
+@end table
-If set to true, limits space between systems on a page with a lot
-of space left. Default: @code{##f}. For details, see
-@ref{Vertical spacing between systems}.
+@seealso
+Notation Reference:
+@ref{Page breaking},
+@ref{Optimal page breaking},
+@ref{Optimal page turning},
+@ref{Minimal page breaking}.
-@item page-limit-inter-system-space-factor
-@funindex page-limit-inter-system-space-factor
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-The factor used by @code{page-limit-inter-system-space}. Default:
-@code{1.4}. For details, see
-@ref{Vertical spacing between systems}.
-@item page-spacing-weight
-@funindex page-spacing-weight
+@node \paper variables for page numbering
+@unnumberedsubsubsec @code{\paper} variables for page numbering
-The relative importance of page (vertical) spacing and line
-(horizontal) spacing. High values will make page spacing more
-important. Default: @code{#10}.
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
-@item print-all-headers
-@funindex print-all-headers
+@table @code
+
+@cindex page numbers, auto-numbering
+@item auto-first-page-number
+@funindex auto-first-page-number
+
+The page breaking algorithm is affected by the first page number
+being odd or even. If set to true, the page breaking algorithm
+will decide whether to start with an odd or even number. This
+will result in the first page number remaining as is or being
+increased by one. Default: @code{#f}.
+
+@cindex page numbers, specify the first
+@item first-page-number
+@funindex first-page-number
-If set to true, this will print all headers for each \score in the
-output. Normally only the piece and opus header variables are
-printed. Default: @code{##f}.
+The value of the page number on the first page.
@item print-first-page-number
@funindex print-first-page-number
If set to true, a page number is printed on the first page.
-Default: @code{##f}.
+@cindex page numbers, suppress
@item print-page-number
@funindex print-page-number
-If set to false, page numbers are not printed. Default:
-@code{##t}.
-
-@item ragged-bottom
-@funindex ragged-bottom
-
-If set to true, systems will not spread vertically across the
-page. This does not affect the last page. Default: @code{##f}.
+If set to false, page numbers are not printed.
-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 { 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
+@end table
-The number of systems to be used for a score.
-Default: unset.
-@item systems-per-page
-@funindex systems-per-page
+@seealso
+Installed Files:
+@file{ly/titling-init.ly}.
-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.
+Snippets:
+@rlsr{Spacing}.
-@item two-sided
-@funindex two-sided
-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}.
+@knownissues
+
+The default page header puts the page number and the @code{instrument}
+field from the @code{\header} block on a line.
+
+
+@node Score layout
+@section Score layout
+
+This section discusses score layout options for the @code{\layout}
+block.
+
+@menu
+* The \layout block::
+* Setting the staff size::
+@end menu
+
+
+@node The \layout block
+@subsection The @code{\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:
-@end table
+@itemize
+@item
+@code{line-width}, @code{ragged-right} and @code{ragged-last}
+(see @ref{\paper variables for widths and margins})
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@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})
-@knownissues
+@end itemize
-The default page header puts the page number and the @code{instrument}
-field from the @code{\header} block on a line.
+Here is an example @code{\layout} block:
-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
+\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
-@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
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
@cindex line breaks
@cindex breaking lines
-Line breaks are normally determined automatically. They are chosen
+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.
+and @code{line-width}. They are set in the @code{\layout} block.
They control the indentation of the first line of music, and the
lengths of the lines.
If @code{ragged-right} is set to true in the @code{\layout} block,
then systems end at their natural horizontal length, instead of
-being spread horizontally to fill the whole line. This is useful
+being spread horizontally to fill the whole line. This is useful
for short fragments, and for checking how tight the natural
spacing is.
@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,fragment,verbatim]
-c4 c2 << c2 {s4 \break } >> % this does nothing
-c2 c4 | % a break here would work
-c4 c2 c4 ~ \break % as does this break
-c4 c2 c4
-@end lilypond
-
-This can be avoided by removing the @code{Forbid_line_break_engraver}.
-Note that manually forced line breaks have to be added in parallel
-with the music.
-
-@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 prefered
- #(define page-breaking ly:minimal-breaking)
+ %% ly:minimal-breaking may be preferred
+ 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 Score \with {
- \override NonMusicalPaperColumn #'line-break-permission = ##f
- \override NonMusicalPaperColumn #'page-break-permission = ##f
- } {
- \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 }
+ \new Staff {
+ \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
+ \override NonMusicalPaperColumn #'line-break-permission = ##f
+ \override NonMusicalPaperColumn #'page-break-permission = ##f
+ }
+ }
+}
+@end lilypond
+
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
+@node Using an extra voice for breaks
+@subsection Using an extra voice for breaks
+
+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 @{ \music @} \break
+ \repeat unfold 3 @{ \music @}
+ @}
+@}
+@end example
+
+This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
+music entry with information that specifies how music should lay out
+on the page. You can keep music entry and line- and page-breaking
+information in two separate places by introducing an extra voice to
+contain the breaks. This extra voice
+contains only skips together with @code{\break}, @code{pageBreak} and other
+breaking layout information.
+
+@lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
+\score {
+ \new Staff <<
+ \new Voice {
+ s1 * 2 \break
+ s1 * 3 \break
+ s1 * 6 \break
+ s1 * 5 \break
+ }
+ \new Voice {
+ \repeat unfold 2 { \music }
+ \repeat unfold 3 { \music }
+ \repeat unfold 6 { \music }
+ \repeat unfold 5 { \music }
+ }
+ >>
+}
+@end lilypond
+
+This pattern becomes especially helpful when overriding
+@code{line-break-system-details} and the other useful but long properties of
+@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
+
+@lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
+\score {
+ \new Staff <<
+ \new Voice {
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0))
+ s1 * 2 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 35))
+ s1 * 3 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 70))
+ s1 * 6 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 105))
+ s1 * 5 \break
}
+ \new Voice {
+ \repeat unfold 2 { \music }
+ \repeat unfold 3 { \music }
+ \repeat unfold 6 { \music }
+ \repeat unfold 5 { \music }
+ }
+ >>
+}
+@end lilypond
+
+
+@seealso
+Notation Reference:
+@ref{Vertical spacing}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
+@node Vertical spacing
+@section Vertical spacing
+
+@cindex vertical spacing
+@cindex spacing, vertical
+
+Vertical spacing is controlled by three things: the amount of
+space available (i.e., paper size and margins), the amount of
+space between systems, and the amount of space between
+staves inside a system.
+
+@menu
+* Flexible vertical spacing within systems::
+* Explicit staff and system positioning::
+* Vertical collision avoidance::
+@end menu
+
+
+@node Flexible vertical spacing within systems
+@subsection Flexible vertical spacing within systems
+
+@cindex distance between staves
+@cindex staff distance
+@cindex space between staves
+@cindex space inside systems
+
+Three separate mechanisms control the flexible vertical spacing
+within systems, one for each of the following categories:
+
+@itemize
+
+@item
+@emph{ungrouped staves},
+
+@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.).
+
+@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
+staves.
+
+Note that the spacing mechanisms discussed in this section only
+control the vertical spacing of staves and non-staff lines within
+individual systems. The vertical spacing between separate
+systems, scores, markups, and margins is controlled by
+@code{\paper} variables, which are discussed in
+@ref{Flexible vertical spacing \paper variables}.
+
+@menu
+* Within-system spacing properties::
+* Spacing of ungrouped staves::
+* Spacing of grouped staves::
+* Spacing of non-staff lines::
+@end menu
+
+
+@node Within-system spacing properties
+@unnumberedsubsubsec Within-system spacing properties
+
+@funindex staff-affinity
+@funindex staffgroup-staff-spacing
+@funindex staff-staff-spacing
+@funindex nonstaff-unrelatedstaff-spacing
+@funindex nonstaff-relatedstaff-spacing
+@funindex nonstaff-nonstaff-spacing
+@funindex default-staff-staff-spacing
+@funindex minimum-Y-extent
+@funindex extra-offset
+@funindex self-alignment-X
+@funindex X-offset
+@funindex VerticalAxisGroup
+
+The within-system vertical spacing mechanisms are controlled by
+two sets of grob properties. The first set is associated with the
+@code{VerticalAxisGroup} grob, which is created by all staves and
+non-staff lines. The second set is associated with the
+@code{StaffGrouper} grob, which can be created by staff-groups,
+but only if explicitly called. These properties are described
+individually at the end of this section.
+
+The names of these properties (except for @code{staff-affinity})
+follow the format @code{@var{item1}-@var{item2}-spacing}, where
+@code{@var{item1}} and @code{@var{item2}} are the items to be
+spaced. Note that @code{@var{item2}} is not necessarily below
+@code{@var{item1}}; for example,
+@code{nonstaff-relatedstaff-spacing} will measure upwards from the
+non-staff line if @code{staff-affinity} is @code{#UP}.
+
+Each distance is measured between the @emph{reference points} of
+the two items. The reference point for a staff is the vertical
+center of its @code{StaffSymbol} (i.e. the middle line if
+@code{line-count} is odd; the middle space if @code{line-count} is
+even). The reference points for individual non-staff lines are
+given in the following table:
+
+@multitable {Non-staff line} {Reference point}
+@headitem Non-staff line @tab Reference point
+@item @code{ChordNames} @tab baseline
+@item @code{NoteNames} @tab baseline
+@item @code{Lyrics} @tab baseline
+@item @code{Dynamics} @tab vertical center
+@item @code{FiguredBass} @tab highest point
+@item @code{FretBoards} @tab top line
+@end multitable
+
+In the following image, horizontal lines indicate the positions
+of these reference points:
+
+@lilypond[quote,noragged-right,line-width=110\mm]
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
+
+alignToZero = \with {
+ \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
+ \override VerticalAxisGroup #'nonstaff-nonstaff-spacing = #zero-space
+}
+lowerCaseChords = \with {
+ chordNameLowercaseMinor = ##t
+}
+staffAffinityDown = \with {
+ \override VerticalAxisGroup #'staff-affinity = #DOWN
+}
+labelContext =
+#(define-music-function
+ (parser location context)
+ (string?)
+ #{ s1*0^\markup { \typewriter $context } #})
+
+\layout {
+ \context { \Dynamics \alignToZero }
+ \context { \FiguredBass \alignToZero }
+ \context { \Lyrics \alignToZero }
+ \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
}
}
+
+%% These contexts have reference points at the baseline:
+%% ChordNames, NoteNames, and Lyrics
+<<
+ \new ChordNames { \chords { g1:m } }
+ \new NoteNames { s1 | g1 | }
+ \new RhythmicStaff {
+ \set RhythmicStaff.instrumentName = #"baseline "
+ \textLengthOn
+ \labelContext "ChordNames " s1 |
+ \labelContext "NoteNames " s1 |
+ \labelContext "Lyrics" s1 |
+ }
+ \new Lyrics { \lyrics { \skip 1*2 | ghijk1 | } }
+>>
+
+%% The reference point for Dynamics is its vertical center
+<<
+ \new RhythmicStaff {
+ \set RhythmicStaff.instrumentName = #"vertical center "
+ \labelContext "Dynamics" s1*3
+ }
+ \new Dynamics { s1\mp s\fp }
+>>
+
+%% The reference point for FiguredBass is its highest point
+<<
+ \new RhythmicStaff {
+ \set RhythmicStaff.instrumentName = #"highest point "
+ \labelContext "FiguredBass" s1
+ }
+ \new FiguredBass { \figuremode { <6 5>1 } }
+>>
+
+%% The reference point for FretBoards is the top line
+\include "predefined-guitar-fretboards.ly"
+<<
+ \new FretBoards { \chordmode { e1 } }
+ \new RhythmicStaff {
+ \set RhythmicStaff.instrumentName = #"top line "
+ \labelContext "FretBoards " s1
+ }
+>>
@end lilypond
+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.
-@seealso
-Snippets:
-@rlsr{Spacing}.
-
+The following example demonstrates the two ways these alists can
+be modified. The first declaration updates one key-value
+individually, and the second completely re-defines the property:
-@node Using an extra voice for breaks
-@subsection Using an extra voice for breaks
+@example
+\new Staff \with @{
+ \override VerticalAxisGroup #'default-staff-staff-spacing
+ #'basic-distance = #10
+@} @{ @dots{} @}
+
+\new Staff \with @{
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((basic-distance . 10)
+ (minimum-distance . 9)
+ (padding . 1)
+ (stretchability . 10))
+@} @{ @dots{} @}
+@end example
-Line- and page-breaking information usually appears within note entry directly.
+To change any spacing settings globally, put them in the
+@code{\layout} block:
@example
-\new 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 @}
+\layout @{
+ \context @{
+ \Staff
+ \override VerticalAxisGroup #'default-staff-staff-spacing
+ #'basic-distance = #10
@}
@}
@end example
-This makes @code{\break} and @code{\pageBreak} commands easy to enter but mixes
-music entry with information that specifies how music should lay out
-on the page. You can keep music entry and line- and page-breaking
-information in two separate places by introducing an extra voice to
-contain the breaks. This extra voice
-contains only skips together with @code{\break}, @code{pageBreak} and other
-breaking layout information.
+Standard settings for the vertical spacing grob properties are
+listed in @rinternals{VerticalAxisGroup} and
+@rinternals{StaffGrouper}. Default overrides for specific types
+of non-staff lines are listed in the relevant context descriptions
+in @rinternals{Contexts}.
-@lilypond[quote,verbatim]
-\new Score {
- \new Staff <<
- \new Voice {
- s1 * 2 \break
- s1 * 3 \break
- s1 * 6 \break
- s1 * 5 \break
- }
- \new Voice {
- \repeat unfold 2 { c'4 c'4 c'4 c'4 }
- \repeat unfold 3 { c'4 c'4 c'4 c'4 }
- \repeat unfold 6 { c'4 c'4 c'4 c'4 }
- \repeat unfold 5 { c'4 c'4 c'4 c'4 }
- }
- >>
-}
-@end lilypond
-This pattern becomes especially helpful when overriding
-@code{line-break-system-details} and the other useful but long properties of
-@code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
+@subsubheading Properties of the @code{VerticalAxisGroup} grob
-@lilypond[quote,verbatim]
-\new Score {
- \new Staff <<
- \new Voice {
+@code{VerticalAxisGroup} properties are typically adjusted with an
+@code{\override} at the @code{Staff} level (or equivalent).
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
- s1 * 2 \break
+@table @code
+@item staff-staff-spacing
+
+Used to determine the distance between the current staff and the
+staff just below it in the same system, even if one or more
+non-staff lines (such as @code{Lyrics}) are placed between the two
+staves. Does not apply to the bottom staff of a system.
+
+Initially, the @code{staff-staff-spacing} of a
+@code{VerticalAxisGroup} is a Scheme function that applies the
+properties of the @code{StaffGrouper} if the staff is part of a
+group, or the @code{default-staff-staff-spacing} of the staff
+otherwise. This allows staves to be spaced differently when they
+are grouped. For uniform spacing regardless of grouping, this
+function may be replaced by a flexible-spacing alist, using the
+complete-redefinition form of override shown above.
+
+@item default-staff-staff-spacing
+A flexible-spacing alist defining the @code{staff-staff-spacing} used for
+ungrouped staves, unless @code{staff-staff-spacing} has been explicitly
+set with an @code{\override}.
+
+@item staff-affinity
+The direction of the staff to use for spacing the current
+non-staff line. Choices are @code{UP}, @code{DOWN}, and
+@code{CENTER}. If @code{CENTER}, the non-staff line will be
+placed equidistant between the two nearest staves on either side,
+unless collisions or other spacing constraints prevent this.
+Adjacent non-staff lines should have non-increasing
+@code{staff-affinity} from top to bottom, e.g. a non-staff line
+set to @code{UP} should not immediately follow one that is set to
+@code{DOWN}. Non-staff lines at the top of a system should use
+@code{DOWN}; those at the bottom should use @code{UP}. Setting
+@code{staff-affinity} for a staff causes it to be treated as a
+non-staff line. Setting @code{staff-affinity} to @code{#f} causes
+a non-staff line to be treated as a staff. Setting
+@code{staff-affinity} to @code{UP}, @code{CENTER}, or @code{DOWN}
+causes a staff to be spaced as a non-staff line.
+
+@item nonstaff-relatedstaff-spacing
+The distance between the current non-staff line and the nearest
+staff in the direction of @code{staff-affinity}, if there are no
+non-staff lines between the two, and @code{staff-affinity} is
+either @code{UP} or @code{DOWN}. If @code{staff-affinity} is
+@code{CENTER}, then @code{nonstaff-relatedstaff-spacing} is used
+for the nearest staves on @emph{both} sides, even if other
+non-staff lines appear between the current one and either of the
+staves. This means that the placement of a non-staff line depends
+on both the surrounding staves and the surrounding non-staff lines.
+Setting the @code{stretchability} of one of these types of spacing to
+a small value will make that spacing dominate. Setting the
+@code{stretchability} to a large value will make that spacing have
+little effect.
+
+@item nonstaff-nonstaff-spacing
+The distance between the current non-staff line and the next
+non-staff line in the direction of @code{staff-affinity}, if both
+are on the same side of the related staff, and
+@code{staff-affinity} is either @code{UP} or @code{DOWN}.
+
+@item nonstaff-unrelatedstaff-spacing
+The distance between the current non-staff line and the staff in
+the opposite direction from @code{staff-affinity}, if there are no
+other non-staff lines between the two, and @code{staff-affinity}
+is either @code{UP} or @code{DOWN}. This can be used, for
+example, to require a minimum amount of padding between a
+@code{Lyrics} line and the staff to which it does not belong.
+@end table
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 35))
- s1 * 3 \break
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 70))
- s1 * 6 \break
+@subsubheading Properties of the @code{StaffGrouper} grob
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 105))
- s1 * 5 \break
- }
- \new Voice {
- \repeat unfold 2 { c'4 c'4 c'4 c'4 }
- \repeat unfold 3 { c'4 c'4 c'4 c'4 }
- \repeat unfold 6 { c'4 c'4 c'4 c'4 }
- \repeat unfold 5 { c'4 c'4 c'4 c'4 }
- }
- >>
-}
-@end lilypond
+@code{StaffGrouper} properties are typically adjusted with an
+@code{\override} at the @code{StaffGroup} level (or equivalent).
+@table @code
+@item staff-staff-spacing
+The distance between consecutive staves within the current
+staff-group. The @code{staff-staff-spacing} property of an
+individual staff's @code{VerticalAxisGroup} grob can be
+overriden with different spacing settings for that staff.
+
+@item staffgroup-staff-spacing
+The distance between the last staff of the current staff-group and
+the staff just below it in the same system, even if one or more
+non-staff lines (such as @code{Lyrics}) exist between the two
+staves. Does not apply to the bottom staff of a system. The
+@code{staff-staff-spacing} property of an individual staff's
+@code{VerticalAxisGroup} grob can be overriden with different
+spacing settings for that staff.
+@end table
@seealso
Notation Reference:
-@ref{Vertical spacing}.
-
-Snippets:
-@rlsr{Spacing}.
-
-
-@node Vertical spacing
-@section Vertical spacing
-
-@cindex vertical spacing
-@cindex spacing, vertical
+@ref{Flexible vertical spacing \paper variables},
+@ref{Modifying alists}.
-Vertical spacing is controlled by three things: the amount of
-space available (i.e., paper size and margins), the amount of
-space between systems, and the amount of space between
-staves inside a system.
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
-@menu
-* Vertical spacing inside a system::
-* Vertical spacing between systems::
-* Explicit staff and system positioning::
-* Vertical collision avoidance::
-@end menu
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
-@node Vertical spacing inside a system
-@subsection Vertical spacing inside a system
+@node Spacing of ungrouped staves
+@unnumberedsubsubsec Spacing of ungrouped staves
-@cindex distance between staves
-@cindex staff distance
-@cindex space between staves
-@cindex space inside systems
+@emph{Staves} (such as @code{Staff}, @code{DrumStaff},
+@code{TabStaff}, etc.) are contexts that can contain one or more
+voice contexts, but cannot contain any other staves.
-The height of each system is determined in two steps. First, all of the
-staves are spaced according to the amount of space available. Then, the
-non-staff lines (eg. lyrics or chords) are distributed between the
-staves.
+The following properties affect the spacing of @emph{ungrouped}
+staves:
-@unnumberedsubsubsec Spacing between staves
-Spacing between staves is controlled by the @var{next-staff-spacing}
-property of the @var{VerticalAxisGroup} grob. This property is an alist
-with four elements: @var{space}, @var{minimum-distance}, @var{padding}
-and @var{stretchability}:
@itemize
-@item
-@var{space} is the size of the stretchable space between the center line
-of one staff to the center line of the next staff.
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{default-staff-staff-spacing}
+@item @code{staff-staff-spacing}
+@end itemize
+@end itemize
-@item
-@var{minimum-distance} provides a lower bound on the final distance
-between the center line of one staff to the center line of the next
-staff. That is, if a page has many systems and needs to be compressed,
-the distance from this staff to the next will never be compressed to
-less than @var{minimum-distance}.
+These grob properties are described individually above; see
+@ref{Within-system spacing properties}.
-@item
-@var{padding} is the amount of whitespace that must be present between
-the bottom of one staff and the top of the next. It differs from
-@var{minimum-distance} in that the effect of @var{padding} depends on
-the height of objects in the staff. For example, @var{padding} is more
-likely to come into effect for staves with notes that are far below the
-staff.
+Additional properties are involved for staves that are part of a
+staff-group; see @ref{Spacing of grouped staves}.
-@item
-@var{stretchability} controls the stretchable space's propensity to
-stretch when the system is stretched. Large values will cause a
-system to stretch more, while a value of zero will prevent the
-space from stretching at all. If unset, @var{stretchability}
-defaults to @code{space - minimum-distance}.
-@end itemize
+The following example shows how the @code{default-staff-staff-spacing}
+property can affect the spacing of ungrouped staves.
+The same overrides applied to @code{staff-staff-spacing} would
+have the same effect, but would also apply in cases where the staves
+are combined in a group or groups.
-@lilypond[verbatim]
-#(set-global-staff-size 16)
-\new StaffGroup <<
- % Since space is small and there is no minimum-distance, the distance
- % between this staff and the next will be determined by padding.
- \new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 1) (padding . 1))
- }
- { \clef bass c, }
- % Since space is small and nothing sticks out very far, the distance
- % between this staff and the next will be determined by minimum-distance.
- \new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 1) (minimum-distance . 12))
+@lilypond[verbatim,quote,staffsize=16]
+\layout {
+ \context {
+ \Staff
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((basic-distance . 8)
+ (minimum-distance . 7)
+ (padding . 1))
}
- { \clef bass c, }
- % By setting padding to a negative value, staves can be made to collide.
+}
+
+<<
+ % The very low note here needs more room than 'basic-distance
+ % can provide, so the distance between this staff and the next
+ % is determined by 'padding.
+ \new Staff { b,2 r | }
+
+ % Here, 'basic-distance provides enough room, and there is no
+ % need to compress the space (towards 'minimum-distance) to make
+ % room for anything else on the page, so the distance between
+ % this staff and the next is determined by 'basic-distance.
+ \new Staff { \clef bass g2 r | }
+
+ % By setting 'padding to a negative value, staves can be made to
+ % collide. The lowest acceptable value for 'basic-distance is 0.
\new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 4) (padding . -10))
- }
- { \clef bass c, }
- \new Staff { \clef bass c, }
+ \override VerticalAxisGroup #'default-staff-staff-spacing =
+ #'((basic-distance . 3.5)
+ (padding . -10))
+ } { \clef bass g2 r | }
+ \new Staff { \clef bass g2 r | }
>>
@end lilypond
+@seealso
+Installed Files:
+@file{scm/define-grobs.scm}.
+
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{VerticalAxisGroup}.
+
+
+@node Spacing of grouped staves
+@unnumberedsubsubsec Spacing of grouped staves
+
+In orchestral and other large scores, it is common to place staves
+in groups. The space between groups is typically larger than the
+space between staves of the same group.
+
+@emph{Staff-groups} (such as @code{StaffGroup}, @code{ChoirStaff},
+etc.) are contexts that can contain one or more staves
+simultaneously.
+
+The following properties affect the spacing of staves inside
+staff-groups:
+
+@itemize
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{staff-staff-spacing}
+@end itemize
+@item @code{StaffGrouper} properties:
+@itemize
+@item @code{staff-staff-spacing}
+@item @code{staffgroup-staff-spacing}
+@end itemize
+@end itemize
+
+These grob properties are described individually above; see
+@ref{Within-system spacing properties}.
+
+The following example shows how properties of the
+@code{StaffGrouper} grob can affect the spacing of grouped staves:
+
+@lilypond[verbatim,quote,staffsize=16]
+\layout {
+ \context {
+ \Score
+ \override StaffGrouper #'staff-staff-spacing #'padding = #0
+ \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
+ }
+}
-In orchestral and other large scores, it is common to place staves in
-groups. The space between groups is typically larger than the space
-between staves of the same group. This spacing can be tweaked with the
-@var{StaffGrouper} grob: the default value of @var{next-staff-spacing}
-for @var{VerticalAxisGroup} is a callback function which operates by
-searching for a @var{StaffGrouper} grob containing the staff. If it
-finds a @var{StaffGrouper} grob and the staff in question is in the
-middle of a group, it reads the @var{between-staff-spacing} property of
-@var{StaffGrouper} and returns it. If the staff in question is the last
-staff of a group, the callback reads the @var{after-last-staff-spacing}
-property of @var{StaffGrouper} and returns it. If the callback did not
-find a @var{StaffGrouper} grob, it reads
-@var{default-next-staff-spacing} from its @var{VerticalAxisGroup} and
-returns that.
-
-@lilypond[verbatim]
-#(set-global-staff-size 16)
<<
\new PianoStaff \with {
- \override StaffGrouper #'between-staff-spacing #'space = #1
- \override StaffGrouper #'between-staff-spacing #'padding = #0
- \override StaffGrouper #'after-last-staff-spacing #'space = #20
- }
- <<
- \new Staff c'1
- \new Staff c'1
+ \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
+ } <<
+ \new Staff { c'1 }
+ \new Staff { c'1 }
>>
- \new StaffGroup \with {
- \override StaffGrouper #'between-staff-spacing #'space = #1
- \override StaffGrouper #'between-staff-spacing #'padding = #0
- }
- <<
- \new Staff c'1
- \new Staff c'1
+ \new StaffGroup <<
+ \new Staff { c'1 }
+ \new Staff { c'1 }
>>
>>
@end lilypond
+@seealso
+Installed Files:
+@file{scm/define-grobs.scm}.
-@unnumberedsubsubsec Spacing of non-staff lines
+Snippets:
+@rlsr{Spacing}.
-After the positions of the staves are determined, the non-staff lines
-are distributed between the staves. Each of these lines has a
-@var{staff-affinity} property which controls its vertical alignment.
-For example,
+Internals Reference:
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
-@example
-\new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
-@end example
-@noindent creates a lyrics context that will be placed close to the
-staff below it. Setting @var{staff-affinity} to something which is not
-a number (@code{#f}, for example) will cause that line to be treated
-like a staff. Conversely, setting @var{staff-affinity} for a staff will
-cause it to be treated like a non-staff.
+@node Spacing of non-staff lines
+@unnumberedsubsubsec Spacing of non-staff lines
-Non-staff lines admit three properties to control their spacing. Each
-of the these properties is an alist of the same format as
-@var{next-staff-spacing}, above.
-@itemize
-@item
-If the nearest line in the @var{staff-affinity} direction is a staff
-then @var{inter-staff-spacing} gives the spacing between the non-staff
-and the staff. If @var{staff-affinity} is @code{CENTER}, then
-@var{inter-staff-spacing} is used for both directions.
+@emph{Non-staff lines} (such as @code{Lyrics}, @code{ChordNames},
+etc.) are contexts whose layout objects are engraved like staves
+(i.e. in horizontal lines within systems). Specifically,
+non-staff lines are non-staff contexts that create the
+@code{VerticalAxisGroup} layout object.
-@item
-If the nearest line in the @var{staff-affinity} direction is a non-staff
-then @var{inter-loose-line-spacing} gives the spacing between the two
-non-staff lines.
+The following properties affect the spacing of non-staff lines:
-@item
-If the nearest line in the opposite direction to @var{staff-affinity} is
-a staff then @var{non-affinity-spacing} gives the spacing between the
-non-staff and the staff. This can be used, for example, to require
-a minimum amount of padding between a Lyrics line and the staff
-to which it does not belong.
+@itemize
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{staff-affinity}
+@item @code{nonstaff-relatedstaff-spacing}
+@item @code{nonstaff-nonstaff-spacing}
+@item @code{nonstaff-unrelatedstaff-spacing}
+@end itemize
@end itemize
-@lilypond[verbatim]
-#(set-global-staff-size 16)
+These grob properties are described individually above; see
+@ref{Within-system spacing properties}.
+
+The following example shows how the
+@code{nonstaff-nonstaff-spacing} property can affect the spacing
+of consecutive non-staff lines. Here, by setting the
+@code{stretchability} key to a very high value, the lyrics are
+able to stretch much more than usual:
+
+@lilypond[verbatim,quote,staffsize=16]
\layout {
\context {
\Lyrics
- % By default, Lyrics are placed close together. Here, we allow them to
- % be stretched more widely.
\override VerticalAxisGroup
- #'inter-loose-line-spacing #'stretchability = #1000
+ #'nonstaff-nonstaff-spacing #'stretchability = #1000
}
}
\new StaffGroup
<<
\new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing = #'((space . 30)) }
- { c'1 }
+ \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
+ } { c'1 }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #UP }
- \lyricmode { up }
+ \override VerticalAxisGroup #'staff-affinity = #UP
+ } \lyricmode { up }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #CENTER }
- \lyricmode { center }
+ \override VerticalAxisGroup #'staff-affinity = #CENTER
+ } \lyricmode { center }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #DOWN }
- \lyricmode { down }
- \new Staff
- { c'1 }
+ \override VerticalAxisGroup #'staff-affinity = #DOWN
+ } \lyricmode { down }
+ \new Staff { c'1 }
>>
@end lilypond
+
@seealso
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
Snippets:
@rlsr{Spacing}.
@c @lsr{spacing,alignment-vertical-spacing.ly}.
Internals Reference:
-@rinternals{VerticalAxisGroup},
-@rinternals{VerticalAlignment},
-@rinternals{Axis_group_engraver}.
-
-@knownissues
-Adjacent non-staff lines should have non-increasing
-@var{staff-affinity} from top-to-bottom. For example, the behavior of
-@example
-<<
- \new Staff c
- \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
- \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #UP @}
- \new Staff c
->>
-@end example
-is undefined.
-
-A non-staff line at the bottom of a system should have
-@var{staff-affinity} set to @code{UP}. Similarly, a non-staff
-line at the top of a system should have @var{staff-affinity} set
-to @code{DOWN}.
-
-@node Vertical spacing between systems
-@subsection Vertical spacing between systems
-
-The mechanisms that control spacing between systems are similar to those
-that control spacing between staves within a system (see
-@ref{Vertical spacing inside a system}). The main difference is that
-the variables to control spacing between systems are set in the
-@code{\paper} block, rather than as grob properties. These paper block
-variables are @var{between-system-spacing},
-@var{between-scores-system-spacing}, @var{after-title-spacing},
-@var{before-title-spacing}, @var{between-title-spacing},
-@var{top-system-spacing}, @var{top-system-spacing},
-@var{top-title-spacing} and @var{bottom-system-spacing}. Note that
-these variables ignore non-staff lines. For example,
-@var{between-system-spacing} controls the spacing from the middle staff
-line of the bottom staff from one system to the middle staff line of the
-top staff of the next system, whether or not there are lyrics below the
-upper system. See @ref{Vertical dimensions} for a description of each
-of these variables.
-
-There are two more @code{\paper} block variables that affect vertical
-spacing: if @var{ragged-bottom} is set to @code{##t} then no pages will
-be stretched (which means that neither the space between systems nor the
-space within systems will be stretched). If @var{ragged-last-bottom}
-is set to @code{##t} then the last page will not be stretched.
-
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup}.
@node Explicit staff and system positioning
@subsection Explicit staff and system positioning
-One way to understand the @code{VerticalAxisGroup} and @code{\paper}
-settings explained in the previous two sections is as a collection of
-different settings that primarily concern the amount of vertical padding
-different staves and systems running down the page.
+One way to understand the flexible vertical spacing mechanisms
+explained above is as a collection of settings that control the
+amount of vertical padding between staves and systems.
-It is possible to approach vertical spacing in a different way using
-@code{NonMusicalPaperColumn #'line-break-system-details}. Where
-@code{VerticalAxisGroup} and @code{\paper} settings specify vertical padding,
-@code{NonMusicalPaperColumn #'line-break-system-details} specifies exact
-vertical positions on the page.
+It is possible to approach vertical spacing in a different way
+using @code{NonMusicalPaperColumn #'line-break-system-details}.
+While the flexible vertical spacing mechanisms specify vertical
+padding, @code{NonMusicalPaperColumn #'line-break-system-details}
+can specify exact vertical positions on the page.
-@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
-list of three different settings:
+@code{NonMusicalPaperColumn #'line-break-system-details} accepts
+an associative list of 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 {
with the lower @code{outside-staff-priority} will be placed closer to
the staff.
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
c4_"Text"\pp
r2.
\once \override TextScript #'outside-staff-priority = #1
previously-positioned grobs can be controlled with
@code{outside-staff-padding}.
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
\once \override TextScript #'outside-staff-padding = #0
a'^"This text is placed very close to the note"
\once \override TextScript #'outside-staff-padding = #3
By default, outside-staff objects are placed only to avoid
a horizontal collision with previously-positioned grobs. This
can lead to situations in which objects are placed very close to each
-other horizontally. The vertical spacing between staffs can
+other horizontally. The vertical spacing between staves can
also be set so that outside staff objects are interleaved.
Setting @code{outside-staff-horizontal-padding}
causes an object to be offset vertically so that such a situation
doesn't occur.
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
% the markup is too close to the following note
c4^"Text"
c4
8th notes; the eighth note is followed by 1 note head width (NHW).
The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
-@lilypond[quote,fragment,verbatim,relative=1]
+@lilypond[quote,verbatim,relative=1]
c2 c4. c8 c4. c8 c4. c8 c8
c8 c4 c4 c4
@end lilypond
the common shortest note. So if we were to add only a few 16th notes
to the example above, they would be followed by half a NHW:
-@lilypond[quote,fragment,verbatim,relative=2]
+@lilypond[quote,verbatim,relative=2]
c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
@end lilypond
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
@lilypond[quote,ragged-right]
{
c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
+ b'4 e''4 b'4 e''4 |
\override Staff.NoteSpacing #'stem-spacing-correction = #1.5
\override Staff.StaffSpacing #'stem-spacing-correction = #1.5
c'4 e''4 e'4 b'4 |
- b'4 e''4 b'4 e''4|
+ b'4 e''4 b'4 e''4 |
}
@end lilypond
@rinternals{StaffSpacing},
@rinternals{NonMusicalPaperColumn}.
+Essay on automated music engraving:
+@ressay{Optical spacing}.
+
@knownissues
In the following example, the time signature change introduces a new
section, and hence the 16ths notes are spaced wider.
-@lilypond[relative,fragment,verbatim,quote]
+@lilypond[relative=1,verbatim,quote]
\time 2/4
c4 c8 c
c8 c c4 c16[ c c8] c4
\context {
\Score
\override SpacingSpanner
- #'base-shortest-duration = #(ly:make-moment 1 16)
+ #'base-shortest-duration = #(ly:make-moment 1 16)
}
}
}
@code{Score.SpacingSpanner #'uniform-stretching}. This
property can only be changed at the beginning of a score,
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-\new Score \with {
- \override SpacingSpanner #'uniform-stretching = ##t
-} <<
- \new Staff{
- \times 4/5 {
- c8 c8 c8 c8 c8
+@lilypond[quote,ragged-right,verbatim]
+\score {
+ <<
+ \new Staff {
+ \times 4/5 {
+ c8 c8 c8 c8 c8
+ }
+ c8 c8 c8 c8
}
- c8 c8 c8 c8
- }
- \new Staff{
- c8 c8 c8 c8
- \times 4/5 {
- c8 c8 c8 c8 c8
+ \new Staff {
+ c8 c8 c8 c8
+ \times 4/5 {
+ c8 c8 c8 c8 c8
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ \override SpacingSpanner #'uniform-stretching = ##t
}
}
->>
+}
@end lilypond
When @code{strict-note-spacing} is set, notes are spaced without
regard for clefs, bar lines, and grace notes,
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
\override Score.SpacingSpanner #'strict-note-spacing = ##t
\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c] c32[ c32] }
@end lilypond
spacing with ragged-right turned on.
@lilypond[quote,verbatim,ragged-right]
-\new Score <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
}
- }
->>
+ >>
+}
@end lilypond
Notice that the half note which begins the measure takes up far less
setting.
@lilypond[quote,verbatim,ragged-right]
-\new Score \with {
- proportionalNotationDuration = #(ly:make-moment 1 20)
-} <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ proportionalNotationDuration = #(ly:make-moment 1 20)
}
}
->>
+}
@end lilypond
The half note at the beginning of the measure and the faster notes in
space. We could place a measured timeline or graphic above or below
this example.
-The @code{proportionalNotationDuration} setting is a context setting that
-lives in @code{Score}. Recall that context settings appear in one of
-three locations in our input file -- in a @code{\with} block, in a
-@code{\context} block, or directly in music entry
-preceded by the @code{\set} command. As with all
-context settings, users can pick which of the three different
-locations they would like to set @code{proportionalNotationDuration}.
+The @code{proportionalNotationDuration} setting is a context setting
+that lives in @code{Score}. Remember that context settings can appear
+in one of three locations within our input file -- in a @code{\with}
+block, in a @code{\context} block, or directly in music entry preceded
+by the @code{\set} command. As with all context settings, users can
+pick which of the three different locations they would like to
+set @code{proportionalNotationDuration} in to.
The @code{proportionalNotationDuration} setting takes a single argument,
-which is the reference duration against which all music will be
-spaced. The LilyPond Scheme function make-moment takes two arguments
+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
-reference duration of a twentieth note. The values
+a whole note. The call @code{#(ly:make-moment 1 20)} therefore produces
+a reference duration of a twentieth note. 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.
How do we select the right reference duration to pass to
-@code{proportionalNotationDuration}? Usually by a process of trial and error,
-beginning with a duration close to the fastest (or smallest) duration
-in the piece. Smaller reference durations space music loosely; larger
-reference durations space music tightly.
+@code{proportionalNotationDuration}? Usually by a process of trial
+and error, beginning with a duration close to the fastest (or smallest)
+duration in the piece. Smaller reference durations space music loosely;
+larger reference durations space music tightly.
@lilypond[quote,verbatim,ragged-right]
-\new Score \with {
- proportionalNotationDuration = #(ly:make-moment 1 8)
-} <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ proportionalNotationDuration = #(ly:make-moment 1 8)
}
}
->>
+}
-\new Score \with {
- proportionalNotationDuration = #(ly:make-moment 1 16)
-} <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ proportionalNotationDuration = #(ly:make-moment 1 16)
}
}
->>
+}
-\new Score \with {
- proportionalNotationDuration = #(ly:make-moment 1 32)
-} <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ proportionalNotationDuration = #(ly:make-moment 1 32)
}
}
->>
+}
@end lilypond
Note that too large a reference duration -- such as the eighth note,
above -- spaces music too tightly and can cause note head collisions.
-Note also that proportional notation in general takes up more
-horizontal space that does classical spacing. Proportional spacing
-provides rhythmic clarity at the expense of horizontal space.
+Also that proportional notation in general takes up more horizontal
+space than classical spacing. Proportional spacing provides rhythmic
+clarity at the expense of horizontal space.
Next we examine how to optimally space overlapping tuplets.
tuplet.
@lilypond[quote,verbatim,ragged-right]
-\new Score <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
}
- }
- \new RhythmicStaff {
- \times 8/9 {
- c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ \new RhythmicStaff {
+ \times 8/9 {
+ c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ }
}
- }
->>
+ >>
+}
@end lilypond
-The spacing is bad because the evenly notes of the bottom staff do not
-stretch uniformly. Classical engraving includes very few complex
+The spacing is bad because the evenly spaced notes of the bottom staff
+do not stretch uniformly. Classical engravings include very few complex
triplets and so classical engraving rules can generate this type of
-result. Setting @code{proportionalNotationDuration} remedies this
-situation considerably.
+result. Setting @code{proportionalNotationDuration} fixes this.
@lilypond[quote,verbatim,ragged-right]
-\new Score \with {
- proportionalNotationDuration = #(ly:make-moment 1 20)
-} <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
}
- }
- \new RhythmicStaff {
- \times 8/9 {
- c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ \new RhythmicStaff {
+ \times 8/9 {
+ c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ proportionalNotationDuration = #(ly:make-moment 1 20)
}
}
->>
+}
@end lilypond
But if we look very carefully we can see that notes of the second half
-of the 9-tuplet space ever so slightly more widely than do the notes
+of the 9-tuplet space ever so slightly more widely than the notes
of the first half of the 9-tuplet. To ensure uniform stretching, we
turn on @code{uniform-stretching}, which is a property of
@code{SpacingSpanner}.
@lilypond[quote,verbatim,ragged-right]
-\new Score \with {
- proportionalNotationDuration = #(ly:make-moment 1 20)
- \override SpacingSpanner #'uniform-stretching = ##t
-} <<
- \new RhythmicStaff {
- c'2
- c'16 c'16 c'16 c'16
- \times 4/5 {
- c'16 c'16 c'16 c'16 c'16
+\score {
+ <<
+ \new RhythmicStaff {
+ c'2
+ c'16 c'16 c'16 c'16
+ \times 4/5 {
+ c'16 c'16 c'16 c'16 c'16
+ }
}
- }
- \new RhythmicStaff {
- \times 8/9 {
- c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ \new RhythmicStaff {
+ \times 8/9 {
+ c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
+ }
+ }
+ >>
+ \layout {
+ \context {
+ \Score
+ proportionalNotationDuration = #(ly:make-moment 1 20)
+ \override SpacingSpanner #'uniform-stretching = ##t
}
}
->>
+}
@end lilypond
Our two-staff example now spaces exactly, our rhythmic
Note that the LilyPond's proportional notation package expects
that all proportional scores set the SpacingSpanner's
-'uniform-stretching attribute to ##t. Setting
+'uniform-stretching attribute to ##t. Setting
proportionalNotationDuration without also setting the
SpacingSpanner's 'uniform-stretching attribute to ##t will, for
example, cause Skips to consume an incorrect amount of horizontal
space.
The SpacingSpanner is an abstract grob that lives in the Score
-context. As with our settings of proportionalNotationDuration,
+context. As with our settings of proportionalNotationDuration,
overrides to the SpacingSpanner can occur in any of three
different places in our input file – in the Score \with block, in
a Score \context block, or in note entry directly.
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:
@end lilypond
Both scores are proportional, but the spacing in the first score
-is too loose because of the clef change. The spacing of the second
+is too loose because of the clef change. The spacing of the second
score remains strict, however, because strict-note-spacing is
turned on. Turning on strict-note-spacing causes the width of
time signatures, key signatures, clefs and accidentals to play no
part in the spacing algorithm.
In addition to the settings given here, there are other settings
-that frequently appear in proportional scores. These include:
+that frequently appear in proportional scores. These include:
@itemize
@item @code{\override SpacingSpanner #'strict-grace-spacing = ##t}
of the units specified in the @code{\paper} or @code{\layout} block.
In the above example, @code{paper-height} has a value of 59.75
@code{staff-spaces}, and the @code{staff-size} is 20 points (the
-default value). Note that:
+default value). Note that:
@multitable {1 staff-space} {staff-size)/4 * (25.4/72.27) mm}
@noindent
In this case, one @code{staff-space} is approximately equal to
-1.757mm. Thus the @code{paper-height} measurement of 59.75
+1.757mm. Thus the @code{paper-height} measurement of 59.75
@code{staff-spaces} is equivalent to 105 millimeters, the height
of @code{a6} paper in landscape orientation. The pairs
(@var{a},@var{b}) are intervals, where @var{a} is the lower
The output of @code{annotate-spacing} reveals vertical dimensions
in great detail. For details about modifying margins and other
-layout variables, see @ref{Page formatting}.
+layout variables, see @ref{Page layout}.
Other than margins, there are a few other options to save space:
@example
\paper @{
- between-system-spacing = #'((padding . 0) (space . 0.1))
+ system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
ragged-last-bottom = ##f
ragged-bottom = ##f
@}
being typeset by default, will sometimes cause more systems to
be fitted onto each page, as an estimation step is then bypassed,
giving a more accurate fit to each page. Also, forcing an actual
-reduction in the number of systems may save a further page. For
+reduction in the number of systems may save a further page. For
example, if the default layout has 11 systems, the following
assignment will force a layout with 10 systems.
@lilypond[verbatim,quote,relative=1]
e4 c g\f c
-\override DynamicText #'extra-offset = #'( -2.2 . 2.0)
-e4 c g\f c
+e4 c g-\tweak #'X-offset #-2.7 -\tweak #'Y-offset #2.5 \f c
@end lilypond
@item
@seealso
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Changing horizontal spacing}.
Snippets:
projects / lilypond.git / blobdiff