Fix "make top-doc" (and thus "make dist") on clean build tree

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

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index f05f0fafeae6cdb00e0f719d83ae69deec8526bd..d9cb825ee37c2719c643e96c49364ffb612f261c 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -353,9 +353,11 @@ toplevel expression is one of the following:
 @item
 An output definition, such as @code{\paper}, @code{\midi}, and
 @code{\layout}.  Such a definition at the toplevel changes the default
 @item
 An output definition, such as @code{\paper}, @code{\midi}, and
 @code{\layout}.  Such a definition at the toplevel changes the default

-book-wide settings.  If more than one such definition of
-the same type is entered at the top level any definitions in the later
-expressions have precedence.
+book-wide settings.  If more than one such definition of the same type
+is entered at the top level the definitions are combined, but in
+conflicting situations the later definitions take precedence.  For
+details of how this affects the @code{\layout} block see
+@ref{The \layout block}.

 
 @item
 A direct scheme expression, such as
 
 @item
 A direct scheme expression, such as


@@ -508,6 +510,9 @@ after the entire command.
 Learning Manual:
 @rlearning{How LilyPond input files work}.
 
 Learning Manual:
 @rlearning{How LilyPond input files work}.
 

+Notation Reference:
+@ref{The \layout block}.
+

 
 @node Titles and headers
 @section Titles and headers
 
 @node Titles and headers
 @section Titles and headers


@@ -635,47 +640,80 @@ Notation Reference:
 @node Default layout of book and score title blocks
 @unnumberedsubsubsec Default layout of book and score title blocks
 
 @node Default layout of book and score title blocks
 @unnumberedsubsubsec Default layout of book and score title blocks
 

-The layout and formatting of title blocks are controlled by two
-@code{\paper} variables; @code{bookTitleMarkup} for the main
-@code{\header} title block and @code{scoreTitleMarkup} for individual
-@code{\header} blocks within a @code{\score}.
-
-@lilypond[papersize=a6,quote,verbatim,noragged-right]
-\header {
-  % The following fields are centered
-  dedication = "Dedication"
-  title = "Title"
-  subtitle = "Subtitle"
-  subsubtitle = "Subsubtitle"
-  instrument = "Instrument"
-
-  % The following fields are left-aligned on the left side
-  poet = "Poet"
-  meter = "Meter"
-
-  % The following fields are right-aligned on the right side
-  composer = "Composer"
-  arranger = "Arranger"
-}
+This example demonstrates all @code{\header} variables:

 
 

-\score {
-  { s1 }
+@lilypond[papersize=a7landscape,quote,verbatim,noragged-right]
+\book {

   \header {
   \header {

-    % The following fields are placed at opposite ends of the same line
-    piece = "Piece"
-    opus = "Opus"
+      % The following fields are centered
+    dedication = "Dedication"
+    title = "Title"
+    subtitle = "Subtitle"
+    subsubtitle = "Subsubtitle"
+      % The following fields are evenly spread on one line
+      % the field "instrument" also appears on following pages
+    instrument = \markup \with-color #green "Instrument"
+    poet = "Poet"
+    composer = "Composer"
+      % The following fields are placed at opposite ends of the same line
+    meter = "Meter"
+    arranger = "Arranger"
+      % The following fields are centered at the bottom
+    tagline = "tagline goes at the bottom of the last page"
+    copyright = "copyright goes at the bottom of the first page"
+  }
+  \score {
+    { s1 }
+    \header {
+        % The following fields are placed at opposite ends of the same line
+      piece = "Piece 1"
+      opus = "Opus 1"
+    }
+  }
+  \score {
+    { s1 }
+    \header {
+        % The following fields are placed at opposite ends of the same line
+      piece = "Piece 2 on the same page"
+      opus = "Opus 2"
+    }
+  }
+  \pageBreak
+  \score {
+    { s1 }
+    \header {
+        % The following fields are placed at opposite ends of the same line
+      piece = "Piece 3 on a new page"
+      opus = "Opus 3"
+    }

   }
 }
 @end lilypond
 
   }
 }
 @end lilypond
 

-@c Is the bit about \null markups true? -mp
+Note that
+
+@itemize
+@item
+The instrument name will be repeated on every page.

 
 

+@item
+Only @code{piece} and @code{opus} are printed in a @code{\score}
+when the paper variable @code{print-all-headers} is set to
+@code{##f} (the default).
+
+@item
+@c Is the bit about \null markups true? -mp

 Text fields left unset in a @code{\header} block are replaced with
 @code{\null} markups so that the space is not wasted.
 
 Text fields left unset in a @code{\header} block are replaced with
 @code{\null} markups so that the space is not wasted.
 

+@item

 The default settings for @code{scoreTitleMarkup} place the @code{piece}
 and @code{opus} text fields at opposite ends of the same line.
 
 The default settings for @code{scoreTitleMarkup} place the @code{piece}
 and @code{opus} text fields at opposite ends of the same line.
 

+@end itemize
+
+To change the default layout see @ref{Custom layout for title blocks}.
+

 @cindex breakbefore
 
 Use the @code{breakbefore} variable inside a @code{\header} block
 @cindex breakbefore
 
 Use the @code{breakbefore} variable inside a @code{\header} block


@@ -705,6 +743,7 @@ Learning Manual:
 @rlearning{How LilyPond input files work},
 
 Notation Reference:
 @rlearning{How LilyPond input files work},
 
 Notation Reference:

+@ref{Custom layout for title blocks},

 @ref{File structure}.
 
 Installed Files:
 @ref{File structure}.
 
 Installed Files:


@@ -814,17 +853,23 @@ Notation Reference:
 @node Custom layout for title blocks
 @unnumberedsubsubsec Custom layout for title blocks
 
 @node Custom layout for title blocks
 @unnumberedsubsubsec Custom layout for title blocks
 

+@cindex bookTitleMarkup
+@cindex scoreTitleMarkup
+@funindex bookTitleMarkup
+@funindex scoreTitleMarkup
+

 @code{\markup} commands in the @code{\header} block are useful for
 simple text formatting, but they do not allow precise control over the
 placement of titles.  To customize the placement of the text fields,
 @code{\markup} commands in the @code{\header} block are useful for
 simple text formatting, but they do not allow precise control over the
 placement of titles.  To customize the placement of the text fields,

-use either or both of the following @code{\paper} variables:
+change either or both of the following @code{\paper} variables:

 
 @itemize
 @item @code{bookTitleMarkup}
 @item @code{scoreTitleMarkup}
 @end itemize
 
 
 @itemize
 @item @code{bookTitleMarkup}
 @item @code{scoreTitleMarkup}
 @end itemize
 

-These markup variables are discussed in
+The placement of titles when using the default values of these
+@code{\markup} variables is shown in the examples in

 @ref{Default layout of book and score title blocks}.
 
 The default settings for @code{scoreTitleMarkup} as defined in
 @ref{Default layout of book and score title blocks}.
 
 The default settings for @code{scoreTitleMarkup} as defined in


@@ -981,6 +1026,49 @@ variables:
 @item @code{evenFooterMarkup}
 @end itemize
 
 @item @code{evenFooterMarkup}
 @end itemize
 

+@cindex markup, conditional
+@cindex on-the-fly
+@funindex \on-the-fly
+
+The @code{\markup} command @code{\on-the-fly} can be used to add
+markup conditionally to header and footer text defined within the
+@code{\paper} block, using the following syntax:
+
+@example
+@code{variable} = @code{\markup} @{
+  ...
+  @code{\on-the-fly}  #@var{procedure}  @var{markup}
+  ...
+@}
+@end example
+
+The @var{procedure} is called each time the @code{\markup} command
+in which it appears is evaluated.  The @var{procedure} should test
+for a particular condition and interpret (i.e. print) the
+@var{markup} argument if and only if the condition is true.
+
+A number of ready-made procedures for testing various conditions are
+provided:
+
+@quotation
+@multitable {print-page-number-check-first-----} {should this page be printed-----}
+
+@headitem  Procedure name           @tab  Condition tested
+
+@item print-page-number-check-first @tab  should this page number be printed?
+@item create-page-number-stencil    @tab  'print-page-numbers true?
+@item print-all-headers             @tab  'print-all-headers true?
+@item first-page                    @tab  first page in the book?
+@item (on-page nmbr)                @tab  page number = nmbr?
+@item last-page                     @tab  last page in the book?
+@item not-first-page                @tab  not first page in the book?
+@item part-first-page               @tab  first page in the book part?
+@item part-last-page                @tab  last page in the book part?
+@item not-single-page               @tab  pages in book part > 1?
+
+@end multitable
+@end quotation
+

 The following example centers page numbers at the bottom of every
 page.  First, the default settings for @code{oddHeaderMarkup} and
 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}
 The following example centers page numbers at the bottom of every
 page.  First, the default settings for @code{oddHeaderMarkup} and
 @code{evenHeaderMarkup} are removed by defining each as a @emph{null}


@@ -1009,11 +1097,25 @@ same layout by defining it as @code{\oddFooterMarkup}:
 }
 @end lilypond
 
 }
 @end lilypond
 

+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{@{ \markup ... \fromproperty #'header: ... @}}
+@end example
+
+determines if the output is a single page.
+

 @seealso
 Notation Reference:
 @ref{Title blocks explained},
 @ref{Default layout of book and score title blocks}.
 
 @seealso
 Notation Reference:
 @ref{Title blocks explained},
 @ref{Default layout of book and score title blocks}.
 

+Installed Files:
+@file{../ly/titling-init.ly}.
+

 
 @node Creating footnotes
 @subsection Creating footnotes
 
 @node Creating footnotes
 @subsection Creating footnotes


@@ -1294,7 +1396,7 @@ command, either at top-level or inside music.  This label can then be
 referred to in a markup, to get the number of the page where the marked
 point is placed, using the @code{\page-ref} markup command.
 
 referred to in a markup, to get the number of the page where the marked
 point is placed, using the @code{\page-ref} markup command.
 

-@lilypond[verbatim]
+@lilypond[verbatim,papersize=a8landscape]

 \header { tagline = ##f }
 \book {
   \label #'firstScore
 \header { tagline = ##f }
 \book {
   \label #'firstScore


@@ -1412,7 +1514,7 @@ tocAct =
    (add-toc-item! 'tocActMarkup text))
 @end verbatim
 
    (add-toc-item! 'tocActMarkup text))
 @end verbatim
 

-@lilypond[line-width=11.0\cm]
+@lilypond[line-width=10.0\cm]

 \header { tagline = ##f }
 \paper {
   tocActMarkup = \markup \large \column {
 \header { tagline = ##f }
 \paper {
   tocActMarkup = \markup \large \column {


@@ -1440,7 +1542,7 @@ tocAct =
 
 Dots can be added to fill the line between an item and its page number:
 
 
 Dots can be added to fill the line between an item and its page number:
 

-@lilypond[verbatim,quote]
+@lilypond[verbatim,line-width=10.0\cm]

 \header { tagline = ##f }
 \paper {
   tocItemMarkup = \tocItemWithDotsMarkup
 \header { tagline = ##f }
 \paper {
   tocItemMarkup = \tocItemWithDotsMarkup


@@ -2231,7 +2333,7 @@ what was entered.  This is convenient for checking the music; octaves
 that are off or accidentals that were mistyped stand out very much
 when listening to the MIDI output.
 
 that are off or accidentals that were mistyped stand out very much
 when listening to the MIDI output.
 

-Standard MIDI oputput is somewhat crude; optionally, an enhanced and
+Standard MIDI output is somewhat crude; optionally, an enhanced and

 more realistic MIDI output is available by means of
 @ref{The Articulate script}.
 
 more realistic MIDI output is available by means of
 @ref{The Articulate script}.