Merge branch 'master' of git+ssh://jneem@git.sv.gnu.org/srv/git/lilypond

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 814525184cbbbea419160b650407da64f2d22b5d..82e22da1efb5dfe68dc352539f69c4ac09a60d2c 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -211,6 +211,13 @@ top-most of the next system. Default is@tie{}4mm.
 Increasing this will put systems whose bounding boxes almost touch
 farther apart.
 
+@funindex page-breaking-between-system-padding
+@item between-system-padding
+This variable, if set, tricks the page breaker into thinking that
+@code{between-system-padding} is set to something different than it
+really is. For example, if this variable is set to something substantially
+larger than @code{between-system-padding}, then the page-breaker will put
+fewer systems on each page.
 
 @funindex horizontal-shift
 @item horizontal-shift
@@ -559,12 +566,6 @@ This makes the following 28 measures (assuming 4/4 time) be broken every
 
 Internals: @internalsref{LineBreakEvent}.
 
-A linebreaking configuration can now be saved as a @code{.ly} file
-automatically.  This allows vertical alignments to be stretched to
-fit pages in a second formatting run.  This is fairly new and
-complicated.  More details are available in
-@lsrdir{spacing}
-
 
 @refbugs
 
@@ -881,6 +882,54 @@ first number is generally negative.  The numbers need not match;
 for example, the staff can be made larger at the bottom by setting
 it to @code{(-6 . 4)}.
 
+After page breaks are determined, the vertical spacing within each
+system is reevaluated in order to fill the page more evenly; if a page
+has space left over, systems are stretched in order to fill that space.
+The amount of stretching can be configured though the @code{max-stretch}
+property of the @internalsref{VerticalAlignment} grob. To disable this
+stretching entirely, set @code{max-stretch} to zero.
+
+In some situations, you may want to stretch most of a system while
+leaving some parts fixed. For example, if a piano part occurs in the
+middle of an orchestral score, you may want to leave the piano staves
+close to each other while stretching the rest of the score. The
+@code{keep-fixed-while-stretching} property of
+@internalsref{VerticalAxisGroup} can be used to achieve this. When set
+to @code{##t}, this property keeps its staff (or line of lyrics) from
+moving relative to the one directly above it. In the example above,
+you would override @code{keep-fixed-while-stretching} to @code{##t} in
+the second piano staff:
+
+@example
+\paper {
+  ragged-last-bottom = ##f
+}
+
+\new GrandStaff
+<<
+  \new StaffGroup
+  <<
+    \new Staff {c' d' e' f'}
+    \new Staff {c' d' e' f'}
+    \new Staff {c' d' e' f'}
+  >>
+
+  \new PianoStaff
+  <<
+    \new Staff {c' d' e' f'}
+    \new Staff \with {
+      \override VerticalAxisGroup #'keep-fixed-while-stretching = ##t
+    }
+    {c' d' e' f'}
+  >>
+
+  \new StaffGroup
+  <<
+    \new Staff {c' d' e' f'}
+    \new Staff {c' d' e' f'}
+  >>
+>>
+@end example
 
 @seealso
 
@@ -1112,62 +1161,6 @@ to print staves or systems on top of one another.  Reasonable values
 passed to these different settings will avoid this.
 @end itemize
 
-
-@node Two-pass vertical spacing
-@subsection Two-pass vertical spacing
-
-In order to automatically stretch systems so that they should fill the
-space left on a page, a two-pass technique can be used:
-
-@enumerate
-@item In the first pass, the amount of vertical space used to increase
-the height of each system is computed and dumped to a file.
-@item In the second pass, spacing inside the systems are
-stretched according to the data in the page layout file.
-@end enumerate
-
-The @code{ragged-bottom} property adds space between systems, while
-the two-pass technique adds space between staves inside a system.
-
-To allow this behaviour, a @code{tweak-key} variable has to be set in
-each score @code{\layout} block, and the tweaks included in each score
-music, using the @code{\scoreTweak} music function.
-
-@quotation
-@verbatim
-%% include the generated page layout file:
-\includePageLayoutFile
-
-\score {
-  \new StaffGroup <<
-    \new Staff <<
-      %% Include this score tweaks:
-      \scoreTweak "scoreA"
-      { \clef french c''1 \break c''1 } 
-    >>
-    \new Staff { \clef soprano g'1 g'1 }
-    \new Staff { \clef mezzosoprano e'1 e'1 }
-    \new Staff { \clef alto g1 g1 }
-    \new Staff { \clef bass c1 c1 }
-  >>
-  \header {
-    piece = "Score with tweaks"
-  }
-  %% Define how to name the tweaks for this score:
-  \layout { #(define tweak-key "scoreA") }
-}
-@end verbatim
-@end quotation
-
-For the first pass, the @code{dump-tweaks} option should be set to
-generate the page layout file.
-
-@example
-lilypond -dbackend=null -d dump-tweaks <file>.ly
-lilypond <file>.ly
-@end example
-
-
 @node Vertical collision avoidance
 @subsection Vertical collision avoidance