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 --psfonts lilybook.tex
97 @emph{lilypond-book (GNU LilyPond) 2.6.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 -h lilybook.psfonts 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 Running dvips will produce many warnings about fonts. They are not
120 harmful; please ignore them.
122 Finally the result of the La@TeX{} example shown above.@footnote{This
123 tutorial is processed with Texinfo, so the example gives slightly
124 different results in layout.} This finishes the tutorial section.
128 Documents for @command{lilypond-book} may freely mix music and text.
133 c2 g'2 \times 2/3 { f8 e d } c'2 g4
137 Options are put in brackets.
139 @lilypond[fragment,quote,staffsize=26,verbatim]
143 Larger examples can be put into a separate file, and introduced with
144 @code{\lilypondfile}.
146 @lilypondfile[quote,noindent]{screech-boink.ly}
155 @cindex documents, adding music to
158 @node Integrating LaTeX and music
159 @section Integrating La@TeX{} and music
161 La@TeX{} is the de-facto standard for publishing layouts in the exact
162 sciences. It is built on top of the @TeX{} typesetting engine,
163 providing the best typography available anywhere.
166 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
167 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
170 Music is entered using
173 \begin[options,go,here]@{lilypond@}
182 \lilypondfile[options,go,here]@{@var{filename}@}
189 \lilypond@{ YOUR LILYPOND CODE @}
192 Running @command{lilypond-book} yields a file that can be further
193 processed with La@TeX{}. Since @command{lilypond-book} produces
194 lilypond snippets as @code{\includegraphics@{NAME.eps@}}, you must
198 \RequirePackage@{graphics@}
202 to the preamble of the LaTeX document.
204 We show some examples here. The lilypond environment
207 \begin[quote,fragment,staffsize=26]@{lilypond@}
215 @lilypond[quote,fragment,staffsize=26]
222 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
228 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
231 Currently, you cannot include @code{@{} or @code{@}} within
232 @code{\lilypond@{@}}, so this command is only useful with the
233 @code{fragment} option.
235 The default linewidth of the music will be adjusted by examining the
236 commands in the document preamble, the part of the document before
237 @code{\begin@{document@}}. The @command{lilypond-book} command sends
238 these to La@TeX{} to find out how wide the text is. The line width for
239 the music fragments is then adjusted to the text width. Note that this
240 heuristic algorithm can fail easily; in such cases it is necessary to
241 use the @code{linewidth} music fragment option.
243 @cindex titling and lilypond-book
244 @cindex @code{\header} in La@TeX{} documents
246 Each snippet will call the following macros if they have been defined by
249 @code{\preLilyPondExample} called before the music
251 @code{\postLilyPondExample} called after the music
253 @code{\betweenLilyPondSystem[1]} is called between systems if
254 @code{lilypond-book} has split the snippet into several postscript
255 files. It must be defined as taking one parameter and will be
256 passed the number of files already included in this snippet.
262 @cindex Latex, feta symbols
265 To include feta symbols (such as flat, segno, etc) in a LaTeX
266 document, use @code{\input@{titledefs@}}
269 \documentclass[a4paper]@{article@}
280 The font symbol names are defined in the file feta20.tex; to find
281 the location of this file, use the command
289 @cindex outline fonts
292 @cindex invoking dvips
294 For printing the La@TeX{} document you need a DVI to PostScript
295 translator like @command{dvips}. To use @command{dvips} to produce
296 a PostScript file, add the following options to the @command{dvips}
300 -Ppdf -h @var{file}.psfonts
304 where the @var{file}@command{psfonts} file is obtained from
305 @command{lilypond-book}, @xref{Invoking lilypond-book} for details. PDF
306 can then be produced with a PostScript to PDF translator like
307 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
308 will produce some warnings about fonts; these are harmless and may
311 @cindex international characters
315 @node Integrating Texinfo and music
316 @section Integrating Texinfo and music
318 Texinfo is the standard format for documentation of the GNU project. An
319 example of a Texinfo document is this manual. The HTML, PDF, and Info
320 versions of the manual are made from the Texinfo document.
322 In the input file, music is specified with
325 @@lilypond[options,go,here]
334 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
341 @@lilypondfile[options,go,here]@{@var{filename}@}
344 When @command{lilypond-book} is run on it, this results in a Texinfo
345 file (with extension @file{.texi}) containing @code{@@image} tags for
346 HTML and info output. For the printed edition, the raw @TeX{} output of
347 LilyPond is included in the main document.
349 We show two simple examples here. A @code{lilypond} environment
367 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
373 @lilypond[fragment,staffsize=11]{<c' e' g'>}
375 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
376 in-line image. It always gets a paragraph of its own.
378 When using the Texinfo output format, @command{lilypond-book} also
379 generates bitmaps of the music (in PNG format), so you can make an HTML
380 document with embedded music.
383 @node Integrating HTML and music
384 @section Integrating HTML and music
386 Music is entered using
389 <lilypond fragment relative=2>
390 \key c \minor c4 es g2
395 @command{lilypond-book} then produces an HTML file with appropriate image
396 tags for the music fragments:
398 @lilypond[fragment,relative=2]
399 \key c \minor c4 es g2
402 For inline pictures, use @code{<lilypond ... />}, where the options
403 are separated by a colon from the music, for example
406 Some music in <lilypond relative=2: a b c/> a line of text.
409 To include separate files, say
412 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
415 @cindex titling in HTML
416 @cindex preview image
420 @node Music fragment options
421 @section Music fragment options
423 In the following, a ``LilyPond command'' refers to any command described
424 in the previous sections which is handled by @command{lilypond-book} to
425 produce a music snippet. For simplicity, LilyPond commands are only
426 shown in La@TeX{} syntax.
428 Note that the option string is parsed from left to right; if an option
429 occurs multiple times, the last one is taken.
431 The following options are available for LilyPond commands:
434 @item staffsize=@var{ht}
435 Set staff size to @var{ht}, which is measured in points.
438 Produce ragged-right lines with natural spacing (i.e., @code{raggedright
439 = ##t} is added to the LilyPond snippet). This is the default for the
440 @code{\lilypond@{@}} command if no @code{linewidth} option is present.
441 It is also the default for the @code{lilypond} environment if the
442 @code{fragment} option is set, and no line width is explicitly
446 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
447 to the LilyPond snippet).
450 @itemx linewidth=@var{size}\@var{unit}
451 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
452 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
453 @code{pt}. This option affects LilyPond output (this is, the staff
454 length of the music snippet), not the text layout.
456 If used without an argument, set line width to a default value (as
457 computed with a heuristic algorithm).
459 If no @code{linewidth} option is given, @command{lilypond-book} tries to
460 guess a default for @code{lilypond} environments which don't use the
461 @code{raggedright} option.
464 Do not print the time signature.
467 Make @command{lilypond-book} add some boilerplate code so that you can
475 without @code{\layout}, @code{\score}, etc.
478 Don't add additional code to complete LilyPond code in music snippets.
479 Since this is the default, @code{nofragment} is redundant normally.
481 @item indent=@var{size}\@var{unit}
482 Set indentation of the first music system to @var{size}, using
483 @var{unit} as units. @var{unit} is one of the following strings:
484 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
485 LilyPond, not the text layout.
488 Set indentation of the first music system to zero. This option affects
489 LilyPond, not the text layout. Since no indentation is the default,
490 @code{noindent} is redundant normally.
493 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
494 the output into a quotation block. The value `0.4@dmn{in}' can be
495 controlled with the @code{exampleindent} option.
498 Set the amount by which the @code{quote} option indents a music snippet.
501 @itemx relative=@var{n}
502 Use relative octave mode. By default, notes are specified relative to
503 middle@tie{}C. The optional integer argument specifies the octave of
504 the starting note, where the default @code{1} is middle C.
507 LilyPond also uses @command{lilypond-book} to produce its own
508 documentation. To do that, some more obscure music fragment options are
513 The argument of a LilyPond command is copied to the output file and
514 enclosed in a verbatim block, followed by any text given with the
515 @code{intertext} option (not implemented yet); then the actual music is
516 displayed. This option does not work well with @code{\lilypond@{@}} if
517 it is part of a paragraph.
520 (Only for Texinfo output.) If @command{lilypond} is called with the
521 @option{--header=@/texidoc} option, and the file to be processed is
522 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
523 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
524 option makes @command{lilypond-book} include such files, adding its
525 contents as a documentation block right before the music snippet.
527 Assuming the file @file{foo@/.ly} contains
531 texidoc = "This file demonstrates a single note."
537 and we have this in our Texinfo document @file{test.texinfo}
540 @@lilypondfile[texidoc]@{foo.ly@}
544 the following command line gives the expected result
547 lilypond-book --process="lilypond --format=tex --tex \
548 --header=texidoc test.texinfo
551 Most LilyPond test documents (in the @file{input} directory of the
552 distribution) are small @file{.ly} files which look exactly like this.
555 If a LilyPond input file is included with @code{\lilypondfile}, print
556 the file name right before the music snippet. For HTML output, this is
560 This option includes fonts in all of the generated EPS-files for this
561 snippet. This should be used if the snippet uses any font that LaTeX
562 cannot find on its own.
567 @node Invoking lilypond-book
568 @section Invoking @command{lilypond-book}
570 @command{lilypond-book} produces a file with one of the following
571 extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
572 output format. Both @file{.tex} and @file{.texi} files need further
575 @command{lilypond-book} can also create a PSFONTS file, which is required
576 by @command{dvips} to produce Postscript and PDF files. You can call
577 this file whatever you want as long as you refer to the same file when
578 you call @command{dvips}.
580 To produce PDF output from the lilypond-book file (here called
581 @code{yourfile.lytex}), you should do
584 lilypond-book --psfonts yourfile.lytex
586 dvips -h yourfile.psfonts -Ppdf yourfile.dvi
590 To produce a Texinfo document (in any output format), follow the normal
591 procedures for Texinfo (this is, either call @command{texi2dvi} or
592 @command{makeinfo}, depending on the output format you want to
595 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
596 an Info File, , , texinfo, GNU Texinfo}.
599 See the documentation of Texinfo for further details.
603 @command{lilypond-book} accepts the following command line options:
606 @item -f @var{format}
607 @itemx --format=@var{format}
608 Specify the document type to process: @code{html}, @code{latex}, or
609 @code{texi} (the default). If this option is missing,
610 @command{lilypond-book} tries to detect the format automatically.
612 The @code{texi} document type produces a Texinfo file with music
613 fragments in the DVI output only. For getting images in the HTML
614 version, the format @code{texi-html} must be used instead.
616 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
618 @item -F @var{filter}
619 @itemx --filter=@var{filter}
620 Pipe snippets through @var{filter}. @code{lilypond-book} will
621 not --filter and --process at the same time.
625 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
630 Print a short help message.
633 @itemx --include=@var{dir}
634 Add @var{dir} to the include path.
637 @itemx --output=@var{dir}
638 Place generated files in directory @var{dir}. Running
639 @command{lilypond-book} generates lots of small files that LilyPond will
640 process. To avoid all that garbage in the source directory use the
641 @option{--output} command line option, and change to that directory
642 before running @command{latex} or @command{makeinfo}:
645 lilypond-book --output=out yourfile.lytex
650 @item -P @var{process}
651 @itemx --process=@var{command}
652 Process LilyPond snippets using @var{command}. The default command is
653 @code{lilypond}. @code{lilypond-book} will not --filter and --process
657 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
658 This is necessary for @command{dvips -h @var{file}.psfonts}.
666 Print version information.
671 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
672 La@TeX{} commands that change margins and line widths after the preamble
675 Only the first @code{\score} of a LilyPond block is processed.
678 @node Filename extensions
679 @section Filename extensions
681 You can use any filename extension for the input file, but if you do not
682 use the recommended extension for a particular format you may need to
683 manually specify the output format. @xref{Invoking lilypond-book}, for
684 details. Otherwise, @command{lilypond-book} automatically selects the
685 output format based on the input filename's extension.
688 @multitable @columnfractions .2 .5
689 @item @strong{extension} @tab @strong{output format}
691 @item @file{.html} @tab HTML
692 @item @file{.itely} @tab Texinfo
693 @item @file{.latex} @tab La@TeX{}
694 @item @file{.lytex} @tab La@TeX{}
695 @item @file{.tely} @tab Texinfo
696 @item @file{.tex} @tab La@TeX{}
697 @item @file{.texi} @tab Texinfo
698 @item @file{.texinfo} @tab Texinfo
699 @item @file{.xml} @tab HTML