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 lilypond-book manual
16 @chapter lilypond-book manual
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 This procedure may be applied to La@TeX{}, @code{html} or Texinfo
32 documents. A tutorial on using lilypond-book is in @ref{Integrating
33 text and music}. In 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::
53 @cindex documents, adding music to
56 @node Integrating Texinfo and music
57 @section Integrating Texinfo and music
59 You specify the LilyPond code like this:
62 @@lilypond[options, go, here]
65 @@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
66 @@lilypondfile[options, go, here]@{@var{filename}@}
69 Then you run lilypond-book on it, and the result is a file you can
70 process with texinfo. We show two simple examples here. First a
86 Then the short version:
89 @@lilypond[11pt]@{<<c' e' g'>>@}
95 @lilypond[11pt]{ <<c' e' g'>> }
97 @command{lilypond-book} knows the default margins and a few paper
98 sizes. One of these commands should be in the beginning of the document:
101 @item @code{@@afourpaper}
102 @item @code{@@afourlatex}
103 @item @code{@@afourwide}
104 @item @code{@@smallbook}
108 @code{@@pagesizes} are not yet supported.
110 When producing texinfo, lilypond-book also generates bitmaps of the
111 music, so you can make a HTML document with embedded music.
114 @node Integrating La@TeX{} and music
115 @section Integrating La@TeX{} and music
118 You specify LilyPond code like this:
121 \begin[options, go, here]@{lilypond@}
127 \lilypondfile[options, go,here]@{@var{filename}@}
134 \lilypond@{ YOUR LILYPOND CODE @}
137 Then you run lilypond-book on it, and the result is a file you can
138 process with La@TeX{}. We show some examples here.
141 \begin[26pt]@{lilypond@}
153 Then the short version:
156 \lilypond[11pt]@{<<c' e' g'>>@}
162 @lilypond[11pt]{<<c' e' g'>>}
164 You can use whatever commands you like in the document preamble,
165 the part of the document before @code{\begin@{document@}}.
166 @command{lilypond-book} will send it to La@TeX{} to find out how wide
167 the text is and adjust the linewidth variable in the paper definition of
168 your music according to that.
170 After @code{\begin@{document@}} you must be a little more careful
171 when you use commands that change the width of the text and how
172 many columns there are. @command{lilypond-book} knows about the
173 @code{\onecolumn} and @code{\twocolumn} commands and the @code{multicols}
174 environment from the multicol package.
177 If you want to add titling from the @code{\header} section of the
178 files, you should add the following to the top of your La@TeX{} file:
182 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
185 The music will be surrounded by @code{\preLilypondExample} and
186 @code{\postLilypondExample}, which are defined to be empty by default.
188 @node Integrating HTML and music
189 @section Integrating HTML and music
191 You specify LilyPond code like this:
194 <lilypond relative1 verbatim>
195 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
200 Then you run lilypond-book on it, and the result is a file you can
201 process with La@TeX{}. The final result look like
204 <lilypond relative1 verbatim>
205 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
210 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
213 For inline pictures, use @code{<lilypond ... />} syntax, eg.
215 Some music in <lilypond a b c/> a line of text.
218 A special feature not (yet) available in other output formats, is the
219 @code{<ly2dvifile>} tag, for example
221 <ly2dvifile>trip.ly</ly2dvifile>
223 This runs @file{trip.ly} through ly2dvi (See also @ref{Invoking
224 ly2dvi}), and substitutes a preview image in the output. The image
225 links to a separate HTML file, so clicking it will take the viewer to
226 a menu, with links to images, midi and printouts.
229 @cindex titling in THML
230 @cindex preview image
233 @node Music fragment options
234 @section Music fragment options
236 The commands for lilypond-book have room to specify one or more of the
241 This will create the music as eps graphics and include it into the
242 document with the @code{\includegraphics} command. It works in
246 This enables you to place music examples in the running text (and not in
247 a separate paragraph). To avoid that La@TeX{} places the music on a line
248 of its own, there should be no empty lines between the normal text and
249 the LilyPond environment. For inline music, you probably also need a
250 smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})
253 CONTENTS is copied into the source enclosed in a verbatim block,
254 followed by any text given with the @code{intertext} option, then
255 the actual music is displayed. This option does not work with
256 the short version of the LilyPond blocks:
258 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
261 Like @code{verbatim}, but in a smaller font.
263 @item intertext="@var{text}"
264 Used in conjunction with @code{verbatim} option: This puts
265 @var{text} between the code and the music (without indentation).
267 @item filename="@var{filename}"
268 Save the LilyPond code to @var{filename}. By default, a hash value
274 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
275 [d16 g, a b][c a b g][d'8 g f-\prall g]
282 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
283 [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] |
297 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
304 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
309 Produce naturally spaced lines (i.e., @code{raggedright = ##t}); this
310 works well for small music fragments.
313 The opposite of @code{singleline}: Justify and break lines.
315 @item linewidth=@var{size}@var{unit}
316 Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
317 This option affects LilyPond output, not the text layout.
320 Do not print time signature.
324 Override @command{lilypond-book} auto detection of what type of code is
325 in the LilyPond block, voice contents or complete code.
327 @item indent=@var{size}@var{unit}
328 Set indentation of the first music system to @var{size},
329 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
330 not the text layout. For single-line fragments the default is to
334 Set indentation of the first music system to zero. This option
335 affects LilyPond, not the text layout.
338 Do not include @code{texidoc}. This is only for Texinfo output.
340 In Texinfo, the music fragment is normally preceded by the
341 @code{texidoc} field from the @code{\header}. The LilyPond test
342 documents are composed from small @file{.ly} files in this way,
346 texidoc = "this file demonstrates a single note"
348 \score @{ \notes @{ c'4 @} @}
352 Instruct @command{lilypond-book} to put La@TeX{} and Texinfo output
353 into a quotation block.
356 Prints the file name before the music example. Useful in conjunction
357 with @code{\lilypondfile}.
359 @item relative, relative @var{N}
360 Use relative octave mode. By default, notes are specified relative
361 central C. The optional integer argument specifies the octave of the
362 starting note, where the default @code{1} is central C.
366 @node Invoking lilypond-book
367 @section Invoking lilypond-book
369 When you run @command{lilypond-book} it will generate lots of small
370 files that LilyPond will process. To avoid all the garbage in
371 your source directory, you should either change to a temporary
372 directory, or use the @option{--outdir} command line options:
374 @code{cd out && lilypond-book ../yourfile.tex}
376 @code{lilypond-book --outdir=out yourfile.tex}
378 For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
379 Texinfo input will be written to a file with extension @file{.texi}.
381 If you use @option{--outdir}, you should also @code{cd} to that directory
382 before running La@TeX{} or @command{makeinfo}. This may seem a little
383 kludgy, but both La@TeX{} and @command{makeinfo} expect picture files
384 (the music) to be in the current working directory. Moreover, if you do
385 this, La@TeX{} will not clutter your normal working directory with output
388 @cindex titling and lilypond-book
389 @cindex lilypond-book and titling
390 @cindex @code{\header} in La@TeX{} documents
392 If you want to add titling from the @code{\header} section of the
393 files, you should add the following to the top of your La@TeX{} file:
397 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
400 @command{lilypond-book} accepts the following command line options:
403 @item @option{-f @var{format}}, @option{--format=@var{format}}
404 Specify the document type to process: @code{html}, @code{latex} or
405 @code{texi} (the default). @command{lilypond-book} usually figures this
408 The @code{texi} document type produces a DVI file; to convert a
409 Texinfo document to @code{html}, you should use the additional format
410 @code{texi-html} instead of @code{texi} to convert lilypond fragments
413 @item @option{--default-music-fontsize=@var{sz}pt}
414 Set the fontsize to use for LilyPond if no fontsize is given
417 @item @option{--force-music-fontsize=@var{sz}pt}
418 Force all LilyPond code to use this fontsize, overriding options
419 given to @code{\begin@{lilypond@}}.
421 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
422 Add @var{DIR} to the include path.
424 @item @option{-M}, @option{--dependencies}
425 Write dependencies to @file{filename.dep}.
427 @item @option{--dep-prefix=@var{pref}}
428 Prepend @var{pref} before each @option{-M} dependency.
430 @item @option{-n}, @option{--no-lily}
431 Do not run LilyPond, but do generate the @code{.ly} files.
433 @item @option{--no-music}
434 Strip all LilyPond blocks from the file.
436 @item @option{--no-pictures}
437 Do not generate pictures when processing Texinfo.
439 @item @option{--outname=@var{file}}
440 The name of La@TeX{} file to output. If this option is not given,
441 the output name is derived from the input name.
443 @item @option{--outdir=@var{dir}}
444 Place generated files in @var{dir}.
446 @item @option{--version}
447 Print version information.
449 @item @option{--help}
450 Print a short help message.
456 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
458 The Texinfo command @code{pagesize} is not interpreted. Almost all
459 La@TeX{} commands that change margins and line widths are ignored.
461 The size of a lilypond block is limited to 1.5 kb, due to technical
462 problems with Python's regular expressions. For longer files, use
463 @code{\lilypondfile}. Using @code{\lilypondfile} also makes upgrading
464 files (through convert-ly, see @ref{Invoking convert-ly}) easier.
467 @command{lilypond-book} processes all music fragments in one big run.
468 The state of the GUILE interpreter is not reset between fragments;
469 this means that changes made to global GUILE definitions, e.g., done
470 with @code{set!} or @code{set-cdr!}, can leak from one fragment into