X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Frunning.itely;h=b0b9bffad4d7cd832b02d2ccbde3b84074a9d3c6;hb=bb91de5b7f8c4f753452730101c2422946067cc3;hp=34eca21c202eb9af69c60b9a7938fe159cbb9f80;hpb=d4ba37c298813e0f7008ef8388e126c34d8f8dd3;p=lilypond.git diff --git a/Documentation/user/running.itely b/Documentation/user/running.itely index 34eca21c20..b0b9bffad4 100644 --- a/Documentation/user/running.itely +++ b/Documentation/user/running.itely @@ -7,41 +7,64 @@ version that you are working on. See TRANSLATION for details. @end ignore +@c \version "2.12.0" + @node Running LilyPond @chapter Running LilyPond 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}. +@menu +* Normal usage:: +* Command-line usage:: +* Error messages:: +* Updating files with convert-ly:: +* Reporting bugs:: +@end menu + + +@node Normal usage +@section Normal usage + +Most users run LilyPond through a GUI; see @rlearning{First steps} if +you have not read this already. -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. + +@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}; MacOS@tie{}X users might be more familiar with the terms +@q{terminal} or @q{console}. They should also consult @ref{Setup +for 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 +if you are unfamiliar with the command-line. @menu -* Invoking lilypond:: -* Updating files with convert-ly:: -* Reporting bugs:: -* Error messages:: +* Invoking lilypond:: +* Command line options for lilypond:: +* Environment variables:: @end menu @node Invoking lilypond -@section Invoking lilypond -@cindex Invoking LilyPond -@cindex command line options +@subsection Invoking @command{lilypond} + +@cindex Invoking @command{lilypond} +@cindex command line options for @command{lilypond} @cindex options, command line @cindex switches -The @code{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{} @@ -52,32 +75,32 @@ When invoked with a filename that has no extension, the @file{.ly} extension is tried first. To read input from stdin, use a dash (@code{-}) for @var{file}. -When @file{filename.ly} is processed it will produce -@file{filename.tex} as output (or @file{filename.ps} for PostScript -output). If @file{filename.ly} contains more than one @code{\score} -block, then the rest of the scores will be output in numbered files, -starting with @file{filename-1.tex}. Several files can be specified; +When @file{filename.ly} is processed it will produce @file{filename.ps} +and @file{filename.pdf} as output. Several files can be specified; they will each be processed independently. @footnote{The status of GUILE is not reset after processing a @code{.ly} file, so be careful not to change any system defaults from within Scheme.} -In addition, the value of @code{output-suffix} will be inserted between -the basename and the number. An input file containing +If @file{filename.ly} contains more than one @code{\score} +block, then the rest of the scores will be output in numbered files, +starting with @file{filename-1.pdf}. In addition, the value of +@code{output-suffix} will be inserted between the basename and the +number. An input file containing @example #(define output-suffix "violin") -\book @{ @dots{} @} +\book @{ @dots{} @} #(define output-suffix "cello") -\book @{ @dots{} @} +\book @{ @dots{} @} @end example @noindent -will output @var{base}@file{-violin.ps} and -@var{base}@file{-cello-1.ps}. - +will output @var{base}@file{-violin.pdf} and +@var{base}@file{-cello-1.pdf}. -@subsection Command line options +@node Command line options for lilypond +@subsection Command line options for @command{lilypond} The following options are supported: @@ -107,15 +130,15 @@ at the top of the @code{.ly} file. @item -f,--format=@var{format} which formats should be written. Choices for @code{format} are -@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}. +@code{svg}, @code{ps}, @code{pdf}, and @code{png}. -Example: @code{lilypond -fpng filename.ly} +Example: @code{lilypond -fpng @var{filename}.ly} @item -d,--define-default=@var{var}=@var{val} This sets the internal program option @var{var} to the Scheme value -@var{val}. If @var{val} is not supplied, then @var{#t} is used. To +@var{val}. If @var{val} is not supplied, then @var{#t} is used. To switch off an option, @code{no-} may be prefixed to @var{var}, e.g. @cindex point and click, command line @@ -138,14 +161,14 @@ Running @code{lilypond -dhelp} will print all of the @code{-d} options available. @item paper-size -This option sets the default paper-size, +This option sets the default paper-size, @example -dpaper-size=\"letter\" @end example @noindent Note that the string must be enclosed in escaped quotes ( @code{\"} ). - +@c Match " in previous line to help context-sensitive editors @item safe Do not trust the @code{.ly} input. @@ -175,7 +198,7 @@ disables the use of backslashes in @TeX{} strings. In safe mode, it is not possible to import LilyPond variables into Scheme. -safe does @emph{not} detect resource overuse. It is still possible to +@code{-dsafe} does @emph{not} detect resource overuse. It is still possible to make the program hang indefinitely, for example by feeding cyclic data structures into the backend. Therefore, if using LilyPond on a publicly accessible webserver, the process should be limited in both @@ -185,20 +208,13 @@ The safe mode will prevent many useful LilyPond snippets from being compiled. The @code{--jail} is a more secure alternative, but requires more work to set up. +@cindex output format, setting @item backend the output format to use for the back-end. Choices for @code{format} are @table @code -@item tex -for @TeX{} output, to be processed with La@TeX{}. If present, the file -@file{file.textmetrics} is read to determine text extents. -@item texstr -dump text strings to @file{.texstr} file, which can be run through -(La)@TeX{}, resulting in a @code{.textmetrics} file, which contains the -extents of strings of text. @strong{Warning:} this functionality is -currently missing due to heavy restructuring of the source code. @item ps - for PostScript. @cindex PostScript output + for PostScript. Postscript files include TTF, Type1 and OTF fonts. No subsetting of these fonts is done. When using oriental character sets, this can @@ -209,25 +225,26 @@ currently missing due to heavy restructuring of the source code. @file{EPS} file, without fonts, and as one collated @file{EPS} file with all pages (systems) including fonts. -This mode is used by default by lilypond-book. +This mode is used by default by @command{lilypond-book}. @item svg +@cindex SVG (Scalable Vector Graphics) for SVG (Scalable Vector Graphics). This dumps every page as a separate @file{SVG} file, with embedded fonts. -@cindex SVG (Scalable Vector Graphics) You need a SVG viewer which supports embedded fonts, or a SVG viewer which is able to replace the embedded fonts with OTF fonts. - Under Unix, you may use @uref{http://www.inkscape.org,Inkscape} - (version 0.42 or later), after copying the OTF fonts in directory - @file{PATH/TO/share/lilypond/VERSION/fonts/otf/} to @file{~/.fonts/}. + Under UNIX, you may use @uref{http://www.inkscape.org,Inkscape} + (version 0.42 or later), after copying the OTF fonts from the LilyPond directory + (typically @file{/usr/share/lilypond/VERSION/fonts/otf/}) to @file{~/.fonts/}. @item scm - for a dump of the raw, internal Scheme-based drawing commands. @cindex Scheme dump -@end table + for a dump of the raw, internal Scheme-based drawing commands. -Example: @code{lilypond -dbackend=svg filename.ly} +@item null + do not output a printed score; has the same effect as @code{-dno-print-pages}. +@end table -@cindex output format, setting +Example: @code{lilypond -dbackend=svg @var{filename}.ly} @item preview Generate an output file containing the titles and the first system @@ -243,8 +260,8 @@ useful in combination with @code{-dpreview}. @item -h,--help Show a summary of usage. -@item -H,--header=FIELD -Dump a header field to file BASENAME.FIELD +@item -H,--header=@var{FIELD} +Dump a header field to file @file{BASENAME.@var{FIELD}}. @item --include, -I=@var{directory} Add @var{directory} to the search path for input files. @@ -256,16 +273,11 @@ Set init file to @var{file} (default: @file{init.ly}). @item -o,--output=@var{FILE} Set the default output file to @var{FILE}. The appropriate -suffix will be added (ie @code{.pdf} for pdf, @code{.tex} -for tex, etc). +suffix will be added (e.g. @code{.pdf} for pdf) @item --ps Generate PostScript. -@item --dvi -Generate DVI files. In this case, the @TeX{} backend should be -specified, i.e., @code{-dbackend=tex}. - @item --png Generate pictures of each page, in PNG format. This implies @code{--ps}. The resolution in DPI of the image may be set with @@ -279,24 +291,24 @@ Generate PDF. This implies @code{--ps}. @item -j,--jail=@var{user},@var{group},@var{jail},@var{dir} -Run LilyPond in a chroot jail. +Run @command{lilypond} in a chroot jail. The @code{--jail} option provides a more flexible alternative to @code{--safe} when LilyPond formatting is available through a web server or whenever LilyPond executes externally provided sources. -The @code{--jail} option works by changing the root of LilyPond to +The @code{--jail} option works by changing the root of @command{lilypond} to @var{jail} just before starting the actual compilation process. The user and group are then changed to match those provided, and the current directory is changed to @var{dir}. This setup guarantees that it is not possible (at least in theory) to escape from the jail. Note that for -@code{--jail} to work LilyPond must be run as root, which is usually +@code{--jail} to work @command{lilypond} must be run as root, which is usually accomplished in a safe way using @command{sudo}. Setting up a jail is a slightly delicate matter, as we must be sure that LilyPond is able to find whatever it needs to compile the source -@emph{inside the jail}. A typical setup comprises the following items: +@emph{inside the jail}. A typical setup comprises the following items: @table @asis @item Setting up a separate filesystem @@ -309,7 +321,7 @@ mount a loop device. A separate filesystem also guarantees that LilyPond cannot write more space than it is allowed. @item Setting up a separate user -A separate user and group (say, @samp{lily}/@samp{lily}) with low +A separate user and group (say, @code{lily}/@code{lily}) with low privileges should be used to run LilyPond inside the jail. There should be a single directory writable by this user, which should be passed in @var{dir}. @@ -349,14 +361,14 @@ Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) @end table - +@node Environment variables @subsection Environment variables @cindex LANG @cindex LILYPOND_DATADIR -@code{Lilypond} recognizes the following environment variables: +@command{lilypond} recognizes the following environment variables: @table @code @item LILYPOND_DATADIR This specifies a directory where locale messages and @@ -368,15 +380,89 @@ This selects the language for the warning messages. @item LILYPOND_GC_YIELD With this variable the memory footprint and performance can be -adjusted. It is a percentage tunes memory management behavior. With +adjusted. It is a percentage tunes memory management behavior. With higher values, the program uses more memory, with smaller values, it -uses more CPU time. The default value is @code{70}. +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} +@section Updating files with @command{convert-ly} @cindex Updating a LilyPond file @cindex convert-ly @@ -389,16 +475,27 @@ 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@tie{}X users may execute this command under the menu entry +@code{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. +@menu +* Command line options for convert-ly:: +* Problems with convert-ly:: +@end menu + +@node Command line options for convert-ly +@subsection Command line options for @command{convert-ly} + @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. @@ -416,7 +513,7 @@ convert-ly --from=... --to=... -s @end example To upgrade many files at once, combine @code{convert-ly} with -standard unix commands. This example will upgrade all @code{.ly} +standard UNIX commands. This example will upgrade all @code{.ly} files in the current directory @example @@ -456,48 +553,30 @@ Print usage help. @end table -@refbugs +@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 +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 {< ->}. Mats' comment on working around this: +>}. 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 + on it, I first replaced all occurrences 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, + 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") @@ -544,7 +623,7 @@ converted. @cindex reporting bugs If you have input that results in a crash or an erroneous output, then -that is a bug. There is a list of current bugs on our google bug tracker, +that is a bug. There is a list of current bugs on our Google bug tracker, @uref{http://code.google.com/p/lilypond/issues/list} @@ -553,84 +632,8 @@ bug by following the directions on @uref{http://lilypond.org/web/devel/participating/bugs} -Please construct submit @ruser{Minimal examples}, of bug reports. We do not +Please construct and submit minimal examples of bugs in 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. - -