Documentation/user/invoking.itexi

   1 @c -*-texinfo-*-
   2 @node Invoking LilyPond
   3 @chapter Invoking LilyPond
   4
   5 This chapter details the technicalities of running LilyPond.
   6
   7
   8 @menu
   9 * Invoking lilypond::
  10 * Error messages::
  11 * Reporting bugs::
  12 * Editor support::
  13 * Point and click::
  14 * Invoking lilypond-latex::
  15 @end menu
  16
  17 @node Invoking lilypond
  18 @section Invoking lilypond
  19 @cindex Invoking LilyPond
  20 @cindex command line options
  21 @cindex options, command line
  22 @cindex switches
  23
  24
  25 The @code{lilypond} may be called as follows from the command line.
  26
  27 @example
  28         lilypond [@var{option}]@dots{} @var{file}@dots{}
  29 @end example
  30
  31
  32 When invoked with a filename that has no extension, the @file{.ly}
  33 extension is tried first.  To read input from  stdin, use a
  34 dash @code{-} for @var{file}.
  35
  36 When @file{filename.ly} is processed it will produce
  37 @file{filename.tex} as output (or @file{filename.ps} for PostScript
  38 output).  If @file{filename.ly} contains more than one @code{\score}
  39 block, then the rest of the scores will be output in numbered files,
  40 starting with @file{filename-1.tex}.  Several files can be specified;
  41 they will each be processed independently.  @footnote{The status of
  42 GUILE is not reset across invocations, so be careful not to change any
  43 system defaults from within Scheme.}
  44
  45
  46 @section Command line options
  47
  48 The following options are supported:
  49
  50 @table @code
  51
  52 @item -e,--evaluate=@var{expr}
  53 Evaluate the Scheme @var{expr} before parsing any @file{.ly} files.
  54 Multiple @code{-e} options may be given, they will be evaluated
  55 sequentially.  The function @code{ly:set-option} allows for access to
  56 some internal variables.  Use @code{-e '(ly:option-usage)'} for more
  57 information.
  58
  59 @item -f,--format=@var{format}
  60 @c
  61 @c
  62 A comma separated list of back-end output formats to use.  Choices are
  63 @code{tex} (for @TeX{} output, to be processed with La@TeX{}, and
  64 @code{ps} for PostScript.
  65
  66 Other output options are intended for developers.
  67
  68
  69 @cindex output format, setting
  70 @cindex PostScript output
  71 @cindex Scheme dump
  72
  73 @item -h,--help
  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
  78 @cindex search path
  79 @item -i,--init=@var{file}
  80 Set init file to @var{file} (default: @file{init.ly}).
  81 @item -o,--output=@var{FILE}
  82     Set the default output file to @var{FILE}.
  83 @item --ps
  84     Generate PostScript.
  85 @item --dvi
  86     Generate DVI files. In this case, the @TeX{} backend  should be
  87     specified, i.e. @code{-f tex}.
  88 @item --png
  89     Generate pictures of each page, in PNG format.  This implies @code{--ps}.
  90 @item --pdf
  91     Generate PDF. This implies @code{--ps}.
  92 @item --preview
  93     Generate an output file containing the titles and the first system
  94 of the score.
  95
  96 @item -s,--safe
  97 Do not trust the @code{.ly} input.
  98
  99 When LilyPond formatting available through a web server, the
 100 @code{--safe} @b{MUST} be passed.  This will prevent code like
 101
 102 @verbatim
 103   #(system "rm -rf /")
 104   \score {
 105     c4^#(ly:export (ly:gulp-file "/etc/passwd"))
 106   }
 107 @end verbatim
 108
 109 The @code{--safe} option works by evaluating in-line Scheme
 110 expressions in a special safe module. This safe module is derived from
 111 GUILE @file{safe-r5rs} module, but adds a number of functions of the
 112 LilyPond API. These functions are listed in @file{safe-lily.scm}.
 113
 114 In addition, @code{--safe} disallows @code{\include} directives and
 115 disables the use of backslashes in @TeX{} strings.
 116
 117 In @code{--safe} mode, it is not possible to import LilyPond variables
 118 into Scheme.
 119
 120 @item -v,--version
 121 Show version information.
 122 @item -V,--verbose
 123 Be verbose: show full paths of all  files read, and give timing
 124 information.
 125
 126 @item -w,--warranty
 127 Show the warranty with which GNU LilyPond comes. (It comes with
 128 @strong{NO WARRANTY}!)
 129 @end table
 130
 131 @section Environment variables
 132
 133
 134 For processing both the @TeX{} and the PostScript output, the
 135 appropriate environment variables must be set.  The following scripts
 136 do this:
 137
 138 @itemize @bullet
 139 @item @file{buildscripts/out/lilypond-profile}
 140 (for SH shells)
 141 @item  @file{buildscripts/out/lilypond-login} (for C-shells)
 142 @end itemize
 143
 144 They should normally be sourced as part of the login process. If these
 145 scripts are not run from the system wide login process, then you must
 146 run it yourself.
 147
 148 @cindex installing LilyPond
 149
 150 If you use sh, bash, or a similar shell, then add the following to
 151 your @file{.profile}:
 152 @example
 153         . @var{/the/path/to/}lilypond-profile
 154 @end example
 155
 156 If you use csh, tcsh or a similar shell, then add the following to
 157 your @file{~/.login}:
 158 @example
 159         source @var{/the/path/to/}lilypond-login
 160 @end example
 161
 162 Of course, in both cases, you should substitute the proper location of
 163 either script.
 164
 165 These scripts set the following variables:
 166 @table @code
 167 @item TEXMF
 168  To make sure that @TeX{} and lilypond find data files (among
 169 others @file{.tex}, @file{.mf} and @file{.tfm}),
 170 you have to set @code{TEXMF} to point to the lilypond data
 171 file tree. A typical setting would be
 172 @example
 173 @{/usr/share/lilypond/1.6.0,@{!!/usr/share/texmf@}@}
 174 @end example
 175
 176
 177 @item GS_LIB
 178 For processing PostScript output (obtained with
 179 @code{-f ps}) with Ghostscript you have to set @code{GS_LIB} to
 180 point to the directory containing library PS files.
 181
 182 @item GS_FONTPATH
 183 For processing PostScript output (obtained with
 184 @code{-f ps}) with Ghostscript you have to set @code{GS_FONTPATH} to
 185 point to the directory containing  PFA files.
 186
 187 When you print direct PS output, remember to send the PFA files to the
 188 printer as well.
 189 @end table
 190
 191
 192 @cindex ghostscript
 193 @cindex PostScript
 194 @cindex GS_FONTPATH
 195 @cindex GS_LIB
 196 @cindex TEXMF
 197 @cindex printing postscript
 198
 199 The  binary itself recognizes the following environment variables:
 200 @table @code
 201 @item LILYPONDPREFIX
 202 This specifies a directory where locale messages and
 203 data files will be looked up by default. The directory should contain
 204 subdirectories called @file{ly/}, @file{ps/}, @file{tex/}, etc.
 205
 206 @item LANG
 207 This selects the language for the warning messages.
 208 @end table
 209
 210 @cindex LANG
 211 @cindex LILYPONDPREFIX
 212
 213 @node Error messages
 214 @section Error messages
 215
 216 @cindex error messages
 217 Different error messages can appear while compiling a file:
 218
 219 @table @emph
 220 @cindex warning
 221
 222 @item Warning
 223   Something looks suspect. If you are requesting something out of the
 224 ordinary then you will understand the message, and can ignore it.
 225 However, warnings usually indicate that something is wrong with the
 226 input file.
 227
 228 @item Error
 229 Something is definitely wrong.  The current processing step (parsing,
 230 interpreting, or formatting) will be finished, but the next step will
 231 be skipped.
 232
 233 @cindex error
 234 @cindex fatal error
 235 @item Fatal error
 236 Something is definitely wrong, and LilyPond cannot continue. This
 237 happens rarely. The most usual cause is misinstalled fonts.
 238
 239 @cindex trace, Scheme
 240 @cindex call trace
 241 @cindex Scheme error
 242 @item Scheme error
 243 Errors that occur while executing Scheme code are caught by the Scheme
 244 interpreter. If running with the verbose option (@code{-V} or
 245 @code{--verbose}) then a call trace is printed of the offending
 246 function call.
 247
 248 @cindex Programming error
 249 @item Programming error
 250 There was some internal inconsistency. These error messages are
 251 intended to help the programmers and debuggers. Usually, they can be
 252 ignored. Sometimes, they come in such big quantities that they obscure
 253 other output. In this case, file a bug-report.
 254
 255 @item Aborted (core dumped)
 256 This signals a serious programming error that caused the program to
 257 crash. Such errors are considered critical. If you stumble on one,
 258 send a bugreport.
 259
 260
 261 @end table
 262
 263 @cindex errors, message format
 264 If warnings and errors can
 265 be linked to some part of the input file, then error messages have the
 266 following form
 267
 268 @example
 269   @var{filename}:@var{lineno}:@var{columnno}: @var{message}
 270   @var{offending input line}
 271 @end example
 272
 273 A line-break is inserted in offending line to indicate the column
 274 where the error was found. For example,
 275
 276 @example
 277 test.ly:2:19: error: not a duration: 5:
 278   \notes @{ c'4 e'5
 279                    g' @}
 280 @end example
 281
 282
 283 @node Reporting bugs
 284 @section Reporting bugs
 285
 286 @cindex bugs
 287 @cindex reporting bugs
 288
 289 If you have input that results in a crash or an erroneous output, then
 290 that is a bug. We try respond to bug-reports promptly, and fix them as
 291 soon as possible. For this, we need to reproduce and isolate the
 292 problem. Help us by sending a defective input file, so we can
 293 reproduce the problem. Make it small, so we can easily debug the
 294 problem. Don't forget to tell which version you use, and on which
 295 platform you run it.  Send the report to
 296 @email{bug-lilypond@@gnu.org}.
 297
 298 @node Editor support
 299 @section Editor support
 300
 301 @cindex editors
 302 @cindex vim
 303 @cindex emacs
 304 @cindex modes, editor
 305 @cindex syntax coloring
 306 @cindex coloring, syntax
 307
 308 There is support from different editors  for LilyPond.
 309
 310 @table @asis
 311 @item Emacs
 312  Emacs has a @file{lilypond-mode}, which provides keyword
 313 autocompletion, indentation, LilyPond specific parenthesis matching
 314 and syntax coloring, handy compile short-cuts and reading LilyPond
 315 manuals using Info.  If lilypond-mode is not installed on your
 316 platform, then refer to the installation instructions for more
 317 information.
 318
 319 @item VIM
 320
 321 For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
 322 syntax coloring tools. For more information, refer to the
 323 @ifhtml
 324 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
 325 @end ifhtml
 326 @ifnothtml
 327 installation instructions.
 328 @end ifnothtml
 329
 330
 331 For both editors, there is also a facility to jump in the input file
 332 to the source of errors in the graphical output. See @ref{Point and
 333 click}.
 334
 335 @item JEdit
 336
 337 There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
 338 the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
 339 information.
 340
 341 @end table
 342
 343 @node Point and click
 344 @section Point and click
 345 @cindex point and click
 346
 347 @cindex source specials
 348 @cindex specials, source
 349
 350 Point and click lets you find notes in the input by clicking on them in
 351 the Xdvi window. This makes it easier to find input that causes some
 352 error in the sheet music.
 353
 354 To use it, you need the following software:
 355 @itemize @bullet
 356 @item a dvi viewer that supports src specials:
 357 @itemize @bullet
 358 @item Xdvi, version 22.36 or newer.  Available from
 359 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
 360
 361    Most @TeX{} distributions ship with xdvik, which is always a few
 362 versions behind the official Xdvi. To find out which Xdvi you are
 363 running, try @code{xdvi -version} or @code{xdvi.bin -version}.
 364 @item KDVI.  A dvi viewer for KDE.  You need KDVI from KDE 3.0 or
 365 newer.  Enable option @emph{Inverse search} in the menu @emph{Settings}.
 366
 367 Apparently, KDVI does not process PostScript specials correctly. Beams
 368 and slurs will not be visible in KDVI.
 369
 370 @cindex Xdvi
 371 @cindex KDVI
 372 @cindex KDE
 373
 374
 375
 376 @end itemize
 377 @item an editor with a client/server interface (or a lightweight GUI
 378 editor):
 379
 380 @cindex editor
 381
 382 @itemize @bullet
 383 @item Emacs. Emacs is an extensible text-editor.  It is available from
 384 @uref{http://www.gnu.org/software/emacs/}.  You need version 21 to use
 385 column location.
 386
 387 @c move this elsewhere?
 388
 389
 390 @cindex Emacs
 391 @cindex Emacs mode
 392 @cindex lilypond-mode for Emacs
 393 @cindex syntax coloring
 394
 395 @item XEmacs. XEmacs is very similar to Emacs.
 396
 397 @cindex XEmacs
 398
 399 @item NEdit.  NEdit runs under Windows, and Unix.
 400   It is available from @uref{http://www.nedit.org}.
 401
 402 @cindex NEdit
 403
 404 @item GVim.  GVim is a GUI variant of VIM, the popular VI
 405 clone.  It is available from @uref{http://www.vim.org}.
 406
 407 @cindex GVim
 408 @cindex Vim
 409
 410 @end itemize
 411 @end itemize
 412
 413
 414 Xdvi must be configured to find the @TeX{} fonts and music
 415 fonts. Refer to the Xdvi documentation for more information.
 416
 417 To use point-and-click, add one of these lines to the top of your .ly
 418 file:
 419 @example
 420 #(ly:set-point-and-click 'line)
 421 @end example
 422 @cindex line-location
 423
 424 When viewing, Control-Mousebutton 1 will take you to the originating
 425 spot in the @file{.ly} file.  Control-Mousebutton 2 will show all
 426 clickable boxes.
 427
 428 If you correct large files with point-and-click, be sure to start
 429 correcting at the end of the file. When you start at the top, and
 430 insert one line, all following locations will be off by a line.
 431
 432 @cindex Emacs
 433 For using point-and-click with Emacs,  add the following
 434 In your Emacs startup file (usually @file{~/.emacs}):
 435 @example
 436 (server-start)
 437 @end example
 438
 439 Make sure that the environment variable @var{XEDITOR} is set to
 440 @example
 441 emacsclient --no-wait +%l %f
 442 @end example
 443 @cindex @var{XEDITOR}
 444 If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
 445 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
 446
 447 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
 448 use this argument with Xdvi's @code{-editor} option.
 449
 450 @cindex NEdit
 451 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
 452 use this argument with Xdvi's @code{-editor} option.
 453
 454 If can also make your editor jump to the exact location of the note
 455 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
 456 20 must apply the patch @file{emacsclient.patch}. Users of version 21
 457 must apply @file{server.el.patch} (version 21.2 and earlier).  At the
 458 top of the @code{ly} file, replace the @code{set-point-and-click} line
 459 with the following line:
 460 @example
 461 #(ly:set-point-and-click 'line-column)
 462 @end example
 463 @cindex line-column-location
 464 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}.  Vim
 465 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
 466
 467
 468
 469 @node Invoking lilypond-latex
 470 @section Invoking lilypond-latex
 471
 472 Before LilyPond 3.0, the @code{lilypond} program only generated music
 473 notation.  Titles and page layout was done in a separate wrapper
 474 program. For compatibility with older files, this wrapper program has
 475 been retained as @code{lilypond-latex}. It uses the LilyPond program
 476 and La@TeX{} to create a nicely titled piece of sheet music.  Use of
 477 this program is only necessary if the input file contains special
 478 La@TeX{} options or formatting codes in markup texts.
 479
 480 The @code{lilypond-latex} wrapper is invoked from the command-line as
 481 follows
 482 @example
 483         @code{lilypond-latex} [@var{option}]@dots{} @var{file}@dots{}
 484 @end example
 485
 486 To have @code{lilypond-latex} read from stdin, use a dash @code{-} for
 487 @var{file}.  The program supports the following options.
 488
 489 @cindex stdin, reading
 490
 491 @table @code
 492 @item -k,--keep
 493     Keep the temporary directory with all output
 494 files. The temporary directory is created in the current directory as @code{@code{lilypond}.dir}.
 495 @item -h,--help
 496     Print usage help.
 497 @item -I,--include=@var{dir}
 498     Add @var{dir} to LilyPond's include path.
 499 @item -o,--output=@var{file}
 500     Generate output to @var{file}.  The extension of @var{file} is ignored.
 501 @item --png
 502     Also generate pictures of each page, in PNG format.
 503 @item --preview
 504     Also generate a picture of the first system of the score.
 505
 506 @cindex preview
 507 @cindex picture
 508 @cindex bitmap
 509 @cindex pixmap
 510 @cindex thumbnail
 511 @cindex screen shot
 512
 513 @item -s,--set=@var{key}=@var{val}
 514     Add @var{key}= @var{val} to the settings, overriding those specified
 515 in the files. Possible keys: @code{language}, @code{latexheaders},
 516 @code{latexpackages}, @code{latexoptions}, @code{papersize},
 517 @code{linewidth}, @code{orientation},
 518 @code{textheight}.
 519 @item -v,--version
 520 Show version information.
 521 @item -V,--verbose
 522 Be verbose. This prints out commands as they are executed, and more
 523 information about the formatting process is printed.
 524 @item --debug
 525 Print even more information. This is useful when generating bug reports.
 526 @item -w,--warranty
 527 Show the warranty with which GNU LilyPond comes. (It comes with
 528 @strong{NO WARRANTY}!)
 529 @end table
 530
 531
 532
 533 @subsection Additional parameters
 534
 535 The @code{lilypond} program responds to several parameters specified
 536 in a @code{\paper} section of the input file. They can be overridden
 537 by supplying a @code{--set} command line option.
 538
 539 @table @code
 540 @item language
 541     Specify La@TeX{} language: the @code{babel} package will be
 542 included.  Default: unset.
 543
 544         Read from the @code{\header} block.
 545
 546 @item latexheaders
 547     Specify additional La@TeX{} headers file.
 548         Normally read from the @code{\header} block. Default value: empty.
 549
 550 @item latexpackages
 551     Specify additional La@TeX{} packages file. This works cumulative,
 552 so you can add multiple packages using multiple @code{-s=latexpackages} options.
 553        Normally read from the @code{\header} block. Default value:
 554 @code{geometry}.
 555
 556 @item latexoptions
 557     Specify additional options for the La@TeX{}
 558 @code{\documentclass}. You can put any valid value here. This was
 559 designed to allow @code{lilypond} to produce output for double-sided
 560 paper, with balanced margins and page numbers on alternating sides. To
 561 achieve this specify @code{twoside}.
 562
 563 @item orientation
 564     Set orientation. Choices are @code{portrait} or @code{landscape}. Is
 565 read from the @code{\paper} block, if set.
 566
 567 @item textheight
 568     The vertical extension of the music on the page. It is normally
 569     calculated automatically, based on the paper size.
 570
 571 @item linewidth
 572         The music line width. It is normally read from the @code{\paper}
 573 block.
 574
 575 @item papersize
 576    The paper size (as a name, e.g. @code{a4}). It is normally read from
 577 the @code{\paper} block.
 578
 579 @item fontenc
 580      The font encoding, should be set identical to the @code{font-encoding}
 581      property in the score.
 582 @end table
 583
 584
 585