3 @node Merging text and music with lilypond-book
4 @chapter Merging text and music with lilypond-book
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.
76 We show two simple examples here. First a complete block:
88 Then the short version:
90 @@lilypond[11pt]@{<c' e' g'>@}
95 @lilypond[11pt]{<c' e' g'>}
97 @section La@TeX{} reference
99 You specify the lilypond code like this:
101 \begin[option, go, here]@{lilypond@}
107 \lilypondfile[options, go,here]@{@var{filename}@}
111 \lilypond@{ YOUR LILYPOND CODE @}
114 Lilypond-book know about the @code{\onecolumn} and
115 @code{\twocolumn} commands, the @code{geometry} package
116 (all except the following options: paperwidth, papersize,
117 hdivide, divide, textwidth, mag, offset) and all the
118 standard paper sizes.
120 The music will be surrounded by @code{\preLilypondExample} and
121 @code{\postLilypondExample}. The variables are
122 defined to nothing by default, and the user can redefine them
123 to whatever he wants.
125 We show some examples here.
128 \begin[26pt]@{lilypond@}
139 Then the short version:
141 \lilypond[11pt]@{<c' e' g'>@}
146 @lilypond[11pt]{<c' e' g'>}
153 This will create the music as eps graphics and include it into the
154 document with the @code{\includegraphics} command. It works in
157 This enables you to place music examples in the running text (and not in
158 a separate paragraph). To avoid that La@TeX{} places the music on a line
159 of its own, there should be no empty lines between the normal text and
160 the lilypond environment. For inline music, you probably also need a
161 smaller music font size (eg. 11 pt or 13 pt)
165 CONTENTS is copied into the source enclosed in a verbatim block,
166 followed by any text given with the @code{intertext} option, then
167 the actual music is displayed. This option does not work with
168 the short version of the lilypond blocks:
170 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
173 like @code{verbatim}, but in a smaller font.
175 @item intertext="@var{text}"
176 Used in conjunction with @code{verbatim} option: this puts
177 @var{text} between the code and the music.
178 @item filename="@var{filename}"
179 Save the lilypond code to @var{filename}. By default, a hash value
185 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
186 [d16 g, a b][c a b g][d'8 g f-\prall g]
192 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
193 [d16 g, a b][c a b g][d'8 g f-\prall g]
199 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
200 [d16 g, a b][c a b g][d'8 g f-\prall g]
206 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
207 [d16 g, a b][c a b g][d'8 g f-\prall g]
213 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
218 Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
220 The opposite of @code{singleline}: justify and break lines.
221 @item linewidth=@var{size}@var{unit}
222 Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
225 Override @command{lilypond-book} auto detection of what type of code is in the
226 lilypond block, voice contents or complete code.
227 @item indent=@var{size}@var{unit}
228 Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
230 Set first line indent to zero.
232 Prints the file name before the music example. Useful in conjunction
233 with @code{\lilypondfile}.
234 @item relative, relative @var{N}
235 Use relative octave mode. By default, notes are specified relative
236 central C. The optional integer argument specifies how many octaves
237 higher (positive number) or lower (negative number) to place the
243 When you run @command{lilypond-book} it will generate lots of small
244 files that Lilypond will process. So to avoid all the garbage in
245 your source directory, you should either change to a temporary
246 directory, or use the @code{--outdir} command line options:
248 @code{cd out && lilypond-book ../yourfile.tex}
250 @code{lilypond-book --outdir=out yourfile.tex}
253 For latex input, the file to give to latex has extension @file{.latex}.
254 Texinfo input will be written to a file with extension @file{.texi}.
256 If you use @code{--outdir}, you should also @code{cd} to that directory
257 before running LaTeX or makeinfo. This may seem a little kludgey, but
258 both Latex and makeinfo expect picture files (the music) to be in the
259 current working directory. Moreover, if you do this, LaTeX will not
260 clutter you normal working directory with output files.
262 @cindex titling and lilypond-book
263 @cindex lilypond-book and titling
264 @cindex \header in LaTeX documents
266 If you want to add titling from the @code{\header} section of the
267 files, you should add the following to the top of your LaTeX
270 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
273 lilypond-book accepts the following command-line options:
275 @item @option{-f}, @option{--format=}
276 Specify the document type to process, @code{latex} or @code{texi}.
277 @command{lilypond-book} usually figure this out automatically.
278 @item --default-music-fontsize=@var{sz}pt
279 Set the fontsize to use for lilypond if no fontsize is given
281 @item --force-music-fontsize=@var{sz}pt
282 Force all lilypond to use this fontsize, overriding options
283 given to @code{\begin@{lilypond@}}
284 @item -I @var{DIR}, --include=@var{DIR}
285 Add @var{DIR} to the include path.
286 @item -M, --dependencies
287 Write dependencies to @file{filename.dep}
288 @item --dep-prefix=@code{PREF}
289 prepend @code{PREF} before each @code{-M} dependency
291 don't run lilypond, but do generate the @code{.ly} files
293 strip all lilypond blocks from the file.
295 don't generate pictures when processing Texinfo.
297 don't write ly files. This way you can do
299 lilypond-book file.tely
301 lilypond-book --read-lys
304 [TODO not a useful option unless you can undump the input file]
306 @item --outname=@var{FILE}
307 The name of La@TeX{} file to output. If this option is not given,
308 the output name is derived from the input name.
309 @item --outdir=@var{DIR}
310 place generated files in @var{DIR}.
312 print version information
314 Print a short help message
320 The La@TeX{} \includeonly@{...@} command is ignored.
322 The Texinfo command @code{pagesize} is on the TODO list for Lilypond
323 1.6, but changing the linewidth in other ways will not give you a
324 straight right margin.
326 Almost all La@TeX{} commands that change margins and line widths are
329 There is no way to automatically apply convert-ly to fragments inside a