Documentation/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2
   3 @ignore
   4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
   5
   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..
   9 @end ignore
  10
  11 @c \version "2.16.0"
  12
  13
  14 @node Updating files with convert-ly
  15 @chapter Updating files with @command{convert-ly}
  16
  17 @cindex Updating a LilyPond file
  18 @cindex convert-ly
  19
  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 to deal with most of the
  24 syntax changes between LilyPond versions.
  25
  26 @menu
  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::
  32 @end menu
  33
  34
  35 @node Why does the syntax change?
  36 @section Why does the syntax change?
  37
  38 @cindex convert-ly
  39 @cindex updating old input files
  40
  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.
  46
  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.
  56
  57 Unfortunately, @code{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.  @code{convert-ly} cannot
  64 change all the LaTeX special characters into UTF-8 characters; you
  65 must manually update your old LilyPond input files.
  66
  67
  68 @node Invoking convert-ly
  69 @section Invoking @command{convert-ly}
  70
  71 @command{convert-ly} uses @code{\version} statements in the input
  72 file to detect the old version number.  In most cases, to upgrade
  73 your input file it is sufficient to run
  74
  75 @example
  76 convert-ly -e myfile.ly
  77 @end example
  78
  79 @noindent
  80 in the directory containing the file.  This will upgrade
  81 @file{myfile.ly} in-place and preserve the original file in
  82 @file{myfile.ly~}.
  83
  84 @warning{@command{convert-ly} always converts up to the last
  85 syntax change handled by it.  This means that the @code{\version}
  86 number left in the file is usually lower than the version of
  87 @command{convert-ly} itself.}
  88
  89 To convert all the input files in a directory together use
  90
  91 @example
  92 convert-ly -e *.ly
  93 @end example
  94
  95 Alternatively, if you want to specify a different name for the
  96 upgraded file, preserving the original file and name unchanged,
  97 use
  98
  99 @example
 100 convert-ly myfile.ly > mynewfile.ly
 101 @end example
 102
 103 The program will list the version numbers for which conversions
 104 have been made.  If no version numbers are listed the file is
 105 already up to date.
 106
 107 MacOS@tie{}X users may execute these commands under the menu entry
 108 @code{Compile > Update syntax}.
 109
 110 Windows users should enter these commands in a Command Prompt
 111 window, which is usually found under
 112 @code{Start > Accessories > Command Prompt}.
 113
 114
 115 @node Command line options for convert-ly
 116 @section Command line options for @command{convert-ly}
 117
 118 The program is invoked as follows:
 119
 120 @example
 121 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
 122 @end example
 123
 124 The following options can be given:
 125
 126 @table @code
 127 @item -d,--diff-version-update
 128 increase the @code{\version} string only if the file has actually
 129 been changed.  Without this option (or when any conversion has
 130 changed the file), the version header reflects the last considered
 131 conversion rule.
 132
 133 @item -e,--edit
 134 Apply the conversions direct to the input file, modifying it
 135 in-place.
 136
 137 @item -f,--from=@var{from-patchlevel}
 138 Set the version to convert from.  If this is not set, @command{convert-ly}
 139 will guess this, on the basis of @code{\version} strings in the file.
 140 E.g. @option{--from=2.10.25}
 141
 142 @item -h, --help
 143 Print usage help.
 144
 145 @item -l @var{loglevel}, --loglevel=@var{loglevel}
 146 Set the output verbosity to @var{loglevel}. Possible values, in upper
 147 case, are @code{PROGRESS} (the default), @code{NONE}, @code{WARNING},
 148 @code{ERROR} and @code{DEBUG}.
 149
 150 @item -n,--no-version
 151 Normally, @command{convert-ly} adds a @code{\version} indicator
 152 to the output.  Specifying this option suppresses this.
 153
 154 @item -s, --show-rules
 155 Show all known conversions and exit.
 156
 157 @item -t, --to=@var{to-patchlevel}
 158 Explicitly set which @code{\version} to convert to, otherwise the
 159 default is the most current value.
 160
 161 @example
 162 convert-ly --to=2.14.1 myfile.ly
 163 @end example
 164
 165 @end table
 166
 167 To upgrade LilyPond fragments in texinfo files, use
 168
 169 @example
 170 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 171 @end example
 172
 173 To see the changes in the LilyPond syntax between two versions, use
 174
 175 @example
 176 convert-ly --from=@dots{} --to=@dots{} -s
 177 @end example
 178
 179
 180 @node Problems running convert-ly
 181 @section Problems running @code{convert-ly}
 182
 183 When running convert-ly in a Command Prompt window under Windows
 184 on a file which has spaces in the filename or in the path to it,
 185 it is necessary to surround the entire input file name with three
 186 (!) sets of double quotes:
 187
 188 @example
 189 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
 190 @end example
 191
 192 If the simple @command{convert-ly -e *.ly} command fails because the
 193 expanded command line becomes too long, the @command{convert-ly}
 194 command may be placed in a loop instead.  This example for UNIX
 195 will upgrade all @file{.ly} files in the current directory
 196
 197 @example
 198 for f in *.ly; do convert-ly -e $f; done;
 199 @end example
 200
 201 In the Windows Command Prompt window the corresponding command is
 202
 203 @example
 204 for %x in (*.ly) do convert-ly -e """%x"""
 205 @end example
 206
 207 Not all language changes are handled.  Only one output option can be
 208 specified.  Automatically updating scheme and LilyPond scheme
 209 interfaces is quite unlikely; be prepared to tweak scheme code
 210 manually.
 211
 212
 213 @node Manual conversions
 214 @section Manual conversions
 215
 216 In theory, a program like @command{convert-ly} could handle any
 217 syntax change.  After all, a computer program interprets the old
 218 version and the new version, so another computer program can
 219 translate one file into another@footnote{At least, this is
 220 possible in any LilyPond file which does not contain scheme.  If
 221 there is scheme in the file, then the LilyPond file contains a
 222 Turing-complete language, and we run into problems with the famous
 223 @qq{Halting Problem} in computer science.}.
 224
 225 However, the LilyPond project has limited resources: not all
 226 conversions are performed automatically.  Below is a list of known
 227 problems.
 228
 229
 230 @verbatim
 231 1.6->2.0:
 232  Doesn't always convert figured bass correctly, specifically things like {<
 233 >}.  Mats' comment on working around this:
 234    To be able to run convert-ly
 235    on it, I first replaced all occurrences of '{<' to some dummy like '{#'
 236    and similarly I replaced '>}' with '&}'.  After the conversion, I could
 237    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 238  Doesn't convert all text markup correctly.  In the old markup syntax,
 239  it was possible to group a number of markup commands together within
 240 parentheses, e.g.
 241    -#'((bold italic) "string")
 242    This will incorrectly be converted into
 243    -\markup{{\bold italic} "string"}
 244    instead of the correct
 245    -\markup{\bold \italic "string"}
 246 2.0->2.2:
 247  Doesn't handle \partcombine
 248  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 249 stanzas.
 250 2.0->2.4:
 251  \magnify isn't changed to \fontsize.
 252     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 253  remove-tag isn't changed.
 254     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 255  first-page-number isn't changed.
 256     - first-page-number no => print-first-page-number = ##f
 257  Line breaks in header strings aren't converted.
 258     - \\\\  as line break in \header strings => \markup \center-align <
 259       "First Line" "Second Line" >
 260  Crescendo and decrescendo terminators aren't converted.
 261     - \rced => \!
 262     - \rc => \!
 263 2.2->2.4:
 264  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 265 converted.
 266 2.4.2->2.5.9
 267  \markup{ \center-align <{ ... }> } should be converted to:
 268  \markup{ \center-align {\line { ... }} }
 269  but now, \line is missing.
 270 2.4->2.6
 271  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 272 2.8
 273  \score{} must now begin with a music expression.  Anything else
 274  (particularly \header{}) must come after the music.
 275 @end verbatim
 276
 277