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
@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::
* 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:
@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
@}
@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 @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
+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
@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 @bullet
+@itemize
@item
An output definition, such as @code{\paper}, @code{\midi}, and
@code{\layout}. Such a definition at the toplevel changes the default
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
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
-@file{../@/scm/@/lily@/.scm}.
+@file{../scm/lily.scm}.
@item
A @code{\bookpart} block. A book may be divided into several parts,
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
@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
-@file{../@/ly/@/titling@/-init@/.ly} lists the default layout.
+@file{../ly/titling-init.ly} lists the default layout.
@table @code
@funindex bookTitleMarkup
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
}
@end lilypond
+Dots can be added to fill the line between an item and its page number:
+
+@lilypond[verbatim,quote]
+\header { tagline = ##f }
+\paper {
+ tocItemMarkup = \tocItemWithDotsMarkup
+}
+
+\book {
+ \markuplines \table-of-contents
+ \tocItem \markup { Allegro }
+ \tocItem \markup { Largo }
+ \markup \null
+}
+@end lilypond
+
@seealso
-Init files: @file{../@/ly/@/toc@/-init@/.ly}.
+Init files: @file{../ly/toc-init.ly}.
@predefined
@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.
@menu
* Using variables::
* Using tags::
+* Using global settings::
@end menu
@node Using variables
@end ignore
+@node Using global settings
+@unnumberedsubsubsec Using global settings
+
+@cindex include-settings
+
+Global settings can be included from a separate file:
+
+@example
+lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
+@end example
+
+Groups of settings such as page size, font or type face can be stored
+in separate files. This allows different editions from the same score
+as well as standard settings to be applied to many scores, simply by
+specifying the proper settings file.
+
+This technique also works well with the use of style sheets, as
+discussed in @rlearning{Style sheets}.
+
+@seealso
+Learning Manual:
+@rlearning{Organizing pieces with variables},
+@rlearning{Style sheets}.
+
+Notation Reference:
+@ref{Including LilyPond files}.
+
@node Text encoding
@subsection Text encoding
}
\addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
-\markup { "Copyright 2008--2010" \char ##x00A9 }
+\markup { "Copyright 2008--2011" \char ##x00A9 }
@end lilypond
@cindex copyright sign
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
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
+more realistic MIDI output is available by means of
+@ref{The Articulate script}.
+
@c TODO Check this
The midi output allocates a channel for each staff, and one for global
settings. Therefore the midi file should not have more than 15 staves
* Repeats in MIDI::
* Controlling MIDI dynamics::
* Percussion in MIDI::
+* The Articulate script::
@end menu
@node Creating MIDI files
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:
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
@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
@cindex MIDI, chord names
@cindex Rhythms in MIDI
@cindex MIDI, Rhythms
+@cindex Articlulate scripts
+@cindex MIDI, articulations
+@cindex articulations in MIDI
+@cindex trills in MIDI
+@cindex turns in MIDI
+@cindex rallentando in MIDI
+@cindex accelerando in MIDI
@c TODO etc
The following items of notation are reflected in the MIDI output:
@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
@item Lyrics
@end itemize
+Using @ref{The Articulate script}, a number of items are added to the
+above list:
+
+@itemize
+@item Articulations (slurs, staccato, etc)
+@item Trills, turns
+@item Rallentando and accelerando
+@end itemize
+
+
@unnumberedsubsubsec Unsupported in MIDI
@c TODO index as above
-The following items of notation have no effect on the MIDI output:
+The following items of notation have no effect on the MIDI output,
+unless you use @ref{The Articulate script}:
@itemize
@item Rhythms entered as annotations, e.g. swing
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
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
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
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.
Because the general MIDI standard does not contain rim shots, the
sidestick is used for this purpose instead.
+@node The Articulate script
+@subsection The Articulate script
+
+A more realistic MIDI output is possible when using the Articulate
+script. It tries to take articulations (slurs, staccato, etc) into
+account, by replacing notes with sequential music of suitably
+time-scaled note plus skip. It also tries to unfold trills turns
+etc., and take rallentando and accelerando into account.
+
+To use the Articulate script, you have to include it at the top of
+your input file,
+
+@example
+\include "articulate.ly"
+@end example
+
+and in the @code{\score} section do
+
+@example
+\unfoldRepeats \articulate <<
+ all the rest of the score...
+>>
+@end example
+
+After altering your input file this way, the visual output is heavily
+altered, but the standard @code{\midi} block will produce a better
+MIDI file.
+
+Although not essential for the Articulate script to work, you may want
+to insert the @code{\unfoldRepeats} command as it appears in the
+example shown above as it enables performing abbreviatures such as
+@notation{trills}.
+
+@knownissues
+Articulate shortens chords and some music (esp. organ music) could
+sound worse.
projects / lilypond.git / blobdiff