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 @item Aborted (core dumped)
 431 This signals a serious programming error that caused the program to
 432 crash. Such errors are considered critical. If you stumble on one,
 433 send a bugreport.
 434
 435
 436 @end table
 437
 438 @cindex errors, message format
 439 If warnings and errors can
 440 be linked to some part of the input file, then error messages have the
 441 following form
 442
 443 @example
 444   @var{filename}:@var{lineno}:@var{columnno}: @var{message}
 445   @var{offending input line}
 446 @end example
 447
 448 A line-break is inserted in offending line to indicate the column
 449 where the error was found. For example,
 450
 451 @example
 452 test.ly:2:19: error: not a duration: 5:
 453   \notes @{ c'4 e'5
 454                    g' @}
 455 @end example
 456
 457
 458 @node Reporting bugs
 459 @section Reporting bugs
 460
 461 @cindex bugs
 462 @cindex reporting bugs
 463
 464 If you have input that results in a crash or an erroneous output, then
 465 that is a bug. We try respond to bug-reports promptly, and fix them as
 466 soon as possible. For this, we need to reproduce and isolate the
 467 problem. Help us by sending a defective input file, so we can
 468 reproduce the problem. Make it small, so we can easily debug the
 469 problem. Don't forget to tell which version you use, and on which
 470 platform you run it.  Send the report to
 471 @email{bug-lilypond@@gnu.org}.
 472
 473 @node Editor support
 474 @section Editor support
 475
 476 @cindex editors
 477 @cindex vim
 478 @cindex emacs
 479 @cindex modes, editor
 480 @cindex syntax coloring
 481 @cindex coloring, syntax
 482
 483 There is support from different editors  for LilyPond.
 484
 485 @table @asis
 486 @item Emacs
 487  Emacs has a @file{lilypond-mode}, which provides keyword
 488 autocompletion, indentation, LilyPond specific parenthesis matching
 489 and syntax coloring, handy compile short-cuts and reading LilyPond
 490 manuals using Info.  If lilypond-mode is not installed on your
 491 platform, then refer to the installation instructions for more
 492 information.
 493
 494 @item VIM
 495
 496 For @uref{http://www.vim.org,VIM}, a vimrc is supplied, along with
 497 syntax coloring tools. For more information, refer to the
 498 @ifhtml
 499 @uref{../../../topdocs/out-www/INSTALL.html,installation instructions}.
 500 @end ifhtml
 501 @ifnothtml
 502 installation instructions.
 503 @end ifnothtml
 504
 505
 506 For both editors, there is also a facility to jump in the input file
 507 to the source of errors in the graphical output. See @ref{Point and
 508 click}.
 509
 510 @item JEdit
 511
 512 There exists a plugin for @uref{http://www.jedit.org/,jEdit}. Refer to
 513 the @uref{http://lily4jedit.sourceforge.net,plugin website} for more
 514 information.
 515
 516 @end table
 517
 518 @node Point and click
 519 @section Point and click
 520 @cindex point and click
 521
 522 @cindex source specials
 523 @cindex specials, source
 524
 525 Point and click lets you find notes in the input by clicking on them in
 526 the Xdvi window. This makes it easier to find input that causes some
 527 error in the sheet music.
 528
 529 To use it, you need the following software:
 530 @itemize @bullet
 531 @item a dvi viewer that supports src specials:
 532 @itemize @bullet
 533 @item Xdvi, version 22.36 or newer.  Available from
 534 @uref{ftp://ftp.math.berkeley.edu/pub/Software/TeX/xdvi.tar.gz,ftp.math.berkeley.edu}.
 535
 536    Most @TeX{} distributions ship with xdvik, which is always a few
 537 versions behind the official Xdvi. To find out which Xdvi you are
 538 running, try @code{xdvi -version} or @code{xdvi.bin -version}.
 539 @item KDVI.  A dvi viewer for KDE.  You need KDVI from KDE 3.0 or
 540 newer.  Enable option @emph{Inverse search} in the menu @emph{Settings}.
 541
 542 Apparently, KDVI does not process PostScript specials correctly. Beams
 543 and slurs will not be visible in KDVI.
 544
 545 @cindex Xdvi
 546 @cindex KDVI
 547 @cindex KDE
 548
 549
 550
 551 @end itemize
 552 @item an editor with a client/server interface (or a lightweight GUI
 553 editor):
 554
 555 @cindex editor
 556
 557 @itemize @bullet
 558 @item Emacs. Emacs is an extensible text-editor.  It is available from
 559 @uref{http://www.gnu.org/software/emacs/}.  You need version 21 to use
 560 column location.
 561
 562 @c move this elsewhere?
 563
 564
 565 @cindex Emacs
 566 @cindex Emacs mode
 567 @cindex lilypond-mode for Emacs
 568 @cindex syntax coloring
 569
 570 @item XEmacs. XEmacs is very similar to Emacs.
 571
 572 @cindex XEmacs
 573
 574 @item NEdit.  NEdit runs under Windows, and Unix.
 575   It is available from @uref{http://www.nedit.org}.
 576
 577 @cindex NEdit
 578
 579 @item GVim.  GVim is a GUI variant of VIM, the popular VI
 580 clone.  It is available from @uref{http://www.vim.org}.
 581
 582 @cindex GVim
 583 @cindex Vim
 584
 585 @end itemize
 586 @end itemize
 587
 588
 589 Xdvi must be configured to find the @TeX{} fonts and music
 590 fonts. Refer to the Xdvi documentation for more information.
 591
 592 To use point-and-click, add one of these lines to the top of your .ly
 593 file:
 594 @example
 595 #(ly:set-point-and-click 'line)
 596 @end example
 597 @cindex line-location
 598
 599 When viewing, Control-Mousebutton 1 will take you to the originating
 600 spot in the @file{.ly} file.  Control-Mousebutton 2 will show all
 601 clickable boxes.
 602
 603 If you correct large files with point-and-click, be sure to start
 604 correcting at the end of the file. When you start at the top, and
 605 insert one line, all following locations will be off by a line.
 606
 607 @cindex Emacs
 608 For using point-and-click with Emacs,  add the following
 609 In your Emacs startup file (usually @file{~/.emacs}):
 610 @example
 611 (server-start)
 612 @end example
 613
 614 Make sure that the environment variable @var{XEDITOR} is set to
 615 @example
 616 emacsclient --no-wait +%l %f
 617 @end example
 618 @cindex @var{XEDITOR}
 619 If you use XEmacs instead of Emacs, you use @code{(gnuserve-start)} in
 620 your @file{.emacs}, and set @code{XEDITOR} to @code{gnuclient -q +%l %f}.
 621
 622 For using Vim, set @code{XEDITOR} to @code{gvim --remote +%l %f}, or
 623 use this argument with Xdvi's @code{-editor} option.
 624
 625 @cindex NEdit
 626 For using NEdit, set @code{XEDITOR} to @code{nc -noask +%l %f}, or
 627 use this argument with Xdvi's @code{-editor} option.
 628
 629 If can also make your editor jump to the exact location of the note
 630 you clicked. This is only supported on Emacs and VIM. Users of Emacs version
 631 20 must apply the patch @file{emacsclient.patch}. Users of version 21
 632 must apply @file{server.el.patch} (version 21.2 and earlier).  At the
 633 top of the @code{ly} file, replace the @code{set-point-and-click} line
 634 with the following line:
 635 @example
 636 #(ly:set-point-and-click 'line-column)
 637 @end example
 638 @cindex line-column-location
 639 and set @code{XEDITOR} to @code{emacsclient --no-wait +%l:%c %f}.  Vim
 640 users can set @var{XEDITOR} to @code{gvim --remote +:%l:norm%c| %f}.
 641
 642