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. The pictures
20 are created separately, yielding PostScript pictures or PNG images,
21 and those are included into a La@TeX{} or HTML document.
23 @command{lilypond-book} provides a way to automate this process: this
24 program extracts snippets of music from your document, runs LilyPond
25 on them, and outputs the document with pictures substituted for the
26 music. The line width and font size definitions for the music are
27 adjusted to match the layout of your document.
29 This procedure may be applied to La@TeX{}, @code{html} or Texinfo
30 documents. A tutorial on using lilypond-book is in @ref{Integrating
31 text and music}. For more information about La@TeX{}
32 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
33 Short Introduction to LaTeX} provides a introction to using La@TeX{}.
39 * Integrating Texinfo and music::
40 * Integrating LaTeX 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 Music is specified like this:
62 @@lilypond[options, go, here]
65 @@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
66 @@lilypondfile[options, go, here]@{@var{filename}@}
69 When lilypond-book is run on it, this results in a texinfo file. We
70 show two simple examples here. First a complete block:
85 Then the short version:
88 @@lilypond[11pt]@{<c' e' g'>@}
94 @lilypond[11pt]{ <c' e' g'> }
96 @command{lilypond-book} knows the default margins and a few paper
97 sizes. One of these commands should be in the beginning of the document:
100 @item @code{@@afourpaper}
101 @item @code{@@afourlatex}
102 @item @code{@@afourwide}
103 @item @code{@@smallbook}
107 @code{@@pagesizes} are not yet supported.
109 When producing texinfo, lilypond-book also generates bitmaps of the
110 music, so you can make a HTML document with embedded music.
113 @c @TeX{} in node name seems to barf
114 @node Integrating LaTeX and music
115 @section Integrating LaTeX and music
118 For La@TeX{}, music is entered using
121 \begin[options, go, here]@{lilypond@}
127 \lilypondfile[options, go,here]@{@var{filename}@}
134 \lilypond@{ YOUR LILYPOND CODE @}
137 Running lilypond-book yields a file that can be processed with
141 We show some examples here:
144 \begin[26pt]@{lilypond@}
156 Then the short version:
159 \lilypond[11pt]@{<c' e' g'>@}
165 @lilypond[11pt]{<c' e' g'>}
167 The linewidth of the music will be adjust by examining the commands in
168 the document preamble, the part of the document before
169 @code{\begin@{document@}}: @command{lilypond-book} sends these to
170 La@TeX{} to find out how wide the text is. The line width variable for
171 the music fragments are adjusted to the text width.
173 After @code{\begin@{document@}}, the column changing commands
174 @code{\onecolumn} , @code{\twocolumn} commands and the
175 @code{multicols} environment from the multicol package are also
178 The titling from the @code{\header} section of the fragments can be
179 imported by adding the following to the top of the La@TeX{} file:
183 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
186 The music will be surrounded by @code{\preLilyPondExample} and
187 @code{\postLilyPondExample}, which are defined to be empty by default.
189 @cindex titling and lilypond-book
190 @cindex lilypond-book and titling
191 @cindex @code{\header} in La@TeX{} documents
193 To add titling from the @code{\header} section of the files, add the
194 following to the top of the La@TeX{} file:
197 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
200 @cindex outline fonts
203 @cindex invoking dvips
205 For printing the LaTeX document, you will need to use dvips. For
206 producing PostScript with scalable fonts, add the following options to
207 the dvips command line:
209 -Ppdf -u +lilypond.map
213 PDF can then be produced with @code{ps2pdf}.
216 @node Integrating HTML and music
217 @section Integrating HTML and music
219 Music is entered using
222 <lilypond relative1 verbatim>
223 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
228 of which lilypond-book will produce a HTML with appropriate image tags for the
232 <lilypond relative1 verbatim>
233 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
238 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
241 For inline pictures, use @code{<lilypond ... />} syntax, eg.
243 Some music in <lilypond a b c/> a line of text.
246 A special feature not (yet) available in other output formats, is the
247 @code{<lilypondfile>} tag, for example,
249 <lilypondfile>trip.ly</lilypondfile>
251 This runs @file{trip.ly} through @code{lilypond} (see also
252 @ref{Invoking lilypond}), and substitutes a preview image in the
253 output. The image links to a separate HTML file, so clicking it will
254 take the viewer to a menu, with links to images, midi and printouts.
256 @cindex titling in THML
257 @cindex preview image
260 @node Music fragment options
261 @section Music fragment options
263 The commands for lilypond-book have room to specify one or more of the
268 CONTENTS is copied into the source enclosed in a verbatim block,
269 followed by any text given with the @code{intertext} option, then
270 the actual music is displayed. This option does not work with
271 the short version of the music blocks:
273 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
276 works like @code{verbatim}, but in a smaller font.
278 @item intertext="@var{text}"
279 is used in conjunction with @code{verbatim} option: This puts
280 @var{text} between the code and the music (without indentation).
282 @item filename=@var{filename}
283 name the file (for @code{printfilename} option). The argument should
289 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
290 d16[ g, a b] c[ a b g] d'8[ g f\prall g]
297 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
298 d16[ g, a b] c[ a b g] d'8[ g f\prall g]
305 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
312 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
319 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
324 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
325 works well for small music fragments.
328 is the opposite of @code{singleline}: it justifies and breaks lines.
330 @item linewidth=@var{size}@var{unit}
331 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
332 This option affects LilyPond output, not the text layout.
335 prevents printing time signature.
339 overrides @command{lilypond-book} auto detection of what type of code is
340 in the LilyPond block, voice contents or complete code.
342 @item indent=@var{size}@var{unit}
343 sets indentation of the first music system to @var{size},
344 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
345 not the text layout. For single-line fragments the default is to
350 \begin[indent=5cm,raggedright]@{lilypond@}
357 sets indentation of the first music system to zero. This option
358 affects LilyPond, not the text layout.
361 prevents including @code{texidoc}. This is only for Texinfo output.
363 In Texinfo, the music fragment is normally preceded by the
364 @code{texidoc} field from the @code{\header}. The LilyPond test
365 documents are composed from small @file{.ly} files in this way:
369 texidoc = "this file demonstrates a single note"
371 \score @{ \notes @{ c'4 @} @}
375 instructs @command{lilypond-book} to put La@TeX{} and Texinfo output
376 into a quotation block.
379 prints the file name before the music example. Useful in conjunction
380 with @code{\lilypondfile}.
382 @item relative, relative @var{N}
383 uses relative octave mode. By default, notes are specified relative
384 central C. The optional integer argument specifies the octave of the
385 starting note, where the default @code{1} is central C.
389 @node Invoking lilypond-book
390 @section Invoking lilypond-book
393 Running @command{lilypond-book} generates lots of small files that
394 LilyPond will process. To avoid all that garbage in the source
395 directory, it is advisable to change to a temporary directory first:
397 cd out && lilypond-book ../yourfile.tex
401 or to use the @option{--outdir} command line option, and change to
402 that director before running La@TeX{} or @file{makeinfo}:
405 lilypond-book --outdir=out yourfile.tex
406 cd out && latex yourfile.latex
410 @command{lilypond-book} accepts the following command line options:
413 @item @option{-f @var{format}}, @option{--format=@var{format}}
414 Specify the document type to process: @code{html}, @code{latex} or
415 @code{texi} (the default). @command{lilypond-book} usually figures this
418 The @code{texi} document type produces a texinfo file with music
419 fragments in the DVI output only. For getting images in the HTML
421 @code{texi-html} must be used.
423 @item @option{--default-music-fontsize=@var{sz}pt}
424 Set the music font size to use if no fontsize is given as option.
426 @item @option{--force-music-fontsize=@var{sz}pt}
427 Force all music to use this fontsize, overriding options given to
428 @code{\begin@{lilypond@}}.
430 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
431 Add @var{DIR} to the include path.
433 @item @option{-M}, @option{--dependencies}
434 Write dependencies to @file{filename.dep}.
436 @item @option{--dep-prefix=@var{pref}}
437 Prepend @var{pref} before each @option{-M} dependency.
439 @item @option{-n}, @option{--no-lily}
440 Generate the @code{.ly} files, but do not process them.
442 @item @option{--no-music}
443 Strip all music from the input file.
445 @item @option{--no-pictures}
446 Do not generate pictures when processing Texinfo.
448 @item @option{--outname=@var{file}}
449 The name of La@TeX{} file to output. If this option is not given,
450 the output name is derived from the input name.
452 @item @option{--outdir=@var{dir}}
453 Place generated files in @var{dir}.
455 @item @option{--version}
456 Print version information.
458 @item @option{--help}
459 Print a short help message.
463 For La@TeX{} input, the file to give to La@TeX{} has extension
464 @file{.latex}. Texinfo input will be written to a file with extension
471 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
473 The Texinfo command @code{pagesize} is not interpreted. Almost all
474 La@TeX{} commands that change margins and line widths are ignored.
476 Only the first @code{\score} of a LilyPond block is processed.
478 The size of a music block is limited to 1.5 kb, due to technical
479 problems with the Python regular expression engine. For longer files,
480 use @code{\lilypondfile}. Using @code{\lilypondfile} also makes
481 upgrading files (through convert-ly, see @ref{Invoking convert-ly})
484 @command{lilypond-book} processes all music fragments in one big run.
485 The state of the GUILE interpreter is not reset between fragments;
486 this means that changes made to global GUILE definitions, e.g. done
487 with @code{set!} or @code{set-cdr!}, can leak from one fragment into