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{}.
37 * Integrating Texinfo and music::
38 * Integrating LaTeX and music::
39 * Integrating HTML and music::
40 * Music fragment options::
41 * Invoking lilypond-book::
51 @cindex documents, adding music to
54 @node Integrating Texinfo and music
55 @section Integrating Texinfo and music
57 Music is specified like this:
60 @@lilypond[options, go, here]
63 @@lilypond[options, go, here]@{ YOUR LILYPOND CODE @}
64 @@lilypondfile[options, go, here]@{@var{filename}@}
67 When lilypond-book is run on it, this results in a texinfo file. We
68 show two simple examples here. First a complete block:
83 Then the short version:
86 @@lilypond[11pt]@{<<c' e' g'>>@}
92 @lilypond[11pt]{ <<c' e' g'>> }
94 @command{lilypond-book} knows the default margins and a few paper
95 sizes. One of these commands should be in the beginning of the document:
98 @item @code{@@afourpaper}
99 @item @code{@@afourlatex}
100 @item @code{@@afourwide}
101 @item @code{@@smallbook}
105 @code{@@pagesizes} are not yet supported.
107 When producing texinfo, lilypond-book also generates bitmaps of the
108 music, so you can make a HTML document with embedded music.
111 @c @TeX{} in node name seems to barf
112 @node Integrating LaTeX and music
113 @section Integrating LaTeX and music
116 For La@TeX{}, music is entered using
119 \begin[options, go, here]@{lilypond@}
125 \lilypondfile[options, go,here]@{@var{filename}@}
132 \lilypond@{ YOUR LILYPOND CODE @}
135 Running lilypond-book yields a file that can be processed with
136 La@TeX{}. We show some examples here:
139 \begin[26pt]@{lilypond@}
151 Then the short version:
154 \lilypond[11pt]@{<<c' e' g'>>@}
160 @lilypond[11pt]{<<c' e' g'>>}
162 The linewidth of the music will be adjust by examining the commands in
163 the document preamble, the part of the document before
164 @code{\begin@{document@}}: @command{lilypond-book} sends these to
165 La@TeX{} to find out how wide the text is. The line width variable for
166 the music fragments are adjusted to the text width.
168 After @code{\begin@{document@}}, the column changing commands
169 @code{\onecolumn} , @code{\twocolumn} commands and the
170 @code{multicols} environment from the multicol package are also
173 The titling from the @code{\header} section of the fragments can be
174 imported by adding the following to the top of the La@TeX{} file:
178 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
181 The music will be surrounded by @code{\preLilyPondExample} and
182 @code{\postLilyPondExample}, which are defined to be empty by default.
184 @node Integrating HTML and music
185 @section Integrating HTML and music
187 Music is entered using
190 <lilypond relative1 verbatim>
191 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
196 of which lilypond-book will produce a HTML with appropriate image tags for the
200 <lilypond relative1 verbatim>
201 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
206 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
209 For inline pictures, use @code{<lilypond ... />} syntax, eg.
211 Some music in <lilypond a b c/> a line of text.
214 A special feature not (yet) available in other output formats, is the
215 @code{<ly2dvifile>} tag, for example,
217 <ly2dvifile>trip.ly</ly2dvifile>
219 This runs @file{trip.ly} through ly2dvi (see also @ref{Invoking
220 ly2dvi}), and substitutes a preview image in the output. The image
221 links to a separate HTML file, so clicking it will take the viewer to
222 a menu, with links to images, midi and printouts.
225 @cindex titling in THML
226 @cindex preview image
229 @node Music fragment options
230 @section Music fragment options
232 The commands for lilypond-book have room to specify one or more of the
237 CONTENTS is copied into the source enclosed in a verbatim block,
238 followed by any text given with the @code{intertext} option, then
239 the actual music is displayed. This option does not work with
240 the short version of the music blocks:
242 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
245 works like @code{verbatim}, but in a smaller font.
247 @item intertext="@var{text}"
248 is used in conjunction with @code{verbatim} option: This puts
249 @var{text} between the code and the music (without indentation).
251 @item filename="@var{filename}"
252 saves the LilyPond code to @var{filename}. By default, a hash value
258 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
259 [d16 g, a b][c a b g][d'8 g f-\prall g]
266 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
267 [d16 g, a b][c a b g][d'8 g f-\prall g]
274 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
281 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
288 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
293 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
294 works well for small music fragments.
297 is the opposite of @code{singleline}: it justifies and breaks lines.
299 @item linewidth=@var{size}@var{unit}
300 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
301 This option affects LilyPond output, not the text layout.
304 prevents printing time signature.
308 overrides @command{lilypond-book} auto detection of what type of code is
309 in the LilyPond block, voice contents or complete code.
311 @item indent=@var{size}@var{unit}
312 sets indentation of the first music system to @var{size},
313 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
314 not the text layout. For single-line fragments the default is to
318 sets indentation of the first music system to zero. This option
319 affects LilyPond, not the text layout.
322 prevents including @code{texidoc}. This is only for Texinfo output.
324 In Texinfo, the music fragment is normally preceded by the
325 @code{texidoc} field from the @code{\header}. The LilyPond test
326 documents are composed from small @file{.ly} files in this way:
330 texidoc = "this file demonstrates a single note"
332 \score @{ \notes @{ c'4 @} @}
336 instructs @command{lilypond-book} to put La@TeX{} and Texinfo output
337 into a quotation block.
340 prints the file name before the music example. Useful in conjunction
341 with @code{\lilypondfile}.
343 @item relative, relative @var{N}
344 uses relative octave mode. By default, notes are specified relative
345 central C. The optional integer argument specifies the octave of the
346 starting note, where the default @code{1} is central C.
350 @node Invoking lilypond-book
351 @section Invoking lilypond-book
353 Running @command{lilypond-book} generates lots of small files that
354 LilyPond will process. To avoid all that garbage in the source
355 directory, it is advisable to change to a temporary directory first:
357 cd out && lilypond-book ../yourfile.tex
361 or to use the @option{--outdir} command line option, and change to
362 that director before running La@TeX{} or @file{makeinfo}:
365 lilypond-book --outdir=out yourfile.tex
366 cd out && latex yourfile.latex
369 For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
370 Texinfo input will be written to a file with extension @file{.texi}.
372 @cindex titling and lilypond-book
373 @cindex lilypond-book and titling
374 @cindex @code{\header} in La@TeX{} documents
376 To add titling from the @code{\header} section of the files, add the
377 following to the top of the La@TeX{} file:
380 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
383 @command{lilypond-book} accepts the following command line options:
386 @item @option{-f @var{format}}, @option{--format=@var{format}}
387 Specify the document type to process: @code{html}, @code{latex} or
388 @code{texi} (the default). @command{lilypond-book} usually figures this
391 The @code{texi} document type produces a texinfo file with music
392 fragments in the DVI output only. For getting images in the HTML
394 @code{texi-html} must be used.
396 @item @option{--default-music-fontsize=@var{sz}pt}
397 Set the music font size to use if no fontsize is given as option.
399 @item @option{--force-music-fontsize=@var{sz}pt}
400 Force all music to use this fontsize, overriding options given to
401 @code{\begin@{lilypond@}}.
403 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
404 Add @var{DIR} to the include path.
406 @item @option{-M}, @option{--dependencies}
407 Write dependencies to @file{filename.dep}.
409 @item @option{--dep-prefix=@var{pref}}
410 Prepend @var{pref} before each @option{-M} dependency.
412 @item @option{-n}, @option{--no-lily}
413 Generate the @code{.ly} files, but do not process them.
415 @item @option{--no-music}
416 Strip all music from the input file.
418 @item @option{--no-pictures}
419 Do not generate pictures when processing Texinfo.
421 @item @option{--outname=@var{file}}
422 The name of La@TeX{} file to output. If this option is not given,
423 the output name is derived from the input name.
425 @item @option{--outdir=@var{dir}}
426 Place generated files in @var{dir}.
428 @item @option{--version}
429 Print version information.
431 @item @option{--help}
432 Print a short help message.
438 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
440 The Texinfo command @code{pagesize} is not interpreted. Almost all
441 La@TeX{} commands that change margins and line widths are ignored.
443 The size of a music block is limited to 1.5 kb, due to technical
444 problems with the Python regular expression engine. For longer files,
445 use @code{\lilypondfile}. Using @code{\lilypondfile} also makes
446 upgrading files (through convert-ly, see @ref{Invoking convert-ly})
449 @command{lilypond-book} processes all music fragments in one big run.
450 The state of the GUILE interpreter is not reset between fragments;
451 this means that changes made to global GUILE definitions, e.g. done
452 with @code{set!} or @code{set-cdr!}, can leak from one fragment into