2 @node Invoking LilyPond
3 @chapter Invoking LilyPond
9 * Invoking ly2dvi:: Titling LilyPond scores.
12 @cindex Invoking LilyPond
13 @cindex command line options
14 @cindex options, command line
20 lilypond [@var{option}]@dots{} @var{file}@dots{}
24 When invoked with a filename that has no extension, the @file{.ly}
25 extension is tried first. To read input from stdin, use a
26 dash @code{-} for @var{file}.
28 When @file{filename.ly} is processed it will produce
29 @file{filename.tex} as output (or @file{filename.ps} for PostScript
30 output). If @file{filename.ly} contains more than one @code{\score}
31 block, then the rest of the scores will be output in numbered files,
32 starting with @file{filename-1.tex}. Several files can be specified;
33 they will each be processed independently. @footnote{The status of
34 GUILE is not reset across invocations, so be careful not to change any
35 default settings from within Scheme .}
38 @section Command line options
40 The following options are supported:
44 @item -e,--evaluate=@var{expr}
45 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
46 Multiple @code{-e} options may be given, they will be evaluated
47 sequentially. The function @code{ly:set-option} allows for access to
48 some internal variables. Use @code{-e '(ly:option-usage')} for more
51 @item -f,--format=@var{format}
54 Output format for sheet music. Choices are @code{tex} (for @TeX{}
55 output, to be processed with plain @TeX{}, or through ly2dvi),
56 @code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript),
57 @code{scm} (for a Scheme dump), @code{sk} (for Sketch) and @code{as}
60 @strong{This option is only for developers}. Only the @TeX{} output of
61 these is usable for real work.
64 @cindex output format, setting
66 @cindex ASCII-art output
68 @cindex PostScript output
72 Show a summary of usage.
73 @item --include, -I=@var{directory}
74 Add @var{directory} to the search path for input files.
75 @cindex file searching
77 @item -i,--init=@var{file}
78 Set init file to @var{file} (default: @file{init.ly}).
81 Disable @TeX{} output. If you have a @code{\midi} definition MIDI output
83 @item -M,--dependencies
84 Output rules to be included in Makefile.
85 @item -o,--output=@var{FILE}
86 Set the default output file to @var{FILE}.
90 Disallow untrusted @code{\include} directives, in-line
91 Scheme evaluation, backslashes in @TeX{}, code.
93 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
94 long time. Do not rely on it for automatic invocation (e.g. over the
95 web). Volunteers are welcome to do a new audit.
99 Show version information
101 Be verbose: show full paths of all files read, and give timing
105 Show the warranty with which GNU LilyPond comes. (It comes with
106 @strong{NO WARRANTY}!)
109 @section Environment variables
112 For processing both the @TeX{} and the PostScript output, the
113 appropriate environment variables must be set. The following scripts
117 @item @file{buildscripts/out/lilypond-profile}
119 @item @file{buildscripts/out/lilypond-login} (for C-shells)
122 They should normally be sourced as part of the login process. If these
123 scripts are not run from the system wide login process, then you must
126 @cindex installing LilyPond
128 If you use sh, bash, or a similar shell, then add the following to
134 If you use csh, tcsh or a similar shell, then add the following to
137 source lilypond-login
140 These scripts set the following variables
143 To make sure that @TeX{} and lilypond find data files (among
144 others @file{.tex}, @file{.mf} and @file{.tfm}),
145 you have to set @code{TEXMF} to point to the lilypond data
146 file tree. A typical setting would be
148 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
153 For processing PostScript output (obtained with
154 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
155 point to the directory containing library PS files.
158 For processing PostScript output (obtained with
159 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
160 point to the directory containing PFA files.
162 When you print direct PS output, remember to send the PFA files to the
172 @cindex printing postscript
174 The binary itself recognizes the following environment variables
177 This specifies a directory where locale messages and
178 data files will be looked up by default. The directory should contain
179 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
182 This selects the language for the warning messages
186 @cindex LILYPONDPREFIX
191 @cindex reporting bugs
194 @section Reporting bugs
196 Since there is no finder's fee which doubles every year, there is no
197 need to wait for the prize money to grow. Send a bug report today!
199 Development moves quickly, so if you have a problem, it is
200 wise to check if it has been fixed in a newer release. If not, please
201 send in a bugreport. When you send us a bugreport, we have to
202 diagnose the problem and if necessary, duplicate it. To make this
203 possible, it is important that you include the following information
208 @item A sample input which causes the error. Please have mercy on the
209 developers, send a @emph{small} sample file.
211 @item The version number
213 @item A description of the platform you use (i.e., operating system,
214 system libraries, whether you downloaded a binary release)
216 @item If necessary, send a description of the bug itself. If you
217 include output a ly2dvi run, please use @code{--debug} option of
222 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
223 mailinglist, but you do not have to be subscribed to it to post.
228 If you are reading this manual in print, it is possible that the
229 website contains updates to the manual. You can find the website at
230 @uref{http://www.lilypond.org/}.
234 @node Point and click
235 @section Point and click
236 @cindex poind and click
238 Point and click lets you find notes in the input by clicking on them in
239 the Xdvi window. This makes it easier to find input that causes some
240 error in the sheet music.
242 To use it, you need the following software
244 @item A dvi viewer that supports src specials.
246 @item Xdvi, version 22.36 or newer. Available from
247 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
249 Most @TeX{} distributions ship with xdvik, which is always
250 a few versions behind the official Xdvi. To find out which Xdvi you
251 are running, try @code{xdvi -version} or @code{xdvi.bin -version}.
252 @item KDVI. A dvi viewer for KDE. You need KDVI from KDE 3.0 or
253 newer. Enable option @emph{Inverse search} in the menu @emph{Settings}.
255 Apparently, KDVI does not process PostScript specials correctly. Beams
256 and slurs will not be visible in KDVI.
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 There is also support for emacs: lilypond-mode for emacs provides
278 keyword autocompletion, indentation, LilyPond specific parenthesis matching
279 and syntax coloring, handy compile short-cuts and reading LilyPond manuals
280 using Info. If lilypond-mode
281 is not installed on your platform, then refer to the installation
282 instructions for more information.
286 @cindex lilypond-mode for emacs
287 @cindex syntax coloring
289 @item XEmacs. Xemacs is very similar to emacs.
293 @item NEdit. NEdit runs under Windows, and Unix.
294 It is available from @uref{http://www.nedit.org}.
298 @item GVim. GVim is a GUI variant of VIM, the popular VI
299 clone. It is available from @uref{http://www.vim.org}.
308 Xdvi must be configured to find the @TeX{} fonts and music
309 fonts. Refer to the Xdvi documentation for more information.
311 To use point-and-click, add one of these lines to the top of your .ly
314 #(ly:set-point-and-click 'line)
316 @cindex line-location
318 When viewing, Control-Mousebutton 1 will take you to the originating
319 spot in the @file{.ly} file. Control-Mousebutton 2 will show all
322 If you correct large files with point-and-click, be sure to start
323 correcting at the end of the file. When you start at the top, and
324 insert one line, all following locations will be off by a line.
327 For using point-and-click with emacs, add the following
328 In your emacs startup file (usually @file{~/.emacs}),
333 Make sure that the environment variable @var{XEDITOR} is set to
335 emacsclient --no-wait +%l %f
337 @cindex @var{XEDITOR}
338 If you use xemacs instead of emacs, you use @code{(gnuserve-start)} in
339 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}
341 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
342 use this argument with Xdvi's @code{-editor} option.
345 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
346 use this argument with Xdvi's @code{-editor} option.
348 If can also make your editor jump to the exact location of the note
349 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
350 20 must apply the patch @file{emacsclient.patch}. Users of version 21
351 must apply @file{server.el.patch} (version 21.2 and earlier). At the
352 top of the @code{ly} file, replace the @code{set-point-and-click} line
353 with the following line,
355 #(ly:set-point-and-click 'line-column)
357 @cindex line-colomn-location
358 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}. Vim
359 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
365 When you convert the @TeX{} file to PostScript using @code{dvips}, it
366 will complain about not finding @code{src:X:Y} files. These complaints
367 are harmless, and can be ignored.
371 @node Invoking ly2dvi
372 @section Invoking ly2dvi
374 Nicely titled output is created through a separate program:
375 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
376 nicely titled piece of sheet music, in DVI format or PostScript.
379 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
382 To have ly2dvi read from stdin, use a dash @code{-} for @var{file}.
384 Ly2dvi supports the following options:
388 Keep the temporary directory including LilyPond and ly2dvi output
389 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
390 @item -d,--dependencies
391 Write @code{Makefile} dependencies for every input file.
394 @item -I,--include=@var{dir}
395 Add @var{dir} to LilyPond's include path.
397 Produce MIDI output only.
399 Do not run LilyPond; useful for debugging ly2dvi.
400 @item -o,--output=@var{file}
401 Generate output to @var{file}. The extension of @var{file} is ignored.
402 @item -P,--postscript
403 Also generate PostScript output, using dvips. The postscript uses
404 the standard @TeX{} bitmap fonts for your printer.
406 Also generate Portable Document Format (PDF). This option will
407 generate a PS file using scalable fonts, and will run the PS file
408 through @code{ps2pdf} producing a PDF file.
411 @cindex Scalable fonts
413 If you use lilypond-book or your own wrapper files, do not use
414 @code{\usepackage[[T1]@{fontenc@}} in the file header but do not forget
415 @code{\usepackage[latin1]@{inputenc@}} if you use any other
416 non-anglosaxian characters.
419 Also generate pictures of each page, in PNG format.
421 Gzip the postscript files
423 Make a .HTML file with links to all output files.
425 Also generate a picture of the first system of the score.
434 @item -s,--set=@var{key}=@var{val}
435 Add @var{key}= @var{val} to the settings, overriding those specified
436 in the files. Possible keys: @code{language}, @code{latexheaders},
437 @code{latexpackages}, @code{latexoptions}, @code{papersize},
438 @code{pagenumber}, @code{linewidth}, @code{orientation},
441 Show version information .
445 Print even more information. This is useful when generating bugreports.
447 Show the warranty with which GNU LilyPond comes. (It comes with
448 @strong{NO WARRANTY}!)
451 @subsection Titling layout
453 Ly2dvi extracts the following header fields from the LY files to
454 generate titling. An example demonstrating all these fields is in
455 @inputfileref{input/test,ly2dvi-testpage.ly}.
459 The title of the music. Centered on top of the first page.
461 Subtitle, centered below the title.
463 Name of the poet, left flushed below the subtitle.
465 Name of the composer, right flushed below the subtitle.
467 Meter string, left flushed below the poet.
469 Name of the opus, right flushed below the composer.
471 Name of the arranger, right flushed below the opus.
473 Name of the instrument, centered below the arranger
475 To whom the piece is dedicated.
477 Name of the piece, left flushed below the instrument
479 A text to print in the header of all pages. It is not called
480 @code{header}, because @code{\header} is a reserved word in LilyPond.
482 A text to print in the footer of the first page. Default is to
483 print the standard footer also on the first page.
485 A text to print in the footer of all but the last page.
487 Line to print at the bottom of last page. The default text is ``Lily
488 was here, @var{version-number}''.
499 @subsection Additional parameters
501 Ly2dvi responds to several parameters specified in a @code{\paper}
502 section of the input file. They can be overridden by supplying a
503 @code{--set} command line option.
507 Specify La@TeX{} language: the @code{babel} package will be
508 included. Default: unset.
510 Read from the @code{\header} block.
513 Specify additional La@TeX{} headers file.
515 Normally read from the @code{\header} block. Default value: empty
518 Specify additional La@TeX{} packages file. This works cumulative,
519 so you can add multiple packages using multiple @code{-s=latexpackages} options.
520 Normally read from the @code{\header} block. Default value:
524 Specify additional options for the La@TeX{}
525 @code{\documentclass}. You can put any valid value here. This was
526 designed to allow ly2dvi to produce output for double-sided paper,
527 with balanced margins and pagenumbers on alternating sides. To achieve
528 this specify @code{twoside}
531 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
532 read from the @code{\paper} block, if set.
535 The vertical extension of the music on the page. It is normally
536 calculated automatically, based on the paper size.
539 The music line width. It is normally read from the @code{\paper}
543 The paper size (as a name, e.g. @code{a4}). It is normally read from
544 the @code{\paper} block.
547 If set to @code{no}, no page numbers will be printed. If set to a
548 positive integer, start with this value as the first page number.
552 The font encoding, should be set identical to the @code{font-encoding}
553 property in the score.