@c -*- coding: utf-8; mode: texinfo; -*-

@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"


@node Updating files with convert-ly
@chapter Updating files with @command{convert-ly}

@cindex Updating a LilyPond file
@cindex convert-ly

The LilyPond input syntax is routinely changed to simplify it or improve
it in different ways.  As a side effect of this, the LilyPond interpreter
often is no longer compatible with older input files.  To remedy this,
the program @command{convert-ly} can be used to deal with most of the
syntax changes between LilyPond versions.

@menu
* Invoking convert-ly::
* Command line options for convert-ly::
* Problems with convert-ly::
@end menu

@node Invoking convert-ly
@section Invoking @command{convert-ly}

@command{convert-ly} uses @code{\version} statements in the input
file to detect the old version number.  In most cases, to upgrade
your input file it is sufficient to run

@example
convert-ly -e myfile.ly
@end example

@noindent
in the directory containing the file.  This will upgrade
@code{myfile.ly} in-place and preserve the original file in
@code{myfile.ly~}.

To convert all the input files in a directory together use

@example
convert-ly -e *.ly
@end example

Alternatively, if you want to specify a different name for the
upgraded file, preserving the original file and name unchanged,
use

@example
convert-ly myfile.ly > mynewfile.ly
@end example

@command{convert-ly} always converts up to the last syntax change
handled by it.  This means that the @code{\version} number left in
the file is usually lower than the version of @command{convert-ly}
itself.

The program will list the version numbers for which conversions
have been made.  If no version numbers are listed the file is
already up to date.

@noindent
MacOS@tie{}X users may execute these commands under the menu entry
@code{Compile > Update syntax}.

Windows users should enter these commands in a Command Prompt window,
which is usually found under
@code{Start > Accessories > Command Prompt}.

@node Command line options for convert-ly
@section Command line options for @command{convert-ly}

In general, the program is invoked as follows:

@example
convert-ly [@var{option}]@dots{} @var{filename}@dots{}
@end example


The following options can be given:

@table @code
@item -e,--edit
Apply the conversions direct to the input file, modifying it
in-place.

@item -f,--from=@var{from-patchlevel}
Set the version to convert from.  If this is not set, @command{convert-ly}
will guess this, on the basis of @code{\version} strings in the file.
E.g. @code{--from=2.10.25}

@item -n,--no-version
Normally, @command{convert-ly} adds a @code{\version} indicator
to the output.  Specifying this option suppresses this.

@item -s, --show-rules
Show all known conversions and exit.

@item --to=@var{to-patchlevel}
Set the goal version of the conversion.  It defaults to the latest
available version.  E.g. @code{--to=2.12.2}

@item -h, --help
Print usage help.
@end table

To upgrade LilyPond fragments in texinfo files, use

@example
convert-ly --from=... --to=... --no-version *.itely
@end example

To see the changes in the LilyPond syntax between two versions, use

@example
convert-ly --from=... --to=... -s
@end example


@node Problems with convert-ly
@section Problems with @code{convert-ly}

When running convert-ly in a Command Prompt window under Windows
on a file which has spaces in the filename or in the path to it,
it is necessary to surround the entire input file name with three
(!) sets of double quotes:

@example
convert-ly """D:/My Scores/Ode.ly""" > "D:/My Scores/new Ode.ly"
@end example

If the simple @command{convert-ly -e *.ly} command fails because the
expanded command line becomes too long, the @command{convert-ly}
command may be placed in a loop instead.  This example for UNIX
will upgrade all @code{.ly} files in the current directory

@example
for f in *.ly; do convert-ly -e $f; done;
@end example

In the Windows Command Prompt window the corresponding command is

@example
for %x in (*.ly) do convert-ly -e """%x"""
@end example

Not all language changes are handled.  Only one output option can be
specified.  Automatically updating scheme and LilyPond scheme
interfaces is quite unlikely; be prepared to tweak scheme code
manually.

@verbatim
There are a few things that the convert-ly cannot handle.  Here's a list
of limitations that the community has complained about.

This bug report structure has been chosen because convert-ly has a
structure that doesn't allow to smoothly implement all needed changes.
Thus this is just a wishlist, placed here for reference.

1.6->2.0:
 Doesn't always convert figured bass correctly, specifically things like {<
>}.  Mats' comment on working around this:
   To be able to run convert-ly
   on it, I first replaced all occurrences of '{<' to some dummy like '{#'
   and similarly I replaced '>}' with '&}'.  After the conversion, I could
   then change back from '{ #' to '{ <' and from '& }' to '> }'.
 Doesn't convert all text markup correctly.  In the old markup syntax,
 it was possible to group a number of markup commands together within
parentheses, e.g.
   -#'((bold italic) "string")
   This will incorrectly be converted into
   -\markup{{\bold italic} "string"}
   instead of the correct
   -\markup{\bold \italic "string"}
2.0->2.2:
 Doesn't handle \partcombine
 Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple
stanzas.
2.0->2.4:
 \magnify isn't changed to \fontsize.
    - \magnify #m => \fontsize #f, where f = 6ln(m)/ln(2)
 remove-tag isn't changed.
    - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 first-page-number isn't changed.
    - first-page-number no => print-first-page-number = ##f
 Line breaks in header strings aren't converted.
    - \\\\  as line break in \header strings => \markup \center-align <
      "First Line" "Second Line" >
 Crescendo and decrescendo terminators aren't converted.
    - \rced => \!
    - \rc => \!
2.2->2.4:
 \turnOff (used in \set Staff.VoltaBracket = \turnOff) is not properly
converted.
2.4.2->2.5.9
 \markup{ \center-align <{ ... }> } should be converted to:
 \markup{ \center-align {\line { ... }} }
 but now, \line is missing.
2.4->2.6
 Special LaTeX characters such as $~$ in text are not converted to UTF8.
2.8
 \score{} must now begin with a music expression.  Anything else
 (particularly \header{}) must come after the music.
@end verbatim