@menu
* Invoking lilypond::
* Notes for the MacOS X app::
+* Updating files with convert-ly::
+* Reporting bugs::
* Error messages::
* Editor support::
* Point and click::
Note that @var{path/to} will generally be @code{/Applications/}.
+@node Updating files with convert-ly
+@section Updating with @command{convert-ly}
+
+@cindex Updating a LilyPond file
+@cindex @code{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 @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. In most cases, to upgrade your input file it is
+sufficient to run@footnote{MacOS X users may execute this command
+under the menu entry @samp{Compile > Update syntax}.}
+
+@example
+convert-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.
+
+@command{convert-ly} always converts up to the last syntax change handled by
+it. This means that the @code{\version} number left in the file is
+usually lower than the version of @command{convert-ly} itself.
+
+To upgrade LilyPond fragments in texinfo files, use
+
+@example
+convert-ly --from=... --to=... --no-version *.itely
+@end example
+
+To upgrade many files at once, combine @code{convert-ly} with
+standard unix commands. This example will upgrade all @code{.ly}
+files in the current directory
+
+@example
+for f in *.ly; do convert-ly -e $f; done;
+@end example
+
+In general, the program is invoked as follows:
+
+@example
+convert-ly [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+
+The following options can be given:
+
+@table @code
+@item -e,--edit
+Do an inline edit of the input file. Overrides @code{--output}.
+
+@item -f,--from=@var{from-patchlevel}
+Set the version to convert from. If this is not set, @command{convert-ly}
+will guess this, on the basis of @code{\version} strings in the file.
+
+@item -n,--no-version
+Normally, @command{convert-ly} adds a @code{\version} indicator
+to the output. Specifying this option suppresses this.
+
+@item -s, --show-rules
+Show all known conversions and exit.
+
+@item --to=@var{to-patchlevel}
+Set the goal version of the conversion. It defaults to the latest
+available version.
+
+@item -h, --help
+Print usage help.
+@end table
+
+
+@refbugs
+
+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
+Aug 18, 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. 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.
+
+@end verbatim
+
+
+@node Reporting bugs
+@section Reporting bugs
+
+@cindex bugs
+@cindex reporting bugs
+
+If you have input that results in a crash or an erroneous output, then
+that is a bug. We try to respond to bug-reports promptly, and fix them as
+soon as possible. Help us by sending a defective input file, so we can
+reproduce the problem. Send the report via:
+
+@example
+@uref{http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs}
+@end example
+
+A few tips:
+@itemize @bullet
+
+@item Try to produce a very small input file which demonstrates the problem;
+one or two bars is often sufficient to reproduce a bug. The smaller the
+input file is, the easier it is for us to debug the problem.
+
+@item Don't forget to tell which version of LilyPond you use!
+
+@item If possible, use @code{ragged-right} in your example. This makes sure
+that the bug can be reproduced in all paper sizes.
+@end itemize
+
+@ignore
+@c the bug database is not up to date enough.
+
+When you've found a bug, have a look at our
+@uref{http://@/lilypond@/.org/@/doc/@/v2.5/@/bugs/,bug database} to see if
+it has already been reported. You could also try to do a few searches
+on the mailing list for the bug. Sometimes the bug will have already
+been reported and a fix or workaround is already known.
+@end ignore
+
+Here is an example of a good bug report:
+
+@verbatim
+It seems that placement of accidentals is broken. In the
+following example, the accidental touches the note head.
+
+Using Mac OSX 10.3.7, lilypond 2.7.32
+
+\version "2.7.32"
+\layout { ragged-right = ##t }
+\relative c'' {
+ a4 b cis d
+}
+@end verbatim
+
+@lilypond[quote]
+\layout { ragged-right = ##t }
+\relative c''{
+ \override Accidental #'extra-offset = #'(1.0 . 0)
+ a4 b cis d
+}
+@end lilypond
+
@node Error messages
@section Error messages
projects / lilypond.git / commitdiff