Guide, node Updating translation committishes..
@end ignore
-@c \version "2.12.0"
+@c \version "2.13.36"
@node General input and output
@chapter General input and output
@menu
* Structure of a score::
* Multiple scores in a book::
+* Multiple output files from one input file::
+* Output file names::
* File structure::
@end menu
block, and inside or outside the single music expression within a
@code{\score} block.
+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
+@file{fandangoforelephants.ly} will produce
+@file{fandangoforelephants.pdf}.
+
+(For more details about @code{\book} blocks, see
+@ref{Multiple scores in a book},
+@ref{Multiple output files from one input file} @ref{File structure}.)
@seealso
Learning Manual:
@}
@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,
+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.
@}
@end example
+@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}.
+
+When producing multiple files from a single source file, Lilypond
+ensures that none of the output files from any @code{\book} block
+overwrites the output file produced by a preceding @code{\book} from
+the same input file.
+
+It does this by adding a suffix to the output name for each
+@code{\book} which uses the default output file name derived from the
+input source file.
+
+The default behaviour is to append a version-number suffix for each
+name which may clash, so
+
+@example
+\book @{
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+@end example
+
+in source file @file{eightminiatures.ly}
+will produce
+
+@itemize
+@item
+@file{eightminiatures.pdf},
+@item
+@file{eightminiatures-1.pdf} and
+@item
+@file{eightminiatures-2.pdf}.
+@end itemize
+
+@node Output file names
+@subsection Output file names
+
+@funindex \bookOutputSuffix
+@funindex \bookOutputName
+
+Lilypond provides facilities to allow you to control what file names
+are used by the various back-ends when producing output files.
+
+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
+@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
+\book @{
+ \bookOutputSuffix "Romanze"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputSuffix "Menuetto"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputSuffix "Nocturne"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+@end example
+
+You can also specify a different output filename for @code{book} block,
+by using @code{\bookOutputName} declarations
+
+@example
+\book @{
+ \bookOutputName "Romanze"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputName "Menuetto"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+\book @{
+ \bookOutputName "Nocturne"
+ \score @{ @dots{} @}
+ \layout @{ @dots{} @}
+@}
+@end example
+
+The file above will produce these output files:
+
+@itemize
+@item
+@file{Romanze.pdf},
+@item
+@file{Menuetto.pdf} and
+@item
+@file{Nocturne.pdf}.
+@end itemize
+
+
@node File structure
@subsection File structure
A @code{.ly} file may contain any number of toplevel expressions, where a
toplevel expression is one of the following:
-@itemize @bullet
+@itemize
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
@menu
* Creating titles::
-* Custom titles::
+* Custom headers footers and titles::
* Reference to page numbers::
* Table of contents::
@end menu
@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
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
- }
- }
-}
-@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
@code{\include} statements are not interpreted until they have
been brought into the main file, so the file names they specify
must all be relative to the directory containing the main file,
-not the directory containing the included file. However,
+not the directory containing the included file. However,
this behavior can be changed by passing the option
@code{-drelative-includes} option at the command line
(or by adding @code{#(ly:set-option 'relative-includes #t)}
-at the top of the main input file). With @code{relative-includes}
+at the top of the main input file). With @code{relative-includes}
set, the path for each @code{\include} command will be taken
-relative to the file containing that command. This behavior is
+relative to the file containing that command. This behavior is
recommended and it will become the default behavior in a future
version of lilypond.
it skips all events, including tempo and instrument changes. You have
been warned.
-@lilypond[quote,fragment,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
@subsubheading Installation Instructions for MacOS
-Download and extract the zip file. Copy the @code{lilyfonts} directory
-to @file{@var{SHARE_DIR}/lilypond/current} see @rlearning{Other sources of information}.
+Download and extract the zip file. Copy the @code{lilyfonts}
+directory to @file{@var{SHARE_DIR}/lilypond/current}; for more
+information, see @rlearning{Other sources of information}.
Move the existing @code{fonts} directory to @code{fonts_orig} and
move the @code{lilyfonts} directory to @code{fonts}. Simply move
@code{fonts_orig} back to @code{fonts} to revert back to Feta.
@seealso
-@rlearning{Other sources of information}.
+Learning Manual: @rlearning{Other sources of information}.
@knownissues
If there is a @code{\midi} block in a @code{\score} with no
@code{\layout} block, only MIDI output will be produced. When
-notation is needed too, a @code{\layout} block must be also be
+notation is needed too, a @code{\layout} block must also be
present.
@example
are reflected in tempo changes in the MIDI output. This command
will normally result in the metronome mark being printed, but this
can be suppressed, see @ref{Metronome marks}. An alternative way
-of specifying the inital or overall MIDI tempo is described below,
+of specifying the initial or overall MIDI tempo is described below,
see @ref{MIDI block}.
Due to some limitations on Windows, the default extension for
-MIDI files on Windows is @code{.mid}. Other operating systems still
-use the extension @code{.midi}. If a different extension is preferred,
+MIDI files on Windows is @code{.mid}. Other operating systems still
+use the extension @code{.midi}. If a different extension is preferred,
insert the following line at the top-level of the input file,
before the start of any @code{\book}, @code{\bookpart} or @code{\score} blocks:
@end example
MIDI output is created only when a @code{\midi} block is included
-within a score block defined with a @code{\score} command. If it
-is placed within an explicitly instantiated score context (i.e.
-within a @code{\new Score} block) the file will fail. To solve
-this, enclose the @code{\new Score} and the @code{\midi} commands
-in a @code{\score} block.
+within a score block defined with a @code{\score} command.
@example
\score @{
- \new Score @{ @dots{}notes@dots{} @}
+ @{ @dots{}notes@dots{} @}
\midi @{ @}
@}
@end example
@itemize
@item Pitches
-@item Microtones (See @ref{Accidentals}. Rendering needs a
+@item Microtones (See @ref{Accidentals}. Rendering needs a
player that supports pitch bend.)
@item Chords entered as chord names
@item Rhythms entered as note durations, including tuplets