Merge branch 'lilypond/translation'

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

diff --git a/Documentation/notation/input.itely b/Documentation/notation/input.itely
index c764dce6ca80d5d7ed32b8c4762fb8f036321f4f..d82845e8f14f02f9b4ebd63d798a79b430cc383d 100644 (file)
--- a/Documentation/notation/input.itely
+++ b/Documentation/notation/input.itely
@@ -29,7 +29,7 @@ rather than specific notation.
 @section Input structure
 
 The main format of input for LilyPond are text files.  By convention,
 @section Input structure
 
 The main format of input for LilyPond are text files.  By convention,

-these files end with @code{.ly}.
+these files end with @file{@/.ly}.

 
 @menu
 * Structure of a score::
 
 @menu
 * Structure of a score::


@@ -106,8 +106,8 @@ Remember that even in a file containing only a @code{\score} block, it
 is implicitly enclosed in a \book block.  A \book block in a source
 file produces at least one output file, and by default the name of the
 output file produced is derived from the name of the input file, so
 is implicitly enclosed in a \book block.  A \book block in a source
 file produces at least one output file, and by default the name of the
 output file produced is derived from the name of the input file, so

-@file{fandangoforelephants.ly} will produce
-@file{fandangoforelephants.pdf}.
+@file{fandangoforelephants@/.ly} will produce
+@file{fandangoforelephants@/.pdf}.

 
 (For more details  about @code{\book} blocks, see
 @ref{Multiple scores in a book},
 
 (For more details  about @code{\book} blocks, see
 @ref{Multiple scores in a book},


@@ -146,7 +146,7 @@ and texts are entered with a @code{\markup} block,
 
 @funindex \book
 
 
 @funindex \book
 

-All the movements and texts which appear in the same @code{.ly} file
+All the movements and texts which appear in the same @file{@/.ly} file

 will normally be typeset in the form of a single output file.
 
 @example
 will normally be typeset in the form of a single output file.
 
 @example


@@ -219,11 +219,13 @@ title, like the book itself, by specifying a @code{\header} block.
 @node Multiple output files from one input file
 @subsection Multiple output files from one input file
 
 @node Multiple output files from one input file
 @subsection Multiple output files from one input file
 

-If you want multiple output files from the same .ly file, then you can
-add multiple @code{\book} blocks, where each such \book block will
-result in a separate output file. If you do not specify any
-@code{\book} block in the input file, LilyPond will implicitly treat
-the whole file as a single \book block, see @ref{File structure}.
+If you want multiple output files from the same @file{@/.ly} file,
+then you can add multiple @code{\book} blocks, where each
+such \book block will result in a separate output file.
+If you do not specify any @code{\book} block in the
+input file, LilyPond will implicitly treat the whole
+file as a single \book block, see
+@ref{File structure}.

 
 When producing multiple files from a single source file, Lilypond
 ensures that none of the output files from any @code{\book} block
 
 When producing multiple files from a single source file, Lilypond
 ensures that none of the output files from any @code{\book} block


@@ -252,16 +254,16 @@ name which may clash, so
 @}
 @end example
 
 @}
 @end example
 

-in source file @file{eightminiatures.ly}
+in source file @file{eightminiatures@/.ly}

 will produce
 
 @itemize
 @item
 will produce
 
 @itemize
 @item

-@file{eightminiatures.pdf},
+@file{eightminiatures@/.pdf},

 @item
 @item

-@file{eightminiatures-1.pdf} and
+@file{eightminiatures@/-1@/.pdf} and

 @item
 @item

-@file{eightminiatures-2.pdf}.
+@file{eightminiatures@/-2@/.pdf}.

 @end itemize
 
 @node Output file names
 @end itemize
 
 @node Output file names


@@ -277,8 +279,8 @@ In the previous section, we saw how Lilypond prevents name-clashes when
 producing several ouputs from a single source file.  You also have the
 ability to specify your own suffixes for each @code{\book} block, so
 for example you can produce files called
 producing several ouputs from a single source file.  You also have the
 ability to specify your own suffixes for each @code{\book} block, so
 for example you can produce files called

-@file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
-and @file{eightminiatures-Nocturne.pdf} by adding a
+@file{eightminiatures@/-Romanze@/.pdf}, @file{eightminiatures@/-Menuetto@/.pdf}
+and @file{eightminiatures@/-Nocturne@/.pdf} by adding a

 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
 
 @example
 @code{\bookOutputSuffix} declaration inside each @code{\book} block.
 
 @example


@@ -324,11 +326,11 @@ The file above will produce these output files:
 
 @itemize
 @item
 
 @itemize
 @item

-@file{Romanze.pdf},
+@file{Romanze@/.pdf},

 @item
 @item

-@file{Menuetto.pdf} and
+@file{Menuetto@/.pdf} and

 @item
 @item

-@file{Nocturne.pdf}.
+@file{Nocturne@/.pdf}.

 @end itemize
 
 
 @end itemize
 
 


@@ -343,7 +345,7 @@ The file above will produce these output files:
 @funindex \book
 @funindex \bookpart
 
 @funindex \book
 @funindex \bookpart
 

-A @code{.ly} file may contain any number of toplevel expressions, where a
+A @file{@/.ly} file may contain any number of toplevel expressions, where a

 toplevel expression is one of the following:
 
 @itemize
 toplevel expression is one of the following:
 
 @itemize


@@ -369,7 +371,7 @@ A @code{\score} block.  This score will be collected with other
 toplevel scores, and combined as a single @code{\book}.
 This behavior can be changed by setting the variable
 @code{toplevel-score-handler} at toplevel.  The default handler is
 toplevel scores, and combined as a single @code{\book}.
 This behavior can be changed by setting the variable
 @code{toplevel-score-handler} at toplevel.  The default handler is

-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{@/.@/./@/scm/@/lily@/.scm}.

 
 @item
 A @code{\book} block logically combines multiple movements
 
 @item
 A @code{\book} block logically combines multiple movements


@@ -377,14 +379,14 @@ A @code{\book} block logically combines multiple movements
 are a number of @code{\score}s, one output file will be created
 for each @code{\book} block, in which all corresponding movements
 are concatenated.  The only reason to explicitly specify
 are a number of @code{\score}s, 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 to create
+@code{\book} blocks in a @file{@/.ly} file is if you wish to create

 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 defined in the init file
 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 defined in the init file

-@file{../@/scm/@/lily@/.scm}.
+@file{@/.@/./@/scm/@/lily@/.scm}.

 
 @item
 A @code{\bookpart} block.  A book may be divided into several parts,
 
 @item
 A @code{\bookpart} block.  A book may be divided into several parts,


@@ -418,7 +420,7 @@ music expression will be translated into
 
 This behavior can be changed by setting the variable
 @code{toplevel-music-handler} at toplevel.  The default handler is
 
 This behavior can be changed by setting the variable
 @code{toplevel-music-handler} at toplevel.  The default handler is

-defined in the init file @file{../@/scm/@/lily@/.scm}.
+defined in the init file @file{@/.@/./@/scm/@/lily@/.scm}.

 
 @item
 A markup text, a verse for example
 
 @item
 A markup text, a verse for example


@@ -514,7 +516,7 @@ some pieces include a lot more information.
 
 @menu
 * Creating titles::
 
 @menu
 * Creating titles::

-* Custom titles::
+* Custom headers footers and titles::

 * Reference to page numbers::
 * Table of contents::
 @end menu
 * Reference to page numbers::
 * Table of contents::
 @end menu


@@ -706,12 +708,12 @@ Headers may be completely removed by setting them to false.
 @end example
 
 
 @end example
 
 

-@node Custom titles
-@subsection Custom titles
+@node Custom headers footers and titles
+@subsection Custom headers, footers, and titles

 
 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file
 
 A more advanced option is to change the definitions of the following
 variables in the @code{\paper} block.  The init file

-@file{../@/ly/@/titling@/-init@/.ly} lists the default layout.
+@file{@/.@/./@/ly/@/titling@/-init@/.ly} lists the default layout.

 
 @table @code
 @funindex bookTitleMarkup
 
 @table @code
 @funindex bookTitleMarkup


@@ -759,16 +761,48 @@ the name of the movement (@code{piece} field).
 The following definition will put the title flush left, and the
 composer flush right on a single line.
 
 The following definition will put the title flush left, and the
 composer flush right on a single line.
 

-@verbatim
-\paper {
-  bookTitleMarkup = \markup {
-   \fill-line {
+@example
+\paper @{
+  bookTitleMarkup = \markup @{
+   \fill-line @{

      \fromproperty #'header:title
      \fromproperty #'header:composer
      \fromproperty #'header:title
      \fromproperty #'header:composer

-   }
-  }
-}
-@end verbatim
+   @}
+  @}
+@}
+@end example
+
+The header and footer are created by the functions
+@code{make-header} and @code{make-footer}, defined in
+@code{\paper}.  The default implementations are in
+@file{ly/@/paper@/-defaults@/-init@/.ly} and
+@file{ly/@/titling@/-init@/.ly}.
+
+This example centers page numbers at the bottom of every page.
+
+@example
+\paper @{
+  print-page-number = ##t
+  print-first-page-number = ##t
+  oddHeaderMarkup = \markup \fill-line @{ " " @}
+  evenHeaderMarkup = \markup \fill-line @{ " " @}
+  oddFooterMarkup = \markup @{
+    \fill-line @{
+      \bold \fontsize #3
+      \on-the-fly #print-page-number-check-first
+      \fromproperty #'page:page-number-string
+    @}
+  @}
+  evenFooterMarkup = \markup @{
+    \fill-line @{
+      \bold \fontsize #3
+      \on-the-fly #print-page-number-check-first
+      \fromproperty #'page:page-number-string
+    @}
+  @}
+@}
+@end example
+

 
 @node Reference to page numbers
 @subsection Reference to page numbers
 
 @node Reference to page numbers
 @subsection Reference to page numbers


@@ -925,7 +959,7 @@ tocAct =
 
 
 @seealso
 
 
 @seealso

-Init files: @file{../@/ly/@/toc@/-init@/.ly}.
+Init files: @file{@/.@/./@/ly/@/toc@/-init@/.ly}.

 
 
 @predefined
 
 
 @predefined


@@ -961,7 +995,7 @@ another file, use
 @end example
 
 The line @code{\include "otherfile.ly"} is equivalent to pasting the
 @end example
 
 The line @code{\include "otherfile.ly"} is equivalent to pasting the

-contents of @file{otherfile.ly} into the current file at the place
+contents of @file{otherfile@/.ly} into the current file at the place

 where the @code{\include} appears.  For example, in a large
 project you might write separate files for each instrument part
 and create a @qq{full score} file which brings together the
 where the @code{\include} appears.  For example, in a large
 project you might write separate files for each instrument part
 and create a @qq{full score} file which brings together the


@@ -977,7 +1011,7 @@ specifying just the file name after the @code{\include} command.
 Files in other locations may be included by giving either a full
 path reference or a relative path reference (but use the UNIX
 forward slash, /, rather than the DOS/Windows back slash, \, as the
 Files in other locations may be included by giving either a full
 path reference or a relative path reference (but use the UNIX
 forward slash, /, rather than the DOS/Windows back slash, \, as the

-directory separator.)  For example, if @file{stuff.ly} is located
+directory separator.)  For example, if @file{stuff@/.ly} is located

 one directory higher than the current working directory, use
 
 @example
 one directory higher than the current working directory, use
 
 @example


@@ -1012,9 +1046,9 @@ version of lilypond.
 Files can also be included from a directory in a search path
 specified as an option when invoking LilyPond from the command
 line.  The included files are then specified using just their
 Files can also be included from a directory in a search path
 specified as an option when invoking LilyPond from the command
 line.  The included files are then specified using just their

-file name.  For example, to compile @file{main.ly} which includes
+file name.  For example, to compile @file{main@/.ly} which includes

 files located in a subdirectory called @file{parts} by this method,
 files located in a subdirectory called @file{parts} by this method,

-cd to the directory containing @file{main.ly} and enter
+cd to the directory containing @file{main@/.ly} and enter

 
 @example
 lilypond --include=parts main.ly
 
 @example
 lilypond --include=parts main.ly


@@ -1029,11 +1063,11 @@ and in main.ly write
 @end example
 
 Files which are to be included in many scores may be placed in
 @end example
 
 Files which are to be included in many scores may be placed in

-the LilyPond directory @file{../ly}.  (The location of this
+the LilyPond directory @file{@/.@/./ly}.  (The location of this

 directory is installation-dependent - see
 @rlearning{Other sources of information}).  These files can then
 be included simply by naming them on an @code{\include} statement.
 directory is installation-dependent - see
 @rlearning{Other sources of information}).  These files can then
 be included simply by naming them on an @code{\include} statement.

-This is how the language-dependent files like @file{english.ly} are
+This is how the language-dependent files like @file{english@/.ly} are

 included.
 
 LilyPond includes a number of files by default when you start
 included.
 
 LilyPond includes a number of files by default when you start


@@ -1526,14 +1560,12 @@ This property is also used to control output to the MIDI file.  Note that
 it skips all events, including tempo and instrument changes.  You have
 been warned.
 
 it skips all events, including tempo and instrument changes.  You have
 been warned.
 

-@lilypond[quote,relative=1,ragged-right,verbatim]
-\relative c'' {
-  c8 d
-  \set Score.skipTypesetting = ##t
-  e8 e e e e e e e
-  \set Score.skipTypesetting = ##f
-  c8 d b bes a g c2
-}
+@lilypond[quote,relative=2,ragged-right,verbatim]
+c8 d
+\set Score.skipTypesetting = ##t
+e8 e e e e e e e
+\set Score.skipTypesetting = ##f
+c8 d b bes a g c2

 @end lilypond
 
 In polyphonic music, @code{Score.skipTypesetting} will affect all
 @end lilypond
 
 In polyphonic music, @code{Score.skipTypesetting} will affect all


@@ -1789,7 +1821,7 @@ tempoWholesPerMinute = #(ly:make-moment 270 8)
 Context definitions follow precisely the same syntax as those
 within a @code{\layout} block.  Translation modules for sound are
 called performers.  The contexts for MIDI output are defined in
 Context definitions follow precisely the same syntax as those
 within a @code{\layout} block.  Translation modules for sound are
 called performers.  The contexts for MIDI output are defined in

-@file{../@/ly/@/performer@/-init@/.ly},
+@file{@/.@/./@/ly/@/performer@/-init@/.ly},

 see @rlearning{Other sources of information}.
 For example, to remove the effect of dynamics
 from the MIDI output, insert the following lines in the
 see @rlearning{Other sources of information}.
 For example, to remove the effect of dynamics
 from the MIDI output, insert the following lines in the


@@ -1922,7 +1954,7 @@ Dynamic marks are translated to a fixed fraction of the available
 MIDI volume range.  The default fractions range from 0.25 for
 @notation{ppppp} to 0.95 for @notation{fffff}.  The set of dynamic
 marks and the associated fractions can be seen in
 MIDI volume range.  The default fractions range from 0.25 for
 @notation{ppppp} to 0.95 for @notation{fffff}.  The set of dynamic
 marks and the associated fractions can be seen in

-@file{../@/scm/@/midi.scm}, see @rlearning{Other sources of information}.
+@file{@/.@/./@/scm/@/midi@/.scm}, see @rlearning{Other sources of information}.

 This set of fractions may be changed or extended by providing a
 function which takes a dynamic mark as its argument and returns the
 required fraction, and setting
 This set of fractions may be changed or extended by providing a
 function which takes a dynamic mark as its argument and returns the
 required fraction, and setting


@@ -1962,7 +1994,7 @@ found, or calls the default function otherwise.
 Alternatively, if the whole table of fractions needs to be
 redefined, it would be better to use the
 @notation{default-dynamic-absolute-volume} procedure in
 Alternatively, if the whole table of fractions needs to be
 redefined, it would be better to use the
 @notation{default-dynamic-absolute-volume} procedure in

-@file{../@/scm/@/midi.scm} and the associated table as a model.
+@file{@/.@/./@/scm/@/midi@/.scm} and the associated table as a model.

 The final example in this section shows how this might be done.
 
 @unnumberedsubsubsec Overall MIDI volume
 The final example in this section shows how this might be done.
 
 @unnumberedsubsubsec Overall MIDI volume


@@ -2073,7 +2105,7 @@ If the MIDI minimum and maximum volume properties are not set
 LilyPond will, by default, apply a small degree of equalization
 to a few instruments.  The instruments and the equalization
 applied are shown in the table @notation{instrument-equalizer-alist}
 LilyPond will, by default, apply a small degree of equalization
 to a few instruments.  The instruments and the equalization
 applied are shown in the table @notation{instrument-equalizer-alist}

-in @file{../@/scm/@/midi.scm}.
+in @file{@/.@/./@/scm/@/midi@/.scm}.

 
 This basic default equalizer can be replaced by setting
 @code{instrumentEqualizer} in the @code{Score} context to a new
 
 This basic default equalizer can be replaced by setting
 @code{instrumentEqualizer} in the @code{Score} context to a new


@@ -2083,7 +2115,7 @@ maximum volumes to be applied to that instrument.  This replacement
 is done in the same way as shown for resetting the
 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
 The default equalizer, @notation{default-instrument-equalizer}, in
 is done in the same way as shown for resetting the
 @code{dynamicAbsoluteVolumeFunction} at the start of this section.
 The default equalizer, @notation{default-instrument-equalizer}, in

-@file{../@/scm/@/midi.scm} shows how such a procedure might be written.
+@file{@/.@/./@/scm/@/midi@/.scm} shows how such a procedure might be written.

 
 The following example sets the relative flute and clarinet volumes
 to the same values as the previous example.
 
 The following example sets the relative flute and clarinet volumes
 to the same values as the previous example.