[ << Updating files with convert-ly ]	[Top][Contents][Index]	[ Running lilypond-book >> ]
[ < Updating files with convert-ly ]	[ Up : Updating files with convert-ly ]	[ Command-line preliminaries > ]

---

2.1 Why does the syntax change?

Syntax changes are often made to make the LilyPond input code simpler for both reading and writing, but occasionally changes are made to accommodate new features or enhancements to existing functions.

Here is a real example to illustrate this.

All \paper and \layout property names are supposed to be written in the form first-second-third. However, in LilyPond version 2.11.60, it was noticed that the printallheaders property did not follow this convention. Should this property be left alone (confusing new users with an inconsistent format)? Or should it be changed (annoying old users with existing LilyPond input files)? The decision was eventually made to change the name of the property to print-all-headers, and by using the convert-ly command old users had a way to automatically update their existing input files.

Unfortunately, the convert-ly command is not capable to manage all syntax changes. For example, accents and non-English characters were entered using standard LaTeX notation in versions of LilyPond before 2.6; words like ‘Noël’ (which is ‘Christmas’ in French) had to be entered as No\"el. Starting with LilyPond 2.6, the special letter ‘ë’ must be entered directly as a UTF-8 character. Because convert-ly cannot convert LaTeX special characters into UTF-8 characters, older LilyPond input files have to be edited manually to take care of that.

The conversion rules of the convert-ly command work by using text pattern matching and replacement (rather than ‘understanding’ the context of what it is changing within a given input file). This has several consequences:

• 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 additional, manual fixes, so the original input files should be kept for comparison just in case.
• Only conversions to newer syntax changes are possible: there are no rule sets to go back to older versions of LilyPond. As a consequence, input files should only be upgraded when older versions of LilyPond are no longer being maintained. Again, the original data should be kept just in case, perhaps by using version control systems like Git to help maintain multiple versions of your input files.
• LilyPond is quite robust when processing ‘creatively’ placed or omitted whitespace, but the rules used by convert-ly often make some stylistic assumptions. For painless upgrades it is therefore advised to follow the input style as used in the LilyPond manuals, particularly as the examples in the manuals themselves are all upgraded using the convert-ly command.