7 ** AARGH.e We also have tutorial.itely: Integrating text and music.
9 Could also do with a cleanup. Lost inspiration to fix this manual
10 where to describe what?
14 @c @node Merging text and music with lilypond-book
15 @c @chapter Merging text and music with lilypond-book
17 @c fix this node name , this is too long.
19 @node Insert music snippets into your texts using lilypond-book
20 @chapter Insert music snippets into your texts using lilypond-book
22 If you want to add pictures of music to a document, you can simply do
23 it the way you would do with other types of pictures. You write
24 LilyPond code, process it separately to embedded PostScript or
25 @code{png}, and include it as a picture into your La@TeX{} or
28 @command{lilypond-book} provides you with a way to automate this
29 process: this program will extract snippets of music from your
30 document, run lilypond on them, and substitute the resulting pictures
31 back. This works for La@TeX{}, @code{html} or texinfo documents.
32 @code{lilypond-book} introduces some extra LilyPond specific
33 constructs, that integrate seamlessly with the rest of your source
41 @cindex documents, adding music to
44 More precisely, if a La@TeX{} file contains
56 then LilyPond is run on CONTENTS. @command{lilypond-book} puts the
57 result back into the latex file. When you run the result through latex,
58 you get a document that mixes text and music. lilypond-book will insert
59 line width and font size definitions before @code{CONTENTS}, so the
60 music samples will match the layout of your document.
62 Very often, if you mix music and text, the music is only a few
63 notes or at most a few bars. This music should be as short as possible
64 and not stretched to be aligned to the right margin. lilypond-book does
65 this automatically if you don't use a @code{\score} block in
66 @code{CONTENTS}. For example: @code{\lilypond@{\context Voice <c' e' g'>
69 You can also use @code{lilypondfile} to include another file:
71 \lilypondfile@{foo.ly@}
74 All three forms can take several options. They are specified in brackets
77 \lilypondfile[options, go, here]@{ .. @}
78 \begin[options, go, here]@{lilypond@} .. \end@{lilypond@}
79 \lilypond[options, go,here]@{ .. @}
82 In the Texinfo version, bitmaps of the music are also generated, so you
83 can make a HTML document with embedded music.
86 @section Texinfo reference
88 You specify the LilyPond code like this:
90 @@lilypond[options, go, here]
93 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
94 @@lilypondfile[options, go,here]@{@var{filename}@}
97 We show two simple examples here. First a complete block:
109 Then the short version:
111 @@lilypond[11pt]@{<c' e' g'>@}
116 @lilypond[11pt]{<c' e' g'>}
118 @command{lilypond-book} knows the default margins, and a few paper
119 sizes. One of these commands should be in the beginning of the document:
121 @item @code{@@afourpaper}
122 @item @code{@@afourlatex}
123 @item @code{@@afourwide}
124 @item @code{@@smallbook}
126 @code{@@pagesizes} are not yet supported.
128 @section La@TeX{} reference
130 You specify the LilyPond code like this:
132 \begin[option, go, here]@{lilypond@}
138 \lilypondfile[options, go,here]@{@var{filename}@}
142 \lilypond@{ YOUR LILYPOND CODE @}
145 We show some examples here.
148 \begin[26pt]@{lilypond@}
159 Then the short version:
161 \lilypond[11pt]@{<c' e' g'>@}
166 @lilypond[11pt]{<c' e' g'>}
169 You can use whatever commands you like in the document preamble,
170 that is the part of the document before @code{\begin@{document@}}.
171 @command{lilypond-book} will send it to La@TeX{} to find out how wide
172 the text is and adjust the linewidth variable in the paper definition of
173 you music according to that.
175 After @code{\begin@{document@}} you must be a little more careful
176 when you use commands that change the width of the text and how
177 many columns there are. @command{lilypond-book} know about the
178 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
179 environment from the multicol package.
181 The music will be surrounded by @code{\preLilypondExample} and
182 @code{\postLilypondExample}. The variables are
183 defined to nothing by default, and the user can redefine them
184 to whatever he wants.
187 @section HTML reference
189 You specify the LilyPond code like this:
193 <lilypond relative1 verbatim>
194 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
203 <lilypond relative1 verbatim>
204 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
208 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
216 Some music in <lilypond a b c/> a line of text.
220 @c Huh? ugh, can't show inline pictures in texinfo?
222 @c Some music in @lilypond{a b c} a line of text.
230 This will create the music as eps graphics and include it into the
231 document with the @code{\includegraphics} command. It works in
234 This enables you to place music examples in the running text (and not in
235 a separate paragraph). To avoid that La@TeX{} places the music on a line
236 of its own, there should be no empty lines between the normal text and
237 the LilyPond environment. For inline music, you probably also need a
238 smaller music font size (eg. 11 pt or 13 pt)
242 CONTENTS is copied into the source enclosed in a verbatim block,
243 followed by any text given with the @code{intertext} option, then
244 the actual music is displayed. This option does not work with
245 the short version of the LilyPond blocks:
247 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
250 like @code{verbatim}, but in a smaller font.
252 @item intertext="@var{text}"
253 Used in conjunction with @code{verbatim} option: this puts
254 @var{text} between the code and the music.
255 @item filename="@var{filename}"
256 Save the LilyPond code to @var{filename}. By default, a hash value
262 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
263 [d16 g, a b][c a b g][d'8 g f-\prall g]
269 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
270 [d16 g, a b][c a b g][d'8 g f-\prall g]
276 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
277 [d16 g, a b][c a b g][d'8 g f-\prall g]
283 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
284 [d16 g, a b][c a b g][d'8 g f-\prall g]
290 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
295 Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
297 The opposite of @code{singleline}: justify and break lines.
298 @item linewidth=@var{size}@var{unit}
299 Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
302 Override @command{lilypond-book} auto detection of what type of code is in the
303 LilyPond block, voice contents or complete code.
304 @item indent=@var{size}@var{unit}
305 Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
307 Set first line indent to zero.
309 Prints the file name before the music example. Useful in conjunction
310 with @code{\lilypondfile}.
311 @item relative, relative @var{N}
312 Use relative octave mode. By default, notes are specified relative
313 central C. The optional integer argument specifies how many octaves
314 higher (positive number) or lower (negative number) to place the
320 When you run @command{lilypond-book} it will generate lots of small
321 files that LilyPond will process. So to avoid all the garbage in
322 your source directory, you should either change to a temporary
323 directory, or use the @code{--outdir} command line options:
325 @code{cd out && lilypond-book ../yourfile.tex}
327 @code{lilypond-book --outdir=out yourfile.tex}
330 For latex input, the file to give to latex has extension @file{.latex}.
331 Texinfo input will be written to a file with extension @file{.texi}.
333 If you use @code{--outdir}, you should also @code{cd} to that directory
334 before running LaTeX or makeinfo. This may seem a little kludgey, but
335 both Latex and makeinfo expect picture files (the music) to be in the
336 current working directory. Moreover, if you do this, LaTeX will not
337 clutter you normal working directory with output files.
339 @cindex titling and lilypond-book
340 @cindex lilypond-book and titling
341 @cindex \header in LaTeX documents
343 If you want to add titling from the @code{\header} section of the
344 files, you should add the following to the top of your LaTeX
347 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
350 lilypond-book accepts the following command-line options:
352 @item @option{-f}, @option{--format=}
353 Specify the document type to process: @code{html}, @code{latex} or
354 @code{texi} (default). @command{lilypond-book} usually figures this
356 @item --default-music-fontsize=@var{sz}pt
357 Set the fontsize to use for LilyPond if no fontsize is given
359 @item --force-music-fontsize=@var{sz}pt
360 Force all LilyPond to use this fontsize, overriding options
361 given to @code{\begin@{lilypond@}}
362 @item -I @var{DIR}, --include=@var{DIR}
363 Add @var{DIR} to the include path.
364 @item -M, --dependencies
365 Write dependencies to @file{filename.dep}
366 @item --dep-prefix=@code{PREF}
367 prepend @code{PREF} before each @code{-M} dependency
369 don't run LilyPond, but do generate the @code{.ly} files
371 strip all LilyPond blocks from the file.
373 don't generate pictures when processing Texinfo.
375 don't write ly files. This way you can do
377 lilypond-book file.tely
379 lilypond-book --read-lys
382 [TODO not a useful option unless you can undump the input file]
384 @item --outname=@var{FILE}
385 The name of La@TeX{} file to output. If this option is not given,
386 the output name is derived from the input name.
387 @item --outdir=@var{DIR}
388 place generated files in @var{DIR}.
390 print version information
392 Print a short help message
398 The La@TeX{} \includeonly@{...@} command is ignored.
400 The Texinfo command @code{pagesize} is on the TODO list for LilyPond
401 1.6, but changing the linewidth in other ways will not give you a
402 straight right margin.
404 Almost all La@TeX{} commands that change margins and line widths are
407 There is no way to automatically apply convert-ly to fragments inside a
410 @file{lilypond-book} processes all music fragments in one big run. The
411 state of the GUILE interpreter is not reset between fragments; this
412 means that GUILE definitions, eg. done with @code{#(define .. )} and
413 @code{#(set! .. )} can leak from one fragment into a next fragment.