Merge branch 'master' into translation

[lilypond.git] / Documentation / notation / input.itely

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index 2debffd3364d722d3066f6613314378d25949344..8c16fd32d71791fc99d9661607cd3ce304ffbeb6 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.
 
@@ -952,7 +965,7 @@ The default settings for @code{scoreTitleMarkup} as defined in
 
 @example
 scoreTitleMarkup = \markup @{ \column @{
-  \on-the-fly #print-all-headers @{ \bookTitleMarkup \hspace #1 @}
+  \on-the-fly \print-all-headers @{ \bookTitleMarkup \hspace #1 @}
   \fill-line @{
     \fromproperty #'header:piece
     \fromproperty #'header:opus
@@ -1112,7 +1125,7 @@ markup conditionally to header and footer text defined within the
 @example
 @code{variable} = @code{\markup} @{
   ...
-  @code{\on-the-fly}  #@var{procedure}  @var{markup}
+  @code{\on-the-fly}  \@var{procedure}  @var{markup}
   ...
 @}
 @end example
@@ -1160,7 +1173,7 @@ same layout by defining it as @code{\oddFooterMarkup}:
     evenHeaderMarkup = \markup \null
     oddFooterMarkup = \markup {
       \fill-line {
-        \on-the-fly #print-page-number-check-first
+        \on-the-fly \print-page-number-check-first
         \fromproperty #'page:page-number-string
       }
     }
@@ -1176,8 +1189,8 @@ Several @code{\on-the-fly} conditions can be combined with an
 @q{and} operation, for example,
 
 @example
-  @code{\on-the-fly #first-page}
-  @code{\on-the-fly #last-page}
+  @code{\on-the-fly \first-page}
+  @code{\on-the-fly \last-page}
   @code{@{ \markup ... \fromproperty #'header: ... @}}
 @end example
 
@@ -2588,11 +2601,11 @@ Here are a few sample bars of music set in Gonville:
 
 @c NOTE: these images are a bit big, but that's important
 @c       for the font comparison.  -gp
-@sourceimage{Gonville_after,,,}
+@sourceimage{Gonville_after,15cm,,}
 
 Here are a few sample bars of music set in LilyPond's Feta font:
 
-@sourceimage{Gonville_before,,,}
+@sourceimage{Gonville_before,15cm,,}
 
 @subsubheading Installation Instructions for MacOS
 
@@ -3027,11 +3040,10 @@ The final example in this section shows how this might be done.
 
 The minimum and maximum overall volume of MIDI dynamic markings is
 controlled by setting the properties @code{midiMinimumVolume} and
-@code{midiMaximumVolume} at the @code{Score} level.  These
-properties have an effect only on dynamic marks, so if they
-are to apply from the start of the score a dynamic mark must be
-placed there.  The fraction corresponding to each dynamic mark is
-modified with this formula
+@code{midiMaximumVolume} at the @code{Score} level.  These properties
+have an effect only at the start of a voice and on dynamic marks.  The
+fraction corresponding to each dynamic mark is modified with this
+formula
 
 @example
 midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
@@ -3085,9 +3097,7 @@ equalizer, which can enhance the quality of the MIDI output
 remarkably.
 
 In this example the volume of the clarinet is reduced relative
-to the volume of the flute.  There must be a dynamic
-mark on the first note of each instrument for this to work
-correctly.
+to the volume of the flute.
 
 @lilypond[verbatim,quote]
 \score {