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 outputs your document with the resulting
26 pictures substituted for the music you entered. The line width and
27 font size definitions for the music are adjusted to match the layout
30 It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
31 on using lilypond-book is in @ref{Integrating text and music}.
34 * Integrating Texinfo and music::
35 * Integrating La@TeX{} and music::
36 * Integrating HTML and music::
37 * Music fragment options::
38 * Invoking lilypond-book::
47 @cindex documents, adding music to
50 @node Integrating Texinfo and music
51 @section Integrating Texinfo and music
53 You specify the LilyPond code like this:
56 @@lilypond[options, go, here]
59 @@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
60 @@lilypondfile[options, go, here]@{@var{filename}@}
63 Then you run lilypond-book on it, and the result is a file you can
64 process with texinfo. We show two simple examples here. First a
80 Then the short version:
83 @@lilypond[11pt]@{<<c' e' g'>>@}
89 @lilypond[11pt]{ <<c' e' g'>> }
91 @command{lilypond-book} knows the default margins and a few paper
92 sizes. One of these commands should be in the beginning of the document:
95 @item @code{@@afourpaper}
96 @item @code{@@afourlatex}
97 @item @code{@@afourwide}
98 @item @code{@@smallbook}
102 @code{@@pagesizes} are not yet supported.
104 When producing texinfo, lilypond-book also generates bitmaps of the
105 music, so you can make a HTML document with embedded music.
108 @node Integrating La@TeX{} and music
109 @section Integrating La@TeX{} and music
112 You specify LilyPond code like this:
115 \begin[options, go, here]@{lilypond@}
121 \lilypondfile[options, go,here]@{@var{filename}@}
128 \lilypond@{ YOUR LILYPOND CODE @}
131 Then you run lilypond-book on it, and the result is a file you can
132 process with La@TeX{}. We show some examples here.
135 \begin[26pt]@{lilypond@}
147 Then the short version:
150 \lilypond[11pt]@{<<c' e' g'>>@}
156 @lilypond[11pt]{<<c' e' g'>>}
158 You can use whatever commands you like in the document preamble,
159 the part of the document before @code{\begin@{document@}}.
160 @command{lilypond-book} will send it to La@TeX{} to find out how wide
161 the text is and adjust the linewidth variable in the paper definition of
162 your music according to that.
164 After @code{\begin@{document@}} you must be a little more careful
165 when you use commands that change the width of the text and how
166 many columns there are. @command{lilypond-book} knows about the
167 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
168 environment from the multicol package.
170 The music will be surrounded by @code{\preLilypondExample} and
171 @code{\postLilypondExample}. The variables are
172 defined to nothing by default, and the user can redefine them
173 to whatever he wants.
176 @node Integrating HTML and music
177 @section Integrating HTML and music
179 You specify LilyPond code like this:
182 <lilypond relative1 verbatim>
183 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
188 Then you run lilypond-book on it, and the result is a file you can
189 process with La@TeX{}. The final result look like
192 <lilypond relative1 verbatim>
193 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
198 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
201 For inline pictures, use @code{<lilypond ... />} syntax, eg.
203 Some music in <lilypond a b c/> a line of text.
207 @node Music fragment options
208 @section Music fragment options
210 The commands for lilypond-book have room to specify options. These are
215 This will create the music as eps graphics and include it into the
216 document with the @code{\includegraphics} command. It works in
219 This enables you to place music examples in the running text (and not in
220 a separate paragraph). To avoid that La@TeX{} places the music on a line
221 of its own, there should be no empty lines between the normal text and
222 the LilyPond environment. For inline music, you probably also need a
223 smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})
226 CONTENTS is copied into the source enclosed in a verbatim block,
227 followed by any text given with the @code{intertext} option, then
228 the actual music is displayed. This option does not work with
229 the short version of the LilyPond blocks:
231 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
234 Like @code{verbatim}, but in a smaller font.
236 @item intertext="@var{text}"
237 Used in conjunction with @code{verbatim} option: This puts
238 @var{text} between the code and the music (without indentation).
240 @item filename="@var{filename}"
241 Save the LilyPond code to @var{filename}. By default, a hash value
247 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
248 [d16 g, a b][c a b g][d'8 g f-\prall g]
255 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
256 [d16 g, a b][c a b g][d'8 g f-\prall g]
263 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
270 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
277 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
282 Produce a single, naturally spaced, unjustified line
283 (i.e., linewidth = @minus{}1).
286 The opposite of @code{singleline}: Justify and break lines.
288 @item linewidth=@var{size}@var{unit}
289 Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
290 This option affects LilyPond output, not the text layout.
293 Don't print time signature.
297 Override @command{lilypond-book} auto detection of what type of code is
298 in the LilyPond block, voice contents or complete code.
300 @item indent=@var{size}@var{unit}
301 Set indentation of the first music system to @var{size},
302 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
303 not the text layout. For single-line fragments the default is to
307 Set indentation of the first music system to zero. This option
308 affects LilyPond, not the text layout.
311 By default, @command{lilypond-book} puts both La@TeX{} and texinfo output
312 into a quotation block. Using this option prevents this; no indentation
316 Prints the file name before the music example. Useful in conjunction
317 with @code{\lilypondfile}.
319 @item relative, relative @var{N}
320 Use relative octave mode. By default, notes are specified relative
321 central C. The optional integer argument specifies how many octaves
322 higher (positive number) or lower (negative number) to place the
327 @node Invoking lilypond-book
328 @section Invoking lilypond-book
330 When you run @command{lilypond-book} it will generate lots of small
331 files that LilyPond will process. To avoid all the garbage in
332 your source directory, you should either change to a temporary
333 directory, or use the @option{--outdir} command line options:
335 @code{cd out && lilypond-book ../yourfile.tex}
337 @code{lilypond-book --outdir=out yourfile.tex}
339 For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
340 Texinfo input will be written to a file with extension @file{.texi}.
342 If you use @option{--outdir}, you should also @code{cd} to that directory
343 before running La@TeX{} or @command{makeinfo}. This may seem a little
344 kludgy, but both La@TeX{} and @command{makeinfo} expect picture files
345 (the music) to be in the current working directory. Moreover, if you do
346 this, La@TeX{} will not clutter your normal working directory with output
349 @cindex titling and lilypond-book
350 @cindex lilypond-book and titling
351 @cindex @code{\header} in La@TeX{} documents
353 If you want to add titling from the @code{\header} section of the
354 files, you should add the following to the top of your La@TeX{} file:
358 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
361 @command{lilypond-book} accepts the following command line options:
364 @item @option{-f @var{format}}, @option{--format=@var{format}}
365 Specify the document type to process: @code{html}, @code{latex} or
366 @code{texi} (the default). @command{lilypond-book} usually figures this
369 Note that the @code{texi} document type produces a DVI file; to
370 convert a texinfo document to @code{html}, you should use the additional
371 format @code{texi-html} instead of @code{texi} to convert lilypond
372 fragments to PNG images.
374 @item @option{--default-music-fontsize=@var{sz}pt}
375 Set the fontsize to use for LilyPond if no fontsize is given
378 @item @option{--force-music-fontsize=@var{sz}pt}
379 Force all LilyPond code to use this fontsize, overriding options
380 given to @code{\begin@{lilypond@}}.
382 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
383 Add @var{DIR} to the include path.
385 @item @option{-M}, @option{--dependencies}
386 Write dependencies to @file{filename.dep}.
388 @item @option{--dep-prefix=@var{pref}}
389 Prepend @var{pref} before each @option{-M} dependency.
391 @item @option{-n}, @option{--no-lily}
392 Don't run LilyPond, but do generate the @code{.ly} files.
394 @item @option{--no-music}
395 Strip all LilyPond blocks from the file.
397 @item @option{--no-pictures}
398 Don't generate pictures when processing Texinfo.
400 @item @option{--read-lys}
401 Don't write ly files. This way you can do
404 lilypond-book file.tely
406 lilypond-book --read-lys
409 @item @option{--outname=@var{file}}
410 The name of La@TeX{} file to output. If this option is not given,
411 the output name is derived from the input name.
413 @item @option{--outdir=@var{dir}}
414 Place generated files in @var{dir}.
416 @item @option{--version}
417 Print version information.
419 @item @option{--help}
420 Print a short help message.
426 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
428 The Texinfo command @code{pagesize} is on the TODO list for LilyPond
429 1.8, but changing the linewidth in other ways will not give you a
430 straight right margin.
432 Almost all La@TeX{} commands that change margins and line widths are
435 There is no way to automatically apply @command{convert-ly} only to fragments
436 inside a lilypond-book file.
438 @command{lilypond-book} processes all music fragments in one big run. The
439 state of the GUILE interpreter is not reset between fragments; this
440 means that global GUILE definitions, e.g., done with @code{#(define @dots{})}
441 and @code{#(set! @dots{})} can leak from one fragment into the next fragment.