version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.11.61"
+@c \version "2.12.0"
@node Running LilyPond
@example
#(define output-suffix "violin")
-\book @{ @dots{} @}
+\score @{ @dots{} @}
#(define output-suffix "cello")
-\book @{ @dots{} @}
+\score @{ @dots{} @}
@end example
@noindent
@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 @var{filename}.ly}
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
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 from the LilyPond directory
- (typically @file{/usr/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
+ for a dump of the raw, internal Scheme-based drawing commands.
+
+@item null
+ do not output a printed score; has the same effect as @code{-dno-print-pages}.
@end table
Example: @code{lilypond -dbackend=svg @var{filename}.ly}
-@cindex output format, setting
-
@item preview
Generate an output file containing the titles and the first system
@item -o,--output=@var{FILE}
Set the default output file to @var{FILE}. The appropriate
-suffix will be added (i.e. @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
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
-
-@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}.
-
-If there are no changes to myfile.ly and file called myfile.ly.NEW
-is created, then myfile.ly is already updated.
-
@menu
+* Invoking convert-ly::
* Command line options for convert-ly::
* Problems with convert-ly::
@end menu
-@node Command line options for convert-ly
-@subsection Command line options for @command{convert-ly}
-
-@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.
+@node Invoking convert-ly
+@subsection Invoking @command{convert-ly}
-To upgrade LilyPond fragments in texinfo files, use
+@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 --from=... --to=... --no-version *.itely
+convert-ly -e myfile.ly
@end example
-To see the changes in the LilyPond syntax between two versions, use
+@noindent
+in the directory containing the file. This will upgrade
+@code{myfile.ly} in-place and preserve the original file in
+@code{myfile.ly~}.
+
+To convert all the input files in a directory together use
@example
-convert-ly --from=... --to=... -s
+convert-ly -e *.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
+Alternatively, if you want to specify a different name for the
+upgraded file, preserving the original file and name unchanged,
+use
@example
-for f in *.ly; do convert-ly -e $f; done;
+convert-ly myfile.ly > mynewfile.ly
@end example
+@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.
+
+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
+
+@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
projects / lilypond.git / blobdiff