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::
@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
@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
@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 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
@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
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
@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:
@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