1 @c -*- coding: latin-1; mode: texinfo; -*-
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 Integrating text and music
17 @chapter Integrating text and music
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
37 * An example of a musicological document::
38 * Integrating Texinfo and music::
39 * Integrating LaTeX and music::
40 * Integrating HTML and music::
41 * Music fragment options::
42 * Invoking lilypond-book::
43 * Filename extensions::
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 La@TeX{}. 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 @c @TeX{} in node name seems to barf
160 @node Integrating LaTeX and music
161 @section Integrating LaTeX and music
163 La@TeX{} is the de facto standard for publishing layouts in the exact
164 sciences. It is built on top of the @TeX{} typesetting engine, so it
165 provides the best typography available anywhere.
167 For more information about La@TeX{}
168 @uref{http://www.ctan.org/tex-archive/info/lshort/english/,The not so
169 Short Introduction to La@TeX{}} provides a introduction to using
172 For La@TeX{}, music is entered using
175 \begin[options,go,here]@{lilypond@}
181 \lilypondfile[options,go,here]@{@var{filename}@}
188 \lilypond@{ YOUR LILYPOND CODE @}
191 Running lilypond-book yields a file that can be processed with
195 We show some examples here:
198 \begin[staffsize=26]@{lilypond@}
206 @lilypond[fragment,staffsize=26]
210 Then the short version:
213 \lilypond[staffsize=11]@{<c' e' g'>@}
219 @lilypond[fragment,staffsize=11]{<c' e' g'>}
221 The linewidth of the music will be adjust by examining the commands in
222 the document preamble, the part of the document before
223 @code{\begin@{document@}}. The @command{lilypond-book} command sends
224 these to La@TeX{} to find out how wide the text is. The line width
225 for the music fragments is then adjusted to the text width.
227 After @code{\begin@{document@}}, the column changing commands
228 @code{\onecolumn}, @code{\twocolumn} commands
231 @code{multicols} environment from the multicol package
233 are also interpreted.
235 @cindex titling and lilypond-book
236 @cindex @code{\header} in La@TeX{} documents
239 The music will be surrounded by @code{\preLilyPondExample} and
240 @code{\postLilyPondExample}, which are defined to be empty by default.
242 @cindex outline fonts
245 @cindex invoking dvips
247 For printing the La@TeX{} document, you will need to use dvips. For
248 producing PostScript with scalable fonts, add the following options to
249 the dvips command line:
251 -Ppdf -u+lilypond.map -u+ec-mftrace.map
255 PDF can then be produced with @code{ps2pdf}.
257 @cindex international characters
260 LilyPond does not use the La@TeX{} font handling scheme for lyrics and text
261 markups, so if you use characters in your lilypond-book
262 documents that are not included in the standard US-ASCII character set,
263 include @code{\usepackage[latin1]@{inputenc@}} in the file
264 header but do not include @code{\usepackage[T1]@{fontenc@}}. Character
265 sets other than latin1 are not supported directly but may be handled by
266 explicitly specifying the @code{font-name} property in LilyPond and
267 using the corresponding La@TeX{} packages. Please consult the mailing list
273 @node Integrating Texinfo and music
274 @section Integrating Texinfo and music
276 Texinfo is the standard format for documentation at the GNU
277 project. An example of a texinfo document is this manual. The HTML,
278 PDF and Info versions of the manual are made from the document.
280 When run on a lilypond-book, produces a @file{.texi} file containing
281 @code{@@image} tags for HTML and info. For the printed edition, the
282 raw @TeX{} output of LilyPond is included into the main document.
284 In the input file, music is specified like
287 @@lilypond[options,go,here]
290 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
291 @@lilypondfile[options,go,here]@{@var{filename}@}
294 When lilypond-book is run on it, this results in a texinfo file. We
295 show two simple examples here. First a complete block:
298 @@lilypond[staffsize=26]
310 Then the short version:
313 @@lilypond[staffsize=11]@{<c' e' g'>@}
319 @lilypond[fragment,staffsize=11]{ <c' e' g'> }
321 When producing texinfo, lilypond-book also generates bitmaps of the
322 music, so you can make a HTML document with embedded music.
328 @node Integrating HTML and music
329 @section Integrating HTML and music
331 Music is entered using
334 <lilypond relative=2 verbatim>
335 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
340 of which lilypond-book will produce a HTML with appropriate image tags for the
343 @c why the second example? -gp
345 <lilypond relative=2 verbatim>
346 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
350 @lilypond[fragment,relative=2]
351 \key c \minor r8 c16 b c8 g as c16 b c8 d | g,4
354 For inline pictures, use @code{<lilypond ... />} syntax, e.g.
356 Some music in <lilypond a b c/> a line of text.
359 @c FIXME: check if this feature is coming soon; if not, @ignore this stuff.
360 A special feature not (yet) available in other output formats, is the
361 @code{<lilypondfile>} tag, for example,
363 <lilypondfile>trip.ly</lilypondfile>
365 This runs @file{trip.ly} through @code{lilypond} (see also
366 @ref{Invoking lilypond}), and substitutes a preview image in the
367 output. The image links to a separate HTML file, so clicking it will
368 take the viewer to a menu, with links to images, midi and printouts.
370 @cindex titling in THML
371 @cindex preview image
374 @node Music fragment options
375 @section Music fragment options
377 The commands for lilypond-book have room to specify one or more of the
382 @var{contents} is copied into the source, enclosed in a verbatim block;
383 followed by any text given with the @code{intertext} option; then
384 the actual music is displayed. This option does not work with
385 the short version of the music blocks:
387 @code{ @@lilypond@{ CONTENTS @} } and @code{ \lilypond@{ CONTENTS @} }
389 @item filename=@var{filename}
390 This names the file for the @code{printfilename} option. The argument
393 @item staffsize=@var{ht}
394 Sets the staff height to @var{ht}, which is measured in points.
397 produces naturally spaced lines (i.e., @code{raggedright = ##t}); this
398 works well for small music fragments.
400 @item linewidth=@var{size}\@var{unit}
401 sets linewidth to @var{size}, where @var{unit} = cm, mm, in, or pt.
402 This option affects LilyPond output, not the text layout.
405 prevents printing time signature.
408 adds some boilerplate code, so you can enter like
415 without @code{\layout}, @code{\score} or other red tape.
417 @item indent=@var{size}\@var{unit}
418 sets indentation of the first music system to @var{size},
419 where @var{unit} = cm, mm, in, or pt. This option affects LilyPond,
420 not the text layout. For single-line fragments, the default is to
425 \begin[indent=5\cm,raggedright]@{lilypond@}
432 sets indentation of the first music system to zero. This option
433 affects LilyPond, not the text layout.
436 sets linewidth to the width of a quotation and puts the output
437 in a quotation block.
440 Includes the @code{texidoc} field, if defined in the file. This is
441 only for Texinfo output.
443 In Texinfo, the music fragment is normally preceded by the
444 @code{texidoc} field from the @code{\header}. The LilyPond test
445 documents are composed from small @file{.ly} files in this way:
449 texidoc = "this file demonstrates a single note"
454 @item relative, relative=@var{N}
455 uses relative octave mode. By default, notes are specified relative
456 to middle C. The optional integer argument specifies the octave of the
457 starting note, where the default @code{1} is middle C.
461 @node Invoking lilypond-book
462 @section Invoking lilypond-book
465 Running @command{lilypond-book} generates lots of small files that
466 LilyPond will process. To avoid all that garbage in the source
467 directory use the @option{--output} command line option, and change to
468 that directory before running La@TeX{} or @file{makeinfo}:
471 lilypond-book --output=out yourfile.lytex
475 This will produce a .tex or .texi file. To produce a pdf from the
476 .tex file, you should do
480 dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
484 To produce a texinfo document (in any output format), follow the normal
485 procedures for texinfo.
487 @command{lilypond-book} accepts the following command line options:
490 @item @option{-f @var{format}}, @option{--format=@var{format}}
491 Specify the document type to process: @code{html}, @code{latex} or
492 @code{texi} (the default). @command{lilypond-book} figures this
495 The @code{texi} document type produces a texinfo file with music
496 fragments in the DVI output only. For getting images in the HTML
498 @code{texi-html} must be used.
500 @item @option{-F @var{filter}}, @option{--filter=@var{filter}}
501 Pipe snippets through @var{filter}.
505 lilypond-book --filter='convert-ly --from=2.0.0' my-book.tely
508 @item @option{--help}
509 Print a short help message.
511 @item @option{-I @var{dir}}, @option{--include=@var{dir}}
512 Add @var{DIR} to the include path.
514 @item @option{-o @var{dir}}, @option{--output=@var{dir}}
515 Place generated files in @var{dir}.
517 @item @option{-P @var{process}}, @option{--process=@var{COMMAND}}
518 Process lilypond snippets using @var{command}. The default command is
521 @item @option{--verbose}
524 @item @option{--version}
525 Print version information.
528 For La@TeX{} input, the file to give to La@TeX{} has extension
529 @file{.latex}. Texinfo input will be written to a file with extension
536 The Texinfo command @code{pagesize} is not interpreted. Almost all
537 La@TeX{} commands that change margins and line widths are ignored.
539 Only the first @code{\score} of a LilyPond block is processed.
542 The size of a music block is limited to 1.5 KB, due to technical
543 problems with the Python regular expression engine. For longer files,
544 use @code{\lilypondfile}.
547 @node Filename extensions
548 @section Filename extensions
550 You can use any filename extension, but if you do not use the
551 recommended extension, you may need to manually specify what output
552 format you want. See @ref{Invoking lilypond-book} for details.
554 @code{Lilypond-book} automatically selects the output format based
559 @item @emph{.html} produces html output
561 @item @emph{.itely} produces texinfo output
563 @item @emph{.lytex} produces latex output