8 ** AARGH.e We also have tutorial.itely: Integrating text and music.
10 Could also do with a cleanup. Lost inspiration to fix this manual
11 where to describe what?
16 @node lilypond-book manual
17 @chapter lilypond-book manual
19 If you want to add pictures of music to a document, you can simply do
20 it the way you would do with other types of pictures. The pictures
21 are created separately, yielding PostScript pictures or PNG images,
22 and those are included into a La@TeX{} or HTML document.
24 @command{lilypond-book} provides a way to automate this process: this
25 program extracts snippets of music from your document, runs LilyPond
26 on them, and outputs the document with pictures substituted for the
27 music. The line width and font size definitions for the music are
28 adjusted to match the layout of your document.
30 This procedure may be applied to La@TeX{}, @code{html} or Texinfo
31 documents. A tutorial on using lilypond-book is in @ref{Integrating
32 text and music}. For more information about La@TeX{}
33 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
34 Short Introduction to LaTeX} provides a introction to using La@TeX{}.
40 * Integrating Texinfo and music::
41 * Integrating LaTeX and music::
42 * Integrating HTML and music::
43 * Music fragment options::
44 * Invoking lilypond-book::
54 @cindex documents, adding music to
57 @node Integrating Texinfo and music
58 @section Integrating Texinfo and music
60 Music is specified like this:
63 @@lilypond[options,go,here]
66 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
67 @@lilypondfile[options,go,here]@{@var{filename}@}
70 When lilypond-book is run on it, this results in a texinfo file. We
71 show two simple examples here. First a complete block:
74 @@lilypond[staffsize=26]
86 Then the short version:
89 @@lilypond[staffsize=11]@{<c' e' g'>@}
95 @lilypond[staffsize=11]{ <c' e' g'> }
97 When producing texinfo, lilypond-book also generates bitmaps of the
98 music, so you can make a HTML document with embedded music.
100 @c @TeX{} in node name seems to barf
101 @node Integrating LaTeX and music
102 @section Integrating LaTeX and music
105 For La@TeX{}, music is entered using
108 \begin[options,go,here]@{lilypond@}
114 \lilypondfile[options,go,here]@{@var{filename}@}
121 \lilypond@{ YOUR LILYPOND CODE @}
124 Running lilypond-book yields a file that can be processed with
128 We show some examples here:
131 \begin[staffsize=26]@{lilypond@}
139 @lilypond[staffsize=26]
143 Then the short version:
146 \lilypond[staffsize=11]@{<c' e' g'>@}
152 @lilypond[staffsize=11]{<c' e' g'>}
154 The linewidth of the music will be adjust by examining the commands in
155 the document preamble, the part of the document before
156 @code{\begin@{document@}}: @command{lilypond-book} sends these to
157 La@TeX{} to find out how wide the text is. The line width variable for
158 the music fragments are adjusted to the text width.
160 After @code{\begin@{document@}}, the column changing commands
161 @code{\onecolumn}, @code{\twocolumn} commands
164 @code{multicols} environment from the multicol package
166 are also interpreted.
168 The titling from the @code{\header} section of the fragments can be
169 imported by adding the following to the top of the La@TeX{} file:
173 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
176 The music will be surrounded by @code{\preLilyPondExample} and
177 @code{\postLilyPondExample}, which are defined to be empty by default.
179 @cindex titling and lilypond-book
180 @cindex lilypond-book and titling
181 @cindex @code{\header} in La@TeX{} documents
183 To add titling from the @code{\header} section of the files, add the
184 following to the top of the La@TeX{} file:
187 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
190 @cindex outline fonts
193 @cindex invoking dvips
195 For printing the LaTeX document, you will need to use dvips. For
196 producing PostScript with scalable fonts, add the following options to
197 the dvips command line:
199 -Ppdf -u +lilypond.map
203 PDF can then be produced with @code{ps2pdf}.
206 @node Integrating HTML and music
207 @section Integrating HTML and music
209 Music is entered using
212 <lilypond relative=1 verbatim>
213 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
218 of which lilypond-book will produce a HTML with appropriate image tags for the
222 <lilypond relative=1 verbatim>
223 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
227 @lilypond[relative=1]
228 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
231 For inline pictures, use @code{<lilypond ... />} syntax, eg.
233 Some music in <lilypond a b c/> a line of text.
236 A special feature not (yet) available in other output formats, is the
237 @code{<lilypondfile>} tag, for example,
239 <lilypondfile>trip.ly</lilypondfile>
241 This runs @file{trip.ly} through @code{lilypond} (see also
242 @ref{Invoking lilypond}), and substitutes a preview image in the
243 output. The image links to a separate HTML file, so clicking it will
244 take the viewer to a menu, with links to images, midi and printouts.
246 @cindex titling in THML
247 @cindex preview image
250 @node Music fragment options
251 @section Music fragment options
253 The commands for lilypond-book have room to specify one or more of the
258 CONTENTS is copied into the source enclosed in a verbatim block,
259 followed by any text given with the @code{intertext} option, then
260 the actual music is displayed. This option does not work with
261 the short version of the music blocks:
263 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
265 @item filename=@var{filename}
266 name the file (for @code{printfilename} option). The argument should
269 @item staffsize=POINTS
270 @lilypond[staffsize=31.41592658]
272 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
273 d16[ g, a b] c[ a b g] d'8[ g f\prall g]
278 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
279 works well for small music fragments.
281 @item linewidth=@var{size}\\@var{unit}
282 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
283 This option affects LilyPond output, not the text layout.
286 prevents printing time signature.
290 overrides @command{lilypond-book} auto detection of what type of code is
291 in the LilyPond block, voice contents or complete code.
293 @item indent=@var{size}\\@var{unit}
294 sets indentation of the first music system to @var{size},
295 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
296 not the text layout. For single-line fragments the default is to
301 \begin[indent=\\5cm,raggedright]@{lilypond@}
308 sets indentation of the first music system to zero. This option
309 affects LilyPond, not the text layout.
312 Includes the @code{texidoc} field, if defined in the file. This is
313 only for Texinfo output.
315 In Texinfo, the music fragment is normally preceded by the
316 @code{texidoc} field from the @code{\header}. The LilyPond test
317 documents are composed from small @file{.ly} files in this way:
321 texidoc = "this file demonstrates a single note"
323 \score @{ \notes @{ c'4 @} @}
326 @item relative, relative=@var{N}
327 uses relative octave mode. By default, notes are specified relative
328 central C. The optional integer argument specifies the octave of the
329 starting note, where the default @code{1} is central C.
333 @node Invoking lilypond-book
334 @section Invoking lilypond-book
337 Running @command{lilypond-book} generates lots of small files that
338 LilyPond will process. To avoid all that garbage in the source
339 directory, it is advisable to change to a temporary directory first:
341 cd out && lilypond-book ../yourfile.tex
345 or to use the @option{--output} command line option, and change to
346 that director before running La@TeX{} or @file{makeinfo}:
349 lilypond-book --output=out yourfile.lytex
350 cd out && latex yourfile.tex
354 @command{lilypond-book} accepts the following command line options:
357 @item @option{-f @var{format}}, @option{--format=@var{format}}
358 Specify the document type to process: @code{html}, @code{latex} or
359 @code{texi} (the default). @command{lilypond-book} usually figures this
362 The @code{texi} document type produces a texinfo file with music
363 fragments in the DVI output only. For getting images in the HTML
365 @code{texi-html} must be used.
367 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
368 Pipe snippets through @var{filter}.
372 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
375 @item @option{--help}
376 Print a short help message.
378 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
379 Add @var{DIR} to the include path.
381 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
382 Place generated files in @var{dir}.
384 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
385 Process lilypond snippets using @var{command}. The default command is
388 @item @option{--verbose}
391 @item @option{--version}
392 Print version information.
395 For La@TeX{} input, the file to give to La@TeX{} has extension
396 @file{.latex}. Texinfo input will be written to a file with extension
403 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
405 The Texinfo command @code{pagesize} is not interpreted. Almost all
406 La@TeX{} commands that change margins and line widths are ignored.
408 Only the first @code{\score} of a LilyPond block is processed.
411 The size of a music block is limited to 1.5 kb, due to technical
412 problems with the Python regular expression engine. For longer files,
413 use @code{\lilypondfile}.
415 @command{lilypond-book} processes all music fragments in one big run.
416 The state of the GUILE interpreter is not reset between fragments;
417 this means that changes made to global GUILE definitions, e.g. done
418 with @code{set!} or @code{set-cdr!}, can leak from one fragment into