@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
@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.
à vo -- cê uma can -- ção legal
}
-\relative {
+\relative c' {
c2 d e f g f e
}
\addlyrics { \bulgarian }
@funindex \displayLilyMusic
Displaying a music expression in LilyPond notation can be
-done using the music function @code{\displayLilyMusic}. For example,
+done with the music function @code{\displayLilyMusic} but only when
+using the command line. For example,
@example
@{
@{ a,4 cis e fis g @}
@end example
-By default, LilyPond will print these messages to the console along
-with all the other messages. To split up these messages and save
-the results of @code{\display@{STUFF@}}, redirect the output to
-a file.
-
-@c TODO What happens under Windows?
+By default, LilyPond will print these messages to the console
+along with all the other LilyPond compilation messages. To split
+up these messages and save the results of @code{\display@{STUFF@}},
+redirect the output to a file.
@example
lilypond file.ly >display.txt
@node Replacing the notation font
@subsection Replacing the notation font
-FIXME stub.
+Gonville is an alternative to the Feta font used in LilyPond and can
+be downloaded from:
+@example
+@uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
+@end example
+
+Here are a few sample bars of music set in Gonville:
+
+@c NOTE: these images are a bit big, but that's important
+@c for the font comparison. -gp
+@sourceimage{Gonville_after,,,}
+
+Here are a few sample bars of music set in LilyPond's Feta font:
+
+@sourceimage{Gonville_before,,,}
+
+@subsubheading Installation Instructions for MacOS
+
+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
+Learning Manual: @rlearning{Other sources of information}.
+
+@knownissues
+
+Gonville cannot be used to typeset @q{Ancient Music} notation. Please
+refer to the author's website for more information on this and other
+specifics including licensing of Gonville.
@node MIDI output
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:
@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
projects / lilypond.git / blobdiff