2 @node Invoking LilyPond
3 @chapter Invoking LilyPond
8 * Invoking ly2dvi:: Titling LilyPond scores.
11 @cindex Invoking LilyPond
12 @cindex command line options
13 @cindex options, command line
19 lilypond [@var{option}]@dots{} @var{file}@dots{}
23 When invoked with a filename that has no extension, LilyPond will try
24 to add @file{.ly} as an extension first. To have LilyPond read from
25 stdin, use a dash @code{-} for @var{file}.
27 When LilyPond processes @file{filename.ly} it will produce
28 @file{filename.tex} as output (or @file{filename.ps} for PostScript
29 output). If @file{filename.ly} contains more than one @code{\score}
30 block, then LilyPond will output the rest in numbered files, starting
31 with @file{filename-1.tex}. Several files can be specified; they will
32 each be processed independently. @footnote{The status of GUILE is not
33 reset across invocations, so be careful not to change any default
34 settings from within Scheme .}
37 @section Command line options
39 The following options are supported:
43 @item -e,--evaluate=@var{expr}
44 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
45 Multiple @code{-e} options may be given, they will be evaluated
46 sequentially. The function @code{ly:set-option} allows for access to
47 some internal variables. Use @code{-e '(ly:option-usage')} for more
50 @item -f,--format=@var{format}
53 Output format for sheet music. Choices are @code{tex} (for @TeX{}
54 output, to be processed with plain @TeX{}, or through ly2dvi),
55 @code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript),
56 @code{scm} (for a Scheme dump), @code{sk} (for Sketch) and @code{as}
59 @strong{This option is only for developers}. Only the @TeX{} output of
60 these is usable for real work.
63 @cindex output format, setting
65 @cindex ASCII-art output
67 @cindex PostScript output
71 Show a summary of usage.
72 @item --include, -I=@var{directory}
73 Add @var{directory} to the search path for input files.
74 @cindex file searching
76 @item -i,--init=@var{file}
77 Set init file to @var{file} (default: @file{init.ly}).
80 Disable @TeX{} output. If you have a @code{\midi} definition midi output
82 @item -M,--dependencies
83 Output rules to be included in Makefile.
84 @item -o,--output=@var{FILE}
85 Set the default output file to @var{FILE}.
89 Disallow untrusted @code{\include} directives, in-line
90 Scheme evaluation, backslashes in @TeX{}, code.
92 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
93 long time. Do not rely on it for automatic invocation (e.g. over the
94 web). Volunteers are welcome to do a new audit.
98 Show version information
100 Be verbose: show full paths of all files read, and give timing
104 Show the warranty with which GNU LilyPond comes. (It comes with
105 @strong{NO WARRANTY}!)
108 @section Environment variables
111 For processing both the @TeX{} and the PostScript output, you must
112 have appropriate environment variables set. The following scripts do
116 @item @file{buildscripts/out/lilypond-profile}
118 @item @file{buildscripts/out/lilypond-login} (for C-shells)
121 They should normally be sourced as part of your login process. If
122 these scripts are not run from the system wide login process, then you
123 must run it yourself.
125 @cindex installing LilyPond
127 If you use sh, bash, or a similar shell, then add the following to
133 If you use csh, tcsh or a similar shell, then add the following to
136 source lilypond-login
139 These scripts set the following variables
142 To make sure that @TeX{} and lilypond find data files (among
143 others @file{.tex}, @file{.mf} and @file{.tfm}),
144 you have to set @code{TEXMF} to point to the lilypond data
145 file tree. A typical setting would be
147 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
152 For processing PostScript output (obtained with
153 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
154 point to the directory containing LilyPond PS files.
157 For processing PostScript output (obtained with
158 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
159 point to the directory containing LilyPond PFA files.
161 When you print direct PS output, remember to send the PFA files to the
171 @cindex printing postscript
173 The LilyPond binary itself recognizes the following environment variables
176 This specifies a directory where locale messages and
177 data files will be looked up by default. The directory should contain
178 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
181 This selects the language for the warning messages of LilyPond.
185 @cindex LILYPONDPREFIX
190 @cindex reporting bugs
193 @section Reporting bugs
195 Since there is no finder's fee which doubles every year, there is no
196 need to wait for the prize money to grow. Send a bug report today!
198 LilyPond development moves quickly, so if you have a problem, it is
199 wise to check if it has been fixed in a newer release. If not, please
200 send in a bugreport. When you send us a bugreport, we have to
201 diagnose the problem and if necessary, duplicate it. To make this
202 possible, it is important that you include the following information
207 @item A sample input which causes the error. Please have mercy on the
208 developers, send a @emph{small} sample file.
210 @item The version number
212 @item A description of the platform you use (i.e., operating system,
213 system libraries, whether you downloaded a binary release)
215 @item If necessary, send a description of the bug itself. If you
216 include output a ly2dvi run, please use @code{--debug} option of
221 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
222 mailinglist, but you do not have to be subscribed to it to post.
227 If you are reading this manual in print, it is possible that the
228 website contains updates to the manual. You can find the website at
229 @uref{http://www.lilypond.org/}.
232 @c . {Point and click}
237 @node Point and click
238 @subsection Point and click
239 @cindex poind and click
241 Point and click lets you find notes in the input by clicking on them in
242 the Xdvi window. This makes it easier to find input that causes some
243 error in the sheet music.
245 To use it, you need the following software
247 @item A dvi viewer that supports src specials.
249 @item Xdvi, version 22.36 or newer. Available from
250 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
252 Most @TeX{} distributions ship with xdvik, which is always
253 a few versions behind the official Xdvi. To find out which Xdvi you
254 are running, try @code{xdvi -version} or @code{xdvi.bin -version}.
255 @item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
256 newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
265 @item An editor with a client/server interface (or a lightweight GUI
271 @item Emacs. Emacs is an extensible text-editor. It is available from
272 @uref{http://www.gnu.org/software/emacs/}. You need version 21 to use
275 @c move this elsewhere?
277 LilyPond also comes with support files for emacs: lilypond-mode for
278 emacs provides indentation, autocompletion, syntax coloring, handy
279 compile short-cuts and reading Info documents of lilypond inside emacs.
280 If lilypond-mode is not installed on your platform,
281 then refer to the installation instructions for more information.
285 @cindex lilypond-mode for emacs
286 @cindex syntax coloring
288 @item XEmacs. Xemacs is very similar to emacs.
292 @item NEdit. NEdit runs under Windows, and Unix.
293 It is available from @uref{http://www.nedit.org}.
297 @item GVim. GVim is a GUI variant of VIM, the popular VI
298 clone. It is available from @uref{http://www.vim.org}.
307 Xdvi must be configured to find the @TeX{} fonts and music
308 fonts. Refer to the Xdvi documentation for more information.
310 To use point-and-click, add one of these lines to the top of your .ly
313 #(ly:set-point-and-click 'line)
315 @cindex line-location
317 When viewing, Control-Mousebutton 1 will take you to the originating
318 spot in the @file{.ly} file. Control-Mousebutton 2 will show all
321 If you correct large files with point-and-click, be sure to start
322 correcting at the end of the file. When you start at the top, and
323 insert one line, all following locations will be off by a line.
326 For using point-and-click with emacs, add the following
327 In your emacs startup file (usually @file{~/.emacs}),
332 Make sure that the environment variable @var{XEDITOR} is set to
334 emacsclient --no-wait +%l %f
336 @cindex @var{XEDITOR}
337 If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in
338 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}
340 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
341 use this argument with Xdvi's @code{-editor} option.
344 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
345 use this argument with Xdvi's @code{-editor} option.
347 If can also make your editor jump to the exact location of the note
348 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
349 20 must apply the patch @file{emacsclient.patch}. Users of version 21
350 must apply @file{server.el.patch} (version 21.2 and earlier). At the
351 top of the @code{ly} file, replace the @code{set-point-and-click} line
352 with the following line,
354 #(ly:set-point-and-click 'line-column)
356 @cindex line-colomn-location
357 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
358 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
364 When you convert the @TeX{} file to PostScript using @code{dvips}, it
365 will complain about not finding @code{src:X:Y} files. These complaints
366 are harmless, and can be ignored.
370 @node Invoking ly2dvi
371 @section Invoking ly2dvi
373 Nicely titled output is created through a separate program:
374 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
375 nicely titled piece of sheet music, in DVI format or PostScript.
378 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
381 To have ly2dvi read from stdin, use a dash @code{-} for @var{file}.
383 Ly2dvi supports the following options:
387 Keep the temporary directory including LilyPond and ly2dvi output
388 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
389 @item -d,--dependencies
390 Write @code{Makefile} dependencies for every input file.
393 @item -I,--include=@var{dir}
394 Add @var{dir} to LilyPond's include path.
396 Produce MIDI output only.
398 Do not run LilyPond; useful for debugging ly2dvi.
399 @item -o,--output=@var{file}
400 Generate output to @var{file}. The extension of @var{file} is ignored.
401 @item -P,--postscript
402 Also generate PostScript output, using dvips. The postscript uses
403 the standard @TeX{} bitmap fonts for your printer.
405 Also generate Portable Document Format (PDF). This option will
406 generate a PS file using scalable fonts, and will run the PS file
407 through @code{ps2pdf} producing a PDF file.
410 @cindex Scalable fonts
412 If you use lilypond-book or your own wrapper files, do not use
413 @code{\usepackage[[T1]@{fontenc@}} in the file header but do not forget
414 @code{\usepackage[latin1]@{inputenc@}} if you use any other
415 non-anglosaxian characters.
418 Also generate pictures of each page, in PNG format.
420 Gzip the postscript files
422 Make a .HTML file with links to all output files.
424 Also generate a picture of the first system of the score.
433 @item -s,--set=@var{key}=@var{val}
434 Add @var{key}= @var{val} to the settings, overriding those specified
435 in the files. Possible keys: @code{language}, @code{latexheaders},
436 @code{latexpackages}, @code{latexoptions}, @code{papersize},
437 @code{pagenumber}, @code{linewidth}, @code{orientation},
440 Show version information .
444 Print even more information. This is useful when generating bugreports.
446 Show the warranty with which GNU LilyPond comes. (It comes with
447 @strong{NO WARRANTY}!)
450 @subsection Titling layout
452 Ly2dvi extracts the following header fields from the LY files to
453 generate titling. An example demonstrating all these fields is in
454 @inputfileref{input/test,ly2dvi-testpage.ly}.
458 The title of the music. Centered on top of the first page.
460 Subtitle, centered below the title.
462 Name of the poet, left flushed below the subtitle.
464 Name of the composer, right flushed below the subtitle.
466 Meter string, left flushed below the poet.
468 Name of the opus, right flushed below the composer.
470 Name of the arranger, right flushed below the opus.
472 Name of the instrument, centered below the arranger
474 To whom the piece is dedicated.
476 Name of the piece, left flushed below the instrument
478 A text to print in the header of all pages. It is not called
479 @code{header}, because @code{\header} is a reserved word in LilyPond.
481 A text to print in the footer of the first page. Default is to
482 print the standard footer also on the first page.
484 A text to print in the footer of all but the last page.
486 Line to print at the bottom of last page. The default text is ``Lily
487 was here, @var{version-number}''.
498 @subsection Additional parameters
500 Ly2dvi responds to several parameters specified in a @code{\paper}
501 section of the LilyPond file. They can be overridden by supplying a
502 @code{--set} command line option.
506 Specify La@TeX{} language: the @code{babel} package will be
507 included. Default: unset.
509 Read from the @code{\header} block.
512 Specify additional La@TeX{} headers file.
514 Normally read from the @code{\header} block. Default value: empty
517 Specify additional La@TeX{} packages file. This works cumulative,
518 so you can add multiple packages using multiple @code{-s=latexpackages} options.
519 Normally read from the @code{\header} block. Default value:
523 Specify additional options for the La@TeX{}
524 @code{\documentclass}. You can put any valid value here. This was
525 designed to allow ly2dvi to produce output for double-sided paper,
526 with balanced margins and pagenumbers on alternating sides. To achieve
527 this specify @code{twoside}
530 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
531 read from the @code{\paper} block, if set.
534 The vertical extension of the music on the page. It is normally
535 calculated automatically, based on the paper size.
538 The music line width. It is normally read from the @code{\paper}
542 The paper size (as a name, e.g. @code{a4}). It is normally read from
543 the @code{\paper} block.
546 If set to @code{no}, no page numbers will be printed. If set to a
547 positive integer, start with this value as the first page number.
551 The font encoding, should be set identical to the @code{font-encoding}
552 property in the score.
555 @subsection Environment variables
559 selects the language for the warning messages of Ly2dvi and LilyPond.
561 @item GUILE_MAX_SEGMENT_SIZE
562 is an option for GUILE, the scheme interpreter; it sets the size of
563 the chunks of memory allocated by GUILE. By increasing this from its
564 default 8388608, the performance of LilyPond on large scores is