From a57ca40f07d1bdd4191a9d857847af26b4d7c5f1 Mon Sep 17 00:00:00 2001 From: James Lowe Date: Sun, 7 Dec 2014 23:43:59 +0000 Subject: [PATCH] Doc: Usage - update Convert-ly chapters Issue 4187 Added some more examples to run convert-ly for 'mass' conversion. Included windows-specific cmds as well. I also took the opportunity (liberty?) to reword some of the paragraphs, for some awkward syntax, inconsistent use of phrases and file names and improve some of the more hard-to-fathom explanations. --- Documentation/usage/updating.itely | 213 +++++++++++++++++++---------- 1 file changed, 137 insertions(+), 76 deletions(-) diff --git a/Documentation/usage/updating.itely b/Documentation/usage/updating.itely index ad92a834e3..60b71c29de 100644 --- a/Documentation/usage/updating.itely +++ b/Documentation/usage/updating.itely @@ -17,11 +17,13 @@ @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 for upgrading files -to newer versions of LilyPond. +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?:: @@ -38,102 +40,148 @@ to newer versions of LilyPond. @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, @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. @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: +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 manual fixes, so the old version -should be kept available for comparison. +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 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. +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 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}. +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; -@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.} +@example +convert-ly -e *.ly +@end example -To convert all the input files in a directory together use +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}. + +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 -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. +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. -MacOS@tie{}X users may execute these commands under the menu entry -@code{Compile > Update syntax}. +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 + +If there are spaces in the path to the top-level folder, then the whole +path needs to be inside double quotes; + +@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 @@ -161,6 +209,19 @@ conversion. Apply the conversions direct to the input file, modifying it 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 @@ -168,9 +229,9 @@ 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} +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. -- 2.39.2