From 8a7c0f6362498d4d95d174ea1ff24ce122612104 Mon Sep 17 00:00:00 2001 From: Graham Percival Date: Tue, 1 Sep 2009 03:38:56 +0100 Subject: [PATCH] Doc: reorg sections in AU. --- Documentation/application/running.itely | 26 ++++---- Documentation/application/updating.itely | 83 +++++++++++++++++++----- Documentation/application/working.itely | 32 --------- 3 files changed, 78 insertions(+), 63 deletions(-) diff --git a/Documentation/application/running.itely b/Documentation/application/running.itely index 86006131f1..966e226b62 100644 --- a/Documentation/application/running.itely +++ b/Documentation/application/running.itely @@ -25,10 +25,8 @@ This chapter details the technicalities of running LilyPond. @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 @@ -41,10 +39,9 @@ as @code{midi2ly}) which are only available on the command-line. 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 @@ -57,9 +54,10 @@ if you are unfamiliar with the command-line. @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{} @@ -95,7 +93,7 @@ will output @var{base}@file{-violin.pdf} and @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} @@ -387,7 +385,7 @@ Show the warranty with which GNU LilyPond comes. (It comes with @end table @node Environment variables -@subsection Environment variables +@unnumberedsubsec Environment variables @cindex LANG @@ -428,12 +426,12 @@ However, warnings usually indicate that something is wrong with the 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. @@ -455,6 +453,7 @@ ignored. Sometimes, they come in such big quantities that they obscure 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. @@ -485,5 +484,6 @@ when something unexpected happens. If you can't see an error in the 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}. diff --git a/Documentation/application/updating.itely b/Documentation/application/updating.itely index 7403c56751..71bb0edfcb 100644 --- a/Documentation/application/updating.itely +++ b/Documentation/application/updating.itely @@ -23,11 +23,47 @@ the program @command{convert-ly} can be used to deal with most of the 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} @@ -44,6 +80,11 @@ in the directory containing the file. This will upgrade @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 @@ -58,27 +99,22 @@ use 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{} @@ -125,8 +161,8 @@ convert-ly --from=... --to=... -s @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, @@ -157,14 +193,25 @@ specified. Automatically updating scheme and LilyPond scheme 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: diff --git a/Documentation/application/working.itely b/Documentation/application/working.itely index f94a0b8d35..f8504556f7 100644 --- a/Documentation/application/working.itely +++ b/Documentation/application/working.itely @@ -28,42 +28,10 @@ this chapter. @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 -- 2.39.5