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
27 to 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:
55 @@lilypond[options, go, here]
58 @@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
59 @@lilypondfile[options, go, here]@{@var{filename}@}
62 We show two simple examples here. First a complete block:
77 Then the short version:
80 @@lilypond[11pt]@{<c' e' g'>@}
86 @lilypond[11pt]{<c' e' g'>}
88 @command{lilypond-book} knows the default margins and a few paper
89 sizes. One of these commands should be in the beginning of the document:
92 @item @code{@@afourpaper}
93 @item @code{@@afourlatex}
94 @item @code{@@afourwide}
95 @item @code{@@smallbook}
99 @code{@@pagesizes} are not yet supported.
101 When producing texinfo, lilypond-book also generates bitmaps of the
102 music, so you can make a HTML document with embedded music.
105 @node Integrating La@TeX{} and music
106 @section Integrating La@TeX{} and music
108 You specify LilyPond code like this:
111 \begin[options, go, here]@{lilypond@}
117 \lilypondfile[options, go,here]@{@var{filename}@}
124 \lilypond@{ YOUR LILYPOND CODE @}
127 We show some examples here.
130 \begin[26pt]@{lilypond@}
142 Then the short version:
145 \lilypond[11pt]@{<c' e' g'>@}
151 @lilypond[11pt]{<c' e' g'>}
153 You can use whatever commands you like in the document preamble,
154 the part of the document before @code{\begin@{document@}}.
155 @command{lilypond-book} will send it to La@TeX{} to find out how wide
156 the text is and adjust the linewidth variable in the paper definition of
157 your music according to that.
159 After @code{\begin@{document@}} you must be a little more careful
160 when you use commands that change the width of the text and how
161 many columns there are. @command{lilypond-book} knows about the
162 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
163 environment from the multicol package.
165 The music will be surrounded by @code{\preLilypondExample} and
166 @code{\postLilypondExample}. The variables are
167 defined to nothing by default, and the user can redefine them
168 to whatever he wants.
171 @node Integrating HTML and music
172 @section Integrating HTML and music
174 You specify LilyPond code like this:
177 <lilypond relative1 verbatim>
178 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
186 <lilypond relative1 verbatim>
187 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
192 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
198 Some music in <lilypond a b c/> a line of text.
202 @node Music fragment options
203 @section Music fragment options
205 The commands for lilypond-book have room to specify options. These are
210 This will create the music as eps graphics and include it into the
211 document with the @code{\includegraphics} command. It works in
214 This enables you to place music examples in the running text (and not in
215 a separate paragraph). To avoid that La@TeX{} places the music on a line
216 of its own, there should be no empty lines between the normal text and
217 the LilyPond environment. For inline music, you probably also need a
218 smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})
221 CONTENTS is copied into the source enclosed in a verbatim block,
222 followed by any text given with the @code{intertext} option, then
223 the actual music is displayed. This option does not work with
224 the short version of the LilyPond blocks:
226 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
229 Like @code{verbatim}, but in a smaller font.
231 @item intertext="@var{text}"
232 Used in conjunction with @code{verbatim} option: This puts
233 @var{text} between the code and the music (without indentation).
235 @item filename="@var{filename}"
236 Save the LilyPond code to @var{filename}. By default, a hash value
242 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
243 [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]
258 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
265 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
272 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
277 Produce a single, naturally spaced, unjustified line
278 (i.e., linewidth = @minus{}1).
281 The opposite of @code{singleline}: Justify and break lines.
283 @item linewidth=@var{size}@var{unit}
284 Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
285 This option affects LilyPond output, not the text layout.
288 Don't print time signature.
292 Override @command{lilypond-book} auto detection of what type of code is
293 in the LilyPond block, voice contents or complete code.
295 @item indent=@var{size}@var{unit}
296 Set indentation of the first music system to @var{size},
297 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
298 not the text layout. For single-line fragments the default is to
302 Set indentation of the first music system to zero. This option
303 affects LilyPond, not the text layout.
306 By default, @command{lilypond-book} puts both La@TeX{} and texinfo output
307 into a quotation block. Using this option prevents this; no indentation
311 Prints the file name before the music example. Useful in conjunction
312 with @code{\lilypondfile}.
314 @item relative, relative @var{N}
315 Use relative octave mode. By default, notes are specified relative
316 central C. The optional integer argument specifies how many octaves
317 higher (positive number) or lower (negative number) to place the
322 @node Invoking lilypond-book
323 @section Invoking lilypond-book
325 When you run @command{lilypond-book} it will generate lots of small
326 files that LilyPond will process. To avoid all the garbage in
327 your source directory, you should either change to a temporary
328 directory, or use the @option{--outdir} command line options:
330 @code{cd out && lilypond-book ../yourfile.tex}
332 @code{lilypond-book --outdir=out yourfile.tex}
334 For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
335 Texinfo input will be written to a file with extension @file{.texi}.
337 If you use @option{--outdir}, you should also @code{cd} to that directory
338 before running La@TeX{} or @command{makeinfo}. This may seem a little
339 kludgy, but both La@TeX{} and @command{makeinfo} expect picture files
340 (the music) to be in the current working directory. Moreover, if you do
341 this, La@TeX{} will not clutter your normal working directory with output
344 @cindex titling and lilypond-book
345 @cindex lilypond-book and titling
346 @cindex @code{\header} in La@TeX{} documents
348 If you want to add titling from the @code{\header} section of the
349 files, you should add the following to the top of your La@TeX{} file:
353 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
356 @command{lilypond-book} accepts the following command line options:
359 @item @option{-f @var{format}}, @option{--format=@var{format}}
360 Specify the document type to process: @code{html}, @code{latex} or
361 @code{texi} (the default). @command{lilypond-book} usually figures this
364 Note that the @code{texi} document type produces a DVI file; to
365 convert a texinfo document to @code{html}, you should use the additional
366 format @code{texi-html} instead of @code{texi} to convert lilypond
367 fragments to PNG images.
369 @item @option{--default-music-fontsize=@var{sz}pt}
370 Set the fontsize to use for LilyPond if no fontsize is given
373 @item @option{--force-music-fontsize=@var{sz}pt}
374 Force all LilyPond code to use this fontsize, overriding options
375 given to @code{\begin@{lilypond@}}.
377 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
378 Add @var{DIR} to the include path.
380 @item @option{-M}, @option{--dependencies}
381 Write dependencies to @file{filename.dep}.
383 @item @option{--dep-prefix=@var{pref}}
384 Prepend @var{pref} before each @option{-M} dependency.
386 @item @option{-n}, @option{--no-lily}
387 Don't run LilyPond, but do generate the @code{.ly} files.
389 @item @option{--no-music}
390 Strip all LilyPond blocks from the file.
392 @item @option{--no-pictures}
393 Don't generate pictures when processing Texinfo.
395 @item @option{--read-lys}
396 Don't write ly files. This way you can do
399 lilypond-book file.tely
401 lilypond-book --read-lys
404 @item @option{--outname=@var{file}}
405 The name of La@TeX{} file to output. If this option is not given,
406 the output name is derived from the input name.
408 @item @option{--outdir=@var{dir}}
409 Place generated files in @var{dir}.
411 @item @option{--version}
412 Print version information.
414 @item @option{--help}
415 Print a short help message.
421 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
423 The Texinfo command @code{pagesize} is on the TODO list for LilyPond
424 1.8, but changing the linewidth in other ways will not give you a
425 straight right margin.
427 Almost all La@TeX{} commands that change margins and line widths are
430 There is no way to automatically apply @command{convert-ly} only to fragments
431 inside a lilypond-book file.
433 @command{lilypond-book} processes all music fragments in one big run. The
434 state of the GUILE interpreter is not reset between fragments; this
435 means that global GUILE definitions, e.g., done with @code{#(define @dots{})}
436 and @code{#(set! @dots{})} can leak from one fragment into the next fragment.