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 92669a28dc1fda9b216d04e6ccc6fb438791405e..f7234ac0980f97c476fdfbebf491deffc6ccdebd 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 

-@c \version "2.11.61"
+@c \version "2.11.64"

 
 @ignore
 GDP TODO list
 
 @ignore
 GDP TODO list


@@ -107,9 +107,9 @@ within which music can be printed.
 
 Two functions are available for changing the paper size:
 @code{set-default-paper-size} and @code{set-paper-size}.
 
 Two functions are available for changing the paper size:
 @code{set-default-paper-size} and @code{set-paper-size}.

-@code{set-default-paper-size} may be placed in a @code{\paper}
-block or in the toplevel scope, and @code{set-paper-size} must be
-placed in a @code{\paper} block:
+@code{set-default-paper-size} must be placed in the toplevel
+scope, and @code{set-paper-size} must be placed in a @code{\paper}
+block:

 
 @example
 #(set-default-paper-size "a4")
 
 @example
 #(set-default-paper-size "a4")


@@ -443,6 +443,16 @@ 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.  Default: @code{##f}.
 
 will result in the first page number remaining as is or being
 increased by one.  Default: @code{##f}.
 

+@ignore
+
+FIXME: this variable is used, but I don't know what it does. -pm
+@item blank-after-score-page-force
+@funindex blank-after-score-page-force
+
+Default: @code{2}.
+
+@end ignore
+

 @item blank-last-page-force
 @funindex blank-last-page-force
 
 @item blank-last-page-force
 @funindex blank-last-page-force
 


@@ -457,22 +467,12 @@ score.  This is not used by @code{ly:optimal-breaking} since it will
 never consider blank pages in the middle of a score.  Default:
 @code{5}.
 
 never consider blank pages in the middle of a score.  Default:
 @code{5}.
 

-@item blank-after-score-page-force
-@funindex blank-after-score-page-force
-
-TODO.  Default: @code{2}.
-

 @item first-page-number
 @funindex first-page-number
 
 The value of the page number on the first page.  Default:
 @code{#1}.
 
 @item first-page-number
 @funindex first-page-number
 
 The value of the page number on the first page.  Default:
 @code{#1}.
 

-@item packed
-@funindex packed
-
-TODO
-

 @item page-breaking-between-system-padding
 @funindex page-breaking-between-system-padding
 
 @item page-breaking-between-system-padding
 @funindex page-breaking-between-system-padding
 


@@ -485,7 +485,7 @@ page-breaker will put fewer systems on each page.  Default: unset.
 @item page-count
 @funindex page-count
 
 @item page-count
 @funindex page-count
 

-TODO
+The number of pages to be used for a score.  Default: unset.

 
 @item page-limit-inter-system-space
 @funindex page-limit-inter-system-space
 
 @item page-limit-inter-system-space
 @funindex page-limit-inter-system-space


@@ -552,6 +552,9 @@ page.  Default: @code{##t}.
 Pieces that amply fill two pages or more should have this set to
 true.
 
 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
 
 @item ragged-right
 @funindex ragged-right
 


@@ -561,8 +564,8 @@ systems end at their natural horizontal length.  Default:
 
 If the score has only one system, the default value is @code{##t}.
 
 
 If the score has only one system, the default value is @code{##t}.
 

-@item systemSeparatorMarkup
-@funindex systemSeparatorMarkup
+@item system-separator-markup
+@funindex system-separator-markup

 
 A markup object that is inserted between systems.  This is often
 used for orchestral scores.  Default: unset.
 
 A markup object that is inserted between systems.  This is often
 used for orchestral scores.  Default: unset.


@@ -577,7 +580,7 @@ default,  for example
     \relative { c1 \break c1 }
   }
   \paper {
     \relative { c1 \break c1 }
   }
   \paper {

-    systemSeparatorMarkup = \slashSeparator
+    system-separator-markup = \slashSeparator

   }
 }
 @end lilypond
   }
 }
 @end lilypond


@@ -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.
 
 @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
 
 
 @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.
 
 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
 @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:
 
 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
 @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}.
 
 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
 @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.
 
 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:
 @end lilypond
 
 Some points to consider: