From c45e558168db739e8971f1b50c940069ed5e1ed9 Mon Sep 17 00:00:00 2001
From: Nicolas Sceaux <nicolas.sceaux@free.fr>
Date: Sun, 16 Nov 2008 23:18:38 +0100
Subject: [PATCH] Nested book parts: documentation

---
 Documentation/topdocs/NEWS.tely  | 23 +++++++++++++++++++++
 Documentation/user/input.itely   | 33 +++++++++++++++++++++++++++++-
 Documentation/user/spacing.itely | 35 ++++++++++++++++++++++++++++++++
 3 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/Documentation/topdocs/NEWS.tely b/Documentation/topdocs/NEWS.tely
index 5f640098d2..34f3fd0bc7 100644
--- a/Documentation/topdocs/NEWS.tely
+++ b/Documentation/topdocs/NEWS.tely
@@ -62,6 +62,29 @@ which scares away people.
 
 @end ignore
 
+@item
+@code{\bookpart} blocks may be used to split a book into several parts,
+separated by a page break, in order to ease the page breaking, or to use
+different @code{\paper} settings in different parts.
+
+@example
+\bookpart @{
+  \header @{
+    title = "Book title"
+    subtitle = "First part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+\bookpart @{
+  \header @{
+    subtitle = "Second part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+@end example
+
 @item
 Nested contexts of the same type are now allowed.
 This deprecates @code{InnerStaffGroup} and @code{InnerChoirStaff}.
diff --git a/Documentation/user/input.itely b/Documentation/user/input.itely
index cd0bd8b165..e02cd494c2 100644
--- a/Documentation/user/input.itely
+++ b/Documentation/user/input.itely
@@ -185,6 +185,30 @@ the top of the file is inserted.
 @}
 @end example
 
+@funindex \bookpart
+
+Pieces of music may be grouped into book parts using @code{\bookpart}
+blocks.  Book parts are separated by a page break, and can start with a
+title, like the book itself, by specifying a @code{\header} block.
+
+@example
+\bookpart @{
+  \header @{
+    title = "Book title"
+    subtitle = "First part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+\bookpart @{
+  \header @{
+    subtitle = "Second part"
+  @}
+  \score @{ @dots{} @}
+  @dots{}
+@}
+@end example
+
 @node File structure
 @subsection File structure
 
@@ -194,6 +218,7 @@ the top of the file is inserted.
 @funindex \header
 @funindex \score
 @funindex \book
+@funindex \bookpart
 
 A @code{.ly} file may contain any number of toplevel expressions, where a
 toplevel expression is one of the following:
@@ -238,6 +263,11 @@ changed by setting the variable @code{toplevel-book-handler} at
 toplevel.  The default handler is defined in the init file
 @file{../scm/@/lily@/.scm}.
 
+@item
+A @code{\bookpart} block.  A book may be divided into several parts,
+using @code{\bookpart} blocks, in order to ease the page breaking,
+or to use different @code{\paper} settings in different parts. 
+
 @item
 A compound music expression, such as
 @example
@@ -348,7 +378,8 @@ some pieces include a lot more information.
 @subsection Creating titles
 
 Titles are created for each @code{\score} block, as well as for the full
-input file (or @code{\book} block).
+input file (or @code{\book} block) and book parts (created by
+@code{\bookpart} blocks).
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following
diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 9ade001b4e..baabf804dc 100644
--- 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
 
-- 
2.39.2