The LilyPond input syntax is routinely changed to simplify it or improve
it in different ways. As a side effect of this, the LilyPond interpreter
often is no longer compatible with older input files. To remedy this,
-the program @command{convert-ly} can be used to deal with most of the
-syntax changes between LilyPond versions.
+the program @command{convert-ly} can be used for upgrading files
+to newer versions of LilyPond.
@menu
* Why does the syntax change?::
name to @code{print-all-headers}. Fortunately, this change can be
automated with our @command{convert-ly} tool.
-Unfortunately, @code{convert-ly} cannot handle all input changes.
+Unfortunately, @command{convert-ly} cannot handle all input changes.
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- displaying the French word for
Christmas was entered as @code{No\"el}. But in LilyPond
@c keep "-matching straight in fancy editors
2.6 and above, the special @code{ë} must be entered directly into
-the LilyPond file as an UTF-8 character. @code{convert-ly} cannot
+the LilyPond file as an UTF-8 character. @command{convert-ly} cannot
change all the LaTeX special characters into UTF-8 characters; you
must manually update your old LilyPond input files.
+The conversion rules of @command{convert-ly} work using text pattern
+matching and replacement rather than a thorough understanding of
+LilyPond. This has several consequences:
+@itemize @bullet
+@item
+The reliability of the conversion depends on the quality of each
+applied rule set and on the complexity of the respective change.
+Sometimes conversions may require manual fixes, so the old version
+should be kept available for comparison.
+@item
+Only conversions to newer formats are possible: there are no rule
+sets for downgrading. So the main working copy of a LilyPond file
+should only be upgraded when older versions of LilyPond no longer
+need to be supported. Version control systems such as Git might
+help with maintaining multiple versions.
+@item
+LilyPond and Scheme themselves are quite robust against creatively
+placed and omitted spaces, but the rules used by
+@command{convert-ly} tend to make some stylistic assumptions.
+Following the style used in the manuals is the safest bet for
+painless upgrades, particularly as the manuals themselves are
+upgraded using @command{convert-ly}.
+@end itemize
+
@node Invoking convert-ly
@section Invoking @command{convert-ly}
convert-ly [@var{option}]@dots{} @var{filename}@dots{}
@end example
-
The following options can be given:
@table @code
-@item -e,--edit
+@item -d, --diff-version-update
+increase the @code{\version} string only if the file has actually
+been changed. In that case, the version header will correspond to
+the version after the last actual change. An unstable version
+number will be rounded up to the next stable version number unless
+that would exceed the target version number. Without this option,
+the version will instead reflect the last @emph{attempted}
+conversion.
+
+@item -e, --edit
Apply the conversions direct to the input file, modifying it
-in-place.
+in-place. The original file is renamed as @file{myfile.ly~}. This
+backup file may be a hidden file on some operating systems.
-@item -f,--from=@var{from-patchlevel}
+@item -b, --backup-numbered
+When used with the @samp{-e} option, number the backup files so that
+no previous version is overwritten. The backup files may be hidden
+on some operating systems.
+
+@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. @option{--from=2.10.25}
-@item -n,--no-version
+@item -h, --help
+Print usage help.
+
+@item -l @var{loglevel}, --loglevel=@var{loglevel}
+Set the output verbosity to @var{loglevel}. Possible values, in upper
+case, are @code{PROGRESS} (the default), @code{NONE}, @code{WARNING},
+@code{ERROR} and @code{DEBUG}.
+
+@item -n, --no-version
Normally, @command{convert-ly} adds a @code{\version} indicator
to the output. Specifying this option suppresses this.
@item -s, --show-rules
Show all known conversions and exit.
-@item --to=@var{to-patchlevel}
-Set the goal version of the conversion. It defaults to the latest
-available version. E.g. @option{--to=2.12.2}
-
-@item -h, --help
-Print usage help.
+@item -t, --to=@var{to-patchlevel}
+Explicitly set which @code{\version} to convert to, otherwise the
+default is the most current value. It must be higher than the
+starting version.
-@item -l @var{loglevel}, --loglevel=@var{loglevel}
-Set the output verbosity to @var{loglevel}. Possible values are @code{NONE},
-@code{ERROR}, @code{WARNING}, @code{PROGRESS} (default) and @code{DEBUG}.
+@example
+convert-ly --to=2.14.1 myfile.ly
+@end example
@end table
To upgrade LilyPond fragments in texinfo files, use
@example
-convert-ly --from=... --to=... --no-version *.itely
+convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
@end example
To see the changes in the LilyPond syntax between two versions, use
@example
-convert-ly --from=... --to=... -s
+convert-ly --from=@dots{} --to=@dots{} -s
@end example
projects / lilypond.git / blobdiff