4 @command{lilypond-book} runs Lilypond on fragments of lilypond in a
5 La@TeX{} or texinfo file, and includes the results into a document that
6 can be processed with La@TeX{}, @command{makeinfo} or
7 @command{texi2dvi}. The result is a text document containing formatted
10 More precisely, if a La@TeX{} file contains
22 then LilyPond is run on CONTENTS. @command{lilypond-book} puts the
23 result back into the latex file. When you run the result through latex,
24 you get a document that mixes text and music. lilypond-book will insert
25 line width and font size definitions before @code{CONTENTS}, so the
26 music samples will match the layout of your document.
28 Very often, if you mix music and text, the music is often only a few
29 notes or at most a few bars. This music should be as short as possible
30 and not stretched to be aligned to the right margin. lilypond-book does
31 this automatically if you don't use a @code{\score} block in
32 @code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
35 You can also use @code{lilypondfile} to include another file:
37 \lilypondfile@{foo.ly@}
40 All three forms can take several options. They are specified in brackets
43 \lilypondfile[options, go, here]@{ .. @}
44 \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
45 \lilypond[options, go,here]@{ .. @}
48 In the texinfo version, bitmaps of the music are also generated, so you
49 can also make a HTML document with embedded music.
52 @section TeXinfo reference
54 Your markup the lilypond code like this:
56 @@lilypond[options, go, here]
59 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
60 @@lilypondfile[options, go,here]@{@var{filename}@}
64 @command{lilypond-book} knows the default margins, and a few papersizes.
65 These commands should be in the beginning of the document:
67 @item @code{@@afourpaper}
68 @item @code{@@afourlatex}
69 @item @code{@@afourwide}
70 @item @code{@@smallbook}
72 @code{@@pagesizes} are not yet supported.
76 Two simple examples. First a complete block:
89 Then the short version:
91 @@lilypond[11pt]@{<c' e' g'>@}
96 @lilypond[11pt]{<c' e' g'>}
98 @section La@TeX{} reference
100 Your markup the lilypond code like this:
102 \begin[option, go, here]@{lilypond@}
110 \lilypond@{ YOUR LILYPOND CODE @}
113 Lilypond-book know about the @code{\onecolumn} and
114 @code{\twocolumn} commands, the @code{geometry} package and
115 all the standard paper sizes.
117 The music will be surrounded by @code{\preLilypondExample} and
118 @code{\postLilypondExample}. The variables are
119 defined to nothing by default, and the user can redefine them
120 to whatever he wants.
125 \begin[26pt]@{lilypond@}
136 Then the short version:
138 \lilypond[11pt]@{<c' e' g'>@}
143 @lilypond[11pt]{<c' e' g'>}
150 This will create the music as eps graphics and include it into the
151 document with the @code{\includegraphics} command. It works in Latex
154 This enables you to place music examples in the running text (and not in
155 a separate paragraph). To avoid that La@TeX{} places the music on a line
156 of its one, there should be no empty lines between the normal text and
157 the lilypond environment. For inline music, you probably also need a
158 smaller music font size (eg. 11 pt or 13 pt)
162 CONTENTS is copied into the source enclosed in a verbatim block,
163 followed by any text given with the @code{intertext} option, then
164 the actual music is displayed. This option does not work with
165 the short version of the lilypond blocks:
167 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
169 @item intertext="@var{text}"
170 Used in conjunction with @code{verbatim} option: this puts
171 @var{text} between the code and the music.
172 @item filename=@var{FILENAME}
173 Save the lilypond code to @var{FILENAME}. By default, a hash value
179 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
180 [d16 g, a b][c a b g][d'8 g f-\prall g]
186 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
187 [d16 g, a b][c a b g][d'8 g f-\prall g]
193 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
194 [d16 g, a b][c a b g][d'8 g f-\prall g]
200 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
201 [d16 g, a b][c a b g][d'8 g f-\prall g]
207 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
212 Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
214 The opposite of @code{singleline}: justify and break lines.
217 Override @command{lilypond-book} autodetection of what type of code is in the
218 lilypond block, voice contents or complete code.
220 Prints the file name before the music example. Useful in conjunction
221 with @code{\lilypondfile}.
226 When you run @command{lilypond-book} it will generate lots of small
227 files that Lilypond will process. So to avoid all the garbage in
228 your source directory, you should either change to a temporary
229 directory, or use the @code{--outdir} commandline options:
231 @code{cd out && lilypond-book ../yourfile.tex}
233 @code{lilypond-book --outdir=out yourfile.tex}
236 For latex input, the file to give to latex has extension @file{.latex}.
237 TeXinfo input will be written to a file with extension @file{.texi}.
239 If you use @code{--outdir}, you should also @code{cd} to that directory
240 before running LaTeX or makeinfo. This may seem a little kludgy, but
241 both Latex and makeinfo expect picture files (the music) to be in the
242 current working directory. Moreover, if you do this, LaTeX will not
243 clutter you normal working directory with output files.
245 @cindex titling and lilypond-book
246 @cindex lilypond-book and titling
247 @cindex \header in LaTeX documents
249 If you want to combine music that has titling in @code{\header}
250 files, you should add the following to the top of your LaTeX
253 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
258 @subsection Command line options
262 @item @option{-f}, @option{--format=}
263 Specify the document type to process, @code{latex} or @code{texi}.
264 @command{lilypond-book} usually figure out this automatically.
265 @item --default-music-fontsize=@var{sz}pt
266 Set the fontsize to use for lilypond if no fontsize is given
268 @item --force-music-fontsize=@var{sz}pt
269 Force all lilypond to use this fontsize, overriding options
270 given to @code{\begin@{lilypond@}}
271 @item -I @var{DIR}, --include=@var{DIR}
272 Add @var{DIR} to the include path.
273 @item -M, --dependencies
274 Write dependencies to @file{filename.dep}
275 @item --dep-prefix=@code{PREF}
276 prepend @code{PREF} before each @code{-M} dependency
278 don't run lilypond, but do generate the @code{.ly} files
280 don't generate pictures when processing texinfo.
282 don't write ly files. This way you can do
284 lilypond-book file.tely
286 lilypond-book --read-lys
289 [TODO not a useful option unless you can undump the input file]
291 @item --outname=@var{FILE}
292 The name of La@TeX{} file to output. If this option is not given,
293 the output name derived from the input name.
294 @item --outdir=@var{DIR}
295 place generated files in @var{DIR}.
297 print version information
299 Print a short help message
304 @command{lilypond-book} is written in python 1.5, so you have to install
305 @uref{http://www.python.org,python}.
311 The La@TeX{} \includeonly@{...@} command is ignored.
313 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4.
314 But changing the linewidth in other ways will not give you a straight
317 Ignores almost all La@TeX{} commands that changes margins and linewidths.
319 Since there is no finder's fee which doubles every year, there is no
320 need to wait for the prize money to grow. So send a bug report today if
321 you need this one of these options.
326 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/~hanwen}
328 @email{tca@@gnu.org, Tom Cato Amundsen}