Update grand-replace script and add to buildscripts. Run grand-replace

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

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index fbeb4c9dfd380360bdc87b5938ff4bb028089ede..7531a858e739261dfdeaa9ab7cb9dcebee2a57b5 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.
 
 Increasing this will put systems whose bounding boxes almost touch
 farther apart.
 

+@funindex page-breaking-between-system-padding
+@item page-breaking-between-system-padding
+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
+fewer systems on each page.

 
 @funindex horizontal-shift
 @item horizontal-shift
 
 @funindex horizontal-shift
 @item horizontal-shift


@@ -550,6 +557,7 @@ The pairs
 * Page breaking::               
 * Optimal page breaking::       
 * Optimal page turning::        
 * Page breaking::               
 * Optimal page breaking::       
 * Optimal page turning::        

+* Minimal page breaking::        

 * Explicit breaks::             
 * Using an extra voice for breaks::  
 @end menu
 * Explicit breaks::             
 * Using an extra voice for breaks::  
 @end menu


@@ -600,13 +608,12 @@ This makes the following 28 measures (assuming 4/4 time) be broken every
 
 Internals: @internalsref{LineBreakEvent}.
 
 
 Internals: @internalsref{LineBreakEvent}.
 

-A linebreaking configuration can now be saved as a @code{.ly} file
+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}
 
 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
 
 Line breaks can only occur if there is a @q{proper} bar line.  A note
 @refbugs
 
 Line breaks can only occur if there is a @q{proper} bar line.  A note


@@ -619,22 +626,23 @@ c4 c2 c4 ~ \break % as does this break
 c4 c2 c4
 @end lilypond
 
 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
 
 
 @end lilypond
 
 

-

 @node Page breaking
 @subsection Page breaking
 
 @node Page breaking
 @subsection Page breaking
 


@@ -645,11 +653,14 @@ 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.
 
 from happening.  Of course, the @code{\pageBreak} command also forces
 a line break.
 

-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
-default is @code{ly:optimal-breaking}, but the value can be changed in
-the @code{\paper} block:
+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 three algorithms for computing page breaks,
+@code{ly:optimal-breaking}, @code{ly:page-turn-breaking} and
+@code{ly:minimal-breaking}. The default is @code{ly:optimal-breaking},
+but the value can be changed in the @code{\paper} block:

 
 @example
 \paper@{
 
 @example
 \paper@{


@@ -692,9 +703,10 @@ attempts to find a page breaking minimizing cramping and stretching, but with
 the additional restriction that it is only allowed to introduce page turns
 in specified places.
 
 the additional restriction that it is only allowed to introduce page turns
 in specified places.
 

-There are two steps to using this page breaking function. First, you must
-enable it in the @code{\paper} block. Then, you must tell the function
-where you would like to allow page breaks.
+There are two steps to using this page breaking function. First, you
+must enable it in the @code{\paper} block, as explained in @ref{Page
+breaking}. Then you must tell the function where you would like to allow
+page breaks.

 
 There are two ways to achieve the second step. First, you can specify each
 potential page turn manually, by inserting @code{\allowPageTurn} into your
 
 There are two ways to achieve the second step. First, you can specify each
 potential page turn manually, by inserting @code{\allowPageTurn} into your


@@ -740,11 +752,40 @@ 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.
 
 @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
 than one, they will interfere with each other.
 
 @refbugs
 
 There should only be one @code{Page_turn_engraver} in a score. If there is more
 than one, they will interfere with each other.
 

+@node Minimal page breaking
+@subsection Minimal page breaking
+
+@funindex ly:minimal-breaking
+
+The @code{ly:minimal-breaking} function performs minimal computations to
+calculate the page breaking: it fills a page with as many systems as
+possible before moving to the next one.  Thus, it may be prefered for
+scores with many pages, where the other page breaking functions could be
+too slow or memory demanding, or a lot of texts.  It is enabled using:
+
+@example
+\paper @{
+  #(define page-breaking ly:minimal-breaking)
+@}
+@end example

 
 @node Explicit breaks
 @subsection Explicit breaks
 
 @node Explicit breaks
 @subsection Explicit breaks


@@ -922,6 +963,61 @@ 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)}.
 
 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:
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+#(set-global-staff-size 14.0)
+
+\book {
+\paper {
+  ragged-last-bottom = ##f
+}
+
+\score {
+\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 lilypond

 
 @seealso
 
 
 @seealso
 


@@ -948,6 +1044,42 @@ Space between systems are controlled by four @code{\paper} variables,
 @}
 @end example
 
 @}
 @end example
 

+When only a couple of flat systems are placed on a page, the resulting
+vertical spacing may be non-eleguant: one system at the top of the page,
+and the other at the bottom, with a huge gap between them. To avoid this
+situation, the space added between the systems can be limited. This
+feature is activated by setting to @code{#t} the
+@code{page-limit-inter-system-space} variable in the @code{\paper}
+block. The paper variable @code{page-limit-inter-system-space-factor}
+determines how much the space can be increased: for instance, the value
+@code{1.3} means that the space can be 30% larger than what it would be
+on a ragged-bottom page.
+
+In the following example, if the inter system space were not limited,
+the second system of page 1 would be placed at the page bottom. By
+activating the space limitation, the second system is placed closer to
+the first one. By setting @code{page-limit-inter-system-space-factor} to
+@code{1}, the spacing would the same as on a ragged-bottom page, like
+the last one.
+
+@lilypond[verbatim]
+#(set-default-paper-size "a6")
+\book {
+  \paper {
+    page-limit-inter-system-space = ##t
+    page-limit-inter-system-space-factor = 1.3
+
+    oddFooterMarkup = \markup "page bottom"
+    evenFooterMarkup = \markup "page bottom"
+    oddHeaderMarkup = \markup \fill-line {
+      "page top" \fromproperty #'page:page-number-string }
+    evenHeaderMarkup = \markup \fill-line {
+      "page top" \fromproperty #'page:page-number-string }
+  }
+  \new Staff << \repeat unfold 4 { g'4 g' g' g' \break }
+                { s1*2 \pageBreak } >>
+}
+@end lilypond

 
 @node Explicit staff and system positioning
 @subsection Explicit staff and system positioning
 
 @node Explicit staff and system positioning
 @subsection Explicit staff and system positioning


@@ -1157,6 +1289,10 @@ passed to these different settings will avoid this.
 @node Two-pass vertical spacing
 @subsection Two-pass vertical spacing
 
 @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:
 
 In order to automatically stretch systems so that they should fill the
 space left on a page, a two-pass technique can be used:
 


@@ -1184,7 +1320,7 @@ music, using the @code{\scoreTweak} music function.
     \new Staff <<
       %% Include this score tweaks:
       \scoreTweak "scoreA"
     \new Staff <<
       %% Include this score tweaks:
       \scoreTweak "scoreA"

-      { \clef french c''1 \break c''1 } 
+      { \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 soprano g'1 g'1 }
     \new Staff { \clef mezzosoprano e'1 e'1 }