Merge branch 'master' of carldsorensen@git.sv.gnu.org:/srv/git/lilypond into ralph

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

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 349eabdbc93775104b06f844a163f7efa100d70c..1b81a996f5a7ae5ded4fb197203e6752755d0856 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.64"
+@c \version "2.12.0"
 
 @ignore
 GDP TODO list
@@ -162,7 +162,6 @@ the variables.
 
 
 @seealso
-
 Installed Files:
 @file{scm/@/paper@/.scm}.
 
@@ -350,7 +349,6 @@ page given the system to put on it.
 
 
 @seealso
-
 Notation Reference:
 @ref{Vertical spacing between systems}.
 
@@ -414,7 +412,6 @@ first system.  Default: @code{0}, as determined by
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -595,7 +592,6 @@ Default: unset.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -712,13 +708,8 @@ 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.
 
-@example
-
-@end example
-
 
 @seealso
-
 Notation Reference:
 @ref{Selecting notation font size}.
 
@@ -756,7 +747,6 @@ layout.
 
 
 @seealso
-
 Notation Reference:
 @ref{Changing context default settings}.
 
@@ -850,15 +840,14 @@ complicated.  More details are available in
 
 
 @predefined
-
 @funindex \break
 @code{\break},
 @funindex \noBreak
 @code{\noBreak}.
+@endpredefined
 
 
 @seealso
-
 Internals Reference:
 @rinternals{LineBreakEvent}.
 
@@ -967,16 +956,16 @@ book parts.
 @}
 @end example
 
-@predefined
 
+@predefined
 @funindex \pageBreak
 @code{\pageBreak},
 @funindex \noPageBreak
 @code{\noPageBreak}.
+@endpredefined
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -993,7 +982,6 @@ cramping and stretching, both horizontally and vertically.  Unlike
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1065,17 +1053,16 @@ top-level markups.
 
 
 @predefined
-
 @funindex \pageTurn
 @code{\pageTurn},
 @funindex \noPageTurn
 @code{\noPageTurn},
 @funindex \allowPageTurn
 @code{\allowPageTurn}.
+@endpredefined
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1105,7 +1092,6 @@ too slow or memory demanding, or a lot of texts.  It is enabled using:
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1154,7 +1140,6 @@ page breaks at explicit @code{\pageBreak} commands and nowhere else.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1238,7 +1223,6 @@ This pattern becomes especially helpful when overriding
 
 
 @seealso
-
 Notation Reference:
 @ref{Vertical spacing}.
 
@@ -1370,7 +1354,6 @@ the @code{Axis_group_engraver}.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1435,7 +1418,6 @@ the last one.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1503,20 +1485,29 @@ example @code{NonMusicalPaperColumn} overrides with the special
 To understand how each of these different settings work, we begin
 by looking at an example that includes no overrides at all.
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      s1 * 5 \break
-      s1 * 5 \break
-      s1 * 5 \break
-    }
-    \new Voice { \repeat unfold 15 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new Staff {
-    \repeat unfold 15 { d'4 d'4 d'4 d'4 }
+@c \book { } is required in these examples to ensure the spacing
+@c overrides can be seen between systems. -np
+
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          s1*5 \break
+          s1*5 \break
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
   }
->>
+}
 @end lilypond
 
 This score isolates line- and page-breaking information in a dedicated
@@ -1530,26 +1521,32 @@ the vertical startpoint of each system explicitly, we can set
 the @code{Y-offset} pair in the @code{line-break-system-details}
 attribute of the @code{NonMusicalPaperColumn} grob:
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 0))
-      s1 * 5 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 40))
-      s1 * 5 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 80))
-      s1 * 5 \break
-    }
-    \new Voice { \repeat unfold 15 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new Staff {
-    \repeat unfold 15 { d'4 d'4 d'4 d'4 }
+@lilypond[quote]
+\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*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 40))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 80))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
   }
->>
+}
 @end lilypond
 
 Note that @code{line-break-system-details} takes an associative list of
@@ -1562,29 +1559,35 @@ explicitly, we can also set the vertical startpoint of each staff
 within each system manually.  We do this using the @code{alignment-offsets}
 subproperty of @code{line-break-system-details}.
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 20)
-          (alignment-offsets . (0 -15)))
-      s1 * 5 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 60)
-          (alignment-offsets . (0 -15)))
-      s1 * 5 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 100)
-          (alignment-offsets . (0 -15)))
-      s1 * 5 \break
-    }
-    \new Voice { \repeat unfold 15 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new Staff {
-    \repeat unfold 15 { d'4 d'4 d'4 d'4 }
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 20)
+                                           (alignment-offsets . (0 -15)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 60)
+                                           (alignment-offsets . (0 -15)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 100)
+                                           (alignment-offsets . (0 -15)))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
   }
->>
+}
 @end lilypond
 
 Note that here we assign two different values to the
@@ -1597,34 +1600,36 @@ additional spacing parameters (including, for example, a corresponding
 every system and every staff.  Finally, note that @code{alignment-offsets}
 specifies the vertical positioning of staves but not of staff groups.
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-      #'line-break-system-details #'((Y-offset . 0)
-        (alignment-offsets . (0 -30 -40)))
-      s1 * 5 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-      #'line-break-system-details #'((Y-offset . 60)
-        (alignment-offsets . (0 -10 -20)))
-      s1 * 5 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-      #'line-break-system-details #'((Y-offset . 100)
-        (alignment-offsets . (0 -10, -40)))
-      s1 * 5 \break
-    }
-    \new Voice { \repeat unfold 15 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new StaffGroup <<
-    \new Staff {
-      \repeat unfold 15 { d'4 d'4 d'4 d'4 }
-    }
-    \new Staff {
-      \repeat unfold 15 { e'4 e'4 e'4 e'4 }
-    }
-  >>
->>
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 0)
+                                           (alignment-offsets . (0 -30 -40)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 60)
+                                           (alignment-offsets . (0 -10 -20)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 100)
+                                           (alignment-offsets . (0 -10 -40)))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new StaffGroup <<
+        \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
+        \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
+      >>
+    >>
+  }
+}
 @end lilypond
 
 Some points to consider:
@@ -1646,7 +1651,6 @@ passed to these different settings will avoid this.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1711,7 +1715,6 @@ lilypond <file>.ly
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1772,29 +1775,31 @@ c^"This text is padded away from the previous text"
 c^"This text is placed close to the previous text"
 @end lilypond
 
-TODO: this example doesn't work any more ?
 
-By default, outside-staff objects are placed without regard to
-their horizontal distance from the previously-positioned grobs.  This
+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.  Setting @code{outside-staff-horizontal-padding}
+other horizontally.  The vertical spacing between staffs 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.
 
 @lilypond[quote,ragged-right,relative=2,fragment,verbatim]
 % the markup is too close to the following note
-c2^"Text"
+c4^"Text"
+c4
 c''2
 % setting outside-staff-horizontal-padding fixes this
 R1
 \once \override TextScript #'outside-staff-horizontal-padding = #1
-c,,2^"Text"
+c,,4^"Text"
+c4
 c''2
 @end lilypond
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1903,7 +1908,6 @@ Proportional notation is supported; see @ref{Proportional notation}.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -1950,7 +1954,6 @@ may be used in that location.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -2037,7 +2040,6 @@ regard for clefs, bar lines, and grace notes,
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -2090,7 +2092,6 @@ paragraph, the last line simply takes its natural horizontal length.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -2439,7 +2440,6 @@ for these related settings.
 
 
 @seealso
-
 Notation Reference:
 @ref{New spacing area}.
 
@@ -2497,7 +2497,6 @@ interval.
 
 
 @seealso
-
 Snippets:
 @rlsr{Spacing}.
 
@@ -2602,7 +2601,6 @@ block so that it applies to the whole score.
 
 
 @seealso
-
 Notation Reference:
 @ref{Page formatting},
 @ref{Changing horizontal spacing}.