-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.
+Often, syntax changes are made to make the input simpler to both read
+and write, but occasionally the changes are made to accommodate new
+features or enhancements to existing functions.
+
+To illustrate this here is a real example:
+
+All @code{\paper} and @code{\layout} property names were supposed to be
+written in the form @code{first-second-third}. However, in LilyPond
+version 2.11.60, it was noticed that the @code{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 made to change the name of the property to
+@code{print-all-headers}, and by using the @command{convert-ly} command
+the old users had a way to automatically update their existing input
+files.
+
+However, the @command{convert-ly} command cannot always be used to
+manage all syntax changes. In versions of LilyPond before 2.4.2,
+accents and non-English characters were entered using standard LaTeX
+notation. For example the French word for @q{Christmas} was entered as
+@code{No\"el}. But in LilyPond 2.6 onwards, the special @code{ë} must
+be entered directly as a UTF-8 character. The @command{convert-ly}
+command cannot change LaTeX special characters into UTF-8 characters, so
+older LilyPond input files have to edited manually.
+
+The conversion rules of the @command{convert-ly} command work using text
+pattern-matching and replacement (rather than @q{understanding} the
+context of what it is changing within a given input file). This has
+several consequences:
+
+@itemize @bullet
+@item
+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.
+
+@item
+Only conversions to newer syntax changes are possible: there are no rule
+sets to go back to older versions of LilyPond. So the input file
+should only be upgraded when older versions of LilyPond are no longer
+being maintained. Again, the original input files should be kept just
+in case; perhaps using version control systems (i.e. Git) to help with
+maintaining multiple versions of your input files.
+
+@item
+LilyPond is quite robust when processing @q{creatively} placed or
+omitted whitespace, but the rules used by @command{convert-ly} often
+make some stylistic assumptions. Therefore following the input style as
+used in the LilyPond manuals is advised for painless upgrades,
+particularly as the examples in the manuals themselves are all upgraded
+using the @command{convert-ly} command.
+@end itemize