Next: , Previous: Error messages, Up: Running LilyPond



5.5 Updating with 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 convert-ly can be used to deal with most of the syntax changes between LilyPond versions.

It uses \version statements in the input files to detect the old version number. In most cases, to upgrade your input file it is sufficient to run1

convert-ly -e myfile.ly

If there are no changes to myfile.ly and file called myfile.ly.NEW is created, then myfile.ly is already updated.

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

To upgrade LilyPond fragments in texinfo files, use

convert-ly --from=... --to=... --no-version *.itely

To upgrade many files at once, combine convert-ly with standard unix commands. This example will upgrade all .ly files in the current directory

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

In general, the program is invoked as follows:

convert-ly [option]... file...

The following options can be given:

-e,--edit
Do an inline edit of the input file. Overrides --output.
-f,--from=from-patchlevel
Set the version to convert from. If this is not set, convert-ly will guess this, on the basis of \version strings in the file.
-n,--no-version
Normally, convert-ly adds a \version indicator to the output. Specifying this option suppresses this.
-s, --show-rules
Show all known conversions and exit.
--to=to-patchlevel
Set the goal version of the conversion. It defaults to the latest available version.
-h, --help
Print usage help.

Bugs

Not all language changes are handled. Only one output option can be specified.


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 occurencies 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 #'. . .
 firstpagenumber isn't changed.
    - firstpagenumber no => printfirstpagenumber = ##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.


Footnotes

[1] MacOS X users may execute this command under the menu entry Compile > Update syntax.


This page is for LilyPond-2.6.3 (stable-branch).

Report errors to <bug-lilypond@gnu.org>.

Other languages: English.
Using automatic language selection.