X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=0b992069c119cda3091e249d79fd87630f9c39d5;hb=651180d1740e69825d07eb83e1454b3cf534b734;hp=34eca21c202eb9af69c60b9a7938fe159cbb9f80;hpb=92d1a61acbd9b8a4556eaff60894426b7e133e6f;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index 34eca21c20..0b992069c1 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -13,28 +13,43 @@ This chapter details the technicalities of running LilyPond. -Some of these commands are run from 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}; OSX users might be more familiar with the -terms @q{terminal} or @q{console}. OSX users should also -consult @ref{Notes for the MacOS X app}. - -Describing how to use -this part of an operating system is outside the scope of this -manual; please consult other documentation on this topic if -you are unfamiliar with the command-line. - @menu -* Invoking lilypond:: +* Normal usage:: +* Command-line usage:: +* Error messages:: * Updating files with convert-ly:: * Reporting bugs:: -* Error messages:: @end menu -@node Invoking lilypond -@section Invoking lilypond + +@node Normal usage +@section Normal usage + +Most users run LilyPond through a GUI; see @ruser{First steps} if +you have not read this already. + + +@node Command-line usage +@section Command-line usage + +This section contains extra information about using LilyPond on the +command-line. This may be desirable to pass extra options to the +program. In addition, there are certain extra @q{helper} programs (such +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}; OSX users might be more familiar with the terms +@q{terminal} or @q{console}. OSX users should also consult @ref{MacOS X +on the command-line}. + +Describing how to use this part of an operating system is outside the +scope of this manual; please consult other documentation on this topic +if you are unfamiliar with the command-line. + + +@subsection Invoking lilypond + @cindex Invoking LilyPond @cindex command line options @cindex options, command line @@ -375,6 +390,80 @@ uses more CPU time. The default value is @code{70}. @end table +@node Error messages +@section Error messages + +@cindex error messages +Different error messages can appear while compiling a file: + +@table @emph + +@item Warning +@cindex warning +Something looks suspect. If you are requesting something out of the +ordinary then you will understand the message, and can ignore it. +However, warnings usually indicate that something is wrong with the +input file. + +@item 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. + +@item Scheme error +@cindex trace, Scheme +@cindex call trace +@cindex Scheme error +Errors that occur while executing Scheme code are caught by the Scheme +interpreter. If running with the verbose option (@code{-V} or +@code{--verbose}) then a call trace of the offending +function call is printed. + +@item Programming error +@cindex Programming error +There was some internal inconsistency. These error messages are +intended to help the programmers and debuggers. Usually, they can be +ignored. Sometimes, they come in such big quantities that they obscure +other output. + +@item 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. +@end table + +@cindex errors, message format +If warnings and errors can +be linked to some part of the input file, then error messages have the +following form + +@example +@var{filename}:@var{lineno}:@var{columnno}: @var{message} +@var{offending input line} +@end example + +A line-break is inserted in the offending line to indicate the column +where the error was found. For example, + +@example +test.ly:2:19: error: not a duration: 5: + @{ c'4 e'5 + g' @} +@end example + +These locations are LilyPond's best guess about where the warning or +error occurred, but (by their very nature) warnings and errors occur +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. + + @node Updating files with convert-ly @section Updating with @command{convert-ly} @@ -389,16 +478,21 @@ 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}.} +sufficient to run @example convert-ly -e myfile.ly @end example +@noindent +MacOS X users may execute this command under the menu entry +@samp{Compile > Update syntax}. + If there are no changes to myfile.ly and file called myfile.ly.NEW is created, then myfile.ly is already updated. +@subsection Command line options + @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. @@ -456,39 +550,26 @@ Print usage help. @end table -@refbugs +@menu +* Problems with convert-ly:: +@end menu + + +@node Problems with convert-ly +@subsection Problems with @code{convert-ly} Not all language changes are handled. Only one output option can be specified. Automatically updating scheme and lilypond scheme interfaces is quite unlikely; be prepared to tweak scheme code manually. - -@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 - -NEW: not exactly copied; this list has been modified. Since we're -changing the bug system, it doesn't make sense to copy from -the bug CVS any more. I'll figure out something else. -gp -@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. -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. +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 {< @@ -557,80 +638,4 @@ Please construct submit @ruser{Minimal examples}, of bug reports. We do not have the resources to investigate reports which are not as small as possible. -@node Error messages -@section Error messages - -@cindex error messages -Different error messages can appear while compiling a file: - -@table @emph -@cindex warning - -@item Warning -Something looks suspect. If you are requesting something out of the -ordinary then you will understand the message, and can ignore it. -However, warnings usually indicate that something is wrong with the -input file. - -@item Error -Something is definitely wrong. The current processing step (parsing, -interpreting, or formatting) will be finished, but the next step will -be skipped. - -@cindex error -@cindex fatal error -@item Fatal error -Something is definitely wrong, and LilyPond cannot continue. This -happens rarely. The most usual cause is misinstalled fonts. - -@cindex trace, Scheme -@cindex call trace -@cindex Scheme error -@item Scheme error -Errors that occur while executing Scheme code are caught by the Scheme -interpreter. If running with the verbose option (@code{-V} or -@code{--verbose}) then a call trace of the offending -function call is printed. - -@cindex Programming error -@item Programming error -There was some internal inconsistency. These error messages are -intended to help the programmers and debuggers. Usually, they can be -ignored. Sometimes, they come in such big quantities that they obscure -other output. In this case, file a bug-report. - -@item 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. - - -@end table - -@cindex errors, message format -If warnings and errors can -be linked to some part of the input file, then error messages have the -following form - -@example -@var{filename}:@var{lineno}:@var{columnno}: @var{message} -@var{offending input line} -@end example - -A line-break is inserted in the offending line to indicate the column -where the error was found. For example, - -@example -test.ly:2:19: error: not a duration: 5: - @{ c'4 e'5 - g' @} -@end example - -These locations are LilyPond's best guess about where the warning or -error occurred, but (by their very nature) warnings and errors occur -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. - -