X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=sidebyside;f=Documentation%2Fuser%2Finvoking.itexi;h=4360324fffbb30c147e3fc2c342ad179112cd2e5;hb=2389ee814c9e12233ad0ccdee077ffb336e08e04;hp=c103bdfd3195886bae767b9935ba58f18fe427b4;hpb=00326da8a7935b31799865e8b199cc380229d420;p=lilypond.git diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index c103bdfd31..4360324fff 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -2,37 +2,48 @@ @node Invoking LilyPond @chapter Invoking LilyPond +This chapter details the technicalities of running LilyPond. + + @menu -* Reporting bugs:: -* Website:: -* Titling LilyPond scores:: +* Invoking the lilypond binary:: +* Error messages:: +* Reporting bugs:: +* Point and click:: +* Invoking ly2dvi:: Titling LilyPond scores. @end menu +@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 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-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, the @file{.ly} +extension is tried first. To read input from stdin, use a +dash @code{-} for @var{file}. -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 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 + default settings from within Scheme.} @section Command line options @@ -41,13 +52,12 @@ The following options are supported: @table @code -@item -e,--evaluate=@var{code} - Evaluates the Scheme @var{code} before parsing @file{.ly} -files. Multiple @code{-e} options may be given. They will be evaluated -sequentially. The function @code{set-lily-option} may be invoked to -set various debugging options. - - +@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 @@ -59,8 +69,7 @@ output, to be processed with plain @TeX{}, or through ly2dvi), (for ASCII-art). @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}. +these is usable for real work. @cindex output format, setting @@ -80,7 +89,7 @@ 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. @@ -98,7 +107,7 @@ web). Volunteers are welcome to do a new audit. @end ignore @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. @@ -111,29 +120,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 @@ -148,12 +166,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. @@ -167,7 +185,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 @@ -175,71 +193,239 @@ 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 call trace +@cindex Scheme error +@item Scheme error +Errors that occur while executing Scheme code are caught by the Scheme +interpreter. When they occur, a call trace of the offending function +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, a bug-report should be filed. +@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 -@cindex bugs -@cindex reporting bugs @node Reporting bugs @section Reporting bugs -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 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 + -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: + +@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? -@item A sample input which causes the error. Please have mercy on the -developers, send a @emph{small} sample file. +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}. -@item The version number of lilypond. +@cindex NEdit -@item A description of the platform you use (i.e., operating system, -system libraries, whether you downloaded a binary release) +@item GVim. GVim is a GUI variant of VIM, the popular VI +clone. It is available from @uref{http://www.vim.org}. -@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 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. -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. +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 -@node Website -@section Website +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-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}. -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/}. -@node Titling LilyPond scores -@section Titling LilyPond scores +@refbugs + +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 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. - -@subsection Invoking ly2dvi +nicely titled piece of sheet music, in DVI format or PostScript: -@c ly2dvi needs at least one FILE, can't act as filter yet @example ly2dvi [@var{option}]@dots{} @var{file}@dots{} @end example +To have ly2dvi read from stdin, use a dash @code{-} for @var{file}. + Ly2dvi supports the following options: @table @code @@ -247,7 +433,7 @@ Ly2dvi supports the following options: 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. + Write @code{Makefile} dependencies for every input file. @item -h,--help Print usage help. @item -I,--include=@var{dir} @@ -261,21 +447,35 @@ files. The temporary directory is created in the current directory as @code{ly2d @item -P,--postscript Also generate PostScript output, using dvips. The postscript uses the standard @TeX{} bitmap fonts for your printer. -@item --pdf - Also generate Portable Document Format (PDF). This option will +@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 -\use package[[T1]{fontenc} in the file header but don't forget -\usepackage[[latin1]{inputenc} if you use any other non-anglosaxian -characters. - - @item --preview + 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. + +@cindex preview +@cindex picture +@cindex bitmap +@cindex pixmap +@cindex thumbnail +@cindex screenshot + @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}, @@ -283,9 +483,11 @@ in the files. Possible keys: @code{language}, @code{latexheaders}, @code{pagenumber}, @code{linewidth}, @code{orientation}, @code{textheight}. @item -v,--version -Show version information +Show version information. @item -V,--verbose -Be verbose +Be verbose. +@item --debug +Print even more information. This is useful when generating bugreports. @item -w,--warranty Show the warranty with which GNU LilyPond comes. (It comes with @strong{NO WARRANTY}!) @@ -294,7 +496,8 @@ Show the warranty with which GNU LilyPond comes. (It comes with @subsection Titling layout Ly2dvi extracts the following header fields from the LY files to -generate titling: +generate titling; an example demonstrating all these fields is in +@inputfileref{input/test,ly2dvi-testpage.ly}: @table @code @item title @@ -312,9 +515,11 @@ generate titling: @item arranger Name of the arranger, right flushed below the opus. @item instrument - Name of the instrument, centered below the arranger + 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 + 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. @@ -339,7 +544,7 @@ was here, @var{version-number}''. @subsection Additional parameters Ly2dvi responds to several parameters specified in a @code{\paper} -section of the LilyPond file. They can be overridden by supplying a +section of the input file. They can be overridden by supplying a @code{--set} command line option. @table @code @@ -352,7 +557,7 @@ 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, @@ -361,7 +566,11 @@ so you can add multiple packages using multiple @code{-s=latexpackages} options. @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} + 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}. @item orientation Set orientation. Choices are @code{portrait} or @code{landscape}. Is @@ -380,8 +589,8 @@ block. the @code{\paper} block. @item pagenumber - If set to @code{no}, no page numbers will be printed. - + 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 @@ -389,19 +598,4 @@ the @code{\paper} block. property in the score. @end table -@subsection Environment variables - -@table @code -@item LANG -selects the language for the warning messages of Ly2dvi and LilyPond. - -@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. - - -@end table -