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 The LilyPond input syntax is routinely changed to simplify it or improve
21 it in different ways. As a side effect of this, the LilyPond interpreter
22 often is no longer compatible with older input files. To remedy this,
23 the program @command{convert-ly} can be used for upgrading files
24 to newer versions of LilyPond.
27 * Why does the syntax change?::
28 * Invoking convert-ly::
29 * Command line options for convert-ly::
30 * Problems running convert-ly::
31 * Manual conversions::
35 @node Why does the syntax change?
36 @section Why does the syntax change?
39 @cindex updating old input files
41 The LilyPond input syntax occasionally changes. As LilyPond
42 itself improves, the syntax (input language) is modified
43 accordingly. Sometimes these changes are made to make the input
44 easier to read and write or sometimes the changes are made to
45 accommodate new features of LilyPond.
47 For example, all @code{\paper} and @code{\layout} property names
48 are supposed to be written in the form @code{first-second-third}.
49 However, in version 2.11.60, we noticed that the
50 @code{printallheaders} property did not follow this convention.
51 Should we leave it alone (confusing new users who must deal with
52 an inconsistent input format), or change it (annoying old users
53 with existing scores)? In this case, we decided to change the
54 name to @code{print-all-headers}. Fortunately, this change can be
55 automated with our @command{convert-ly} tool.
57 Unfortunately, @command{convert-ly} cannot handle all input changes.
58 For example, in LilyPond 2.4 and earlier, accents and non-English
59 letters were entered using LaTeX -- displaying the French word for
60 Christmas was entered as @code{No\"el}. But in LilyPond
61 @c keep "-matching straight in fancy editors
62 2.6 and above, the special @code{ë} must be entered directly into
63 the LilyPond file as an UTF-8 character. @command{convert-ly} cannot
64 change all the LaTeX special characters into UTF-8 characters; you
65 must manually update your old LilyPond input files.
67 The conversion rules of @command{convert-ly} work using text pattern
68 matching and replacement rather than a thorough understanding of
69 LilyPond. This has several consequences:
72 The reliability of the conversion depends on the quality of each
73 applied rule set and on the complexity of the respective change.
74 Sometimes conversions may require manual fixes, so the old version
75 should be kept available for comparison.
77 Only conversions to newer formats are possible: there are no rule
78 sets for downgrading. So the main working copy of a LilyPond file
79 should only be upgraded when older versions of LilyPond no longer
80 need to be supported. Version control systems such as Git might
81 help with maintaining multiple versions.
83 LilyPond and Scheme themselves are quite robust against creatively
84 placed and omitted spaces, but the rules used by
85 @command{convert-ly} tend to make some stylistic assumptions.
86 Following the style used in the manuals is the safest bet for
87 painless upgrades, particularly as the manuals themselves are
88 upgraded using @command{convert-ly}.
92 @node Invoking convert-ly
93 @section Invoking @command{convert-ly}
95 @command{convert-ly} uses @code{\version} statements in the input
96 file to detect the old version number. In most cases, to upgrade
97 your input file it is sufficient to run
100 convert-ly -e myfile.ly
104 in the directory containing the file. This will upgrade
105 @file{myfile.ly} in-place and preserve the original file in
108 @warning{@command{convert-ly} always converts up to the last
109 syntax change handled by it. This means that the @code{\version}
110 number left in the file is usually lower than the version of
111 @command{convert-ly} itself.}
113 To convert all the input files in a directory together use
119 Alternatively, if you want to specify a different name for the
120 upgraded file, preserving the original file and name unchanged,
124 convert-ly myfile.ly > mynewfile.ly
127 The program will list the version numbers for which conversions
128 have been made. If no version numbers are listed the file is
131 MacOS@tie{}X users may execute these commands under the menu entry
132 @code{Compile > Update syntax}.
134 Windows users should enter these commands in a Command Prompt
135 window, which is usually found under
136 @code{Start > Accessories > Command Prompt}.
139 @node Command line options for convert-ly
140 @section Command line options for @command{convert-ly}
142 The program is invoked as follows:
145 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
148 The following options can be given:
151 @item -d, --diff-version-update
152 increase the @code{\version} string only if the file has actually
153 been changed. In that case, the version header will correspond to
154 the version after the last actual change. An unstable version
155 number will be rounded up to the next stable version number unless
156 that would exceed the target version number. Without this option,
157 the version will instead reflect the last @emph{attempted}
161 Apply the conversions direct to the input file, modifying it
162 in-place. The original file is renamed as @file{myfile.ly~}. This
163 backup file may be a hidden file on some operating systems.
165 @item -b, --backup-numbered
166 When used with the @samp{-e} option, number the backup files so that
167 no previous version is overwritten. The backup files may be hidden
168 on some operating systems.
170 @item -f, --from=@var{from-patchlevel}
171 Set the version to convert from. If this is not set, @command{convert-ly}
172 will guess this, on the basis of @code{\version} strings in the file.
173 E.g. @option{--from=2.10.25}
178 @item -l @var{loglevel}, --loglevel=@var{loglevel}
179 Set the output verbosity to @var{loglevel}. Possible values, in upper
180 case, are @code{PROGRESS} (the default), @code{NONE}, @code{WARNING},
181 @code{ERROR} and @code{DEBUG}.
183 @item -n, --no-version
184 Normally, @command{convert-ly} adds a @code{\version} indicator
185 to the output. Specifying this option suppresses this.
187 @item -s, --show-rules
188 Show all known conversions and exit.
190 @item -t, --to=@var{to-patchlevel}
191 Explicitly set which @code{\version} to convert to, otherwise the
192 default is the most current value. It must be higher than the
196 convert-ly --to=2.14.1 myfile.ly
201 To upgrade LilyPond fragments in texinfo files, use
204 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
207 To see the changes in the LilyPond syntax between two versions, use
210 convert-ly --from=@dots{} --to=@dots{} -s
214 @node Problems running convert-ly
215 @section Problems running @code{convert-ly}
217 When running convert-ly in a Command Prompt window under Windows
218 on a file which has spaces in the filename or in the path to it,
219 it is necessary to surround the entire input file name with three
220 (!) sets of double quotes:
223 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
226 If the simple @command{convert-ly -e *.ly} command fails because the
227 expanded command line becomes too long, the @command{convert-ly}
228 command may be placed in a loop instead. This example for UNIX
229 will upgrade all @file{.ly} files in the current directory
232 for f in *.ly; do convert-ly -e $f; done;
235 In the Windows Command Prompt window the corresponding command is
238 for %x in (*.ly) do convert-ly -e """%x"""
241 Not all language changes are handled. Only one output option can be
242 specified. Automatically updating scheme and LilyPond scheme
243 interfaces is quite unlikely; be prepared to tweak scheme code
247 @node Manual conversions
248 @section Manual conversions
250 In theory, a program like @command{convert-ly} could handle any
251 syntax change. After all, a computer program interprets the old
252 version and the new version, so another computer program can
253 translate one file into another@footnote{At least, this is
254 possible in any LilyPond file which does not contain scheme. If
255 there is scheme in the file, then the LilyPond file contains a
256 Turing-complete language, and we run into problems with the famous
257 @qq{Halting Problem} in computer science.}.
259 However, the LilyPond project has limited resources: not all
260 conversions are performed automatically. Below is a list of known
266 Doesn't always convert figured bass correctly, specifically things like {<
267 >}. Mats' comment on working around this:
268 To be able to run convert-ly
269 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
270 and similarly I replaced '>}' with '&}'. After the conversion, I could
271 then change back from '{ #' to '{ <' and from '& }' to '> }'.
272 Doesn't convert all text markup correctly. In the old markup syntax,
273 it was possible to group a number of markup commands together within
275 -#'((bold italic) "string")
276 This will incorrectly be converted into
277 -\markup{{\bold italic} "string"}
278 instead of the correct
279 -\markup{\bold \italic "string"}
281 Doesn't handle \partcombine
282 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
285 \magnify isn't changed to \fontsize.
286 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
287 remove-tag isn't changed.
288 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
289 first-page-number isn't changed.
290 - first-page-number no => print-first-page-number = ##f
291 Line breaks in header strings aren't converted.
292 - \\\\ as line break in \header strings => \markup \center-align <
293 "First Line" "Second Line" >
294 Crescendo and decrescendo terminators aren't converted.
298 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
301 \markup{ \center-align <{ ... }> } should be converted to:
302 \markup{ \center-align {\line { ... }} }
303 but now, \line is missing.
305 Special LaTeX characters such as $~$ in text are not converted to UTF8.
307 \score{} must now begin with a music expression. Anything else
308 (particularly \header{}) must come after the music.