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. See TRANSLATION for details.
13 @node Updating files with convert-ly
14 @chapter Updating files with @command{convert-ly}
16 @cindex Updating a LilyPond file
19 The LilyPond input syntax is routinely changed to simplify it or improve
20 it in different ways. As a side effect of this, the LilyPond interpreter
21 often is no longer compatible with older input files. To remedy this,
22 the program @command{convert-ly} can be used to deal with most of the
23 syntax changes between LilyPond versions.
26 * Invoking convert-ly::
27 * Command line options for convert-ly::
28 * Problems with convert-ly::
31 @node Invoking convert-ly
32 @section Invoking @command{convert-ly}
34 @command{convert-ly} uses @code{\version} statements in the input
35 file to detect the old version number. In most cases, to upgrade
36 your input file it is sufficient to run
39 convert-ly -e myfile.ly
43 in the directory containing the file. This will upgrade
44 @code{myfile.ly} in-place and preserve the original file in
47 To convert all the input files in a directory together use
53 Alternatively, if you want to specify a different name for the
54 upgraded file, preserving the original file and name unchanged,
58 convert-ly myfile.ly > mynewfile.ly
61 @command{convert-ly} always converts up to the last syntax change
62 handled by it. This means that the @code{\version} number left in
63 the file is usually lower than the version of @command{convert-ly}
66 The program will list the version numbers for which conversions
67 have been made. If no version numbers are listed the file is
71 MacOS@tie{}X users may execute these commands under the menu entry
72 @code{Compile > Update syntax}.
74 Windows users should enter these commands in a Command Prompt window,
75 which is usually found under
76 @code{Start > Accessories > Command Prompt}.
78 @node Command line options for convert-ly
79 @section Command line options for @command{convert-ly}
81 In general, the program is invoked as follows:
84 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
88 The following options can be given:
92 Apply the conversions direct to the input file, modifying it
95 @item -f,--from=@var{from-patchlevel}
96 Set the version to convert from. If this is not set, @command{convert-ly}
97 will guess this, on the basis of @code{\version} strings in the file.
98 E.g. @code{--from=2.10.25}
100 @item -n,--no-version
101 Normally, @command{convert-ly} adds a @code{\version} indicator
102 to the output. Specifying this option suppresses this.
104 @item -s, --show-rules
105 Show all known conversions and exit.
107 @item --to=@var{to-patchlevel}
108 Set the goal version of the conversion. It defaults to the latest
109 available version. E.g. @code{--to=2.12.2}
115 To upgrade LilyPond fragments in texinfo files, use
118 convert-ly --from=... --to=... --no-version *.itely
121 To see the changes in the LilyPond syntax between two versions, use
124 convert-ly --from=... --to=... -s
128 @node Problems with convert-ly
129 @section Problems with @code{convert-ly}
131 When running convert-ly in a Command Prompt window under Windows
132 on a file which has spaces in the filename or in the path to it,
133 it is necessary to surround the entire input file name with three
134 (!) sets of double quotes:
137 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
140 If the simple @command{convert-ly -e *.ly} command fails because the
141 expanded command line becomes too long, the @command{convert-ly}
142 command may be placed in a loop instead. This example for UNIX
143 will upgrade all @code{.ly} files in the current directory
146 for f in *.ly; do convert-ly -e $f; done;
149 In the Windows Command Prompt window the corresponding command is
152 for %x in (*.ly) do convert-ly -e """%x"""
155 Not all language changes are handled. Only one output option can be
156 specified. Automatically updating scheme and LilyPond scheme
157 interfaces is quite unlikely; be prepared to tweak scheme code
161 There are a few things that the convert-ly cannot handle. Here's a list
162 of limitations that the community has complained about.
164 This bug report structure has been chosen because convert-ly has a
165 structure that doesn't allow to smoothly implement all needed changes.
166 Thus this is just a wishlist, placed here for reference.
169 Doesn't always convert figured bass correctly, specifically things like {<
170 >}. Mats' comment on working around this:
171 To be able to run convert-ly
172 on it, I first replaced all occurrences of '{<' to some dummy like '{#'
173 and similarly I replaced '>}' with '&}'. After the conversion, I could
174 then change back from '{ #' to '{ <' and from '& }' to '> }'.
175 Doesn't convert all text markup correctly. In the old markup syntax,
176 it was possible to group a number of markup commands together within
178 -#'((bold italic) "string")
179 This will incorrectly be converted into
180 -\markup{{\bold italic} "string"}
181 instead of the correct
182 -\markup{\bold \italic "string"}
184 Doesn't handle \partcombine
185 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
188 \magnify isn't changed to \fontsize.
189 - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
190 remove-tag isn't changed.
191 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
192 first-page-number isn't changed.
193 - first-page-number no => print-first-page-number = ##f
194 Line breaks in header strings aren't converted.
195 - \\\\ as line break in \header strings => \markup \center-align <
196 "First Line" "Second Line" >
197 Crescendo and decrescendo terminators aren't converted.
201 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
204 \markup{ \center-align <{ ... }> } should be converted to:
205 \markup{ \center-align {\line { ... }} }
206 but now, \line is missing.
208 Special LaTeX characters such as $~$ in text are not converted to UTF8.
210 \score{} must now begin with a music expression. Anything else
211 (particularly \header{}) must come after the music.