lilypond-book robustness: ensure EOL at the end of @verbatim

[lilypond.git] / Documentation / user / spacing.itely

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 1b81a996f5a7ae5ded4fb197203e6752755d0856..fd7e52140a37ea77a7937519301c77338f48bd81 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -470,6 +470,17 @@ never consider blank pages in the middle of a score.  Default:
 The value of the page number on the first page.  Default:
 @code{#1}.
 
+@item 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.
+
+@item 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 page-breaking-between-system-padding
 @funindex page-breaking-between-system-padding
 
@@ -588,6 +599,13 @@ default,  for example
 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.
+
 @end table
 
 
@@ -1474,10 +1492,10 @@ example @code{NonMusicalPaperColumn} overrides with the special
 \overrideProperty NonMusicalPaperColumn
   #'line-break-system-details #'((X-offset . 20) (Y-offset . 40))
 
-\override NonMusicalPaperColumn
+\overrideProperty NonMusicalPaperColumn
   #'line-break-system-details #'((alignment-offsets . (0 -15)))
 
-\override NonMusicalPaperColumn
+\overrideProperty NonMusicalPaperColumn
   #'line-break-system-details #'((X-offset . 20) (Y-offset . 40)
                                  (alignment-offsets . (0 -15)))
 @end example
@@ -1780,7 +1798,7 @@ By default, outside-staff objects are placed only to avoid
 a horizontal collision with previously-positioned grobs.  This
 can lead to situations in which objects are placed very close to each
 other horizontally.  The vertical spacing between staffs can
-also be set so that outside staff objects are interleaved.  
+also be set so that outside staff objects are interleaved.
 Setting @code{outside-staff-horizontal-padding}
 causes an object to be offset vertically so that such a situation
 doesn't occur.
@@ -1915,15 +1933,16 @@ Internals Reference:
 @rinternals{SpacingSpanner},
 @rinternals{NoteSpacing},
 @rinternals{StaffSpacing},
-@rinternals{SeparationItem}.
+@rinternals{NonMusicalPaperColumn}.
 
 
 @knownissues
 
 There is no convenient mechanism to manually override spacing.  The
-following work-around may be used to insert extra space into a score.
+following work-around may be used to insert extra space into a score,
+adjusting the padding value as necessary.
 @example
- \once \override Score.SeparationItem #'padding = #1
+ \override Score.NonMusicalPaperColumn #'padding = #10
 @end example
 
 No work-around exists for decreasing the amount of space.
@@ -2485,18 +2504,37 @@ that may be altered for page formatting, set
 }
 @end lilypond
 
+
+@noindent
+All layout dimensions are displayed in staff-spaces, regardless
+of the units specified in the @code{\paper} or @code{\layout} block.
+In the above example, @code{paper-height} has a value of 59.75
+@code{staff-spaces}, and the @code{staff-size} is 20 points (the
+default value). Note that:
+
+@multitable {1 staff-space} {staff-size)/4 * (25.4/72.27) mm}
+
+@item 1 point
+@tab = (25.4/72.27) mm
+
+@item 1 staff-space
+@tab = (@code{staff-size})/4 pts
+@item
+@tab = (@code{staff-size})/4 * (25.4/72.27) mm
+
+@end multitable
+
 @noindent
-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.
+In this case, one @code{staff-space} is approximately equal to
+1.757mm. Thus the @code{paper-height} measurement of 59.75
+@code{staff-spaces} is equivalent to 105 millimeters, the height
+of @code{a6} paper in landscape orientation.  The pairs
+(@var{a},@var{b}) are intervals, where @var{a} is the lower
+edge and @var{b} the upper edge of the interval.
 
 
 @seealso
+@ref{Setting the staff size}
 Snippets:
 @rlsr{Spacing}.
 
@@ -2526,9 +2564,14 @@ there is no blank space at the bottom of the page.
 @end example
 
 @item
-Force the number of systems.  For example, if the default layout
-has 11 systems, the following assignment will force a layout with
-10 systems.
+Force the number of systems.  This can help in two ways.  Just
+setting a value, even the same value as the number of systems
+being typeset by default, will sometimes cause more systems to
+be fitted onto each page, as an estimation step is then bypassed,
+giving a more accurate fit to each page.  Also, forcing an actual
+reduction in the number of systems may save a further page. For
+example, if the default layout has 11 systems, the following
+assignment will force a layout with 10 systems.
 
 @example
 \paper @{