version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.51"
+@c \version "2.12.0"
@ignore
GDP TODO list
> and prints page number -1 on the second page, for example.
-- default paper size is A4.
-
-
In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
states:
@end ignore
+
@node Spacing issues
@chapter Spacing issues
be placed in either.
@menu
-* Paper and pages::
+* Paper and pages::
* Music layout::
* Breaks::
* Vertical spacing::
within which music can be printed.
@menu
-* Paper size::
-* Page formatting::
+* Paper size::
+* Page formatting::
@end menu
@cindex paper size
@cindex page size
-@funindex papersize
-To change the paper size, there are two commands,
+Two functions are available for changing the paper size:
+@code{set-default-paper-size} and @code{set-paper-size}.
+@code{set-default-paper-size} must be placed in the toplevel
+scope, and @code{set-paper-size} must be placed in a @code{\paper}
+block:
+
@example
#(set-default-paper-size "a4")
@end example
+
@example
\paper @{
#(set-paper-size "a4")
@}
@end example
-The first command sets the size of all pages. The second command sets the
-size
-of the pages that the @code{\paper} block applies to -- if the @code{\paper}
-block is at the top of the file, then it will apply to all pages. If the
-@code{\paper} block is inside a @code{\book}, then the paper size will only
-apply to that book.
+@noindent
+@code{set-default-paper-size} sets the size of all pages, whereas
+@code{set-paper-size} only sets the size of the pages that the
+@code{\paper} block applies to. For example, if the @code{\paper}
+block is at the top of the file, then it will apply the paper size
+to all pages. If the @code{\paper} block is inside a
+@code{\book}, then the paper size will only apply to that book.
+
+Common paper sizes are available, including @code{a4},
+@code{letter}, @code{legal}, and @code{11x17} (also known as
+tabloid). Many more paper sizes are supported by default. For
+details, see @file{scm/@/paper@/.scm}, and search for the
+definition of @code{paper-alist}.
-Support for the following paper sizes are included by default,
-@code{a6}, @code{a5}, @code{a4}, @code{a3}, @code{legal}, @code{letter},
-@code{11x17} (also known as tabloid).
+@c TODO add a new appendix for paper sizes (auto-generated) -pm
-@c TODO Add new paper sizes -td
+@warning{The default paper size is @code{a4}.}
-Extra sizes may be added by editing the definition for
-@code{paper-alist} in the initialization file @file{scm/paper.scm}.
+Extra sizes may be added by editing the definition of
+@code{paper-alist} in the initialization file
+@file{scm/@/paper@/.scm}, however they will be overridden on a
+subsequent install.
@cindex orientation
@cindex landscape
-If the symbol @code{landscape} is supplied as an argument to
-@code{set-default-paper-size}, the pages will be rotated by 90 degrees,
-and wider line widths will be set correspondingly.
+If the symbol @code{'landscape} is supplied as an argument to
+@code{set-default-paper-size}, pages will be rotated by 90
+degrees, and wider line widths will be set accordingly.
@example
#(set-default-paper-size "a6" 'landscape)
@end example
-Setting the paper size will adjust a number of @code{\paper} variables
-(such as margins). To use a particular paper size with altered
-@code{\paper} variables, set the paper size before setting the variables.
+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.
-@node Page formatting
-@subsection Page formatting
-
-@cindex page formatting
-@cindex margins
-@cindex header, page
-@cindex footer, page
-
-LilyPond will do page layout, set margins, and add headers and
-footers to each page.
-
-The default layout responds to the following settings in the
-@code{\paper} block.
+@seealso
+Installed Files:
+@file{scm/@/paper@/.scm}.
-@funindex \paper
+Snippets:
+@rlsr{Spacing}.
-@quotation
-@table @code
-@funindex first-page-number
-@item first-page-number
-The value of the page number of the first page. Default is@tie{}1.
-@funindex print-first-page-number
-@item print-first-page-number
-If set to true, will print the page number in the first page. Default is
-false.
+@node Page formatting
+@subsection Page formatting
-@funindex print-page-number
-@item print-page-number
-If set to false, page numbers will not be printed. Default is true.
+Margins, headers, and footers and other layout variables are
+automatically set according to the paper size.
-@funindex paper-width
-@item paper-width
-The width of the page. The default is taken from the current paper size,
-see @ref{Paper size}.
+This section lists and describes a number of paper variables that
+may be altered.
-@funindex paper-height
-@item paper-height
-The height of the page. The default is taken from the current paper size,
-see @ref{Paper size}.
+@menu
+* Vertical dimensions::
+* Horizontal dimensions::
+* Other layout variables::
+@end menu
-@funindex top-margin
-@item top-margin
-Margin between header and top of the page. Default is@tie{}5mm.
-@funindex bottom-margin
-@item bottom-margin
-Margin between footer and bottom of the page. Default is@tie{}6mm.
+@node Vertical dimensions
+@unnumberedsubsubsec Vertical dimensions
-@funindex left-margin
-@item left-margin
-Margin between the left side of the page and the beginning of the
-music. Unset by default, which means that the margins is determined
-based on the @code{paper-width} and @code{line-width} to center the
-score on the paper.
+These variables are used to set different vertical dimensions on a
+page:
-@funindex line-width
-@item line-width
-The length of the systems. Default is @code{paper-width} minus @tie{}20mm.
+@funindex \paper
-@funindex head-separation
-@item head-separation
-Distance between the top-most music system and the page header. Default
-is@tie{}4mm.
+@table @code
-@funindex foot-separation
-@item foot-separation
-Distance between the bottom-most music system and the page
-footer. Default is@tie{}4mm.
+@item after-title-space
+@funindex after-title-space
-@funindex page-top-space
-@item page-top-space
-Distance from the top of the printable area to the center of the first
-staff. This only works for staves which are vertically small. Big staves
-are set with the top of their bounding box aligned to the top of the
-printable area. Default is@tie{}12mm.
+The amount of space between the title and the first system.
+Default: @code{5\mm}.
-@funindex ragged-bottom
-@item ragged-bottom
-If set to true, systems will not be spread vertically across the page. This
-does not affect the last page. Default is false.
+@item before-title-space
+@funindex before-title-space
-This should be set to true for pieces that have only two or three
-systems per page, for example orchestral scores.
+Amount of space between the last system of the previous piece and the
+title of the next. Default: @code{10\mm}.
-@funindex ragged-last-bottom
-@item ragged-last-bottom
-If set to false, systems will be spread vertically to fill the last
-page. Default is true.
+@item between-system-padding
+@funindex between-system-padding
-Pieces that amply fill two pages or more should have this set to
-true.
+The minimum amount of white space that will always be present
+between the bottom-most symbol of one system, and the top-most of
+the next system. Default: @code{4\mm}.
-@funindex system-count
-@item system-count
-This variable, if set, specifies into how many lines a score should be
-broken. Unset by default.
+Increasing this will put systems whose bounding boxes almost touch
+farther apart.
-@funindex between-system-space
@item between-system-space
-This dimensions determines the distance between systems. It is the
-ideal distance between the center of the bottom staff of one system
-and the center of the top staff of the next system. Default is@tie{}20mm.
+@funindex between-system-space
-Increasing this will provide a more even appearance of the page at the
-cost of using more vertical space.
+The distance between systems. It is the ideal distance between
+the center of the bottom staff of one system and the center of the
+top staff of the next system. Default: @code{20\mm}.
-@funindex between-system-padding
-@item between-system-padding
-This dimension is the minimum amount of white space that will always
-be present between the bottom-most symbol of one system, and the
-top-most of the next system. Default is@tie{}4mm.
+Increasing this value will provide a more even appearance of the
+page at the cost of using more vertical space.
-Increasing this will put systems whose bounding boxes almost touch
-farther apart.
+@item between-title-space
+@funindex between-title-space
-@funindex page-breaking-between-system-padding
-@item page-breaking-between-system-padding
-This variable tricks the page breaker into thinking that
-@code{between-system-padding} is set to something different than it
-really is. For example, if this variable is set to something substantially
-larger than @code{between-system-padding}, then the page-breaker will put
-fewer systems on each page.
+Amount of space between consecutive titles (e.g., the title of the
+book and the title of a piece). Default: @code{2\mm}.
-@funindex horizontal-shift
-@item horizontal-shift
-All systems (including titles and system separators) are shifted by
-this amount to the right. Page markup, such as headers and footers are
-not affected by this. The purpose of this variable is to make space
-for instrument names at the left. Default is@tie{}0.
+@item bottom-margin
+@funindex bottom-margin
-@funindex after-title-space
-@item after-title-space
-Amount of space between the title and the first system. Default is@tie{}5mm.
+The margin between footer and bottom of the page. Default:
+@code{6\mm}.
-@funindex before-title-space
-@item before-title-space
-Amount of space between the last system of the previous piece and the
-title of the next. Default is@tie{}10mm.
+@item foot-separation
+@funindex foot-separation
-@funindex between-title-space
-@item between-title-space
-Amount of space between consecutive titles (e.g., the title of the
-book and the title of a piece). Default is@tie{}2mm.
+Distance between the bottom-most music system and the page
+footer. Default: @code{4\mm}.
-@funindex printallheaders
-@item printallheaders
-Setting this to #t will print all headers for each \score in the
-output. Normally only the piece and opus \headers are printed.
+@item head-separation
+@funindex head-separation
-@funindex systemSeparatorMarkup
-@item systemSeparatorMarkup
-This contains a markup object, which will be inserted between
-systems. This is often used for orchestral scores. Unset by default.
+Distance between the top-most music system and the page header.
+Default: @code{4\mm}.
-The markup command @code{\slashSeparator} is provided as a sensible
-default, for example
+@item page-top-space
+@funindex page-top-space
-@lilypond[ragged-right]
-#(set-default-paper-size "a6" 'landscape)
-\book {
- \score {
- \relative { c1 \break c1 }
- }
- \paper {
- systemSeparatorMarkup = \slashSeparator
- }
-}
-@end lilypond
+Distance from the top of the printable area to the center of the
+first staff. This only works for staves that are vertically
+small. Big staves are set with the top of their bounding box
+aligned to the top of the printable area. Default: @code{12\mm}.
-@funindex blank-page-force
-@item blank-page-force
-The penalty for having a blank page in the middle of a
-score. This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score. Default value
-is 10.
+@item paper-height
+@funindex paper-height
-@funindex blank-last-page-force
-@item blank-last-page-force
-The penalty for ending the score on an odd-numbered page.
-Default value is 0.
+The height of the page. Default: the height of the current paper
+size. For details, see @ref{Paper size}.
-@funindex page-spacing-weight
-@item page-spacing-weight
-The relative importance of page (vertical) spacing and line (horizontal)
-spacing. High values will make page spacing more important. Default
-value is 10.
+@item top-margin
+@funindex top-margin
-@funindex auto-first-page-number
-@item auto-first-page-number
-The page breaking algorithm is affected by the first page number being
-odd or even. If this variable is set to #t, 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.
+The margin between header and top of the page. Default:
+@code{5\mm}.
@end table
-@end quotation
@snippets
page given the system to put on it.
+@seealso
+Notation Reference:
+@ref{Vertical spacing between systems}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
+@node Horizontal dimensions
+@unnumberedsubsubsec Horizontal dimensions
+
+@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.}
+
+There are a few variables that determine the horizontal dimensions
+on a page:
+
+@table @code
+
+@item horizontal-shift
+@funindex horizontal-shift
+
+The amount that all systems (including titles and system
+separators) are shifted to the right. Default: @code{0.0}.
+
+@item indent
+@funindex indent
+
+The level of indentation for the first system in a score.
+Default: @code{paper-width} divided by @code{14}, as determined by
+@code{set-default-paper-size} or @code{set-paper-size}.
+
+@item left-margin
+@funindex left-margin
+
+The margin between the left edge of the page and the beginning of
+each system. Default: @code{10\mm}, as determined by
+@code{set-default-paper-size} or @code{set-paper-size}.
+
+@item line-width
+@funindex line-width
+
+The width of music systems. Default: @code{paper-width} minus
+@code{20\mm}, as determined by @code{set-default-paper-size} or
+@code{set-paper-size}.
+
+@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}.
+
+@item short-indent
+@funindex short-indent
+
+The level of indentation for all systems in a score besides the
+first system. Default: @code{0}, as determined by
+@code{set-default-paper-size} or @code{set-paper-size}.
+
+@end table
+
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@knownissues
-The option right-margin is defined but doesn't set the right margin
-yet. The value for the right margin has to be defined adjusting the
-values of @code{left-margin} and @code{line-width}.
+The option @code{right-margin} is defined but doesn't set the
+right margin yet. The value for the right margin has to be
+defined by adjusting the values of @code{left-margin} and
+@code{line-width}.
+
+
+@node Other layout variables
+@unnumberedsubsubsec Other layout variables
+
+These variables can be used to adjust page layout in general.
+
+@table @code
+
+@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}.
+
+@ignore
+
+FIXME: this variable is used, but I don't know what it does. -pm
+@item blank-after-score-page-force
+@funindex blank-after-score-page-force
+
+Default: @code{2}.
+
+@end ignore
+
+@item blank-last-page-force
+@funindex blank-last-page-force
+
+The penalty for ending the score on an odd-numbered page.
+Default: @code{0}.
+
+@item blank-page-force
+@funindex blank-page-force
+
+The penalty for having a blank page in the middle of a
+score. This is not used by @code{ly:optimal-breaking} since it will
+never consider blank pages in the middle of a score. Default:
+@code{5}.
+
+@item first-page-number
+@funindex first-page-number
+
+The value of the page number on the first page. Default:
+@code{#1}.
+
+@item page-breaking-between-system-padding
+@funindex page-breaking-between-system-padding
+
+Tricks the page breaker into thinking that
+@code{between-system-padding} is set to something different than
+it really is. For example, if this variable is set to something
+substantially larger than @code{between-system-padding}, then the
+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.
+
+@item page-limit-inter-system-space
+@funindex page-limit-inter-system-space
+
+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}.
+
+@item page-limit-inter-system-space-factor
+@funindex page-limit-inter-system-space-factor
+
+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
+
+The relative importance of page (vertical) spacing and line
+(horizontal) spacing. High values will make page spacing more
+important. Default: @code{#10}.
+
+@item print-all-headers
+@funindex print-all-headers
+
+If set to true, this will print all headers for each \score in the
+output. Normally only the piece and opus header variables are
+printed. Default: @code{##f}.
+
+@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}.
+
+This should be set to true for pieces that have only two or three
+systems per page, for example orchestral scores.
+
+@item ragged-last
+@funindex ragged-last
+
+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}.
+
+@item ragged-last-bottom
+@funindex ragged-last-bottom
+
+If set to false, systems will spread vertically across the last
+page. Default: @code{##t}.
+
+Pieces that amply fill two pages or more should have this set to
+true.
+
+It also affects the last page of book parts, ie parts of a book created
+with @code{\bookpart} blocks.
+
+@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{##f}.
+
+If the score has only one system, the default value is @code{##t}.
+
+@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.
+
+The markup command @code{\slashSeparator} is provided as a sensible
+default, for example
+
+@lilypond[quote,ragged-right]
+#(set-default-paper-size "a6" 'landscape)
+\book {
+ \score {
+ \relative { c1 \break c1 }
+ }
+ \paper {
+ system-separator-markup = \slashSeparator
+ }
+}
+@end lilypond
+
+@item system-count
+@funindex system-count
+
+The number of systems to be used for a score.
+Default: unset.
+
+@end table
+
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
+@knownissues
The default page header puts the page number and the @code{instrument}
field from the @code{\header} block on a line.
@rinternals{StaffSymbol}) can be used to tune the size for individual
staves. The sizes of individual staves are relative to the global size.
-@example
-
-@end example
@seealso
+Notation Reference:
+@ref{Selecting notation font size}.
-This manual: @ref{Selecting notation font size}.
+Snippets:
+@rlsr{Spacing}.
@knownissues
@seealso
+Notation Reference:
+@ref{Changing context default settings}.
-This manual: @ref{Changing context default settings}.
+Snippets:
+@rlsr{Spacing}.
@node Breaks
* Using an extra voice for breaks::
@end menu
+
@node Line breaking
@subsection Line breaking
>>
@end example
-@predefined
+@c TODO Check this
+A linebreaking configuration can be saved as a @code{.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
+@rlsr{Spacing}.
+
-@code{\break}, and @code{\noBreak}.
+@predefined
@funindex \break
+@code{\break},
@funindex \noBreak
+@code{\noBreak}.
+@endpredefined
-@seealso
-Internals: @rinternals{LineBreakEvent}.
+@seealso
+Internals Reference:
+@rinternals{LineBreakEvent}.
-@c TODO Check this
-A linebreaking configuration can be saved as a @code{.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
+Snippets:
@rlsr{Spacing}.
+
@knownissues
Line breaks can only occur if there is a @q{proper} bar line. A note
@code{optimal-page-breaks}. If you are having trouble with the new page
breakers, you can enable the old one as a workaround.
-@predefined
+@funindex \bookpart
+When a book has many scores and pages, the page breaking problem may be
+difficult to solve, requiring large processing time and memory. To ease
+the page breaking process, @code{\bookpart} blocks are used to divide
+the book into several parts: the page breaking occurs separately on each
+part. Different page breaking functions may also be used in different
+book parts.
+
+@example
+\bookpart @{
+ \header @{
+ subtitle = "Preface"
+ @}
+ \paper @{
+ %% In a part consisting mostly of text,
+ %% ly:minimal-breaking may be prefered
+ #(define page-breaking ly:minimal-breaking)
+ @}
+ \markup @{ @dots{} @}
+ @dots{}
+@}
+\bookpart @{
+ %% In this part, consisting of music, the default optimal
+ %% page breaking function is used.
+ \header @{
+ subtitle = "First movement"
+ @}
+ \score @{ @dots{} @}
+ @dots{}
+@}
+@end example
+
+
+@predefined
@funindex \pageBreak
-@code{\pageBreak}
+@code{\pageBreak},
@funindex \noPageBreak
-@code{\noPageBreak}
+@code{\noPageBreak}.
+@endpredefined
+
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
@node Optimal page breaking
@code{ly:page-turn-breaking}, it has no concept of page turns.
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Optimal page turning
@subsection Optimal page turning
@code{\allowPageTurn}, may also be used at top-level, between scores and
top-level markups.
-@predefined
+@predefined
@funindex \pageTurn
-@code{\pageTurn}
+@code{\pageTurn},
@funindex \noPageTurn
-@code{\noPageTurn}
+@code{\noPageTurn},
@funindex \allowPageTurn
-@code{\allowPageTurn}
+@code{\allowPageTurn}.
+@endpredefined
+
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
@knownissues
There should only be one @code{Page_turn_engraver} in a score. If there is more
than one, they will interfere with each other.
+
@node Minimal page breaking
@subsection Minimal page breaking
@}
@end example
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Explicit breaks
@subsection Explicit breaks
@end lilypond
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Using an extra voice for breaks
@subsection Using an extra voice for breaks
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
+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.
@end lilypond
+@seealso
+Notation Reference:
+@ref{Vertical spacing}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
@node Vertical spacing
@section Vertical spacing
staves inside a system.
@menu
-* Vertical spacing inside a system::
-* Vertical spacing between systems::
-* Explicit staff and system positioning::
-* Two-pass vertical spacing::
-* Vertical collision avoidance::
+* Vertical spacing inside a system::
+* Vertical spacing between systems::
+* Explicit staff and system positioning::
+* Two-pass vertical spacing::
+* Vertical collision avoidance::
@end menu
}
@end lilypond
-@seealso
-
-Internals: Vertical alignment of staves is handled by the
-@rinternals{VerticalAlignment} object. The context parameters
+Vertical alignment of staves is handled by the
+@code{VerticalAlignment} object. The context parameters
specifying the vertical extent are described in connection with
-the @rinternals{Axis_group_engraver}.
+the @code{Axis_group_engraver}.
-Example files: @c @lsr{spacing,page-spacing.ly},
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+@c @lsr{spacing,page-spacing.ly},
@c @lsr{spacing,alignment-vertical-spacing.ly}.
+Internals Reference:
+@rinternals{VerticalAlignment},
+@rinternals{Axis_group_engraver}.
+
@node Vertical spacing between systems
@subsection Vertical spacing between systems
}
@end lilypond
+
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Explicit staff and system positioning
@subsection Explicit staff and system positioning
@code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
list of five different settings:
-@itemize
+@itemize
@item @code{X-offset}
@item @code{Y-offset}
@item @code{alignment-offsets}
To understand how each of these different settings work, we begin
by looking at an example that includes no overrides at all.
-@lilypond[quote,ragged-right]
-\new Score <<
- \new Staff <<
- \new Voice {
- s1 * 6 \break
- s1 * 6 \break
- s1 * 6 \break
- }
- \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
- >>
- \new Staff {
- \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+@c \book { } is required in these examples to ensure the spacing
+@c overrides can be seen between systems. -np
+
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+ \score {
+ <<
+ \new Staff <<
+ \new Voice {
+ s1*5 \break
+ s1*5 \break
+ s1*5 \break
+ }
+ \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+ >>
+ \new Staff {
+ \repeat unfold 15 { d'4 d' d' d' }
+ }
+ >>
}
->>
+}
@end lilypond
This score isolates line- and page-breaking information in a dedicated
the @code{Y-offset} pair in the @code{line-break-system-details}
attribute of the @code{NonMusicalPaperColumn} grob:
-@lilypond[quote,ragged-right]
-\new Score <<
- \new Staff <<
- \new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0))
- s1 * 6 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 40))
- s1 * 6 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 80))
- s1 * 6 \break
- }
- \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
- >>
- \new Staff {
- \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+ \score {
+ <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0))
+ s1*5 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 40))
+ s1*5 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 80))
+ s1*5 \break
+ }
+ \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+ >>
+ \new Staff {
+ \repeat unfold 15 { d'4 d' d' d' }
+ }
+ >>
}
->>
+}
@end lilypond
Note that @code{line-break-system-details} takes an associative list of
within each system manually. We do this using the @code{alignment-offsets}
subproperty of @code{line-break-system-details}.
-@lilypond[quote,ragged-right]
-\new Score <<
- \new Staff <<
- \new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 20)
- (alignment-offsets . (0 -15)))
- s1 * 6 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 60)
- (alignment-offsets . (0 -15)))
- s1 * 6 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 100)
- (alignment-offsets . (0 -15)))
- s1 * 6 \break
- }
- \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
- >>
- \new Staff {
- \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+ \score {
+ <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 20)
+ (alignment-offsets . (0 -15)))
+ s1*5 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 60)
+ (alignment-offsets . (0 -15)))
+ s1*5 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 100)
+ (alignment-offsets . (0 -15)))
+ s1*5 \break
+ }
+ \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+ >>
+ \new Staff {
+ \repeat unfold 15 { d'4 d' d' d' }
+ }
+ >>
}
->>
+}
@end lilypond
Note that here we assign two different values to the
every system and every staff. Finally, note that @code{alignment-offsets}
specifies the vertical positioning of staves but not of staff groups.
-@lilypond[quote,ragged-right]
-\new Score <<
- \new Staff <<
- \new Voice {
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 0)
- (alignment-offsets . (0 -30 -40)))
- s1 * 6 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 60)
- (alignment-offsets . (0 -10 -20)))
- s1 * 6 \break
- \overrideProperty #"Score.NonMusicalPaperColumn"
- #'line-break-system-details #'((Y-offset . 100)
- (alignment-offsets . (0 -10, -40)))
- s1 * 6 \break
- }
- \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
- >>
- \new StaffGroup <<
- \new Staff {
- \repeat unfold 18 { d'4 d'4 d'4 d'4 }
- }
- \new Staff {
- \repeat unfold 18 { e'4 e'4 e'4 e'4 }
- }
- >>
->>
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+ \score {
+ <<
+ \new Staff <<
+ \new Voice {
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 0)
+ (alignment-offsets . (0 -30 -40)))
+ s1*5 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 60)
+ (alignment-offsets . (0 -10 -20)))
+ s1*5 \break
+ \overrideProperty #"Score.NonMusicalPaperColumn"
+ #'line-break-system-details #'((Y-offset . 100)
+ (alignment-offsets . (0 -10 -40)))
+ s1*5 \break
+ }
+ \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+ >>
+ \new StaffGroup <<
+ \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
+ \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
+ >>
+ >>
+ }
+}
@end lilypond
Some points to consider:
@end itemize
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Two-pass vertical spacing
@subsection Two-pass vertical spacing
-Warning: two-pass vertical spacing is deprecated and will be removed in
+@warning{Two-pass vertical spacing is deprecated and will be removed in
a future version of LilyPond. Systems are now stretched automatically
-in a single pass. See @ref{Vertical spacing inside a system}.
+in a single pass. See @ref{Vertical spacing inside a system}.}
In order to automatically stretch systems so that they should fill the
space left on a page, a two-pass technique can be used:
@end example
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Vertical collision avoidance
@subsection Vertical collision avoidance
\once \override TextScript #'outside-staff-priority = #1
c4_"Text"\pp % this time the text will be closer to the staff
r2.
-% by setting outside-staff-priority to a non-number,
+% by setting outside-staff-priority to a non-number,
% we disable the automatic collision avoidance
\once \override TextScript #'outside-staff-priority = ##f
\once \override DynamicLineSpanner #'outside-staff-priority = ##f
c^"This text is placed close to the previous text"
@end lilypond
-TODO: this example doesn't work any more ?
-By default, outside-staff objects are placed without regard to
-their horizontal distance from the previously-positioned grobs. This
+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. Setting @code{outside-staff-horizontal-padding}
+other horizontally. The vertical spacing between staffs 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]
% the markup is too close to the following note
-c2^"Text"
+c4^"Text"
+c4
c''2
% setting outside-staff-horizontal-padding fixes this
R1
\once \override TextScript #'outside-staff-horizontal-padding = #1
-c,,2^"Text"
+c,,4^"Text"
+c4
c''2
@end lilypond
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
@node Horizontal spacing
-@section Horizontal Spacing
+@section Horizontal spacing
@cindex horizontal spacing
@cindex spacing, horizontal
@menu
-* Horizontal spacing overview::
-* New spacing area::
-* Changing horizontal spacing::
-* Line length::
-* Proportional notation::
+* Horizontal spacing overview::
+* New spacing area::
+* Changing horizontal spacing::
+* Line length::
+* Proportional notation::
@end menu
@seealso
+Snippets:
+@rlsr{Spacing}.
-Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
-@rinternals{StaffSpacing}, and @rinternals{SeparationItem}.
+Internals Reference:
+@rinternals{SpacingSpanner},
+@rinternals{NoteSpacing},
+@rinternals{StaffSpacing},
+@rinternals{NonMusicalPaperColumn}.
@knownissues
There is no convenient mechanism to manually override spacing. The
-following work-around may be used to insert extra space into a score.
+following work-around may be used to insert extra space into a score,
+adjusting the padding value as necessary.
@example
- \once \override Score.SeparationItem #'padding = #1
+ \override Score.NonMusicalPaperColumn #'padding = #10
@end example
No work-around exists for decreasing the amount of space.
@subsection New spacing area
New sections with different spacing parameters can be started with
-@code{newSpacingSection}. This is useful when there are
+@code{newSpacingSection}. This is useful when there are
sections with a different notions of long and short notes.
In the following example, the time signature change introduces a new
@lilypond[relative,fragment,verbatim,quote]
\time 2/4
-c4 c8 c
+c4 c8 c
c8 c c4 c16[ c c8] c4
\newSpacingSection
\time 4/16
c16[ c c8]
@end lilypond
-
The @code{\newSpacingSection} command creates a new
-@rinternals{SpacingSpanner} object, and hence new @code{\override}s
+@code{SpacingSpanner} object, and hence new @code{\override}s
may be used in that location.
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{SpacingSpanner}.
+
+
@node Changing horizontal spacing
@subsection Changing horizontal spacing
>>
@end lilypond
-
When @code{strict-note-spacing} is set, notes are spaced without
regard for clefs, bar lines, and grace notes,
@end lilypond
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Line length
@subsection Line length
@end example
+@seealso
+Snippets:
+@rlsr{Spacing}.
+
+
@node Proportional notation
@subsection Proportional notation
for these related settings.
+@seealso
+Notation Reference:
+@ref{New spacing area}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
@node Fitting music onto fewer pages
@section Fitting music onto fewer pages
}
@end lilypond
+
@noindent
-All layout dimensions are displayed in staff spaces, regardless of
-the units specified in the @code{\paper} or @code{\layout} block.
-For example, @code{paper-height} has a value of 59.75 staff
-spaces, using the default staff size of 20 points, which is
-equivalent to 148 millimeters, the height of @code{a6} paper in
-landscape orientation. The pairs (@var{a},@var{b}) are intervals,
-where @var{a} is the lower edge and @var{b} the upper edge of the
-interval.
+All layout dimensions are displayed in staff-spaces, regardless
+of the units specified in the @code{\paper} or @code{\layout} block.
+In the above example, @code{paper-height} has a value of 59.75
+@code{staff-spaces}, and the @code{staff-size} is 20 points (the
+default value). Note that:
+
+@multitable {1 staff-space} {staff-size)/4 * (25.4/72.27) mm}
+
+@item 1 point
+@tab = (25.4/72.27) mm
+
+@item 1 staff-space
+@tab = (@code{staff-size})/4 pts
+@item
+@tab = (@code{staff-size})/4 * (25.4/72.27) mm
+
+@end multitable
+
+@noindent
+In this case, one @code{staff-space} is approximately equal to
+1.757mm. Thus the @code{paper-height} measurement of 59.75
+@code{staff-spaces} is equivalent to 105 millimeters, the height
+of @code{a6} paper in landscape orientation. The pairs
+(@var{a},@var{b}) are intervals, where @var{a} is the lower
+edge and @var{b} the upper edge of the interval.
+
+
+@seealso
+@ref{Setting the staff size}
+Snippets:
+@rlsr{Spacing}.
@node Changing spacing
@end example
@item
-Force the number of systems. For example, if the default layout
-has 11 systems, the following assignment will force a layout with
-10 systems.
+Force the number of systems. This can help in two ways. Just
+setting a value, even the same value as the number of systems
+being typeset by default, will sometimes cause more systems to
+be fitted onto each page, as an estimation step is then bypassed,
+giving a more accurate fit to each page. Also, forcing an actual
+reduction in the number of systems may save a further page. For
+example, if the default layout has 11 systems, the following
+assignment will force a layout with 10 systems.
@example
\paper @{
@seealso
-
Notation Reference:
@ref{Page formatting},
@ref{Changing horizontal spacing}.
+
+Snippets:
+@rlsr{Spacing}.