X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fnotation%2Fspacing.itely;h=6ca227e5f8bdb7c3c1e84d8830dfe015b914bfae;hb=b00f11e450fd9c3c7b56ece5afa72606cac064cb;hp=8352e5a8be91335dc05b44870624f8c332f8f485;hpb=232de3305dd5262822fd1e081ddd52581319f4ce;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 8352e5a8be..6ca227e5f8 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.17.6"
+@c \version "2.17.11"
 
 @ignore
 GDP TODO list
@@ -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
@@ -1393,7 +1420,7 @@ with the music:
   \remove "Forbid_line_break_engraver"
 } \relative c'' {
   <<
-    { c2. \times 2/3 { c4 c c } c2. | }
+    { c2. \tuplet 3/2 { c4 c c } c2. | }
     { s1 | \break s1 | }
   >>
 }
@@ -1607,7 +1634,7 @@ the section.
 The @code{Page_turn_engraver} reads the context property
 @code{minimumPageTurnLength} to determine how long a note-free section must
 be before a page turn is considered.  The default value for
-@code{minimumPageTurnLength} is @code{(ly:make-moment 1 1)}.  If you want
+@code{minimumPageTurnLength} is @code{(ly:make-moment 1/1)}.  If you want
 to disable page turns, you can set it to something very large.
 
 @example
@@ -1616,7 +1643,7 @@ to disable page turns, you can set it to something very large.
   a4 b c d |
   R1 | % a page turn will be allowed here
   a4 b c d |
-  \set Staff.minimumPageTurnLength = #(ly:make-moment 5 2)
+  \set Staff.minimumPageTurnLength = #(ly:make-moment 5/2)
   R1 | % a page turn will not be allowed here
   a4 b r2 |
   R1*2 | % a page turn will be allowed here
@@ -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:
@@ -2902,7 +2952,7 @@ than @code{1 16}.
   \layout {
     \context {
       \Score
-      \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1 16)
+      \override SpacingSpanner.base-shortest-duration = #(ly:make-moment 1/16)
     }
   }
 }
@@ -2921,14 +2971,14 @@ property can only be changed at the beginning of a score,
 \score {
   <<
     \new Staff {
-      \times 4/5 {
+      \tuplet 5/4 {
         c8 c8 c8 c8 c8
       }
       c8 c8 c8 c8
     }
     \new Staff {
       c8 c8 c8 c8
-      \times 4/5 {
+      \tuplet 5/4 {
         c8 c8 c8 c8 c8
       }
     }
@@ -3042,7 +3092,7 @@ spacing with ragged-right turned on.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
@@ -3071,7 +3121,7 @@ setting.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
@@ -3079,7 +3129,7 @@ setting.
  \layout {
     \context {
       \Score
-      proportionalNotationDuration = #(ly:make-moment 1 20)
+      proportionalNotationDuration = #(ly:make-moment 1/20)
     }
   }
 }
@@ -3102,10 +3152,10 @@ The @code{proportionalNotationDuration} setting takes a single argument,
 which is the reference duration against that all music will be spaced.
 The LilyPond Scheme function @code{make-moment} takes two arguments
 -- a numerator and denominator which together express some fraction of
-a whole note.  The call @code{(ly:make-moment 1 20)} therefore produces
+a whole note.  The call @code{(ly:make-moment 1/20)} therefore produces
 a reference duration of a twentieth note.  Values such as
-@code{(ly:make-moment 1 16)}, @code{(ly:make-moment 1 8)}, and
-@code{(ly:make-moment 3 97)} are all possible as well.
+@code{(ly:make-moment 1/16)}, @code{(ly:make-moment 1/8)}, and
+@code{(ly:make-moment 3/97)} are all possible as well.
 
 How do we select the right reference duration to pass to
 @code{proportionalNotationDuration}?  Usually by a process of trial
@@ -3119,7 +3169,7 @@ larger reference durations space music tightly.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
@@ -3127,7 +3177,7 @@ larger reference durations space music tightly.
   \layout {
     \context {
       \Score
-      proportionalNotationDuration = #(ly:make-moment 1 8)
+      proportionalNotationDuration = #(ly:make-moment 1/8)
     }
   }
 }
@@ -3137,7 +3187,7 @@ larger reference durations space music tightly.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
@@ -3145,7 +3195,7 @@ larger reference durations space music tightly.
   \layout {
     \context {
       \Score
-      proportionalNotationDuration = #(ly:make-moment 1 16)
+      proportionalNotationDuration = #(ly:make-moment 1/16)
     }
   }
 }
@@ -3155,7 +3205,7 @@ larger reference durations space music tightly.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
@@ -3163,7 +3213,7 @@ larger reference durations space music tightly.
   \layout {
     \context {
       \Score
-      proportionalNotationDuration = #(ly:make-moment 1 32)
+      proportionalNotationDuration = #(ly:make-moment 1/32)
     }
   }
 }
@@ -3187,12 +3237,12 @@ tuplet.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
     \new RhythmicStaff {
-      \times 8/9 {
+      \tuplet 9/8 {
         c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
       }
     }
@@ -3211,12 +3261,12 @@ result.  Setting @code{proportionalNotationDuration} fixes this.
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
     \new RhythmicStaff {
-      \times 8/9 {
+      \tuplet 9/8 {
         c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
       }
     }
@@ -3224,7 +3274,7 @@ result.  Setting @code{proportionalNotationDuration} fixes this.
   \layout {
     \context {
       \Score
-      proportionalNotationDuration = #(ly:make-moment 1 20)
+      proportionalNotationDuration = #(ly:make-moment 1/20)
     }
   }
 }
@@ -3242,12 +3292,12 @@ turn on @code{uniform-stretching}, which is a property of
     \new RhythmicStaff {
       c'2
       c'16 c'16 c'16 c'16
-      \times 4/5 {
+      \tuplet 5/4 {
         c'16 c'16 c'16 c'16 c'16
       }
     }
     \new RhythmicStaff {
-      \times 8/9 {
+      \tuplet 9/8 {
         c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
       }
     }
@@ -3255,7 +3305,7 @@ turn on @code{uniform-stretching}, which is a property of
   \layout {
     \context {
       \Score
-      proportionalNotationDuration = #(ly:make-moment 1 20)
+      proportionalNotationDuration = #(ly:make-moment 1/20)
       \override SpacingSpanner.uniform-stretching = ##t
     }
   }
@@ -3344,7 +3394,7 @@ property of @code{SpacingSpanner}.  Compare the two scores below:
 
 @lilypond[quote,verbatim,ragged-right]
 \new Staff {
-  \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
+  \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
   c''8
   c''8
   c''8
@@ -3354,7 +3404,7 @@ property of @code{SpacingSpanner}.  Compare the two scores below:
 }
 
 \new Staff {
-  \set Score.proportionalNotationDuration = #(ly:make-moment 1 16)
+  \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
   \override Score.SpacingSpanner.strict-note-spacing = ##t
   c''8
   c''8
@@ -3568,7 +3618,7 @@ duration longer, a @q{squeezing} effect occurs:
   \layout {
     \context {
       \Score
-      \override SpacingSpanner.common-shortest-duration = #(ly:make-moment 1 2)
+      \override SpacingSpanner.common-shortest-duration = #(ly:make-moment 1/2)
     }
   }
 }