version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.12.0"
+
@node Running LilyPond
@chapter Running LilyPond
This chapter details the technicalities of running LilyPond.
@menu
-* Normal usage::
-* Command-line usage::
-* Error messages::
-* Updating files with convert-ly::
-* Reporting bugs::
+* Normal usage::
+* Command-line usage::
+* Error messages::
+* Updating files with convert-ly::
+* Reporting bugs::
@end menu
@node Normal usage
@section Normal usage
-Most users run LilyPond through a GUI; see @ruser{First steps} if
+Most users run LilyPond through a GUI; see @rlearning{First steps} if
you have not read this already.
By @q{command-line}, we mean the command line in the operating system.
Windows users might be more familiar with the terms @q{DOS shell} or
@q{command shell}; MacOS@tie{}X users might be more familiar with the terms
-@q{terminal} or @q{console}. They should also consult @ref{MacOS X
-on the command-line}.
+@q{terminal} or @q{console}. They should also consult @ref{Setup
+for MacOS X}.
Describing how to use this part of an operating system is outside the
scope of this manual; please consult other documentation on this topic
if you are unfamiliar with the command-line.
+@menu
+* Invoking lilypond::
+* Command line options for lilypond::
+* Environment variables::
+@end menu
-@subsection Invoking lilypond
+@node Invoking lilypond
+@subsection Invoking @command{lilypond}
-@cindex Invoking LilyPond
-@cindex command line options
+@cindex Invoking @command{lilypond}
+@cindex command line options for @command{lilypond}
@cindex options, command line
@cindex switches
extension is tried first. To read input from stdin, use a
dash (@code{-}) for @var{file}.
-When @file{filename.ly} is processed it will produce
-@file{filename.tex} as output (or @file{filename.ps} for PostScript
-output). If @file{filename.ly} contains more than one @code{\score}
-block, then the rest of the scores will be output in numbered files,
-starting with @file{filename-1.tex}. Several files can be specified;
+When @file{filename.ly} is processed it will produce @file{filename.ps}
+and @file{filename.pdf} as output. Several files can be specified;
they will each be processed independently. @footnote{The status of
GUILE is not reset after processing a @code{.ly} file, so be careful
not to change any system defaults from within Scheme.}
-In addition, the value of @code{output-suffix} will be inserted between
-the basename and the number. An input file containing
+If @file{filename.ly} contains more than one @code{\score}
+block, then the rest of the scores will be output in numbered files,
+starting with @file{filename-1.pdf}. In addition, the value of
+@code{output-suffix} will be inserted between the basename and the
+number. An input file containing
@example
#(define output-suffix "violin")
-\book @{ @dots{} @}
+\score @{ @dots{} @}
#(define output-suffix "cello")
-\book @{ @dots{} @}
+\score @{ @dots{} @}
@end example
@noindent
-will output @var{base}@file{-violin.ps} and
-@var{base}@file{-cello-1.ps}.
-
+will output @var{base}@file{-violin.pdf} and
+@var{base}@file{-cello-1.pdf}.
-@subsection Command line options
+@node Command line options for lilypond
+@subsection Command line options for @command{lilypond}
The following options are supported:
@item -f,--format=@var{format}
which formats should be written. Choices for @code{format} are
-@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+@code{svg}, @code{ps}, @code{pdf}, and @code{png}.
-Example: @code{lilypond -fpng filename.ly}
+Example: @code{lilypond -fpng @var{filename}.ly}
available.
@item paper-size
-This option sets the default paper-size,
+This option sets the default paper-size,
@example
-dpaper-size=\"letter\"
@end example
@noindent
Note that the string must be enclosed in escaped quotes ( @code{\"} ).
-
+@c Match " in previous line to help context-sensitive editors
@item safe
Do not trust the @code{.ly} input.
In safe mode, it is not possible to import LilyPond variables
into Scheme.
-safe does @emph{not} detect resource overuse. It is still possible to
+@code{-dsafe} does @emph{not} detect resource overuse. It is still possible to
make the program hang indefinitely, for example by feeding cyclic data
structures into the backend. Therefore, if using LilyPond on a
publicly accessible webserver, the process should be limited in both
compiled. The @code{--jail} is a more secure alternative, but
requires more work to set up.
+@cindex output format, setting
@item backend
the output format to use for the back-end. Choices for @code{format} are
@table @code
-@item tex
-for @TeX{} output, to be processed with La@TeX{}. If present, the file
-@file{file.textmetrics} is read to determine text extents.
-@item texstr
-dump text strings to @file{.texstr} file, which can be run through
-(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the
-extents of strings of text. @strong{Warning:} this functionality is
-currently missing due to heavy restructuring of the source code.
@item ps
- for PostScript.
@cindex PostScript output
+ for PostScript.
Postscript files include TTF, Type1 and OTF fonts. No subsetting of
these fonts is done. When using oriental character sets, this can
@file{EPS} file, without fonts, and as one collated @file{EPS} file with
all pages (systems) including fonts.
-This mode is used by default by lilypond-book.
+This mode is used by default by @command{lilypond-book}.
@item svg
- for SVG (Scalable Vector Graphics). This dumps every page as a separate
-@file{SVG} file, with embedded fonts.
@cindex SVG (Scalable Vector Graphics)
- You need a SVG viewer which supports embedded fonts, or a SVG
- viewer which is able to replace the embedded fonts with OTF fonts.
- Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape}
- (version 0.42 or later), after copying the OTF fonts in directory
- @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}.
+ for SVG (Scalable Vector Graphics).
+
+ This creates a single SVG file containing the entire music
+ output, with embedded fonts. You need an SVG viewer that
+ supports embedded fonts, or an SVG viewer that can replace the
+ embedded fonts with OTF fonts. Under UNIX, you may use
+ @uref{http://www.inkscape.org,Inkscape} (version 0.42 or later),
+ after copying the OTF fonts from the LilyPond directory
+ (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to
+ @file{~/.fonts/}.
+
@item scm
- for a dump of the raw, internal Scheme-based drawing commands.
@cindex Scheme dump
-@end table
+ for a dump of the raw, internal Scheme-based drawing commands.
-Example: @code{lilypond -dbackend=svg filename.ly}
+@item null
+ do not output a printed score; has the same effect as @code{-dno-print-pages}.
+@end table
-@cindex output format, setting
+Example: @code{lilypond -dbackend=svg @var{filename}.ly}
@item preview
Generate an output file containing the titles and the first system
@item -h,--help
Show a summary of usage.
-@item -H,--header=FIELD
-Dump a header field to file BASENAME.FIELD
+@item -H,--header=@var{FIELD}
+Dump a header field to file @file{BASENAME.@var{FIELD}}.
@item --include, -I=@var{directory}
Add @var{directory} to the search path for input files.
@item -o,--output=@var{FILE}
Set the default output file to @var{FILE}. The appropriate
-suffix will be added (ie @code{.pdf} for pdf, @code{.tex}
-for tex, etc).
+suffix will be added (e.g. @code{.pdf} for pdf)
@item --ps
Generate PostScript.
-@item --dvi
-Generate DVI files. In this case, the @TeX{} backend should be
-specified, i.e., @code{-dbackend=tex}.
-
@item --png
Generate pictures of each page, in PNG format. This implies
@code{--ps}. The resolution in DPI of the image may be set with
@strong{NO WARRANTY}!)
@end table
-
+@node Environment variables
@subsection Environment variables
where the error was found. For example,
@example
-test.ly:2:19: error: not a duration: 5:
- @{ c'4 e'5
- g' @}
+test.ly:2:19: error: not a duration: 5
+ @{ c'4 e'
+ 5 g' @}
@end example
These locations are LilyPond's best guess about where the warning or
@node Updating files with convert-ly
-@section Updating with @command{convert-ly}
+@section Updating files with @command{convert-ly}
@cindex Updating a LilyPond file
@cindex convert-ly
the program @command{convert-ly} can be used to deal with most of the
syntax changes between LilyPond versions.
-It uses @code{\version} statements in the input files to detect the
-old version number. In most cases, to upgrade your input file it is
-sufficient to run
+@menu
+* Invoking convert-ly::
+* Command line options for convert-ly::
+* Problems with convert-ly::
+@end menu
+
+@node Invoking convert-ly
+@subsection Invoking @command{convert-ly}
+
+@command{convert-ly} uses @code{\version} statements in the input
+file to detect the old version number. In most cases, to upgrade
+your input file it is sufficient to run
@example
convert-ly -e myfile.ly
@end example
@noindent
-MacOS@tie{}X users may execute this command under the menu entry
-@code{Compile > Update syntax}.
+in the directory containing the file. This will upgrade
+@code{myfile.ly} in-place and preserve the original file in
+@code{myfile.ly~}.
-If there are no changes to myfile.ly and file called myfile.ly.NEW
-is created, then myfile.ly is already updated.
-
-@subsection Command line options
-
-@command{convert-ly} always converts up to the last syntax change handled by
-it. This means that the @code{\version} number left in the file is
-usually lower than the version of @command{convert-ly} itself.
-
-To upgrade LilyPond fragments in texinfo files, use
+To convert all the input files in a directory together use
@example
-convert-ly --from=... --to=... --no-version *.itely
+convert-ly -e *.ly
@end example
-To see the changes in the LilyPond syntax between two versions, use
+Alternatively, if you want to specify a different name for the
+upgraded file, preserving the original file and name unchanged,
+use
@example
-convert-ly --from=... --to=... -s
+convert-ly myfile.ly > mynewfile.ly
@end example
-To upgrade many files at once, combine @code{convert-ly} with
-standard UNIX commands. This example will upgrade all @code{.ly}
-files in the current directory
+@command{convert-ly} always converts up to the last syntax change
+handled by it. This means that the @code{\version} number left in
+the file is usually lower than the version of @command{convert-ly}
+itself.
-@example
-for f in *.ly; do convert-ly -e $f; done;
-@end example
+The program will list the version numbers for which conversions
+have been made. If no version numbers are listed the file is
+already up to date.
+
+@noindent
+MacOS@tie{}X users may execute these commands under the menu entry
+@code{Compile > Update syntax}.
+
+Windows users should enter these commands in a Command Prompt window,
+which is usually found under
+@code{Start > Accessories > Command Prompt}.
+
+@node Command line options for convert-ly
+@subsection Command line options for @command{convert-ly}
In general, the program is invoked as follows:
@example
-convert-ly [@var{option}]@dots{} @var{file}@dots{}
+convert-ly [@var{option}]@dots{} @var{filename}@dots{}
@end example
@table @code
@item -e,--edit
-Do an inline edit of the input file. Overrides @code{--output}.
+Apply the conversions direct to the input file, modifying it
+in-place.
@item -f,--from=@var{from-patchlevel}
Set the version to convert from. If this is not set, @command{convert-ly}
will guess this, on the basis of @code{\version} strings in the file.
+E.g. @code{--from=2.10.25}
@item -n,--no-version
Normally, @command{convert-ly} adds a @code{\version} indicator
@item --to=@var{to-patchlevel}
Set the goal version of the conversion. It defaults to the latest
-available version.
+available version. E.g. @code{--to=2.12.2}
@item -h, --help
Print usage help.
@end table
+To upgrade LilyPond fragments in texinfo files, use
+
+@example
+convert-ly --from=... --to=... --no-version *.itely
+@end example
+
+To see the changes in the LilyPond syntax between two versions, use
-@menu
-* Problems with convert-ly::
-@end menu
+@example
+convert-ly --from=... --to=... -s
+@end example
@node Problems with convert-ly
@subsection Problems with @code{convert-ly}
+When running convert-ly in a Command Prompt window under Windows
+on a file which has spaces in the filename or in the path to it,
+it is necessary to surround the entire input file name with three
+(!) sets of double quotes:
+
+@example
+convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
+@end example
+
+If the simple @command{convert-ly -e *.ly} command fails because the
+expanded command line becomes too long, the @command{convert-ly}
+command may be placed in a loop instead. This example for UNIX
+will upgrade all @code{.ly} files in the current directory
+
+@example
+for f in *.ly; do convert-ly -e $f; done;
+@end example
+
+In the Windows Command Prompt window the corresponding command is
+
+@example
+for %x in (*.ly) do convert-ly -e """%x"""
+@end example
+
Not all language changes are handled. Only one output option can be
specified. Automatically updating scheme and LilyPond scheme
interfaces is quite unlikely; be prepared to tweak scheme code
@uref{http://lilypond.org/web/devel/participating/bugs}
-Please construct submit @ruser{Minimal examples}, of bug reports. We do not
+Please construct and submit minimal examples of bugs in reports. We do not
have the resources to investigate reports which are not as small as possible.
projects / lilypond.git / blobdiff