2 @node Invoking LilyPond
3 @chapter Invoking LilyPond
8 * 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{}
24 When invoked with a filename that has no extension, LilyPond will try
25 to add @file{.ly} as an extension first. To have LilyPond read from
26 stdin, use a dash @code{-} for @var{file}.
28 When LilyPond processes @file{filename.ly} 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 LilyPond will output the rest in numbered files, starting
32 with @file{filename-1.tex}. Several files can be specified; they will
33 each be processed independently. @footnote{The status of GUILE is not
34 reset across invocations, so be careful not to change any default
35 settings from within Scheme .}
38 @section Command line options
40 The following options are supported:
44 @item -e,--evaluate=@var{code}
45 Evaluates the Scheme @var{code} before parsing @file{.ly}
46 files. Multiple @code{-e} options may be given. They will be evaluated
47 sequentially. The function @code{set-lily-option} may be invoked to
48 set various debugging options.
52 @item -f,--format=@var{format}
55 Output format for sheet music. Choices are @code{tex} (for @TeX{}
56 output, to be processed with plain @TeX{}, or through ly2dvi),
57 @code{pdftex} for PDF@TeX{} input, @code{ps} (for PostScript),
58 @code{scm} (for a Scheme dump), @code{sk} (for Sketch) and @code{as}
61 @strong{This option is only for developers}. Only the @TeX{} output of
62 these is usable for real work. More information can be found at
63 @uref{http://lilypond.org/wiki?OutputFormats}.
66 @cindex output format, setting
68 @cindex ASCII-art output
70 @cindex PostScript output
74 Show a summary of usage.
75 @item --include, -I=@var{directory}
76 Add @var{directory} to the search path for input files.
77 @cindex file searching
79 @item -i,--init=@var{file}
80 Set init file to @var{file} (default: @file{init.ly}).
83 Disable @TeX{} output. If you have a @code{\midi} definition midi output
85 @item -M,--dependencies
86 Output rules to be included in Makefile.
87 @item -o,--output=@var{FILE}
88 Set the default output file to @var{FILE}.
92 Disallow untrusted @code{\include} directives, in-line
93 Scheme evaluation, backslashes in @TeX{}, code.
95 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
96 long time. Do not rely on it for automatic invocation (e.g. over the
97 web). Volunteers are welcome to do a new audit.
101 Show version information
103 Be verbose: show full paths of all files read, and give timing
107 Show the warranty with which GNU LilyPond comes. (It comes with
108 @strong{NO WARRANTY}!)
111 @section Environment variables
114 For processing both the @TeX{} and the PostScript output, you must
115 have appropriate environment variables set. Scripts to do this are
116 included in @file{buildscripts/out/lilypond-profile} (for sh shells)
117 and @file{buildscripts/out/lilypond-login} (for C-shells), and should
118 normally be sourced as part of your login process. If these scripts
119 are not run from the system wide login process, then you must run it
122 @cindex installing LilyPond
124 If you use sh, bash, or a similar shell, then add the following to
130 If you use csh, tcsh or a similar shell, then add the following to
133 source lilypond-login
136 These scripts set the following variables
139 To make sure that @TeX{} and lilypond find data files (among
140 others @file{.tex}, @file{.mf} and @file{.tfm}),
141 you have to set @code{TEXMF} to point to the lilypond data
142 file tree. A typical setting would be
144 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
149 For processing PostScript output (obtained with
150 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
151 point to the directory containing LilyPond PS files.
154 For processing PostScript output (obtained with
155 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
156 point to the directory containing LilyPond PFA files.
158 When you print direct PS output, remember to send the PFA files to the
168 @cindex printing postscript
170 The LilyPond binary itself recognizes the following environment variables
173 This specifies a directory where locale messages and
174 data files will be looked up by default. The directory should contain
175 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
178 This selects the language for the warning messages of LilyPond.
182 @cindex LILYPONDPREFIX
187 @cindex reporting bugs
190 @section Reporting bugs
192 Since there is no finder's fee which doubles every year, there is no
193 need to wait for the prize money to grow. So send a bug report today!
195 LilyPond development moves quickly, so if you have a problem, it is
196 wise to check if it has been fixed in a newer release. If you think
197 you found a bug, please send in a bugreport. When you send us a
198 bugreport, we have to diagnose the problem and if possible, duplicate
199 it. To make this possible, it is important that you include the
200 following information in your report:
204 @item A sample input which causes the error. Please have mercy on the
205 developers, send a @emph{small} sample file.
207 @item The version number of lilypond.
209 @item A description of the platform you use (i.e., operating system,
210 system libraries, whether you downloaded a binary release)
212 @item If necessary, send a description of the bug itself. If you
213 include output a ly2dvi run, please use @code{--verbose} option of
218 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
219 mailinglist, but you don't have to be subscribed to it to post.
224 If you are reading this manual in print, it is possible that the
225 website contains updates to the manual. You can find the lilypond
226 website at @uref{http://www.lilypond.org/}.
229 @node Titling LilyPond scores
230 @section Titling LilyPond scores
232 Nicely titled output is created through a separate program:
233 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
234 nicely titled piece of sheet music, in DVI format or PostScript.
236 @subsection Invoking ly2dvi
238 @c ly2dvi needs at least one FILE, can't act as filter yet
240 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
243 Ly2dvi supports the following options:
247 Keep the temporary directory including LilyPond and ly2dvi output
248 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
249 @item -d,--dependencies
250 Write makefile dependencies for every input file.
253 @item -I,--include=@var{dir}
254 Add @var{dir} to LilyPond's include path.
256 Produce MIDI output only.
258 Do not run LilyPond; useful for debugging ly2dvi.
259 @item -o,--output=@var{file}
260 Generate output to @var{file}. The extension of @var{file} is ignored.
261 @item -P,--postscript
262 Also generate PostScript output, using dvips. The postscript uses
263 the standard @TeX{} bitmap fonts for your printer.
265 Also generate Portable Document Format (PDF). This option will
266 generate a PS file using scalable fonts, and will run the PS file
267 through @code{ps2pdf} producing a PDF file.
270 @cindex Scalable fonts
272 If you use lilypond-book or your own wrapper files, don't use
273 @code{\usepackage[[T1]@{fontenc@}} in the file header but don't forget
274 @code{\usepackage[latin1]@{inputenc@}} if you use any other
275 non-anglosaxian characters.
278 Also generate a picture of the first system of the score.
279 @item -s,--set=@var{key}=@var{val}
280 Add @var{key}= @var{val} to the settings, overriding those specified
281 in the files. Possible keys: @code{language}, @code{latexheaders},
282 @code{latexpackages}, @code{latexoptions}, @code{papersize},
283 @code{pagenumber}, @code{linewidth}, @code{orientation},
286 Show version information
290 Show the warranty with which GNU LilyPond comes. (It comes with
291 @strong{NO WARRANTY}!)
294 @subsection Titling layout
296 Ly2dvi extracts the following header fields from the LY files to
301 The title of the music. Centered on top of the first page.
303 Subtitle, centered below the title.
305 Name of the poet, left flushed below the subtitle.
307 Name of the composer, right flushed below the subtitle.
309 Meter string, left flushed below the poet.
311 Name of the opus, right flushed below the composer.
313 Name of the arranger, right flushed below the opus.
315 Name of the instrument, centered below the arranger
317 Name of the piece, left flushed below the instrument
319 A text to print in the header of all pages. It is not called
320 @code{header}, because @code{\header} is a reserved word in LilyPond.
322 A text to print in the footer of the first page. Default is to
323 print the standard footer also on the first page.
325 A text to print in the footer of all but the last page.
327 Line to print at the bottom of last page. The default text is ``Lily
328 was here, @var{version-number}''.
339 @subsection Additional parameters
341 Ly2dvi responds to several parameters specified in a @code{\paper}
342 section of the LilyPond file. They can be overridden by supplying a
343 @code{--set} command line option.
347 Specify La@TeX{} language: the @code{babel} package will be
348 included. Default: unset.
350 Read from the @code{\header} block.
353 Specify additional La@TeX{} headers file.
355 Normally read from the @code{\header} block. Default value: empty
358 Specify additional La@TeX{} packages file. This works cumulative,
359 so you can add multiple packages using multiple @code{-s=latexpackages} options.
360 Normally read from the @code{\header} block. Default value:
364 Specify additional options for the La@TeX{}
365 @code{\documentclass}. You can put any valid value here. This was
366 designed to allow ly2dvi to produce output for double-sided paper,
367 with balanced margins and pagenumbers on alternating sides. To achieve
368 this specify @code{twoside}
371 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
372 read from the @code{\paper} block, if set.
375 The vertical extension of the music on the page. It is normally
376 calculated automatically, based on the paper size.
379 The music line width. It is normally read from the @code{\paper}
383 The paper size (as a name, e.g. @code{a4}). It is normally read from
384 the @code{\paper} block.
387 If set to @code{no}, no page numbers will be printed. If set to a
388 positive integer, start with this value as the first page number.
392 The font encoding, should be set identical to the @code{font-encoding}
393 property in the score.
396 @subsection Environment variables
400 selects the language for the warning messages of Ly2dvi and LilyPond.
402 @item GUILE_MAX_SEGMENT_SIZE
403 is an option for GUILE, the scheme interpreter; it sets the size of
404 the chunks of memory allocated by GUILE. By increasing this from its
405 default 8388608, the performance of LilyPond on large scores is