@cindex Updating a LilyPond file
@cindex convert-ly
-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.
+As LilyPond is improved, the syntax (input language) of some commands
+and functions can change. This can result in unexpected errors,
+warnings or even output when input files, previously created with older
+versions of LilyPond are then used with later versions.
+
+To help with this the @command{convert-ly} command can be used to
+upgrade these older input files to use the newer syntax.
@menu
* Why does the syntax change?::
@cindex convert-ly
@cindex updating old input files
-The LilyPond input syntax occasionally changes. As LilyPond
-itself improves, the syntax (input language) is modified
-accordingly. Sometimes these changes are made to make the input
-easier to read and write or sometimes the changes are made to
-accommodate new features of LilyPond.
-
-For example, all @code{\paper} and @code{\layout} property names
-are supposed to be written in the form @code{first-second-third}.
-However, in version 2.11.60, we noticed that the
-@code{printallheaders} property did not follow this convention.
-Should we leave it alone (confusing new users who must deal with
-an inconsistent input format), or change it (annoying old users
-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.
-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
-change all the LaTeX special characters into UTF-8 characters; you
-must manually update your old LilyPond input files.
+Often, syntax changes are made to make the input simpler to both read
+and write, but occasionally the changes are made to accommodate new
+features or enhancements to existing functions.
+
+To illustrate this here is a real example:
+
+All @code{\paper} and @code{\layout} property names were supposed to be
+written in the form @code{first-second-third}. However, in LilyPond
+version 2.11.60, it was noticed that the @code{printallheaders} property
+did not follow this convention. Should this property be left alone
+(confusing new users with an inconsistent format)? Or should it be
+changed (annoying old users with existing LilyPond input files)?
+
+The decision was made to change the name of the property to
+@code{print-all-headers}, and by using the @command{convert-ly} command
+the old users had a way to automatically update their existing input
+files.
+
+However, the @command{convert-ly} command cannot always be used to
+manage all syntax changes. In versions of LilyPond before 2.4.2,
+accents and non-English characters were entered using standard LaTeX
+notation. For example the French word for @q{Christmas} was entered as
+@code{No\"el}. But in LilyPond 2.6 onwards, the special @code{ë} must
+be entered directly as a UTF-8 character. The @command{convert-ly}
+command cannot change LaTeX special characters into UTF-8 characters, so
+older LilyPond input files have to edited manually.
+
+The conversion rules of the @command{convert-ly} command work using text
+pattern-matching and replacement (rather than @q{understanding} the
+context of what it is changing within a given input file). 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 additional, manual fixes, so the original input
+files should be kept for comparison just in case.
+
+@item
+Only conversions to newer syntax changes are possible: there are no rule
+sets to go back to older versions of LilyPond. So the input file
+should only be upgraded when older versions of LilyPond are no longer
+being maintained. Again, the original input files should be kept just
+in case; perhaps using version control systems (i.e. Git) to help with
+maintaining multiple versions of your input files.
+
+@item
+LilyPond is quite robust when processing @q{creatively} placed or
+omitted whitespace, but the rules used by @command{convert-ly} often
+make some stylistic assumptions. Therefore following the input style as
+used in the LilyPond manuals is advised for painless upgrades,
+particularly as the examples in the manuals themselves are all upgraded
+using the @command{convert-ly} command.
+@end itemize
@node Invoking convert-ly
@section Invoking @command{convert-ly}
-@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
+The @command{convert-ly} command uses the @code{\version} number in
+the input file to detect older versions. In most cases, to upgrade your
+input file it is sufficient just to run;
@example
convert-ly -e myfile.ly
@end example
@noindent
-in the directory containing the file. This will upgrade
-@file{myfile.ly} in-place and preserve the original file in
-@file{myfile.ly~}.
+in the directory containing the input file. This will upgrade
+@file{myfile.ly} in-place and preserve the original file by renaming it
+@file{myfile.ly~}. The @code{\version} number in the upgraded input
+file, along with any required syntax updates, is also changed.
+
+When run, the @command{convert-ly} command will output the version
+numbers of which conversions have been made to. If no version numbers
+are listed in the output for the file, it is already up to date and
+using the latest LilyPond syntax.
+
+@warning{For each new version of LilyPond, a new @command{convert-ly}
+command is created, however not every version of LilyPond will need
+syntax changes for its input files from the version before. This means
+that the @command{convert-ly} command will only convert input files up
+to the latest syntax change it has and this, in turn, may mean that the
+@code{\version} number left in the upgraded input file is sometimes
+earlier than the version of @command{convert-ly} command itself.}
+
+To convert all input files in a single directory use;
+
+@example
+convert-ly -e *.ly
+@end example
-@warning{@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.}
+Linux and MacOS@tie{}X users can both use the appropriate terminal
+application, but MacOS@tie{}X users can also execute this command
+directly under the menu entry @code{Compile > Update syntax}.
-To convert all the input files in a directory together use
+A Windows user would run the command;
@example
-convert-ly -e *.ly
+convert-ly.py -e *.ly
@end example
-Alternatively, if you want to specify a different name for the
-upgraded file, preserving the original file and name unchanged,
-use
+@noindent
+entering these commands in a @code{command prompt} usually found under
+@code{Start > Accessories > Command Prompt} or for version 8 users,
+by typing in the search window @q{command prompt}.
+
+To convert all input files that reside in different sets of
+subdirectories;
@example
-convert-ly myfile.ly > mynewfile.ly
+find . -name '*.ly' -exec convert-ly -e '@{@}' \;
+@end example
+
+This example searches and converts all input files in the current
+directory and all directories below it recursively. The converted files
+will be located in the same directory along with their renamed
+originals. This should also work for MacOS@tie{}X users, although only
+via the terminal app.
+
+Windows user would use;
+
+@example
+forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
+
+Alternatively, an explicit path to the top-level of your folder
+containing all the sub-folders that have input files in them can be
+stated using the @code{/p} option;
+
+@example
+forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly.py -e @@file"
@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.
+If there are spaces in the path to the top-level folder, then the whole
+path needs to be inside double quotes;
-MacOS@tie{}X users may execute these commands under the menu entry
-@code{Compile > Update syntax}.
+@example
+forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
-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
The following options can be given:
@table @code
-@item -d,--diff-version-update
+@item -d, --diff-version-update
increase the @code{\version} string only if the file has actually
-been changed. Without this option (or when any conversion has
-changed the file), the version header reflects the last considered
-conversion rule.
-
-@item -e,--edit
+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.
+Alternatively, if you want to specify a different name for the
+upgraded file without using the @code{-e} options default @code{~}
+appended to the old input file, the output can be redirected instead;
+
+@example
+convert-ly myfile.ly > mynewfile.ly
+@end example
+
+Windows user would use;
+
+@example
+convert-ly.py myfile.ly > mynewfile.ly
+@end example
+
+@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 -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 -h, --help
Print usage help.
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.
@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
projects / lilypond.git / blobdiff