6 @command{lilypond-book} runs Lilypond on fragments of lilypond in a
7 La@TeX{} or texinfo file, and includes the results into a document that
8 can be processed with La@TeX{}, @command{makeinfo} or
9 @command{texi2dvi}. The result is a text document containing formatted
12 More precisely, if a La@TeX{} file contains
24 then LilyPond is run on CONTENTS. @command{lilypond-book} puts the
25 result back into the latex file. When you run the result through latex,
26 you get a document that mixes text and music. lilypond-book will insert
27 line width and font size definitions before @code{CONTENTS}, so the
28 music samples will match the layout of your document.
30 Very often, if you mix music and text, the music is only a few
31 notes or at most a few bars. This music should be as short as possible
32 and not stretched to be aligned to the right margin. lilypond-book does
33 this automatically if you don't use a @code{\score} block in
34 @code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
37 You can also use @code{lilypondfile} to include another file:
39 \lilypondfile@{foo.ly@}
42 All three forms can take several options. They are specified in brackets
45 \lilypondfile[options, go, here]@{ .. @}
46 \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
47 \lilypond[options, go,here]@{ .. @}
50 In the texinfo version, bitmaps of the music are also generated, so you
51 can make a HTML document with embedded music.
54 @section TeXinfo reference
56 You specify the lilypond code like this:
58 @@lilypond[options, go, here]
61 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
62 @@lilypondfile[options, go,here]@{@var{filename}@}
66 @command{lilypond-book} knows the default margins, and a few paper
67 sizes. One of these commands should be in the beginning of the document:
69 @item @code{@@afourpaper}
70 @item @code{@@afourlatex}
71 @item @code{@@afourwide}
72 @item @code{@@smallbook}
74 @code{@@pagesizes} are not yet supported.
78 Two simple examples. First a complete block:
91 Then the short version:
93 @@lilypond[11pt]@{<c' e' g'>@}
98 @lilypond[11pt]{<c' e' g'>}
100 @section La@TeX{} reference
102 You specify the lilypond code like this:
104 \begin[option, go, here]@{lilypond@}
110 \lilypondfile[options, go,here]@{@var{filename}@}
114 \lilypond@{ YOUR LILYPOND CODE @}
117 Lilypond-book know about the @code{\onecolumn} and
118 @code{\twocolumn} commands, the @code{geometry} package and
119 all the standard paper sizes.
121 The music will be surrounded by @code{\preLilypondExample} and
122 @code{\postLilypondExample}. The variables are
123 defined to nothing by default, and the user can redefine them
124 to whatever he wants.
129 \begin[26pt]@{lilypond@}
140 Then the short version:
142 \lilypond[11pt]@{<c' e' g'>@}
147 @lilypond[11pt]{<c' e' g'>}
154 This will create the music as eps graphics and include it into the
155 document with the @code{\includegraphics} command. It works in
158 This enables you to place music examples in the running text (and not in
159 a separate paragraph). To avoid that La@TeX{} places the music on a line
160 of its own, there should be no empty lines between the normal text and
161 the lilypond environment. For inline music, you probably also need a
162 smaller music font size (eg. 11 pt or 13 pt)
166 CONTENTS is copied into the source enclosed in a verbatim block,
167 followed by any text given with the @code{intertext} option, then
168 the actual music is displayed. This option does not work with
169 the short version of the lilypond blocks:
171 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
173 @item intertext="@var{text}"
174 Used in conjunction with @code{verbatim} option: this puts
175 @var{text} between the code and the music.
176 @item filename=@var{FILENAME}
177 Save the lilypond code to @var{FILENAME}. By default, a hash value
183 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
184 [d16 g, a b][c a b g][d'8 g f-\prall g]
190 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
191 [d16 g, a b][c a b g][d'8 g f-\prall g]
197 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
198 [d16 g, a b][c a b g][d'8 g f-\prall g]
204 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
205 [d16 g, a b][c a b g][d'8 g f-\prall g]
211 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
216 Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
218 The opposite of @code{singleline}: justify and break lines.
221 Override @command{lilypond-book} auto detection of what type of code is in the
222 lilypond block, voice contents or complete code.
224 Prints the file name before the music example. Useful in conjunction
225 with @code{\lilypondfile}.
230 When you run @command{lilypond-book} it will generate lots of small
231 files that Lilypond will process. So to avoid all the garbage in
232 your source directory, you should either change to a temporary
233 directory, or use the @code{--outdir} command line options:
235 @code{cd out && lilypond-book ../yourfile.tex}
237 @code{lilypond-book --outdir=out yourfile.tex}
240 For latex input, the file to give to latex has extension @file{.latex}.
241 TeXinfo input will be written to a file with extension @file{.texi}.
243 If you use @code{--outdir}, you should also @code{cd} to that directory
244 before running LaTeX or makeinfo. This may seem a little kludgey, but
245 both Latex and makeinfo expect picture files (the music) to be in the
246 current working directory. Moreover, if you do this, LaTeX will not
247 clutter you normal working directory with output files.
249 @cindex titling and lilypond-book
250 @cindex lilypond-book and titling
251 @cindex \header in LaTeX documents
253 If you want to add titling from the @code{\header} section of the
254 files, you should add the following to the top of your LaTeX
257 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
262 @subsection Command line options
266 @item @option{-f}, @option{--format=}
267 Specify the document type to process, @code{latex} or @code{texi}.
268 @command{lilypond-book} usually figure this out automatically.
269 @item --default-music-fontsize=@var{sz}pt
270 Set the fontsize to use for lilypond if no fontsize is given
272 @item --force-music-fontsize=@var{sz}pt
273 Force all lilypond to use this fontsize, overriding options
274 given to @code{\begin@{lilypond@}}
275 @item -I @var{DIR}, --include=@var{DIR}
276 Add @var{DIR} to the include path.
277 @item -M, --dependencies
278 Write dependencies to @file{filename.dep}
279 @item --dep-prefix=@code{PREF}
280 prepend @code{PREF} before each @code{-M} dependency
282 don't run lilypond, but do generate the @code{.ly} files
284 don't generate pictures when processing texinfo.
286 don't write ly files. This way you can do
288 lilypond-book file.tely
290 lilypond-book --read-lys
293 [TODO not a useful option unless you can undump the input file]
295 @item --outname=@var{FILE}
296 The name of La@TeX{} file to output. If this option is not given,
297 the output name is derived from the input name.
298 @item --outdir=@var{DIR}
299 place generated files in @var{DIR}.
301 print version information
303 Print a short help message
308 @command{lilypond-book} is written in python 1.5, so you have to install
309 @uref{http://www.python.org,python}.
315 The La@TeX{} \includeonly@{...@} command is ignored.
317 The TeXinfo command @code{pagesize} is on the TODO list for Lilypond 1.4,
318 but changing the linewidth in other ways will not give you a straight
321 Almost all La@TeX{} commands that change margins and line widths are ignored.
323 Since there is no finder's fee which doubles every year, there is no
324 need to wait for the prize money to grow. So send a bug report today if
325 you need this one of these options.
330 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}, @uref{http://www.cs.uu.nl/~hanwen}
332 @email{tca@@gnu.org, Tom Cato Amundsen}