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 @node Integrating text and music with lilypond-book
15 @chapter Integrating text and music with lilypond-book
17 If you want to add pictures of music to a document, you can simply do
18 it the way you would do with other types of pictures. You write
19 LilyPond code, process it separately to embedded PostScript or
20 @code{png}, and include it as a picture into your La@TeX{} or
23 @command{lilypond-book} provides you with a way to automate this
24 process: this program extracts snippets of music from your document,
25 runs lilypond on them, and substitutes the resulting pictures back.
26 The line width and font size definitions for the music are adjusted so
27 they match the layout of your document.
29 It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
30 on using lilypond-book is in @ref{Integrating text and music}.
33 * Integrating Texinfo and music::
34 * Integrating La@TeX{} and music::
35 * Integrating HTML and music::
36 * Music fragment options::
37 * Invoking lilypond-book::
46 @cindex documents, adding music to
49 @node Integrating Texinfo and music
50 @section Integrating Texinfo and music
52 You specify the LilyPond code like this:
54 @@lilypond[options, go, here]
57 @@lilypond[option, go, here]@{ YOUR LILYPOND CODE @}
58 @@lilypondfile[options, go,here]@{@var{filename}@}
61 We show two simple examples here. First a complete block:
73 Then the short version:
75 @@lilypond[11pt]@{<c' e' g'>@}
80 @lilypond[11pt]{<c' e' g'>}
82 @command{lilypond-book} knows the default margins, and a few paper
83 sizes. One of these commands should be in the beginning of the document:
85 @item @code{@@afourpaper}
86 @item @code{@@afourlatex}
87 @item @code{@@afourwide}
88 @item @code{@@smallbook}
90 @code{@@pagesizes} are not yet supported.
92 When producing texinfo, lilypond-book also generates bitmaps of the
93 music, so you can make a HTML document with embedded music.
95 @node Integrating La@TeX{} and music
96 @section Integrating La@TeX{} and music
98 You specify the LilyPond code like this:
100 \begin[option, go, here]@{lilypond@}
106 \lilypondfile[options, go,here]@{@var{filename}@}
110 \lilypond@{ YOUR LILYPOND CODE @}
113 We show some examples here.
116 \begin[26pt]@{lilypond@}
127 Then the short version:
129 \lilypond[11pt]@{<c' e' g'>@}
134 @lilypond[11pt]{<c' e' g'>}
137 You can use whatever commands you like in the document preamble,
138 that is the part of the document before @code{\begin@{document@}}.
139 @command{lilypond-book} will send it to La@TeX{} to find out how wide
140 the text is and adjust the linewidth variable in the paper definition of
141 you music according to that.
143 After @code{\begin@{document@}} you must be a little more careful
144 when you use commands that change the width of the text and how
145 many columns there are. @command{lilypond-book} know about the
146 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
147 environment from the multicol package.
149 The music will be surrounded by @code{\preLilypondExample} and
150 @code{\postLilypondExample}. The variables are
151 defined to nothing by default, and the user can redefine them
152 to whatever he wants.
155 @node Integrating HTML and music
156 @section Integrating HTML and music
158 You specify the LilyPond code like this:
162 <lilypond relative1 verbatim>
163 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
172 <lilypond relative1 verbatim>
173 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
177 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
185 Some music in <lilypond a b c/> a line of text.
189 @node Music fragment options
190 @section Music fragment options
192 The commands for lilypond-book have room to specify options. These are
197 This will create the music as eps graphics and include it into the
198 document with the @code{\includegraphics} command. It works in
201 This enables you to place music examples in the running text (and not in
202 a separate paragraph). To avoid that La@TeX{} places the music on a line
203 of its own, there should be no empty lines between the normal text and
204 the LilyPond environment. For inline music, you probably also need a
205 smaller music font size (eg. 11 pt or 13 pt)
209 CONTENTS is copied into the source enclosed in a verbatim block,
210 followed by any text given with the @code{intertext} option, then
211 the actual music is displayed. This option does not work with
212 the short version of the LilyPond blocks:
214 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
217 like @code{verbatim}, but in a smaller font.
219 @item intertext="@var{text}"
220 Used in conjunction with @code{verbatim} option: this puts
221 @var{text} between the code and the music.
222 @item filename="@var{filename}"
223 Save the LilyPond code to @var{filename}. By default, a hash value
229 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
230 [d16 g, a b][c a b g][d'8 g f-\prall g]
236 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
237 [d16 g, a b][c a b g][d'8 g f-\prall g]
243 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
244 [d16 g, a b][c a b g][d'8 g f-\prall g]
250 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
251 [d16 g, a b][c a b g][d'8 g f-\prall g]
257 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
262 Produce a single naturally spaced, unjustified line. (i.e.: linewidth = -1).
264 The opposite of @code{singleline}: justify and break lines.
265 @item linewidth=@var{size}@var{unit}
266 Set linewidth to @var{size}, where @var{unit} = cm, mm, in or pt.
269 Override @command{lilypond-book} auto detection of what type of code is in the
270 LilyPond block, voice contents or complete code.
271 @item indent=@var{size}@var{unit}
272 Set first line indent to @var{size}, where @var{unit} = cm, mm, in or pt.
274 Set first line indent to zero.
276 Prints the file name before the music example. Useful in conjunction
277 with @code{\lilypondfile}.
278 @item relative, relative @var{N}
279 Use relative octave mode. By default, notes are specified relative
280 central C. The optional integer argument specifies how many octaves
281 higher (positive number) or lower (negative number) to place the
285 @node Invoking lilypond-book
286 @section Invoking lilypond-book
288 When you run @command{lilypond-book} it will generate lots of small
289 files that LilyPond will process. So to avoid all the garbage in
290 your source directory, you should either change to a temporary
291 directory, or use the @code{--outdir} command line options:
293 @code{cd out && lilypond-book ../yourfile.tex}
295 @code{lilypond-book --outdir=out yourfile.tex}
298 For latex input, the file to give to latex has extension @file{.latex}.
299 Texinfo input will be written to a file with extension @file{.texi}.
301 If you use @code{--outdir}, you should also @code{cd} to that directory
302 before running LaTeX or makeinfo. This may seem a little kludgey, but
303 both Latex and makeinfo expect picture files (the music) to be in the
304 current working directory. Moreover, if you do this, LaTeX will not
305 clutter you normal working directory with output files.
307 @cindex titling and lilypond-book
308 @cindex lilypond-book and titling
309 @cindex \header in LaTeX documents
311 If you want to add titling from the @code{\header} section of the
312 files, you should add the following to the top of your LaTeX
315 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
318 lilypond-book accepts the following command-line options:
320 @item @option{-f}, @option{--format=}
321 Specify the document type to process: @code{html}, @code{latex} or
322 @code{texi} (default). @command{lilypond-book} usually figures this
325 @item --default-music-fontsize=@var{sz}pt
326 Set the fontsize to use for LilyPond if no fontsize is given
328 @item --force-music-fontsize=@var{sz}pt
329 Force all LilyPond to use this fontsize, overriding options
330 given to @code{\begin@{lilypond@}}
331 @item -I @var{DIR}, --include=@var{DIR}
332 Add @var{DIR} to the include path.
333 @item -M, --dependencies
334 Write dependencies to @file{filename.dep}
335 @item --dep-prefix=@code{PREF}
336 prepend @code{PREF} before each @code{-M} dependency
338 don't run LilyPond, but do generate the @code{.ly} files
340 strip all LilyPond blocks from the file.
342 don't generate pictures when processing Texinfo.
344 don't write ly files. This way you can do
346 lilypond-book file.tely
348 lilypond-book --read-lys
351 @item --outname=@var{FILE}
352 The name of La@TeX{} file to output. If this option is not given,
353 the output name is derived from the input name.
354 @item --outdir=@var{DIR}
355 place generated files in @var{DIR}.
357 print version information
359 Print a short help message
365 The La@TeX{} \includeonly@{...@} command is ignored.
367 The Texinfo command @code{pagesize} is on the TODO list for LilyPond
368 1.6, but changing the linewidth in other ways will not give you a
369 straight right margin.
371 Almost all La@TeX{} commands that change margins and line widths are
374 There is no way to automatically apply convert-ly only to fragments
375 inside a lilypond-book file.
377 @file{lilypond-book} processes all music fragments in one big run. The
378 state of the GUILE interpreter is not reset between fragments; this
379 means that global GUILE definitions, eg. done with @code{#(define
380 .. )} and @code{#(set! .. )} can leak from one fragment into a next