1 @node Invoking LilyPond
2 @chapter Invoking LilyPond
7 * Titling LilyPond scores::
10 @cindex Invoking LilyPond
11 @cindex command line options
12 @cindex options, command line
18 lilypond [@var{options}] @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{code}
44 Evaluates the Scheme @var{code} before parsing @file{.ly}
45 files. Multiple @code{-e} options may be given. They will be evaluated
46 sequentially. The function @code{set-lily-option} may be invoked to
47 set various debugging options.
51 @item -f,--format=@var{format} Output format for sheet music. Choices
52 are @code{tex} (for @TeX{} output, to be processed with plain @TeX{},
53 or through ly2dvi), @code{pdftex} for PDF@TeX{} input, @code{ps} (for
54 PostScript), @code{scm} (for a Scheme dump), and @code{as} (for
57 Unless you have special requirements, you should use @TeX{}
58 output. All other options are experimental.
60 Show a summary of usage.
61 @item --include, -I=@var{directory}
62 Add @var{directory} to the search path for input files.
63 @cindex file searching
65 @item -i,--init=@var{file}
66 Set init file to @var{file} (default: @file{init.ly}).
69 Disable @TeX{} output. If you have a @code{\midi} definition midi output
71 @item -M,--dependencies
72 Output rules to be included in Makefile.
73 @item -o,--output=@var{FILE}
74 Set the default output file to @var{FILE}.
78 Disallow untrusted @code{\include} directives, in-line
79 Scheme evaluation, backslashes in @TeX{}, code.
81 @strong{WARNING}: the @code{--safe} option has not been reviewed for a
82 long time. Do not rely on it for automatic invocation (e.g. over the
83 web). Volunteers are welcome to do a new audit.
87 Show version information
89 Be verbose: show full paths of all files read, and give timing
93 Show the warranty with which GNU LilyPond comes. (It comes with
94 @strong{NO WARRANTY}!)
97 @section Environment variables
100 For processing both the @TeX{} and the PostScript output, you must
101 have appropriate environment variables set. Scripts to do this are
102 included in @file{buildscripts/out/lilypond-profile} (for sh shells)
103 and @file{buildscripts/out/lilypond-login} (for C-shells), and should
104 normally be sourced as part of your login process. If these scripts
105 are not run from the system wide login process, then you must run it
108 @cindex installing LilyPond
110 If you use sh, bash, or a similar shell, then add the following to
116 If you use csh, tcsh or a similar shell, then add the following to
119 source lilypond-login
122 These scripts set the following variables
125 To make sure that @TeX{} and lilypond find data files (among
126 others @file{.tex}, @file{.mf} and @file{.tfm}),
127 you have to set @code{TEXMF} to point to the lilypond data
128 file tree. A typical setting would be
130 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
135 For processing PostScript output (obtained with
136 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
137 point to the directory containing LilyPond PS files.
140 For processing PostScript output (obtained with
141 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
142 point to the directory containing LilyPond PFA files.
144 When you print direct PS output, remember to send the PFA files to the
154 @cindex printing postscript
156 The LilyPond binary itself recognizes the following environment variables
159 This specifies a directory where locale messages and
160 data files will be looked up by default. The directory should contain
161 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
164 This selects the language for the warning messages of LilyPond.
168 @cindex LILYPONDPREFIX
173 @cindex reporting bugs
176 @section Reporting bugs
178 Since there is no finder's fee which doubles every year, there is no
179 need to wait for the prize money to grow. So send a bug report today!
181 LilyPond development moves quickly, so if you have a problem, it is
182 wise to check if it has been fixed in a newer release. If you think
183 you found a bug, please send in a bugreport. When you send us a
184 bugreport, we have to diagnose the problem and if possible, duplicate
185 it. To make this possible, it is important that you include the
186 following information in your report:
190 @item A sample input which causes the error. Please have mercy on the
191 developers, send a @emph{small} sample file.
193 @item The version number of lilypond.
195 @item A description of the platform you use (i.e., operating system,
196 system libraries, whether you downloaded a binary release)
198 @item If necessary, send a description of the bug itself. If you
199 include output a ly2dvi run, please use @code{--verbose} option of
204 You can send the report to @email{bug-lilypond@@gnu.org}. This is a
205 mailinglist, but you don't have to be subscribed to it to post.
210 If you are reading this manual in print, it is possible that the
211 website contains updates to the manual. You can find the lilypond
212 website at @uref{http://www.lilypond.org/}.
215 @node Titling LilyPond scores
216 @section Titling LilyPond scores
218 Nicely titled output is created through a separate program:
219 @file{ly2dvi} is a script that uses LilyPond and La@TeX{} to create a
220 nicely titled piece of sheet music, in DVI format or PostScript.
222 @subsection Invoking ly2dvi
224 @c ly2dvi needs at least one FILE, can't act as filter yet
226 ly2dvi [@var{option}]@dots{} @var{file}@dots{}
229 Ly2dvi supports the following options:
233 Keep the temporary directory including LilyPond and ly2dvi output
234 files. The temporary directory is created in the current directory as @code{ly2dvi.dir}.
235 @item -d,--dependencies
236 Write makefile dependencies for every input file.
239 @item -I,--include=@var{dir}
240 Add @var{dir} to LilyPond's include path.
242 Produce MIDI output only.
244 Do not run LilyPond; useful for debugging ly2dvi.
245 @item -o,--output=@var{file}
246 Generate output to @var{file}. The extension of @var{file} is ignored.
247 @item -P,--postscript
248 Also generate PostScript output, using dvips.
250 Also generate a picture of the first system of the score.
251 @item -s,--set=@var{key}=@var{val}
252 Add @var{key}= @var{val} to the settings, overriding those specified
253 in the files. Possible keys: @code{language}, @code{latexheaders},
254 @code{latexpackages}, @code{latexoptions}, @code{papersize},
255 @code{pagenumber}, @code{linewidth}, @code{orientation},
258 Show version information
262 Show the warranty with which GNU LilyPond comes. (It comes with
263 @strong{NO WARRANTY}!)
266 @subsection Titling layout
268 Ly2dvi extracts the following header fields from the LY files to
273 The title of the music. Centered on top of the first page.
275 Subtitle, centered below the title.
277 Name of the poet, left flushed below the subtitle.
279 Name of the composer, right flushed below the subtitle.
281 Meter string, left flushed below the poet.
283 Name of the opus, right flushed below the composer.
285 Name of the arranger, right flushed below the opus.
287 Name of the instrument, centered below the arranger
289 Name of the piece, left flushed below the instrument
291 A text to print in the header of all pages. It is not called
292 @code{header}, because @code{\header} is a reserved word in LilyPond.
294 A text to print in the footer of the first page. Default is to
295 print the standard footer also on the first page.
297 A text to print in the footer of all but the last page.
299 Line to print at the bottom of last page. The default text is ``Lily
300 was here, @var{version-number}''.
311 @subsection Additional parameters
313 Ly2dvi responds to several parameters specified in a @code{\paper}
314 section of the LilyPond file. They can be overridden by supplying a
315 @code{--set} command line option.
319 Specify La@TeX{} language: the @code{babel} package will be
320 included. Default: unset.
322 Read from the @code{\header} block.
325 Specify additional La@TeX{} headers file.
327 Normally read from the @code{\header} block. Default value: empty
330 Specify additional La@TeX{} packages file. This works cumulative,
331 so you can add multiple packages using multiple @code{-s=latexpackages} options.
332 Normally read from the @code{\header} block. Default value:
336 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}
339 Set orientation. Choices are @code{portrait} or @code{landscape}. Is
340 read from the @code{\paper} block, if set.
343 The vertical extension of the music on the page. It is normally
344 calculated automatically, based on the paper size.
347 The music line width. It is normally read from the @code{\paper}
351 The paper size (as a name, e.g. @code{a4}). It is normally read from
352 the @code{\paper} block.
355 If set to @code{no}, no page numbers will be printed.
360 The font encoding, should be set identical to the @code{font-encoding}
361 property in the score.
364 @subsection Environment variables
368 selects the language for the warning messages of Ly2dvi and LilyPond.