X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fspacing.itely;h=ecc3217cf9bab0370d9f0b23780bebb61888a715;hb=80ac25965335ba51ace93fe478ce7f7907e4df91;hp=37557fcb2de4e7bcda6514ba7079be49d69f3b68;hpb=f875ef39c544bd3499dae5360e9e24f69933575f;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 37557fcb2d..ecc3217cf9 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.14.0"
+@c \version "2.16.0"
 
 @ignore
 GDP TODO list
@@ -130,7 +130,7 @@ 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}.
+@ref{Custom titles headers and footers}.
 
 Most @code{\paper} variables will only work in a @code{\paper}
 block.  The few that will also work in a @code{\layout} block are
@@ -175,7 +175,7 @@ The Scheme equivalent of the above example is:
 @seealso
 Notation Reference:
 @ref{Paper size and automatic scaling},
-@ref{Custom headers footers and titles},
+@ref{Custom titles headers and footers},
 @ref{The \layout block}.
 
 Installed Files:
@@ -191,74 +191,97 @@ Installed Files:
 @funindex \paper
 
 @menu
-* Setting paper size::
+* Setting the paper size::
 * Automatic scaling to paper size::
 @end menu
 
 
-@node Setting paper size
-@unnumberedsubsubsec Setting paper size
+@node Setting the paper size
+@unnumberedsubsubsec Setting the 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
-scope, and @code{set-paper-size} must be placed in a @code{\paper}
-block:
+@q{A4} is the default value when no explicit paper size is set. However,
+there are two functions that can be used to change it
+@code{set-default-paper-size},
 
 @example
-#(set-default-paper-size "a4")
+#(set-default-paper-size "quarto")
 @end example
 
+which must always be placed at the toplevel scope. and
+@code{set-paper-size},
+
 @example
 \paper @{
-  #(set-paper-size "a4")
+  #(set-paper-size "tabloid")
 @}
 @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}.
+which must always be placed in a @code{\paper} block.
 
-@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
+If the @code{set-default-paper-size} function is used in the toplevel
+scope, it must come before the any @code{\paper} block.
+@code{set-default-paper-size} sets the paper size for all pages,
+whereas @code{set-paper-size} only sets the paper size for 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}.
+When the @code{set-paper-size} function is used, it must be
+placed @emph{before} any other functions used within the same
+@code{\paper} block.  See @ref{Automatic scaling to paper size}.
+
+Paper sizes are defined in @file{scm/paper.scm}, and while it is
+possible to add custom sizes, they will be overwritten on subsequent
+software updates.  The available paper sizes are listed in
+@ref{Predefined paper sizes}.
+
+@c An appendix entry exists for paper sizes but is not auto-generated
 
-@c TODO add a new appendix for paper sizes (auto-generated) -pm
+The following command can be used in the file to add a custom paper size
+which can then be used with @code{set-default-paper-size} or
+@code{set-paper-size} as appropriate,
 
-@warning{The default paper size is @code{a4}.}
+@example
+#(set! paper-alist (cons '("my size" . (cons (* 15 in) (* 3 in))) paper-alist))
+
+\paper @{
+  #(set-paper-size "my size")
+@}
+@end example
 
-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.
+The units @code{in} (inches), @code{cm} (centimeters) and @code{mm}
+(millimeters) can all be used.
 
-@cindex orientation
-@cindex landscape
+@cindex paper size, orientation
+@cindex page, orientation
+@cindex paper size, landscape
 
-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.
+If the symbol @code{'landscape} is added to the paper size function,
+pages will be rotated by 90 degrees, and wider line widths will be set
+accordingly.
 
 @example
 #(set-default-paper-size "a6" 'landscape)
 @end example
 
+Swapping the paper dimensions @emph{without} having the print rotated
+(like when printing to postcard size, or creating graphics for inclusion
+rather than a standalone document) can be achieved by appending
+@samp{landscape} to the name of the paper size itself:
+
+@example
+#(set-default-paper-size "a6landscape")
+@end example
+
+When the paper size ends with an explicit @samp{landscape} or
+@samp{portrait}, the presence of a @code{'landscape} symbol @emph{only}
+affects print orientation, not the paper dimensions used for layout.
+
 @seealso
 Notation Reference:
-@ref{Automatic scaling to paper size}.
+@ref{Automatic scaling to paper size},
+@ref{Predefined paper sizes}.
 
 Installed Files:
 @file{scm/paper.scm}.
@@ -277,7 +300,7 @@ that the automatic scaling is not triggered by setting the
 @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}.
+are described in @ref{Setting the paper size}.
 
 The vertical dimensions affected by automatic scaling are
 @code{top-margin} and @code{bottom-margin} (see
@@ -349,7 +372,7 @@ example orchestral scores.
 
 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.
+set to false.  It also affects the last page of book parts, i.e.
 parts of a book created with @code{\bookpart} blocks.
 
 @end table
@@ -365,11 +388,13 @@ 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.
 
+Explicitly defined paper-sizes will override any user-defined top or
+bottom margin settings.
+
 
 @node Flexible vertical spacing \paper variables
 @subsection Flexible vertical spacing @code{\paper} variables
@@ -465,6 +490,10 @@ collisions.
 
 @end itemize
 
+For multi-page scores with a ragged bottom on the last page, the last
+page uses the same spacing as the preceding page, provided there is
+enough space for that.
+
 Specific methods for modifying alists are discussed in
 @ref{Modifying alists}.  The following example demonstrates the
 two ways these alists can be modified.  The first declaration
@@ -672,6 +701,10 @@ Notation Reference:
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
+@knownissues
+Explicitly defined paper-sizes will override any user-defined left or
+right margin settings.
+
 
 @node \paper variables for two-sided mode
 @unnumberedsubsubsec @code{\paper} variables for two-sided mode
@@ -785,8 +818,6 @@ Snippets:
 @node \paper variables for line breaking
 @unnumberedsubsubsec @code{\paper} variables for line breaking
 
-@c TODO: Mention that ly:optimal-breaking is on by default? -mp
-
 @table @code
 
 @item max-systems-per-page
@@ -832,32 +863,13 @@ Default values not listed here are defined in
 
 @table @code
 
-@item blank-after-score-page-force
-@funindex blank-after-score-page-force
-
-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.
-
-@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.
-
 @item page-breaking
 @funindex page-breaking
 
 The page-breaking algorithm to use.  Choices are
-@code{ly:minimal-breaking}, @code{ly:page-turn-breaking}, and
-@code{ly:optimal-breaking}.
+@code{ly:minimal-breaking}, @code{ly:page-turn-breaking},
+@code{ly:one-line-breaking} and @code{ly:optimal-breaking}
+(the default).
 
 @item page-breaking-system-system-spacing
 @funindex page-breaking-system-system-spacing
@@ -876,12 +888,63 @@ The number of pages to be used for a score, unset by default.
 
 @end table
 
+The following variables are effective only when @code{page-breaking}
+is set to @code{ly:page-turn-breaking}.  Page breaks are then chosen
+to minimize the number of page turns.  Since page turns are required
+on moving from an odd-numbered page to an even-numbered one, a
+layout in which the last page is odd-numbered will usually be
+favoured.  Places where page turns are preferred can be indicated
+manually by inserting @code{\allowPageTurn} or automatically by
+including the @code{Page_turn_engraver} (see @ref{Optimal page turning}).
+
+If there are insufficient choices available for making suitable page
+turns, LilyPond may insert a blank page either within a score, between
+scores (if there are two or more scores), or by ending a score on an
+even-numbered page.  The values of the following three variables may
+be increased to make these actions less likely.
+
+The values are penalties, i.e. the higher the value the less likely
+will be the associated action relative to other choices.
+
+@table @code
+
+@item blank-page-penalty
+@funindex blank-page-penalty
+
+The penalty for having a blank page in the middle of a score.  If
+@code{blank-page-penalty} is large and @code{ly:page-turn-breaking} is
+selected, then LilyPond will be less likely to insert a page in the
+middle of a score.  Instead, it will space out the music further to
+fill the blank page and the following one.  Default: 5.
+
+@item blank-last-page-penalty
+@funindex blank-last-page-penalty
+
+The penalty for ending the score on an even-numbered page.  If
+@code{blank-last-page-penalty} is large and
+@code{ly:page-turn-breaking} is selected, then LilyPond will be less
+likely to produce a score in which the last page is even-numbered.
+Instead, it will adjust the spacing in order to use one page more or
+one page less.  Default: 0.
+
+@item blank-after-score-page-penalty
+@funindex blank-after-score-page-penalty
+
+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-penalty}, so that blank pages after scores are
+inserted in preference to blank pages within a score.  Default: 2.
+
+@end table
+
+
 @seealso
 Notation Reference:
 @ref{Page breaking},
 @ref{Optimal page breaking},
 @ref{Optimal page turning},
-@ref{Minimal page breaking}.
+@ref{Minimal page breaking},
+@ref{One-line page breaking}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
@@ -979,7 +1042,6 @@ sensible default, for example:
 
 @end table
 
-
 @seealso
 Installed Files:
 @file{ly/titling-init.ly}.
@@ -987,9 +1049,7 @@ Installed Files:
 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.
 
@@ -1066,6 +1126,102 @@ Here is an example @code{\layout} block:
 @}
 @end example
 
+Multiple @code{\layout} blocks can be entered as toplevel expressions.
+This can, for example, be useful if different settings are stored in
+separate files and included optionally.  Internally, when
+a @code{\layout} block is evaluated, a copy of the current
+@code{\layout} configuration is made, then any changes defined within
+the block are applied and the result is saved as the new current
+configuration.  From the user's perspective the @code{\layout} blocks
+are combined, but in conflicting situations (when the same property
+is changed in different blocks) the later definitions take precedence.
+
+For example, if this block:
+
+@example
+\layout @{
+  \context @{
+    \Voice
+    \override TextScript #'color = #magenta
+    \override Glissando #'thickness = #1.5
+  @}
+@}
+@end example
+
+is placed after the one from the preceding example the @code{'padding}
+and @code{'color} overrides for @code{TextScript} are combined, but
+the later @code{'thickness} override for @code{Glissando} replaces
+(or hides) the earlier one.
+
+@code{\layout} blocks may be assigned to variables for reuse later,
+but the way this works is slightly but significantly different from
+writing them literally.
+
+If a variable is defined like this:
+
+@example
+layoutVariable = \layout @{
+  \context @{
+    \Voice
+    \override NoteHead #'font-size = #4
+  @}
+@}
+@end example
+
+it will hold the current @code{\layout} configuration with the
+@code{NoteHead #'font-size} override added, but this combination
+is @emph{not} saved as the new current configuration.  Be aware
+that the @q{current configuration} is read when the variable is
+defined and not when it is used, so the content of the variable
+is dependent on its position in the source.
+
+The variable can then be used inside another @code{\layout} block,
+for example:
+
+@example
+\layout @{
+  \layoutVariable
+  \context @{
+    \Voice
+    \override NoteHead #'color = #red
+  @}
+@}
+@end example
+
+A @code{\layout} block containing a variable, as in the example above,
+does @emph{not} copy the current configuration but instead uses the
+content of @code{\layoutVariable} as the base configuration for the
+further additions.  This means that any changes defined between the
+definition and the use of the variable are lost.
+
+If @code{layoutVariable} is defined (or @code{\include}d) immediately
+before being used, its content is just the current configuration plus
+the overrides defined within it.  So in the example above showing the
+use of @code{\layoutVariable} the final @code{\layout} block would
+consist of:
+
+@example
+  TextScript #'padding = #1
+  TextScript #'color = #magenta
+  Glissando #'thickness = #1.5
+  NoteHead #' font-size = #4
+  NoteHead #' color = #red
+@end example
+
+plus the @code{indent} and the @code{StaffGrouper} overrides.
+
+But if the variable had already been defined before the first
+@code{\layout} block the current configuration would now contain
+only
+
+@example
+  NoteHead #' font-size= #4 % (written in the variable definition)
+  NoteHead #' color = #red % (added after the use of the variable)
+@end example
+
+If carefully planned, @code{\layout} variables can be a valuable tool
+to structure the layout design of sources, and also to reset the
+@code{\layout} configuration to a known state.
 
 @seealso
 Notation Reference:
@@ -1168,7 +1324,6 @@ These fonts are available in any sizes.  The context property
 @rinternals{StaffSymbol}) can be used to tune the size for individual
 staves.  The sizes of individual staves are relative to the global size.
 
-
 @seealso
 Notation Reference:
 @ref{Selecting notation font size}.
@@ -1176,9 +1331,7 @@ Notation Reference:
 Snippets:
 @rlsr{Spacing}.
 
-
 @knownissues
-
 @code{layout-set-staff-size} does not change the distance between the
 staff lines.
 
@@ -1192,6 +1345,7 @@ staff lines.
 * Optimal page breaking::
 * Optimal page turning::
 * Minimal page breaking::
+* One-line page breaking::
 * Explicit breaks::
 * Using an extra voice for breaks::
 @end menu
@@ -1236,7 +1390,7 @@ with the music:
 
 @lilypond[quote,ragged-right,verbatim]
 \new Voice \with {
-  \remove Forbid_line_break_engraver
+  \remove "Forbid_line_break_engraver"
 } \relative c'' {
   <<
     { c2. \times 2/3 { c4 c c } c2. | }
@@ -1302,13 +1456,6 @@ every 4 measures, and only there:
 >>
 @end example
 
-@c TODO Check this
-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
-@rlsr{Spacing}.
-
 
 @predefined
 @funindex \break
@@ -1317,7 +1464,6 @@ complicated.  More details are available in
 @code{\noBreak}.
 @endpredefined
 
-
 @seealso
 Notation Reference:
 @ref{\paper variables for line breaking}.
@@ -1402,7 +1548,6 @@ book parts.
 @code{\noPageBreak}.
 @endpredefined
 
-
 @seealso
 Notation Reference:
 @ref{\paper variables for page breaking}.
@@ -1421,7 +1566,6 @@ determining page breaks.  It attempts to find a page breaking that minimizes
 cramping and stretching, both horizontally and vertically.  Unlike
 @code{ly:page-turn-breaking}, it has no concept of page turns.
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -1492,7 +1636,6 @@ 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},
@@ -1502,14 +1645,14 @@ top-level markups.
 @code{\allowPageTurn}.
 @endpredefined
 
-
 @seealso
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
 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.
 
@@ -1531,11 +1674,27 @@ too slow or memory demanding, or a lot of texts.  It is enabled using:
 @}
 @end example
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
 
+@node One-line page breaking
+@subsection One-line page breaking
+
+@funindex ly:one-line-breaking
+
+The @code{ly:one-line-breaking} function is a special-purpose
+page breaking algorithm that puts each score on its own page,
+and on a single line.  This page breaking function does not
+typeset titles or margins; only the score will be displayed.
+
+The page width will be adjusted so that
+the longest score fits on one line.  In particular,
+@code{paper-width}, @code{line-width} and @code{indent}
+variables in the @code{\paper} block will be ignored, although
+@code{left-margin} and @code{right-margin} will
+still be honored.  The height of the page will
+be left unmodified.
 
 @node Explicit breaks
 @subsection Explicit breaks
@@ -1583,7 +1742,6 @@ music = \relative c'' { c8 c c c }
 }
 @end lilypond
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -1670,7 +1828,6 @@ music = \relative c'' { c4 c c c }
 }
 @end lilypond
 
-
 @seealso
 Notation Reference:
 @ref{Vertical spacing}.
@@ -1815,7 +1972,7 @@ labelContext =
 #(define-music-function
      (parser location context)
      (string?)
-   #{ s1*0^\markup { \typewriter $context } #})
+   #{ s1*0^\markup { \typewriter #context } #})
 
 \layout {
   \context { \Dynamics    \alignToZero }
@@ -2031,15 +2188,15 @@ Notation Reference:
 @ref{Flexible vertical spacing \paper variables},
 @ref{Modifying alists}.
 
+Installed Files:
+@file{ly/engraver-init.ly},
+@file{scm/define-grobs.scm}.
+
 Internals Reference:
 @rinternals{Contexts},
 @rinternals{VerticalAxisGroup},
 @rinternals{StaffGrouper}.
 
-Installed Files:
-@file{ly/engraver-init.ly},
-@file{scm/define-grobs.scm}.
-
 
 @node Spacing of ungrouped staves
 @unnumberedsubsubsec Spacing of ungrouped staves
@@ -2241,7 +2398,6 @@ able to stretch much more than usual:
 >>
 @end lilypond
 
-
 @seealso
 Installed Files:
 @file{ly/engraver-init.ly},
@@ -2485,7 +2641,6 @@ to print staves or systems on top of one another.  Reasonable values
 passed to these different settings will avoid this.
 @end itemize
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -2539,7 +2694,7 @@ The vertical padding between an outside-staff object and the
 previously-positioned grobs can be controlled with
 @code{outside-staff-padding}.
 
-@lilypond[quote,ragged-right,relative=2,verbatim]
+@lilypond[quote,ragged-right,relative=2,verbatim,staffsize=18]
 \once \override TextScript #'outside-staff-padding = #0
 a'^"This text is placed very close to the note"
 \once \override TextScript #'outside-staff-padding = #3
@@ -2570,7 +2725,6 @@ c4
 c''2
 @end lilypond
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -2679,8 +2833,10 @@ once with exaggerated corrections:
 
 Proportional notation is supported; see @ref{Proportional notation}.
 
-
 @seealso
+Essay on automated music engraving:
+@ressay{Optical spacing}.
+
 Snippets:
 @rlsr{Spacing}.
 
@@ -2690,15 +2846,11 @@ Internals Reference:
 @rinternals{StaffSpacing},
 @rinternals{NonMusicalPaperColumn}.
 
-Essay on automated music engraving:
-@ressay{Optical spacing}.
-
-
 @knownissues
-
 There is no convenient mechanism to manually override spacing.  The
 following work-around may be used to insert extra space into a score,
 adjusting the padding value as necessary.
+
 @example
  \override Score.NonMusicalPaperColumn #'padding = #10
 @end example
@@ -2729,7 +2881,6 @@ The @code{\newSpacingSection} command creates a new
 @code{SpacingSpanner} object, and hence new @code{\override}s
 may be used in that location.
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -2821,7 +2972,6 @@ regard for clefs, bar lines, and grace notes,
 \new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c32] }
 @end lilypond
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -2875,7 +3025,6 @@ paragraph, the last line simply takes its natural horizontal length.
 @}
 @end example
 
-
 @seealso
 Snippets:
 @rlsr{Spacing}.
@@ -2899,7 +3048,7 @@ which may be used together or alone:
 @item @code{proportionalNotationDuration}
 @item @code{uniform-stretching}
 @item @code{strict-note-spacing}
-@item @code{\remove Separating_line_group_engraver}
+@item @code{\remove "Separating_line_group_engraver"}
 @item @code{\override PaperColumn #'used = ##t}
 @end itemize
 
@@ -3189,7 +3338,7 @@ reduces this space to zero.
 }
 
 \new Staff \with {
-  \remove Separating_line_group_engraver
+  \remove "Separating_line_group_engraver"
 } {
   c'1
   \break
@@ -3254,7 +3403,7 @@ that frequently appear in proportional scores.  These include:
 @item @code{\override Beam #'breakable = ##t}
 @item @code{\override Glissando #'breakable = ##t}
 @item @code{\override TextSpanner #'breakable = ##t}
-@item @code{\remove Forbid_line_break_engraver in the Voice context}
+@item @code{\remove "Forbid_line_break_engraver" in the Voice context}
 @end itemize
 
 These settings space grace notes strictly, extend tuplet brackets to
@@ -3262,7 +3411,6 @@ mark both rhythmic start- and stop-points, and allow spanning elements
 to break across systems and pages.  See the respective parts of the manual
 for these related settings.
 
-
 @seealso
 Notation Reference:
 @ref{New spacing area}.
@@ -3275,7 +3423,7 @@ Snippets:
 @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
+(or third, or fourth@dots{}) page.  This is annoying, especially
 if you look at previous pages and it looks like there is plenty
 of room left on those.
 
@@ -3337,7 +3485,6 @@ 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
 Notation Reference:
 @ref{Setting the staff size}.
@@ -3385,6 +3532,16 @@ assignment will force a layout with 10 systems.
 @}
 @end example
 
+@item
+Force the number of pages.  For example, the following
+assignment will force a layout with 2 pages.
+
+@example
+\paper @{
+  page-count = #2
+@}
+@end example
+
 @item
 Avoid (or reduce) objects that increase the vertical size of a
 system.  For example, volta repeats (or alternate repeats) require
@@ -3447,7 +3604,6 @@ block so that it applies to the whole score.
 
 @end itemize
 
-
 @seealso
 Notation Reference:
 @ref{Page layout},