Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.13.39"
@ignore
GDP TODO list
so that neither the horizontal nor the vertical spacing is too cramped
or stretched.
-Settings which influence layout may be placed in two blocks.
-The @code{\paper @{...@}} block is placed outside any
-@code{\score @{...@}} blocks and contains settings that
-relate to the entire document. The @code{\layout @{...@}}
-block is placed within a @code{\score @{...@}} block and
-contains settings for that particular score. If you have
-only one @code{\score @{...@}} block the two have the same
-effect. In general the commands shown in this chapter can
-be placed in either.
+Two types of blocks can contain layout settings:
+@code{\paper @{@dots{}@}} and @code{\layout @{@dots{}@}}. The
+@code{\paper} block contains page layout settings that are
+expected to be the same for all scores in a book, such as the
+paper height, or whether to print page numbers, etc. See
+@ref{Page layout}. The @code{\layout} block contains score layout
+settings, such as the number of systems to use, or the space
+between staff-groups, etc. See @ref{Score layout}.
@menu
-* Paper and pages::
-* Music layout::
+* Page layout::
+* Score layout::
* Breaks::
* Vertical spacing::
* Horizontal spacing::
@end menu
-@node Paper and pages
-@section Paper and pages
+@node Page layout
+@section Page layout
-This section deals with the boundaries that define the area
-within which music can be printed.
+This section discusses page layout options for the @code{\paper}
+block.
@menu
-* Paper size::
-* Page formatting::
+* The \paper block::
+* Paper size and automatic scaling::
+* Fixed vertical spacing \paper variables::
+* Flexible vertical spacing \paper variables::
+* Horizontal spacing \paper variables::
+* Other \paper variables::
@end menu
-@node Paper size
-@subsection Paper size
+@node The \paper block
+@subsection The @code{\paper} block
+
+The @code{\paper} block can appear within a @code{\book} block,
+but not within a @code{\score} block. Settings in a @code{\paper}
+block apply to the entire book, which may include multiple scores.
+Settings that can appear in a @code{\paper} block include:
+
+@itemize
+
+@item
+the @code{set-paper-size} scheme function,
+
+@item
+@code{\paper} variables used for customizing page layout, and
+
+@item
+markup definitions used for customizing the layout of headers,
+footers, and titles.
+
+@end itemize
+
+The @code{set-paper-size} function is discussed in the next
+section, @ref{Paper size and automatic scaling}. The
+@code{\paper} variables that deal with page layout are discussed
+in later sections. The markup definitions that deal with headers,
+footers, and titles are discussed in
+@ref{Custom headers footers and titles}.
+
+Most @code{\paper} variables will only work in a @code{\paper}
+block. The few that will also work in a @code{\layout} block are
+listed in @ref{The \layout block}.
+
+Except when specified otherwise, all @code{\paper} variables that
+correspond to distances on the page are measured in millimeters,
+unless a different unit is specified by the user. For example,
+the following declaration sets @code{top-margin} to ten
+millimeters:
+
+@example
+\paper @{
+ top-margin = 10
+@}
+@end example
+
+To set it to @code{0.5} inches, use the @code{\in} unit suffix:
+
+@example
+\paper @{
+ top-margin = 0.5\in
+@}
+@end example
+
+The available unit suffixes are @code{\mm}, @code{\cm},
+@code{\in}, and @code{\pt}. 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{Custom headers footers and titles}.
+
+
+@node Paper size and automatic scaling
+@subsection Paper size and automatic scaling
@cindex paper size
@cindex page size
+@funindex \paper
+
+@menu
+* Setting paper size::
+* Automatic scaling to paper size::
+@end menu
+
+
+@node Setting paper size
+@unnumberedsubsubsec Setting paper size
+
Two functions are available for changing the paper size:
@code{set-default-paper-size} and @code{set-paper-size}.
@code{set-default-paper-size} must be placed in the toplevel
@end example
@noindent
+In the toplevel scope, the @code{set-default-paper-size} function
+can safely be called anywhere before the first @code{\paper}
+block. Within a @code{\paper} block, the safest place to call
+@code{set-paper-size} is at the top, above the list of variable
+declarations. The reasons for this are discussed in
+@ref{Automatic scaling to paper size}.
+
@code{set-default-paper-size} sets the size of all pages, whereas
@code{set-paper-size} only sets the size of the pages that the
@code{\paper} block applies to. For example, if the @code{\paper}
Common paper sizes are available, including @code{a4},
@code{letter}, @code{legal}, and @code{11x17} (also known as
tabloid). Many more paper sizes are supported by default. For
-details, see @file{scm/@/paper@/.scm}, and search for the
+details, see @file{scm/paper.scm}, and search for the
definition of @code{paper-alist}.
@c TODO add a new appendix for paper sizes (auto-generated) -pm
Extra sizes may be added by editing the definition of
@code{paper-alist} in the initialization file
-@file{scm/@/paper@/.scm}, however they will be overridden on a
+@file{scm/paper.scm}, however they will be overridden on a
subsequent install.
@cindex orientation
#(set-default-paper-size "a6" 'landscape)
@end example
-Setting the paper size will adjust a number of @code{\paper}
-variables, such as margins. To use a particular paper size with
-altered @code{\paper} variables, set the paper size before setting
-the variables.
-
-
@seealso
Installed Files:
-@file{scm/@/paper@/.scm}.
+@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
+@code{paper-height} or @code{paper-width}, 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}. 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}.
+
+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}.
-Snippets:
-@rlsr{Spacing}.
-
-
-@node Page formatting
-@subsection Page formatting
+@seealso
+Installed Files:
+@file{ly/paper-defaults-init.ly},
+@file{scm/paper.scm}.
-Margins, headers, and footers and other layout variables are
-automatically set according to the paper size.
-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.
+@node Fixed vertical spacing \paper variables
+@subsection Fixed vertical spacing @code{\paper} variables
-This section lists and describes a number of paper variables that
-may be altered.
+@warning{Some @code{@bs{}paper} dimensions are automatically
+scaled to the paper size, which may lead to unexpected behavior.
+See @ref{Automatic scaling to paper size}.}
-@menu
-* Vertical dimensions::
-* Horizontal dimensions::
-* Other layout variables::
-@end menu
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
+@table @code
+@item paper-height
+@funindex paper-height
-@node Vertical dimensions
-@unnumberedsubsubsec Vertical dimensions
+The height of the page, unset by default. Note that the automatic
+scaling of some vertical dimensions is not affected by this.
-These variables are used to set different vertical dimensions on a
-page:
+@item top-margin
+@funindex top-margin
-@funindex \paper
+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.
-@table @code
+@item bottom-margin
+@funindex bottom-margin
-@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
+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.
-For example, the default is:
+@item ragged-bottom
+@funindex ragged-bottom
-@example
-after-title-spacing = #'((space . 2) (padding . 0.5))
-@end example
+If set to true, systems will not spread vertically down the page.
+This does not affect the last page. This should be set to true
+for pieces that have only two or three systems per page, for
+example orchestral scores.
+@item ragged-last-bottom
+@funindex ragged-last-bottom
-If 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
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@item between-scores-system-spacing
-@funindex between-scores-system-spacing
+Snippets:
+@rlsr{Spacing}.
-Specifies the spacing between two systems if they are in different scores, but
-there is no title between them. See @var{after-title-spacing}.
+@knownissues
-@item between-system-spacing
-@funindex between-system-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.
-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}.
-@item between-title-spacing
-@funindex between-title-spacing
+@node Flexible vertical spacing \paper variables
+@subsection Flexible vertical spacing @code{\paper} variables
-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}.
+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.
-@item bottom-margin
-@funindex bottom-margin
+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}.
-The margin between footer and bottom of the page. Default:
-@code{6\mm}.
+@menu
+* Structure of flexible vertical spacing alists::
+* List of flexible vertical spacing \paper variables::
+@end menu
-@item bottom-system-spacing
-@funindex bottom-system-spacing
-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}.
+@node Structure of flexible vertical spacing alists
+@unnumberedsubsubsec Structure of flexible vertical spacing alists
-@item top-title-spacing
-@funindex top-title-spacing
+Each of the flexible vertical spacing @code{\paper} variables is
+an alist (association list) containing four @emph{keys}:
-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}.
+@itemize
-@item top-system-spacing
-@funindex top-system-spacing
+@item
+@code{padding} -- the minimum required amount of unobstructed
+vertical whitespace between two items, measured in staff-spaces.
+This can be thought of as the minimum height of an unobstructed
+(invisible) rectangle that extends from the leftmost to the
+rightmost point of the combined items.
-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{space} -- the vertical distance, measured in staff-spaces,
+between the @emph{reference points} of the two items, when no
+collisions would result, and no stretching or compressing is in
+effect. The reference point of a (title or top-level) markup is
+its highest point, and the reference point of a system is the
+vertical center of the nearest @code{StaffSymbol} -- even if a
+non-staff line (such as a @code{Lyrics} context) is in the way.
+Values for @code{space} that are less than either @code{padding}
+or @code{minimum-distance} are not meaningful, since the resulting
+distance will never be less than either @code{padding} or
+@code{minimum-distance}.
-@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}.
+@item
+@code{stretchability} -- a unitless measure of the dimension's
+relative propensity to stretch. If zero, the distance will not
+stretch (unless collisions would result). When positive, the
+significance of a particular dimension's @code{stretchability}
+value lies only in its relation to the @code{stretchability}
+values of the other dimensions. For example, if one dimension has
+twice the @code{stretchability} of another, it will stretch twice
+as easily. Values should be non-negative and finite. The value
+@code{+inf.0} triggers a @code{programming_error} and is ignored,
+but @code{1.0e7} can be used for an almost infinitely stretchable
+spring. If unset, the default value is set to @code{space}. Note
+that the dimension's propensity to @emph{compress} cannot be
+directly set by the user and is equal to
+(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
-@item top-margin
-@funindex top-margin
+@end itemize
-The margin between header and top of the page. Default:
-@code{5\mm}.
+If a page has a ragged bottom, the resulting distance is the
+largest of:
-@end table
+@itemize
+@item
+@code{space},
-@snippets
+@item
+@code{minimum-distance}, and
-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{padding} plus the smallest distance necessary to eliminate
+collisions.
-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.
+@end itemize
-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
+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 #'space = #8
+ score-system-spacing =
+ #'((padding . 1)
+ (space . 12)
+ (minimum-distance . 6)
+ (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.
-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}.
+@item score-markup-spacing
+@funindex score-markup-spacing
-The page layout itself is done by two functions in the
-@code{\paper} block, @code{page-music-height} and
-@code{page-make-stencil}. The former tells the line-breaking algorithm
-how much space can be spent on a page, the latter creates the actual
-page given the system to put on it.
+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
-@seealso
-Notation Reference:
-@ref{Vertical spacing between systems}.
+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.
-Snippets:
-@rlsr{Spacing}.
+@item system-system-spacing
+@funindex system-system-spacing
+the distance between two systems in the same score.
-@node Horizontal dimensions
-@unnumberedsubsubsec Horizontal dimensions
+@item markup-markup-spacing
+@funindex markup-markup-spacing
+the distance between two (title or top-level) markups.
-There are a few variables that determine the horizontal dimensions
-on a page:
+@item last-bottom-spacing
+@funindex last-bottom-spacing
-@table @code
+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 binding-offset
-@funindex binding-offset
+@item top-system-spacing
+@funindex top-system-spacing
-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}.
+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 horizontal-shift
-@funindex horizontal-shift
+@item top-markup-spacing
+@funindex top-markup-spacing
-The amount that all systems (including titles and system
-separators) are shifted to the right. Default: @code{0.0}.
+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
-@item indent
-@funindex indent
+@seealso
+Notation Reference:
+@ref{Flexible vertical spacing within systems}.
-The level of indentation for the first system in a score.
-Default: @code{15\mm}.
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@item inner-margin
-@funindex inner-margin
+Snippets:
+@rlsr{Spacing}.
-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}.
-@item left-margin
-@funindex left-margin
+@node Horizontal spacing \paper variables
+@subsection Horizontal spacing @code{\paper} variables
-The margin between the left edge of the page and the beginning of
-each system. Default: @code{10\mm}.
+@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}.}
-@item line-width
-@funindex line-width
+@menu
+* \paper variables for widths and margins::
+* \paper variables for two-sided mode::
+* \paper variables for shifts and indents::
+@end menu
-The width of music systems. Default: @code{paper-width} minus
-@code{left-margin} and @code{right-margin}.
-@item outer-margin
-@funindex outer-margin
+@node \paper variables for widths and margins
+@unnumberedsubsubsec @code{\paper} variables for widths and margins
-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}.
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
+
+@table @code
@item paper-width
@funindex paper-width
-The width of the page. Default: the width of the current paper
-size. For details, see @ref{Paper size}.
+The width of the page, unset by default. While @code{paper-width}
+has no effect on the automatic scaling of some horizontal
+dimensions, it does influence the @code{line-width} variable. If
+both @code{paper-width} and @code{line-width} are set, then
+@code{left-margin} and @code{right-margin} will also be updated.
+Also see @code{check-consistency}.
+
+@item line-width
+@funindex line-width
+
+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}.
+
+@item left-margin
+@funindex left-margin
+
+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
-each system. Default: @code{10\mm}.
+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 short-indent
-@funindex short-indent
+@item check-consistency
+@funindex check-consistency
-The level of indentation for all systems in a score besides the
-first system. Default: @code{0}.
+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
-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
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@itemize
-@item @var{left-margin}
-@item @var{right-margin}
-@item @var{top-margin}
-@item @var{bottom-margin}
-@item @var{head-separation}
-@item @var{foot-separation}
-@item @var{indent}
-@item @var{short-indent}
-@end itemize
-The settings for @code{line-width}, @code{left-margin},
-@code{right-margin} and @code{paper-width} depend on
-each other, but they do not have to be specified
-completely.
+@node \paper variables for two-sided mode
+@unnumberedsubsubsec @code{\paper} variables for two-sided mode
-@example
-\paper @{
- left-margin = 30\mm
-@}
-@end example
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
-In this example, only @code{left-margin} is set. The value for
-@code{right-margin} will remain default, @code{line-width} is
-calculated automatically.
+@table @code
-@example
-\paper @{
- line-width = 150\mm
-@}
-@end example
+@item two-sided
+@funindex two-sided
+
+@cindex gutter
+@cindex binding gutter
-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.
+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}.
-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.
+@item inner-margin
+@funindex inner-margin
-@example
-\paper @{
- paper-width = 210\mm
- left-margin = 20\mm
- right-margin = 30\mm
- line-width = 100\mm
-@}
-@end example
+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.
-These checks can be avoided by setting @code{check-consistency}
-to false.
+@item outer-margin
+@funindex outer-margin
-@example
-\paper @{
- paper-width = 210\mm
- left-margin = 20\mm
- line-width = 200\mm
- check-consistency = ##f
-@}
-@end example
+The margin all pages have at the outer side if they are part of a
+book. If the paper size is modified, this dimension's default
+value is scaled accordingly. Works only with @code{two-sided} set
+to true.
+
+@item binding-offset
+@funindex binding-offset
-@warning{If @code{paper-width} is manually set, @code{line-width},
-@code{left-margin}, @code{indent}, and @code{short-indent} may
-have to be adjusted as well.}
+The amount @code{inner-margin} is increased to make sure nothing
+will be hidden by the binding. If the paper size is modified,
+this dimension's default value is scaled accordingly. Works only
+with @code{two-sided} set to true.
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@end table
+@seealso
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@node Other layout variables
-@unnumberedsubsubsec Other layout variables
+@node \paper variables for shifts and indents
+@unnumberedsubsubsec @code{\paper} variables for shifts and indents
-These variables can be used to adjust page layout in general.
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
@table @code
-@item auto-first-page-number
-@funindex auto-first-page-number
+@item horizontal-shift
+@funindex horizontal-shift
-The page breaking algorithm is affected by the first page number
-being odd or even. If set to true, the page breaking algorithm
-will decide whether to start with an odd or even number. This
-will result in the first page number remaining as is or being
-increased by one. Default: @code{##f}.
+@c This default value is buried in the middle of page.scm. -mp
-@ignore
+The amount that all systems (including titles and system
+separators) are shifted to the right. Default: @code{0.0\mm}.
-TODO: this variable is used, but I don't know what it does. -pm
-@item blank-after-score-page-force
-@funindex blank-after-score-page-force
+@item indent
+@funindex indent
-Default: @code{2}.
+The level of indentation for the first system in a score. If the
+paper size is modified, this dimension's default value is scaled
+accordingly. This variable can also be set in a @code{\layout}
+block.
-@end ignore
+@item short-indent
+@funindex short-indent
-@item blank-last-page-force
-@funindex blank-last-page-force
+The level of indentation for all systems in a score besides the
+first system. If the paper size is modified, this dimension's
+default value is scaled accordingly. This variable can also be
+set in a @code{\layout} block.
-The penalty for ending the score on an odd-numbered page.
-Default: @code{0}.
+@end table
-@item blank-page-force
-@funindex blank-page-force
+@seealso
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-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}.
+Snippets:
+@rlsr{Spacing}.
-@item check-consistency
-@funindex check-consistency
-If set to true, check whether @code{left-margin}, @code{right-margin} and
-@code{line-width} fit each other. Also make sure that their combination
-does not exceed the available @code{paper-width}. Default: @code{##t}.
+@node Other \paper variables
+@subsection Other @code{\paper} variables
-@item first-page-number
-@funindex first-page-number
+@menu
+* \paper variables for line breaking::
+* \paper variables for page breaking::
+* \paper variables for page numbering::
+* Miscellaneous \paper variables::
+@end menu
-The value of the page number on the first page. Default:
-@code{#1}.
+
+@node \paper variables for line breaking
+@unnumberedsubsubsec @code{\paper} variables for line breaking
+
+@c TODO: Mention that ly:optimal-breaking is on by default? -mp
+
+@table @code
@item max-systems-per-page
@funindex max-systems-per-page
currently supported only by the @code{ly:optimal-breaking} algorithm.
Default: unset.
-@item page-breaking-between-system-spacing
-@funindex page-breaking-between-system-spacing
+@item systems-per-page
+@funindex systems-per-page
+
+The number of systems that should be placed on each page.
+This is currently supported only by the @code{ly:optimal-breaking} algorithm.
+Default: unset.
+
+@item system-count
+@funindex system-count
+
+The number of systems to be used for a score. Default: unset.
+This variable can also be set in a @code{\layout} block.
+
+@end table
+
+@seealso
+Notation Reference:
+@ref{Line breaking}.
+
+
+@node \paper variables for page breaking
+@unnumberedsubsubsec @code{\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
+
+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.
+
+@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.
+
+@item page-breaking
+@funindex page-breaking
+
+The page-breaking algorithm to use. Choices are
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
+@code{ly:optimal-breaking}.
+
+@item page-breaking-system-system-spacing
+@funindex page-breaking-system-system-spacing
Tricks the page breaker into thinking that
-@code{between-system-spacing} is set to something different than
+@code{system-system-spacing} is set to something different than
it really is. For example, if
-@code{page-breaking-between-system-spacing #'padding} is set to something
-substantially larger than @code{between-system-spacing #'padding}, then the
+@code{page-breaking-system-system-spacing #'padding} is set to something
+substantially larger than @code{system-system-spacing #'padding}, then the
page-breaker will put fewer systems on each page. Default: unset.
@item page-count
@funindex page-count
-The number of pages to be used for a score. Default: unset.
+The number of pages to be used for a score, unset by default.
-@item page-limit-inter-system-space
-@funindex page-limit-inter-system-space
+@end table
-If set to true, limits space between systems on a page with a lot
-of space left. Default: @code{##f}. For details, see
-@ref{Vertical spacing between systems}.
+@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
+
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
+
+@table @code
-The relative importance of page (vertical) spacing and line
-(horizontal) spacing. High values will make page spacing more
-important. Default: @code{#10}.
+@item auto-first-page-number
+@funindex auto-first-page-number
-@item print-all-headers
-@funindex print-all-headers
+The page breaking algorithm is affected by the first page number
+being odd or even. If set to true, the page breaking algorithm
+will decide whether to start with an odd or even number. This
+will result in the first page number remaining as is or being
+increased by one. Default: @code{#f}.
+
+@item first-page-number
+@funindex first-page-number
-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}.
@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.
-
-@item ragged-last
-@funindex ragged-last
+@end table
-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}.
+@seealso
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
-@item ragged-last-bottom
-@funindex ragged-last-bottom
-If set to false, systems will spread vertically across the last
-page. Default: @code{##t}.
+@node Miscellaneous \paper variables
+@unnumberedsubsubsec Miscellaneous @code{\paper} variables
-Pieces that amply fill two pages or more should have this set to
-true.
+@table @code
-It also affects the last page of book parts, ie parts of a book created
-with @code{\bookpart} blocks.
+@item page-spacing-weight
+@funindex page-spacing-weight
-@item ragged-right
-@funindex ragged-right
+The relative importance of page (vertical) spacing and line
+(horizontal) spacing. High values will make page spacing more
+important. Default: @code{#10}.
-If set to true, systems will not fill the line width. Instead,
-systems end at their natural horizontal length. Default:
-@code{##f}.
+@item print-all-headers
+@funindex print-all-headers
-If the score has only one system, the default value is @code{##t}.
+If set to true, this will print all headers for each @code{\score}
+in the output. Normally only the @code{piece} and @code{opus}
+header variables are printed. Default: @code{#f}.
@item system-separator-markup
@funindex system-separator-markup
-A markup object that is inserted between systems. This is often
-used for orchestral scores. Default: unset.
+A markup object that is inserted between systems, often used for
+orchestral scores. Default: unset. The @code{\slashSeparator}
+markup, defined in @file{ly/titling-init.ly}, is provided as a
+sensible default, for example:
-The markup command @code{\slashSeparator} is provided as a sensible
-default, for example
+@lilypond[quote,verbatim,noragged-right,line-width=30\mm]
+#(set-default-paper-size "a8")
-@lilypond[quote,ragged-right]
-#(set-default-paper-size "a6" 'landscape)
\book {
- \score {
- \relative c' { c1 \break c1 }
- }
\paper {
system-separator-markup = \slashSeparator
}
+ \header {
+ tagline = ##f
+ }
+ \score {
+ \relative c'' { c1 \break c1 \break c1 }
+ }
}
@end lilypond
-@item system-count
-@funindex system-count
-
-The number of systems to be used for a score.
-Default: unset.
-
-@item systems-per-page
-@funindex systems-per-page
-
-The number of systems that should be placed on each page.
-This is currently supported only by the @code{ly:optimal-breaking} algorithm.
-Default: unset.
-
-@item two-sided
-@funindex two-sided
-
-@cindex gutter
-@cindex binding gutter
-
-If set to true, use @code{inner-margin}, @code{outer-margin} and
-@code{binding-offset} to determine margins depending on whether
-the page number is odd or even. This overrides @code{left-margin}
-and @code{right-margin}. Default: @code{##f}.
-
@end table
@seealso
+Installed Files:
+@file{ly/titling-init.ly}.
+
Snippets:
@rlsr{Spacing}.
The default page header puts the page number and the @code{instrument}
field from the @code{\header} block on a line.
-The titles (from the @code{\header@{@}} section) are treated as a
-system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
-add space between the titles and the first system of the score.
+@node Score layout
+@section Score layout
-@node Music layout
-@section Music layout
+This section discusses score layout options for the @code{\layout}
+block.
@menu
+* The \layout block::
* Setting the staff size::
-* Score layout::
@end menu
+@node The \layout block
+@subsection The @code{\layout} block
+
+@funindex \layout
+
+While the @code{\paper} block contains settings that relate to the
+page formatting of the whole document, the @code{\layout} block
+contains settings for score-specific layout. To set score layout
+options globally, enter them in a toplevel @code{\layout} block.
+To set layout options for an individual score, enter them in a
+@code{\layout} block inside the @code{\score} block, after the
+music. Settings that can appear in a @code{\layout} block
+include:
+
+@itemize
+@item the @code{layout-set-staff-size} scheme function,
+@item context modifications in @code{\context} blocks, and
+@item @code{\paper} variables that affect score layout.
+@end itemize
+
+The @code{layout-set-staff-size} function is discussed in the next
+section, @ref{Setting the staff size}. Context modifications are
+discussed in a separate chapter; see
+@ref{Modifying context plug-ins} and
+@ref{Changing context default settings}. The @code{\paper}
+variables that can appear in a @code{\layout} block are:
+
+@itemize
+@item @code{ragged-right}
+@item @code{ragged-last}
+@item @code{indent}
+@item @code{short-indent}
+@item @code{system-count}
+@end itemize
+
+Here is an example @code{\layout} block:
+
+@example
+\layout @{
+ indent = 2.0\cm
+ \context @{
+ \StaffGroup
+ \override StaffGrouper #'staff-staff-spacing #space = #8
+ @}
+ \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 Setting the staff size
@subsection Setting the staff size
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
@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}.
-
Snippets:
@rlsr{Spacing}.
+Internals Reference:
+@rinternals{LineBreakEvent}.
+
@knownissues
Line breaks can only occur if there is a @q{proper} bar line. A note
which is hanging over a bar line is not proper, such as
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim]
c4 c2 << c2 {s4 \break } >> % this does nothing
c2 c4 | % a break here would work
c4 c2 c4 ~ \break % as does this break
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 }
- }
->>
+ \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{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
@lilypond[quote,verbatim]
-\new Score {
+\score {
\new Staff <<
- \new Voice {
+ \new Voice {
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0))
+ s1 * 2 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 35))
+ s1 * 3 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 70))
+ s1 * 6 \break
+
+ \overrideProperty "Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 105))
+ s1 * 5 \break
+ }
+ \new Voice {
+ \repeat unfold 2 { c'4 c'4 c'4 c'4 }
+ \repeat unfold 3 { c'4 c'4 c'4 c'4 }
+ \repeat unfold 6 { c'4 c'4 c'4 c'4 }
+ \repeat unfold 5 { c'4 c'4 c'4 c'4 }
+ }
+ >>
+}
+@end lilypond
+
+
+@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
+
+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) (space . 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 }
+ \context { \ChordNames \alignToZero \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 { s2\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}) is stored as an alist (association list),
+and each uses the same alist structure as the @code{\paper}
+spacing variables discussed in
+@ref{Flexible vertical spacing \paper variables}. Specific methods
+for modifying alists are discussed in @ref{Modifying alists}.
+Grob properties should be adjusted with an @code{\override} inside
+a @code{\score} or @code{\layout} block, and not inside a
+@code{\paper} block.
+
+The following example demonstrates the two ways these alists can
+be modified. The first declaration updates one key-value
+individually, and the second completely re-defines the property:
+
+@example
+\new Staff \with @{
+ \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+@} @{ @dots{} @}
+
+\new Staff \with @{
+ \override VerticalAxisGroup #'staff-staff-spacing =
+ #'((padding . 1)
+ (space . 10)
+ (minimum-distance . 9)
+ (stretchability . 10))
+@} @{ @dots{} @}
+@end example
+
+To change any spacing settings globally, put them in the
+@code{\layout} block:
+
+@example
+\layout @{
+ \context @{
+ \Staff
+ \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+ @}
+@}
+@end example
- \overrideProperty "Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
- s1 * 2 \break
+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}.
- \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{VerticalAxisGroup} 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{VerticalAxisGroup} properties are typically adjusted with an
+@code{\override} at the @code{Staff} level (or equivalent).
+@table @code
+@item staff-staff-spacing
+The distance between the current staff and the staff just below it
+in the same system, even if one or more non-staff lines (such as
+@code{Lyrics}) are placed between the two staves. Does not apply
+to the bottom staff of a system. This replaces any settings
+inherited from the @code{StaffGrouper} grob of the containing
+staff-group, if there is one. If this is unset, and there are no
+@code{StaffGrouper} properties to inherit, the
+@code{default-staff-staff-spacing} property is used.
+
+@item default-staff-staff-spacing
+The settings to use for @code{staff-staff-spacing} when it is
+unset. This applies to ungrouped staves and to grouped staves
+that do not inherit settings from the @code{StaffGrouper} grob.
+
+@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.
+
+@c TODO: verify last clause below ("even if other...")
+
+@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.
-@seealso
-Notation Reference:
-@ref{Vertical spacing}.
+@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
-Snippets:
-@rlsr{Spacing}.
+@subsubheading Properties of the @code{StaffGrouper} grob
-@node Vertical spacing
-@section Vertical spacing
+@code{StaffGrouper} properties are typically adjusted with an
+@code{\override} at the @code{StaffGroup} level (or equivalent).
-@cindex vertical spacing
-@cindex spacing, vertical
+@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 will be used
+instead for any staves in the staff-group that have it set. Also
+see @code{default-staff-staff-spacing}.
+
+@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 will be used instead for any staves
+in the staff-group that have it set. Also see
+@code{default-staff-staff-spacing}.
+@end table
-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.
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
-@menu
-* Vertical spacing inside a system::
-* Vertical spacing between systems::
-* Explicit staff and system positioning::
-* Vertical collision avoidance::
-@end menu
+Internals Reference:
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup},
+@rinternals{StaffGrouper}.
-@node Vertical spacing inside a system
-@subsection Vertical spacing inside a system
+@node Spacing of ungrouped staves
+@unnumberedsubsubsec Spacing of ungrouped staves
-@cindex distance between staves
-@cindex staff distance
-@cindex space between staves
-@cindex space inside systems
+@emph{Staves} (such as @code{Staff}, @code{DrumStaff},
+@code{TabStaff}, etc.) are contexts that can contain one or more
+voice contexts, but cannot contain any other staves.
-The height of each system is determined in two steps. First, all of the
-staves are spaced according to the amount of space available. Then, the
-non-staff lines (eg. lyrics or chords) are distributed between the
-staves.
+The following properties affect the spacing of @emph{ungrouped}
+staves:
-@unnumberedsubsubsec Spacing between staves
-Spacing between staves is controlled by the @var{next-staff-spacing}
-property of the @var{VerticalAxisGroup} grob. This property is an alist
-with four elements: @var{space}, @var{minimum-distance}, @var{padding}
-and @var{stretchability}:
@itemize
-@item
-@var{space} is the size of the stretchable space between the center line
-of one staff to the center line of the next staff.
+@item @code{VerticalAxisGroup} properties:
+@itemize
+@item @code{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{staff-staff-spacing}
+property can affect the spacing of ungrouped staves:
-@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 #'staff-staff-spacing =
+ #'((padding . 1)
+ (space . 8)
+ (minimum-distance . 7))
}
- { \clef bass c, }
- % By setting padding to a negative value, staves can be made to collide.
+}
+
+\new StaffGroup <<
+ % The very low note here needs more room than 'space can
+ % provide, so the distance between this staff and the next is
+ % determined by 'padding.
+ \new Staff { b,2 r | }
+
+ % Here, 'space provides enough room, and there is no need to
+ % compress the space (towards 'minimum-distance) to make room
+ % for anything else on the page, so the distance between this
+ % staff and the next is determined by 'space.
+ \new Staff { \clef bass g2 r | }
+
+ % By setting 'padding to a negative value, staves can be made to
+ % collide. The lowest acceptable value for 'space is 0.
\new Staff \with {
- \override VerticalAxisGroup #'next-staff-spacing =
- #'((space . 4) (padding . -10))
- }
- { \clef bass c, }
- \new Staff { \clef bass c, }
+ \override VerticalAxisGroup #'staff-staff-spacing =
+ #'((padding . -10)
+ (space . 3.5))
+ } { \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}
+@item @code{default-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 #'space = #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 #'space = #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 = #'((space . 30))
+ } { c'1 }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #UP }
- \lyricmode { up }
+ \override VerticalAxisGroup #'staff-affinity = #UP
+ } \lyricmode { up }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #CENTER }
- \lyricmode { center }
+ \override VerticalAxisGroup #'staff-affinity = #CENTER
+ } \lyricmode { center }
\new Lyrics \with {
- \override VerticalAxisGroup #'staff-affinity = #DOWN }
- \lyricmode { down }
- \new Staff
- { c'1 }
+ \override VerticalAxisGroup #'staff-affinity = #DOWN
+ } \lyricmode { down }
+ \new Staff { c'1 }
>>
@end lilypond
+
@seealso
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
Snippets:
@rlsr{Spacing}.
@c @lsr{spacing,alignment-vertical-spacing.ly}.
Internals Reference:
-@rinternals{VerticalAxisGroup},
-@rinternals{VerticalAlignment},
-@rinternals{Axis_group_engraver}.
-
-@knownissues
-Adjacent non-staff lines should have non-increasing
-@var{staff-affinity} from top-to-bottom. For example, the behavior of
-@example
-<<
- \new Staff c
- \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @}
- \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #UP @}
- \new Staff c
->>
-@end example
-is undefined.
-
-A non-staff line at the bottom of a system should have
-@var{staff-affinity} set to @code{UP}. Similarly, a non-staff
-line at the top of a system should have @var{staff-affinity} set
-to @code{DOWN}.
-
-@node Vertical spacing between systems
-@subsection Vertical spacing between systems
-
-The mechanisms that control spacing between systems are similar to those
-that control spacing between staves within a system (see
-@ref{Vertical spacing inside a system}). The main difference is that
-the variables to control spacing between systems are set in the
-@code{\paper} block, rather than as grob properties. These paper block
-variables are @var{between-system-spacing},
-@var{between-scores-system-spacing}, @var{after-title-spacing},
-@var{before-title-spacing}, @var{between-title-spacing},
-@var{top-system-spacing}, @var{top-title-spacing} and
-@var{bottom-system-spacing}. Note that these variables ignore non-staff
-lines. For example, @var{between-system-spacing} controls the spacing
-from the middle staff line of the bottom staff from one system to
-the middle staff line of the top staff of the next system, whether
-or not there are lyrics below the upper system.
-See @ref{Vertical dimensions} for a description of each of these
-variables.
-
-There are two more @code{\paper} block variables that affect vertical
-spacing: if @var{ragged-bottom} is set to @code{##t} then no pages will
-be stretched (which means that neither the space between systems nor the
-space within systems will be stretched). If @var{ragged-last-bottom}
-is set to @code{##t} then the last page will not be stretched.
-
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@rinternals{Contexts},
+@rinternals{VerticalAxisGroup}.
@node Explicit staff and system positioning
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
@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
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.
}
@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
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 = #'((padding . 0) (space . 0.1))
ragged-last-bottom = ##f
ragged-bottom = ##f
@}
@seealso
Notation Reference:
-@ref{Page formatting},
+@ref{Page layout},
@ref{Changing horizontal spacing}.
Snippets:
projects / lilypond.git / blobdiff