## 5 Invoking LilyPond

This chapter details the technicalities of running LilyPond.

### 5.1 Invoking lilypond

Nicely titled output is created through a separate program: `lilypond` is a script that uses the LilyPond formatting engine (which is in a separate program) and LaTeX to create a nicely titled piece of sheet music, in PDF (Portable Document Format) format.

                 lilypond [option]... file...

To have `lilypond` read from stdin, use a dash `-` for file. The program supports the following options.

`-k,--keep`
  Keep the temporary directory with all output files. The temporary directory is created in the current directory as `lilypond.dir`.
`-d,--dependencies`
  Write `Makefile` dependencies for every input file.
`-h,--help`
  Print usage help.
`-I,--include=`dir
  Add dir to LilyPond's include path.
`-m,--no-paper`
  Produce MIDI output only.
`--no-lily`
  Do not run lilypond-bin. Useful for debugging `lilypond`.
`-o,--output=`file
  Generate output to file. The extension of file is ignored.
`--no-pdf`
  Do not generate (PDF) or PS.

`--png`
  Also generate pictures of each page, in PNG format.
`--psgz`
  Gzip the postscript file.
`--html`
  Make a .HTML file with links to all output files.
`--preview`
  Also generate a picture of the first system of the score.

`-s,--set=`key`=`val
  Add key= val to the settings, overriding those specified in the files. Possible keys: `language`, `latexheaders`, `latexpackages`, `latexoptions`, `papersize`, `pagenumber`, `linewidth`, `orientation`, `textheight`.
`-v,--version`
  Show version information.
`-V,--verbose`
  Be verbose. This prints out commands as they are executed, and more information about the formatting process is printed.
`--debug`
  Print even more information. This is useful when generating bug reports.
`-w,--warranty`
  Show the warranty with which GNU LilyPond comes. (It comes with NO WARRANTY!)

#### 5.1.1 Titling layout

`lilypond` extracts the following header fields from the LY files to generate titling; an example demonstrating all these fields is in input/test/lilypond-testpage.ly:

`title`
  The title of the music. Centered on top of the first page.
`subtitle`
  Subtitle, centered below the title.
`poet`
  Name of the poet, left flushed below the subtitle.
`composer`
  Name of the composer, right flushed below the subtitle.
`meter`
  Meter string, left flushed below the poet.
`opus`
  Name of the opus, right flushed below the composer.
`arranger`
  Name of the arranger, right flushed below the opus.
`instrument`
  Name of the instrument, centered below the arranger.
`dedication`
  To whom the piece is dedicated.
`piece`
  Name of the piece, left flushed below the instrument.
`head`
  A text to print in the header of all pages. It is not called `header`, because `\header` is a reserved word in LilyPond.
`copyright`
  A text to print in the footer of the first page. Default is to print the standard footer also on the first page. Note that if the score consists of only a single page, the first page is also the last page, and in this case, the tagline is printed instead of the copyright.
`footer`
  A text to print in the footer of all but the last page.
`tagline`
  Line to print at the bottom of last page. The default text is “Engraved by LilyPond version-number”.

#### 5.1.2 Additional parameters

The `lilypond` program responds to several parameters specified in a `\paper` section of the input file. They can be overridden by supplying a `--set` command line option.

`language`
  Specify LaTeX language: the `babel` package will be included. Default: unset.

  Read from the `\header` block.

`latexheaders`
  Specify additional LaTeX headers file.

  Normally read from the `\header` block. Default value: empty.

`latexpackages`
  Specify additional LaTeX packages file. This works cumulative, so you can add multiple packages using multiple `-s=latexpackages` options. Normally read from the `\header` block. Default value: `geometry`.
`latexoptions`
  Specify additional options for the LaTeX `\documentclass`. You can put any valid value here. This was designed to allow `lilypond` to produce output for double-sided paper, with balanced margins and page numbers on alternating sides. To achieve this specify `twoside`.
`orientation`
  Set orientation. Choices are `portrait` or `landscape`. Is read from the `\paper` block, if set.
`textheight`
  The vertical extension of the music on the page. It is normally calculated automatically, based on the paper size.
`linewidth`
  The music line width. It is normally read from the `\paper` block.
`papersize`
  The paper size (as a name, e.g. `a4`). It is normally read from the `\paper` block.
`pagenumber`
  If set to `no`, no page numbers will be printed. If set to a positive integer, start with this value as the first page number.
`fontenc`
  The font encoding, should be set identical to the `font-encoding` property in the score.

Read comments on this page, or add one. This page is for LilyPond-2.2.2 (stable-branch).