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 introduction 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:
73 @@lilypond[staffsize=26]
85 Then the short version:
88 @@lilypond[staffsize=11]@{<c' e' g'>@}
94 @lilypond[staffsize=11]{ <c' e' g'> }
96 When producing texinfo, lilypond-book also generates bitmaps of the
97 music, so you can make a HTML document with embedded music.
99 @c @TeX{} in node name seems to barf
100 @node Integrating LaTeX and music
101 @section Integrating LaTeX and music
104 For La@TeX{}, music is entered using
107 \begin[options,go,here]@{lilypond@}
113 \lilypondfile[options,go,here]@{@var{filename}@}
120 \lilypond@{ YOUR LILYPOND CODE @}
123 Running lilypond-book yields a file that can be processed with
127 We show some examples here:
130 \begin[staffsize=26]@{lilypond@}
138 @lilypond[staffsize=26]
142 Then the short version:
145 \lilypond[staffsize=11]@{<c' e' g'>@}
151 @lilypond[staffsize=11]{<c' e' g'>}
153 The linewidth of the music will be adjust by examining the commands in
154 the document preamble, the part of the document before
155 @code{\begin@{document@}}: @command{lilypond-book} sends these to
156 La@TeX{} to find out how wide the text is. The line width variable for
157 the music fragments are adjusted to the text width.
159 After @code{\begin@{document@}}, the column changing commands
160 @code{\onecolumn}, @code{\twocolumn} commands
163 @code{multicols} environment from the multicol package
165 are also interpreted.
167 @cindex titling and lilypond-book
168 @cindex lilypond-book and titling
169 @cindex @code{\header} in La@TeX{} documents
171 The titling from the @code{\header} section of the fragments can be
172 imported by adding the following to the top of the La@TeX{} file:
176 \def\preLilyPondExample@{\def\mustmakelilypondtitle@{@}@}
179 The music will be surrounded by @code{\preLilyPondExample} and
180 @code{\postLilyPondExample}, which are defined to be empty by default.
182 @cindex outline fonts
185 @cindex invoking dvips
187 For printing the LaTeX document, you will need to use dvips. For
188 producing PostScript with scalable fonts, add the following options to
189 the dvips command line:
191 -Ppdf -u +lilypond.map
195 PDF can then be produced with @code{ps2pdf}.
197 @cindex international characters
200 LilyPond does not use the LaTeX font handling scheme for lyrics and text
201 markups, so if you use characters in your lilypond-book
202 documents that are not included in the standard US-ASCII character set,
203 include @code{\usepackage[latin1]@{inputenc@}} in the file
204 header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
205 sets other than latin1 are not supported directly but may be handled by
206 explicitly specifying the @code{font-name} property in LilyPond and
207 using the corresponding LaTeX packages. Please consult the mailing list
214 @node Integrating HTML and music
215 @section Integrating HTML and music
217 Music is entered using
220 <lilypond relative=1 verbatim>
221 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
226 of which lilypond-book will produce a HTML with appropriate image tags for the
230 <lilypond relative=1 verbatim>
231 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
235 @lilypond[relative=1]
236 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
239 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
241 Some music in <lilypond a b c/> a line of text.
244 A special feature not (yet) available in other output formats, is the
245 @code{<lilypondfile>} tag, for example,
247 <lilypondfile>trip.ly</lilypondfile>
249 This runs @file{trip.ly} through @code{lilypond} (see also
250 @ref{Invoking lilypond}), and substitutes a preview image in the
251 output. The image links to a separate HTML file, so clicking it will
252 take the viewer to a menu, with links to images, midi and printouts.
254 @cindex titling in THML
255 @cindex preview image
258 @node Music fragment options
259 @section Music fragment options
261 The commands for lilypond-book have room to specify one or more of the
266 @var{contents} is copied into the source, enclosed in a verbatim block;
267 followed by any text given with the @code{intertext} option; then
268 the actual music is displayed. This option does not work with
269 the short version of the music blocks:
271 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
273 @item filename=@var{filename}
274 name the file (for @code{printfilename} option). The argument should
277 @item staffsize=POINTS
278 @lilypond[staffsize=31.41592658]
280 r16 c[ d e] f[ d e c] g'8[ c] b[\prall c] |
281 d16[ g, a b] c[ a b g] d'8[ g f\prall g]
286 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
287 works well for small music fragments.
289 @item linewidth=@var{size}\\@var{unit}
290 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
291 This option affects LilyPond output, not the text layout.
294 prevents printing time signature.
298 overrides @command{lilypond-book} auto detection of what type of code is
299 in the LilyPond block, voice contents, or complete code.
301 @item indent=@var{size}\\@var{unit}
302 sets indentation of the first music system to @var{size},
303 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
304 not the text layout. For single-line fragments, the default is to
309 \begin[indent=\\5cm,raggedright]@{lilypond@}
316 sets indentation of the first music system to zero. This option
317 affects LilyPond, not the text layout.
320 Includes the @code{texidoc} field, if defined in the file. This is
321 only for Texinfo output.
323 In Texinfo, the music fragment is normally preceded by the
324 @code{texidoc} field from the @code{\header}. The LilyPond test
325 documents are composed from small @file{.ly} files in this way:
329 texidoc = "this file demonstrates a single note"
331 \score @{ \notes @{ c'4 @} @}
334 @item relative, relative=@var{N}
335 uses relative octave mode. By default, notes are specified relative
336 to middle C. The optional integer argument specifies the octave of the
337 starting note, where the default @code{1} is middle C.
341 @node Invoking lilypond-book
342 @section Invoking lilypond-book
345 Running @command{lilypond-book} generates lots of small files that
346 LilyPond will process. To avoid all that garbage in the source
347 directory, it is advisable to change to a temporary directory first:
349 cd out && lilypond-book ../yourfile.tex
353 or to use the @option{--output} command line option, and change to
354 that directory before running La@TeX{} or @file{makeinfo}:
357 lilypond-book --output=out yourfile.lytex
358 cd out && latex yourfile.tex
362 @command{lilypond-book} accepts the following command line options:
365 @item @option{-f @var{format}}, @option{--format=@var{format}}
366 Specify the document type to process: @code{html}, @code{latex} or
367 @code{texi} (the default). @command{lilypond-book} usually figures this
370 The @code{texi} document type produces a texinfo file with music
371 fragments in the DVI output only. For getting images in the HTML
373 @code{texi-html} must be used.
375 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
376 Pipe snippets through @var{filter}.
380 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
383 @item @option{--help}
384 Print a short help message.
386 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
387 Add @var{DIR} to the include path.
389 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
390 Place generated files in @var{dir}.
392 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
393 Process lilypond snippets using @var{command}. The default command is
396 @item @option{--verbose}
399 @item @option{--version}
400 Print version information.
403 For La@TeX{} input, the file to give to La@TeX{} has extension
404 @file{.latex}. Texinfo input will be written to a file with extension
411 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
413 The Texinfo command @code{pagesize} is not interpreted. Almost all
414 La@TeX{} commands that change margins and line widths are ignored.
416 Only the first @code{\score} of a LilyPond block is processed.
419 The size of a music block is limited to 1.5 KB, due to technical
420 problems with the Python regular expression engine. For longer files,
421 use @code{\lilypondfile}.
423 @command{lilypond-book} processes all music fragments in one big run.
424 The state of the GUILE interpreter is not reset between fragments;
425 this means that changes made to global GUILE definitions, e.g. done
426 with @code{set!} or @code{set-cdr!}, can leak from one fragment into