X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finvoking.itexi;h=7fdf1ef1421cb50d9e7cd334b77978c4d02a7af4;hb=90daa84e03c580aa51d292e7ab3ae8ed0e8d72e6;hp=3845651a763777c4f5d8aa6a178121f5f783ba83;hpb=610249ab45542c88161088f9d27ec7397a4a3071;p=lilypond.git diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index 3845651a76..7fdf1ef142 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -1,40 +1,35 @@ @c -*-texinfo-*- -@node Invoking LilyPond -@chapter Invoking LilyPond +@node Running LilyPond +@chapter Running LilyPond This chapter details the technicalities of running LilyPond. @menu -* Invoking the lilypond binary:: +* Invoking lilypond:: +* Error messages:: * Reporting bugs:: -* Point and click:: -* Invoking ly2dvi:: Titling LilyPond scores. +* Editor support:: +* Invoking lilypond-latex:: @end menu - - -@node Invoking the lilypond binary -@section Invoking the lilypond binary +@node Invoking lilypond +@section Invoking lilypond @cindex Invoking LilyPond @cindex command line options @cindex options, command line @cindex switches -The LilyPond system consists of two parts: a binary executable, 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} binary. However, -@code{lilypond} may be called directly as follows. +The @code{lilypond} may be called as follows from the command line. @example - lilypond [@var{option}]@dots{} @var{file}@dots{} + lilypond [@var{option}]@dots{} @var{file}@dots{} @end example When invoked with a filename that has no extension, the @file{.ly} -extension is tried first. To read input from stdin, use a +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 @@ -43,8 +38,8 @@ 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 - default settings from within Scheme.} +GUILE is not reset after processing a @code{.ly} files, so be careful +not to change any system defaults from within Scheme.} @section Command line options @@ -57,26 +52,20 @@ The following options are supported: 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 +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 back-end output formats to use. 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. +There are other output options, but they are intended for developers. @cindex output format, setting -@cindex Sketch output -@cindex ASCII-art output -@cindex PDFTeX output @cindex PostScript output @cindex Scheme dump @@ -88,29 +77,50 @@ Add @var{directory} to the search path for input files. @cindex search path @item -i,--init=@var{file} 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 -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}. + 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. -@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 is available through a web server, the +@code{--safe} @b{MUST} be passed. This will prevent inline Scheme +code from wreaking havoc, for example -@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 /") + { + 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{scm/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. @item -V,--verbose -Be verbose: show full paths of all files read, and give timing +Be verbose: show full paths of all files read, and give timing information. @item -w,--warranty @@ -131,7 +141,7 @@ do this: @item @file{buildscripts/out/lilypond-login} (for C-shells) @end itemize -They should normally be sourced as part of the login process. If these +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. @@ -158,39 +168,23 @@ These scripts set the following variables: 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 +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. - -@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: +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 +data files will be looked up by default. The directory should contain subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc. @item LANG @@ -200,214 +194,211 @@ This selects the language for the warning messages. @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 -@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 replicate and isolate the -problem. Please help us by sending a good bug-report: an input file -that will reproduce the problem. Please make it small, so we can -easily isolate 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 Point and click -@section Point and click -@cindex poind and click - -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? - -There is also support for Emacs: lilypond-mode for Emacs 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. - -@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 +@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 -Xdvi must be configured to find the @TeX{} fonts and music -fonts. Refer to the Xdvi documentation for more information. +A line-break is inserted in offending line to indicate the column +where the error was found. For example, -To use point-and-click, add one of these lines to the top of your .ly -file: @example -#(ly:set-point-and-click 'line) +test.ly:2:19: error: not a duration: 5: + @{ c'4 e'5 + g' @} @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. +These locations are LilyPond's best guess about where the warning or +error occured, but (by their very nature) warning 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. -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 +@node Reporting bugs +@section Reporting bugs -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-colomn-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}. +@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. 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 of LilyPond you use! Send +the report to @email{bug-lilypond@@gnu.org}. + +When you've found a bug, have a look at our +@uref{http://lilypond.org/doc/v2.3/bugs/,bug database} to see if it +has already been reported. You could also try doing a few searches +on the mailing list for the bug. Sometimes the bug will have already +been reported and a fix or workaround is already known. + +Here is an example of a good bug report: + +@verbatim + +It seems that placement of accidentals is broken. In the +following example, the accidental touches the note head. + +Using Mac OSX 10.3.5, fink package lilypond-unstable + +\version "2.3.16" +\relative c''{ + a4 b cis d +} +@end verbatim + +@lilypond +\version "2.3.16" +\relative c''{ + \override Accidental #'extra-offset = #'(1.0 . 0) + a4 b cis d +} +@end lilypond + +@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 @file{lilypond-mode} is not installed on your +platform, then read the +@ifhtml +@uref{../../../topdocs/out-www/INSTALL.html,installation instructions}. +@end ifhtml +@ifnothtml +installation instructions. +@end ifnothtml + +@item VIM + +For @uref{http://www.vim.org,VIM}, a @file{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 + + +@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 -@refbugs +For both VIM and Emacs 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}. -When you convert the @TeX{} file to PostScript using @code{dvips}, it -will complain about not finding @code{src:X:Y} files. These complaints -are harmless, and can be ignored. -@node Invoking ly2dvi -@section Invoking ly2dvi +@node Invoking lilypond-latex +@section Invoking lilypond-latex -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: +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 - ly2dvi [@var{option}]@dots{} @var{file}@dots{} + @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{} @end example -To have ly2dvi read from stdin, use a dash @code{-} for @var{file}. +To have @code{lilypond-latex} read from stdin, use a dash @code{-} for +@var{file}. The program supports the following options. -Ly2dvi supports the following options: +@cindex stdin, reading @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 @code{Makefile} dependencies for every input file. + 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 -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, do not use -@code{\usepackage[[T1]@{fontenc@}} in the file header but do not forget -@code{\usepackage[latin1]@{inputenc@}} if you use any other -non-anglosaxian characters. - @item --png Also generate pictures of each page, in PNG format. -@item --psgz - Gzip the postscript file. -@item --html - Make a .HTML file with links to all output files. @item --preview Also generate a picture of the first system of the score. @@ -416,78 +407,33 @@ non-anglosaxian characters. @cindex bitmap @cindex pixmap @cindex thumbnail -@cindex screenshot +@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}, +in the files. Possible keys: @code{language}, @code{latexheaders}, @code{latexpackages}, @code{latexoptions}, @code{papersize}, -@code{pagenumber}, @code{linewidth}, @code{orientation}, +@code{linewidth}, @code{orientation}, @code{textheight}. @item -v,--version Show version information. @item -V,--verbose -Be 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 bugreports. +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 Titling layout - -Ly2dvi extracts the following header fields from the LY files to -generate titling; an example demonstrating all these fields is in -@inputfileref{input/test,ly2dvi-testpage.ly}: - -@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 dedication - To whom the piece is dedicated. -@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 header -@cindex footer -@cindex page layout -@cindex titles - @subsection Additional parameters -Ly2dvi 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. +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 @@ -498,46 +444,41 @@ included. Default: unset. @item latexheaders Specify additional La@TeX{} headers file. - - Normally read from the @code{\header} block. Default value: empty. + Normally read from the @code{\header} block. Default value: empty. @item latexpackages - Specify additional La@TeX{} packages file. This works cumulative, + 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: + 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 ly2dvi to produce output for double-sided paper, -with balanced margins and pagenumbers on alternating sides. To achieve -this specify @code{twoside}. +@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 + 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 + 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} + 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 paper size (as a name, e.g. @code{a4}). It is normally read from the @code{\paper} block. - -@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 +@item fontenc The font encoding, should be set identical to the @code{font-encoding} property in the score. @end table +