Docs: AU 3.4 Clarify Convert-ly

 - show how to make new file
 - say what happens when file is up to date
 - delete reference to myfile.ly.NEW
 - say where to find Windows Command Prompt
 - rearrange options section and clarify
 - say how to deal with Windows filenames containing spaces
(cherry picked from commit 3312aa695e2d1ff1ebe38b7a9d5b514167567174)

diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely
index ecae5f9e82f381a727e245e1193064fd049b7ed0..49a4eecba79ca76425ac6700a66fd12ee971ff9c 100644 (file)
--- a/Documentation/user/running.itely
+++ b/Documentation/user/running.itely
@@ -481,12 +481,24 @@ sufficient to run
 convert-ly -e myfile.ly
 @end example
 
+@noindent
+or, if you want to preserve the original file
+
+@example
+convert-ly myfile.ly > mynewfile.ly
+@end example
+
+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 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.
+Windows users should enter this command in a Command Prompt window,
+which is usually found under
+@code{Start > Accessories > Command Prompt}.
 
 @menu
 * Command line options for convert-ly::
@@ -496,34 +508,15 @@ is created, then myfile.ly is already updated.
 @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.
-
-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
-
-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
-
-@example
-for f in *.ly; do convert-ly -e $f; done;
-@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.
 
 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
 
 
@@ -531,11 +524,13 @@ The following options can be given:
 
 @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
@@ -546,16 +541,45 @@ 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.
+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
+
+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
+
+@example
+for f in *.ly; do convert-ly -e $f; done;
+@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 file name with three (!)
+sets of double quotes:
+
+@example
+convert-ly """D:/My Scores/Ode.ly""" > """D:/My Scores/new Ode.ly"""
+@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