(Two-pass vertical spacing): add documentation for two-pass spacing

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

diff --git a/Documentation/user/page.itely b/Documentation/user/page.itely
index 4aa6f228c25e665c9f2b3bc8786217b9ca2174d2..ceaee2adef2bc9e3b9a2ece1644322632dedbe2d 100644 (file)
--- a/Documentation/user/page.itely
+++ b/Documentation/user/page.itely
@@ -160,6 +160,7 @@ Distance between the bottom-most music system and the page
 footer. Default is@tie{}4mm.
 
 @funindex page-top-space
+@item page-top-space
 Distance from the top of the printable area to the center of the first
 staff. This only works for staves which are vertically small. Big staves
 are set with the top of their bounding box aligned to the top of the
@@ -268,6 +269,13 @@ The relative importance of page (vertical) spacing and line (horizontal)
 spacing. High values will make page spacing more important. Default
 value is 1.
 
+@funindex auto-first-page-number
+@item auto-first-page-number
+The page breaking algorithm is affected by the first page number being
+odd or even.  If this variable is set to #t, the page breaking algorithm
+will decide whether to start with an odd or even number.  This will 
+result in the first page number remaining as is or being increased by one.
+
 @end table
 @end quotation
 
@@ -460,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
 
 
@@ -610,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
@@ -618,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