Rewrote the description of \book blocks, trying to convey the idea

that these are almost never needed and clarifying when they are
needed.

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index a89b2585014c7541266975b3cd548c3bd02d01d4..a414fe7b44c3909cb42013f05212ea98d2de7229 100644 (file)
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -303,9 +303,8 @@ but it can also be used anywhere text is called in lilypond
 }
 @end lilypond
 
-Text can also be placed on its own, away from any @code{\score}
-block.  This is primarily used in a @code{\book} (see
-@ref{Multiple scores in a book}).
+A @code{\markup} command can also be placed on its own, away from any
+@code{\score} block, see @ref{Multiple scores in a book}.
 
 @lilypond[quote,ragged-right,verbatim]
 \markup{ Here is some text. }

diff --git a/Documentation/user/non-music.itely b/Documentation/user/non-music.itely
index 414548667f7120bf8d6188c77a789ac639d825ff..9fb163d7c0742c579367e23aabf8a6691fc6c5c1 100644 (file)
--- a/Documentation/user/non-music.itely
+++ b/Documentation/user/non-music.itely
@@ -98,23 +98,29 @@ and texts are entered with a @code{\markup} block,
 
 @funindex \book
 
-The movements and texts are combined together in a @code{\book} block,
-like
+All the movements and texts which appear in the same @code{.ly} file 
+will normally be typeset in the form of a single output file. 
 
 @example
-\book @{
-  \score @{
-    @var{..}
-  @}
-  \markup @{
-    @var{..}
-  @}
-  \score @{
-    @var{..}
-  @}
+\score @{
+  @var{..}
+@}
+\markup @{
+  @var{..}
+@}
+\score @{
+  @var{..}
 @}
 @end example
 
+However, if you want multiple output files from the same @code{.ly}
+file, then you can add multiple @code{\book} blocks, where each such
+@code{\book} block will result in a separate output. If you do not
+specify any @code{\book} block in the file, LilyPond will implicitly
+treat the full file as a single @code{\book} block, see @ref{File
+structure}. One important exception is within lilypond-book documents,
+where you explicitly have to add a @code{\book} block, otherwise only
+the first @code{\score} or @code{\markup} will appear in the output.
 
 The header for each piece of music can be put inside the @code{\score}
 block.  The @code{piece} name from the header will be printed before
@@ -123,25 +129,23 @@ each movement.  The title for the entire book can be put inside the
 the top of the file is inserted.
 
 @example
-\book @{
-  \header @{
-    title = "Eight miniatures"
-    composer = "Igor Stravinsky"
-  @}
-  \score @{
-    @dots{}
-    \header @{ piece = "Romanze" @}
-  @}
-  \markup @{
-     ..text of second verse..
-  @}
-  \markup @{
-     ..text of third verse..
-  @}
-  \score @{
-    @dots{}
-    \header @{ piece = "Menuetto" @}
-  @}
+\header @{
+  title = "Eight miniatures"
+  composer = "Igor Stravinsky"
+@}
+\score @{
+  @dots{}
+  \header @{ piece = "Romanze" @}
+@}
+\markup @{
+   ..text of second verse..
+@}
+\markup @{
+   ..text of third verse..
+@}
+\score @{
+  @dots{}
+  \header @{ piece = "Menuetto" @}
 @}
 @end example
 
@@ -221,8 +225,13 @@ contain only one music expression.
 @item
 A @code{\book} block logically combines multiple movements
 (i.e., multiple @code{\score} blocks) in one document.  If there are
-a number of @code{\scores}, a single output file will be created
-in which all movements are concatenated.
+a number of @code{\scores}, one output file will be created for
+each @code{\book} block, in which all corresponding movements are
+concatenated. The only reason to explicitly specify @code{\book} blocks
+in a @code{.ly} file is if you wish multiple output files from a single
+input file. One exception is within lilypond-book documents, where you
+explicitly have to add a @code{\book} block if you want more than a
+single @code{\score} or @code{\markup} in the same example.
 
 This behavior can be changed by setting the variable
 @code{toplevel-book-handler} at toplevel.  The default handler is
@@ -469,8 +478,8 @@ some pieces include a lot more information.
 @node Creating titles
 @subsection Creating titles
 
-Titles are created for each @code{\score} block, and over a
-@code{\book}.
+Titles are created for each @code{\score} block, and for the full input
+file (or @code{\book} block).
 
 The contents of the titles are taken from the @code{\header} blocks.
 The header block for a book supports the following
@@ -661,14 +670,13 @@ variables in the @code{\paper} block.  The init file
 @table @code
 @funindex bookTitleMarkup
 @item bookTitleMarkup
-  This is the title put over an entire @code{\book} block.  Typically,
-  it has the composer and the title of the piece
+  This is the title added at the top of the entire output document.
+Typically, it has the composer and the title of the piece
 
 @funindex scoreTitleMarkup
 @item scoreTitleMarkup
-  This is the title put over a @code{\score} block within a
-@code{\book}.  Typically, it has the name of the movement (@code{piece}
-field).
+  This is the title put over a @code{\score} block.  Typically, it has
+the name of the movement (@code{piece} field).
 
 @funindex oddHeaderMarkup
 @item oddHeaderMarkup

diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 35902501a902d93ed3ddba10811cc4a818da2022..658fc62dbae02bc59adb3161910a79a60aee0d2d 100644 (file)
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -229,8 +229,8 @@ book and the title of a piece). Default is@tie{}2mm.
 
 @funindex printallheaders
 @item printallheaders
-Setting this to #t will print all headers for each \score in a
-\book.  Normally only the piece and opus \headers are printed.
+Setting this to #t will print all headers for each \score in the
+output.  Normally only the piece and opus \headers are printed.
 
 @funindex systemSeparatorMarkup
 @item systemSeparatorMarkup