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. More information can be found at
61 @uref{http://lilypond.org/wiki?OutputFormats}.
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, you must
113 have appropriate environment variables set. Scripts to do this are
114 included in @file{buildscripts/out/lilypond-profile} (for sh shells)
115 and @file{buildscripts/out/lilypond-login} (for C-shells), and should
116 normally be sourced as part of your login process. If these scripts
117 are not run from the system wide login process, then you must run it
120 @cindex installing LilyPond
122 If you use sh, bash, or a similar shell, then add the following to
128 If you use csh, tcsh or a similar shell, then add the following to
131 source lilypond-login
134 These scripts set the following variables
137 To make sure that @TeX{} and lilypond find data files (among
138 others @file{.tex}, @file{.mf} and @file{.tfm}),
139 you have to set @code{TEXMF} to point to the lilypond data
140 file tree. A typical setting would be
142 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
147 For processing PostScript output (obtained with
148 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
149 point to the directory containing LilyPond PS files.
152 For processing PostScript output (obtained with
153 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
154 point to the directory containing LilyPond PFA files.
156 When you print direct PS output, remember to send the PFA files to the
166 @cindex printing postscript
168 The LilyPond binary itself recognizes the following environment variables
171 This specifies a directory where locale messages and
172 data files will be looked up by default. The directory should contain
173 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
176 This selects the language for the warning messages of LilyPond.
180 @cindex LILYPONDPREFIX
185 @cindex reporting bugs
188 @section Reporting bugs
190 Since there is no finder's fee which doubles every year, there is no
191 need to wait for the prize money to grow. So send a bug report today!
193 LilyPond development moves quickly, so if you have a problem, it is
194 wise to check if it has been fixed in a newer release. If you think
195 you found a bug, please send in a bugreport. When you send us a
196 bugreport, we have to diagnose the problem and if possible, duplicate
197 it. To make this possible, it is important that you include the
198 following information in your report:
202 @item A sample input which causes the error. Please have mercy on the
203 developers, send a @emph{small} sample file.
205 @item The version number of lilypond.
207 @item A description of the platform you use (i.e., operating system,
208 system libraries, whether you downloaded a binary release)
210 @item If necessary, send a description of the bug itself. If you
211 include output a ly2dvi run, please use @code{--verbose} option of
216 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
217 mailinglist, but you don't have to be subscribed to it to post.
222 If you are reading this manual in print, it is possible that the
223 website contains updates to the manual. You can find the lilypond
224 website at @uref{http://www.lilypond.org/}.
227 @node Invoking ly2dvi
228 @section Invoking ly2dvi
230 Nicely titled output is created through a separate program:
231 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
232 nicely titled piece of sheet music, in DVI format or PostScript.
235 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
238 To have ly2dvi read from stdin, use a dash @code{-} for @var{file}.
240 Ly2dvi supports the following options:
244 Keep the temporary directory including LilyPond and ly2dvi output
245 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
246 @item -d,--dependencies
247 Write makefile dependencies for every input file.
250 @item -I,--include=@var{dir}
251 Add @var{dir} to LilyPond's include path.
253 Produce MIDI output only.
255 Do not run LilyPond; useful for debugging ly2dvi.
256 @item -o,--output=@var{file}
257 Generate output to @var{file}. The extension of @var{file} is ignored.
258 @item -P,--postscript
259 Also generate PostScript output, using dvips. The postscript uses
260 the standard @TeX{} bitmap fonts for your printer.
262 Also generate Portable Document Format (PDF). This option will
263 generate a PS file using scalable fonts, and will run the PS file
264 through @code{ps2pdf} producing a PDF file.
267 @cindex Scalable fonts
269 If you use lilypond-book or your own wrapper files, don't use
270 @code{\usepackage[[T1]@{fontenc@}} in the file header but don't forget
271 @code{\usepackage[latin1]@{inputenc@}} if you use any other
272 non-anglosaxian characters.
275 Also generate a picture of the first system of the score.
276 @item -s,--set=@var{key}=@var{val}
277 Add @var{key}= @var{val} to the settings, overriding those specified
278 in the files. Possible keys: @code{language}, @code{latexheaders},
279 @code{latexpackages}, @code{latexoptions}, @code{papersize},
280 @code{pagenumber}, @code{linewidth}, @code{orientation},
283 Show version information
287 Show the warranty with which GNU LilyPond comes. (It comes with
288 @strong{NO WARRANTY}!)
291 @subsection Titling layout
293 Ly2dvi extracts the following header fields from the LY files to
298 The title of the music. Centered on top of the first page.
300 Subtitle, centered below the title.
302 Name of the poet, left flushed below the subtitle.
304 Name of the composer, right flushed below the subtitle.
306 Meter string, left flushed below the poet.
308 Name of the opus, right flushed below the composer.
310 Name of the arranger, right flushed below the opus.
312 Name of the instrument, centered below the arranger
314 Name of the piece, left flushed below the instrument
316 A text to print in the header of all pages. It is not called
317 @code{header}, because @code{\header} is a reserved word in LilyPond.
319 A text to print in the footer of the first page. Default is to
320 print the standard footer also on the first page.
322 A text to print in the footer of all but the last page.
324 Line to print at the bottom of last page. The default text is ``Lily
325 was here, @var{version-number}''.
336 @subsection Additional parameters
338 Ly2dvi responds to several parameters specified in a @code{\paper}
339 section of the LilyPond file. They can be overridden by supplying a
340 @code{--set} command line option.
344 Specify La@TeX{} language: the @code{babel} package will be
345 included. Default: unset.
347 Read from the @code{\header} block.
350 Specify additional La@TeX{} headers file.
352 Normally read from the @code{\header} block. Default value: empty
355 Specify additional La@TeX{} packages file. This works cumulative,
356 so you can add multiple packages using multiple @code{-s=latexpackages} options.
357 Normally read from the @code{\header} block. Default value:
361 Specify additional options for the La@TeX{}
362 @code{\documentclass}. You can put any valid value here. This was
363 designed to allow ly2dvi to produce output for double-sided paper,
364 with balanced margins and pagenumbers on alternating sides. To achieve
365 this specify @code{twoside}
368 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
369 read from the @code{\paper} block, if set.
372 The vertical extension of the music on the page. It is normally
373 calculated automatically, based on the paper size.
376 The music line width. It is normally read from the @code{\paper}
380 The paper size (as a name, e.g. @code{a4}). It is normally read from
381 the @code{\paper} block.
384 If set to @code{no}, no page numbers will be printed. If set to a
385 positive integer, start with this value as the first page number.
389 The font encoding, should be set identical to the @code{font-encoding}
390 property in the score.
393 @subsection Environment variables
397 selects the language for the warning messages of Ly2dvi and LilyPond.
399 @item GUILE_MAX_SEGMENT_SIZE
400 is an option for GUILE, the scheme interpreter; it sets the size of
401 the chunks of memory allocated by GUILE. By increasing this from its
402 default 8388608, the performance of LilyPond on large scores is