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