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 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 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 @c @TeX{} in node name seems to barf
115 @node Integrating LaTeX and music
116 @section Integrating LaTeX 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.
178 If you want to add titling from the @code{\header} section of the
179 files, you should add the following to the top of your 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 @node Integrating HTML and music
190 @section Integrating HTML and music
192 You specify LilyPond code like this:
195 <lilypond relative1 verbatim>
196 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
201 Then you run lilypond-book on it, and the result is a file you can
202 process with La@TeX{}. The final result look like
205 <lilypond relative1 verbatim>
206 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
211 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
214 For inline pictures, use @code{<lilypond ... />} syntax, eg.
216 Some music in <lilypond a b c/> a line of text.
219 A special feature not (yet) available in other output formats, is the
220 @code{<ly2dvifile>} tag, for example
222 <ly2dvifile>trip.ly</ly2dvifile>
224 This runs @file{trip.ly} through ly2dvi (See also @ref{Invoking
225 ly2dvi}), and substitutes a preview image in the output. The image
226 links to a separate HTML file, so clicking it will take the viewer to
227 a menu, with links to images, midi and printouts.
230 @cindex titling in THML
231 @cindex preview image
234 @node Music fragment options
235 @section Music fragment options
237 The commands for lilypond-book have room to specify one or more of the
242 This will create the music as eps graphics and include it into the
243 document with the @code{\includegraphics} command. It works in
247 This enables you to place music examples in the running text (and not in
248 a separate paragraph). To avoid that La@TeX{} places the music on a line
249 of its own, there should be no empty lines between the normal text and
250 the LilyPond environment. For inline music, you probably also need a
251 smaller music font size (e.g.@: 11@dmn{pt} or 13@dmn{pt})
254 CONTENTS is copied into the source enclosed in a verbatim block,
255 followed by any text given with the @code{intertext} option, then
256 the actual music is displayed. This option does not work with
257 the short version of the LilyPond blocks:
259 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
262 Like @code{verbatim}, but in a smaller font.
264 @item intertext="@var{text}"
265 Used in conjunction with @code{verbatim} option: This puts
266 @var{text} between the code and the music (without indentation).
268 @item filename="@var{filename}"
269 Save the LilyPond code to @var{filename}. By default, a hash value
275 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
276 [d16 g, a b][c a b g][d'8 g f-\prall g]
283 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
284 [d16 g, a b][c a b g][d'8 g f-\prall g]
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] |
305 r16 [c d e][f d e c] [g'8 c][b-\prall c] |
310 Produce naturally spaced lines (i.e., @code{raggedright = ##t}); this
311 works well for small music fragments.
314 The opposite of @code{singleline}: Justify and break lines.
316 @item linewidth=@var{size}@var{unit}
317 Set linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
318 This option affects LilyPond output, not the text layout.
321 Do not print time signature.
325 Override @command{lilypond-book} auto detection of what type of code is
326 in the LilyPond block, voice contents or complete code.
328 @item indent=@var{size}@var{unit}
329 Set indentation of the first music system to @var{size},
330 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
331 not the text layout. For single-line fragments the default is to
335 Set indentation of the first music system to zero. This option
336 affects LilyPond, not the text layout.
339 Do not include @code{texidoc}. This is only for Texinfo output.
341 In Texinfo, the music fragment is normally preceded by the
342 @code{texidoc} field from the @code{\header}. The LilyPond test
343 documents are composed from small @file{.ly} files in this way,
347 texidoc = "this file demonstrates a single note"
349 \score @{ \notes @{ c'4 @} @}
353 Instruct @command{lilypond-book} to put La@TeX{} and Texinfo output
354 into a quotation block.
357 Prints the file name before the music example. Useful in conjunction
358 with @code{\lilypondfile}.
360 @item relative, relative @var{N}
361 Use relative octave mode. By default, notes are specified relative
362 central C. The optional integer argument specifies the octave of the
363 starting note, where the default @code{1} is central C.
367 @node Invoking lilypond-book
368 @section Invoking lilypond-book
370 When you run @command{lilypond-book} it will generate lots of small
371 files that LilyPond will process. To avoid all the garbage in
372 your source directory, you should either change to a temporary
373 directory, or use the @option{--outdir} command line options:
375 @code{cd out && lilypond-book ../yourfile.tex}
377 @code{lilypond-book --outdir=out yourfile.tex}
379 For La@TeX{} input, the file to give to La@TeX{} has extension @file{.latex}.
380 Texinfo input will be written to a file with extension @file{.texi}.
382 If you use @option{--outdir}, you should also @code{cd} to that directory
383 before running La@TeX{} or @command{makeinfo}. This may seem a little
384 kludgy, but both La@TeX{} and @command{makeinfo} expect picture files
385 (the music) to be in the current working directory. Moreover, if you do
386 this, La@TeX{} will not clutter your normal working directory with output
389 @cindex titling and lilypond-book
390 @cindex lilypond-book and titling
391 @cindex @code{\header} in La@TeX{} documents
393 If you want to add titling from the @code{\header} section of the
394 files, you should add the following to the top of your La@TeX{} file:
398 \def\preLilypondExample@{\def\mustmakelilypondtitle@{@}@}
401 @command{lilypond-book} accepts the following command line options:
404 @item @option{-f @var{format}}, @option{--format=@var{format}}
405 Specify the document type to process: @code{html}, @code{latex} or
406 @code{texi} (the default). @command{lilypond-book} usually figures this
409 The @code{texi} document type produces a DVI file; to convert a
410 Texinfo document to @code{html}, you should use the additional format
411 @code{texi-html} instead of @code{texi} to convert lilypond fragments
414 @item @option{--default-music-fontsize=@var{sz}pt}
415 Set the fontsize to use for LilyPond if no fontsize is given
418 @item @option{--force-music-fontsize=@var{sz}pt}
419 Force all LilyPond code to use this fontsize, overriding options
420 given to @code{\begin@{lilypond@}}.
422 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
423 Add @var{DIR} to the include path.
425 @item @option{-M}, @option{--dependencies}
426 Write dependencies to @file{filename.dep}.
428 @item @option{--dep-prefix=@var{pref}}
429 Prepend @var{pref} before each @option{-M} dependency.
431 @item @option{-n}, @option{--no-lily}
432 Do not run LilyPond, but do generate the @code{.ly} files.
434 @item @option{--no-music}
435 Strip all LilyPond blocks from the file.
437 @item @option{--no-pictures}
438 Do not generate pictures when processing Texinfo.
440 @item @option{--outname=@var{file}}
441 The name of La@TeX{} file to output. If this option is not given,
442 the output name is derived from the input name.
444 @item @option{--outdir=@var{dir}}
445 Place generated files in @var{dir}.
447 @item @option{--version}
448 Print version information.
450 @item @option{--help}
451 Print a short help message.
457 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
459 The Texinfo command @code{pagesize} is not interpreted. Almost all
460 La@TeX{} commands that change margins and line widths are ignored.
462 The size of a lilypond block is limited to 1.5 kb, due to technical
463 problems with Python's regular expressions. For longer files, use
464 @code{\lilypondfile}. Using @code{\lilypondfile} also makes upgrading
465 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