* Info Catalog Up lilypond-usage: Updating files with convert-ly Next lilypond-usage: Invoking convert-ly

lilypond-usage: Why does the syntax change?

 
 2.1 Why does the syntax change?
 ===============================
 
 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 ‘\paper’ and ‘\layout’ property names are supposed
 to be written in the form ‘first-second-third’.  However, in version
 2.11.60, we noticed that the ‘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 ‘print-all-headers’.  Fortunately, this change can be automated
 with our ‘convert-ly’ tool.
 
    Unfortunately, ‘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 ‘No\"el’.  But in LilyPond 2.6 and above, the special ‘ë’
 must be entered directly into the LilyPond file as an UTF-8 character.
 ‘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 ‘convert-ly’ work using text pattern matching
 and replacement rather than a thorough understanding of LilyPond.  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 manual fixes, so the old version
      should be kept available for comparison.
    • 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.
    • LilyPond and Scheme themselves are quite robust against creatively
      placed and omitted spaces, but the rules used by ‘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 ‘convert-ly’.
* Info Catalog Up lilypond-usage: Updating files with convert-ly Next lilypond-usage: Invoking convert-ly