X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fspacing.itely;h=91eeefa4e82687acb6fb7b6f40a57b5c6c6e61e6;hb=9352789b729682d683482c2852cc7b53e9dcdc70;hp=3f427ddbad0160e0bc408a6552b4bea4975de003;hpb=0f882952d6c97277aec32d4476415393c00cc400;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 3f427ddbad..91eeefa4e8 100644
--- 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
@@ -1774,21 +1801,25 @@ breaking layout information.
 @lilypond[quote,verbatim]
 music = \relative c'' { c4 c c c }
 
-\score {
-  \new Staff <<
-    \new Voice {
-      s1 * 2 \break
-      s1 * 3 \break
-      s1 * 6 \break
-      s1 * 5 \break
-    }
-    \new Voice {
-      \repeat unfold 2 { \music }
-      \repeat unfold 3 { \music }
-      \repeat unfold 6 { \music }
-      \repeat unfold 5 { \music }
-    }
-  >>
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    \new Staff <<
+      \new Voice {
+        s1 * 2 \break
+        s1 * 3 \break
+        s1 * 6 \break
+        s1 * 5 \break
+      }
+      \new Voice {
+        \repeat unfold 2 { \music }
+        \repeat unfold 3 { \music }
+        \repeat unfold 6 { \music }
+        \repeat unfold 5 { \music }
+      }
+    >>
+  }
 }
 @end lilypond
 
@@ -1799,28 +1830,36 @@ This pattern becomes especially helpful when overriding
 @lilypond[quote,verbatim]
 music = \relative c'' { c4 c c c }
 
-\score {
-  \new Staff <<
-    \new Voice {
-      \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 0))
-      s1 * 2 \break
-
-      \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 35))
-      s1 * 3 \break
-
-      \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 70))
-      s1 * 6 \break
-
-      \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 105))
-      s1 * 5 \break
-    }
-    \new Voice {
-      \repeat unfold 2 { \music }
-      \repeat unfold 3 { \music }
-      \repeat unfold 6 { \music }
-      \repeat unfold 5 { \music }
-    }
-  >>
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    \new Staff <<
+      \new Voice {
+        \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+          #'((Y-offset . 0))
+        s1 * 2 \break
+
+        \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+          #'((Y-offset . 5))
+        s1 * 3 \break
+
+        \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+          #'((Y-offset . 15))
+        s1 * 6 \break
+
+        \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+          #'((Y-offset . 30))
+        s1 * 5 \break
+      }
+      \new Voice {
+        \repeat unfold 2 { \music }
+        \repeat unfold 3 { \music }
+        \repeat unfold 6 { \music }
+        \repeat unfold 5 { \music }
+      }
+    >>
+  }
 }
 @end lilypond
 
@@ -2447,18 +2486,23 @@ example @code{NonMusicalPaperColumn} overrides with the special
 @code{\overrideProperty} command:
 
 @example
-\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((X-offset . 20))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+  #'((X-offset . 20))
 
-\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 40))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+  #'((Y-offset . 40))
 
-\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((X-offset . 20)
-                                 (Y-offset . 40))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+  #'((X-offset . 20)
+     (Y-offset . 40))
 
-\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((alignment-distances . (15)))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+  #'((alignment-distances . (15)))
 
-\overrideProperty NonMusicalPaperColumn.line-break-system-details #'((X-offset . 20)
-                                 (Y-offset . 40)
-                                 (alignment-distances . (15)))
+\overrideProperty NonMusicalPaperColumn.line-break-system-details
+  #'((X-offset . 20)
+     (Y-offset . 40)
+     (alignment-distances . (15)))
 @end example
 
 To understand how each of these different settings work, we begin
@@ -2508,11 +2552,14 @@ attribute of the @code{NonMusicalPaperColumn} grob:
     <<
       \new Staff <<
         \new Voice {
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 0))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 0))
           s1*5 \break
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 40))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 40))
           s1*5 \break
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 80))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 60))
           s1*5 \break
         }
         \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
@@ -2543,14 +2590,17 @@ subproperty of @code{line-break-system-details}.
     <<
       \new Staff <<
         \new Voice {
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 20)
-                                           (alignment-distances . (15)))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 20)
+               (alignment-distances . (10)))
           s1*5 \break
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 60)
-                                           (alignment-distances . (15)))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 60)
+               (alignment-distances . (15)))
           s1*5 \break
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 100)
-                                           (alignment-distances . (15)))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+          #'((Y-offset . 85)
+             (alignment-distances . (20)))
           s1*5 \break
         }
         \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
@@ -2581,14 +2631,17 @@ specifies the vertical positioning of staves but not of staff groups.
     <<
       \new Staff <<
         \new Voice {
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 0)
-                                           (alignment-distances . (30 10)))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 0)
+               (alignment-distances . (30 10)))
           s1*5 \break
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 60)
-                                           (alignment-distances . (10 10)))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 60)
+               (alignment-distances . (10 10)))
           s1*5 \break
-          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details #'((Y-offset . 100)
-                                           (alignment-distances . (10 30)))
+          \overrideProperty Score.NonMusicalPaperColumn.line-break-system-details
+            #'((Y-offset . 100)
+               (alignment-distances . (10 30)))
           s1*5 \break
         }
         \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
@@ -2682,26 +2735,19 @@ c^"This text is placed close to the previous text"
 @end lilypond
 
 
-By default, outside-staff objects are placed only to avoid
+By default, outside-staff objects are placed so they 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 staves can
-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.
+can lead to situations in which objects are placed close to each
+other horizontally.
+As shown in the example below, setting @code{outside-staff-horizontal-padding}
+increases the horizontal spacing required, and in this case moves the text up
+to prevent it from getting too close to the ledger lines.
 
 @lilypond[quote,ragged-right,relative=2,verbatim]
-% the markup is too close to the following note
-c4^"Text"
-c4
-c''2
-% setting outside-staff-horizontal-padding fixes this
+c4^"Word" c c''2
 R1
 \once \override TextScript.outside-staff-horizontal-padding = #1
-c,,4^"Text"
-c4
-c''2
+c,,4^"Word" c c''2
 @end lilypond
 
 @seealso
@@ -2741,8 +2787,9 @@ For example, the following piece contains lots of half, quarter, and
 The quarter note is followed by 2 NHW, the half by 3 NHW, etc.
 
 @lilypond[quote,verbatim,relative=1]
-c2 c4. c8 c4. c8 c4. c8 c8
-c8 c4 c4 c4
+c2 c4. c8
+c4. c8 c4. c8
+c8 c c4 c c
 @end lilypond
 
 Normally, @code{spacing-increment} is set to 1.2 staff space, which is
@@ -2784,7 +2831,7 @@ the common shortest note.  So if we were to add only a few 16th notes
 to the example above, they would be followed by half a NHW:
 
 @lilypond[quote,verbatim,relative=2]
-c2 c4. c8 c4. c16[ c] c4. c8 c8 c8 c4 c4 c4
+c2 c4. c8 | c4. c16[ c] c4. c8 | c8 c c4 c c
 @end lilypond
 
 
@@ -2944,16 +2991,10 @@ property can only be changed at the beginning of a score,
 \score {
   <<
     \new Staff {
-      \tuplet 5/4 {
-        c8 c8 c8 c8 c8
-      }
-      c8 c8 c8 c8
+      \tuplet 5/4 { c8 c c c c } c8 c c c
     }
     \new Staff {
-      c8 c8 c8 c8
-      \tuplet 5/4 {
-        c8 c8 c8 c8 c8
-      }
+      c8 c c c \tuplet 5/4 { c8 c c c c }
     }
   >>
   \layout {
@@ -2970,7 +3011,7 @@ regard for clefs, bar lines, and grace notes,
 
 @lilypond[quote,ragged-right,relative=2,verbatim]
 \override Score.SpacingSpanner.strict-note-spacing = ##t
-\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c32] }
+\new Staff { c8[ c \clef alto c \grace { c16[ c] } c8 c c]  c32[ c] }
 @end lilypond
 
 @seealso
@@ -3063,11 +3104,7 @@ spacing with ragged-right turned on.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
   >>
 }
@@ -3092,11 +3129,7 @@ setting.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
   >>
  \layout {
@@ -3140,11 +3173,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
   >>
   \layout {
@@ -3158,11 +3187,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
   >>
   \layout {
@@ -3176,11 +3201,7 @@ larger reference durations space music tightly.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
   >>
   \layout {
@@ -3208,16 +3229,10 @@ tuplet.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
     \new RhythmicStaff {
-      \tuplet 9/8 {
-        c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
-      }
+      \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
     }
   >>
 }
@@ -3232,16 +3247,10 @@ result.  Setting @code{proportionalNotationDuration} fixes this.
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
     \new RhythmicStaff {
-      \tuplet 9/8 {
-        c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
-      }
+      \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
     }
   >>
   \layout {
@@ -3263,16 +3272,10 @@ turn on @code{uniform-stretching}, which is a property of
 \score {
   <<
     \new RhythmicStaff {
-      c'2
-      c'16 c'16 c'16 c'16
-      \tuplet 5/4 {
-        c'16 c'16 c'16 c'16 c'16
-      }
+      c'2 c'16 c' c' c' \tuplet 5/4 { c'16 c' c' c' c' }
     }
     \new RhythmicStaff {
-      \tuplet 9/8 {
-        c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8 c'8
-      }
+      \tuplet 9/8 { c'8 c' c' c' c' c' c' c' c' }
     }
   >>
   \layout {
@@ -3368,23 +3371,13 @@ property of @code{SpacingSpanner}.  Compare the two scores below:
 @lilypond[quote,verbatim,ragged-right]
 \new Staff {
   \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
-  c''8
-  c''8
-  c''8
-  \clef alto
-  d'8
-  d'2
+  c''8 c'' c'' \clef alto d' d'2
 }
 
 \new Staff {
   \set Score.proportionalNotationDuration = #(ly:make-moment 1/16)
   \override Score.SpacingSpanner.strict-note-spacing = ##t
-  c''8
-  c''8
-  c''8
-  \clef alto
-  d'8
-  d'2
+  c''8 c'' c'' \clef alto d' d'2
 }
 @end lilypond
 
@@ -3400,7 +3393,7 @@ that frequently appear in proportional scores.  These include:
 
 @itemize
 @item @code{\override SpacingSpanner.strict-grace-spacing = ##t}
-@item @code{tupletFullLength = ##t}
+@item @code{\set tupletFullLength = ##t}
 @item @code{\override Beam.breakable = ##t}
 @item @code{\override Glissando.breakable = ##t}
 @item @code{\override TextSpanner.breakable = ##t}
@@ -3449,9 +3442,7 @@ To graphically display the dimensions of vertical layout variables
 that may be altered for page formatting, set
 @code{annotate-spacing} in the @code{\paper} block:
 
-@c need to have \book{} otherwise we get the separate systems. -hwn
-@lilypond[verbatim,quote]
-#(set-default-paper-size "a6" 'landscape)
+@lilypond[verbatim,quote,papersize=a6landscape]
 \book {
   \score { { c4 } }
   \paper { annotate-spacing = ##t }
@@ -3553,7 +3544,7 @@ a system can be moved closer to the staff:
 
 @lilypond[verbatim,quote,relative=1]
 e4 c g\f c
-e4 c g-\tweak X-offset #-2.7 -\tweak Y-offset #2.5 \f c
+e4 c g-\tweak X-offset #-2.7 \f c
 @end lilypond
 
 @item
@@ -3591,7 +3582,8 @@ 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)
     }
   }
 }