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 * Inserting LilyPond output into other programs::
45 @node An example of a musicological document
46 @section An example of a musicological document
49 @cindex La@TeX{}, music in
50 @cindex HTML, music in
51 @cindex Texinfo, music in
52 Some texts contain music examples. These texts are musicological
53 treatises, songbooks, or manuals like this. Such texts can be made by
54 hand, simply by importing a PostScript figure into the word processor.
55 However, there is an automated procedure to reduce the amount of work
56 involved in HTML, La@TeX{}, and Texinfo documents.
58 A script called @code{lilypond-book} will extract the music fragments,
59 format them, and put back the resulting notation. Here we show a small
60 example for use with La@TeX{}. The example also contains explanatory
61 text, so we will not comment on it further.
65 \documentclass[a4paper]{article}
69 Documents for @command{lilypond-book} may freely mix music and text.
74 c2 g'2 \times 2/3 { f8 e d } c'2 g4
78 Options are put in brackets.
80 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
84 Larger examples can be put into a separate file, and introduced with
87 \lilypondfile[quote,noindent]{screech-boink.ly}
93 Under Unix, you can view the results as follows
98 lilypond-book --output=out --psfonts lilybook.tex
99 @emph{lilypond-book (GNU LilyPond) 2.6.0}
100 @emph{Reading lilybook.tex...}
101 @emph{..lots of stuff deleted..}
102 @emph{Compiling out/lilybook.tex...}
105 @emph{lots of stuff deleted}
109 To convert the file into a PDF document, run the following commands
112 dvips -o -Ppdf -h lilybook.psfonts lilybook
116 Running @command{lilypond-book} and @command{latex} creates a lot of
117 temporary files, which would clutter up the working directory. To
118 remedy this, use the @code{--output=@var{dir}} option. It will create
119 the files in a separate subdirectory @file{dir}.
121 Running dvips will produce many warnings about fonts. They are not
122 harmful; please ignore them.
124 Finally the result of the La@TeX{} example shown above.@footnote{This
125 tutorial is processed with Texinfo, so the example gives slightly
126 different results in layout.} This finishes the tutorial section.
130 Documents for @command{lilypond-book} may freely mix music and text.
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 into a separate file, and introduced with
146 @code{\lilypondfile}.
148 @lilypondfile[quote,noindent]{screech-boink.ly}
157 @cindex documents, adding music to
160 @node Integrating LaTeX and music
161 @section Integrating La@TeX{} 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,
165 providing the best typography available anywhere.
168 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
169 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
172 Music is entered using
175 \begin[options,go,here]@{lilypond@}
184 \lilypondfile[options,go,here]@{@var{filename}@}
191 \lilypond@{ YOUR LILYPOND CODE @}
194 Running @command{lilypond-book} yields a file that can be further
195 processed with La@TeX{}.
197 We show some examples here. The lilypond environment
200 \begin[quote,fragment,staffsize=26]@{lilypond@}
208 @lilypond[quote,fragment,staffsize=26]
215 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
221 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
224 Currently, you cannot include @code{@{} or @code{@}} within
225 @code{\lilypond@{@}}, so this command is only useful with the
226 @code{fragment} option.
228 The default line width of the music will be adjusted by examining the
229 commands in the document preamble, the part of the document before
230 @code{\begin@{document@}}. The @command{lilypond-book} command sends
231 these to La@TeX{} to find out how wide the text is. The line width for
232 the music fragments is then adjusted to the text width. Note that this
233 heuristic algorithm can fail easily; in such cases it is necessary to
234 use the @code{line-width} music fragment option.
236 @cindex titling and lilypond-book
237 @funindex \header in La@TeX{} documents
239 Each snippet will call the following macros if they have been defined by
242 @code{\preLilyPondExample} called before the music
244 @code{\postLilyPondExample} called after the music
246 @code{\betweenLilyPondSystem[1]} is called between systems if
247 @code{lilypond-book} has split the snippet into several postscript
248 files. It must be defined as taking one parameter and will be
249 passed the number of files already included in this snippet.
250 The default is to simply insert a @code{\linebreak}.
255 @cindex Latex, feta symbols
258 To include feta symbols (such as flat, segno, etc) in a LaTeX
259 document, use @code{\input@{titledefs@}}
262 \documentclass[a4paper]@{article@}
273 The font symbol names are defined in the file feta20.tex; to find
274 the location of this file, use the command
282 @cindex outline fonts
285 @cindex invoking dvips
287 For printing the La@TeX{} document you need a DVI to PostScript
288 translator like @command{dvips}. To use @command{dvips} to produce
289 a PostScript file, add the following options to the @command{dvips}
293 -o -Ppdf -h @var{file}.psfonts
297 where the @var{file}@command{psfonts} file is obtained from
298 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
299 can then be produced with a PostScript to PDF translator like
300 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
301 will produce some warnings about fonts; these are harmless and may
304 @cindex international characters
307 Sometimes it is useful to display music elements (such as ties and slurs)
308 as if they continued after the end of the fragment. This can be done by
309 breaking the staff and suppressing inclusion of the rest of the lilypond
312 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
313 inclusion of other systems is terminated once the required number of
314 systems are included. Since @code{\betweenLilypondSystem} is first
315 called @b{after} the first system, including only the first system
319 \def\betweenLilyPondSystem#1@{\endinput@}
321 \begin[fragment]@{lilypond@}
322 c'1\( e'( c'~ \break c' d) e f\)
326 If a greater number of systems is requested, a TeX conditional must be
327 used before the @code{\endinput}. In this example, replace "2" by
328 the numer of systems you want in the output,
331 \def\betweenLilyPondSystem#1@{
332 \ifnum##1<2\else\endinput\fi
336 Remember that the definition of @code{\betweenLilyPondSystem} is
337 effective until @TeX{} quits the current group (such as the La@TeX{}
338 environment) or is overridden by another definition (which is, in
339 most cases, for the rest of the document). To reset your
343 \let\betweenLilyPondSystem\undefined
347 in your LaTeX source.
349 This may be simplified by defining a @TeX{} macro
352 \def\onlyFirstNSystems#1@{
353 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
358 and then saying only how many systems you want before each fragment,
361 \onlyFirstNSystems@{3@}
362 \begin@{lilypond@}...\end@{lilypond@}
363 \onlyFirstNSystems@{1@}
364 \begin@{lilypond@}...\end@{lilypond@}
368 @node Integrating Texinfo and music
369 @section Integrating Texinfo and music
371 Texinfo is the standard format for documentation of the GNU project. An
372 example of a Texinfo document is this manual. The HTML, PDF, and Info
373 versions of the manual are made from the Texinfo document.
375 In the input file, music is specified with
378 @@lilypond[options,go,here]
387 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
394 @@lilypondfile[options,go,here]@{@var{filename}@}
397 When @command{lilypond-book} is run on it, this results in a Texinfo
398 file (with extension @file{.texi}) containing @code{@@image} tags for
399 HTML and info output. For the printed edition, the raw @TeX{} output of
400 LilyPond is included in the main document.
402 We show two simple examples here. A @code{lilypond} environment
420 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
426 @lilypond[fragment,staffsize=11]{<c' e' g'>}
428 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
429 in-line image. It always gets a paragraph of its own.
431 When using the Texinfo output format, @command{lilypond-book} also
432 generates bitmaps of the music (in PNG format), so you can make an HTML
433 document with embedded music.
436 @node Integrating HTML and music
437 @section Integrating HTML and music
439 Music is entered using
442 <lilypond fragment relative=2>
443 \key c \minor c4 es g2
448 @command{lilypond-book} then produces an HTML file with appropriate image
449 tags for the music fragments:
451 @lilypond[fragment,relative=2]
452 \key c \minor c4 es g2
455 For inline pictures, use @code{<lilypond ... />}, where the options
456 are separated by a colon from the music, for example
459 Some music in <lilypond relative=2: a b c/> a line of text.
462 To include separate files, say
465 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
468 @cindex titling in HTML
469 @cindex preview image
473 @node Music fragment options
474 @section Music fragment options
476 In the following, a ``LilyPond command'' refers to any command described
477 in the previous sections which is handled by @command{lilypond-book} to
478 produce a music snippet. For simplicity, LilyPond commands are only
479 shown in La@TeX{} syntax.
481 Note that the option string is parsed from left to right; if an option
482 occurs multiple times, the last one is taken.
484 The following options are available for LilyPond commands:
487 @item staffsize=@var{ht}
488 Set staff size to @var{ht}, which is measured in points.
491 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
492 = ##t} is added to the LilyPond snippet). This is the default for the
493 @code{\lilypond@{@}} command if no @code{line-width} option is present.
494 It is also the default for the @code{lilypond} environment if the
495 @code{fragment} option is set, and no line width is explicitly
499 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
500 to the LilyPond snippet).
503 @itemx line-width=@var{size}\@var{unit}
504 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
505 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
506 @code{pt}. This option affects LilyPond output (this is, the staff
507 length of the music snippet), not the text layout.
509 If used without an argument, set line width to a default value (as
510 computed with a heuristic algorithm).
512 If no @code{line-width} option is given, @command{lilypond-book} tries to
513 guess a default for @code{lilypond} environments which don't use the
514 @code{ragged-right} option.
517 Do not print the time signature, and turns off the timing (key signature,
518 bar lines) in the score.
521 Make @command{lilypond-book} add some boilerplate code so that you can
529 without @code{\layout}, @code{\score}, etc.
532 Don't add additional code to complete LilyPond code in music snippets.
533 Since this is the default, @code{nofragment} is redundant normally.
535 @item indent=@var{size}\@var{unit}
536 Set indentation of the first music system to @var{size}, using
537 @var{unit} as units. @var{unit} is one of the following strings:
538 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
539 LilyPond, not the text layout.
542 Set indentation of the first music system to zero. This option affects
543 LilyPond, not the text layout. Since no indentation is the default,
544 @code{noindent} is redundant normally.
547 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
548 the output into a quotation block. The value `0.4@dmn{in}' can be
549 controlled with the @code{exampleindent} option.
552 Set the amount by which the @code{quote} option indents a music snippet.
555 @itemx relative=@var{n}
556 Use relative octave mode. By default, notes are specified relative to
557 middle@tie{}C. The optional integer argument specifies the octave of
558 the starting note, where the default @code{1} is middle C.
561 LilyPond also uses @command{lilypond-book} to produce its own
562 documentation. To do that, some more obscure music fragment options are
567 The argument of a LilyPond command is copied to the output file and
568 enclosed in a verbatim block, followed by any text given with the
569 @code{intertext} option (not implemented yet); then the actual music is
570 displayed. This option does not work well with @code{\lilypond@{@}} if
571 it is part of a paragraph.
574 (Only for Texinfo output.) If @command{lilypond} is called with the
575 @option{--header=@/texidoc} option, and the file to be processed is
576 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
577 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
578 option makes @command{lilypond-book} include such files, adding its
579 contents as a documentation block right before the music snippet.
581 Assuming the file @file{foo@/.ly} contains
585 texidoc = "This file demonstrates a single note."
591 and we have this in our Texinfo document @file{test.texinfo}
594 @@lilypondfile[texidoc]@{foo.ly@}
598 the following command line gives the expected result
601 lilypond-book --process="lilypond --format=tex --tex \
602 --header=texidoc test.texinfo
605 Most LilyPond test documents (in the @file{input} directory of the
606 distribution) are small @file{.ly} files which look exactly like this.
609 If a LilyPond input file is included with @code{\lilypondfile}, print
610 the file name right before the music snippet. For HTML output, this is
614 This option includes fonts in all of the generated EPS-files for this
615 snippet. This should be used if the snippet uses any font that LaTeX
616 cannot find on its own.
621 @node Invoking lilypond-book
622 @section Invoking @command{lilypond-book}
624 @command{lilypond-book} produces a file with one of the following
625 extensions: @file{.tex}, @file{.texi}, or @file{.html}, depending on the
626 output format. Both @file{.tex} and @file{.texi} files need further
629 @command{lilypond-book} can also create a PSFONTS file, which is required
630 by @command{dvips} to produce Postscript and PDF files.
632 To produce PDF output from the lilypond-book file (here called
633 @code{yourfile.lytex}) via LaTeX, you should do
636 lilypond-book --psfonts yourfile.lytex
638 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
642 The @file{.dvi} file created by this process will not contain
643 noteheads. This is normal; if you follow the instructions, they
644 will be included in the @file{.ps} and @file{.pdf} files.
646 To produce a PDF file through PDF(La)TeX, use
649 lilypond-book --pdf yourfile.pdftex
650 pdflatex yourfile.tex
654 To produce a Texinfo document (in any output format), follow the normal
655 procedures for Texinfo (this is, either call @command{texi2dvi} or
656 @command{makeinfo}, depending on the output format you want to
659 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
660 an Info File, , , texinfo, GNU Texinfo}.
663 See the documentation of Texinfo for further details.
667 @command{lilypond-book} accepts the following command line options:
670 @item -f @var{format}
671 @itemx --format=@var{format}
672 Specify the document type to process: @code{html}, @code{latex}, or
673 @code{texi} (the default). If this option is missing,
674 @command{lilypond-book} tries to detect the format automatically.
676 The @code{texi} document type produces a Texinfo file with music
677 fragments in the DVI output only. For getting images in the HTML
678 version, the format @code{texi-html} must be used instead.
680 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
682 @item -F @var{filter}
683 @itemx --filter=@var{filter}
684 Pipe snippets through @var{filter}. @code{lilypond-book} will
685 not --filter and --process at the same time.
689 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
694 Print a short help message.
697 @itemx --include=@var{dir}
698 Add @var{dir} to the include path.
701 @itemx --output=@var{dir}
702 Place generated files in directory @var{dir}. Running
703 @command{lilypond-book} generates lots of small files that LilyPond will
704 process. To avoid all that garbage in the source directory use the
705 @option{--output} command line option, and change to that directory
706 before running @command{latex} or @command{makeinfo}:
709 lilypond-book --output=out yourfile.lytex
714 @item -P @var{process}
715 @itemx --process=@var{command}
716 Process LilyPond snippets using @var{command}. The default command is
717 @code{lilypond}. @code{lilypond-book} will not --filter and --process
721 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
722 This is necessary for @command{dvips -h @var{file}.psfonts}.
730 Print version information.
735 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
736 La@TeX{} commands that change margins and line widths after the preamble
739 Only the first @code{\score} of a LilyPond block is processed.
742 @node Filename extensions
743 @section Filename extensions
745 You can use any filename extension for the input file, but if you do not
746 use the recommended extension for a particular format you may need to
747 manually specify the output format. @xref{Invoking lilypond-book}, for
748 details. Otherwise, @command{lilypond-book} automatically selects the
749 output format based on the input filename's extension.
752 @multitable @columnfractions .2 .5
753 @item @strong{extension} @tab @strong{output format}
755 @item @file{.html} @tab HTML
756 @item @file{.itely} @tab Texinfo
757 @item @file{.latex} @tab La@TeX{}
758 @item @file{.lytex} @tab La@TeX{}
759 @item @file{.tely} @tab Texinfo
760 @item @file{.tex} @tab La@TeX{}
761 @item @file{.texi} @tab Texinfo
762 @item @file{.texinfo} @tab Texinfo
763 @item @file{.xml} @tab HTML
768 @node Inserting LilyPond output into other programs
769 @section Inserting LilyPond output into other programs
771 To insert LilyPond output in other programs, use @code{lilypond}
772 instead of @code{lilypond-book}. Each example must be created
773 individually and added to the document; consult the
774 documentation for that program. Most programs will be able
775 to insert lilypond output in @file{PNG}, @file{EPS}, or @file{PDF}
778 To reduce the white space around your lilypond score, use
779 the following options
787 bookTitleMarkup = ##f
788 scoreTitleMarkup = ##f
794 To produce a useful @file{eps} file, use
797 lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly