X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fspacing.itely;h=c4e303010e86d4fbbe976b90a19c2b8ea260739e;hb=5c14a087ca6cbd665fd631452b7b1283ba0387c3;hp=feb46e1246ec4ed4337f5c2cca829e5b5ae71c57;hpb=a38a563f999c2b0c6fe2715e19b14afe77108338;p=lilypond.git

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index feb46e1246..c4e303010e 100644
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.61"
 
 @ignore
 GDP TODO list
@@ -20,9 +20,6 @@ Negative numbers are allowed:
 > 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:
 
@@ -52,6 +49,7 @@ http://code.google.com/p/lilypond/issues/detail?id=68
 
 @end ignore
 
+
 @node Spacing issues
 @chapter Spacing issues
 
@@ -69,14 +67,23 @@ 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.
+
 @menu
-* Paper and pages::             
-* Music layout::                
-* Displaying spacing::          
-* Breaks::                      
-* Vertical spacing::            
-* Horizontal spacing::          
-* Page layout MOVED FROM LM::   
+* Paper and pages::
+* Music layout::
+* Breaks::
+* Vertical spacing::
+* Horizontal spacing::
+* Fitting music onto fewer pages::
 @end menu
 
 
@@ -84,11 +91,11 @@ or stretched.
 @section Paper and pages
 
 This section deals with the boundaries that define the area
-that music can be printed inside.
+within which music can be printed.
 
 @menu
-* Paper size::                  
-* Page formatting::             
+* Paper size::
+* Page formatting::
 @end menu
 
 
@@ -97,243 +104,175 @@ that music can be printed inside.
 
 @cindex paper size
 @cindex page size
-@funindex papersize
 
-To change the paper size, there are two commands,
+Two functions are available for changing the paper size:
+@code{set-default-paper-size} and @code{set-paper-size}.
+@code{set-default-paper-size} must be placed in the toplevel
+scope, and @code{set-paper-size} must be placed in a @code{\paper}
+block:
+
 @example
 #(set-default-paper-size "a4")
+@end example
+
+@example
 \paper @{
   #(set-paper-size "a4")
 @}
 @end example
 
-The first command sets the size of all pages.  The second command sets the
-size
-of the pages that the @code{\paper} block applies to -- if the @code{\paper}
-block is at the top of the file, then it will apply to all pages.  If the
-@code{\paper} block is inside a @code{\book}, then the paper size will only
-apply to that book.
+@noindent
+@code{set-default-paper-size} sets the size of all pages, whereas
+@code{set-paper-size} only sets the size of the pages that the
+@code{\paper} block applies to.  For example, if the @code{\paper}
+block is at the top of the file, then it will apply the paper size
+to all pages.  If the @code{\paper} block is inside a
+@code{\book}, then the paper size will only apply to that book.
+
+Common paper sizes are available, including @code{a4},
+@code{letter}, @code{legal}, and @code{11x17} (also known as
+tabloid).  Many more paper sizes are supported by default.  For
+details, see @file{scm/@/paper@/.scm}, and search for the
+definition of @code{paper-alist}.
+
+@c TODO add a new appendix for paper sizes (auto-generated) -pm
 
-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).
+@warning{The default paper size is @code{a4}.}
 
-Extra sizes may be added by editing the definition for
-@code{paper-alist} in the initialization file @file{scm/paper.scm}.
+Extra sizes may be added by editing the definition of
+@code{paper-alist} in the initialization file
+@file{scm/@/paper@/.scm}, however they will be overridden on a
+subsequent install.
 
 @cindex orientation
 @cindex landscape
 
-If the symbol @code{landscape} is supplied as an argument to
-@code{set-default-paper-size}, the pages will be rotated by 90 degrees,
-and wider line widths will be set correspondingly.
+If the symbol @code{'landscape} is supplied as an argument to
+@code{set-default-paper-size}, pages will be rotated by 90
+degrees, and wider line widths will be set accordingly.
 
 @example
 #(set-default-paper-size "a6" 'landscape)
 @end example
 
-Setting the paper size will adjust a number of @code{\paper} variables
-(such as margins).  To use a particular paper size with altered
-@code{\paper} variables, set the paper size before setting the variables.
+Setting the paper size will adjust a number of @code{\paper}
+variables, such as margins.  To use a particular paper size with
+altered @code{\paper} variables, set the paper size before setting
+the variables.
 
 
-@node Page formatting
-@subsection Page formatting
-
-@cindex page formatting
-@cindex margins
-@cindex header, page
-@cindex footer, page
+@seealso
 
-LilyPond will do page layout, set margins, and add headers and
-footers to each page.
+Installed Files:
+@file{scm/@/paper@/.scm}.
 
-The default layout responds to the following settings in the
-@code{\paper} block.
+Snippets:
+@rlsr{Spacing}.
 
-@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.
+@node Page formatting
+@subsection Page formatting
 
-@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.
+Margins, headers, and footers and other layout variables are
+automatically set according to the paper size.
 
-@funindex print-page-number
-@item print-page-number
-If set to false, page numbers will not be printed.  Default is true.
-
-@funindex paper-width
-@item paper-width
-The width of the page.  The default is taken from the current paper size,
-see @ref{Paper size}. 
+This section lists and describes a number of paper variables that
+may be altered.
 
-@funindex paper-height
-@item paper-height
-The height of the page.  The default is taken from the current paper size,
-see @ref{Paper size}. 
+@menu
+* Vertical dimensions::
+* Horizontal dimensions::
+* Other layout variables::
+@end menu
 
-@funindex top-margin
-@item top-margin
-Margin between header and top of the page.  Default is@tie{}5mm.
 
-@funindex bottom-margin
-@item bottom-margin
-Margin between footer and bottom of the page.  Default is@tie{}6mm.
+@node Vertical dimensions
+@unnumberedsubsubsec Vertical dimensions
 
-@funindex left-margin
-@item left-margin
-Margin between the left side of the page and the beginning of the
-music.  Unset by default, which means that the margins is determined
-based on the @code{paper-width} and @code{line-width} to center the
-score on the paper. 
+These variables are used to set different vertical dimensions on a
+page:
 
-@funindex line-width
-@item line-width
-The length of the systems.  Default is @code{paper-width} minus @tie{}20mm.
+@funindex \paper
 
-@funindex head-separation
-@item head-separation
-Distance between the top-most music system and the page header.  Default
-is@tie{}4mm. 
+@table @code
 
-@funindex foot-separation
-@item foot-separation
-Distance between the bottom-most music system and the page
-footer.  Default is@tie{}4mm.
+@item after-title-space
+@funindex after-title-space
 
-@funindex page-top-space
-@item page-top-space
-Distance from the top of the printable area to the center of the first
-staff.  This only works for staves which are vertically small.  Big staves
-are set with the top of their bounding box aligned to the top of the
-printable area.  Default is@tie{}12mm.
+The amount of space between the title and the first system.
+Default: @code{5\mm}.
 
-@funindex ragged-bottom
-@item ragged-bottom
-If set to true, systems will not be spread vertically across the page.  This
-does not affect the last page.  Default is false.
+@item before-title-space
+@funindex before-title-space
 
-This should be set to true for pieces that have only two or three
-systems per page, for example orchestral scores.
+Amount of space between the last system of the previous piece and the
+title of the next.  Default: @code{10\mm}.
 
-@funindex ragged-last-bottom
-@item ragged-last-bottom
-If set to false, systems will be spread vertically to fill the last
-page.  Default is true.
+@item between-system-padding
+@funindex between-system-padding
 
-Pieces that amply fill two pages or more should have this set to
-true.
+The minimum amount of white space that will always be present
+between the bottom-most symbol of one system, and the top-most of
+the next system.  Default: @code{4\mm}.
 
-@funindex system-count
-@item system-count
-This variable, if set, specifies into how many lines a score should be
-broken.  Unset by default.
+Increasing this will put systems whose bounding boxes almost touch
+farther apart.
 
-@funindex between-system-space
 @item between-system-space
-This dimensions determines the distance between systems.  It is the
-ideal distance between the center of the bottom staff of one system
-and the center of the top staff of the next system.  Default is@tie{}20mm.
+@funindex between-system-space
 
-Increasing this will provide a more even appearance of the page at the
-cost of using more vertical space.
+The distance between systems.  It is the ideal distance between
+the center of the bottom staff of one system and the center of the
+top staff of the next system.  Default: @code{20\mm}.
 
-@funindex between-system-padding
-@item between-system-padding
-This dimension is the minimum amount of white space that will always
-be present between the bottom-most symbol of one system, and the
-top-most of the next system.  Default is@tie{}4mm.
+Increasing this value will provide a more even appearance of the
+page at the cost of using more vertical space.
 
-Increasing this will put systems whose bounding boxes almost touch
-farther apart.
+@item between-title-space
+@funindex between-title-space
 
-@funindex page-breaking-between-system-padding
-@item page-breaking-between-system-padding
-This variable tricks the page breaker into thinking that
-@code{between-system-padding} is set to something different than it
-really is.  For example, if this variable is set to something substantially
-larger than @code{between-system-padding}, then the page-breaker will put
-fewer systems on each page.
+Amount of space between consecutive titles (e.g., the title of the
+book and the title of a piece).  Default: @code{2\mm}.
 
-@funindex horizontal-shift
-@item horizontal-shift
-All systems (including titles and system separators) are shifted by
-this amount to the right.  Page markup, such as headers and footers are
-not affected by this.  The purpose of this variable is to make space
-for instrument names at the left.  Default is@tie{}0.
+@item bottom-margin
+@funindex bottom-margin
 
-@funindex after-title-space
-@item after-title-space
-Amount of space between the title and the first system.  Default is@tie{}5mm.
+The margin between footer and bottom of the page.  Default:
+@code{6\mm}.
 
-@funindex before-title-space
-@item before-title-space
-Amount of space between the last system of the previous piece and the
-title of the next.  Default is@tie{}10mm.
+@item foot-separation
+@funindex foot-separation
 
-@funindex between-title-space
-@item between-title-space
-Amount of space between consecutive titles (e.g., the title of the
-book and the title of a piece).  Default is@tie{}2mm.
+Distance between the bottom-most music system and the page
+footer.  Default: @code{4\mm}.
 
-@funindex printallheaders
-@item printallheaders
-Setting this to #t will print all headers for each \score in the
-output.  Normally only the piece and opus \headers are printed.
+@item head-separation
+@funindex head-separation
 
-@funindex systemSeparatorMarkup
-@item systemSeparatorMarkup
-This contains a markup object, which will be inserted between
-systems.  This is often used for orchestral scores.  Unset by default.
+Distance between the top-most music system and the page header.
+Default: @code{4\mm}.
 
-The markup command @code{\slashSeparator} is provided as a sensible
-default,  for example
+@item page-top-space
+@funindex page-top-space
 
-@lilypond[ragged-right]
-#(set-default-paper-size "a6" 'landscape)
-\book {
-  \score {
-    \relative { c1 \break c1 }
-  }
-  \paper {
-    systemSeparatorMarkup = \slashSeparator
-  }
-}
-@end lilypond
+Distance from the top of the printable area to the center of the
+first staff.  This only works for staves that are vertically
+small.  Big staves are set with the top of their bounding box
+aligned to the top of the printable area.  Default: @code{12\mm}.
 
-@funindex blank-page-force
-@item blank-page-force
-The penalty for having a blank page in the middle of a
-score.  This is not used by @code{ly:optimal-breaking} since it will
-never consider blank pages in the middle of a score.  Default value
-is 10.
+@item paper-height
+@funindex paper-height
 
-@funindex blank-last-page-force
-@item blank-last-page-force
-The penalty for ending the score on an odd-numbered page.
-Default value is 0.
+The height of the page.  Default: the height of the current paper
+size.  For details, see @ref{Paper size}.
 
-@funindex page-spacing-weight
-@item page-spacing-weight
-The relative importance of page (vertical) spacing and line (horizontal)
-spacing.  High values will make page spacing more important.  Default
-value is 10.
+@item top-margin
+@funindex top-margin
 
-@funindex auto-first-page-number
-@item auto-first-page-number
-The page breaking algorithm is affected by the first page number being
-odd or even.  If this variable is set to #t, the page breaking algorithm
-will decide whether to start with an odd or even number.  This will 
-result in the first page number remaining as is or being increased by one.
+The margin between header and top of the page.  Default:
+@code{5\mm}.
 
 @end table
-@end quotation
 
 
 @snippets
@@ -370,7 +309,7 @@ Example:
 @}
 @end example
 
-This second example centers page numbers at the bottom of every page. 
+This second example centers page numbers at the bottom of every page.
 
 @example
 \paper @{
@@ -384,7 +323,7 @@ This second example centers page numbers at the bottom of every page.
   evenFooterMarkup = \markup @{ \fill-line @{
      \bold \fontsize #3 \on-the-fly #print-page-number-check-first
      \fromproperty #'page:page-number-string @} @}
-@} 
+@}
 @end example
 
 You can also define these values in Scheme.  In that case @code{mm},
@@ -410,11 +349,255 @@ how much space can be spent on a page, the latter creates the actual
 page given the system to put on it.
 
 
+@seealso
+
+Notation Reference:
+@ref{Vertical spacing between systems}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
+@node Horizontal dimensions
+@unnumberedsubsubsec Horizontal dimensions
+
+@warning{If @code{paper-width} is manually set, @code{line-width},
+@code{left-margin}, @code{indent}, and @code{short-indent} may
+have to be adjusted as well.}
+
+There are a few variables that determine the horizontal dimensions
+on a page:
+
+@table @code
+
+@item horizontal-shift
+@funindex horizontal-shift
+
+The amount that all systems (including titles and system
+separators) are shifted to the right.  Default: @code{0.0}.
+
+@item indent
+@funindex indent
+
+The level of indentation for the first system in a score.
+Default: @code{paper-width} divided by @code{14}, as determined by
+@code{set-default-paper-size} or @code{set-paper-size}.
+
+@item left-margin
+@funindex left-margin
+
+The margin between the left edge of the page and the beginning of
+each system.  Default: @code{10\mm}, as determined by
+@code{set-default-paper-size} or @code{set-paper-size}.
+
+@item line-width
+@funindex line-width
+
+The width of music systems.  Default: @code{paper-width} minus
+@code{20\mm}, as determined by @code{set-default-paper-size} or
+@code{set-paper-size}.
+
+@item paper-width
+@funindex paper-width
+
+The width of the page.  Default: the width of the current paper
+size.  For details, see @ref{Paper size}.
+
+@item short-indent
+@funindex short-indent
+
+The level of indentation for all systems in a score besides the
+first system.  Default: @code{0}, as determined by
+@code{set-default-paper-size} or @code{set-paper-size}.
+
+@end table
+
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @knownissues
 
-The option right-margin is defined but doesn't set the right margin
-yet.  The value for the right margin has to be defined adjusting the
-values of @code{left-margin} and @code{line-width}.
+The option @code{right-margin} is defined but doesn't set the
+right margin yet.  The value for the right margin has to be
+defined by adjusting the values of @code{left-margin} and
+@code{line-width}.
+
+
+@node Other layout variables
+@unnumberedsubsubsec Other layout variables
+
+These variables can be used to adjust page layout in general.
+
+@table @code
+
+@item auto-first-page-number
+@funindex auto-first-page-number
+
+The page breaking algorithm is affected by the first page number
+being odd or even.  If set to true, the page breaking algorithm
+will decide whether to start with an odd or even number.  This
+will result in the first page number remaining as is or being
+increased by one.  Default: @code{##f}.
+
+@ignore
+
+FIXME: this variable is used, but I don't know what it does. -pm
+@item blank-after-score-page-force
+@funindex blank-after-score-page-force
+
+Default: @code{2}.
+
+@end ignore
+
+@item blank-last-page-force
+@funindex blank-last-page-force
+
+The penalty for ending the score on an odd-numbered page.
+Default: @code{0}.
+
+@item blank-page-force
+@funindex blank-page-force
+
+The penalty for having a blank page in the middle of a
+score.  This is not used by @code{ly:optimal-breaking} since it will
+never consider blank pages in the middle of a score.  Default:
+@code{5}.
+
+@item first-page-number
+@funindex first-page-number
+
+The value of the page number on the first page.  Default:
+@code{#1}.
+
+@item page-breaking-between-system-padding
+@funindex page-breaking-between-system-padding
+
+Tricks the page breaker into thinking that
+@code{between-system-padding} is set to something different than
+it really is.  For example, if this variable is set to something
+substantially larger than @code{between-system-padding}, then the
+page-breaker will put fewer systems on each page.  Default: unset.
+
+@item page-count
+@funindex page-count
+
+The number of pages to be used for a score.  Default: unset.
+
+@item page-limit-inter-system-space
+@funindex page-limit-inter-system-space
+
+If set to true, limits space between systems on a page with a lot
+of space left.  Default: @code{##f}.  For details, see
+@ref{Vertical spacing between systems}.
+
+@item page-limit-inter-system-space-factor
+@funindex page-limit-inter-system-space-factor
+
+The factor used by @code{page-limit-inter-system-space}.  Default:
+@code{1.4}.  For details, see
+@ref{Vertical spacing between systems}.
+
+@item page-spacing-weight
+@funindex page-spacing-weight
+
+The relative importance of page (vertical) spacing and line
+(horizontal) spacing.  High values will make page spacing more
+important.  Default: @code{#10}.
+
+@item print-all-headers
+@funindex print-all-headers
+
+If set to true, this will print all headers for each \score in the
+output.  Normally only the piece and opus header variables are
+printed.  Default: @code{##f}.
+
+@item print-first-page-number
+@funindex print-first-page-number
+
+If set to true, a page number is printed on the first page.
+Default: @code{##f}.
+
+@item print-page-number
+@funindex print-page-number
+
+If set to false, page numbers are not printed.  Default:
+@code{##t}.
+
+@item ragged-bottom
+@funindex ragged-bottom
+
+If set to true, systems will not spread vertically across the
+page.  This does not affect the last page.  Default: @code{##f}.
+
+This should be set to true for pieces that have only two or three
+systems per page, for example orchestral scores.
+
+@item ragged-last
+@funindex ragged-last
+
+If set to true, the last system in the score will not fill the
+line width.  Instead the last system ends at its natural
+horizontal length.  Default: @code{##f}.
+
+@item ragged-last-bottom
+@funindex ragged-last-bottom
+
+If set to false, systems will spread vertically across the last
+page.  Default: @code{##t}.
+
+Pieces that amply fill two pages or more should have this set to
+true.
+
+@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 systemSeparatorMarkup
+@funindex systemSeparatorMarkup
+
+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 {
+    systemSeparatorMarkup = \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.
@@ -428,8 +611,8 @@ add space between the titles and the first system of the score.
 @section Music layout
 
 @menu
-* Setting the staff size::      
-* Score layout::                
+* Setting the staff size::
+* Score layout::
 @end menu
 
 
@@ -440,6 +623,9 @@ add space between the titles and the first system of the score.
 @cindex staff size, setting
 @funindex layout file
 
+The default @strong{staff size} is set to 20 points.
+This may be changed in two ways:
+
 To set the staff size globally for all scores in a file (or
 in a @code{book} block, to be precise), use @code{set-global-staff-size}.
 
@@ -451,7 +637,7 @@ in a @code{book} block, to be precise), use @code{set-global-staff-size}.
 This sets the global default size to 14pt staff height and scales all
 fonts accordingly.
 
-To set the staff size individually for each score, use 
+To set the staff size individually for each score, use
 @example
 \score@{
   ...
@@ -527,9 +713,14 @@ staves.  The sizes of individual staves are relative to the global size.
 
 @end example
 
+
 @seealso
 
-This manual: @ref{Selecting notation font size}.
+Notation Reference:
+@ref{Selecting notation font size}.
+
+Snippets:
+@rlsr{Spacing}.
 
 
 @knownissues
@@ -561,79 +752,84 @@ layout.
 @end example
 
 
-@seealso
-
-This manual: @ref{Changing context default settings}.
-
-
-@node Displaying spacing
-@section Displaying spacing
-
-@funindex annotate-spacing
-@cindex Spacing, display of properties
-
-To graphically display the dimensions of vertical properties that may
-be altered for page formatting, set @code{annotate-spacing} in the
-@code{\paper} block, like this
-
-
-@c need to have \book{} otherwise we get  the separate systems. -hwn
-@lilypond[verbatim]
-#(set-default-paper-size "a6" 'landscape)
-
-\book {
-  \score { { c4 } }
-  \paper { annotate-spacing = ##t }
-}
-@end lilypond
+@seealso
 
+Notation Reference:
+@ref{Changing context default settings}.
 
-@c  TODO: really bad vagueness due to bug in annotate-spacing.  -gp
-@noindent
-Some unit dimensions are measured in staff spaces, while others
-are measured in millimeters.
-The pairs
-(@var{a},@var{b}) are intervals, where @var{a} is the lower edge and
-@var{b} the upper edge of the interval.
+Snippets:
+@rlsr{Spacing}.
 
 
 @node Breaks
 @section Breaks
 
 @menu
-* Line breaking::               
-* Page breaking::               
-* Optimal page breaking::       
-* Optimal page turning::        
-* Minimal page breaking::       
-* Explicit breaks::             
-* Using an extra voice for breaks::  
+* Line breaking::
+* Page breaking::
+* Optimal page breaking::
+* Optimal page turning::
+* Minimal page breaking::
+* Explicit breaks::
+* Using an extra voice for breaks::
 @end menu
 
+
 @node Line breaking
 @subsection Line breaking
 
 @cindex line breaks
 @cindex breaking lines
 
-Line breaks are normally computed automatically.  They are chosen so
-that lines look neither cramped nor loose, and that consecutive lines
-have similar density.
+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.
+
+The most basic settings influencing line spacing are @code{indent}
+and @code{line-width}. They are set in the @code{\layout} block.
+They control the indentation of the first line of music, and the
+lengths of the lines.
+
+If @code{ragged-right} is set to true in the @code{\layout} block,
+then systems end at their natural horizontal length, instead of
+being spread horizontally to fill the whole line. This is useful
+for short fragments, and for checking how tight the natural
+spacing is.
+
+@c TODO Check and add para on default for ragged-right
+
+The option @code{ragged-last} is similar to @code{ragged-right},
+but affects only the last line of the piece.
+
+@example
+\layout @{
+indent = #0
+line-width = #150
+ragged-last = ##t
+@}
+@end example
 
-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.  Line breaks can only occur at places where there are bar
-lines.  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
-""}.  Similarly, @code{\noBreak} forbids a line break at a
-point.
 
 
 @cindex regular line breaks
 @cindex four bar music.
 
 For line breaks at regular intervals use @code{\break} separated by
-skips and repeated with @code{\repeat}:
+skips and repeated with @code{\repeat}.  For example, this would
+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
@@ -642,26 +838,31 @@ skips and repeated with @code{\repeat}:
 >>
 @end example
 
-@noindent
-This makes the following 28 measures (assuming 4/4 time) be broken every
-4 measures, and only there.
+@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
 
-@code{\break}, and @code{\noBreak}.
 @funindex \break
+@code{\break},
 @funindex \noBreak
+@code{\noBreak}.
+
 
 @seealso
 
-Internals: @rinternals{LineBreakEvent}.
+Internals Reference:
+@rinternals{LineBreakEvent}.
 
-A linebreaking configuration can be saved as a @code{.ly} file
-automatically.  This allows vertical alignments to be stretched to
-fit pages in a second formatting run.  This is fairly new and
-complicated.  More details are available in
+Snippets:
 @rlsr{Spacing}.
 
+
 @knownissues
 
 Line breaks can only occur if there is a @q{proper} bar line.  A note
@@ -683,12 +884,12 @@ with the music.
   \remove Forbid_line_break_engraver
 } {
   c4 c2 << c2 {s4 \break } >>  % now the break is allowed
-  c2 c4 
+  c2 c4
 }
 @end lilypond
 
 Similarly, line breaks are normally forbidden when beams cross bar
-lines.  This behavior can be changed by setting 
+lines.  This behavior can be changed by setting
 @code{\override Beam #'breakable = ##t}.
 
 
@@ -705,6 +906,14 @@ a line break.
 The @code{\pageBreak} and @code{\noPageBreak} commands may also be
 inserted at top-level, between scores and top-level markups.
 
+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}.
+
 Page breaks are computed by the @code{page-breaking} function.  LilyPond
 provides three algorithms for computing page breaks,
 @code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
@@ -717,16 +926,24 @@ but the value can be changed in the @code{\paper} block:
 @}
 @end example
 
+@c TODO Check this -td
 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.
 
+
 @predefined
 
 @funindex \pageBreak
-@code{\pageBreak}
+@code{\pageBreak},
 @funindex \noPageBreak
-@code{\noPageBreak}
+@code{\noPageBreak}.
+
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
 
 
 @node Optimal page breaking
@@ -740,6 +957,12 @@ cramping and stretching, both horizontally and vertically.  Unlike
 @code{ly:page-turn-breaking}, it has no concept of page turns.
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Optimal page turning
 @subsection Optimal page turning
 
@@ -805,20 +1028,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.
 
+
 @predefined
 
 @funindex \pageTurn
-@code{\pageTurn}
+@code{\pageTurn},
 @funindex \noPageTurn
-@code{\noPageTurn}
+@code{\noPageTurn},
 @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.
 
+
 @node Minimal page breaking
 @subsection Minimal page breaking
 
@@ -836,6 +1068,13 @@ too slow or memory demanding, or a lot of texts.  It is enabled using:
 @}
 @end example
 
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Explicit breaks
 @subsection Explicit breaks
 
@@ -879,6 +1118,12 @@ page breaks at explicit @code{\pageBreak} commands and nowhere else.
 @end lilypond
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Using an extra voice for breaks
 @subsection Using an extra voice for breaks
 
@@ -897,7 +1142,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
-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.
@@ -957,6 +1202,15 @@ This pattern becomes especially helpful when overriding
 @end lilypond
 
 
+@seealso
+
+Notation Reference:
+@ref{Vertical spacing}.
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Vertical spacing
 @section Vertical spacing
 
@@ -969,11 +1223,11 @@ space between systems, and the amount of space between
 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
 
 
@@ -1074,16 +1328,24 @@ the second piano staff:
 }
 @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
 
-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}.
 
+Internals Reference:
+@rinternals{VerticalAlignment},
+@rinternals{Axis_group_engraver}.
+
 
 @node Vertical spacing between systems
 @subsection Vertical spacing between systems
@@ -1136,6 +1398,13 @@ the last one.
 }
 @end lilypond
 
+
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Explicit staff and system positioning
 @subsection Explicit staff and system positioning
 
@@ -1153,7 +1422,7 @@ vertical positions on the page.
 @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}
@@ -1341,12 +1610,18 @@ passed to these different settings will avoid this.
 @end itemize
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Two-pass vertical spacing
 @subsection Two-pass vertical spacing
 
-Warning: two-pass vertical spacing is deprecated and will be removed in
+@warning{Two-pass vertical spacing is deprecated and will be removed in
 a future version of LilyPond.  Systems are now stretched automatically
-in a single pass.  See @ref{Vertical spacing inside a system}.
+in a single pass.  See @ref{Vertical spacing inside a system}.}
 
 In order to automatically stretch systems so that they should fill the
 space left on a page, a two-pass technique can be used:
@@ -1400,6 +1675,12 @@ lilypond <file>.ly
 @end example
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Vertical collision avoidance
 @subsection Vertical collision avoidance
 
@@ -1437,7 +1718,7 @@ 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
@@ -1477,19 +1758,24 @@ c''2
 @end lilypond
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
 
 @node Horizontal spacing
-@section Horizontal Spacing
+@section Horizontal spacing
 
 @cindex horizontal spacing
 @cindex spacing, horizontal
 
 @menu
-* Horizontal spacing overview::  
-* New spacing area::            
-* Changing horizontal spacing::  
-* Line length::                 
-* Proportional notation::       
+* Horizontal spacing overview::
+* New spacing area::
+* Changing horizontal spacing::
+* Line length::
+* Proportional notation::
 @end menu
 
 
@@ -1583,9 +1869,14 @@ Proportional notation is supported; see @ref{Proportional notation}.
 
 @seealso
 
-Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
-@rinternals{StaffSpacing}, @rinternals{SeparationItem}, and
-@rinternals{SeparatingGroupSpanner}.
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{SpacingSpanner},
+@rinternals{NoteSpacing},
+@rinternals{StaffSpacing},
+@rinternals{SeparationItem}.
 
 
 @knownissues
@@ -1603,7 +1894,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
-@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
@@ -1611,19 +1902,27 @@ section, and hence the 16ths notes are spaced wider.
 
 @lilypond[relative,fragment,verbatim,quote]
 \time 2/4
-c4 c8 c 
+c4 c8 c
 c8 c c4 c16[ c c8] c4
 \newSpacingSection
 \time 4/16
 c16[ c c8]
 @end lilypond
 
-
 The @code{\newSpacingSection} command creates a new
-@rinternals{SpacingSpanner} object, and hence new @code{\override}s
+@code{SpacingSpanner} object, and hence new @code{\override}s
 may be used in that location.
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+Internals Reference:
+@rinternals{SpacingSpanner}.
+
+
 @node Changing horizontal spacing
 @subsection Changing horizontal spacing
 
@@ -1693,7 +1992,6 @@ property can only be changed at the beginning of a score,
 >>
 @end lilypond
 
-
 When @code{strict-note-spacing} is set, notes are spaced without
 regard for clefs, bar lines, and grace notes,
 
@@ -1703,6 +2001,12 @@ regard for clefs, bar lines, and grace notes,
 @end lilypond
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Line length
 @subsection Line length
 
@@ -1750,6 +2054,12 @@ paragraph, the last line simply takes its natural horizontal length.
 @end example
 
 
+@seealso
+
+Snippets:
+@rlsr{Spacing}.
+
+
 @node Proportional notation
 @subsection Proportional notation
 
@@ -2093,175 +2403,84 @@ to break across systems and pages.  See the respective parts of the manual
 for these related settings.
 
 
+@seealso
 
-@node Page layout MOVED FROM LM
-@section Page layout MOVED FROM LM
-
-@menu
-* Introduction to layout::      
-* Global sizes::                
-* Line breaks::                 
-* Page breaks::                 
-* Fitting music onto fewer pages::  
-@end menu
+Notation Reference:
+@ref{New spacing area}.
 
-@node Introduction to layout
-@subsection Introduction to layout
+Snippets:
+@rlsr{Spacing}.
 
-The global paper layout is determined by three factors: 
-the page layout, the line breaks, and the spacing. These all 
-influence each other. The choice of spacing determines how 
-densely each system of music is set. This influences where line 
-breaks are chosen, and thus ultimately, how many pages a piece 
-of music takes.
 
-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 section can
-be placed in either.
+@node Fitting music onto fewer pages
+@section Fitting music onto fewer pages
 
-Much more detail on the options for tweaking the laying out
-of music are contained in @ref{Spacing issues}.
+Sometimes you can end up with one or two staves on a second
+(or third, or fourth...) page.  This is annoying, especially
+if you look at previous pages and it looks like there is plenty
+of room left on those.
 
-@node Global sizes
-@subsection Global sizes
+When investigating layout issues, @code{annotate-spacing} is an
+invaluable tool.  This command prints the values of various layout
+spacing variables; for more details see the following section,
+@ref{Displaying spacing}.
 
-TODO Check all these examples
+@menu
+* Displaying spacing::
+* Changing spacing::
+@end menu
 
-The default @strong{paper size} which LilyPond assumes in laying
-out the music is A4.  This may be changed in two ways:
 
-@example
-#(set-default-paper-size "a6")
+@node Displaying spacing
+@subsection Displaying spacing
 
-\paper @{
-#(set-paper-size "letter")
-@}
-@end example
+@funindex annotate-spacing
+@cindex spacing, display of layout
 
-@noindent
-The first command sets the size of all pages. The second command
-sets the size of the pages to which the \paper block applies -- if
-the \paper block is at the top of the file, then it will apply
-to all pages.  Support for the following paper sizes is available:
-a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid).
-Setting the paper size automatically sets suitable margins and
-line length.
-
-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, e.g.
+To graphically display the dimensions of vertical layout variables
+that may be altered for page formatting, set
+@code{annotate-spacing} in the @code{\paper} block:
 
-@example
+@c need to have \book{} otherwise we get the separate systems. -hwn
+@lilypond[verbatim,quote]
 #(set-default-paper-size "a6" 'landscape)
-@end example
-
-The default @strong{staff size} is set to 20 points.
-This may be changed in two ways:
-
-@example
-#(set-global-staff-size 14)
-
-\paper @{
-#(set-global-staff-size 16)
-@}
-@end example
+\book {
+  \score { { c4 } }
+  \paper { annotate-spacing = ##t }
+}
+@end lilypond
 
 @noindent
-The first command sets the size in all pages. The second command
-sets the size in the pages to which the \paper block applies -– if
-the \paper block is at the top of the file, then it will apply
-to all pages.  All the fonts are automatically scaled to suit
-the new value of the staff size.
-
-@node Line breaks
-@subsection Line breaks
-
-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.
-
-The most basic settings influencing line spacing are @code{indent}
-and @code{line-width}. They are set in the @code{\layout} block.
-They control the indentation of the first line of music, and the
-lengths of the lines.
-
-If @code{ragged-right} is set to true in the @code{\layout} block,
-then systems end at their natural horizontal length, instead of
-being spread horizontally to fill the whole line. This is useful
-for short fragments, and for checking how tight the natural
-spacing is.
-
-The option @code{ragged-last} is similar to @code{ragged-right},
-but affects only the last line of the piece.
-
-@example
-\layout @{
-indent = #0
-line-width = #150
-ragged-last = ##t
-@}
-@end example
+All layout dimensions are displayed in staff spaces, regardless of
+the units specified in the @code{\paper} or @code{\layout} block.
+For example, @code{paper-height} has a value of 59.75 staff
+spaces, using the default staff size of 20 points, which is
+equivalent to 148 millimeters, the height of @code{a6} paper in
+landscape orientation.  The pairs (@var{a},@var{b}) are intervals,
+where @var{a} is the lower edge and @var{b} the upper edge of the
+interval.
 
-@node Page breaks
-@subsection Page breaks
 
-The default page breaking may be overridden by inserting 
-@code{\pageBreak} or @code{\noPageBreak} commands.
-These commands are analogous to the @code{\break} and 
-@code{\noBreak} commands discussed above and force or forbid 
-a page-break at the point where they are inserted.
-Of course, the @code{\pageBreak} command also forces a line break.
-Like @code{\break}, the @code{\pageBreak} command is effective only
-at the end of a @q{complete} bar as defined above.  For more
-details see @ref{Page breaking} and following sections.
-
-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.
+@seealso
 
-For more details see @ref{Vertical spacing}.
+Snippets:
+@rlsr{Spacing}.
 
-@node Fitting music onto fewer pages
-@subsection Fitting music onto fewer pages
 
-Sometimes you can end up with one or two staves on a second
-(or third, or fourth...) page.  This is annoying, especially
-if you look at previous pages and it looks like there is plenty
-of room left on those.
+@node Changing spacing
+@subsection Changing spacing
 
-When investigating layout issues, @code{annotate-spacing} is
-an invaluable tool.  This command prints the values of various
-layout spacing commands; see @ref{Displaying spacing}, for more
-details.  From the output of @code{annotate-spacing}, we can
-see which margins we may wish to alter.
+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}.
 
 Other than margins, there are a few other options to save space:
 
 @itemize
 @item
-You may tell LilyPond to place systems as close together as
-possible (to fit as many systems as possible onto a page), but
-then to space those systems out so that there is no blank
-space at the bottom of the page.
+Force systems to move as close together as possible (to fit as
+many systems as possible onto a page) while being spaced so that
+there is no blank space at the bottom of the page.
 
 @example
 \paper @{
@@ -2273,9 +2492,9 @@ space at the bottom of the page.
 @end example
 
 @item
-You may force the number of systems (i.e., if LilyPond wants
-to typeset some music with 11 systems, you could force it to
-use 10).
+Force the number of systems.  For example, if the default layout
+has 11 systems, the following assignment will force a layout with
+10 systems.
 
 @example
 \paper @{
@@ -2284,27 +2503,25 @@ use 10).
 @end example
 
 @item
-Avoid (or reduce) objects which increase the vertical size of
-a system.  For example, volta repeats (or alternate repeats)
-require extra space.  If these repeats are spread over two
-systems, they will take up more space than one system with
-the volta repeats and another system without.
-
-Another example is moving dynamics which @q{stick out} of
-a system, as in the second bar here:
-
-@lilypond[verbatim,quote,fragment,ragged-right,relative=1]
+Avoid (or reduce) objects that increase the vertical size of a
+system.  For example, volta repeats (or alternate repeats) require
+extra space.  If these repeats are spread over two systems, they
+will take up more space than one system with the volta repeats and
+another system without.  For example, dynamics that @q{stick out} of
+a system can be moved closer to the staff:
+
+@lilypond[verbatim,quote,relative=1]
 e4 c g\f c
 \override DynamicText #'extra-offset = #'( -2.2 . 2.0)
 e4 c g\f c
 @end lilypond
 
 @item
-Alter the horizontal spacing via @code{SpacingSpanner}.  See
-@ref{Changing horizontal spacing}, for more details.  Here's
-an example first showing the default behavior:
+Alter the horizontal spacing via @code{SpacingSpanner}.  For more
+details, see @ref{Changing horizontal spacing}.  The following
+example illustrates the default spacing:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \score {
   \relative c'' {
     g4 e e2 |
@@ -2317,11 +2534,12 @@ an example first showing the default behavior:
 @end lilypond
 
 @noindent
-and now with @code{common-shortest-duration} increased from the
-value of @code{1/4} (a quarter note is the most common in this
-example) to @code{1/2}:
+The next example modifies @code{common-shortest-duration} from a
+value of @code{1/4} to @code{1/2}.  The quarter note is the most
+common and shortest duration in this example, so by making this
+duration longer, a @q{squeezing} effect occurs:
 
-@lilypond[verbatim,quote,ragged-right]
+@lilypond[verbatim,quote]
 \score {
   \relative c'' {
     g4 e e2 |
@@ -2334,21 +2552,25 @@ example) to @code{1/2}:
     \context {
       \Score
       \override SpacingSpanner
-                #'common-shortest-duration = #(ly:make-moment 1 2)
+        #'common-shortest-duration = #(ly:make-moment 1 2)
     }
   }
 }
 @end lilypond
 
 @noindent
-Note that this override cannot be modified dynamically, so it must
-always be placed in a @code{\context@{..@}} block so that it applies
-to the whole score.
-
-TODO Add description of using \context in this way earlier if it is
-not already anywhere  -td
+The @code{common-shortest-duration} property cannot be modified
+dynamically, so it must always be placed in a @code{\context}
+block so that it applies to the whole score.
 
 @end itemize
 
 
+@seealso
+
+Notation Reference:
+@ref{Page formatting},
+@ref{Changing horizontal spacing}.
 
+Snippets:
+@rlsr{Spacing}.