From 04265f11d1f21416ccebd2dcaa1d903dc781b36e Mon Sep 17 00:00:00 2001
From: Nicolas Sceaux <nicolas.sceaux@free.fr>
Date: Sun, 8 Oct 2006 09:17:06 +0000
Subject: [PATCH] (Two-pass vertical spacing): add documentation for two-pass
 spacing technique.

---
 ChangeLog                     |  5 +++
 Documentation/user/page.itely | 59 ++++++++++++++++++++++++++++++++---
 2 files changed, 60 insertions(+), 4 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 8a3935ce17..549e153de2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-10-08  Nicolas Sceaux  <nicolas.sceaux@free.fr>
+
+	* Documentation/user/page.itely (Two-pass vertical spacing): add
+	documentation for two-pass spacing technique.
+
 2006-10-06  Graham Percival  <gpermus@gmail.com>
 
 	* Documentation/user/convert-ly.txt: new file; new
diff --git a/Documentation/user/page.itely b/Documentation/user/page.itely
index 8511f8ea6b..ceaee2adef 100644
--- a/Documentation/user/page.itely
+++ b/Documentation/user/page.itely
@@ -468,6 +468,7 @@ staves inside a system.
 * Vertical spacing of piano staves::  
 * Vertical spacing between systems::  
 * Controlling spacing of individual systems::  
+* Two-pass vertical spacing::
 @end menu
 
 
@@ -618,6 +619,56 @@ The distance for @code{fixed-alignment-extra-space} may also be
 negative.
 
 
+@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, the systems are stretched according to the
+data in the page layout file.
+@end enumerate
+
+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 -b null -d dump-tweaks <file>.ly
+lilypond <file>.ly
+@end example
 
 @node Horizontal spacing
 @section Horizontal Spacing
@@ -626,10 +677,10 @@ negative.
 @cindex spacing, horizontal
 
 @menu
-* Horizontal spacing overview::  
-* New spacing area::            
-* Changing horizontal spacing::  
-* Line length::                 
+* Horizontal spacing overview::
+* New spacing area::
+* Changing horizontal spacing::
+* Line length::
 @end menu
 
 
-- 
2.39.2