]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/spacing.itely
Merge branch 'master' of /home/lilydev/git/lily/
[lilypond.git] / Documentation / user / spacing.itely
index 64977b0233a29ca05a2faddfcaf232549e56368d..f7234ac0980f97c476fdfbebf491deffc6ccdebd 100644 (file)
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.64"
 
 @ignore
 GDP TODO list
 
 @ignore
 GDP TODO list
@@ -20,9 +20,6 @@ Negative numbers are allowed:
 > and prints page number -1 on the second page, for example.
 
 
 > 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:
 
 In 5.2.1 the @refbugs (line 495 in spacing.itely on master) it
 states:
 
@@ -52,6 +49,7 @@ http://code.google.com/p/lilypond/issues/detail?id=68
 
 @end ignore
 
 
 @end ignore
 
+
 @node Spacing issues
 @chapter Spacing issues
 
 @node Spacing issues
 @chapter Spacing issues
 
@@ -80,7 +78,7 @@ effect.  In general the commands shown in this chapter can
 be placed in either.
 
 @menu
 be placed in either.
 
 @menu
-* Paper and pages::             
+* Paper and pages::
 * Music layout::
 * Breaks::
 * Vertical spacing::
 * Music layout::
 * Breaks::
 * Vertical spacing::
@@ -96,8 +94,8 @@ This section deals with the boundaries that define the area
 within which music can be printed.
 
 @menu
 within which music can be printed.
 
 @menu
-* Paper size::                  
-* Page formatting::             
+* Paper size::
+* Page formatting::
 @end menu
 
 
 @end menu
 
 
@@ -106,247 +104,175 @@ within which music can be printed.
 
 @cindex paper size
 @cindex page size
 
 @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
 #(set-default-paper-size "a4")
 @end example
+
 @example
 \paper @{
   #(set-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
 
 
 @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
 
 
 @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
+@seealso
 
 
-@cindex page formatting
-@cindex margins
-@cindex header, page
-@cindex footer, page
+Installed Files:
+@file{scm/@/paper@/.scm}.
 
 
-LilyPond will do page layout, set margins, and add headers and
-footers to each page.
+Snippets:
+@rlsr{Spacing}.
 
 
-The default layout responds to the following settings in the
-@code{\paper} block.
 
 
-@funindex \paper
-
-@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
 @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 table
-@end quotation
 
 
 @snippets
 
 
 @snippets
@@ -423,11 +349,258 @@ how much space can be spent on a page, the latter creates the actual
 page given the system to put on it.
 
 
 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
 
 @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.
 
 The default page header puts the page number and the @code{instrument}
 field from the @code{\header} block on a line.
@@ -543,9 +716,14 @@ staves.  The sizes of individual staves are relative to the global size.
 
 @end example
 
 
 @end example
 
+
 @seealso
 
 @seealso
 
-This manual: @ref{Selecting notation font size}.
+Notation Reference:
+@ref{Selecting notation font size}.
+
+Snippets:
+@rlsr{Spacing}.
 
 
 @knownissues
 
 
 @knownissues
@@ -579,7 +757,11 @@ layout.
 
 @seealso
 
 
 @seealso
 
-This manual: @ref{Changing context default settings}.
+Notation Reference:
+@ref{Changing context default settings}.
+
+Snippets:
+@rlsr{Spacing}.
 
 
 @node Breaks
 
 
 @node Breaks
@@ -595,6 +777,7 @@ This manual: @ref{Changing context default settings}.
 * Using an extra voice for breaks::
 @end menu
 
 * Using an extra voice for breaks::
 @end menu
 
+
 @node Line breaking
 @subsection Line breaking
 
 @node Line breaking
 @subsection Line breaking
 
@@ -658,23 +841,31 @@ every 4 measures, and only there:
 >>
 @end example
 
 >>
 @end example
 
+@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}.
+
+
 @predefined
 
 @predefined
 
-@code{\break}, and @code{\noBreak}.
 @funindex \break
 @funindex \break
+@code{\break},
 @funindex \noBreak
 @funindex \noBreak
+@code{\noBreak}.
+
 
 @seealso
 
 
 @seealso
 
-Internals: @rinternals{LineBreakEvent}.
+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}.
 
 @rlsr{Spacing}.
 
+
 @knownissues
 
 Line breaks can only occur if there is a @q{proper} bar line.  A note
 @knownissues
 
 Line breaks can only occur if there is a @q{proper} bar line.  A note
@@ -743,12 +934,51 @@ The old page breaking algorithm is called
 @code{optimal-page-breaks}.  If you are having trouble with the new page
 breakers, you can enable the old one as a workaround.
 
 @code{optimal-page-breaks}.  If you are having trouble with the new page
 breakers, you can enable the old one as a workaround.
 
+@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
 @predefined
 
 @funindex \pageBreak
-@code{\pageBreak}
+@code{\pageBreak},
 @funindex \noPageBreak
 @funindex \noPageBreak
-@code{\noPageBreak}
+@code{\noPageBreak}.
+
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
 
 
 @node Optimal page breaking
 
 
 @node Optimal page breaking
@@ -762,6 +992,12 @@ cramping and stretching, both horizontally and vertically.  Unlike
 @code{ly:page-turn-breaking}, it has no concept of page turns.
 
 
 @code{ly:page-turn-breaking}, it has no concept of page turns.
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Optimal page turning
 @subsection Optimal page turning
 
 @node Optimal page turning
 @subsection Optimal page turning
 
@@ -827,20 +1063,29 @@ The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
 @code{\allowPageTurn}, may also be used at top-level, between scores and
 top-level markups.
 
 @code{\allowPageTurn}, may also be used at top-level, between scores and
 top-level markups.
 
+
 @predefined
 
 @funindex \pageTurn
 @predefined
 
 @funindex \pageTurn
-@code{\pageTurn}
+@code{\pageTurn},
 @funindex \noPageTurn
 @funindex \noPageTurn
-@code{\noPageTurn}
+@code{\noPageTurn},
 @funindex \allowPageTurn
 @funindex \allowPageTurn
-@code{\allowPageTurn}
+@code{\allowPageTurn}.
+
+
+@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.
 
 
 @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
 
 @node Minimal page breaking
 @subsection Minimal page breaking
 
@@ -858,6 +1103,13 @@ too slow or memory demanding, or a lot of texts.  It is enabled using:
 @}
 @end example
 
 @}
 @end example
 
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Explicit breaks
 @subsection Explicit breaks
 
 @node Explicit breaks
 @subsection Explicit breaks
 
@@ -901,6 +1153,12 @@ page breaks at explicit @code{\pageBreak} commands and nowhere else.
 @end lilypond
 
 
 @end lilypond
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Using an extra voice for breaks
 @subsection Using an extra voice for breaks
 
 @node Using an extra voice for breaks
 @subsection Using an extra voice for breaks
 
@@ -919,7 +1177,7 @@ Line- and page-breaking information usually appears within note entry directly.
 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
 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.
 contain the  breaks.  This extra voice
 contains only skips together with @code{\break}, @code{pageBreak} and other
 breaking layout information.
@@ -979,6 +1237,15 @@ This pattern becomes especially helpful when overriding
 @end lilypond
 
 
 @end lilypond
 
 
+@seealso
+
+Notation Reference:
+@ref{Vertical spacing}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Vertical spacing
 @section Vertical spacing
 
 @node Vertical spacing
 @section Vertical spacing
 
@@ -991,11 +1258,11 @@ space between systems, and the amount of space between
 staves inside a system.
 
 @menu
 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 menu
 
 
@@ -1096,16 +1363,24 @@ the second piano staff:
 }
 @end lilypond
 
 }
 @end lilypond
 
+Vertical alignment of staves is handled by the
+@code{VerticalAlignment} object.  The context parameters
+specifying the vertical extent are described in connection with
+the @code{Axis_group_engraver}.
+
+
 @seealso
 
 @seealso
 
-Internals: Vertical alignment of staves is handled by the
-@rinternals{VerticalAlignment} object.  The context parameters
-specifying the vertical extent are described in connection with
-the @rinternals{Axis_group_engraver}.
+Snippets:
+@rlsr{Spacing}.
 
 
-Example files: @c @lsr{spacing,page-spacing.ly},
+@c @lsr{spacing,page-spacing.ly},
 @c @lsr{spacing,alignment-vertical-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
 
 @node Vertical spacing between systems
 @subsection Vertical spacing between systems
@@ -1158,6 +1433,13 @@ the last one.
 }
 @end lilypond
 
 }
 @end lilypond
 
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Explicit staff and system positioning
 @subsection Explicit staff and system positioning
 
 @node Explicit staff and system positioning
 @subsection Explicit staff and system positioning
 
@@ -1175,7 +1457,7 @@ vertical positions on the page.
 @code{NonMusicalPaperColumn #'line-break-system-details} accepts an associative
 list of five different settings:
 
 @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}
 @item @code{X-offset}
 @item @code{Y-offset}
 @item @code{alignment-offsets}
@@ -1221,20 +1503,29 @@ example @code{NonMusicalPaperColumn} overrides with the special
 To understand how each of these different settings work, we begin
 by looking at an example that includes no overrides at all.
 
 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
 @end lilypond
 
 This score isolates line- and page-breaking information in a dedicated
@@ -1248,26 +1539,32 @@ 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:
 
 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
 @end lilypond
 
 Note that @code{line-break-system-details} takes an associative list of
@@ -1280,29 +1577,35 @@ explicitly, we can also set the vertical startpoint of each staff
 within each system manually.  We do this using the @code{alignment-offsets}
 subproperty of @code{line-break-system-details}.
 
 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
 @end lilypond
 
 Note that here we assign two different values to the
@@ -1315,34 +1618,36 @@ additional spacing parameters (including, for example, a corresponding
 every system and every staff.  Finally, note that @code{alignment-offsets}
 specifies the vertical positioning of staves but not of staff groups.
 
 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 lilypond
 
 Some points to consider:
@@ -1363,12 +1668,18 @@ passed to these different settings will avoid this.
 @end itemize
 
 
 @end itemize
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Two-pass vertical spacing
 @subsection Two-pass vertical 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
 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:
 
 In order to automatically stretch systems so that they should fill the
 space left on a page, a two-pass technique can be used:
@@ -1422,6 +1733,12 @@ lilypond <file>.ly
 @end example
 
 
 @end example
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Vertical collision avoidance
 @subsection Vertical collision avoidance
 
 @node Vertical collision avoidance
 @subsection Vertical collision avoidance
 
@@ -1459,7 +1776,7 @@ r2.
 \once \override TextScript #'outside-staff-priority = #1
 c4_"Text"\pp % this time the text will be closer to the staff
 r2.
 \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
 % we disable the automatic collision avoidance
 \once \override TextScript #'outside-staff-priority = ##f
 \once \override DynamicLineSpanner #'outside-staff-priority = ##f
@@ -1499,19 +1816,24 @@ c''2
 @end lilypond
 
 
 @end lilypond
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
 
 @node Horizontal spacing
 
 @node Horizontal spacing
-@section Horizontal Spacing
+@section Horizontal spacing
 
 @cindex horizontal spacing
 @cindex spacing, horizontal
 
 @menu
 
 @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
 
 
 @end menu
 
 
@@ -1605,8 +1927,14 @@ Proportional notation is supported; see @ref{Proportional notation}.
 
 @seealso
 
 
 @seealso
 
-Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
-@rinternals{StaffSpacing}, and @rinternals{SeparationItem}.
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{SpacingSpanner},
+@rinternals{NoteSpacing},
+@rinternals{StaffSpacing},
+@rinternals{SeparationItem}.
 
 
 @knownissues
 
 
 @knownissues
@@ -1624,7 +1952,7 @@ No work-around exists for decreasing the amount of space.
 @subsection New spacing area
 
 New sections with different spacing parameters can be started with
 @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
 sections with a different notions of long and short notes.
 
 In the following example, the time signature change introduces a new
@@ -1632,19 +1960,27 @@ section, and hence the 16ths notes are spaced wider.
 
 @lilypond[relative,fragment,verbatim,quote]
 \time 2/4
 
 @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
 
 c8 c c4 c16[ c c8] c4
 \newSpacingSection
 \time 4/16
 c16[ c c8]
 @end lilypond
 
-
 The @code{\newSpacingSection} command creates a new
 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.
 
 
 may be used in that location.
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{SpacingSpanner}.
+
+
 @node Changing horizontal spacing
 @subsection Changing horizontal spacing
 
 @node Changing horizontal spacing
 @subsection Changing horizontal spacing
 
@@ -1714,7 +2050,6 @@ property can only be changed at the beginning of a score,
 >>
 @end lilypond
 
 >>
 @end lilypond
 
-
 When @code{strict-note-spacing} is set, notes are spaced without
 regard for clefs, bar lines, and grace notes,
 
 When @code{strict-note-spacing} is set, notes are spaced without
 regard for clefs, bar lines, and grace notes,
 
@@ -1724,6 +2059,12 @@ regard for clefs, bar lines, and grace notes,
 @end lilypond
 
 
 @end lilypond
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Line length
 @subsection Line length
 
 @node Line length
 @subsection Line length
 
@@ -1771,6 +2112,12 @@ paragraph, the last line simply takes its natural horizontal length.
 @end example
 
 
 @end example
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Proportional notation
 @subsection Proportional notation
 
 @node Proportional notation
 @subsection Proportional notation
 
@@ -2114,6 +2461,15 @@ to break across systems and pages.  See the respective parts of the manual
 for these related settings.
 
 
 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
 
 @node Fitting music onto fewer pages
 @section Fitting music onto fewer pages
 
@@ -2163,6 +2519,12 @@ where @var{a} is the lower edge and @var{b} the upper edge of the
 interval.
 
 
 interval.
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Changing spacing
 @subsection Changing spacing
 
 @node Changing spacing
 @subsection Changing spacing
 
@@ -2267,3 +2629,6 @@ block so that it applies to the whole score.
 Notation Reference:
 @ref{Page formatting},
 @ref{Changing horizontal spacing}.
 Notation Reference:
 @ref{Page formatting},
 @ref{Changing horizontal spacing}.
+
+Snippets:
+@rlsr{Spacing}.