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. The following scripts do
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 your login process. If
123 these scripts are not run from the system wide login process, then you
124 must run it yourself.
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 LilyPond 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 LilyPond PFA files.
162 When you print direct PS output, remember to send the PFA files to the
172 @cindex printing postscript
174 The LilyPond 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 of LilyPond.
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. So send a bug report today!
199 LilyPond 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 you think
201 you found a bug, please send in a bugreport. When you send us a
202 bugreport, we have to diagnose the problem and if possible, duplicate
203 it. To make this possible, it is important that you include the
204 following information in your report:
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 of lilypond.
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{--verbose} option of
222 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
223 mailinglist, but you don't 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 lilypond
230 website at @uref{http://www.lilypond.org/}.
233 @node Invoking ly2dvi
234 @section Invoking ly2dvi
236 Nicely titled output is created through a separate program:
237 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
238 nicely titled piece of sheet music, in DVI format or PostScript.
241 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
244 To have ly2dvi read from stdin, use a dash @code{-} for @var{file}.
246 Ly2dvi supports the following options:
250 Keep the temporary directory including LilyPond and ly2dvi output
251 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
252 @item -d,--dependencies
253 Write makefile dependencies for every input file.
256 @item -I,--include=@var{dir}
257 Add @var{dir} to LilyPond's include path.
259 Produce MIDI output only.
261 Do not run LilyPond; useful for debugging ly2dvi.
262 @item -o,--output=@var{file}
263 Generate output to @var{file}. The extension of @var{file} is ignored.
264 @item -P,--postscript
265 Also generate PostScript output, using dvips. The postscript uses
266 the standard @TeX{} bitmap fonts for your printer.
268 Also generate Portable Document Format (PDF). This option will
269 generate a PS file using scalable fonts, and will run the PS file
270 through @code{ps2pdf} producing a PDF file.
273 @cindex Scalable fonts
275 If you use lilypond-book or your own wrapper files, don't use
276 @code{\usepackage[[T1]@{fontenc@}} in the file header but don't forget
277 @code{\usepackage[latin1]@{inputenc@}} if you use any other
278 non-anglosaxian characters.
281 Also generate a picture of the first system of the score.
282 @item -s,--set=@var{key}=@var{val}
283 Add @var{key}= @var{val} to the settings, overriding those specified
284 in the files. Possible keys: @code{language}, @code{latexheaders},
285 @code{latexpackages}, @code{latexoptions}, @code{papersize},
286 @code{pagenumber}, @code{linewidth}, @code{orientation},
289 Show version information
293 Show the warranty with which GNU LilyPond comes. (It comes with
294 @strong{NO WARRANTY}!)
297 @subsection Titling layout
299 Ly2dvi extracts the following header fields from the LY files to
304 The title of the music. Centered on top of the first page.
306 Subtitle, centered below the title.
308 Name of the poet, left flushed below the subtitle.
310 Name of the composer, right flushed below the subtitle.
312 Meter string, left flushed below the poet.
314 Name of the opus, right flushed below the composer.
316 Name of the arranger, right flushed below the opus.
318 Name of the instrument, centered below the arranger
322 Name of the piece, left flushed below the instrument
324 A text to print in the header of all pages. It is not called
325 @code{header}, because @code{\header} is a reserved word in LilyPond.
327 A text to print in the footer of the first page. Default is to
328 print the standard footer also on the first page.
330 A text to print in the footer of all but the last page.
332 Line to print at the bottom of last page. The default text is ``Lily
333 was here, @var{version-number}''.
344 @subsection Additional parameters
346 Ly2dvi responds to several parameters specified in a @code{\paper}
347 section of the LilyPond file. They can be overridden by supplying a
348 @code{--set} command line option.
352 Specify La@TeX{} language: the @code{babel} package will be
353 included. Default: unset.
355 Read from the @code{\header} block.
358 Specify additional La@TeX{} headers file.
360 Normally read from the @code{\header} block. Default value: empty
363 Specify additional La@TeX{} packages file. This works cumulative,
364 so you can add multiple packages using multiple @code{-s=latexpackages} options.
365 Normally read from the @code{\header} block. Default value:
369 Specify additional options for the La@TeX{}
370 @code{\documentclass}. You can put any valid value here. This was
371 designed to allow ly2dvi to produce output for double-sided paper,
372 with balanced margins and pagenumbers on alternating sides. To achieve
373 this specify @code{twoside}
376 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
377 read from the @code{\paper} block, if set.
380 The vertical extension of the music on the page. It is normally
381 calculated automatically, based on the paper size.
384 The music line width. It is normally read from the @code{\paper}
388 The paper size (as a name, e.g. @code{a4}). It is normally read from
389 the @code{\paper} block.
392 If set to @code{no}, no page numbers will be printed. If set to a
393 positive integer, start with this value as the first page number.
397 The font encoding, should be set identical to the @code{font-encoding}
398 property in the score.
401 @subsection Environment variables
405 selects the language for the warning messages of Ly2dvi and LilyPond.
407 @item GUILE_MAX_SEGMENT_SIZE
408 is an option for GUILE, the scheme interpreter; it sets the size of
409 the chunks of memory allocated by GUILE. By increasing this from its
410 default 8388608, the performance of LilyPond on large scores is