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 @cindex output format, setting
63 @cindex ASCII-art output
65 @cindex PostScript output
68 Unless you have special requirements, you should use @TeX{}
69 output. All other options are experimental.
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. Scripts to do this are
113 included in @file{buildscripts/out/lilypond-profile} (for sh shells)
114 and @file{buildscripts/out/lilypond-login} (for C-shells), and should
115 normally be sourced as part of your login process. If these scripts
116 are not run from the system wide login process, then you must run it
119 @cindex installing LilyPond
121 If you use sh, bash, or a similar shell, then add the following to
127 If you use csh, tcsh or a similar shell, then add the following to
130 source lilypond-login
133 These scripts set the following variables
136 To make sure that @TeX{} and lilypond find data files (among
137 others @file{.tex}, @file{.mf} and @file{.tfm}),
138 you have to set @code{TEXMF} to point to the lilypond data
139 file tree. A typical setting would be
141 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
146 For processing PostScript output (obtained with
147 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
148 point to the directory containing LilyPond PS files.
151 For processing PostScript output (obtained with
152 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
153 point to the directory containing LilyPond PFA files.
155 When you print direct PS output, remember to send the PFA files to the
165 @cindex printing postscript
167 The LilyPond binary itself recognizes the following environment variables
170 This specifies a directory where locale messages and
171 data files will be looked up by default. The directory should contain
172 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
175 This selects the language for the warning messages of LilyPond.
179 @cindex LILYPONDPREFIX
184 @cindex reporting bugs
187 @section Reporting bugs
189 Since there is no finder's fee which doubles every year, there is no
190 need to wait for the prize money to grow. So send a bug report today!
192 LilyPond development moves quickly, so if you have a problem, it is
193 wise to check if it has been fixed in a newer release. If you think
194 you found a bug, please send in a bugreport. When you send us a
195 bugreport, we have to diagnose the problem and if possible, duplicate
196 it. To make this possible, it is important that you include the
197 following information in your report:
201 @item A sample input which causes the error. Please have mercy on the
202 developers, send a @emph{small} sample file.
204 @item The version number of lilypond.
206 @item A description of the platform you use (i.e., operating system,
207 system libraries, whether you downloaded a binary release)
209 @item If necessary, send a description of the bug itself. If you
210 include output a ly2dvi run, please use @code{--verbose} option of
215 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
216 mailinglist, but you don't have to be subscribed to it to post.
221 If you are reading this manual in print, it is possible that the
222 website contains updates to the manual. You can find the lilypond
223 website at @uref{http://www.lilypond.org/}.
226 @node Titling LilyPond scores
227 @section Titling LilyPond scores
229 Nicely titled output is created through a separate program:
230 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
231 nicely titled piece of sheet music, in DVI format or PostScript.
233 @subsection Invoking ly2dvi
235 @c ly2dvi needs at least one FILE, can't act as filter yet
237 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
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.
261 Also generate a picture of the first system of the score.
262 @item -s,--set=@var{key}=@var{val}
263 Add @var{key}= @var{val} to the settings, overriding those specified
264 in the files. Possible keys: @code{language}, @code{latexheaders},
265 @code{latexpackages}, @code{latexoptions}, @code{papersize},
266 @code{pagenumber}, @code{linewidth}, @code{orientation},
269 Show version information
273 Show the warranty with which GNU LilyPond comes. (It comes with
274 @strong{NO WARRANTY}!)
277 @subsection Titling layout
279 Ly2dvi extracts the following header fields from the LY files to
284 The title of the music. Centered on top of the first page.
286 Subtitle, centered below the title.
288 Name of the poet, left flushed below the subtitle.
290 Name of the composer, right flushed below the subtitle.
292 Meter string, left flushed below the poet.
294 Name of the opus, right flushed below the composer.
296 Name of the arranger, right flushed below the opus.
298 Name of the instrument, centered below the arranger
300 Name of the piece, left flushed below the instrument
302 A text to print in the header of all pages. It is not called
303 @code{header}, because @code{\header} is a reserved word in LilyPond.
305 A text to print in the footer of the first page. Default is to
306 print the standard footer also on the first page.
308 A text to print in the footer of all but the last page.
310 Line to print at the bottom of last page. The default text is ``Lily
311 was here, @var{version-number}''.
322 @subsection Additional parameters
324 Ly2dvi responds to several parameters specified in a @code{\paper}
325 section of the LilyPond file. They can be overridden by supplying a
326 @code{--set} command line option.
330 Specify La@TeX{} language: the @code{babel} package will be
331 included. Default: unset.
333 Read from the @code{\header} block.
336 Specify additional La@TeX{} headers file.
338 Normally read from the @code{\header} block. Default value: empty
341 Specify additional La@TeX{} packages file. This works cumulative,
342 so you can add multiple packages using multiple @code{-s=latexpackages} options.
343 Normally read from the @code{\header} block. Default value:
347 Specify additional options for the La@TeX{} @code{\documentclass}. You can put any valid value here. This was designed to allow ly2dvi to produce output for double-sided paper, with balanced margins and pagenumbers on alternating sides. To achieve this specify @code{twoside}
350 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
351 read from the @code{\paper} block, if set.
354 The vertical extension of the music on the page. It is normally
355 calculated automatically, based on the paper size.
358 The music line width. It is normally read from the @code{\paper}
362 The paper size (as a name, e.g. @code{a4}). It is normally read from
363 the @code{\paper} block.
366 If set to @code{no}, no page numbers will be printed.
371 The font encoding, should be set identical to the @code{font-encoding}
372 property in the score.
375 @subsection Environment variables
379 selects the language for the warning messages of Ly2dvi and LilyPond.