Merge branch 'master' of /home/lilydev/git/lily/

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

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 9ade001b4e56676b2b55b162997c931da5be3164..f7234ac0980f97c476fdfbebf491deffc6ccdebd 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -552,6 +552,9 @@ page.  Default: @code{##t}.
 Pieces that amply fill two pages or more should have this set to
 true.
 
+It also affects the last page of book parts, ie parts of a book created
+with @code{\bookpart} blocks.
+
 @item ragged-right
 @funindex ragged-right
 
@@ -931,6 +934,38 @@ The old page breaking algorithm is called
 @code{optimal-page-breaks}.  If you are having trouble with the new page
 breakers, you can enable the old one as a workaround.
 
+@funindex \bookpart
+
+When a book has many scores and pages, the page breaking problem may be
+difficult to solve, requiring large processing time and memory.  To ease
+the page breaking process, @code{\bookpart} blocks are used to divide
+the book into several parts: the page breaking occurs separately on each
+part.  Different page breaking functions may also be used in different
+book parts.
+
+@example
+\bookpart @{
+  \header @{
+    subtitle = "Preface"
+  @}
+  \paper @{
+     %% In a part consisting mostly of text,
+     %% ly:minimal-breaking may be prefered
+     #(define page-breaking ly:minimal-breaking)
+  @}
+  \markup @{ @dots{} @}
+  @dots{}
+@}
+\bookpart @{
+  %% In this part, consisting of music, the default optimal
+  %% page breaking function is used.
+  \header @{
+    subtitle = "First movement"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+@end example
 
 @predefined
 
@@ -1468,20 +1503,29 @@ example @code{NonMusicalPaperColumn} overrides with the special
 To understand how each of these different settings work, we begin
 by looking at an example that includes no overrides at all.
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      s1 * 6 \break
-      s1 * 6 \break
-      s1 * 6 \break
-    }
-    \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new Staff {
-    \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+@c \book { } is required in these examples to ensure the spacing
+@c overrides can be seen between systems. -np
+
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          s1*5 \break
+          s1*5 \break
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
   }
->>
+}
 @end lilypond
 
 This score isolates line- and page-breaking information in a dedicated
@@ -1495,26 +1539,32 @@ the vertical startpoint of each system explicitly, we can set
 the @code{Y-offset} pair in the @code{line-break-system-details}
 attribute of the @code{NonMusicalPaperColumn} grob:
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 0))
-      s1 * 6 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 40))
-      s1 * 6 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 80))
-      s1 * 6 \break
-    }
-    \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new Staff {
-    \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 0))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 40))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 80))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
   }
->>
+}
 @end lilypond
 
 Note that @code{line-break-system-details} takes an associative list of
@@ -1527,29 +1577,35 @@ explicitly, we can also set the vertical startpoint of each staff
 within each system manually.  We do this using the @code{alignment-offsets}
 subproperty of @code{line-break-system-details}.
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 20)
-          (alignment-offsets . (0 -15)))
-      s1 * 6 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 60)
-          (alignment-offsets . (0 -15)))
-      s1 * 6 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-        #'line-break-system-details #'((Y-offset . 100)
-          (alignment-offsets . (0 -15)))
-      s1 * 6 \break
-    }
-    \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new Staff {
-    \repeat unfold 18 { d'4 d'4 d'4 d'4 }
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 20)
+                                           (alignment-offsets . (0 -15)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 60)
+                                           (alignment-offsets . (0 -15)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 100)
+                                           (alignment-offsets . (0 -15)))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new Staff {
+        \repeat unfold 15 { d'4 d' d' d' }
+      }
+    >>
   }
->>
+}
 @end lilypond
 
 Note that here we assign two different values to the
@@ -1562,34 +1618,36 @@ additional spacing parameters (including, for example, a corresponding
 every system and every staff.  Finally, note that @code{alignment-offsets}
 specifies the vertical positioning of staves but not of staff groups.
 
-@lilypond[quote,ragged-right]
-\new Score <<
-  \new Staff <<
-    \new Voice {
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-      #'line-break-system-details #'((Y-offset . 0)
-        (alignment-offsets . (0 -30 -40)))
-      s1 * 6 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-      #'line-break-system-details #'((Y-offset . 60)
-        (alignment-offsets . (0 -10 -20)))
-      s1 * 6 \break
-      \overrideProperty #"Score.NonMusicalPaperColumn"
-      #'line-break-system-details #'((Y-offset . 100)
-        (alignment-offsets . (0 -10, -40)))
-      s1 * 6 \break
-    }
-    \new Voice { \repeat unfold 18 { c'4 c'4 c'4 c'4 } }
-  >>
-  \new StaffGroup <<
-    \new Staff {
-      \repeat unfold 18 { d'4 d'4 d'4 d'4 }
-    }
-    \new Staff {
-      \repeat unfold 18 { e'4 e'4 e'4 e'4 }
-    }
-  >>
->>
+@lilypond[quote]
+\header { tagline = ##f }
+\paper { left-margin = 0\mm }
+\book {
+  \score {
+    <<
+      \new Staff <<
+        \new Voice {
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 0)
+                                           (alignment-offsets . (0 -30 -40)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 60)
+                                           (alignment-offsets . (0 -10 -20)))
+          s1*5 \break
+          \overrideProperty #"Score.NonMusicalPaperColumn"
+            #'line-break-system-details #'((Y-offset . 100)
+                                           (alignment-offsets . (0 -10 -40)))
+          s1*5 \break
+        }
+        \new Voice { \repeat unfold 15 { c'4 c' c' c' } }
+      >>
+      \new StaffGroup <<
+        \new Staff { \repeat unfold 15 { d'4 d' d' d' } }
+        \new Staff { \repeat unfold 15 { e'4 e' e' e' } }
+      >>
+    >>
+  }
+}
 @end lilypond
 
 Some points to consider: