X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finvoking.itexi;h=999f81574f143eb23641e535440dae41c024e92e;hb=b34c63f0e1afe6b1312c4c167b1cad312acd1b00;hp=f6f8924191adb799a87c45ad1c9f20305d7d8e72;hpb=793925ac7c6a2cd031124beae79d2eda547d127d;p=lilypond.git diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index f6f8924191..999f81574f 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -2,36 +2,166 @@ @node Invoking LilyPond @chapter Invoking LilyPond +This chapter details the technicalities of running LilyPond. + + @menu +* Invoking lilypond:: Titling LilyPond scores. +* Invoking the lilypond binary:: +* Error messages:: * Reporting bugs:: -* Website:: -* Invoking ly2dvi:: Titling LilyPond scores. +* Editor support:: +* Point and click:: @end menu +@node Invoking lilypond +@section Invoking lilypond + +Nicely titled output is created through a separate program: +@file{@code{lilypond}} is a script that uses the LilyPond formatting +engine (which is in a separate program) and La@TeX{} to create a +nicely titled piece of sheet music, in PDF (Portable Document Format) +format. + +@example + @code{lilypond} [@var{option}]@dots{} @var{file}@dots{} +@end example + +To have @code{lilypond} 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 --psgz + Gzip the postscript file. +@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 + + + +@node Invoking the lilypond binary +@section Invoking the lilypond binary @cindex Invoking LilyPond @cindex command line options @cindex options, command line @cindex switches -Usage: + +The formatting system consists of two parts: a binary executable +(@file{lilypond-bin}), which is responsible for the formatting +functionality, and support scripts, which post-process the resulting +output. Normally, the support scripts are called, which in turn invoke +the @code{lilypond-bin} binary. However, @code{lilypond-bin} may be +called directly as follows. @example - lilypond [@var{option}]@dots{} @var{file}@dots{} + lilypond-bin [@var{option}]@dots{} @var{file}@dots{} @end example -When invoked with a filename that has no extension, LilyPond will try -to add @file{.ly} as an extension first. To have LilyPond read from -stdin, use a dash @code{-} for @var{file}. +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 LilyPond processes @file{filename.ly} it will produce +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 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 any default -settings from within Scheme .} +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 @@ -43,28 +173,21 @@ The following options are supported: @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 +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 -Output format for sheet music. Choices are @code{tex} (for @TeX{} -output, to be processed with plain @TeX{}, or through ly2dvi), -@code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript), -@code{scm} (for a Scheme dump), @code{sk} (for Sketch) and @code{as} -(for ASCII-art). +A comma separated list of output formats. Choices are @code{tex} (for +@TeX{} output, to be processed with La@TeX{}, and @code{ps} for +PostScript. -@strong{This option is only for developers}. Only the @TeX{} output of -these is usable for real work. More information can be found at -@uref{http://lilypond.org/wiki?OutputFormats}. +Other output options are intended for developers. @cindex output format, setting -@cindex Sketch output -@cindex ASCII-art output -@cindex PDFTeX output @cindex PostScript output @cindex Scheme dump @@ -78,25 +201,37 @@ Add @var{directory} to the search path for input files. Set init file to @var{file} (default: @file{init.ly}). @item -m,--no-paper @cindex MIDI -Disable @TeX{} output. If you have a @code{\midi} definition midi output +Disable @TeX{} output. If you have a @code{\midi} definition MIDI output will be generated. -@item -M,--dependencies -Output rules to be included in Makefile. @item -o,--output=@var{FILE} Set the default output file to @var{FILE}. -@ignore @item -s,--safe -Disallow untrusted @code{\include} directives, in-line -Scheme evaluation, backslashes in @TeX{}, code. +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 -@strong{WARNING}: the @code{--safe} option has not been reviewed for a -long time. Do not rely on it for automatic invocation (e.g. over the -web). Volunteers are welcome to do a new audit. -@end ignore +@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}. + +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 -v,--version -Show version information +Show version information. @item -V,--verbose Be verbose: show full paths of all files read, and give timing information. @@ -109,29 +244,38 @@ Show the warranty with which GNU LilyPond comes. (It comes with @section Environment variables -For processing both the @TeX{} and the PostScript output, you must -have appropriate environment variables set. Scripts to do this are -included in @file{buildscripts/out/lilypond-profile} (for sh shells) -and @file{buildscripts/out/lilypond-login} (for C-shells), and should -normally be sourced as part of your login process. If these scripts -are not run from the system wide login process, then you must run it -yourself. +For processing both the @TeX{} and the PostScript output, the +appropriate environment variables must be set. The following scripts +do this: + +@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} +your @file{.profile}: @example - . lilypond-profile + . @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} +your @file{~/.login}: @example - source lilypond-login + source @var{/the/path/to/}lilypond-login @end example -These scripts set the following variables +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 @@ -146,12 +290,12 @@ file tree. A typical setting would be @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 LilyPond PS files. +point to the directory containing library PS files. @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 LilyPond PFA files. +point to the directory containing PFA files. When you print direct PS output, remember to send the PFA files to the printer as well. @@ -165,7 +309,7 @@ printer as well. @cindex TEXMF @cindex printing postscript -The LilyPond binary itself recognizes the following environment variables +The binary itself recognizes the following environment variables: @table @code @item LILYPONDPREFIX This specifies a directory where locale messages and @@ -173,236 +317,264 @@ data files will be looked up by default. The directory should contain subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. @item LANG -This 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. -@cindex bugs -@cindex reporting bugs - -@node Reporting bugs -@section Reporting bugs +@end table -Since there is no finder's fee which doubles every year, there is no -need to wait for the prize money to grow. So send a bug report today! +@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 -LilyPond development moves quickly, so if you have a problem, it is -wise to check if it has been fixed in a newer release. If you think -you found a bug, please send in a bugreport. When you send us a -bugreport, we have to diagnose the problem and if possible, duplicate -it. To make this possible, it is important that you include the -following information in your report: +@example + @var{filename}:@var{lineno}:@var{columnno}: @var{message} + @var{offending input line} +@end example -@itemize @bullet +A line-break is inserted in offending line to indicate the column +where the error was found. For example, -@item A sample input which causes the error. Please have mercy on the -developers, send a @emph{small} sample file. +@example +test.ly:2:19: error: not a duration: 5: + \notes @{ c'4 e'5 + g' @} +@end example -@item The version number of lilypond. -@item A description of the platform you use (i.e., operating system, -system libraries, whether you downloaded a binary release) +@node Reporting bugs +@section Reporting bugs -@item If necessary, send a description of the bug itself. If you -include output a ly2dvi run, please use @code{--verbose} option of -ly2dvi. +@cindex bugs +@cindex reporting bugs -@end itemize +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. -You can send the report to @email{bug-lilypond@@gnu.org}. This is a -mailinglist, but you don't have to be subscribed to it to post. +@item VIM -@node Website -@section Website +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 -If you are reading this manual in print, it is possible that the -website contains updates to the manual. You can find the lilypond -website at @uref{http://www.lilypond.org/}. +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}. -@node Invoking ly2dvi -@section Invoking ly2dvi +@item JEdit -Nicely titled output is created through a separate program: -@file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a -nicely titled piece of sheet music, in DVI format or PostScript. +There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to +the @uref{http://lily4jedit.sourceforge.net,plugin website} for more +information. -@example - ly2dvi [@var{option}]@dots{} @var{file}@dots{} -@end example +@end table -To have ly2dvi read from stdin, use a dash @code{-} for @var{file}. +@node Point and click +@section Point and click +@cindex point and click -Ly2dvi supports the following options: +@cindex source specials +@cindex specials, source -@table @code -@item -k,--keep - Keep the temporary directory including LilyPond and ly2dvi output -files. The temporary directory is created in the current directory as @code{ly2dvi.dir}. -@item -d,--dependencies - Write makefile dependencies for every input file. -@item -h,--help - Print usage help. -@item -I,--include=@var{dir} - Add @var{dir} to LilyPond's include path. -@item -m,--no-paper - Produce MIDI output only. -@item --no-lily - Do not run LilyPond; useful for debugging ly2dvi. -@item -o,--output=@var{file} - Generate output to @var{file}. The extension of @var{file} is ignored. -@item -P,--postscript - Also generate PostScript output, using dvips. The postscript uses -the standard @TeX{} bitmap fonts for your printer. -@item -p,--pdf - Also generate Portable Document Format (PDF). This option will -generate a PS file using scalable fonts, and will run the PS file -through @code{ps2pdf} producing a PDF file. - -@cindex PDF -@cindex Scalable fonts - - If you use lilypond-book or your own wrapper files, don't use -@code{\usepackage[[T1]@{fontenc@}} in the file header but don't forget -@code{\usepackage[latin1]@{inputenc@}} if you use any other -non-anglosaxian characters. +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. - @item --preview - Also generate a picture of the first system of the score. -@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{pagenumber}, @code{linewidth}, @code{orientation}, -@code{textheight}. -@item -v,--version -Show version information -@item -V,--verbose -Be verbose -@item -w,--warranty -Show the warranty with which GNU LilyPond comes. (It comes with -@strong{NO WARRANTY}!) -@end table +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}. -@subsection Titling layout + 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}. -Ly2dvi extracts the following header fields from the LY files to -generate titling: +Apparently, KDVI does not process PostScript specials correctly. Beams +and slurs will not be visible in KDVI. -@table @code -@item title - The title of the music. Centered on top of the first page. -@item subtitle - Subtitle, centered below the title. -@item poet - Name of the poet, left flushed below the subtitle. -@item composer - Name of the composer, right flushed below the subtitle. -@item meter - Meter string, left flushed below the poet. -@item opus - Name of the opus, right flushed below the composer. -@item arranger - Name of the arranger, right flushed below the opus. -@item instrument - Name of the instrument, centered below the arranger -@item piece - Name of the piece, left flushed below the instrument -@item head - A text to print in the header of all pages. It is not called -@code{header}, because @code{\header} is a reserved word in LilyPond. -@item copyright - A text to print in the footer of the first page. Default is to - print the standard footer also on the first page. -@item footer - A text to print in the footer of all but the last page. -@item tagline - Line to print at the bottom of last page. The default text is ``Lily -was here, @var{version-number}''. -@end table +@cindex Xdvi +@cindex KDVI +@cindex KDE -@cindex header -@cindex footer -@cindex page layout -@cindex titles +@end itemize +@item an editor with a client/server interface (or a lightweight GUI +editor): +@cindex editor -@subsection Additional parameters +@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. -Ly2dvi responds to several parameters specified in a @code{\paper} -section of the LilyPond file. They can be overridden by supplying a -@code{--set} command line option. +@c move this elsewhere? -@table @code -@item language - Specify La@TeX{} language: the @code{babel} package will be -included. Default: unset. - Read from the @code{\header} block. +@cindex Emacs +@cindex Emacs mode +@cindex lilypond-mode for Emacs +@cindex syntax coloring -@item latexheaders - Specify additional La@TeX{} headers file. +@item XEmacs. XEmacs is very similar to Emacs. - Normally read from the @code{\header} block. Default value: empty +@cindex XEmacs -@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 NEdit. NEdit runs under Windows, and Unix. + It is available from @uref{http://www.nedit.org}. -@item latexoptions - Specify additional options for the La@TeX{} -@code{\documentclass}. You can put any valid value here. This was -designed to allow ly2dvi to produce output for double-sided paper, -with balanced margins and pagenumbers on alternating sides. To achieve -this specify @code{twoside} +@cindex NEdit -@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 GVim. GVim is a GUI variant of VIM, the popular VI +clone. It is available from @uref{http://www.vim.org}. -@item linewidth - The music line width. It is normally read from the @code{\paper} -block. +@cindex GVim +@cindex Vim -@item papersize - The paper size (as a name, e.g. @code{a4}). It is normally read from -the @code{\paper} block. +@end itemize +@end itemize -@item pagenumber - If set to @code{no}, no page numbers will be printed. If set to a -positive integer, start with this value as the first page number. - - @item fontenc - The font encoding, should be set identical to the @code{font-encoding} - property in the score. -@end table +Xdvi must be configured to find the @TeX{} fonts and music +fonts. Refer to the Xdvi documentation for more information. -@subsection Environment variables +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 -@table @code -@item LANG -selects the language for the warning messages of Ly2dvi and LilyPond. +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. -@item GUILE_MAX_SEGMENT_SIZE -is an option for GUILE, the scheme interpreter; it sets the size of -the chunks of memory allocated by GUILE. By increasing this from its -default 8388608, the performance of LilyPond on large scores is -slightly improved. +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 -@end table +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}.