1 @c -*- coding: latin-1; mode: texinfo; -*-
8 ** AARGH. 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 @c Note: keep this node named so that `info lilypond-book' brings you here.
18 @chapter @command{lilypond-book}: Integrating text and music
20 If you want to add pictures of music to a document, you can simply do it
21 the way you would do with other types of pictures. The pictures are
22 created separately, yielding PostScript output or PNG images, and those
23 are included into a La@TeX{} or HTML document.
25 @command{lilypond-book} provides a way to automate this process: This
26 program extracts snippets of music from your document, runs
27 @command{lilypond} on them, and outputs the document with pictures
28 substituted for the music. The line width and font size definitions for
29 the music are adjusted to match the layout of your document.
31 This procedure may be applied to La@TeX{}, HTML or Texinfo documents.
34 * An example of a musicological document::
35 * Integrating LaTeX and music::
36 * Integrating Texinfo and music::
37 * Integrating HTML and music::
38 * Music fragment options::
39 * Invoking lilypond-book::
40 * Filename extensions::
44 @node An example of a musicological document
45 @section An example of a musicological document
48 @cindex La@TeX{}, music in
49 @cindex HTML, music in
50 @cindex Texinfo, music in
51 Some texts contain music examples. These texts are musicological
52 treatises, songbooks, or manuals like this. Such texts can be made by
53 hand, simply by importing a PostScript figure into the word processor.
54 However, there is an automated procedure to reduce the amount of work
55 involved in HTML, La@TeX{}, and Texinfo documents.
57 A script called @code{lilypond-book} will extract the music fragments,
58 format them, and put back the resulting notation. Here we show a small
59 example for use with La@TeX{}. The example also contains explanatory
60 text, so we will not comment on it further.
64 \documentclass[a4paper]{article}
67 Documents for @command{lilypond-book} may freely mix music and text.
72 c2 g'2 \times 2/3 { f8 e d } c'2 g4
76 Options are put in brackets.
78 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
82 Larger examples can be put into a separate file, and introduced with
85 \lilypondfile[quote,noindent]{screech-boink.ly}
91 Under Unix, you can view the results as follows
96 lilypond-book --output=out lilybook.tex
97 @emph{lilypond-book (GNU LilyPond) 2.5.0}
98 @emph{Reading lilybook.tex...}
99 @emph{..lots of stuff deleted..}
100 @emph{Compiling out/lilybook.tex...}
103 @emph{lots of stuff deleted}
107 To convert the file into a PDF document, run the following commands
110 dvips -Ppdf -u+lilypond -u+ec-mftrace lilybook
114 Running @command{lilypond-book} and @command{latex} creates a lot of
115 temporary files, which would clutter up the working directory. To
116 remedy this, use the @code{--output=@var{dir}} option. It will create
117 the files in a separate subdirectory @file{dir}.
119 Finally the result of the La@TeX{} example shown above.@footnote{This
120 tutorial is processed with Texinfo, so the example gives slightly
121 different results in layout.} This finishes the tutorial section.
125 Documents for @command{lilypond-book} may freely mix music and text.
130 c2 g'2 \times 2/3 { f8 e d } c'2 g4
134 Options are put in brackets.
136 @lilypond[fragment,quote,staffsize=26,verbatim]
140 Larger examples can be put into a separate file, and introduced with
141 @code{\lilypondfile}.
143 @lilypondfile[quote,noindent]{screech-boink.ly}
152 @cindex documents, adding music to
155 @node Integrating LaTeX and music
156 @section Integrating La@TeX{} and music
158 La@TeX{} is the de-facto standard for publishing layouts in the exact
159 sciences. It is built on top of the @TeX{} typesetting engine,
160 providing the best typography available anywhere.
163 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
164 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
167 Music is entered using
170 \begin[options,go,here]@{lilypond@}
179 \lilypondfile[options,go,here]@{@var{filename}@}
186 \lilypond@{ YOUR LILYPOND CODE @}
189 Running @command{lilypond-book} yields a file that can be further
190 processed with La@TeX{}.
192 We show some examples here. The lilypond environment
195 \begin[quote,fragment,staffsize=26]@{lilypond@}
203 @lilypond[quote,fragment,staffsize=26]
210 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
216 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
219 Currently, you cannot include @code{@{} or @code{@}} within
220 @code{\lilypond@{@}}, so this command is only useful with the
221 @code{fragment} option.
223 The default linewidth of the music will be adjusted by examining the
224 commands in the document preamble, the part of the document before
225 @code{\begin@{document@}}. The @command{lilypond-book} command sends
226 these to La@TeX{} to find out how wide the text is. The line width for
227 the music fragments is then adjusted to the text width. Note that this
228 heuristic algorithm can fail easily; in such cases it is necessary to
229 use the @code{linewidth} music fragment option.
231 @cindex titling and lilypond-book
232 @cindex @code{\header} in La@TeX{} documents
234 Each snippet calls @code{\preLilyPondExample} before and
235 @code{\postLilyPondExample} after the music if those macros have been
238 @cindex Latex, feta symbols
241 To include feta symbols (such as flat, segno, etc) in a LaTeX
242 document, use @code{\input@{titledefs@}}
245 \documentclass[a4paper]@{article@}
256 The font symbol names are defined in the file feta20.tex; to find
257 the location of this file, use the command
263 @cindex outline fonts
266 @cindex invoking dvips
268 For printing the La@TeX{} document you need a DVI to PostScript
269 translator like @command{dvips}. To use @command{dvips} to produce
270 a PostScript file, add the following options to the @command{dvips}
274 -Ppdf -u+lilypond.map -u+ec-mftrace.map
278 PDF can then be produced with a PostScript to PDF translator like
279 @code{ps2pdf} (which is part of GhostScript).
281 @cindex international characters
285 @node Integrating Texinfo and music
286 @section Integrating Texinfo and music
288 Texinfo is the standard format for documentation of the GNU project. An
289 example of a Texinfo document is this manual. The HTML, PDF, and Info
290 versions of the manual are made from the Texinfo document.
292 In the input file, music is specified with
295 @@lilypond[options,go,here]
304 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
311 @@lilypondfile[options,go,here]@{@var{filename}@}
314 When @command{lilypond-book} is run on it, this results in a Texinfo
315 file (with extension @file{.texi}) containing @code{@@image} tags for
316 HTML and info output. For the printed edition, the raw @TeX{} output of
317 LilyPond is included in the main document.
319 We show two simple examples here. A @code{lilypond} environment
337 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
343 @lilypond[fragment,staffsize=11]{<c' e' g'>}
345 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
346 in-line image. It always gets a paragraph of its own.
348 When using the Texinfo output format, @command{lilypond-book} also
349 generates bitmaps of the music (in PNG format), so you can make an HTML
350 document with embedded music.
353 @node Integrating HTML and music
354 @section Integrating HTML and music
356 Music is entered using
359 <lilypond fragment relative=2>
360 \key c \minor c4 es g2
365 @command{lilypond-book} then produces an HTML file with appropriate image
366 tags for the music fragments:
368 @lilypond[fragment,relative=2]
369 \key c \minor c4 es g2
372 For inline pictures, use @code{<lilypond ... />}, where the options
373 are separated by a colon from the music, for example
376 Some music in <lilypond relative=2: a b c/> a line of text.
379 To include separate files, say
382 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
385 @cindex titling in HTML
386 @cindex preview image
390 @node Music fragment options
391 @section Music fragment options
393 In the following, a ``LilyPond command'' refers to any command described
394 in the previous sections which is handled by @command{lilypond-book} to
395 produce a music snippet. For simplicity, LilyPond commands are only
396 shown in La@TeX{} syntax.
398 Note that the option string is parsed from left to right; if an option
399 occurs multiple times, the last one is taken.
401 The following options are available for LilyPond commands:
404 @item staffsize=@var{ht}
405 Set staff size to @var{ht}, which is measured in points.
408 Produce ragged-right lines with natural spacing (i.e., @code{raggedright
409 = ##t} is added to the LilyPond snippet). This is the default for the
410 @code{\lilypond@{@}} command if no @code{linewidth} option is present.
411 It is also the default for the @code{lilypond} environment if the
412 @code{fragment} option is set, and no line width is explicitly
416 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
417 to the LilyPond snippet).
420 @itemx linewidth=@var{size}\@var{unit}
421 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
422 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
423 @code{pt}. This option affects LilyPond output (this is, the staff
424 length of the music snippet), not the text layout.
426 If used without an argument, set line width to a default value (as
427 computed with a heuristic algorithm).
429 If no @code{linewidth} option is given, @command{lilypond-book} tries to
430 guess a default for @code{lilypond} environments which don't use the
431 @code{raggedright} option.
434 Do not print the time signature.
437 Make @command{lilypond-book} add some boilerplate code so that you can
445 without @code{\layout}, @code{\score}, etc.
448 Don't add additional code to complete LilyPond code in music snippets.
449 Since this is the default, @code{nofragment} is redundant normally.
451 @item indent=@var{size}\@var{unit}
452 Set indentation of the first music system to @var{size}, using
453 @var{unit} as units. @var{unit} is one of the following strings:
454 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
455 LilyPond, not the text layout.
458 Set indentation of the first music system to zero. This option affects
459 LilyPond, not the text layout. Since no indentation is the default,
460 @code{noindent} is redundant normally.
463 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
464 the output into a quotation block. The value `0.4@dmn{in}' can be
465 controlled with the @code{exampleindent} option.
468 Set the amount by which the @code{quote} option indents a music snippet.
471 @itemx relative=@var{n}
472 Use relative octave mode. By default, notes are specified relative to
473 middle@tie{}C. The optional integer argument specifies the octave of
474 the starting note, where the default @code{1} is middle C.
477 LilyPond also uses @command{lilypond-book} to produce its own
478 documentation. To do that, some more obscure music fragment options are
483 The argument of a LilyPond command is copied to the output file and
484 enclosed in a verbatim block, followed by any text given with the
485 @code{intertext} option (not implemented yet); then the actual music is
486 displayed. This option does not work well with @code{\lilypond@{@}} if
487 it is part of a paragraph.
490 (Only for Texinfo output.) If @command{lilypond} is called with the
491 @option{--header=@/texidoc} option, and the file to be processed is
492 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
493 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
494 option makes @command{lilypond-book} include such files, adding its
495 contents as a documentation block right before the music snippet.
497 Assuming the file @file{foo@/.ly} contains
501 texidoc = "This file demonstrates a single note."
507 and we have this in our Texinfo document @file{test.texinfo}
510 @@lilypondfile[texidoc]@{foo.ly@}
514 the following command line gives the expected result
517 lilypond-book --process="lilypond --format=tex --tex \
518 --header=texidoc test.texinfo
521 Most LilyPond test documents (in the @file{input} directory of the
522 distribution) are small @file{.ly} files which look exactly like this.
525 If a LilyPond input file is included with @code{\lilypondfile}, print
526 the file name right before the music snippet. For HTML output, this is
530 This option includes fonts in all of the generated EPS-files for this
531 snippet. This should be used if the snippet uses any font that LaTeX
532 cannot find on its own.
537 @node Invoking lilypond-book
538 @section Invoking @command{lilypond-book}
540 @command{lilypond-book} produces a file with one of the following
541 extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
542 output format. Both @file{.tex} and @file{.texi} files need further
545 To produce PDF output from the @file{.tex} file, you should do
549 dvips -Ppdf -u+ec-mftrace.map -u+lilypond.map yourfile.dvi
553 To produce a Texinfo document (in any output format), follow the normal
554 procedures for Texinfo (this is, either call @command{texi2dvi} or
555 @command{makeinfo}, depending on the output format you want to
558 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
559 an Info File, , , texinfo, GNU Texinfo}.
562 See the documentation of Texinfo for further details.
566 @command{lilypond-book} accepts the following command line options:
569 @item -f @var{format}
570 @itemx --format=@var{format}
571 Specify the document type to process: @code{html}, @code{latex}, or
572 @code{texi} (the default). If this option is missing,
573 @command{lilypond-book} tries to detect the format automatically.
575 The @code{texi} document type produces a Texinfo file with music
576 fragments in the DVI output only. For getting images in the HTML
577 version, the format @code{texi-html} must be used instead.
579 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
581 @item -F @var{filter}
582 @itemx --filter=@var{filter}
583 Pipe snippets through @var{filter}. @code{lilypond-book} will
584 not --filter and --process at the same time.
588 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
593 Print a short help message.
596 @itemx --include=@var{dir}
597 Add @var{dir} to the include path.
600 @itemx --output=@var{dir}
601 Place generated files in directory @var{dir}. Running
602 @command{lilypond-book} generates lots of small files that LilyPond will
603 process. To avoid all that garbage in the source directory use the
604 @option{--output} command line option, and change to that directory
605 before running @command{latex} or @command{makeinfo}:
608 lilypond-book --output=out yourfile.lytex
613 @item -P @var{process}
614 @itemx --process=@var{command}
615 Process LilyPond snippets using @var{command}. The default command is
616 @code{lilypond}. @code{lilypond-book} will not --filter and --process
625 Print version information.
630 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
631 La@TeX{} commands that change margins and line widths after the preamble
634 Only the first @code{\score} of a LilyPond block is processed.
637 The size of a music block is limited to 1.5 KB, due to technical
638 problems with the Python regular expression engine. For longer files,
639 use @code{\lilypondfile}.
642 @node Filename extensions
643 @section Filename extensions
645 You can use any filename extension for the input file, but if you do not
646 use the recommended extension for a particular format you may need to
647 manually specify the output format. @xref{Invoking lilypond-book}, for
648 details. Otherwise, @command{lilypond-book} automatically selects the
649 output format based on the input filename's extension.
652 @multitable @columnfractions .2 .5
653 @item @strong{extension} @tab @strong{output format}
655 @item @file{.html} @tab HTML
656 @item @file{.itely} @tab Texinfo
657 @item @file{.latex} @tab La@TeX{}
658 @item @file{.lytex} @tab La@TeX{}
659 @item @file{.tely} @tab Texinfo
660 @item @file{.tex} @tab La@TeX{}
661 @item @file{.texi} @tab Texinfo
662 @item @file{.texinfo} @tab Texinfo
663 @item @file{.xml} @tab HTML