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