X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=inline;f=Documentation%2Fuser%2Finvoking.itexi;h=feaa644aafe3b72b40480284344c6560448d2b09;hb=5bda59b7c7c09e4418872f1f40b9f7ae219ff5fc;hp=ab2b5bd1aba1876bd14d1c29072ef5841ce4a903;hpb=a54eded7c9ae0fa7dd70bfd2fbdb506502513c17;p=lilypond.git diff --git a/Documentation/user/invoking.itexi b/Documentation/user/invoking.itexi index ab2b5bd1ab..feaa644aaf 100644 --- a/Documentation/user/invoking.itexi +++ b/Documentation/user/invoking.itexi @@ -2,36 +2,49 @@ @node Invoking LilyPond @chapter Invoking LilyPond +This chapter details the technicalities of running LilyPond. + + @menu +* Invoking the lilypond binary:: * Reporting bugs:: -* Website:: -* Invoking ly2dvi:: Titling LilyPond scores. +* 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} binary. However, +@code{lilypond} may be called directly as follows. @example lilypond [@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 + default settings from within Scheme.} @section Command line options @@ -57,8 +70,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 @@ -78,7 +90,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. @@ -96,7 +108,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. @@ -109,19 +121,19 @@ 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. The following scripts do -this: +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) +(for SH shells) @item @file{buildscripts/out/lilypond-login} (for C-shells) @end itemize -They 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. +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 @@ -152,12 +164,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. @@ -171,7 +183,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 @@ -179,7 +191,7 @@ 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 @@ -187,28 +199,31 @@ This selects the language for the warning messages of LilyPond. -@cindex bugs -@cindex reporting bugs @node Reporting bugs @section Reporting bugs +@cindex bugs +@cindex 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! +need to wait for the prize money to grow. Send a bug report today! -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: +Development moves quickly, so if you have a problem, it is +wise to check if it has been fixed in a newer release. If not, please +send in a bugreport. When you send us a bugreport, we have to +diagnose the problem and if necessary, duplicate it. To make this +possible, it is important that you include the following information +in your report: @itemize @bullet @item A sample input which causes the error. Please have mercy on the developers, send a @emph{small} sample file. -@item The version number of lilypond. +@item The version number @item A description of the platform you use (i.e., operating system, system libraries, whether you downloaded a binary release) @@ -219,15 +234,143 @@ ly2dvi. @end itemize -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. +You can 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}. -@node Website -@section Website +@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-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}. + + + +@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. -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 Invoking ly2dvi @@ -250,7 +393,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} @@ -272,8 +415,8 @@ 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 + 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. @@ -300,7 +443,7 @@ 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. @item --debug @@ -333,8 +476,8 @@ generate titling. An example demonstrating all these fields is in Name of the arranger, right flushed below the opus. @item instrument Name of the instrument, centered below the arranger -@item dedication - [docme] +@item dedication + To whom the piece is dedicated. @item piece Name of the piece, left flushed below the instrument @item head @@ -361,7 +504,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 @@ -415,19 +558,4 @@ positive integer, start with this value as the first page number. 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 -