1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 @node Updating files with convert-ly
15 @chapter Updating files with @command{convert-ly}
17 @cindex Updating a LilyPond file
20 As LilyPond is improved, the syntax (input language) of some commands
21 and functions can change. This can result in unexpected errors,
22 warnings or even output when input files, previously created with older
23 versions of LilyPond are then used with later versions.
25 To help with this the @command{convert-ly} command can be used to
26 upgrade these older input files to use the newer syntax.
29 * Why does the syntax change?::
30 * Invoking convert-ly::
31 * Command line options for convert-ly::
32 * Problems running convert-ly::
33 * Manual conversions::
37 @node Why does the syntax change?
38 @section Why does the syntax change?
41 @cindex updating old input files
43 Often, syntax changes are made to make the input simpler to both read
44 and write, but occasionally the changes are made to accommodate new
45 features or enhancements to existing functions.
47 To illustrate this here is a real example:
49 All @code{\paper} and @code{\layout} property names were supposed to be
50 written in the form @code{first-second-third}. However, in LilyPond
51 version 2.11.60, it was noticed that the @code{printallheaders} property
52 did not follow this convention. Should this property be left alone
53 (confusing new users with an inconsistent format)? Or should it be
54 changed (annoying old users with existing LilyPond input files)?
56 The decision was made to change the name of the property to
57 @code{print-all-headers}, and by using the @command{convert-ly} command
58 the old users had a way to automatically update their existing input
61 However, the @command{convert-ly} command cannot always be used to
62 manage all syntax changes. In versions of LilyPond before 2.4.2,
63 accents and non-English characters were entered using standard LaTeX
64 notation. For example the French word for @q{Christmas} was entered as
65 @code{No\"el}. But in LilyPond 2.6 onwards, the special @code{ë} must
66 be entered directly as a UTF-8 character. The @command{convert-ly}
67 command cannot change LaTeX special characters into UTF-8 characters, so
68 older LilyPond input files have to edited manually.
70 The conversion rules of the @command{convert-ly} command work using text
71 pattern-matching and replacement (rather than @q{understanding} the
72 context of what it is changing within a given input file). This has
77 The reliability of the conversion depends on the quality of each applied
78 rule set and on the complexity of the respective change. Sometimes
79 conversions may require additional, manual fixes, so the original input
80 files should be kept for comparison just in case.
83 Only conversions to newer syntax changes are possible: there are no rule
84 sets to go back to older versions of LilyPond. So the input file
85 should only be upgraded when older versions of LilyPond are no longer
86 being maintained. Again, the original input files should be kept just
87 in case; perhaps using version control systems (i.e. Git) to help with
88 maintaining multiple versions of your input files.
91 LilyPond is quite robust when processing @q{creatively} placed or
92 omitted whitespace, but the rules used by @command{convert-ly} often
93 make some stylistic assumptions. Therefore following the input style as
94 used in the LilyPond manuals is advised for painless upgrades,
95 particularly as the examples in the manuals themselves are all upgraded
96 using the @command{convert-ly} command.
100 @node Invoking convert-ly
101 @section Invoking @command{convert-ly}
103 The @command{convert-ly} command uses the @code{\version} number in
104 the input file to detect older versions. In most cases, to upgrade your
105 input file it is sufficient just to run;
108 convert-ly -e myfile.ly
112 in the directory containing the input file. This will upgrade
113 @file{myfile.ly} in-place and preserve the original file by renaming it
114 @file{myfile.ly~}. The @code{\version} number in the upgraded input
115 file, along with any required syntax updates, is also changed.
117 When run, the @command{convert-ly} command will output the version
118 numbers of which conversions have been made to. If no version numbers
119 are listed in the output for the file, it is already up to date and
120 using the latest LilyPond syntax.
122 @warning{For each new version of LilyPond, a new @command{convert-ly}
123 command is created, however not every version of LilyPond will need
124 syntax changes for its input files from the version before. This means
125 that the @command{convert-ly} command will only convert input files up
126 to the latest syntax change it has and this, in turn, may mean that the
127 @code{\version} number left in the upgraded input file is sometimes
128 earlier than the version of @command{convert-ly} command itself.}
130 To convert all input files in a single directory use;
136 Linux and MacOS@tie{}X users can both use the appropriate terminal
137 application, but MacOS@tie{}X users can also execute this command
138 directly under the menu entry @code{Compile > Update syntax}.
140 A Windows user would run the command;
143 convert-ly.py -e *.ly
147 entering these commands in a @code{command prompt} usually found under
148 @code{Start > Accessories > Command Prompt} or for version 8 users,
149 by typing in the search window @q{command prompt}.
151 To convert all input files that reside in different sets of
155 find . -name '*.ly' -exec convert-ly -e '@{@}' \;
158 This example searches and converts all input files in the current
159 directory and all directories below it recursively. The converted files
160 will be located in the same directory along with their renamed
161 originals. This should also work for MacOS@tie{}X users, although only
162 via the terminal app.
164 Windows user would use;
167 forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
170 Alternatively, an explicit path to the top-level of your folder
171 containing all the sub-folders that have input files in them can be
172 stated using the @code{/p} option;
175 forfiles /s /p C:\Documents\MyScores /M *.ly /c "cmd /c convert-ly.py -e @@file"
178 If there are spaces in the path to the top-level folder, then the whole
179 path needs to be inside double quotes;
182 forfiles /s /p "C:\Documents\My Scores" /M *.ly /c "cmd /c convert-ly.py -e @@file"
187 @node Command line options for convert-ly
188 @section Command line options for @command{convert-ly}
190 The program is invoked as follows:
193 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
196 The following options can be given:
199 @item -d, --diff-version-update
200 increase the @code{\version} string only if the file has actually
201 been changed. In that case, the version header will correspond to
202 the version after the last actual change. An unstable version
203 number will be rounded up to the next stable version number unless
204 that would exceed the target version number. Without this option,
205 the version will instead reflect the last @emph{attempted}
209 Apply the conversions direct to the input file, modifying it
210 in-place. The original file is renamed as @file{myfile.ly~}. This
211 backup file may be a hidden file on some operating systems.
212 Alternatively, if you want to specify a different name for the
213 upgraded file without using the @code{-e} options default @code{~}
214 appended to the old input file, the output can be redirected instead;
217 convert-ly myfile.ly > mynewfile.ly
220 Windows user would use;
223 convert-ly.py myfile.ly > mynewfile.ly
226 @item -b, --backup-numbered
227 When used with the @samp{-e} option, number the backup files so that
228 no previous version is overwritten. The backup files may be hidden
229 on some operating systems.
231 @item -f, --from=@var{from-patchlevel}
232 Set the version to convert from. If this is not set,
233 @command{convert-ly} will guess this, on the basis of @code{\version}
234 strings in the file. E.g. @option{--from=2.10.25}
239 @item -l @var{loglevel}, --loglevel=@var{loglevel}
240 Set the output verbosity to @var{loglevel}. Possible values, in upper
241 case, are @code{PROGRESS} (the default), @code{NONE}, @code{WARNING},
242 @code{ERROR} and @code{DEBUG}.
244 @item -n, --no-version
245 Normally, @command{convert-ly} adds a @code{\version} indicator
246 to the output. Specifying this option suppresses this.
248 @item -s, --show-rules
249 Show all known conversions and exit.
251 @item -t, --to=@var{to-patchlevel}
252 Explicitly set which @code{\version} to convert to, otherwise the
253 default is the most current value. It must be higher than the
257 convert-ly --to=2.14.1 myfile.ly
262 To upgrade LilyPond fragments in texinfo files, use
265 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
268 To see the changes in the LilyPond syntax between two versions, use
271 convert-ly --from=@dots{} --to=@dots{} -s
275 @node Problems running convert-ly
276 @section Problems running @code{convert-ly}
278 When running convert-ly in a Command Prompt window under Windows
279 on a file which has spaces in the filename or in the path to it,
280 it is necessary to surround the entire input file name with three
281 (!) sets of double quotes:
284 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
287 If the simple @command{convert-ly -e *.ly} command fails because the
288 expanded command line becomes too long, the @command{convert-ly}
289 command may be placed in a loop instead. This example for UNIX
290 will upgrade all @file{.ly} files in the current directory
293 for f in *.ly; do convert-ly -e $f; done;
296 In the Windows Command Prompt window the corresponding command is
299 for %x in (*.ly) do convert-ly -e """%x"""
302 Not all language changes are handled. Only one output option can be
303 specified. Automatically updating scheme and LilyPond scheme
304 interfaces is quite unlikely; be prepared to tweak scheme code
308 @node Manual conversions
309 @section Manual conversions
311 In theory, a program like @command{convert-ly} could handle any
312 syntax change. After all, a computer program interprets the old
313 version and the new version, so another computer program can
314 translate one file into another@footnote{At least, this is
315 possible in any LilyPond file which does not contain scheme. If
316 there is scheme in the file, then the LilyPond file contains a
317 Turing-complete language, and we run into problems with the famous
318 @qq{Halting Problem} in computer science.}.
320 However, the LilyPond project has limited resources: not all
321 conversions are performed automatically. Below is a list of known
327 Doesn't always convert figured bass correctly, specifically things like {<
328 >}. Mats' comment on working around this:
329 To be able to run convert-ly
330 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
331 and similarly I replaced '>}' with '&}'. After the conversion, I could
332 then change back from '{ #' to '{ <' and from '& }' to '> }'.
333 Doesn't convert all text markup correctly. In the old markup syntax,
334 it was possible to group a number of markup commands together within
336 -#'((bold italic) "string")
337 This will incorrectly be converted into
338 -\markup{{\bold italic} "string"}
339 instead of the correct
340 -\markup{\bold \italic "string"}
342 Doesn't handle \partcombine
343 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
346 \magnify isn't changed to \fontsize.
347 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
348 remove-tag isn't changed.
349 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
350 first-page-number isn't changed.
351 - first-page-number no => print-first-page-number = ##f
352 Line breaks in header strings aren't converted.
353 - \\\\ as line break in \header strings => \markup \center-align <
354 "First Line" "Second Line" >
355 Crescendo and decrescendo terminators aren't converted.
359 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
362 \markup{ \center-align <{ ... }> } should be converted to:
363 \markup{ \center-align {\line { ... }} }
364 but now, \line is missing.
366 Special LaTeX characters such as $~$ in text are not converted to UTF8.
368 \score{} must now begin with a music expression. Anything else
369 (particularly \header{}) must come after the music.