3.4 Invoking lilypond-book

lilypond-book produces a file with one of the following extensions: .tex, .texi, .html or .xml, depending on the output format. All of .tex, .texi and .xml files need further processing.

Format-specific instructions

LaTeX

There are two ways of processing your LaTeX document for printing or publishing: getting a PDF file directly with pdfLaTeX (XeLaTeX, luaLaTeX) or getting a PostScript file with LaTeX via a DVI-to-PostScript translator like dvips. The first way is simpler and recommended⁶, and whichever way you use, you can easily convert between PostScript and PDF with tools, like ps2pdf and pdf2ps included in Ghostscript package.

To produce a PDF file with pdfLaTeX, use:

lilypond-book --pdf yourfile.lytex
pdflatex yourfile.tex

To produce PDF output via LaTeX/dvips/ps2pdf:

lilypond-book yourfile.lytex
latex yourfile.tex
dvips -Ppdf yourfile.dvi
ps2pdf yourfile.ps

The .dvi file created by this process will not contain note heads. This is normal; if you follow the instructions, they will be included in the .ps and .pdf files.

Running dvips may produce some warnings about fonts; these are harmless and may be ignored. If you are running latex in twocolumn mode, remember to add -t landscape to the dvips options.

Environments such as

\begin{lilypond} … \end{lilypond}

are not interpreted by LaTeX. Instead, lilypond-book extracts those ‘environments’ into files of its own and runs LilyPond on them. It then takes the resulting graphics and creates a .tex file where the \begin{lilypond}…\end{lilypond} macros are replaced by ‘graphics inclusion’ commands. It is at this time that LaTeX is run (although LaTeX will have run previously, it will have been, effectively, on an ‘empty’ document in order to calculate paper dimensions and the line width for LilyPond snippets).

Known issues and warnings

The \pageBreak command will not work within a \begin{lilypond} … \end{lilypond} environment.

Many \paper block variables will also not work within a \begin{lilypond} … \end{lilypond} environment. Use \newcommand with \betweenLilyPondSystem in the preamble.

\newcommand{\betweenLilyPondSystem}[1]{\vspace{36mm}\linebreak}

Texinfo

To produce a Texinfo document (in any output format), follow the normal procedures for Texinfo; that is, either call texi2pdf or texi2dvi or texi2any, depending on the output format you want to create. By default, texi2pdf uses pdftex for processing, which you can verify in the console output. In this case, run lilypond-book with the --pdf option so that it creates .pdf snippets instead of .eps files. pdftex is unable to include the latter ones and will output an error message otherwise.

See the documentation of Texinfo for further details.

Command-line options

lilypond-book accepts the following command-line options.

-f format

--format=format

Specify the document type to process: html, latex, texi (the default), texi-html, or docbook. If this option is missing, lilypond-book tries to detect the format automatically, see Filename extensions. Currently, texi-html is the same as texi.

-F filter

--filter=filter

Pipe snippets through filter. With this option, lilypond-book does not create snippet files; instead, it modifies the code of the embedded snippets in the input document and emits the resulting file, which in turn can then be processed by another run with lilypond-book (without the --filter option). Example:

lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely

lilypond-book does not accept options --filter and --process at the same time.

-h

--help

Print a short help message.

-I dir

--include=dir

Add dir to the include path. Since lilypond-book also looks for already compiled snippets in the include path and does not write them back to the output directory, it is necessary in some cases to invoke further processing commands such as texi2any or latex with the same -I dir options.

-l loglevel

--loglevel=loglevel

Set the output verbosity to loglevel. Possible values are NONE, ERROR, WARN, PROGRESS (default), and DEBUG. If this option is not used and the environment variable LILYPOND_BOOK_LOGLEVEL is set, its value is used as the log level.

-o dir

--output=dir

Place generated files into directory dir. Running lilypond-book generates lots of small files that LilyPond will process. To avoid all that clutter in the source directory, use the --output command-line option, and change to that directory before running latex or texi2any.

lilypond-book --output=out yourfile.lytex
cd out
…

--skip-lily-check

Do not fail if no LilyPond output is found. It is used for generating LilyPond’s Info documentation without images.

--skip-png-check

Do not fail if no PNG images are found for EPS files. It is used for generating LilyPond’s Info documentation without images.

--lily-output-dir=dir

Write lily-XXX files to directory dir and link into --output directory. Use this option to save building time for documents in different directories that share a lot of identical snippets.

--lily-loglevel=loglevel

Set the output verbosity of the invoked lilypond command to loglevel. Possible values are NONE, ERROR, WARN, BASIC, PROGRESS, INFO (default), and DEBUG. If this option is not used and the environment variable LILYPOND_LOGLEVEL is set, its value is used as the log level.

--info-images-dir=dir

Format Texinfo output so that Info will look for images of music in directory dir.

--inline-vshift=vshift

In the LaTeX backend, use vshift to vertically move all inline images. vshift is a factor of an image’s height; the default value is -0.3, thus moving the images down by approx. one third of their individual heights. The factor can be locally overridden with an argument to the inline snippet option.

--latex-program=prog

Run executable prog instead of latex. This is useful if your document is processed with xelatex, for example.

--left-padding=amount

Pad LilyPond snippets on the left with whitespace.

amount is given in millimeters relative to the start of the staff. The default value is 3.0mm.

The widths of tightly clipped systems can vary due to notation elements such as bar numbers or instrument names that are positioned left of the beginning of staves. The padding sets the minimum distance between the left margin of the snippet images and the beginning of (non-indented) staves; this allows the expected vertical alignment of snippets in the master document.

In addition to padding at the left, this option shortens each staff line by amount. As a consequence, each line is moved to the right visually.

Note that amount, as used for padding, is rounded up to be an integer multiple of the big point (bp) unit for PostScript and PDF output (one bp is 1/72th of an inch, approx. 0.353mm). However, this is not done on the LilyPond side for shortening the staff line. This might lead to a tiny but probably surprising staff length change instead of changing the padding if amount is not an integer multiple of the bp unit.

-P command

--process=command

Process LilyPond snippets using command. The default command is lilypond. lilypond-book does not accept options --filter and --process at the same time.

--pdf

Create PDF snippet files. If not set, only PNG and EPS files are produced. Use this option if you want to directly embed PDF files into LaTeX or Texinfo files.

--redirect-lilypond-output

By default, logging output is displayed on the terminal. This option redirects all output to log files in the same directory as the source files.

--use-source-file-names

Write snippet output files with the same base name as their source file. This option works only for snippets included with the lilypondfile command and only if directories implied by --output-dir and --lily-output-dir options are different.

-V

--verbose

Be verbose. This is equivalent to --loglevel=DEBUG.

-v

--version

Print version information.

Known issues and warnings

The Texinfo command @pagesizes is not interpreted. Similarly, LaTeX commands that change margins and line widths after the preamble are ignored.

Only the first \score of a LilyPond block is processed.