X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fusage%2Fupdating.itely;h=ad92a834e35db8307521379f9dc4bd9789e6ce09;hb=15b9d5a33fe02826075a651e96ae21d2ae66a680;hp=5b75dfb558880599d761e83bdde5f8449b309cd9;hpb=7eb9c626943a47141ec2cc5fad7723f69e04bbd2;p=lilypond.git diff --git a/Documentation/usage/updating.itely b/Documentation/usage/updating.itely index 5b75dfb558..ad92a834e3 100644 --- a/Documentation/usage/updating.itely +++ b/Documentation/usage/updating.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.13.36" +@c \version "2.16.0" @node Updating files with convert-ly @@ -20,8 +20,8 @@ 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?:: @@ -54,16 +54,40 @@ with existing scores)? In this case, we decided to change the 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} @@ -78,8 +102,8 @@ convert-ly -e myfile.ly @noindent in the directory containing the file. This will upgrade -@file{myfile@/.ly} in-place and preserve the original file in -@file{myfile@/.ly@/~}. +@file{myfile.ly} in-place and preserve the original file in +@file{myfile.ly~}. @warning{@command{convert-ly} always converts up to the last syntax change handled by it. This means that the @code{\version} @@ -121,44 +145,69 @@ The program is invoked as follows: 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 -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} +@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} +E.g. @option{--from=2.10.25} + +@item -h, --help +Print usage help. -@item -n,--no-version +@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. @code{--to=2.12.2} +@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. + +@example +convert-ly --to=2.14.1 myfile.ly +@end example -@item -h, --help -Print usage help. @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 @@ -177,7 +226,7 @@ convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly" 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 @file{@/.ly} files in the current directory +will upgrade all @file{.ly} files in the current directory @example for f in *.ly; do convert-ly -e $f; done;