@node Normal usage
@section Normal usage
-Most users run LilyPond through a GUI; see
-FIXME FIXME FIXME
-@c @rlearning{First steps} if
-you have not read this already.
+Most users run LilyPond through a GUI; see @rlearning{First steps}
+if you have not read this already.
@node Command-line usage
By @q{command-line}, we mean the command line in the operating system.
Windows users might be more familiar with the terms @q{DOS shell} or
-@q{command shell}; MacOS@tie{}X users might be more familiar with the terms
-@q{terminal} or @q{console}. They should also consult
-FIXME
-@c @ref{Setup for MacOS X}.
+@q{command shell}. MacOS@tie{}X users might be more familiar with the terms
+@q{terminal} or @q{console}. Some additional setup is required
+for MacOS@tie{}X users; please see @rgeneral{MacOS X}.
Describing how to use this part of an operating system is outside the
scope of this manual; please consult other documentation on this topic
@end menu
@node Invoking lilypond
-@subsection Invoking @command{lilypond}
+@unnumberedsubsec Invoking @command{lilypond}
-The @command{lilypond} executable may be called as follows from the command line.
+The @command{lilypond} executable may be called as follows from
+the command line.
@example
lilypond [@var{option}]@dots{} @var{file}@dots{}
@node Command line options for lilypond
-@subsection Command line options for @command{lilypond}
+@unnumberedsubsec Command line options for @command{lilypond}
@cindex Invoking @command{lilypond}
@cindex command line options for @command{lilypond}
@end table
@node Environment variables
-@subsection Environment variables
+@unnumberedsubsec Environment variables
@cindex LANG
input file.
@item Error
+@cindex error
Something is definitely wrong. The current processing step (parsing,
interpreting, or formatting) will be finished, but the next step will
be skipped.
@item Fatal error
-@cindex error
@cindex fatal error
Something is definitely wrong, and LilyPond cannot continue. This
happens rarely. The most usual cause is misinstalled fonts.
other output.
@item Aborted (core dumped)
+@cindex Aborted (core dumped)
This signals a serious programming error that caused the program to
crash. Such errors are considered critical. If you stumble on one,
send a bug-report.
indicated line of your input file, try checking one or two lines
above the indicated position.
+More information about errors is given in @ref{Common errors}.
syntax changes between LilyPond versions.
@menu
+* Why does the syntax change?::
* Invoking convert-ly::
* Command line options for convert-ly::
-* Problems with convert-ly::
+* Problems running convert-ly::
+* Manual conversions::
@end menu
+
+@node Why does the syntax change?
+@section Why does the syntax change?
+
+@cindex convert-ly
+@cindex updating old input files
+
+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.
+
+
@node Invoking convert-ly
@section Invoking @command{convert-ly}
@code{myfile.ly} in-place and preserve the original file in
@code{myfile.ly~}.
+@warning{@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 convert all the input files in a directory together use
@example
convert-ly myfile.ly > mynewfile.ly
@end example
-@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.
-
The program will list the version numbers for which conversions
have been made. If no version numbers are listed the file is
already up to date.
-@noindent
MacOS@tie{}X users may execute these commands under the menu entry
@code{Compile > Update syntax}.
-Windows users should enter these commands in a Command Prompt window,
-which is usually found under
+Windows users should enter these commands in a Command Prompt
+window, which is usually found under
@code{Start > Accessories > Command Prompt}.
+
@node Command line options for convert-ly
@section Command line options for @command{convert-ly}
-In general, the program is invoked as follows:
+The program is invoked as follows:
@example
convert-ly [@var{option}]@dots{} @var{filename}@dots{}
@end example
-@node Problems with convert-ly
-@section Problems with @code{convert-ly}
+@node Problems running convert-ly
+@section Problems running @code{convert-ly}
When running convert-ly in a Command Prompt window under Windows
on a file which has spaces in the filename or in the path to it,
interfaces is quite unlikely; be prepared to tweak scheme code
manually.
-@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.
+@node Manual conversions
+@section Manual conversions
+
+In theory, a program like @command{convert-ly} could handle any
+syntax change. After all, a computer program interprets the old
+version and the new version, so another computer program can
+translate one file into another@footnote{At least, this is
+possible in any LilyPond file which does not contain scheme. If
+there is scheme in the file, then the LilyPond file contains a
+Turing-complete language, and we run into problems with the famous
+@qq{Halting Problem} in computer science.}.
+However, the LilyPond project has limited resources: not all
+conversions are performed automatically. Below is a list of known
+problems.
+
+
+@verbatim
1.6->2.0:
Doesn't always convert figured bass correctly, specifically things like {<
>}. Mats' comment on working around this:
@section When things don't work
@menu
-* Updating old input files::
* Common errors::
* Troubleshooting (taking it all apart)::
@end menu
-@node Updating old input files
-@subsection Updating old input files
-
-@cindex convert-ly
-@cindex updating old input files
-
-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.
-
-LilyPond comes with a file that makes this updating easier:
-@code{convert-ly}. For details about how to run this program, see
-@rprogram{Updating files with convert-ly}.
-
-Unfortunately, @code{convert-ly} cannot handle all input changes. It
-takes care of simple search-and-replace changes (such as @code{raggedright}
-becoming @code{ragged-right}), but some changes are too
-complicated. The syntax changes that @code{convert-ly} cannot handle
-are listed in @rprogram{Updating files with convert-ly}.
-
-For example, in LilyPond 2.4 and earlier, accents and non-English
-letters were entered using LaTeX -- for example,
-@code{No\"el} (this would print the French word for
-@c keep "-matching straight in fancy editors
-@q{Christmas}). In LilyPond 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.
-
@node Common errors
@subsection Common errors
projects / lilypond.git / commitdiff