Table of Contents
Introduction
[ The tutorial part is at the moment commented out and moved to
the end of this document ]
[TODO: THIS MANUAL IS NOT FINISHED YET. FIXME.]
lilypond-book
is a script that helps integrating lilypond with
LaTeX or TeXinfo. lilypond-book
runs Lilypond on fragments
of lilypond in your source file, and includes the results into a
document that can be processed with LaTeX, makeinfo
or texi2dvi
.
The result is a text document with formatted music integrated.
lilypond-book
will do its best to try to align the music to
the left and right margins. Currently all papersizes, one- and
twocolumn mode and the geometry
package is supported.
The TeXinfo command pagesize
is on the TODO list for Lilypond 1.4.
But changing the linewidth in other ways will not give you a straight
right margin.
This document assumes you have basic knowledge of GNU LilyPond and
LaTeX or texinfo.
TeXinfo reference
Your markup the lilypond code like this:
@lilypond[options, go, here]
YOUR LILYPOND CODE
@end lilypond
or
@lilypond[option, go, here]{ YOUR LILYPOND CODE }
lilypond-book
knows the default margins, and a few papersizes.
These commands should be in the beginning of the document:
@afourpaper
@afourlatex
@afourwide
@smallbook
@pagesizes
are not yet supported.
Examples
Two simple examples. First a complete block:
@lilypond[26pt]
c' d' e' f' g'2 g'
@end lilypond
produces this music:
Then the short version:
@lilypond[11pt]{<c' e' g'>}
and its music:
@example and @code
I'm not sure if this will go into the final documentation, this is
here mostly to remember me on why things are the way they are.
lilypond-book
will do nothing with special with @code
and
@example
environments. The 'code' and 'example' commands
should work just as normal. People looking at document that should be
processed by lilypond-book
, should notice nothing special, except from
some block like this:
@lilypond
BLABLA
@end lilypond
or this:
@lilypond{ BLABLA }
Anything other is a bug in lilypond-book
.
So to get this in the printed manual:
@lilypond[26pt]
\relative c'{c d e f g2 g}
@end lilypond
you have to write this:
@example
@@lilypond[26pt]
\relative c'@{c d e f g2 g@}
@@end lilypond
@end example
Simply explained, every '{', '}' and '@' has to be written as '@{',
'@}' and '@@'. This is how it works in plain texinfo too.
LaTeX reference
Your markup the lilypond code like this:
\begin[option, go, here]{lilypond}
YOUR LILYPOND CODE
\end{lilypond}
or
\lilypond{ YOUR LILYPOND CODE }
Lilypond-book know about the \onecolumn
and
\twocolumn
commands, the geometry
package and
all the standard paper sizes.
The music will be surrounded by \preLilypondExample
and
\postLilypondExample
. The variables are
defined to nothing by default, and the user can redefine them
to whatever he wants.
[UGH: THIS DOES NOT HAPPEN WHEN
YOU USE THE SHORT FORM, \LILYPOND{ ... }, CHECK OUT WHY]
Examples
\begin[26pt]{lilypond}
c' d' e' f' g'2 g'2
\end{lilypond}
produces this music:
Then the short version:
\lilypond[11pt]{<c' e' g'>}
and its music:
\begin{verbatim} and \verb|\verb|
There work just as expected. Look at mb-latex.tex
for details.
Options
eps
- the music is created as eps graphics that can be inserted in
the middle of a text line, not only as a separate paragraph.
(LaTeX only)
verbatim
- CONTENTS is copied into the source enclosed in a verbatim block,
followed by any text given with the
intertext
option, then
the actual music is displayed. This option does not work with
the short version of the lilypond blocks:
@lilypond{ CONTENTS }
and \lilypond{ CONTENTS }
intertext="text inside apostrophs"
- Used in conjunction with
verbatim
option.
filename=FILENAME
- Save the lilypond code to FILENAME instead of using a hash value
of CONTENTS.
11pt, 13pt, 16pt, 20pt, 26pt
- set the fontsize to use for the music
singleline
- linewidth = -1.
multiline
- linewidth = textwidth
fragment
nonfragment
- Override
lilypond-book
autodetection of what type of code is in the
lilypond block, voice contents or complete code.
Invocation
When you run lilypond-book
it will generate lots of small
files that Lilypond will process. So to avoid all the garbage in
your source directory, you should either change to a temporary
directory, or use the --outdir
commandline options:
cd out && lilypond-book ../yourfile.tex
lilypond-book --outdir=out yourfile.tex
For latex input, the file to give to latex has ext .latex
.
TeXinfo input will be written to a file with ext .texi
. So be
careful, don't give the source file that ext, or the file will be
overwritten.
If you use --outdir
, you should also cd
to that directory
before running LaTeX or makeinfo.
[UGH: IS THIS THE BEST WAY TO DO IT? MAYBE ADD A COMMENT LINE TO THE
GENERATED FILE, SO LILYPOND-BOOK CAN TEST IF THE FILE IT IS TO OVERWRITE
IS GENERATED.]
About the input
If the file contains the "block"
\begin{lilypond}
CONTENTS
\end{lilypond}
then LilyPond is run on CONTENTS. lilypond-book
puts the result back,
surrounded by \preLilypondExample
and \postLilypondExample
commands. \preLilypondExample
and posLilypondExample
is
defined to nothing by default, and the user can redefine them
to whatever he wants.
Command line options
-f
, --format=
- Specify the document type to process,
latex
or texi
.
lilypond-book
usually figure out this automatically.
--default-music-fontsize=??pt
- Set the fontsize to use for lilypond if no fontsize is given
as option.
--force-music-fontsize=??pt
- Force all lilypond to use this fontsize, overriding options
given to \begin{lilypond}
-I DIR, --include=DIR
- include path
-M, --dependencies
- Write dependencies to out-www/filename.dep
--dep-prefix=PREF
- prepend PREF before each -M dependency
-n, --no-lily
- don't run lilypond
--no-pictures
- don't generate pictures
--read-lys
- don't write ly files. This way you can do
lilypond-book file.tely
convert-ly
lilypond-book --read-lys
--outname=FILE
- The name of LaTeX file to output. If this option is not given,
the output name derived from the input name.
--outdir=
- where to place generated files
--version
- print version information
--help
- Print a short help message
lilypond-book
is written in python 1.5, so you have to install
python.
Bugs
The LaTeX \includeonly{...} command is ignored.
Ignores almost all LaTeX commands that changes margins and linewidths.
Authors
Han-Wen Nienhuys, http://www.cs.uu.nl/people/hanwen
Tom Cato Amundsen