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 Integrating text and music
16 @chapter Integrating text and music
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::
49 @node An example of a musicological document
50 @section An example of a musicological document
53 @cindex La@TeX{}, music in
54 @cindex HTML, music in
55 @cindex Texinfo, music in
56 Some texts contain music examples. These texts are musicological
57 treatises, songbooks or manuals like this. Such texts can be made by
58 hand, simply by importing a PostScript figure into the word processor.
59 However, there is an automated procedure to reduce the amount of work
60 involved HTML, La@TeX{}, and Texinfo documents.
62 A script called @code{lilypond-book} will extract the music fragments,
63 format them, and put back the resulting notation. Here we show a
64 small example for use with @LaTeX{}. The example also contains explanatory text, so we will
65 not comment on it further
68 \documentclass[a4paper]{article}
71 Documents for lilypond-book may freely mix music and text. For
76 c2 g'2 \times 2/3 { f8 e d } c'2 g4
80 Options are put in brackets.
82 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
86 Larger examples can be put in a separate file, and introduced with
89 \lilypondfile[quote,noindent]{screech-boink.ly}
94 Under Unix, you can view the results as follows
99 lilypond-book --output=out/ lilybook.tex
100 @emph{lilypond-book (GNU LilyPond) 2.3.11}
101 @emph{Reading `input/tutorial/lilybook.tex'}
102 @emph{..lots of stuff deleted..}
103 @emph{Compiling `out//lilybook.tex'
106 @emph{lots of stuff deleted}
110 To convert the file into a nice PDF document, run the following
114 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
118 Running lilypond-book and running latex creates a lot of temporary
119 files, which would clutter up the working directory. To remedy this,
120 use the @code{--output=@var{dir}} option. It will create the files in
121 a separate subdirectory @file{dir}.
123 Finally the result of the La@TeX{} example shown above.@footnote{ This
124 tutorial is processed with Texinfo, so the example is as well. This
125 gives slightly different results in layout.} This finishes the
130 Documents for lilypond-book may freely mix music and text. For
135 c2 g'2 \times 2/3 { f8 e d } c'2 g4
139 Options are put in brackets.
141 @lilypond[fragment,quote,staffsize=26,verbatim]
145 Larger examples can be put in a separate file, and introduced with
146 @code{\lilypondfile}.
148 @lilypondfile[quote,noindent]{screech-boink.ly}
156 @cindex documents, adding music to
159 @node Integrating Texinfo and music
160 @section Integrating Texinfo and music
162 Music is specified like this:
165 @@lilypond[options,go,here]
168 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
169 @@lilypondfile[options,go,here]@{@var{filename}@}
172 When lilypond-book is run on it, this results in a texinfo file. We
173 show two simple examples here. First a complete block:
176 @@lilypond[staffsize=26]
188 Then the short version:
191 @@lilypond[staffsize=11]@{<c' e' g'>@}
197 @lilypond[fragment,staffsize=11]{ <c' e' g'> }
199 When producing texinfo, lilypond-book also generates bitmaps of the
200 music, so you can make a HTML document with embedded music.
202 @c @TeX{} in node name seems to barf
203 @node Integrating LaTeX and music
204 @section Integrating LaTeX and music
207 For La@TeX{}, music is entered using
210 \begin[options,go,here]@{lilypond@}
216 \lilypondfile[options,go,here]@{@var{filename}@}
223 \lilypond@{ YOUR LILYPOND CODE @}
226 Running lilypond-book yields a file that can be processed with
230 We show some examples here:
233 \begin[staffsize=26]@{lilypond@}
241 @lilypond[fragment,staffsize=26]
245 Then the short version:
248 \lilypond[staffsize=11]@{<c' e' g'>@}
254 @lilypond[fragment,staffsize=11]{<c' e' g'>}
256 The linewidth of the music will be adjust by examining the commands in
257 the document preamble, the part of the document before
258 @code{\begin@{document@}}: @command{lilypond-book} sends these to
259 La@TeX{} to find out how wide the text is. The line width variable for
260 the music fragments are adjusted to the text width.
262 After @code{\begin@{document@}}, the column changing commands
263 @code{\onecolumn}, @code{\twocolumn} commands
266 @code{multicols} environment from the multicol package
268 are also interpreted.
270 @cindex titling and lilypond-book
271 @cindex @code{\header} in La@TeX{} documents
274 The music will be surrounded by @code{\preLilyPondExample} and
275 @code{\postLilyPondExample}, which are defined to be empty by default.
277 @cindex outline fonts
280 @cindex invoking dvips
282 For printing the LaTeX document, you will need to use dvips. For
283 producing PostScript with scalable fonts, add the following options to
284 the dvips command line:
286 -Ppdf -u+lilypond.map -u+ec-mftrace.map
290 PDF can then be produced with @code{ps2pdf}.
292 @cindex international characters
295 LilyPond does not use the LaTeX font handling scheme for lyrics and text
296 markups, so if you use characters in your lilypond-book
297 documents that are not included in the standard US-ASCII character set,
298 include @code{\usepackage[latin1]@{inputenc@}} in the file
299 header but do not include @code{\usepackage[[T1]@{fontenc@}}. Character
300 sets other than latin1 are not supported directly but may be handled by
301 explicitly specifying the @code{font-name} property in LilyPond and
302 using the corresponding LaTeX packages. Please consult the mailing list
309 @node Integrating HTML and music
310 @section Integrating HTML and music
312 Music is entered using
315 <lilypond relative=1 verbatim>
316 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
321 of which lilypond-book will produce a HTML with appropriate image tags for the
325 <lilypond relative=2 verbatim>
326 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
330 @lilypond[fragment,relative=2]
331 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
334 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
336 Some music in <lilypond a b c/> a line of text.
339 A special feature not (yet) available in other output formats, is the
340 @code{<lilypondfile>} tag, for example,
342 <lilypondfile>trip.ly</lilypondfile>
344 This runs @file{trip.ly} through @code{lilypond} (see also
345 @ref{Invoking lilypond}), and substitutes a preview image in the
346 output. The image links to a separate HTML file, so clicking it will
347 take the viewer to a menu, with links to images, midi and printouts.
349 @cindex titling in THML
350 @cindex preview image
353 @node Music fragment options
354 @section Music fragment options
356 The commands for lilypond-book have room to specify one or more of the
361 @var{contents} is copied into the source, enclosed in a verbatim block;
362 followed by any text given with the @code{intertext} option; then
363 the actual music is displayed. This option does not work with
364 the short version of the music blocks:
366 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
368 @item filename=@var{filename}
369 This names the file for the @code{printfilename} option. The argument
372 @item staffsize=@var{ht}
373 Sets the staff height to @var{ht}, which is measured in points.
376 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
377 works well for small music fragments.
379 @item linewidth=@var{size}\@var{unit}
380 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
381 This option affects LilyPond output, not the text layout.
384 prevents printing time signature.
388 overrides @command{lilypond-book} auto detection of what type of code is
389 in the LilyPond block, voice contents, or complete code.
391 @item indent=@var{size}\@var{unit}
392 sets indentation of the first music system to @var{size},
393 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
394 not the text layout. For single-line fragments, the default is to
399 \begin[indent=5\cm,raggedright]@{lilypond@}
406 sets indentation of the first music system to zero. This option
407 affects LilyPond, not the text layout.
410 sets linewidth to the width of a quotation and puts the output
411 in a quotation block.
414 Includes the @code{texidoc} field, if defined in the file. This is
415 only for Texinfo output.
417 In Texinfo, the music fragment is normally preceded by the
418 @code{texidoc} field from the @code{\header}. The LilyPond test
419 documents are composed from small @file{.ly} files in this way:
423 texidoc = "this file demonstrates a single note"
428 @item relative, relative=@var{N}
429 uses relative octave mode. By default, notes are specified relative
430 to middle C. The optional integer argument specifies the octave of the
431 @item relative, relative=@var{N}
432 uses relative octave mode. By default, notes are specified relative
433 to middle C. The optional integer argument specifies the octave of the
434 starting note, where the default @code{1} is middle C.
438 @node Invoking lilypond-book
439 @section Invoking lilypond-book
442 Running @command{lilypond-book} generates lots of small files that
443 LilyPond will process. To avoid all that garbage in the source
444 directory use the @option{--output} command line option, and change to
445 that directory before running La@TeX{} or @file{makeinfo}:
448 lilypond-book --output=out yourfile.lytex
449 cd out && latex yourfile.tex
453 @command{lilypond-book} accepts the following command line options:
456 @item @option{-f @var{format}}, @option{--format=@var{format}}
457 Specify the document type to process: @code{html}, @code{latex} or
458 @code{texi} (the default). @command{lilypond-book} figures this
461 The @code{texi} document type produces a texinfo file with music
462 fragments in the DVI output only. For getting images in the HTML
464 @code{texi-html} must be used.
466 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
467 Pipe snippets through @var{filter}.
471 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
474 @item @option{--help}
475 Print a short help message.
477 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
478 Add @var{DIR} to the include path.
480 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
481 Place generated files in @var{dir}.
483 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
484 Process lilypond snippets using @var{command}. The default command is
487 @item @option{--verbose}
490 @item @option{--version}
491 Print version information.
494 For La@TeX{} input, the file to give to La@TeX{} has extension
495 @file{.latex}. Texinfo input will be written to a file with extension
502 The La@TeX{} @code{\includeonly@{...@}} command is ignored.
504 The Texinfo command @code{pagesize} is not interpreted. Almost all
505 La@TeX{} commands that change margins and line widths are ignored.
507 Only the first @code{\score} of a LilyPond block is processed.
510 The size of a music block is limited to 1.5 KB, due to technical
511 problems with the Python regular expression engine. For longer files,
512 use @code{\lilypondfile}.