Documentation/application/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 * Invoking convert-ly::
  27 * Command line options for convert-ly::
  28 * Problems with convert-ly::
  29 @end menu
  30
  31 @node Invoking convert-ly
  32 @section Invoking @command{convert-ly}
  33
  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
  37
  38 @example
  39 convert-ly -e myfile.ly
  40 @end example
  41
  42 @noindent
  43 in the directory containing the file.  This will upgrade
  44 @code{myfile.ly} in-place and preserve the original file in
  45 @code{myfile.ly~}.
  46
  47 To convert all the input files in a directory together use
  48
  49 @example
  50 convert-ly -e *.ly
  51 @end example
  52
  53 Alternatively, if you want to specify a different name for the
  54 upgraded file, preserving the original file and name unchanged,
  55 use
  56
  57 @example
  58 convert-ly myfile.ly > mynewfile.ly
  59 @end example
  60
  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}
  64 itself.
  65
  66 The program will list the version numbers for which conversions
  67 have been made.  If no version numbers are listed the file is
  68 already up to date.
  69
  70 @noindent
  71 MacOS@tie{}X users may execute these commands under the menu entry
  72 @code{Compile > Update syntax}.
  73
  74 Windows users should enter these commands in a Command Prompt window,
  75 which is usually found under
  76 @code{Start > Accessories > Command Prompt}.
  77
  78 @node Command line options for convert-ly
  79 @section Command line options for @command{convert-ly}
  80
  81 In general, the program is invoked as follows:
  82
  83 @example
  84 convert-ly [@var{option}]@dots{} @var{filename}@dots{}
  85 @end example
  86
  87
  88 The following options can be given:
  89
  90 @table @code
  91 @item -e,--edit
  92 Apply the conversions direct to the input file, modifying it
  93 in-place.
  94
  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}
  99
 100 @item -n,--no-version
 101 Normally, @command{convert-ly} adds a @code{\version} indicator
 102 to the output.  Specifying this option suppresses this.
 103
 104 @item -s, --show-rules
 105 Show all known conversions and exit.
 106
 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}
 110
 111 @item -h, --help
 112 Print usage help.
 113 @end table
 114
 115 To upgrade LilyPond fragments in texinfo files, use
 116
 117 @example
 118 convert-ly --from=... --to=... --no-version *.itely
 119 @end example
 120
 121 To see the changes in the LilyPond syntax between two versions, use
 122
 123 @example
 124 convert-ly --from=... --to=... -s
 125 @end example
 126
 127
 128 @node Problems with convert-ly
 129 @section Problems with @code{convert-ly}
 130
 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:
 135
 136 @example
 137 convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
 138 @end example
 139
 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
 144
 145 @example
 146 for f in *.ly; do convert-ly -e $f; done;
 147 @end example
 148
 149 In the Windows Command Prompt window the corresponding command is
 150
 151 @example
 152 for %x in (*.ly) do convert-ly -e """%x"""
 153 @end example
 154
 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
 158 manually.
 159
 160 @verbatim
 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.
 163
 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.
 167
 168 1.6->2.0:
 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
 177 parentheses, e.g.
 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"}
 183 2.0->2.2:
 184  Doesn't handle \partcombine
 185  Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
 186 stanzas.
 187 2.0->2.4:
 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.
 198     - \rced => \!
 199     - \rc => \!
 200 2.2->2.4:
 201  \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
 202 converted.
 203 2.4.2->2.5.9
 204  \markup{ \center-align <{ ... }> } should be converted to:
 205  \markup{ \center-align {\line { ... }} }
 206  but now, \line is missing.
 207 2.4->2.6
 208  Special LaTeX characters such as $~$ in text are not converted to UTF8.
 209 2.8
 210  \score{} must now begin with a music expression.  Anything else
 211  (particularly \header{}) must come after the music.
 212 @end verbatim
 213
 214