[lilypond.git] / Documentation / usage / updating.itely

@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.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.16.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 for upgrading files
to newer versions of LilyPond.

@menu
* Why does the syntax change?::
* Invoking convert-ly::
* Command line options for convert-ly::
* Problems running convert-ly::
* Manual conversions::
@end menu


@node Why does the syntax change?
@section Why does the syntax change?

@cindex convert-ly
@cindex updating old input files

The LilyPond input syntax occasionally changes.  As LilyPond
itself improves, the syntax (input language) is modified
accordingly.  Sometimes these changes are made to make the input
easier to read and write or sometimes the changes are made to
accommodate new features of LilyPond.

For example, all @code{\paper} and @code{\layout} property names
are supposed to be written in the form @code{first-second-third}.
However, in version 2.11.60, we noticed that the
@code{printallheaders} property did not follow this convention.
Should we leave it alone (confusing new users who must deal with
an inconsistent input format), or change it (annoying old users
with existing scores)?  In this case, we decided to change the
name to @code{print-all-headers}.  Fortunately, this change can be
automated with our @command{convert-ly} tool.

Unfortunately, @command{convert-ly} cannot handle all input changes.
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- displaying the French word for
Christmas was entered as @code{No\"el}.  But in LilyPond
@c keep "-matching straight in fancy editors
2.6 and above, the special @code{ë} must be entered directly into
the LilyPond file as an UTF-8 character.  @command{convert-ly} cannot
change all the LaTeX special characters into UTF-8 characters; you
must manually update your old LilyPond input files.

The conversion rules of @command{convert-ly} work using text pattern
matching and replacement rather than a thorough understanding of
LilyPond.  This has several consequences:
@itemize @bullet
@item
The reliability of the conversion depends on the quality of each
applied rule set and on the complexity of the respective change.
Sometimes conversions may require manual fixes, so the old version
should be kept available for comparison.
@item
Only conversions to newer formats are possible: there are no rule
sets for downgrading.  So the main working copy of a LilyPond file
should only be upgraded when older versions of LilyPond no longer
need to be supported.  Version control systems such as Git might
help with maintaining multiple versions.
@item
LilyPond and Scheme themselves are quite robust against creatively
placed and omitted spaces, but the rules used by
@command{convert-ly} tend to make some stylistic assumptions.
Following the style used in the manuals is the safest bet for
painless upgrades, particularly as the manuals themselves are
upgraded using @command{convert-ly}.
@end itemize


@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
@file{myfile.ly} in-place and preserve the original file in
@file{myfile.ly~}.

@warning{@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.}

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

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.

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}

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 -d, --diff-version-update
increase the @code{\version} string only if the file has actually
been changed.  In that case, the version header will correspond to
the version after the last actual change.  An unstable version
number will be rounded up to the next stable version number unless
that would exceed the target version number.  Without this option,
the version will instead reflect the last @emph{attempted}
conversion.

@item -e, --edit
Apply the conversions direct to the input file, modifying it
in-place.  The original file is renamed as @file{myfile.ly~}.  This
backup file may be a hidden file on some operating systems.

@item -b, --backup-numbered
When used with the @samp{-e} option, number the backup files so that
no previous version is overwritten.  The backup files may be hidden
on some operating systems.

@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. @option{--from=2.10.25}

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

@item -l @var{loglevel}, --loglevel=@var{loglevel}
Set the output verbosity to @var{loglevel}. Possible values, in upper
case, are @code{PROGRESS} (the default), @code{NONE}, @code{WARNING},
@code{ERROR} and @code{DEBUG}.

@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 -t, --to=@var{to-patchlevel}
Explicitly set which @code{\version} to convert to, otherwise the
default is the most current value.  It must be higher than the
starting version.

@example
convert-ly --to=2.14.1 myfile.ly
@end example

@end table

To upgrade LilyPond fragments in texinfo files, use

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

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

@example
convert-ly --from=@dots{} --to=@dots{} -s
@end example


@node Problems running convert-ly
@section Problems running @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 @file{.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.


@node Manual conversions
@section Manual conversions

In theory, a program like @command{convert-ly} could handle any
syntax change.  After all, a computer program interprets the old
version and the new version, so another computer program can
translate one file into another@footnote{At least, this is
possible in any LilyPond file which does not contain scheme.  If
there is scheme in the file, then the LilyPond file contains a
Turing-complete language, and we run into problems with the famous
@qq{Halting Problem} in computer science.}.

However, the LilyPond project has limited resources: not all
conversions are performed automatically.  Below is a list of known
problems.


@verbatim
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