X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=inline;f=Documentation%2Fnotation%2Fspacing.itely;h=98f054555847d06c6042fe8a846adddb0b6c5708;hb=ace881437adc0146a62cffa3255ac1ca169bd054;hp=da64448d74b78b10036a5651d65b70cf716b0426;hpb=e1a149d0cc60b02e86209387958f4028567dd366;p=lilypond.git diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely index da64448d74..98f0545558 100644 --- a/Documentation/notation/spacing.itely +++ b/Documentation/notation/spacing.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.12.0" +@c \version "2.13.42" @ignore GDP TODO list @@ -68,19 +68,18 @@ estimated. Finally, a page breaking and line breaking combination is chosen 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:: @@ -88,24 +87,118 @@ be placed in either. @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 @@ -123,6 +216,13 @@ block: @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} @@ -133,7 +233,7 @@ to all pages. If the @code{\paper} block is inside a 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 @@ -142,7 +242,7 @@ definition of @code{paper-alist}. 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 @@ -156,619 +256,820 @@ degrees, and wider line widths will be set accordingly. #(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 -Installed Files: -@file{scm/@/paper@/.scm}. +Notation Reference: +@ref{Fixed vertical spacing \paper variables}, +@ref{Horizontal spacing \paper variables}. -Snippets: -@rlsr{Spacing}. +Installed Files: +@file{ly/paper-defaults-init.ly}, +@file{scm/paper.scm}. -@node Page formatting -@subsection Page formatting +@node Fixed vertical spacing \paper variables +@subsection Fixed vertical spacing @code{\paper} variables -Margins, headers, and footers and other layout variables are -automatically set according to the paper size. +@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}.} -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. +Default values (before scaling) are defined in +@file{ly/paper-defaults-init.ly}. -This section lists and describes a number of paper variables that -may be altered. +@table @code +@item paper-height +@funindex paper-height -@menu -* Vertical dimensions:: -* Horizontal dimensions:: -* Other layout variables:: -@end menu +The height of the page, unset by default. Note that the automatic +scaling of some vertical dimensions is not affected by this. +@item top-margin +@funindex top-margin -@node Vertical dimensions -@unnumberedsubsubsec Vertical dimensions +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. -These variables are used to set different vertical dimensions on a -page: +@item bottom-margin +@funindex bottom-margin -@funindex \paper +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. -@table @code +@item ragged-bottom +@funindex ragged-bottom -@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 +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. -For example, the default is: +@item ragged-last-bottom +@funindex ragged-last-bottom -@example -after-title-spacing = #'((space . 2) (padding . 0.5)) -@end example +If set to false, systems will spread vertically down the last +page. Pieces that amply fill two pages or more should have this +set to true. It also affects the last page of book parts, i.e. +parts of a book created with @code{\bookpart} blocks. +@end table -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 +@seealso +Notation Reference: +@ref{Automatic scaling to paper size}. -@item before-title-spacing -@funindex before-title-spacing +Installed Files: +@file{ly/paper-defaults-init.ly}. -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}. +Snippets: +@rlsr{Spacing}. -@item between-scores-system-spacing -@funindex between-scores-system-spacing +@knownissues -Specifies the spacing between two systems if they are in different scores, but -there is no title between them. 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-system-spacing -@funindex between-system-spacing -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}. +@node Flexible vertical spacing \paper variables +@subsection Flexible vertical spacing @code{\paper} variables -@item between-title-spacing -@funindex between-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. -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}. +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-margin -@funindex bottom-margin +@menu +* Structure of flexible vertical spacing alists:: +* List of flexible vertical spacing \paper variables:: +@end menu -The margin between footer and bottom of the page. Default: -@code{6\mm}. -@item bottom-system-spacing -@funindex bottom-system-spacing +@node Structure of flexible vertical spacing alists +@unnumberedsubsubsec Structure of flexible vertical spacing alists -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}. +Each of the flexible vertical spacing @code{\paper} variables is +an alist (association list) containing four @emph{keys}: -@item top-title-spacing -@funindex top-title-spacing +@itemize -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}. +@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 top-system-spacing -@funindex top-system-spacing +@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.} -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}. +@c TODO: explain skylines somewhere and xref to it from here. -@item paper-height -@funindex paper-height +@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 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{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}). -@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{basic-distance}, -@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 #'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. -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 + +Default values (before scaling) that are not listed here are +defined in @file{ly/paper-defaults-init.ly}. -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}. +@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}. 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 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 +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. -@example -\paper @{ - left-margin = 30\mm -@} -@end example +@node \paper variables for two-sided mode +@unnumberedsubsubsec @code{\paper} variables for two-sided mode -In this example, only @code{left-margin} is set. The value for -@code{right-margin} will remain default, @code{line-width} is -calculated automatically. +Default values (before scaling) are defined in +@file{ly/paper-defaults-init.ly}. -@example -\paper @{ - line-width = 150\mm -@} -@end example +@table @code -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. +@item two-sided +@funindex two-sided -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. +@cindex gutter +@cindex binding gutter -@example -\paper @{ - paper-width = 210\mm - left-margin = 20\mm - right-margin = 30\mm - line-width = 100\mm -@} -@end example +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}. -These checks can be avoided by setting @code{check-consistency} -to false. +@item inner-margin +@funindex inner-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 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. -@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.} +@item outer-margin +@funindex outer-margin + +The margin all pages have at the outer side if they are part of a +book. If the paper size is modified, this dimension's default +value is scaled accordingly. Works only with @code{two-sided} set +to true. + +@item binding-offset +@funindex binding-offset + +The amount @code{inner-margin} is increased to make sure nothing +will be hidden by the binding. If the paper size is modified, +this dimension's default value is scaled accordingly. Works only +with @code{two-sided} set to true. + +@end table @seealso -Snippets: -@rlsr{Spacing}. +Notation Reference: +@ref{Automatic scaling to paper size}. +Installed Files: +@file{ly/paper-defaults-init.ly}. -@node Other layout variables -@unnumberedsubsubsec Other layout variables +@node \paper variables for shifts and indents +@unnumberedsubsubsec @code{\paper} variables for shifts and indents -These variables can be used to adjust page layout in general. +Default values (before scaling) that are not listed here are +defined in @file{ly/paper-defaults-init.ly}. @table @code -@item auto-first-page-number -@funindex auto-first-page-number +@item horizontal-shift +@funindex horizontal-shift -The page breaking algorithm is affected by the first page number -being odd or even. If set to true, the page breaking algorithm -will decide whether to start with an odd or even number. This -will result in the first page number remaining as is or being -increased by one. Default: @code{##f}. +@c This default value is buried in the middle of page.scm. -mp -@ignore +The amount that all systems (including titles and system +separators) are shifted to the right. Default: @code{0.0\mm}. -TODO: this variable is used, but I don't know what it does. -pm -@item blank-after-score-page-force -@funindex blank-after-score-page-force +@item indent +@funindex indent -Default: @code{2}. +The level of indentation for the first system in a score. If the +paper size is modified, this dimension's default value is scaled +accordingly. This variable can also be set in a @code{\layout} +block. -@end ignore +@item short-indent +@funindex short-indent -@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 +Notation Reference: +@ref{Automatic scaling to paper size}. -The penalty for having a blank page in the middle of a -score. This is not used by @code{ly:optimal-breaking} since it will -never consider blank pages in the middle of a score. Default: -@code{5}. +Installed Files: +@file{ly/paper-defaults-init.ly}. -@item check-consistency -@funindex check-consistency +Snippets: +@rlsr{Spacing}. -If set to true, check whether @code{left-margin}, @code{right-margin} and -@code{line-width} fit each other. Also make sure that their combination -does not exceed the available @code{paper-width}. Default: @code{##t}. -@item first-page-number -@funindex first-page-number +@node Other \paper variables +@subsection Other @code{\paper} variables + +@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 + 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 +@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 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 -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 -If set to true, this will print all headers for each \score in the -output. Normally only the piece and opus header variables are -printed. Default: @code{##f}. +@item auto-first-page-number +@funindex auto-first-page-number + +The page breaking algorithm is affected by the first page number +being odd or even. If set to true, the page breaking algorithm +will decide whether to start with an odd or even number. This +will result in the first page number remaining as is or being +increased by one. Default: @code{#f}. + +@item first-page-number +@funindex first-page-number + +The value of the page number on the first page. @item print-first-page-number @funindex print-first-page-number If set to true, a page number is printed on the first page. -Default: @code{##f}. @item print-page-number @funindex print-page-number -If set to false, page numbers are not printed. Default: -@code{##t}. - -@item ragged-bottom -@funindex ragged-bottom - -If set to 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 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 +@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 -@cindex gutter -@cindex binding gutter +@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 -If set to true, use @code{inner-margin}, @code{outer-margin} and -@code{binding-offset} to determine margins depending on whether -the page number is odd or even. This overrides @code{left-margin} -and @code{right-margin}. Default: @code{##f}. +The @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 @@ -795,9 +1096,9 @@ fonts accordingly. 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 @@ -879,37 +1180,6 @@ Snippets: 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 @@ -932,18 +1202,58 @@ Snippets: Line breaks are normally determined automatically. They are chosen so that lines look neither cramped nor loose, and consecutive -lines have similar density. Occasionally you might want to -override the automatic breaks; you can do this by specifying -@code{\break}. This will force a line break at this point. However, -line breaks can only occur at the end of @q{complete} bars, i.e., -where there are no notes or tuplets left @q{hanging} over the bar -line. If you want to have a line break where there is no bar line, -you can force an invisible bar line by entering @code{\bar ""}, -although again there must be no notes left hanging over in any of -the staves at this point, or it will be ignored. - -The opposite command, @code{\noBreak}, forbids a line break at the -bar line where it is inserted. +lines have similar density. + +To manually force a line break at a bar line, use the +@code{\break} command: + +@lilypond[quote,ragged-right,relative=2,verbatim] +c4 c c c | \break +c4 c c c | +@end lilypond + +By default, a @code{\break} in the middle of a measure is ignored, +and a warning is printed. To force a line break in the middle of +a measure, add an invisible bar line with @w{@samp{\bar ""}}: + +@lilypond[quote,ragged-right,relative=2,verbatim] +c4 c c +\bar "" \break +c | +c4 c c c | +@end lilypond + +A @code{\break} occuring at a bar line is also ignored if the +previous measure ends in the middle of a note, such as when a +tuplet begins and ends in different measures. To allow +@code{\break} commands to work in these situations, remove the +@code{Forbid_line_break_engraver} from the @code{Voice} context. +Note that manually forced line breaks have to be added in parallel +with the music: + +@lilypond[quote,ragged-right,verbatim] +\new Voice \with { + \remove Forbid_line_break_engraver +} \relative c'' { + << + { c2. \times 2/3 { c4 c c } c2. | } + { s1 | \break s1 | } + >> +} +@end lilypond + +Similarly, line breaks are normally forbidden when beams cross bar +lines. This behavior can be changed by setting +@code{\override Beam #'breakable = ##t}: + +@lilypond[quote,ragged-right,relative=2,verbatim] +\override Beam #'breakable = ##t +c2. c8[ c | \break +c8 c] c2. | +@end lilypond + +The @code{\noBreak} command forbids a line break at the bar line +where it is inserted. The most basic settings influencing line spacing are @code{indent} and @code{line-width}. They are set in the @code{\layout} block. @@ -963,9 +1273,9 @@ but affects only the last line of the piece. @example \layout @{ -indent = #0 -line-width = #150 -ragged-last = ##t + indent = 0\mm + line-width = 150\mm + ragged-last = ##t @} @end example @@ -980,15 +1290,17 @@ cause the following 28 measures (assuming 4/4 time) to be broken every 4 measures, and only there: @example -<< \repeat unfold 7 @{ - s1 \noBreak s1 \noBreak - s1 \noBreak s1 \break @} - @emph{the real music} +<< + \repeat unfold 7 @{ + s1 \noBreak s1 \noBreak + s1 \noBreak s1 \break + @} + @{ @var{the actual music@dots{}} @} >> @end example @c TODO Check this -A linebreaking configuration can be saved as a @code{.ly} file +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 @@ -1004,41 +1316,14 @@ 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 @@ -1058,9 +1343,8 @@ There are also analogous settings to @code{ragged-right} and @code{ragged-last} which have the same effect on vertical spacing: @code{ragged-bottom} and @code{ragged-last-bottom}. If set to @code{##t} the systems on all pages or just the last page -respectively will not be justified vertically. - -For more details see @ref{Vertical spacing}. +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, @@ -1069,8 +1353,8 @@ 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 @@ -1091,7 +1375,7 @@ book parts. \paper @{ %% In a part consisting mostly of text, %% ly:minimal-breaking may be preferred - #(define page-breaking ly:minimal-breaking) + page-breaking = #ly:minimal-breaking @} \markup @{ @dots{} @} @dots{} @@ -1117,6 +1401,9 @@ book parts. @seealso +Notation Reference: +@ref{\paper variables for page breaking}. + Snippets: @rlsr{Spacing}. @@ -1237,7 +1524,7 @@ too slow or memory demanding, or a lot of texts. It is enabled using: @example \paper @{ - #(define page-breaking ly:minimal-breaking) + page-breaking = #ly:minimal-breaking @} @end example @@ -1270,322 +1557,661 @@ page breaks at explicit @code{\pageBreak} commands and nowhere else. 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}. +@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 + +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 } + \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: -@node Using an extra voice for breaks -@subsection Using an extra voice for breaks +@example +\new Staff \with @{ + \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10 +@} @{ @dots{} @} + +\new Staff \with @{ + \override VerticalAxisGroup #'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 #'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 +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. - \overrideProperty "Score.NonMusicalPaperColumn" - #'line-break-system-details #'((Y-offset . 35)) - s1 * 3 \break +@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 . 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 +@subsubheading Properties of the @code{StaffGrouper} grob +@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 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 @seealso -Notation Reference: -@ref{Vertical spacing}. +Installed Files: +@file{ly/engraver-init.ly}, +@file{scm/define-grobs.scm}. -Snippets: -@rlsr{Spacing}. +Internals Reference: +@rinternals{Contexts}, +@rinternals{VerticalAxisGroup}, +@rinternals{StaffGrouper}. -@node Vertical spacing -@section Vertical spacing +@node Spacing of ungrouped staves +@unnumberedsubsubsec Spacing of ungrouped staves -@cindex vertical spacing -@cindex spacing, vertical +@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. -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. +The following properties affect the spacing of @emph{ungrouped} +staves: -@menu -* Vertical spacing inside a system:: -* Vertical spacing between systems:: -* Explicit staff and system positioning:: -* Vertical collision avoidance:: -@end menu +@itemize +@item @code{VerticalAxisGroup} properties: +@itemize +@item @code{staff-staff-spacing} +@end itemize +@end itemize +These grob properties are described individually above; see +@ref{Within-system spacing properties}. -@node Vertical spacing inside a system -@subsection Vertical spacing inside a system +Additional properties are involved for staves that are part of a +staff-group; see @ref{Spacing of grouped staves}. -@cindex distance between staves -@cindex staff distance -@cindex space between staves -@cindex space inside systems +The following example shows how the @code{staff-staff-spacing} +property can affect the spacing of ungrouped 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. +@lilypond[verbatim,quote,staffsize=16] +\layout { + \context { + \Staff + \override VerticalAxisGroup #'staff-staff-spacing = + #'((basic-distance . 8) + (minimum-distance . 7) + (padding . 1)) + } +} -@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. +\new StaffGroup << + % 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 #'staff-staff-spacing = + #'((basic-distance . 3.5) + (padding . -10)) + } { \clef bass g2 r | } + \new Staff { \clef bass g2 r | } +>> +@end lilypond -@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}. +@seealso +Installed Files: +@file{scm/define-grobs.scm}. -@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. +Snippets: +@rlsr{Spacing}. -@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}. +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 -@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)) - } - { \clef bass c, } - % By setting padding to a negative value, staves can be made to collide. - \new Staff \with { - \override VerticalAxisGroup #'next-staff-spacing = - #'((space . 4) (padding . -10)) - } - { \clef bass c, } - \new Staff { \clef bass c, } ->> -@end lilypond +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 + +These grob properties are described individually above; see +@ref{Within-system spacing properties}. -@lilypond[verbatim] -#(set-global-staff-size 16) +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}. @@ -1593,75 +2219,25 @@ Snippets: @c @lsr{spacing,alignment-vertical-spacing.ly}. Internals Reference: -@rinternals{VerticalAxisGroup}, -@rinternals{VerticalAlignment}, -@rinternals{Axis_group_engraver}. - -@knownissues -Adjacent non-staff lines should have non-increasing -@var{staff-affinity} from top-to-bottom. For example, the behavior of -@example -<< - \new Staff c - \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #DOWN @} - \new Lyrics \with @{ \override VerticalAxisGroup #'staff-affinity = #UP @} - \new Staff c ->> -@end example -is undefined. - -A non-staff line at the bottom of a system should have -@var{staff-affinity} set to @code{UP}. Similarly, a non-staff -line at the top of a system should have @var{staff-affinity} set -to @code{DOWN}. - -@node Vertical spacing between systems -@subsection Vertical spacing between systems - -The mechanisms that control spacing between systems are similar to those -that control spacing between staves within a system (see -@ref{Vertical spacing inside a system}). The main difference is that -the variables to control spacing between systems are set in the -@code{\paper} block, rather than as grob properties. These paper block -variables are @var{between-system-spacing}, -@var{between-scores-system-spacing}, @var{after-title-spacing}, -@var{before-title-spacing}, @var{between-title-spacing}, -@var{top-system-spacing}, @var{top-title-spacing} and -@var{bottom-system-spacing}. Note that these variables ignore non-staff -lines. For example, @var{between-system-spacing} controls the spacing -from the middle staff line of the bottom staff from one system to -the middle staff line of the top staff of the next system, whether -or not there are lyrics below the upper system. -See @ref{Vertical dimensions} for a description of each of these -variables. - -There are two more @code{\paper} block variables that affect vertical -spacing: if @var{ragged-bottom} is set to @code{##t} then no pages will -be stretched (which means that neither the space between systems nor the -space within systems will be stretched). If @var{ragged-last-bottom} -is set to @code{##t} then the last page will not be stretched. - -@seealso -Snippets: -@rlsr{Spacing}. +@rinternals{Contexts}, +@rinternals{VerticalAxisGroup}. @node Explicit staff and system positioning @subsection Explicit staff and system positioning -One way to understand the @code{VerticalAxisGroup} and @code{\paper} -settings explained in the previous two sections is as a collection of -different settings that primarily concern the amount of vertical padding -different staves and systems running down the page. +One way to understand the flexible vertical spacing mechanisms +explained above is as a collection of settings that control the +amount of vertical padding between staves and systems. -It is possible to approach vertical spacing in a different way using -@code{NonMusicalPaperColumn #'line-break-system-details}. Where -@code{VerticalAxisGroup} and @code{\paper} settings specify vertical padding, -@code{NonMusicalPaperColumn #'line-break-system-details} specifies exact -vertical positions on the page. +It is possible to approach vertical spacing in a different way +using @code{NonMusicalPaperColumn #'line-break-system-details}. +While the flexible vertical spacing mechanisms specify vertical +padding, @code{NonMusicalPaperColumn #'line-break-system-details} +can specify exact vertical positions on the page. -@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative -list of three different settings: +@code{NonMusicalPaperColumn #'line-break-system-details} accepts +an associative list of three different settings: @itemize @item @code{X-offset} @@ -1694,13 +2270,15 @@ example @code{NonMusicalPaperColumn} overrides with the special #'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 @@ -1710,7 +2288,7 @@ by looking at an example that includes no overrides at all. @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 { @@ -1743,7 +2321,7 @@ the vertical startpoint of each system explicitly, we can set the @code{Y-offset} pair in the @code{line-break-system-details} attribute of the @code{NonMusicalPaperColumn} grob: -@lilypond[quote] +@lilypond[verbatim,quote,staffsize=16] \header { tagline = ##f } \paper { left-margin = 0\mm } \book { @@ -1781,7 +2359,7 @@ explicitly, we can also set the vertical distances between staves within each system manually. We do this using the @code{alignment-distances} subproperty of @code{line-break-system-details}. -@lilypond[quote] +@lilypond[verbatim,quote,staffsize=16] \header { tagline = ##f } \paper { left-margin = 0\mm } \book { @@ -1822,7 +2400,7 @@ additional spacing parameters (including, for example, a corresponding 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 { @@ -1909,7 +2487,7 @@ is, if two outside-staff grobs are competing for the same space, the one 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 @@ -1926,7 +2504,7 @@ The vertical padding between an outside-staff object and the previously-positioned grobs can be controlled with @code{outside-staff-padding}. -@lilypond[quote,ragged-right,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 @@ -1938,13 +2516,13 @@ c^"This text is placed close to the previous text" 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 @@ -1994,7 +2572,7 @@ For example, the following piece contains lots of half, quarter, and 8th notes; the eighth note is followed by 1 note head width (NHW). The quarter note is followed by 2 NHW, the half by 3 NHW, etc. -@lilypond[quote,fragment,verbatim,relative=1] +@lilypond[quote,verbatim,relative=1] c2 c4. c8 c4. c8 c4. c8 c8 c8 c4 c4 c4 @end lilypond @@ -2037,7 +2615,7 @@ followed by a space that is proportional to their duration relative to 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 @@ -2056,11 +2634,11 @@ once with exaggerated corrections: @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 @@ -2100,7 +2678,7 @@ sections with a different notions of long and short notes. 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 @@ -2157,7 +2735,7 @@ than @code{1 16}. \context { \Score \override SpacingSpanner - #'base-shortest-duration = #(ly:make-moment 1 16) + #'base-shortest-duration = #(ly:make-moment 1 16) } } } @@ -2172,29 +2750,35 @@ such symbols and force uniform equal-duration spacing, use @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 @@ -2288,15 +2872,17 @@ We start with the following one-measure example, which uses classical 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 @@ -2315,17 +2901,23 @@ turn proportional notation on with the proportionalNotationDuration 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 @@ -2333,72 +2925,90 @@ the second half of the measure now occupy equal amounts of horizontal 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. @@ -2407,71 +3017,84 @@ classical spacing, when we add a second staff with a different type of 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 @@ -2690,7 +3313,7 @@ Snippets: 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: @@ -2702,7 +3325,7 @@ there is no blank space at the bottom of the page. @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 @} @@ -2734,8 +3357,7 @@ a system can be moved closer to the staff: @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 @@ -2790,7 +3412,7 @@ block so that it applies to the whole score. @seealso Notation Reference: -@ref{Page formatting}, +@ref{Page layout}, @ref{Changing horizontal spacing}. Snippets: