Doc: Augment section about titles (3103)

 - add Book Titles and explain why they might not be printed

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index 09d4e898794c915e0b5e1d035d7a32d1189f07c2..651a8267fd0f822306d03470a2c5e6f3b4794977 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -548,17 +548,17 @@ some pieces include a lot more information.
 
 Each @code{\book} block in a single input file produces a separate
 output file, see @ref{File structure}.  Within each output file
-two types of titling areas are provided: @emph{Bookpart Titles} at
-the beginning of each bookpart and @emph{Score Titles} at the
-beginning of each score.
+three types of titling areas are provided: @emph{Book Titles} at the
+beginning of each book, @emph{Bookpart Titles} at the beginning of
+each bookpart and @emph{Score Titles} at the beginning of each score.
 
 Values of titling fields such as @code{title} and @code{composer}
 are set in @code{\header} blocks.  (For the syntax of @code{\header}
 blocks and a complete list of the fields available by default see
-@ref{Default layout of bookpart and score titles}).  Both Bookpart
-Titles and Score Titles can contain the same fields, although by
-default the fields in Score Titles are limited to @code{piece} and
-@code{opus}.
+@ref{Default layout of bookpart and score titles}).  Book Titles,
+Bookpart Titles and Score Titles can all contain the same fields,
+although by default the fields in Score Titles are limited to
+@code{piece} and @code{opus}.
 
 @code{\header} blocks may be placed in four different places to form
 a descending hierarchy of @code{\header} blocks:
@@ -589,7 +589,15 @@ by a value set lower in the hierarchy, so:
 @itemize
 
 @item
- A Bookpart Title is derived from fields set at the top of the input
+A Book Title is derived from fields set at the top of the input file,
+modified by fields set in the @code{\book} block.  The resulting
+fields are used to print the Book Title for that book, providing that
+there is other material which generates a page at the start of the
+book, before the first bookpart.  A single @code{\pageBreak} will
+suffice.
+
+@item
+A Bookpart Title is derived from fields set at the top of the input
 file, modified by fields set in the @code{\book} block, and further
 modified by fields set in the @code{\bookpart} block.  The resulting
 values are used to print the Bookpart Title for that bookpart.
@@ -791,8 +799,13 @@ To change the default layout see @ref{Custom layout for titles}.
 
 @cindex breakbefore
 
+If a @code{\book} block starts immediately with a @code{\bookpart}
+block, no Book Title will be printed, as there is no page on which
+to print it.  If a Book Title is required, begin the @code{\book}
+block with some markup material or a @code{\pageBreak} command.
+
 Use the @code{breakbefore} variable inside a @code{\header} block
-that is itself in a @code{\score} block, to make the top-level
+that is itself in a @code{\score} block, to make the higher-level
 @code{\header} block titles appear on the first page on their own, with
 the music (defined in the @code{\score} block) starting on the next.