[ << lilypond-book ] | [Top][Contents][Index] | [ External programs >> ] |
[ < Music fragment options ] | [ Up : lilypond-book ] | [ Filename extensions > ] |
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, or getting a
PostScript file with LaTeX via a DVI to PostScript translator like
dvips
. The first way is simpler and recommended1, 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 through 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 then 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 things like \linewidth
).
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; this is, either call texi2pdf
or
texi2dvi
or makeinfo
, 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
, ordocbook
. If this option is missing,lilypond-book
tries to detect the format automatically, see Filename extensions. Currently,texi-html
is the same astexi
.-
-F filter
-
--filter=filter
Pipe snippets through
filter
. 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 asmakeinfo
orlatex
with the same ‘-I dir’ options.-
-l loglevel
-
--loglevel=loglevel
Set the output verbosity to loglevel. Possible values are
NONE
,ERROR
,WARNING
,PROGRESS
(default), andDEBUG
. If this option is not used and the environment variableLILYPOND_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 runninglatex
ormakeinfo
.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 areNONE
,ERROR
,WARNING
,BASIC
,PROGRESS
,INFO
(default), andDEBUG
. If this option is not used and the environment variableLILYPOND_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.
-
--latex-program=prog
Run executable
prog
instead oflatex
. This is useful if your document is processed withxelatex
, for example.-
--left-padding=amount
Pad LilyPond snippets on the left with whitespace.
amount is rounded up to be an integer multiple of a big point (bp). One bp is 1/72th of an inch (approx. 0.353mm). amount is given in millimeters relative to the start of the staff. The default value is 3.175mm (which equals 9bp).
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.
-
-P command
-
--process=command
Process LilyPond snippets using
command
. The default command islilypond
.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.
Footnotes
[1] Note that PDFLaTeX and LaTeX may not be both usable to compile any LaTeX document, that is why we explain the two ways.
[ << lilypond-book ] | [Top][Contents][Index] | [ External programs >> ] |
[ < Music fragment options ] | [ Up : lilypond-book ] | [ Filename extensions > ] |