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 svg
@cindex SVG (Scalable Vector Graphics)
- for SVG (Scalable Vector Graphics). This dumps every page as a separate
-@file{SVG} file, with embedded fonts.
- 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
@cindex Scheme dump
for a dump of the raw, internal Scheme-based drawing commands.
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