Merge branch 'master' of ssh://jomand@git.sv.gnu.org/srv/git/lilypond into topic...

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

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 1606e96f74e2cf4376b838028f42c042dbf264af..ac85a6c214f74c5589168492c38ced496343d2b3 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -213,7 +213,7 @@ farther apart.
 
 @funindex page-breaking-between-system-padding
 @item between-system-padding
-This variable, if set, tricks the page breaker into thinking that
+This variable 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
@@ -607,6 +607,11 @@ This makes the following 28 measures (assuming 4/4 time) be broken every
 
 Internals: @internalsref{LineBreakEvent}.
 
+A linebreaking configuration can 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
 
@@ -620,22 +625,23 @@ c4 c2 c4 ~ \break % as does this break
 c4 c2 c4
 @end lilypond
 
-To allow line breaks on such bar lines, the
-@code{Forbid_line_break_engraver} can be removed from @code{Voice}
-context, like so
+This can be avoided by removing the @code{Forbid_line_break_engraver}
+and adding the line breaks in another voice:
 
-
-@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
-\new Voice \with {
-  \remove "Forbid_line_break_engraver"
-} {
-  c4 c2 c2 \break   % now the break is allowed
-  c2 c4
-}
+@lilypond[quote,ragged-right,verbatim]
+\new Staff <<
+  \new Voice \with {
+    \remove Forbid_line_break_engraver
+  } {
+    c'4 c'2 c'2 c'2 c'4
+  }
+  \new Voice {
+    s1 \break s1
+  }
+>>
 @end lilypond
 
 
-
 @node Page breaking
 @subsection Page breaking
 
@@ -646,6 +652,9 @@ inserted at a bar line.  These commands force and forbid a page-break
 from happening.  Of course, the @code{\pageBreak} command also forces
 a line break.
 
+The @code{\pageBreak} and @code{\noPageBreak} commands may also be
+inserted at top-level, between scores and top-level markups.
+
 Page breaks are computed by the @code{page-breaking} function.
 LilyPond provides two algorithms for computing page
 breaks, @code{ly:optimal-breaking} and @code{ly:page-turn-breaking}. The
@@ -741,6 +750,19 @@ page turns if the repeat is very short. If you set the context property
 @code{minimumRepeatLengthForPageTurn} then the @code{Page_turn_engraver} will
 only allow turns in repeats whose duration is longer than this value.
 
+The page turning commands, @code{\pageTurn}, @code{\noPageTurn} and
+@code{\allowPageTurn}, may also be used at top-level, between scores and
+top-level markups.
+
+@refcommands
+
+@funindex \pageTurn
+@code{\pageTurn}
+@funindex \noPageTurn
+@code{\noPageTurn}
+@funindex \allowPageTurn
+@code{\allowPageTurn}
+
 @refbugs
 
 There should only be one @code{Page_turn_engraver} in a score. If there is more
@@ -883,6 +905,7 @@ staves inside a system.
 * Vertical spacing inside a system::  
 * Vertical spacing between systems::  
 * Explicit staff and system positioning::  
+* Two-pass vertical spacing::
 * Vertical collision avoidance::  
 @end menu
 
@@ -1208,6 +1231,66 @@ 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
+
+Warning: two-pass vertical spacing is deprecated and will be removed in
+a future version of LilyPond. Systems are now stretched automatically
+in a single pass. See @ref{Vertical spacing inside a system}.
+
+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