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.  See TRANSLATION for details.
   8 @end ignore
   9
  10 @c \version "2.12.0"
  11
  12
  13 @node Updating files with convert-ly
  14 @chapter Updating files with @command{convert-ly}
  15
  16 @cindex Updating a LilyPond file
  17 @cindex convert-ly
  18
  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.
  24
  25 @menu
  26 * Why does the syntax change?::
  27 * Invoking convert-ly::
  28 * Command line options for convert-ly::
  29 * Problems running convert-ly::
  30 * Manual conversions::
  31 @end menu
  32
  33
  34 @node Why does the syntax change?
  35 @section Why does the syntax change?
  36
  37 @cindex convert-ly
  38 @cindex updating old input files
  39
  40 The LilyPond input syntax occasionally changes.  As LilyPond
  41 itself improves, the syntax (input language) is modified
  42 accordingly.  Sometimes these changes are made to make the input
  43 easier to read and write or sometimes the changes are made to
  44 accommodate new features of LilyPond.
  45
  46 For example, all @code{\paper} and @code{\layout} property names
  47 are supposed to be written in the form @code{first-second-third}.
  48 However, in version 2.11.60, we noticed that the
  49 @code{printallheaders} property did not follow this convention.
  50 Should we leave it alone (confusing new users who must deal with
  51 an inconsistent input format), or change it (annoying old users
  52 with existing scores)?  In this case, we decided to change the
  53 name to @code{print-all-headers}.  Fortunately, this change can be
  54 automated with our @command{convert-ly} tool.
  55
  56 Unfortunately, @code{convert-ly} cannot handle all input changes.
  57 For example, in LilyPond 2.4 and earlier, accents and non-English
  58 letters were entered using LaTeX -- displaying the French word for
  59 Christmas was entered as @code{No\"el}.  But in LilyPond
  60 @c keep "-matching straight in fancy editors
  61 2.6 and above, the special @code{ë} must be entered directly into
  62 the LilyPond file as an UTF-8 character.  @code{convert-ly} cannot
  63 change all the LaTeX special characters into UTF-8 characters; you
  64 must manually update your old LilyPond input files.
  65
  66
  67 @node Invoking convert-ly
  68 @section Invoking @command{convert-ly}
  69
  70 @command{convert-ly} uses @code{\version} statements in the input
  71 file to detect the old version number.  In most cases, to upgrade
  72 your input file it is sufficient to run
  73
  74 @example
  75 convert-ly -e myfile.ly
  76 @end example
  77
  78 @noindent
  79 in the directory containing the file.  This will upgrade
  80 @code{myfile.ly} in-place and preserve the original file in
  81 @code{myfile.ly~}.
  82
  83 @warning{@command{convert-ly} always converts up to the last
  84 syntax change handled by it.  This means that the @code{\version}
  85 number left in the file is usually lower than the version of
  86 @command{convert-ly} itself.}
  87
  88 To convert all the input files in a directory together use
  89
  90 @example
  91 convert-ly -e *.ly
  92 @end example
  93
  94 Alternatively, if you want to specify a different name for the
  95 upgraded file, preserving the original file and name unchanged,
  96 use
  97
  98 @example
  99 convert-ly myfile.ly > mynewfile.ly
 100 @end example
 101
 102 The program will list the version numbers for which conversions
 103 have been made.  If no version numbers are listed the file is
 104 already up to date.
 105
 106 MacOS@tie{}X users may execute these commands under the menu entry
 107 @code{Compile > Update syntax}.
 108
 109 Windows users should enter these commands in a Command Prompt
 110 window, which is usually found under
 111 @code{Start > Accessories > Command Prompt}.
 112
 113
 114 @node Command line options for convert-ly
 115 @section Command line options for @command{convert-ly}
 116
 117 The program is invoked as follows:
 118
 119 @example
 120 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
 121 @end example
 122
 123
 124 The following options can be given:
 125
 126 @table @code
 127 @item -e,--edit
 128 Apply the conversions direct to the input file, modifying it
 129 in-place.
 130
 131 @item -f,--from=@var{from-patchlevel}
 132 Set the version to convert from.  If this is not set, @command{convert-ly}
 133 will guess this, on the basis of @code{\version} strings in the file.
 134 E.g. @code{--from=2.10.25}
 135
 136 @item -n,--no-version
 137 Normally, @command{convert-ly} adds a @code{\version} indicator
 138 to the output.  Specifying this option suppresses this.
 139
 140 @item -s, --show-rules
 141 Show all known conversions and exit.
 142
 143 @item --to=@var{to-patchlevel}
 144 Set the goal version of the conversion.  It defaults to the latest
 145 available version.  E.g. @code{--to=2.12.2}
 146
 147 @item -h, --help
 148 Print usage help.
 149 @end table
 150
 151 To upgrade LilyPond fragments in texinfo files, use
 152
 153 @example
 154 convert-ly --from=... --to=... --no-version *.itely
 155 @end example
 156
 157 To see the changes in the LilyPond syntax between two versions, use
 158
 159 @example
 160 convert-ly --from=... --to=... -s
 161 @end example
 162
 163
 164 @node Problems running convert-ly
 165 @section Problems running @code{convert-ly}
 166
 167 When running convert-ly in a Command Prompt window under Windows
 168 on a file which has spaces in the filename or in the path to it,
 169 it is necessary to surround the entire input file name with three
 170 (!) sets of double quotes:
 171
 172 @example
 173 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
 174 @end example
 175
 176 If the simple @command{convert-ly -e *.ly} command fails because the
 177 expanded command line becomes too long, the @command{convert-ly}
 178 command may be placed in a loop instead.  This example for UNIX
 179 will upgrade all @code{.ly} files in the current directory
 180
 181 @example
 182 for f in *.ly; do convert-ly -e $f; done;
 183 @end example
 184
 185 In the Windows Command Prompt window the corresponding command is
 186
 187 @example
 188 for %x in (*.ly) do convert-ly -e """%x"""
 189 @end example
 190
 191 Not all language changes are handled.  Only one output option can be
 192 specified.  Automatically updating scheme and LilyPond scheme
 193 interfaces is quite unlikely; be prepared to tweak scheme code
 194 manually.
 195
 196
 197 @node Manual conversions
 198 @section Manual conversions
 199
 200 In theory, a program like @command{convert-ly} could handle any
 201 syntax change.  After all, a computer program interprets the old
 202 version and the new version, so another computer program can
 203 translate one file into another@footnote{At least, this is
 204 possible in any LilyPond file which does not contain scheme.  If
 205 there is scheme in the file, then the LilyPond file contains a
 206 Turing-complete language, and we run into problems with the famous
 207 @qq{Halting Problem} in computer science.}.
 208
 209 However, the LilyPond project has limited resources: not all
 210 conversions are performed automatically.  Below is a list of known
 211 problems.
 212
 213
 214 @verbatim
 215 1.6->2.0:
 216  Doesn't always convert figured bass correctly, specifically things like {<
 217 >}.  Mats' comment on working around this:
 218    To be able to run convert-ly
 219    on it, I first replaced all occurrences of '{<' to some dummy like '{#'
 220    and similarly I replaced '>}' with '&}'.  After the conversion, I could
 221    then change back from '{ #' to '{ <' and from '& }' to '> }'.
 222  Doesn't convert all text markup correctly.  In the old markup syntax,
 223  it was possible to group a number of markup commands together within
 224 parentheses, e.g.
 225    -#'((bold italic) "string")
 226    This will incorrectly be converted into
 227    -\markup{{\bold italic} "string"}
 228    instead of the correct
 229    -\markup{\bold \italic "string"}
 230 2.0->2.2:
 231  Doesn't handle \partcombine
 232  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 233 stanzas.
 234 2.0->2.4:
 235  \magnify isn't changed to \fontsize.
 236     - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 237  remove-tag isn't changed.
 238     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 239  first-page-number isn't changed.
 240     - first-page-number no => print-first-page-number = ##f
 241  Line breaks in header strings aren't converted.
 242     - \\\\  as line break in \header strings => \markup \center-align <
 243       "First Line" "Second Line" >
 244  Crescendo and decrescendo terminators aren't converted.
 245     - \rced => \!
 246     - \rc => \!
 247 2.2->2.4:
 248  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 249 converted.
 250 2.4.2->2.5.9
 251  \markup{ \center-align <{ ... }> } should be converted to:
 252  \markup{ \center-align {\line { ... }} }
 253  but now, \line is missing.
 254 2.4->2.6
 255  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 256 2.8
 257  \score{} must now begin with a music expression.  Anything else
 258  (particularly \header{}) must come after the music.
 259 @end verbatim
 260
 261