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