X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finvoking.itexi;h=9d1b0008a028b9a2bfd8214f40a923c95d2acb97;hb=7a5a58a6f270a0ee2f488305b8c1f222174fa742;hp=13a40742be7b8bdb54cd8937a4135832007e3efe;hpb=cda8fc1780778b760905c8832f7e984161218f20;p=lilypond.git diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index 13a40742be..9d1b0008a0 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -1,83 +1,585 @@ - -@node Invoking LilyPond, , , Top +@c -*-texinfo-*- +@node Invoking LilyPond @chapter Invoking LilyPond + +This chapter details the technicalities of running LilyPond. + + +@menu +* Invoking lilypond:: +* Error messages:: +* Reporting bugs:: +* Editor support:: +* Point and click:: +* Invoking lilypond-latex:: +@end menu + +@node Invoking lilypond +@section Invoking lilypond @cindex Invoking LilyPond +@cindex command line options +@cindex options, command line +@cindex switches + +The @code{lilypond} may be called as follows from the command line. @example - @strong{lilypond} [OPTION]... [MUDELA-FILE]... + lilypond [@var{option}]@dots{} @var{file}@dots{} @end example -@section Options -@table @samp -@item -f,--format= - Output format for sheet music. Choices are tex (for @TeX{} - output), ps (for PostScript) and scm (for GUILE) +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; +they will each be processed independently. @footnote{The status of +GUILE is not reset across invocations, so be careful not to change any +system defaults from within Scheme.} + + +@section Command line options + +The following options are supported: + +@table @code + +@item -e,--evaluate=@var{expr} +Evaluate the Scheme @var{expr} before parsing any @file{.ly} files. +Multiple @code{-e} options may be given, they will be evaluated +sequentially. The function @code{ly:set-option} allows for access to +some internal variables. Use @code{-e '(ly:option-usage)'} for more +information. + +@item -f,--format=@var{format} +@c +@c +A comma separated list of back-end output formats to use. Choices are +@code{tex} (for @TeX{} output, to be processed with La@TeX{}, and +@code{ps} for PostScript. + +Other output options are intended for developers. + + +@cindex output format, setting +@cindex PostScript output +@cindex Scheme dump + @item -h,--help - Show a summary of usage. -@item --include, -I=DIRECTORY - Add @file{DIRECTORY} to the search path for input files. - -@item -i,--init=FILE - Set init file to @file{FILE} (default: @file{init.ly}). -@item -m,--no-paper - Disable @TeX{} output. If you have a \midi definition, it will do the - midi output only. -@item -M,--dependencies - Output rules to be included in Makefile. -@item -o,--output=FILE - Set the default output file to @file{FILE}. -@item -Q,--find-old-relative - show all changes needed to convert a file to relative octave syntax. +Show a summary of usage. +@item --include, -I=@var{directory} +Add @var{directory} to the search path for input files. +@cindex file searching +@cindex search path +@item -i,--init=@var{file} +Set init file to @var{file} (default: @file{init.ly}). +@item -o,--output=@var{FILE} + Set the default output file to @var{FILE}. +@item --ps + Generate PostScript. +@item --dvi + Generate DVI files. In this case, the @TeX{} backend should be + specified, i.e. @code{-f tex}. +@item --png + Generate pictures of each page, in PNG format. This implies @code{--ps}. +@item --pdf + Generate PDF. This implies @code{--ps}. +@item --preview + Generate an output file containing the titles and the first system +of the score. @item -s,--safe - Disallow untrusted @code{\include} directives, backslashes in @TeX{} -code and named output. +Do not trust the @code{.ly} input. + +When LilyPond formatting available through a web server, the +@code{--safe} @b{MUST} be passed. This will prevent code like + +@verbatim + #(system "rm -rf /") + \score { + c4^#(ly:export (ly:gulp-file "/etc/passwd")) + } +@end verbatim + +The @code{--safe} option works by evaluating in-line Scheme +expressions in a special safe module. This safe module is derived from +GUILE @file{safe-r5rs} module, but adds a number of functions of the +LilyPond API. These functions are listed in @file{safe-lily.scm}. -WARNING: the --safe option has not been reviewed for over a year; do -not rely on for automatic lily invocation (eg. over the -web). Volunteers are welcome. +In addition, @code{--safe} disallows @code{\include} directives and +disables the use of backslashes in @TeX{} strings. + +In @code{--safe} mode, it is not possible to import LilyPond variables +into Scheme. -@item -T,--no-timestamps - don't timestamp the output -@item -t,--test - Switch on any experimental features. Not for general public use. @item -v,--version - Show version information +Show version information. @item -V,--verbose - verbose +Be verbose: show full paths of all files read, and give timing +information. + @item -w,--warranty - Show the warranty with which GNU LilyPond comes. (It comes with - @strong{NO WARRANTY}!) +Show the warranty with which GNU LilyPond comes. (It comes with +@strong{NO WARRANTY}!) @end table +@section Environment variables -When invoked with a filename that has no extension, LilyPond will try -adding `@file{.ly}' as an extension first. -When LilyPond processes @file{filename.ly} 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 LilyPond will output the rest in numbered -files, starting with @file{filename-1.tex}. Several files can be -specified; they will each be processed independently. @footnote{The -status of GUILE is not reset across invocations, so be careful not to - change defaults settings from within Scheme .} +For processing both the @TeX{} and the PostScript output, the +appropriate environment variables must be set. The following scripts +do this: -@section Environment variables +@itemize @bullet +@item @file{buildscripts/out/lilypond-profile} +(for SH shells) +@item @file{buildscripts/out/lilypond-login} (for C-shells) +@end itemize + +They should normally be sourced as part of the login process. If these +scripts are not run from the system wide login process, then you must +run it yourself. + +@cindex installing LilyPond + +If you use sh, bash, or a similar shell, then add the following to +your @file{.profile}: +@example + . @var{/the/path/to/}lilypond-profile +@end example + +If you use csh, tcsh or a similar shell, then add the following to +your @file{~/.login}: +@example + source @var{/the/path/to/}lilypond-login +@end example + +Of course, in both cases, you should substitute the proper location of +either script. + +These scripts set the following variables: +@table @code +@item TEXMF + To make sure that @TeX{} and lilypond find data files (among +others @file{.tex}, @file{.mf} and @file{.tfm}), +you have to set @code{TEXMF} to point to the lilypond data +file tree. A typical setting would be +@example +@{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@} +@end example + + +@item GS_LIB +For processing PostScript output (obtained with +@code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to +point to the directory containing library PS files. -@table @samp -@item LILYINCLUDE - additional directories for finding lilypond data. The - format is like the format of @file{PATH}. +@item GS_FONTPATH +For processing PostScript output (obtained with +@code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to +point to the directory containing PFA files. + +When you print direct PS output, remember to send the PFA files to the +printer as well. +@end table + + +@cindex ghostscript +@cindex PostScript +@cindex GS_FONTPATH +@cindex GS_LIB +@cindex TEXMF +@cindex printing postscript + +The binary itself recognizes the following environment variables: +@table @code @item LILYPONDPREFIX - This specifies a directory where locale messages and -data-files will be looked up by default. The directory should contain +This specifies a directory where locale messages and +data files will be looked up by default. The directory should contain subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. @item LANG - selects the language for the warning messages of LilyPond. +This selects the language for the warning messages. +@end table + +@cindex LANG +@cindex LILYPONDPREFIX + +@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 is printed of the offending +function call. + +@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 bugreport. + + +@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 offending line to indicate the column +where the error was found. For example, + +@example +test.ly:2:19: error: not a duration: 5: + \notes @{ c'4 e'5 + g' @} +@end example + + +@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 respond to bug-reports promptly, and fix them as +soon as possible. For this, we need to reproduce and isolate the +problem. Help us by sending a defective input file, so we can +reproduce the problem. Make it small, so we can easily debug the +problem. Don't forget to tell which version you use, and on which +platform you run it. Send the report to +@email{bug-lilypond@@gnu.org}. + +@node Editor support +@section Editor support + +@cindex editors +@cindex vim +@cindex emacs +@cindex modes, editor +@cindex syntax coloring +@cindex coloring, syntax + +There is support from different editors for LilyPond. + +@table @asis +@item Emacs + Emacs has a @file{lilypond-mode}, which provides keyword +autocompletion, indentation, LilyPond specific parenthesis matching +and syntax coloring, handy compile short-cuts and reading LilyPond +manuals using Info. If lilypond-mode is not installed on your +platform, then refer to the installation instructions for more +information. + +@item VIM + +For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with +syntax coloring tools. For more information, refer to the +@ifhtml +@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}. +@end ifhtml +@ifnothtml +installation instructions. +@end ifnothtml + + +For both editors, there is also a facility to jump in the input file +to the source of errors in the graphical output. See @ref{Point and +click}. + +@item JEdit + +There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to +the @uref{http://lily4jedit.sourceforge.net,plugin website} for more +information. + +@end table + +@node Point and click +@section Point and click +@cindex point and click + +@cindex source specials +@cindex specials, source + +Point and click lets you find notes in the input by clicking on them in +the Xdvi window. This makes it easier to find input that causes some +error in the sheet music. + +To use it, you need the following software: +@itemize @bullet +@item a dvi viewer that supports src specials: +@itemize @bullet +@item Xdvi, version 22.36 or newer. Available from +@uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}. + + Most @TeX{} distributions ship with xdvik, which is always a few +versions behind the official Xdvi. To find out which Xdvi you are +running, try @code{xdvi -version} or @code{xdvi.bin -version}. +@item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or +newer. Enable option @emph{Inverse search} in the menu @emph{Settings}. + +Apparently, KDVI does not process PostScript specials correctly. Beams +and slurs will not be visible in KDVI. + +@cindex Xdvi +@cindex KDVI +@cindex KDE + + + +@end itemize +@item an editor with a client/server interface (or a lightweight GUI +editor): + +@cindex editor + +@itemize @bullet +@item Emacs. Emacs is an extensible text-editor. It is available from +@uref{http://www.gnu.org/software/emacs/}. You need version 21 to use +column location. + +@c move this elsewhere? + + +@cindex Emacs +@cindex Emacs mode +@cindex lilypond-mode for Emacs +@cindex syntax coloring + +@item XEmacs. XEmacs is very similar to Emacs. + +@cindex XEmacs + +@item NEdit. NEdit runs under Windows, and Unix. + It is available from @uref{http://www.nedit.org}. + +@cindex NEdit + +@item GVim. GVim is a GUI variant of VIM, the popular VI +clone. It is available from @uref{http://www.vim.org}. + +@cindex GVim +@cindex Vim + +@end itemize +@end itemize + + +Xdvi must be configured to find the @TeX{} fonts and music +fonts. Refer to the Xdvi documentation for more information. + +To use point-and-click, add one of these lines to the top of your .ly +file: +@example +#(ly:set-point-and-click 'line) +@end example +@cindex line-location + +When viewing, Control-Mousebutton 1 will take you to the originating +spot in the @file{.ly} file. Control-Mousebutton 2 will show all +clickable boxes. + +If you correct large files with point-and-click, be sure to start +correcting at the end of the file. When you start at the top, and +insert one line, all following locations will be off by a line. + +@cindex Emacs +For using point-and-click with Emacs, add the following +In your Emacs startup file (usually @file{~/.emacs}): +@example +(server-start) +@end example + +Make sure that the environment variable @var{XEDITOR} is set to +@example +emacsclient --no-wait +%l %f +@end example +@cindex @var{XEDITOR} +If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in +your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}. + +For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or +use this argument with Xdvi's @code{-editor} option. + +@cindex NEdit +For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or +use this argument with Xdvi's @code{-editor} option. + +If can also make your editor jump to the exact location of the note +you clicked. This is only supported on Emacs and VIM. Users of Emacs version +20 must apply the patch @file{emacsclient.patch}. Users of version 21 +must apply @file{server.el.patch} (version 21.2 and earlier). At the +top of the @code{ly} file, replace the @code{set-point-and-click} line +with the following line: +@example +#(ly:set-point-and-click 'line-column) +@end example +@cindex line-column-location +and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim +users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}. + + + +@node Invoking lilypond-latex +@section Invoking lilypond-latex + +Before LilyPond 3.0, the @code{lilypond} program only generated music +notation. Titles and page layout was done in a separate wrapper +program. For compatibility with older files, this wrapper program has +been retained as @code{lilypond-latex}. It uses the LilyPond program +and La@TeX{} to create a nicely titled piece of sheet music. Use of +this program is only necessary if the input file contains special +La@TeX{} options or formatting codes in markup texts. + +The @code{lilypond-latex} wrapper is invoked from the command-line as +follows +@example + @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{} +@end example + +To have @code{lilypond-latex} read from stdin, use a dash @code{-} for +@var{file}. The program supports the following options. + +@cindex stdin, reading + +@table @code +@item -k,--keep + Keep the temporary directory with all output +files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}. +@item -h,--help + Print usage help. +@item -I,--include=@var{dir} + Add @var{dir} to LilyPond's include path. +@item -o,--output=@var{file} + Generate output to @var{file}. The extension of @var{file} is ignored. +@item --png + Also generate pictures of each page, in PNG format. +@item --preview + Also generate a picture of the first system of the score. + +@cindex preview +@cindex picture +@cindex bitmap +@cindex pixmap +@cindex thumbnail +@cindex screen shot + +@item -s,--set=@var{key}=@var{val} + Add @var{key}= @var{val} to the settings, overriding those specified +in the files. Possible keys: @code{language}, @code{latexheaders}, +@code{latexpackages}, @code{latexoptions}, @code{papersize}, +@code{linewidth}, @code{orientation}, +@code{textheight}. +@item -v,--version +Show version information. +@item -V,--verbose +Be verbose. This prints out commands as they are executed, and more +information about the formatting process is printed. +@item --debug +Print even more information. This is useful when generating bug reports. +@item -w,--warranty +Show the warranty with which GNU LilyPond comes. (It comes with +@strong{NO WARRANTY}!) +@end table + + + +@subsection Additional parameters + +The @code{lilypond} program responds to several parameters specified +in a @code{\paper} section of the input file. They can be overridden +by supplying a @code{--set} command line option. + +@table @code +@item language + Specify La@TeX{} language: the @code{babel} package will be +included. Default: unset. + + Read from the @code{\header} block. + +@item latexheaders + Specify additional La@TeX{} headers file. + Normally read from the @code{\header} block. Default value: empty. + +@item latexpackages + Specify additional La@TeX{} packages file. This works cumulative, +so you can add multiple packages using multiple @code{-s=latexpackages} options. + Normally read from the @code{\header} block. Default value: +@code{geometry}. + +@item latexoptions + Specify additional options for the La@TeX{} +@code{\documentclass}. You can put any valid value here. This was +designed to allow @code{lilypond} to produce output for double-sided +paper, with balanced margins and page numbers on alternating sides. To +achieve this specify @code{twoside}. + +@item orientation + Set orientation. Choices are @code{portrait} or @code{landscape}. Is +read from the @code{\paper} block, if set. + +@item textheight + The vertical extension of the music on the page. It is normally + calculated automatically, based on the paper size. + +@item linewidth + The music line width. It is normally read from the @code{\paper} +block. + +@item papersize + The paper size (as a name, e.g. @code{a4}). It is normally read from +the @code{\paper} block. + +@item fontenc + The font encoding, should be set identical to the @code{font-encoding} + property in the score. @end table +