X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fspacing.itely;h=19cc1cbdb8f796e72e6f0ee824eaa3cccf992d67;hb=efa7af705ab6beb1f9c4d71ef4897b103f69b23c;hp=27aef2095e341083c7b8e0a001c5c93b5f62bcba;hpb=a396a31d3d8df664dbadef65f0e807759d6b355e;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 27aef2095e..19cc1cbdb8 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.13.39"
+@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,70 +256,123 @@ 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
-Installed Files:
-@file{scm/@/paper@/.scm}.
-
-Snippets:
-@rlsr{Spacing}.
-
-
-@node Page formatting
-@subsection Page formatting
+Notation Reference:
+@ref{Automatic scaling to paper size}.
 
-@funindex \paper
+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}.
 
-Margins, headers, and footers and other layout variables are
-automatically set according to the paper size.
+@seealso
+Notation Reference:
+@ref{Fixed vertical spacing \paper variables},
+@ref{Horizontal spacing \paper variables}.
 
-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.
+Installed Files:
+@file{ly/paper-defaults-init.ly},
+@file{scm/paper.scm}.
 
-This section lists and describes a number of paper variables that
-may be altered.
 
-@menu
-* Fixed vertical dimensions::
-* Flexible vertical dimensions::
-* Horizontal dimensions::
-* Other layout variables::
-@end menu
+@node Fixed vertical spacing \paper variables
+@subsection Fixed vertical spacing @code{\paper} variables
 
+@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}.}
 
-@node Fixed vertical dimensions
-@unnumberedsubsubsec Fixed vertical dimensions
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
 
 @table @code
 @item paper-height
 @funindex paper-height
 
-The height of the page.  Default: the height of the current paper
-size.  For details, see @ref{Paper size}.
+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
 
 The margin between the top of the page and the top of the
-printable area.  Default: @code{5\mm}.
+printable area.  If the paper size is modified, this dimension's
+default value is scaled accordingly.
 
 @item bottom-margin
 @funindex bottom-margin
 
 The margin between the bottom of the printable area and the bottom
-of the page.  Default: @code{6\mm}.
+of the page.  If the paper size is modified, this dimension's
+default value is scaled accordingly.
+
+@item ragged-bottom
+@funindex ragged-bottom
+
+If set to true, systems will not spread vertically down the page.
+This does not affect the last page.  This should be set to true
+for pieces that have only two or three systems per page, for
+example orchestral scores.
+
+@item ragged-last-bottom
+@funindex ragged-last-bottom
+
+If 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
 
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+Snippets:
+@rlsr{Spacing}.
+
+@knownissues
+
+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.
+
 
-@node Flexible vertical dimensions
-@unnumberedsubsubsec Flexible vertical dimensions
+@node Flexible vertical spacing \paper variables
+@subsection Flexible vertical spacing @code{\paper} variables
 
 In most cases, it is preferable for the vertical distances between
 certain items (such as margins, titles, systems, and separate
@@ -231,93 +384,107 @@ of these dimensions.
 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
+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}.
 
+@menu
+* Structure of flexible vertical spacing alists::
+* List of flexible vertical spacing \paper variables::
+@end menu
 
-@subsubheading Structure of spacing alists for @code{\paper} variables
 
-Each of these variables is an alist (association list) containing
-four @emph{keys}:
+@node Structure of flexible vertical spacing alists
+@unnumberedsubsubsec Structure of flexible vertical spacing alists
+
+Each of the flexible vertical spacing @code{\paper} variables is
+an alist (association list) containing four @emph{keys}:
 
 @itemize
-@item @code{padding} -- the minimum required amount of
-unobstructed vertical whitespace between two items, measured in
-staff-spaces.  This can be thought of as the minimum height of an
-unobstructed (invisible) rectangle that extends from the leftmost
-to the rightmost point of the combined items.
 
-@item @code{space} -- the default vertical distance, measured in
+@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{space} that are less than either
-@code{padding} or @code{minimum-distance} are not meaningful,
-since the resulting distance will never be less than either
-@code{padding} or @code{minimum-distance}.
+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 @code{minimum-distance} -- the minimum required vertical
+@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.}
 
-@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}
+@c TODO: explain skylines somewhere and xref to it from here.
+
+@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.
+
+@item
+@code{stretchability} -- a unitless measure of the dimension's
+relative propensity to stretch.  If zero, the distance will not
+stretch (unless collisions would result).  When positive, the
+significance of a particular dimension's @code{stretchability}
 value lies only in its relation to the @code{stretchability}
 values of the other dimensions.  For example, if one dimension has
 twice the @code{stretchability} of another, it will stretch twice
 as easily.  Values should be non-negative and finite.  The value
 @code{+inf.0} triggers a @code{programming_error} and is ignored,
 but @code{1.0e7} can be used for an almost infinitely stretchable
-spring.  If unset, the default value is set to @code{space}.  Note
-that the dimension's propensity to @emph{compress} cannot be
-directly set by the user and is equal to
-(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
+spring.  If unset, the default value is set to
+@code{basic-distance}.  Note that the dimension's propensity to
+@emph{compress} cannot be directly set by the user and is equal to
+(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).
+
 @end itemize
 
 If a page has a ragged bottom, the resulting distance is the
 largest of:
 
 @itemize
-@item @code{space},
-@item @code{minimum-distance}, and
-@item @code{padding} plus the smallest distance necessary to
-eliminate collisions.
+
+@item
+@code{basic-distance},
+
+@item
+@code{minimum-distance}, and
+
+@item
+@code{padding} plus the smallest distance necessary to eliminate
+collisions.
+
 @end itemize
 
 Specific methods for modifying alists are discussed in
-@ref{Modifying alists}.  The flexible vertical @code{\paper}
-dimensions variables can only be set within 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 complete re-defines the variable:
+@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 @{
-  system-system-spacing #'space = #8
-
+  system-system-spacing #'basic-distance = #8
   score-system-spacing =
-    #'((padding . 1)
-       (space . 12)
+    #'((basic-distance . 12)
        (minimum-distance . 6)
+       (padding . 1)
        (stretchability . 12))
 @}
 @end example
 
-The initialized default settings for these variables are defined
-in @file{ly/paper-defaults-init.ly}.
-
 
-@subsubheading Flexible vertical dimension @code{\paper} variables
+@node List of flexible vertical spacing \paper variables
+@unnumberedsubsubsec List of flexible vertical spacing @code{\paper} variables
 
 The names of these variables follow the format
 @code{@var{upper}-@var{lower}-spacing}, where @code{@var{upper}}
@@ -327,7 +494,12 @@ 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}).
+@ref{File structure}).  All distances are measured in
+staff-spaces.
+
+Default settings are defined in @file{ly/paper-defaults-init.ly}.
+
+@c TODO: Where do headers/footers fit in? -mp
 
 @table @code
 @item markup-system-spacing
@@ -381,288 +553,311 @@ of the top margin) to the first (title or top-level) markup on a
 page, when there is no system between the two.
 @end table
 
+@seealso
+Notation Reference:
+@ref{Flexible vertical spacing within systems}.
 
-@snippets
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
 
-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.ly} and @file{ly/titling-init.ly}.
+Snippets:
+@rlsr{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.
 
-You can define @code{\paper} block values in Scheme.  In that case
-@code{mm}, @code{in}, @code{pt}, and @code{cm} are variables
-defined in @file{paper-defaults.ly} with values in millimeters.
-That is why the value @w{@code{2 cm}} must be multiplied in the
-example:
+@node Horizontal spacing \paper variables
+@subsection Horizontal spacing @code{\paper} variables
 
-@example
-\paper @{
- #(define bottom-margin (* 2 cm))
-@}
-@end example
+@warning{Some @code{@bs{}paper} dimensions are automatically
+scaled to the paper size, which may lead to unexpected behavior.
+See @ref{Automatic scaling to paper size}.}
 
+@menu
+* \paper variables for widths and margins::
+* \paper variables for two-sided mode::
+* \paper variables for shifts and indents::
+@end menu
 
-Example:
 
-@example
-\paper @{
-  paper-width = 2\cm
-  top-margin = 3\cm
-  bottom-margin = 3\cm
-  ragged-last-bottom = ##t
-@}
-@end example
+@node \paper variables for widths and margins
+@unnumberedsubsubsec @code{\paper} variables for widths and margins
 
-This second example centers page numbers at the bottom of every page.
+Default values (before scaling) that are not listed here 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
+@table @code
 
-@seealso
-Notation Reference:
-@ref{Flexible vertical spacing within systems}.
+@item paper-width
+@funindex paper-width
 
-Snippets:
-@rlsr{Spacing}.
+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
 
-@node Horizontal dimensions
-@unnumberedsubsubsec Horizontal dimensions
+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
 
-There are a few variables that determine the horizontal dimensions
-on a page:
+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}.
 
-@table @code
+@item right-margin
+@funindex right-margin
 
-@item binding-offset
-@funindex binding-offset
+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}.
 
-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}.
+@item check-consistency
+@funindex check-consistency
 
-@item horizontal-shift
-@funindex horizontal-shift
+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.
 
-The amount that all systems (including titles and system
-separators) are shifted to the right.  Default: @code{0.0}.
+@item ragged-right
+@funindex ragged-right
 
-@item indent
-@funindex indent
+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.
 
-The level of indentation for the first system in a score.
-Default: @code{15\mm}.
+@item ragged-last
+@funindex ragged-last
 
-@item inner-margin
-@funindex inner-margin
+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.
 
-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}.
+@end table
 
-@item left-margin
-@funindex left-margin
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
 
-The margin between the left edge of the page and the beginning of
-each system.  Default: @code{10\mm}.
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
 
-@item line-width
-@funindex line-width
 
-The width of music systems.  Default: @code{paper-width} minus
-@code{left-margin} and @code{right-margin}.
+@node \paper variables for two-sided mode
+@unnumberedsubsubsec @code{\paper} variables for two-sided mode
+
+Default values (before scaling) are defined in
+@file{ly/paper-defaults-init.ly}.
+
+@table @code
+
+@item two-sided
+@funindex two-sided
+
+@cindex gutter
+@cindex binding gutter
+
+If set to true, use @code{inner-margin}, @code{outer-margin} and
+@code{binding-offset} to determine margins depending on whether
+the page number is odd or even.  This overrides @code{left-margin}
+and @code{right-margin}.
+
+@item inner-margin
+@funindex inner-margin
+
+The margin all pages have at the inner side if they are part of a
+book.  If the paper size is modified, this dimension's default
+value is scaled accordingly.  Works only with @code{two-sided} set
+to true.
 
 @item outer-margin
 @funindex outer-margin
 
-The margin all pages have at the outer side if they are part
-of a book.  Works only with @code{two-sided} set to true.
-Default: @code{20\mm}.
+The margin all pages have at the outer side if they are part of a
+book.  If the paper size is modified, this dimension's default
+value is scaled accordingly.  Works only with @code{two-sided} set
+to true.
 
-@item paper-width
-@funindex paper-width
+@item binding-offset
+@funindex binding-offset
 
-The width of the page.  Default: the width of the current paper
-size.  For details, see @ref{Paper size}.
+The amount @code{inner-margin} is increased to make sure nothing
+will be hidden by the binding.  If the paper size is modified,
+this dimension's default value is scaled accordingly.  Works only
+with @code{two-sided} set to true.
+
+@end table
+
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
 
-@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}.
+@node \paper variables for shifts and indents
+@unnumberedsubsubsec @code{\paper} variables for shifts and indents
+
+Default values (before scaling) that are not listed here are
+defined in @file{ly/paper-defaults-init.ly}.
+
+@table @code
+
+@item horizontal-shift
+@funindex horizontal-shift
+
+@c This default value is buried in the middle of page.scm.  -mp
+
+The amount that all systems (including titles and system
+separators) are shifted to the right.  Default: @code{0.0\mm}.
+
+@item indent
+@funindex indent
+
+The level of indentation for the first system in a score.  If the
+paper size is modified, this dimension's default value is scaled
+accordingly.  This variable can also be set in a @code{\layout}
+block.
 
 @item short-indent
 @funindex short-indent
 
 The level of indentation for all systems in a score besides the
-first system.  Default: @code{0}.
+first system.  If the paper size is modified, this dimension's
+default value is scaled accordingly.  This variable can also be
+set in a @code{\layout} block.
 
 @end table
 
-If some values are not set, defaults will be taken.  Their exact
-value is adjusted, depending on the paper size specified.  Currently,
-the following values are affected by this scaling:
+@seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
 
-@itemize
-@item @var{left-margin}
-@item @var{right-margin}
-@item @var{top-margin}
-@item @var{bottom-margin}
-@item @var{head-separation}
-@item @var{foot-separation}
-@item @var{indent}
-@item @var{short-indent}
-@end itemize
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
 
-The settings for @code{line-width}, @code{left-margin},
-@code{right-margin} and @code{paper-width} depend on
-each other, but they do not have to be specified
-completely.
+Snippets:
+@rlsr{Spacing}.
 
-@example
-\paper @{
-  left-margin = 30\mm
-@}
-@end example
 
-In this example, only @code{left-margin} is set.  The value for
-@code{right-margin} will remain default, @code{line-width} is
-calculated automatically.
+@node Other \paper variables
+@subsection Other @code{\paper} variables
 
-@example
-\paper @{
-  line-width = 150\mm
-@}
-@end example
+@menu
+* \paper variables for line breaking::
+* \paper variables for page breaking::
+* \paper variables for page numbering::
+* Miscellaneous \paper variables::
+@end menu
 
-Here @code{left-margin} and @code{right-margin} will be set
-to the same value.  Therefore, @code{line-width} is subtracted
-from @code{paper-width} and divided by two.  That means systems
-are centered on the page, if only @code{line-width} is
-specified.
 
-Some checks occur to ensure the values are set correctly.
-If the values do not match or systems would run off the page,
-a warning is printed and default values are set.
+@node \paper variables for line breaking
+@unnumberedsubsubsec @code{\paper} variables for line breaking
 
-@example
-\paper @{
-  paper-width = 210\mm
-  left-margin = 20\mm
-  right-margin = 30\mm
-  line-width = 100\mm
-@}
-@end example
+@c TODO: Mention that ly:optimal-breaking is on by default? -mp
 
-These checks can be avoided by setting @code{check-consistency}
-to false.
+@table @code
 
-@example
-\paper @{
-  paper-width = 210\mm
-  left-margin = 20\mm
-  line-width = 200\mm
-  check-consistency = ##f
-@}
-@end example
+@item max-systems-per-page
+@funindex max-systems-per-page
 
-@warning{If @code{paper-width} is manually set, @code{line-width},
-@code{left-margin}, @code{indent}, and @code{short-indent} may
-have to be adjusted as well.}
+The maximum number of systems that will be placed on a page.  This
+is currently supported only by the @code{ly:optimal-breaking} algorithm.
+Default: unset.
 
-@seealso
-Snippets:
-@rlsr{Spacing}.
+@item min-systems-per-page
+@funindex min-systems-per-page
 
+The minimum number of systems that will be placed on a page.  This
+may cause pages to be overfilled if it is made too large.  This is
+currently supported only by the @code{ly:optimal-breaking} algorithm.
+Default: unset.
+
+@item systems-per-page
+@funindex systems-per-page
+
+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.
 
-@node Other layout variables
-@unnumberedsubsubsec Other layout variables
+@end table
 
-These variables can be used to adjust page layout in general.
+@seealso
+Notation Reference:
+@ref{Line breaking}.
 
-@table @code
 
-@item auto-first-page-number
-@funindex auto-first-page-number
+@node \paper variables for page breaking
+@unnumberedsubsubsec @code{\paper} variables for page breaking
 
-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}.
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
 
-@ignore
+@table @code
 
-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
 
-Default: @code{2}.
-
-@end ignore
+The penalty for having a blank page after the end of one score and
+before the next.  By default, this is smaller than
+@code{blank-page-force}, so that we prefer blank pages after
+scores to blank pages within a score.
 
 @item blank-last-page-force
 @funindex blank-last-page-force
 
 The penalty for ending the score on an odd-numbered page.
-Default: @code{0}.
 
 @item blank-page-force
 @funindex blank-page-force
 
 The penalty for having a blank page in the middle of a
 score.  This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score.  Default:
-@code{5}.
-
-@item check-consistency
-@funindex check-consistency
-
-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
-
-The value of the page number on the first page.  Default:
-@code{#1}.
-
-@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.
+never consider blank pages in the middle of a score.
 
-@item min-systems-per-page
-@funindex min-systems-per-page
+@item page-breaking
+@funindex page-breaking
 
-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.
+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
@@ -677,120 +872,115 @@ 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-spacing-weight
-@funindex page-spacing-weight
+@end table
 
-The relative importance of page (vertical) spacing and line
-(horizontal) spacing.  High values will make page spacing more
-important.  Default: @code{#10}.
+@seealso
+Notation Reference:
+@ref{Page breaking},
+@ref{Optimal page breaking},
+@ref{Optimal page turning},
+@ref{Minimal page breaking}.
 
-@item print-all-headers
-@funindex print-all-headers
+Installed Files:
+@file{ly/paper-defaults-init.ly}.
+
+
+@node \paper variables for page numbering
+@unnumberedsubsubsec @code{\paper} variables for page numbering
+
+Default values not listed here are defined in
+@file{ly/paper-defaults-init.ly}
+
+@table @code
 
-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 false, page numbers are not printed.
 
-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.
+@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
-
-The number of systems to be used for a score.
-Default: unset.
-
-@item systems-per-page
-@funindex systems-per-page
-
-The number of systems that should be placed on each page.
-This is currently supported only by the @code{ly:optimal-breaking} algorithm.
-Default: unset.
-
-@item two-sided
-@funindex two-sided
-
-@cindex gutter
-@cindex binding gutter
-
-If set to true, use @code{inner-margin}, @code{outer-margin} and
-@code{binding-offset} to determine margins depending on whether
-the page number is odd or even.  This overrides @code{left-margin}
-and @code{right-margin}.  Default: @code{##f}.
-
 @end table
 
 
 @seealso
+Installed Files:
+@file{ly/titling-init.ly}.
+
 Snippets:
 @rlsr{Spacing}.
 
@@ -800,20 +990,88 @@ Snippets:
 The default page header puts the page number and the @code{instrument}
 field from the @code{\header} block on a line.
 
-The titles (from the @code{\header@{@}} section) are treated as a
-system, so @code{ragged-bottom} and @code{ragged-last-bottom} will
-add space between the titles and the first system of the score.
 
+@node Score layout
+@section Score layout
 
-@node Music layout
-@section Music layout
+This section discusses score layout options for the @code{\layout}
+block.
 
 @menu
+* The \layout block::
 * Setting the staff size::
-* Score layout::
 @end menu
 
 
+@node The \layout block
+@subsection The @code{\layout} block
+
+@funindex \layout
+
+While the @code{\paper} block contains settings that relate to the
+page formatting of the whole document, the @code{\layout} block
+contains settings for score-specific layout.  To set score layout
+options globally, enter them in a toplevel @code{\layout} block.
+To set layout options for an individual score, enter them in a
+@code{\layout} block inside the @code{\score} block, after the
+music.  Settings that can appear in a @code{\layout} block
+include:
+
+@itemize
+@item the @code{layout-set-staff-size} scheme function,
+@item context modifications in @code{\context} blocks, and
+@item @code{\paper} variables that affect score layout.
+@end itemize
+
+The @code{layout-set-staff-size} function is discussed in the next
+section, @ref{Setting the staff size}.  Context modifications are
+discussed in a separate chapter; see
+@ref{Modifying context plug-ins} and
+@ref{Changing context default settings}.  The @code{\paper}
+variables that can appear in a @code{\layout} block are:
+
+@itemize
+
+@item
+@code{line-width}, @code{ragged-right} and @code{ragged-last}
+(see @ref{\paper variables for widths and margins})
+
+@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})
+
+@end itemize
+
+Here is an example @code{\layout} block:
+
+@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
+
+
+@seealso
+Notation Reference:
+@ref{Changing context default settings}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Setting the staff size
 @subsection Setting the staff size
 
@@ -838,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
@@ -922,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
 
@@ -975,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.
@@ -1006,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
 
@@ -1023,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
@@ -1047,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,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
@@ -1101,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,
@@ -1112,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
 
@@ -1134,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{}
@@ -1160,6 +1401,9 @@ book parts.
 
 
 @seealso
+Notation Reference:
+@ref{\paper variables for page breaking}.
+
 Snippets:
 @rlsr{Spacing}.
 
@@ -1280,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
 
@@ -1313,17 +1557,19 @@ page breaks at explicit @code{\pageBreak} commands and nowhere else.
   ragged-bottom = ##t
 }
 
+music = \relative c'' { c8 c c c }
+
 \score {
   \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 }
-    }
+    \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
@@ -1346,11 +1592,12 @@ Snippets:
 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 @{ c'4 c'4 c'4 c'4 @}
-    \break
-    \repeat unfold 3 @{ c'4 c'4 c'4 c'4 @}
+    \repeat unfold 2 @{ \music @} \break
+    \repeat unfold 3 @{ \music @}
   @}
 @}
 @end example
@@ -1364,6 +1611,8 @@ 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 {
@@ -1373,10 +1622,10 @@ breaking layout information.
       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 }
+      \repeat unfold 2 { \music }
+      \repeat unfold 3 { \music }
+      \repeat unfold 6 { \music }
+      \repeat unfold 5 { \music }
     }
   >>
 }
@@ -1387,6 +1636,8 @@ This pattern becomes especially helpful when overriding
 @code{NonMusicalPaperColumnGrob}, as explained in @ref{Vertical spacing}.
 
 @lilypond[quote,verbatim]
+music = \relative c'' { c4 c c c }
+
 \score {
   \new Staff <<
     \new Voice {
@@ -1407,10 +1658,10 @@ This pattern becomes especially helpful when overriding
       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 }
+      \repeat unfold 2 { \music }
+      \repeat unfold 3 { \music }
+      \repeat unfold 6 { \music }
+      \repeat unfold 5 { \music }
     }
   >>
 }
@@ -1455,11 +1706,18 @@ 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
+
+@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.).
+
+@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
@@ -1475,7 +1733,7 @@ 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 dimensions}.
+@ref{Flexible vertical spacing \paper variables}.
 
 @menu
 * Within-system spacing properties::
@@ -1525,7 +1783,7 @@ In the following image, horizontal lines indicate the positions
 of these reference points:
 
 @lilypond[quote,noragged-right,line-width=110\mm]
-#(define zero-space '((padding . -inf.0) (space . 0)))
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
 
 alignToZero = \with {
   \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
@@ -1608,11 +1866,12 @@ labelContext =
 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 dimensions}.
-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.
+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
@@ -1620,14 +1879,14 @@ individually, and the second completely re-defines the property:
 
 @example
 \new Staff \with @{
-  \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+  \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
 @} @{ @dots{} @}
 
 \new Staff \with @{
   \override VerticalAxisGroup #'staff-staff-spacing =
-    #'((padding . 1)
-       (space . 10)
+    #'((basic-distance . 10)
        (minimum-distance . 9)
+       (padding . 1)
        (stretchability . 10))
 @} @{ @dots{} @}
 @end example
@@ -1639,7 +1898,7 @@ To change any spacing settings globally, put them in the
 \layout @{
   \context @{
     \Staff
-    \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+    \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
   @}
 @}
 @end example
@@ -1740,7 +1999,7 @@ in the staff-group that have it set.  Also see
 @end table
 
 @seealso
-Installed files:
+Installed Files:
 @file{ly/engraver-init.ly},
 @file{scm/define-grobs.scm}.
 
@@ -1781,30 +2040,30 @@ property can affect the spacing of ungrouped staves:
   \context {
     \Staff
     \override VerticalAxisGroup #'staff-staff-spacing =
-      #'((padding . 1)
-         (space . 8)
-         (minimum-distance . 7))
+      #'((basic-distance . 8)
+         (minimum-distance . 7)
+         (padding . 1))
   }
 }
 
 \new StaffGroup <<
-  % The very low note here needs more room than 'space can
-  % provide, so the distance between this staff and the next is
-  % determined by 'padding.
+  % 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, 'space provides enough room, and there is no need to
-  % compress the space (towards 'minimum-distance) to make room
-  % for anything else on the page, so the distance between this
-  % staff and the next is determined by 'space.
+  % 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 'space is 0.
+  % collide.  The lowest acceptable value for 'basic-distance is 0.
   \new Staff \with {
     \override VerticalAxisGroup #'staff-staff-spacing =
-      #'((padding . -10)
-         (space . 3.5))
+      #'((basic-distance . 3.5)
+         (padding . -10))
   } { \clef bass g2 r | }
   \new Staff { \clef bass g2 r | }
 >>
@@ -1859,13 +2118,13 @@ The following example shows how properties of the
   \context {
     \Score
     \override StaffGrouper #'staff-staff-spacing #'padding = #0
-    \override StaffGrouper #'staff-staff-spacing #'space = #1
+    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
   }
 }
 
 <<
   \new PianoStaff \with {
-    \override StaffGrouper #'staffgroup-staff-spacing #'space = #20
+    \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
   } <<
     \new Staff { c'1 }
     \new Staff { c'1 }
@@ -1932,7 +2191,7 @@ able to stretch much more than usual:
 \new StaffGroup
 <<
   \new Staff \with {
-    \override VerticalAxisGroup #'staff-staff-spacing = #'((space . 30))
+    \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
   } { c'1 }
   \new Lyrics \with {
     \override VerticalAxisGroup #'staff-affinity = #UP
@@ -1967,19 +2226,18 @@ Internals Reference:
 @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}
@@ -2012,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
 
@@ -2028,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 {
@@ -2061,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 {
@@ -2099,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 {
@@ -2140,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 {
@@ -3053,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:
 
@@ -3065,7 +3325,7 @@ there is no blank space at the bottom of the page.
 
 @example
 \paper @{
-  system-system-spacing = #'((padding . 0) (space . 0.1))
+  system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
   ragged-last-bottom = ##f
   ragged-bottom = ##f
 @}
@@ -3152,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: