X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fnotation%2Fspacing.itely;h=89810f6dad17b130f1566f91d5aa28a88b2169f1;hb=c8a283f91341e572b04f115c8edfa5bd00d61ad7;hp=53ef68ad37a6a3caf0d68d7a1476ef5bdc7935b4;hpb=52e389f2b2009195b7aa2f13e6476ca6455e5b2e;p=lilypond.git

diff --git a/Documentation/notation/spacing.itely b/Documentation/notation/spacing.itely
index 53ef68ad37..89810f6dad 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.13.39"
+@c \version "2.13.42"
 
 @ignore
 GDP TODO list
@@ -174,7 +174,9 @@ The Scheme equivalent of the above example is:
 
 @seealso
 Notation Reference:
-@ref{Custom headers footers and titles}.
+@ref{Paper size and automatic scaling},
+@ref{Custom headers footers and titles},
+@ref{The \layout block}.
 
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
@@ -255,6 +257,9 @@ degrees, and wider line widths will be set accordingly.
 @end example
 
 @seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
 Installed Files:
 @file{scm/paper.scm}.
 
@@ -350,6 +355,9 @@ parts of a book created with @code{\bookpart} blocks.
 @end table
 
 @seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
@@ -395,24 +403,17 @@ an alist (association list) containing four @emph{keys}:
 @itemize
 
 @item
-@code{padding} -- the minimum required amount of unobstructed
-vertical whitespace between two items, measured in staff-spaces.
-This can be thought of as the minimum height of an unobstructed
-(invisible) rectangle that extends from the leftmost to the
-rightmost point of the combined items.
-
-@item
-@code{space} -- the vertical distance, measured in staff-spaces,
-between the @emph{reference points} of the two items, when no
-collisions would result, and no stretching or compressing is in
-effect.  The reference point of a (title or top-level) markup is
-its highest point, and the reference point of a system is the
-vertical center of the nearest @code{StaffSymbol} -- even if a
-non-staff line (such as a @code{Lyrics} context) is in the way.
-Values for @code{space} that are less than either @code{padding}
-or @code{minimum-distance} are not meaningful, since the resulting
-distance will never be less than either @code{padding} or
-@code{minimum-distance}.
+@code{basic-distance} -- the vertical distance, measured in
+staff-spaces, between the @emph{reference points} of the two
+items, when no collisions would result, and no stretching or
+compressing is in effect.  The reference point of a (title or
+top-level) markup is its highest point, and the reference point of
+a system is the vertical center of the nearest @code{StaffSymbol}
+-- even if a non-staff line (such as a @code{Lyrics} context) is
+in the way.  Values for @code{basic-distance} that are less than
+either @code{padding} or @code{minimum-distance} are not
+meaningful, since the resulting distance will never be less than
+either @code{padding} or @code{minimum-distance}.
 
 @item
 @code{minimum-distance} -- the smallest allowable vertical
@@ -422,6 +423,13 @@ of the two items, when compressing is in effect.  Values for
 meaningful, since the resulting distance will never be less than
 @code{padding.}
 
+@c TODO: explain skylines somewhere and xref to it from here.
+
+@item
+@code{padding} -- the minimum required amount of unobstructed
+vertical whitespace between the bounding boxes (or skylines) of
+the two items, measured in staff-spaces.
+
 @item
 @code{stretchability} -- a unitless measure of the dimension's
 relative propensity to stretch.  If zero, the distance will not
@@ -433,10 +441,10 @@ twice the @code{stretchability} of another, it will stretch twice
 as easily.  Values should be non-negative and finite.  The value
 @code{+inf.0} triggers a @code{programming_error} and is ignored,
 but @code{1.0e7} can be used for an almost infinitely stretchable
-spring.  If unset, the default value is set to @code{space}.  Note
-that the dimension's propensity to @emph{compress} cannot be
-directly set by the user and is equal to
-(@code{space}@tie{}@minus{}@tie{}@code{minimum-distance}).
+spring.  If unset, the default value is set to
+@code{basic-distance}.  Note that the dimension's propensity to
+@emph{compress} cannot be directly set by the user and is equal to
+(@code{basic-distance}@tie{}@minus{}@tie{}@code{minimum-distance}).
 
 @end itemize
 
@@ -446,7 +454,7 @@ largest of:
 @itemize
 
 @item
-@code{space},
+@code{basic-distance},
 
 @item
 @code{minimum-distance}, and
@@ -465,11 +473,11 @@ redefines the variable:
 
 @example
 \paper @{
-  system-system-spacing #'space = #8
+  system-system-spacing #'basic-distance = #8
   score-system-spacing =
-    #'((padding . 1)
-       (space . 12)
+    #'((basic-distance . 12)
        (minimum-distance . 6)
+       (padding . 1)
        (stretchability . 12))
 @}
 @end example
@@ -658,6 +666,9 @@ set in a @code{\layout} block.
 @end table
 
 @seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
@@ -708,6 +719,9 @@ with @code{two-sided} set to true.
 @end table
 
 @seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
@@ -747,6 +761,9 @@ set in a @code{\layout} block.
 @end table
 
 @seealso
+Notation Reference:
+@ref{Automatic scaling to paper size}.
+
 Installed Files:
 @file{ly/paper-defaults-init.ly}.
 
@@ -1031,7 +1048,7 @@ Here is an example @code{\layout} block:
   indent = 2\cm
   \context @{
     \StaffGroup
-    \override StaffGrouper #'staff-staff-spacing #space = #8
+    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #8
   @}
   \context @{
     \Voice
@@ -1180,18 +1197,58 @@ staff lines.
 
 Line breaks are normally determined automatically.  They are chosen
 so that lines look neither cramped nor loose, and consecutive
-lines have similar density.  Occasionally you might want to
-override the automatic breaks; you can do this by specifying
-@code{\break}.  This will force a line break at this point.  However,
-line breaks can only occur at the end of @q{complete} bars, i.e.,
-where there are no notes or tuplets left @q{hanging} over the bar
-line.  If you want to have a line break where there is no bar line,
-you can force an invisible bar line by entering @code{\bar ""},
-although again there must be no notes left hanging over in any of
-the staves at this point, or it will be ignored.
-
-The opposite command, @code{\noBreak}, forbids a line break at the
-bar line where it is inserted.
+lines have similar density.
+
+To manually force a line break at a bar line, use the
+@code{\break} command:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c c | \break
+c4 c c c |
+@end lilypond
+
+By default, a @code{\break} in the middle of a measure is ignored,
+and a warning is printed.  To force a line break in the middle of
+a measure, add an invisible bar line with @w{@samp{\bar ""}}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+c4 c c
+\bar "" \break
+c |
+c4 c c c |
+@end lilypond
+
+A @code{\break} occuring at a bar line is also ignored if the
+previous measure ends in the middle of a note, such as when a
+tuplet begins and ends in different measures.  To allow
+@code{\break} commands to work in these situations, remove the
+@code{Forbid_line_break_engraver} from the @code{Voice} context.
+Note that manually forced line breaks have to be added in parallel
+with the music:
+
+@lilypond[quote,ragged-right,verbatim]
+\new Voice \with {
+  \remove Forbid_line_break_engraver
+} \relative c'' {
+  <<
+    { c2. \times 2/3 { c4 c c } c2. | }
+    { s1 | \break s1 | }
+  >>
+}
+@end lilypond
+
+Similarly, line breaks are normally forbidden when beams cross bar
+lines.  This behavior can be changed by setting
+@code{\override Beam #'breakable = ##t}:
+
+@lilypond[quote,ragged-right,relative=2,verbatim]
+\override Beam #'breakable = ##t
+c2. c8[ c | \break
+c8 c] c2. |
+@end lilypond
+
+The @code{\noBreak} command forbids a line break at the bar line
+where it is inserted.
 
 The most basic settings influencing line spacing are @code{indent}
 and @code{line-width}.  They are set in the @code{\layout} block.
@@ -1254,6 +1311,9 @@ complicated.  More details are available in
 
 
 @seealso
+Notation Reference:
+@ref{\paper variables for line breaking}.
+
 Snippets:
 @rlsr{Spacing}.
 
@@ -1261,36 +1321,6 @@ Internals Reference:
 @rinternals{LineBreakEvent}.
 
 
-@knownissues
-
-Line breaks can only occur if there is a @q{proper} bar line.  A note
-which is hanging over a bar line is not proper, such as
-
-@lilypond[quote,ragged-right,relative=2,verbatim]
-c4 c2 << c2 {s4 \break } >>  % this does nothing
-c2 c4 |           % a break here would work
-c4 c2 c4 ~ \break % as does this break
-c4 c2 c4
-@end lilypond
-
-This can be avoided by removing the @code{Forbid_line_break_engraver}.
-Note that manually forced line breaks have to be added in parallel
-with the music.
-
-@lilypond[quote,ragged-right,verbatim]
-\new Voice \with {
-  \remove Forbid_line_break_engraver
-} {
-  c4 c2 << c2 {s4 \break } >>  % now the break is allowed
-  c2 c4
-}
-@end lilypond
-
-Similarly, line breaks are normally forbidden when beams cross bar
-lines.  This behavior can be changed by setting
-@code{\override Beam #'breakable = ##t}.
-
-
 @node Page breaking
 @subsection Page breaking
 
@@ -1366,6 +1396,9 @@ book parts.
 
 
 @seealso
+Notation Reference:
+@ref{\paper variables for page breaking}.
+
 Snippets:
 @rlsr{Spacing}.
 
@@ -1745,7 +1778,7 @@ In the following image, horizontal lines indicate the positions
 of these reference points:
 
 @lilypond[quote,noragged-right,line-width=110\mm]
-#(define zero-space '((padding . -inf.0) (space . 0)))
+#(define zero-space '((padding . -inf.0) (basic-distance . 0)))
 
 alignToZero = \with {
   \override VerticalAxisGroup #'nonstaff-relatedstaff-spacing = #zero-space
@@ -1841,14 +1874,14 @@ individually, and the second completely re-defines the property:
 
 @example
 \new Staff \with @{
-  \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+  \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
 @} @{ @dots{} @}
 
 \new Staff \with @{
   \override VerticalAxisGroup #'staff-staff-spacing =
-    #'((padding . 1)
-       (space . 10)
+    #'((basic-distance . 10)
        (minimum-distance . 9)
+       (padding . 1)
        (stretchability . 10))
 @} @{ @dots{} @}
 @end example
@@ -1860,7 +1893,7 @@ To change any spacing settings globally, put them in the
 \layout @{
   \context @{
     \Staff
-    \override VerticalAxisGroup #'staff-staff-spacing #'space = #10
+    \override VerticalAxisGroup #'staff-staff-spacing #'basic-distance = #10
   @}
 @}
 @end example
@@ -2002,30 +2035,30 @@ property can affect the spacing of ungrouped staves:
   \context {
     \Staff
     \override VerticalAxisGroup #'staff-staff-spacing =
-      #'((padding . 1)
-         (space . 8)
-         (minimum-distance . 7))
+      #'((basic-distance . 8)
+         (minimum-distance . 7)
+         (padding . 1))
   }
 }
 
 \new StaffGroup <<
-  % The very low note here needs more room than 'space can
-  % provide, so the distance between this staff and the next is
-  % determined by 'padding.
+  % The very low note here needs more room than 'basic-distance
+  % can provide, so the distance between this staff and the next
+  % is determined by 'padding.
   \new Staff { b,2 r | }
 
-  % Here, 'space provides enough room, and there is no need to
-  % compress the space (towards 'minimum-distance) to make room
-  % for anything else on the page, so the distance between this
-  % staff and the next is determined by 'space.
+  % Here, 'basic-distance provides enough room, and there is no
+  % need to compress the space (towards 'minimum-distance) to make
+  % room for anything else on the page, so the distance between
+  % this staff and the next is determined by 'basic-distance.
   \new Staff { \clef bass g2 r | }
 
   % By setting 'padding to a negative value, staves can be made to
-  % collide.  The lowest acceptable value for 'space is 0.
+  % collide.  The lowest acceptable value for 'basic-distance is 0.
   \new Staff \with {
     \override VerticalAxisGroup #'staff-staff-spacing =
-      #'((padding . -10)
-         (space . 3.5))
+      #'((basic-distance . 3.5)
+         (padding . -10))
   } { \clef bass g2 r | }
   \new Staff { \clef bass g2 r | }
 >>
@@ -2080,13 +2113,13 @@ The following example shows how properties of the
   \context {
     \Score
     \override StaffGrouper #'staff-staff-spacing #'padding = #0
-    \override StaffGrouper #'staff-staff-spacing #'space = #1
+    \override StaffGrouper #'staff-staff-spacing #'basic-distance = #1
   }
 }
 
 <<
   \new PianoStaff \with {
-    \override StaffGrouper #'staffgroup-staff-spacing #'space = #20
+    \override StaffGrouper #'staffgroup-staff-spacing #'basic-distance = #20
   } <<
     \new Staff { c'1 }
     \new Staff { c'1 }
@@ -2153,7 +2186,7 @@ able to stretch much more than usual:
 \new StaffGroup
 <<
   \new Staff \with {
-    \override VerticalAxisGroup #'staff-staff-spacing = #'((space . 30))
+    \override VerticalAxisGroup #'staff-staff-spacing = #'((basic-distance . 30))
   } { c'1 }
   \new Lyrics \with {
     \override VerticalAxisGroup #'staff-affinity = #UP
@@ -3287,7 +3320,7 @@ there is no blank space at the bottom of the page.
 
 @example
 \paper @{
-  system-system-spacing = #'((padding . 0) (space . 0.1))
+  system-system-spacing = #'((basic-distance . 0.1) (padding . 0))
   ragged-last-bottom = ##f
   ragged-bottom = ##f
 @}