Doc: elaborate the placement of \paper blocks (2902)

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

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index ad892f96ebf42648c7b292ed31d58e99c032949f..6ca227e5f8bdb7c3c1e84d8830dfe015b914bfae 100644 (file)
--- a/Documentation/notation/spacing.itely
+++ b/Documentation/notation/spacing.itely
@@ -70,8 +70,8 @@ or stretched.
 
 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
+@code{\paper} block contains page layout settings that are expected
+to be the same for all scores in a book or bookpart, 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
@@ -106,9 +106,36 @@ block.
 @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.
+@code{\paper} blocks may be placed in three different places to form
+a descending hierarchy of @code{\paper} blocks:
+
+@itemize
+
+@item
+At the top of the input file, before all @code{\book},
+@code{\bookpart}, and @code{\score} blocks.
+
+@item
+Within a @code{\book} block but outside all the @code{\bookpart} and
+@code{\score} blocks within that book.
+
+@item
+Within a @code{\bookpart} block but outside all @code{\score} blocks
+within that bookpart.
+
+@end itemize
+
+A @code{\paper} block cannot be placed within a @code{\score} block.
+
+The values of the fields filter down this hierarchy, with the values
+set higher in the hierarchy persisting unless they are over-ridden
+by a value set lower in the hierarchy.
+
+Several @code{\paper} blocks can appear at each of the levels, for
+example as parts of several @code{\include}d files.  If so, the
+fields at each level are merged, with values encountered last taking
+precedence if duplicated fields appear.
+
 Settings that can appear in a @code{\paper} block include:
 
 @itemize
@@ -2840,12 +2867,18 @@ No work-around exists for decreasing the amount of space.
 @node New spacing area
 @subsection New spacing area
 
+@funindex \newSpacingSection
+@cindex new spacing area
+@cindex spacing area, new
+@cindex notes, spacing horizontally
+
 New sections with different spacing parameters can be started with
 @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
-section, and hence the 16ths notes are spaced wider.
+section, and hence the 16ths notes are automatically spaced slightly
+wider.
 
 @lilypond[relative=1,verbatim,quote]
 \time 2/4
@@ -2857,8 +2890,25 @@ c16[ c c8]
 @end lilypond
 
 The @code{\newSpacingSection} command creates a new
-@code{SpacingSpanner} object, and hence new @code{\override}s
-may be used in that location.
+@code{SpacingSpanner} object at that musical moment.
+If the automatic spacing adjustments do not give the required spacing,
+manual @code{\override}s may be applied to its properties.  These must
+be applied at the same musical moment as the @code{\newSpacingSection}
+command itself.  They will then affect the spacing of all the following
+music until the properties are changed in a new spacing section, for
+example,
+
+@lilypond[relative=1,verbatim,quote]
+\time 4/16
+c16[ c c8]
+\newSpacingSection
+\override Score.SpacingSpanner.spacing-increment = #2
+c16[ c c8]
+\newSpacingSection
+\revert Score.SpacingSpanner.spacing-increment
+c16[ c c8]
+@end lilypond
+
 
 @seealso
 Snippets: