--- /dev/null
+@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.14.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
+* 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, @code{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. @code{convert-ly} cannot
+change all the LaTeX special characters into UTF-8 characters; you
+must manually update your old LilyPond input files.
+
+
+@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 -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 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
+
+
projects / lilypond.git / blobdiff