1 c -*- coding: utf-8; 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::
41 * Many quotes of a large score::
42 * Inserting LilyPond output into other programs::
46 @node An example of a musicological document
47 @section An example of a musicological document
50 @cindex La@TeX{}, music in
51 @cindex HTML, music in
52 @cindex Texinfo, music in
53 Some texts contain music examples. These texts are musicological
54 treatises, songbooks, or manuals like this. Such texts can be made by
55 hand, simply by importing a PostScript figure into the word processor.
56 However, there is an automated procedure to reduce the amount of work
57 involved in HTML, La@TeX{}, and Texinfo documents.
59 A script called @code{lilypond-book} will extract the music fragments,
60 format them, and put back the resulting notation. Here we show a small
61 example for use with La@TeX{}. The example also contains explanatory
62 text, so we will not comment on it further.
66 \documentclass[a4paper]{article}
70 Documents for @command{lilypond-book} may freely mix music and text.
75 c2 g'2 \times 2/3 { f8 e d } c'2 g4
79 Options are put in brackets.
81 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
85 Larger examples can be put into a separate file, and introduced with
88 \lilypondfile[quote,noindent]{screech-boink.ly}
94 Under Unix, you can view the results as follows
99 lilypond-book --output=out --psfonts lilybook.tex
100 @emph{lilypond-book (GNU LilyPond) 2.6.0}
101 @emph{Reading 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 PDF document, run the following commands
113 dvips -o -Ppdf -h lilybook.psfonts lilybook
117 Running @command{lilypond-book} and @command{latex} creates a lot of
118 temporary files, which would clutter up the working directory. To
119 remedy this, use the @code{--output=@var{dir}} option. It will create
120 the files in a separate subdirectory @file{dir}.
122 Running dvips will produce many warnings about fonts. They are not
123 harmful; please ignore them.
125 Finally the result of the La@TeX{} example shown above.@footnote{This
126 tutorial is processed with Texinfo, so the example gives slightly
127 different results in layout.} This finishes the tutorial section.
131 Documents for @command{lilypond-book} may freely mix music and text.
136 c2 g'2 \times 2/3 { f8 e d } c'2 g4
140 Options are put in brackets.
142 @lilypond[fragment,quote,staffsize=26,verbatim]
146 Larger examples can be put into a separate file, and introduced with
147 @code{\lilypondfile}.
149 @lilypondfile[quote,noindent]{screech-boink.ly}
158 @cindex documents, adding music to
161 @node Integrating LaTeX and music
162 @section Integrating La@TeX{} and music
164 La@TeX{} is the de-facto standard for publishing layouts in the exact
165 sciences. It is built on top of the @TeX{} typesetting engine,
166 providing the best typography available anywhere.
169 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
170 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
173 Music is entered using
176 \begin[options,go,here]@{lilypond@}
185 \lilypondfile[options,go,here]@{@var{filename}@}
192 \lilypond@{ YOUR LILYPOND CODE @}
195 Running @command{lilypond-book} yields a file that can be further
196 processed with La@TeX{}.
198 We show some examples here. The lilypond environment
201 \begin[quote,fragment,staffsize=26]@{lilypond@}
209 @lilypond[quote,fragment,staffsize=26]
216 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
222 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
225 Currently, you cannot include @code{@{} or @code{@}} within
226 @code{\lilypond@{@}}, so this command is only useful with the
227 @code{fragment} option.
229 The default line width of the music will be adjusted by examining the
230 commands in the document preamble, the part of the document before
231 @code{\begin@{document@}}. The @command{lilypond-book} command sends
232 these to La@TeX{} to find out how wide the text is. The line width for
233 the music fragments is then adjusted to the text width. Note that this
234 heuristic algorithm can fail easily; in such cases it is necessary to
235 use the @code{line-width} music fragment option.
237 @cindex titling and lilypond-book
238 @funindex \header in La@TeX{} documents
240 Each snippet will call the following macros if they have been defined by
243 @code{\preLilyPondExample} called before the music
245 @code{\postLilyPondExample} called after the music
247 @code{\betweenLilyPondSystem[1]} is called between systems if
248 @code{lilypond-book} has split the snippet into several postscript
249 files. It must be defined as taking one parameter and will be
250 passed the number of files already included in this snippet.
251 The default is to simply insert a @code{\linebreak}.
256 @cindex Latex, feta symbols
259 To include feta symbols (such as flat, segno, etc) in a LaTeX
260 document, use @code{\input@{titledefs@}}
263 \documentclass[a4paper]@{article@}
274 The font symbol names are defined in the file feta20.tex; to find
275 the location of this file, use the command
283 @cindex outline fonts
286 @cindex invoking dvips
288 For printing the La@TeX{} document you need a DVI to PostScript
289 translator like @command{dvips}. To use @command{dvips} to produce
290 a PostScript file, add the following options to the @command{dvips}
294 -o -Ppdf -h @var{file}.psfonts
298 where the @var{file}@command{psfonts} file is obtained from
299 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
300 can then be produced with a PostScript to PDF translator like
301 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
302 will produce some warnings about fonts; these are harmless and may
305 @cindex international characters
308 Sometimes it is useful to display music elements (such as ties and slurs)
309 as if they continued after the end of the fragment. This can be done by
310 breaking the staff and suppressing inclusion of the rest of the lilypond
313 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
314 inclusion of other systems is terminated once the required number of
315 systems are included. Since @code{\betweenLilypondSystem} is first
316 called @b{after} the first system, including only the first system
320 \def\betweenLilyPondSystem#1@{\endinput@}
322 \begin[fragment]@{lilypond@}
323 c'1\( e'( c'~ \break c' d) e f\)
327 If a greater number of systems is requested, a TeX conditional must be
328 used before the @code{\endinput}. In this example, replace "2" by
329 the numer of systems you want in the output,
332 \def\betweenLilyPondSystem#1@{
333 \ifnum##1<2\else\endinput\fi
337 Remember that the definition of @code{\betweenLilyPondSystem} is
338 effective until @TeX{} quits the current group (such as the La@TeX{}
339 environment) or is overridden by another definition (which is, in
340 most cases, for the rest of the document). To reset your
344 \let\betweenLilyPondSystem\undefined
348 in your LaTeX source.
350 This may be simplified by defining a @TeX{} macro
353 \def\onlyFirstNSystems#1@{
354 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
359 and then saying only how many systems you want before each fragment,
362 \onlyFirstNSystems@{3@}
363 \begin@{lilypond@}...\end@{lilypond@}
364 \onlyFirstNSystems@{1@}
365 \begin@{lilypond@}...\end@{lilypond@}
369 @node Integrating Texinfo and music
370 @section Integrating Texinfo and music
372 Texinfo is the standard format for documentation of the GNU project. An
373 example of a Texinfo document is this manual. The HTML, PDF, and Info
374 versions of the manual are made from the Texinfo document.
376 In the input file, music is specified with
379 @@lilypond[options,go,here]
388 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
395 @@lilypondfile[options,go,here]@{@var{filename}@}
398 When @command{lilypond-book} is run on it, this results in a Texinfo
399 file (with extension @file{.texi}) containing @code{@@image} tags for
400 HTML and info output. For the printed edition, the raw @TeX{} output of
401 LilyPond is included in the main document.
403 We show two simple examples here. A @code{lilypond} environment
421 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
427 @lilypond[fragment,staffsize=11]{<c' e' g'>}
429 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
430 in-line image. It always gets a paragraph of its own.
432 When using the Texinfo output format, @command{lilypond-book} also
433 generates bitmaps of the music (in PNG format), so you can make an HTML
434 document with embedded music.
437 @node Integrating HTML and music
438 @section Integrating HTML and music
440 Music is entered using
443 <lilypond fragment relative=2>
444 \key c \minor c4 es g2
449 @command{lilypond-book} then produces an HTML file with appropriate image
450 tags for the music fragments:
452 @lilypond[fragment,relative=2]
453 \key c \minor c4 es g2
456 For inline pictures, use @code{<lilypond ... />}, where the options
457 are separated by a colon from the music, for example
460 Some music in <lilypond relative=2: a b c/> a line of text.
463 To include separate files, say
466 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
469 @cindex titling in HTML
470 @cindex preview image
474 @node Music fragment options
475 @section Music fragment options
477 In the following, a ``LilyPond command'' refers to any command described
478 in the previous sections which is handled by @command{lilypond-book} to
479 produce a music snippet. For simplicity, LilyPond commands are only
480 shown in La@TeX{} syntax.
482 Note that the option string is parsed from left to right; if an option
483 occurs multiple times, the last one is taken.
485 The following options are available for LilyPond commands:
488 @item staffsize=@var{ht}
489 Set staff size to @var{ht}, which is measured in points.
492 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
493 = ##t} is added to the LilyPond snippet). This is the default for the
494 @code{\lilypond@{@}} command if no @code{line-width} option is present.
495 It is also the default for the @code{lilypond} environment if the
496 @code{fragment} option is set, and no line width is explicitly
500 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
501 to the LilyPond snippet).
504 @itemx line-width=@var{size}\@var{unit}
505 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
506 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
507 @code{pt}. This option affects LilyPond output (this is, the staff
508 length of the music snippet), not the text layout.
510 If used without an argument, set line width to a default value (as
511 computed with a heuristic algorithm).
513 If no @code{line-width} option is given, @command{lilypond-book} tries to
514 guess a default for @code{lilypond} environments which don't use the
515 @code{ragged-right} option.
518 Do not print the time signature, and turns off the timing (key signature,
519 bar lines) in the score.
522 Make @command{lilypond-book} add some boilerplate code so that you can
530 without @code{\layout}, @code{\score}, etc.
533 Don't add additional code to complete LilyPond code in music snippets.
534 Since this is the default, @code{nofragment} is redundant normally.
536 @item indent=@var{size}\@var{unit}
537 Set indentation of the first music system to @var{size}, using
538 @var{unit} as units. @var{unit} is one of the following strings:
539 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
540 LilyPond, not the text layout.
543 Set indentation of the first music system to zero. This option affects
544 LilyPond, not the text layout. Since no indentation is the default,
545 @code{noindent} is redundant normally.
548 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
549 the output into a quotation block. The value `0.4@dmn{in}' can be
550 controlled with the @code{exampleindent} option.
553 Set the amount by which the @code{quote} option indents a music snippet.
556 @itemx relative=@var{n}
557 Use relative octave mode. By default, notes are specified relative to
558 middle@tie{}C. The optional integer argument specifies the octave of
559 the starting note, where the default @code{1} is middle C.
562 LilyPond also uses @command{lilypond-book} to produce its own
563 documentation. To do that, some more obscure music fragment options are
568 The argument of a LilyPond command is copied to the output file and
569 enclosed in a verbatim block, followed by any text given with the
570 @code{intertext} option (not implemented yet); then the actual music is
571 displayed. This option does not work well with @code{\lilypond@{@}} if
572 it is part of a paragraph.
575 (Only for Texinfo output.) If @command{lilypond} is called with the
576 @option{--header=@/texidoc} option, and the file to be processed is
577 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
578 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
579 option makes @command{lilypond-book} include such files, adding its
580 contents as a documentation block right before the music snippet.
582 Assuming the file @file{foo@/.ly} contains
586 texidoc = "This file demonstrates a single note."
592 and we have this in our Texinfo document @file{test.texinfo}
595 @@lilypondfile[texidoc]@{foo.ly@}
599 the following command line gives the expected result
602 lilypond-book --process="lilypond --format=tex --tex \
603 --header=texidoc test.texinfo
606 Most LilyPond test documents (in the @file{input} directory of the
607 distribution) are small @file{.ly} files which look exactly like this.
610 If a LilyPond input file is included with @code{\lilypondfile}, print
611 the file name right before the music snippet. For HTML output, this is
615 This option includes fonts in all of the generated EPS-files for this
616 snippet. This should be used if the snippet uses any font that LaTeX
617 cannot find on its own.
622 @node Invoking lilypond-book
623 @section Invoking @command{lilypond-book}
625 @command{lilypond-book} produces a file with one of the following
626 extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
627 output format. Both @file{.tex} and @file{.texi} files need further
630 @command{lilypond-book} can also create a PSFONTS file, which is required
631 by @command{dvips} to produce Postscript and PDF files.
633 To produce PDF output from the lilypond-book file (here called
634 @code{yourfile.lytex}) via LaTeX, you should do
637 lilypond-book --psfonts yourfile.lytex
639 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
643 The @file{.dvi} file created by this process will not contain
644 noteheads. This is normal; if you follow the instructions, they
645 will be included in the @file{.ps} and @file{.pdf} files.
647 To produce a PDF file through PDF(La)TeX, use
650 lilypond-book --pdf yourfile.pdftex
651 pdflatex yourfile.tex
655 To produce a Texinfo document (in any output format), follow the normal
656 procedures for Texinfo (this is, either call @command{texi2dvi} or
657 @command{makeinfo}, depending on the output format you want to
660 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
661 an Info File, , , texinfo, GNU Texinfo}.
664 See the documentation of Texinfo for further details.
668 @command{lilypond-book} accepts the following command line options:
671 @item -f @var{format}
672 @itemx --format=@var{format}
673 Specify the document type to process: @code{html}, @code{latex}, or
674 @code{texi} (the default). If this option is missing,
675 @command{lilypond-book} tries to detect the format automatically.
677 The @code{texi} document type produces a Texinfo file with music
678 fragments in the DVI output only. For getting images in the HTML
679 version, the format @code{texi-html} must be used instead.
681 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
683 @item -F @var{filter}
684 @itemx --filter=@var{filter}
685 Pipe snippets through @var{filter}. @code{lilypond-book} will
686 not --filter and --process at the same time.
690 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
695 Print a short help message.
698 @itemx --include=@var{dir}
699 Add @var{dir} to the include path.
702 @itemx --output=@var{dir}
703 Place generated files in directory @var{dir}. Running
704 @command{lilypond-book} generates lots of small files that LilyPond will
705 process. To avoid all that garbage in the source directory use the
706 @option{--output} command line option, and change to that directory
707 before running @command{latex} or @command{makeinfo}:
710 lilypond-book --output=out yourfile.lytex
715 @item -P @var{process}
716 @itemx --process=@var{command}
717 Process LilyPond snippets using @var{command}. The default command is
718 @code{lilypond}. @code{lilypond-book} will not --filter and --process
722 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
723 This is necessary for @command{dvips -h @var{file}.psfonts}.
731 Print version information.
736 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
737 La@TeX{} commands that change margins and line widths after the preamble
740 Only the first @code{\score} of a LilyPond block is processed.
743 @node Filename extensions
744 @section Filename extensions
746 You can use any filename extension for the input file, but if you do not
747 use the recommended extension for a particular format you may need to
748 manually specify the output format. @xref{Invoking lilypond-book}, for
749 details. Otherwise, @command{lilypond-book} automatically selects the
750 output format based on the input filename's extension.
753 @multitable @columnfractions .2 .5
754 @item @strong{extension} @tab @strong{output format}
756 @item @file{.html} @tab HTML
757 @item @file{.itely} @tab Texinfo
758 @item @file{.latex} @tab La@TeX{}
759 @item @file{.lytex} @tab La@TeX{}
760 @item @file{.tely} @tab Texinfo
761 @item @file{.tex} @tab La@TeX{}
762 @item @file{.texi} @tab Texinfo
763 @item @file{.texinfo} @tab Texinfo
764 @item @file{.xml} @tab HTML
768 @node Many quotes of a large score
769 @section Many quotes of a large score
771 If you need to quote many fragments of a large score, you can also use
772 the clip systems feature, see @ref{Extracting fragments of notation}.
774 @node Inserting LilyPond output into other programs
775 @section Inserting LilyPond output into other programs
777 To insert LilyPond output in other programs, use @code{lilypond}
778 instead of @code{lilypond-book}. Each example must be created
779 individually and added to the document; consult the documentation for
780 that program. Most programs will be able to insert lilypond output in
781 @file{PNG}, @file{EPS}, or @file{PDF} formats.
783 To reduce the white space around your lilypond score, use
784 the following options
792 bookTitleMarkup = ##f
793 scoreTitleMarkup = ##f
799 To produce a useful @file{eps} file, use
802 lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly