Updating files with convert-ly - GNU LilyPond
Description: GNU LilyPond

Next: Reporting bugs, Previous: Notes for the MacOS X app, Up: Running LilyPond

### 12.3 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 #'. . .
     first-page-number isn't changed.
        - first-page-number no => printfirst-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.

#### Footnotes

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

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

Other languages: English.
Using automatic language selection.