Issue 3675: Make convert-ly -d only ever update on changed files

[lilypond.git] / Documentation / usage / updating.itely

diff --git a/Documentation/usage/updating.itely b/Documentation/usage/updating.itely
index e7a1e80d6ebaf337259028aba699e75bbca3563f..ad92a834e35db8307521379f9dc4bd9789e6ce09 100644 (file)
--- a/Documentation/usage/updating.itely
+++ b/Documentation/usage/updating.itely
@@ -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 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?::
 
 @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.
 
 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
 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.
 
 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}
 
 @node Invoking convert-ly
 @section Invoking @command{convert-ly}


@@ -124,15 +148,26 @@ convert-ly [@var{option}]@dots{} @var{filename}@dots{}
 The following options can be given:
 
 @table @code
 The following options can be given:
 
 @table @code

-@item -d,--diff-version-update
-update the @code{\version} to the latest or, if this is greater, do
-nothing.
-
-@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
 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. @option{--from=2.10.25}
 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}


@@ -145,7 +180,7 @@ 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}.
 
 case, are @code{PROGRESS} (the default), @code{NONE}, @code{WARNING},
 @code{ERROR} and @code{DEBUG}.
 

-@item -n,--no-version
+@item -n, --no-version

 Normally, @command{convert-ly} adds a @code{\version} indicator
 to the output.  Specifying this option suppresses this.
 
 Normally, @command{convert-ly} adds a @code{\version} indicator
 to the output.  Specifying this option suppresses this.
 


@@ -154,7 +189,8 @@ Show all known conversions and exit.
 
 @item -t, --to=@var{to-patchlevel}
 Explicitly set which @code{\version} to convert to, otherwise the
 
 @item -t, --to=@var{to-patchlevel}
 Explicitly set which @code{\version} to convert to, otherwise the

-default is the most current value.
+default is the most current value.  It must be higher than the
+starting version.

 
 @example
 convert-ly --to=2.14.1 myfile.ly
 
 @example
 convert-ly --to=2.14.1 myfile.ly