(LY_DEFINE): deprecate

[lilypond.git] / Documentation / user / converters.itely

diff --git a/Documentation/user/converters.itely b/Documentation/user/converters.itely
index 93d0da1eb8aa1c0f42494d56b2427feb50f0d6aa..513b52e3c6e45c3bccbfe4ec659be69f6d3d313b 100644 (file)
--- a/Documentation/user/converters.itely
+++ b/Documentation/user/converters.itely
@@ -31,12 +31,20 @@ the program @command{convert-ly} can be used to deal with most of the
 syntax changes between LilyPond versions.
 
 It uses @code{\version} statements in the input files to detect the old
-version number.  For example, to upgrade all LilyPond files in the
-current directory and its subdirectories, enter the following on the
-command line.
+version number.  In most cases, to upgrade your input file it is sufficient
+to run
 
 @example
-convert-ly -e `find . -name '*.ly' -print`
+covert-ly -e myfile.ly
+@end example
+
+If there are no changes to myfile.ly and file called myfile.ly.NEW
+is created, then myfile.ly is already updated.
+
+To upgrade LilyPond fragments in texinfo files, use
+
+@example
+convert-ly --from=... --to=... --no-version *.itely
 @end example
 
 In general, the program is invoked as follows:
@@ -61,7 +69,7 @@ Set the output file to write.
 
 @item -n,--no-version
 Normally, @command{convert-ly} adds a @code{\version} indicator 
-to the output. Specifying this option suppresses this.  
+to the output.  Specifying this option suppresses this.  
 
 @item -s, --show-rules
 Show all known conversions and exit.
@@ -83,6 +91,44 @@ usually lower than the version of @command{convert-ly} itself.
 Not all language changes are handled.  Only one output option can be
 specified.
 
+
+@c  We might want to make this a completely new section, along with more
+@c  info about how to upgrade old input files.  -gp
+
+@ignore
+Copy and paste from CVS, last updated
+Feb 14, 2005
+
+http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/lilypond/lily-bugs/bugs/convert-ly.txt?rev=HEAD&content-type=text/plain
+@end ignore
+@verbatim
+
+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. Only very simple cases are fixed.
+2.0->2.2:
+ Doesn't handle \partcombine
+ Doesn't do \addlyrics => \lyricsto, this breaks some scores with multiple stanzas.
+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.
+@end verbatim
+
+
 @node Invoking midi2ly
 @section Invoking @command{midi2ly}