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?
15 @node Integrating text and music with lilypond-book
16 @chapter Integrating text and music with lilypond-book
18 If you want to add pictures of music to a document, you can simply do
19 it the way you would do with other types of pictures. You write
20 LilyPond code, process it separately to embedded PostScript or
21 @code{png}, and include it as a picture into your La@TeX{} or
24 @command{lilypond-book} provides you with a way to automate this
25 process: This program extracts snippets of music from your document,
26 runs LilyPond on them, and outputs your document with the resulting
27 pictures substituted for the music you entered. The line width and
28 font size definitions for the music are adjusted to match the layout
31 It can work on La@TeX{}, @code{html} or texinfo documents. A tutorial
32 on using lilypond-book is in @ref{Integrating text and music}. In
33 case that you do not know La@TeX{}, then
34 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
35 Short Introduction to LaTeX} provides a introction to using La@TeX{}.
39 * Integrating Texinfo and music::
40 * Integrating La@TeX{} and music::
41 * Integrating HTML and music::
42 * Music fragment options::
43 * Invoking lilypond-book::
46 TODO: explain how to use lilypond fonts in text.
54 @cindex documents, adding music to
57 @node Integrating Texinfo and music
58 @section Integrating Texinfo and music
60 You specify the LilyPond code like this:
63 @@lilypond[options, go, here]
66 @@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
67 @@lilypondfile[options, go, here]@{@var{filename}@}
70 Then you run lilypond-book on it, and the result is a file you can
71 process with texinfo. We show two simple examples here. First a
87 Then the short version:
90 @@lilypond[11pt]@{<<c' e' g'>>@}
96 @lilypond[11pt]{ <<c' e' g'>> }
98 @command{lilypond-book} knows the default margins and a few paper
99 sizes. One of these commands should be in the beginning of the document:
102 @item @code{@@afourpaper}
103 @item @code{@@afourlatex}
104 @item @code{@@afourwide}
105 @item @code{@@smallbook}
109 @code{@@pagesizes} are not yet supported.
111 When producing texinfo, lilypond-book also generates bitmaps of the
112 music, so you can make a HTML document with embedded music.
115 @node Integrating La@TeX{} and music
116 @section Integrating La@TeX{} and music
119 You specify LilyPond code like this:
122 \begin[options, go, here]@{lilypond@}
128 \lilypondfile[options, go,here]@{@var{filename}@}
135 \lilypond@{ YOUR LILYPOND CODE @}
138 Then you run lilypond-book on it, and the result is a file you can
139 process with La@TeX{}. We show some examples here.
142 \begin[26pt]@{lilypond@}
154 Then the short version:
157 \lilypond[11pt]@{<<c' e' g'>>@}
163 @lilypond[11pt]{<<c' e' g'>>}
165 You can use whatever commands you like in the document preamble,
166 the part of the document before @code{\begin@{document@}}.
167 @command{lilypond-book} will send it to La@TeX{} to find out how wide
168 the text is and adjust the linewidth variable in the paper definition of
169 your music according to that.
171 After @code{\begin@{document@}} you must be a little more careful
172 when you use commands that change the width of the text and how
173 many columns there are. @command{lilypond-book} knows about the
174 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
175 environment from the multicol package.
177 The music will be surrounded by @code{\preLilypondExample} and
178 @code{\postLilypondExample}. The variables are
179 defined to nothing by default, and the user can redefine them
180 to whatever he wants.
183 @node Integrating HTML and music
184 @section Integrating HTML and music
186 You specify LilyPond code like this:
189 <lilypond relative1 verbatim>
190 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
195 Then you run lilypond-book on it, and the result is a file you can
196 process with La@TeX{}. The final result look like
199 <lilypond relative1 verbatim>
200 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
205 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
208 For inline pictures, use @code{<lilypond ... />} syntax, eg.
210 Some music in <lilypond a b c/> a line of text.
213 A special feature not (yet) available in other output formats, is the
214 @code{<ly2dvifile>} tag, for example
216 <ly2dvifile>trip.ly</ly2dvifile>
218 This runs @file{trip.ly} through ly2dvi (See also @ref{Invoking
219 ly2dvi}), and substitutes a preview image in the output. The image
220 links to a separate HTML file, so clicking it will take the viewer to
221 a menu, with links to images, midi and printouts.
224 @cindex titling in THML
225 @cindex preview image
228 @node Music fragment options
229 @section Music fragment options
231 The commands for lilypond-book have room to specify options. These
232 are all of the options:
236 This will create the music as eps graphics and include it into the
237 document with the @code{\includegraphics} command. It works in
240 This enables you to place music examples in the running text (and not in
241 a separate paragraph). To avoid that La@TeX{} places the music on a line
242 of its own, there should be no empty lines between the normal text and
243 the LilyPond environment. For inline music, you probably also need a
244 smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})
247 CONTENTS is copied into the source enclosed in a verbatim block,
248 followed by any text given with the @code{intertext} option, then
249 the actual music is displayed. This option does not work with
250 the short version of the LilyPond blocks:
252 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
255 Like @code{verbatim}, but in a smaller font.
257 @item intertext="@var{text}"
258 Used in conjunction with @code{verbatim} option: This puts
259 @var{text} between the code and the music (without indentation).
261 @item filename="@var{filename}"
262 Save the LilyPond code to @var{filename}. By default, a hash value
268 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
269 [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]
284 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
291 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
298 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
303 Produce a single, naturally spaced, unjustified line
304 (i.e., linewidth = @minus{}1).
307 The opposite of @code{singleline}: Justify and break lines.
309 @item linewidth=@var{size}@var{unit}
310 Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
311 This option affects LilyPond output, not the text layout.
314 Do not print time signature.
318 Override @command{lilypond-book} auto detection of what type of code is
319 in the LilyPond block, voice contents or complete code.
321 @item indent=@var{size}@var{unit}
322 Set indentation of the first music system to @var{size},
323 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
324 not the text layout. For single-line fragments the default is to
328 Set indentation of the first music system to zero. This option
329 affects LilyPond, not the text layout.
332 Do not include the .texidoc header. This is only for Texinfo output.
335 Instruct @command{lilypond-book} to put La@TeX{} and texinfo output
336 into a quotation block.
339 Prints the file name before the music example. Useful in conjunction
340 with @code{\lilypondfile}.
342 @item relative, relative @var{N}
343 Use relative octave mode. By default, notes are specified relative
344 central C. The optional integer argument specifies how many octaves
345 higher (positive number) or lower (negative number) to place the
350 @node Invoking lilypond-book
351 @section Invoking lilypond-book
353 When you run @command{lilypond-book} it will generate lots of small
354 files that LilyPond will process. To avoid all the garbage in
355 your source directory, you should either change to a temporary
356 directory, or use the @option{--outdir} command line options:
358 @code{cd out && lilypond-book ../yourfile.tex}
360 @code{lilypond-book --outdir=out yourfile.tex}
362 For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
363 Texinfo input will be written to a file with extension @file{.texi}.
365 If you use @option{--outdir}, you should also @code{cd} to that directory
366 before running La@TeX{} or @command{makeinfo}. This may seem a little
367 kludgy, but both La@TeX{} and @command{makeinfo} expect picture files
368 (the music) to be in the current working directory. Moreover, if you do
369 this, La@TeX{} will not clutter your normal working directory with output
372 @cindex titling and lilypond-book
373 @cindex lilypond-book and titling
374 @cindex @code{\header} in La@TeX{} documents
376 If you want to add titling from the @code{\header} section of the
377 files, you should add the following to the top of your La@TeX{} file:
381 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
384 @command{lilypond-book} accepts the following command line options:
387 @item @option{-f @var{format}}, @option{--format=@var{format}}
388 Specify the document type to process: @code{html}, @code{latex} or
389 @code{texi} (the default). @command{lilypond-book} usually figures this
392 Note that the @code{texi} document type produces a DVI file; to
393 convert a texinfo document to @code{html}, you should use the additional
394 format @code{texi-html} instead of @code{texi} to convert lilypond
395 fragments to PNG images.
397 @item @option{--default-music-fontsize=@var{sz}pt}
398 Set the fontsize to use for LilyPond if no fontsize is given
401 @item @option{--force-music-fontsize=@var{sz}pt}
402 Force all LilyPond code to use this fontsize, overriding options
403 given to @code{\begin@{lilypond@}}.
405 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
406 Add @var{DIR} to the include path.
408 @item @option{-M}, @option{--dependencies}
409 Write dependencies to @file{filename.dep}.
411 @item @option{--dep-prefix=@var{pref}}
412 Prepend @var{pref} before each @option{-M} dependency.
414 @item @option{-n}, @option{--no-lily}
415 Do not run LilyPond, but do generate the @code{.ly} files.
417 @item @option{--no-music}
418 Strip all LilyPond blocks from the file.
420 @item @option{--no-pictures}
421 Do not generate pictures when processing Texinfo.
423 @item @option{--read-lys}
424 Do not write ly files. This way you can do
427 lilypond-book file.tely
429 lilypond-book --read-lys
432 @item @option{--outname=@var{file}}
433 The name of La@TeX{} file to output. If this option is not given,
434 the output name is derived from the input name.
436 @item @option{--outdir=@var{dir}}
437 Place generated files in @var{dir}.
439 @item @option{--version}
440 Print version information.
442 @item @option{--help}
443 Print a short help message.
449 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
451 The Texinfo command @code{pagesize} is on the TODO list for LilyPond
452 1.8, but changing the linewidth in other ways will not give you a
453 straight right margin.
455 Almost all La@TeX{} commands that change margins and line widths are
458 There is no way to automatically apply @command{convert-ly} only to fragments
459 inside a lilypond-book file.
461 @command{lilypond-book} processes all music fragments in one big run. The
462 state of the GUILE interpreter is not reset between fragments; this
463 means that global GUILE definitions, e.g., done with @code{#(define @dots{})}
464 and @code{#(set! @dots{})} can leak from one fragment into the next fragment.