+@node Fitting music onto fewer pages
+@section 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.
+
+When investigating layout issues, @code{annotate-spacing} is
+an invaluable tool. This command prints the values of various
+layout spacing commands; for more details see the following
+section, @ref{Displaying spacing}.
+
+@menu
+* Displaying spacing::
+* Changing spacing::
+@end menu
+
+@node Displaying spacing
+@subsection 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
+
+
+@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.
+
+@node Changing spacing
+@subsection Changing spacing
+
+From the output of @code{annotate-spacing}, we can
+see which margins we may wish to alter.
+
+@c TODO add info about or pointers to margin settings
+
+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.
+
+@example
+\paper @{
+ between-system-padding = #0.1
+ between-system-space = #0.1
+ ragged-last-bottom = ##f
+ ragged-bottom = ##f
+@}
+@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).
+
+@example
+\paper @{
+ system-count = #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]
+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:
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+ \relative c'' {
+ g4 e e2 |
+ f4 d d2 |
+ c4 d e f |
+ g4 g g2 |
+ g4 e e2 |
+ }
+}
+@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}:
+
+@lilypond[verbatim,quote,ragged-right]
+\score {
+ \relative c'' {
+ g4 e e2 |
+ f4 d d2 |
+ c4 d e f |
+ g4 g g2 |
+ g4 e e2 |
+ }
+ \layout {
+ \context {
+ \Score
+ \override SpacingSpanner
+ #'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.
+
+@end itemize
+
+
+