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 recommended(1), 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. *Note
(texinfo)Format with texi2dvi::, and *note (texinfo)Creating an Info
File::.
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) or ‘docbook’. If this option is missing, ‘lilypond-book’
tries to detect the format automatically, see *note Filename
extensions::. Currently, ‘texi’ is the same as ‘texi-html’.
‘-F FILTER’
‘--filter=FILTER’
Pipe snippets through FILTER. ‘lilypond-book’ will not –filter and
–process at the same time. For example,
lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
‘-h’
‘--help’
Print a short help message.
‘-I DIR’
‘--include=DIR’
Add DIR to the include path. ‘lilypond-book’ also looks for
already compiled snippets in the include path, and does not write
them back to the output directory, so in some cases it is necessary
to invoke further processing commands such as ‘makeinfo’ or ‘latex’
with the same ‘-I DIR’ options.
‘-l LOGLEVEL’
‘--loglevel=LOGLEVEL’
Set the output verbosity to LOGLEVEL. Possible values are ‘NONE’,
‘ERROR’, ‘WARNING’, ‘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 loglevel.
‘-o DIR’
‘--output=DIR’
Place generated files in directory DIR. Running ‘lilypond-book’
generates lots of small files that LilyPond will process. To avoid
all that garbage in the source directory, use the ‘--output’
command line option, and change to that directory before running
‘latex’ or ‘makeinfo’.
lilypond-book --output=out yourfile.lytex
cd out
…
‘--skip-lily-check’
Do not fail if no lilypond output is found. It is used for
LilyPond Info documentation without images.
‘--skip-png-check’
Do not fail if no PNG images are found for EPS files. It is used
for LilyPond Info documentation without images.
‘--lily-output-dir=DIR’
Write lily-XXX files to directory DIR, link into ‘--output’
directory. Use this option to save building time for documents in
different directories which share a lot of identical snippets.
‘--lily-loglevel=LOGLEVEL’
Set the output verbosity of the invoked ‘lilypond’ calls to
LOGLEVEL. Possible values are ‘NONE’, ‘ERROR’, ‘WARNING’,
‘BASIC_PROGRESS’, ‘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 loglevel.
‘--info-images-dir=DIR’
Format Texinfo output so that Info will look for images of music in
DIR.
‘--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 EPS boxes by this much. AMOUNT is measured in millimeters, and
is 3.0 by default. This option should be used if the lines of
music stick out of the right margin.
The width of a tightly clipped system can vary, due to notation
elements that stick into the left margin, such as bar numbers and
instrument names. This option will shorten each line and move each
line to the right by the same amount.
‘-P COMMAND’
‘--process=COMMAND’
Process LilyPond snippets using COMMAND. The default command is
‘lilypond’. ‘lilypond-book’ will not ‘--filter’ and ‘--process’ at
the same time.
‘--pdf’
Create PDF files for use with PDFLaTeX.
‘--redirect-lilypond-output’
By default, 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
‘lilypondfile’ 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.
3.6 lilypond-book templates
===========================
These templates are for use with ‘lilypond-book’. If you’re not
familiar with this program, please refer to *note lilypond-book::.
3.6.1 LaTeX
-----------
You can include LilyPond fragments in a LaTeX document.
\documentclass[]{article}
\begin{document}
Normal LaTeX text.
\begin{lilypond}
\relative {
a'4 b c d
}
\end{lilypond}
More LaTeX text, and options in square brackets.
\begin{lilypond}[fragment,relative=2,quote,staffsize=26,verbatim]
d4 c b a
\end{lilypond}
\end{document}
3.6.2 Texinfo
-------------
You can include LilyPond fragments in Texinfo; in fact, this entire
manual is written in Texinfo.
\input texinfo @node Top
@top
Texinfo text
@lilypond
\relative {
a4 b c d
}
@end lilypond
More Texinfo text, and options in brackets.
@lilypond[verbatim,fragment,ragged-right]
d4 c b a
@end lilypond
@bye
3.6.3 html
----------
Documents for lilypond-book may freely mix music and text. For
example,
\relative {
a'4 b c d
}
Another bit of lilypond, this time with options:
a4 b c d
3.6.4 xelatex
-------------
\documentclass{article}
\usepackage{ifxetex}
\ifxetex
%xetex specific stuff
\usepackage{xunicode,fontspec,xltxtra}
\setmainfont[Numbers=OldStyle]{Times New Roman}
\setsansfont{Arial}
\else
%This can be empty if you are not going to use pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{mathptmx}%Times
\usepackage{helvet}%Helvetica
\fi
%Here you can insert all packages that pdftex also understands
\usepackage[ngerman,finnish,english]{babel}
\usepackage{graphicx}
\begin{document}
\title{A short document with LilyPond and xelatex}
\maketitle
Normal \textbf{font} commands inside the \emph{text} work,
because they \textsf{are supported by \LaTeX{} and XeteX.}
If you want to use specific commands like \verb+\XeTeX+, you
should include them again in a \verb+\ifxetex+ environment.
You can use this to print the \ifxetex \XeTeX{} command \else
XeTeX command \fi which is not known to normal \LaTeX .
In normal text you can easily use LilyPond commands, like this:
\begin{lilypond}
{a2 b c'8 c' c' c'}
\end{lilypond}
\noindent
and so on.
The fonts of snippets set with LilyPond will have to be set from
inside
of the snippet. For this you should read the AU on how to use
lilypond-book.
\selectlanguage{ngerman}
Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
anderen
seltsamen Zeichen: __ ______, wenn sie von der Schriftart
unterst__tzt werden.
\end{document}
3.7 Sharing the table of contents
=================================
These functions already exist in the OrchestralLily package:
For greater flexibility in text handling, some users prefer to export
the table of contents from lilypond and read it into LaTeX.
Exporting the ToC from LilyPond
...............................
This assumes that your score has multiple movements in the same lilypond
output file.
#(define (oly:create-toc-file layout pages)
(let* ((label-table (ly:output-def-lookup layout 'label-page-table)))
(if (not (null? label-table))
(let* ((format-line (lambda (toc-item)
(let* ((label (car toc-item))
(text (caddr toc-item))
(label-page (and (list? label-table)
(assoc label label-table)))
(page (and label-page (cdr label-page))))
(format #f "~a, section, 1, {~a}, ~a" page text label))))
(formatted-toc-items (map format-line (toc-items)))
(whole-string (string-join formatted-toc-items ",\n"))
(output-name (ly:parser-output-name parser))
(outfilename (format "~a.toc" output-name))
(outfile (open-output-file outfilename)))
(if (output-port? outfile)
(display whole-string outfile)
(ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename))
(close-output-port outfile)))))
\paper {
#(define (page-post-process layout pages) (oly:create-toc-file layout pages))
}
Importing the ToC into LaTeX
............................
In LaTeX, the header should include:
\usepackage{pdfpages}
\includescore{nameofthescore}
where ‘\includescore’ is defined as:
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \includescore{PossibleExtension}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Read in the TOC entries for a PDF file from the corresponding .toc file.
% This requires some heave latex tweaking, since reading in things from a file
% and inserting it into the arguments of a macro is not (easily) possible
% Solution by Patrick Fimml on #latex on April 18, 2009:
% \readfile{filename}{\variable}
% reads in the contents of the file into \variable (undefined if file
% doesn't exist)
\newread\readfile@f
\def\readfile@line#1{%
{\catcode`\^^M=10\global\read\readfile@f to \readfile@tmp}%
\edef\do{\noexpand\g@addto@macro{\noexpand#1}{\readfile@tmp}}\do%
\ifeof\readfile@f\else%
\readfile@line{#1}%
\fi%
}
\def\readfile#1#2{%
\openin\readfile@f=#1 %
\ifeof\readfile@f%
\typeout{No TOC file #1 available!}%
\else%
\gdef#2{}%
\readfile@line{#2}%
\fi
\closein\readfile@f%
}%
\newcommand{\includescore}[1]{
\def\oly@fname{\oly@basename\@ifmtarg{#1}{}{_#1}}
\let\oly@addtotoc\undefined
\readfile{\oly@xxxxxxxxx}{\oly@addtotoc}
\ifx\oly@addtotoc\undefined
\includepdf[pages=-]{\oly@fname}
\else
\edef\includeit{\noexpand\includepdf[pages=-,addtotoc={\oly@addtotoc}]
{\oly@fname}}\includeit
\fi
}