1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 @c Note: keep this node named so that `info lilypond-book' brings you here.
13 @chapter @command{lilypond-book}: Integrating text and music
15 If you want to add pictures of music to a document, you can simply do it
16 the way you would do with other types of pictures. The pictures are
17 created separately, yielding PostScript output or PNG images, and those
18 are included into a @LaTeX{} or HTML document.
20 @command{lilypond-book} provides a way to automate this process: This
21 program extracts snippets of music from your document, runs
22 @command{lilypond} on them, and outputs the document with pictures
23 substituted for the music. The line width and font size definitions for
24 the music are adjusted to match the layout of your document.
26 This is a separate programs from lilypond itself, and is run
27 on the command-line; see @ref{Command-line usage} for more information.
29 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
37 @cindex documents, adding music to
38 @cindex HTML, music in
39 @cindex Texinfo, music in
40 @cindex DocBook, music in
41 @cindex @LaTeX{}, music in
44 * An example of a musicological document::
45 * Integrating music and text::
46 * Music fragment options::
47 * Invoking lilypond-book::
48 * Filename extensions::
49 * Alternate methods of mixing text and music::
53 @node An example of a musicological document
54 @section An example of a musicological document
57 Some texts contain music examples. These texts are musicological
58 treatises, songbooks, or manuals like this. Such texts can be made by
59 hand, simply by importing a PostScript figure into the word processor.
60 However, there is an automated procedure to reduce the amount of work
61 involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
63 A script called @code{lilypond-book} will extract the music fragments,
64 format them, and put back the resulting notation. Here we show a small
65 example for use with @LaTeX{}. The example also contains explanatory
66 text, so we will not comment on it further.
72 \documentclass[a4paper]{article}
76 Documents for @command{lilypond-book} may freely mix music and text.
81 c2 g'2 \times 2/3 { f8 e d } c'2 g4
85 Options are put in brackets.
87 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
91 Larger examples can be put into a separate file, and introduced with
94 \lilypondfile[quote,noindent]{screech-boink.ly}
100 @subheading Processing
102 Under Unix, you can view the results as follows
107 lilypond-book --output=out --psfonts lilybook.tex
108 @emph{lilypond-book (GNU LilyPond) 2.6.0}
109 @emph{Reading lilybook.tex...}
110 @emph{..lots of stuff deleted..}
111 @emph{Compiling out/lilybook.tex...}
114 @emph{lots of stuff deleted}
118 To convert the file into a PDF document, run the following commands
121 dvips -o -Ppdf -h lilybook.psfonts lilybook
125 If you are running latex in twocolumn mode, remember to add
126 @code{-t landscape} to the dvips options.
128 Running @command{lilypond-book} and @command{latex} creates a lot of
129 temporary files, which would clutter up the working directory. To
130 remedy this, use the @code{--output=@var{dir}} option. It will create
131 the files in a separate subdirectory @file{dir}.
133 Running dvips will produce many warnings about fonts. They are not
134 harmful; please ignore them.
136 Finally the result of the @LaTeX{} example shown above.@footnote{This
137 tutorial is processed with Texinfo, so the example gives slightly
138 different results in layout.} This finishes the tutorial section.
144 Documents for @command{lilypond-book} may freely mix music and text.
149 c2 g'2 \times 2/3 { f8 e d } c'2 g4
153 Options are put in brackets.
155 @lilypond[fragment,quote,staffsize=26,verbatim]
159 Larger examples can be put into a separate file, and introduced with
160 @code{\lilypondfile}.
162 @lilypondfile[quote,noindent]{screech-boink.ly}
167 @node Integrating music and text
168 @section Integrating music and text
170 Here we explain how to integrate LilyPond with various output formats.
182 @LaTeX{} is the de-facto standard for publishing layouts in the exact
183 sciences. It is built on top of the @TeX{} typesetting engine,
184 providing the best typography available anywhere.
187 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
188 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
191 Music is entered using
194 \begin[options,go,here]@{lilypond@}
203 \lilypondfile[options,go,here]@{@var{filename}@}
210 \lilypond@{ YOUR LILYPOND CODE @}
213 Running @command{lilypond-book} yields a file that can be further
214 processed with @LaTeX{}.
216 We show some examples here. The lilypond environment
219 \begin[quote,fragment,staffsize=26]@{lilypond@}
227 @lilypond[quote,fragment,staffsize=26]
234 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
240 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
243 Currently, you cannot include @code{@{} or @code{@}} within
244 @code{\lilypond@{@}}, so this command is only useful with the
245 @code{fragment} option.
247 The default line width of the music will be adjusted by examining the
248 commands in the document preamble, the part of the document before
249 @code{\begin@{document@}}. The @command{lilypond-book} command sends
250 these to @LaTeX{} to find out how wide the text is. The line width for
251 the music fragments is then adjusted to the text width. Note that this
252 heuristic algorithm can fail easily; in such cases it is necessary to
253 use the @code{line-width} music fragment option.
255 @cindex titling and lilypond-book
256 @cindex \header in @LaTeX{} documents
258 Each snippet will call the following macros if they have been defined by
261 @code{\preLilyPondExample} called before the music
263 @code{\postLilyPondExample} called after the music
265 @code{\betweenLilyPondSystem[1]} is called between systems if
266 @code{lilypond-book} has split the snippet into several postscript
267 files. It must be defined as taking one parameter and will be
268 passed the number of files already included in this snippet.
269 The default is to simply insert a @code{\linebreak}.
274 @cindex Latex, feta symbols
277 To include feta symbols (such as flat, segno, etc) in a LaTeX
278 document, use @code{\input@{titledefs@}}
281 \documentclass[a4paper]@{article@}
292 The font symbol names are defined in the file feta20.tex; to find
293 the location of this file, use the command
301 @cindex outline fonts
304 @cindex invoking dvips
306 For printing the @LaTeX{} document you need a DVI to PostScript
307 translator like @command{dvips}. To use @command{dvips} to produce
308 a PostScript file, add the following options to the @command{dvips}
312 -o -Ppdf -h @var{file}.psfonts
316 where the @var{file}@command{psfonts} file is obtained from
317 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
318 can then be produced with a PostScript to PDF translator like
319 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
320 will produce some warnings about fonts; these are harmless and may
323 If you are running latex in twocolumn mode, remember to add
324 @code{-t landscape} to the dvips options.
326 @cindex international characters
329 Sometimes it is useful to display music elements (such as ties and slurs)
330 as if they continued after the end of the fragment. This can be done by
331 breaking the staff and suppressing inclusion of the rest of the lilypond
334 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
335 inclusion of other systems is terminated once the required number of
336 systems are included. Since @code{\betweenLilypondSystem} is first
337 called @b{after} the first system, including only the first system
341 \def\betweenLilyPondSystem#1@{\endinput@}
343 \begin[fragment]@{lilypond@}
344 c'1\( e'( c'~ \break c' d) e f\)
348 If a greater number of systems is requested, a TeX conditional must be
349 used before the @code{\endinput}. In this example, replace @q{2} by
350 the number of systems you want in the output,
353 \def\betweenLilyPondSystem#1@{
354 \ifnum##1<2\else\endinput\fi
358 Remember that the definition of @code{\betweenLilyPondSystem} is
359 effective until @TeX{} quits the current group (such as the @LaTeX{}
360 environment) or is overridden by another definition (which is, in
361 most cases, for the rest of the document). To reset your
365 \let\betweenLilyPondSystem\undefined
369 in your LaTeX source.
371 This may be simplified by defining a @TeX{} macro
374 \def\onlyFirstNSystems#1@{
375 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
380 and then saying only how many systems you want before each fragment,
383 \onlyFirstNSystems@{3@}
384 \begin@{lilypond@}...\end@{lilypond@}
385 \onlyFirstNSystems@{1@}
386 \begin@{lilypond@}...\end@{lilypond@}
393 Texinfo is the standard format for documentation of the GNU project. An
394 example of a Texinfo document is this manual. The HTML, PDF, and Info
395 versions of the manual are made from the Texinfo document.
397 In the input file, music is specified with
400 @@lilypond[options,go,here]
409 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
416 @@lilypondfile[options,go,here]@{@var{filename}@}
419 When @command{lilypond-book} is run on it, this results in a Texinfo
420 file (with extension @file{.texi}) containing @code{@@image} tags for
421 HTML and info output. For the printed edition, the raw @TeX{} output of
422 LilyPond is included in the main document.
424 We show two simple examples here. A @code{lilypond} environment
442 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
448 @lilypond[fragment,staffsize=11]{<c' e' g'>}
450 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
451 in-line image. It always gets a paragraph of its own.
453 When using the Texinfo output format, @command{lilypond-book} also
454 generates bitmaps of the music (in PNG format), so you can make an HTML
455 document with embedded music.
461 Music is entered using
464 <lilypond fragment relative=2>
465 \key c \minor c4 es g2
470 @command{lilypond-book} then produces an HTML file with appropriate image
471 tags for the music fragments:
473 @lilypond[fragment,relative=2]
474 \key c \minor c4 es g2
477 For inline pictures, use @code{<lilypond ... />}, where the options
478 are separated by a colon from the music, for example
481 Some music in <lilypond relative=2: a b c/> a line of text.
484 To include separate files, say
487 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
490 @cindex titling in HTML
491 @cindex preview image
497 For inserting LilyPond snippets it is good to keep the conformity of
498 our DocBook document, thus allowing us to use DocBook editors,
499 validation etc. So we don't use custom tags, only specify a convention
500 based on the standard DocBook elements.
502 @subheading Common conventions
504 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
505 formatted inline or not inline.
506 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
507 chosen to allow DocBook editors format the content gracefully.
508 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
510 @subheading Including a LilyPond file
512 This is the most simple case. We must use the @file{.ly} extension for the included file, and insert it as a standard @code{imageobject},
513 with the following structure:
518 <imagedata fileref="music1.ly" role="printfilename" />
523 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
525 @subheading Including LilyPond code
527 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
532 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
533 \context Staff \with @{
534 \remove Time_signature_engraver
535 \remove Clef_engraver@}
542 As you can see, the outermost element is a @code{mediaobject} or @code{inlinemediaobject}, and there is a @code{textobject} containing the @code{programlisting} inside.
544 @subheading Processing the DocBook document
546 Running @command{lilypond-book} on our @file{.lyxml} file will create a
547 valid DocBook document to be further processed with @file{.xml}
548 extension. If you use
549 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
550 PDF file from this document automatically. For HTML (HTML Help,
551 JavaHelp etc.) generation you can use the official DocBook XSL
552 stylesheets, however, it is possible that you have to make some
553 customization for it.
556 @node Music fragment options
557 @section Music fragment options
559 In the following, a @q{LilyPond command} refers to any command described
560 in the previous sections which is handled by @command{lilypond-book} to
561 produce a music snippet. For simplicity, LilyPond commands are only
562 shown in @LaTeX{} syntax.
564 Note that the option string is parsed from left to right; if an option
565 occurs multiple times, the last one is taken.
567 The following options are available for LilyPond commands:
570 @item staffsize=@var{ht}
571 Set staff size to @var{ht}, which is measured in points.
574 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
575 = ##t} is added to the LilyPond snippet). This is the default for the
576 @code{\lilypond@{@}} command if no @code{line-width} option is present.
577 It is also the default for the @code{lilypond} environment if the
578 @code{fragment} option is set, and no line width is explicitly
582 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
583 to the LilyPond snippet).
586 @itemx line-width=@var{size}\@var{unit}
587 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
588 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
589 @code{pt}. This option affects LilyPond output (this is, the staff
590 length of the music snippet), not the text layout.
592 If used without an argument, set line width to a default value (as
593 computed with a heuristic algorithm).
595 If no @code{line-width} option is given, @command{lilypond-book} tries to
596 guess a default for @code{lilypond} environments which don't use the
597 @code{ragged-right} option.
600 Do not print the time signature, and turns off the timing (key signature,
601 bar lines) in the score.
604 Make @command{lilypond-book} add some boilerplate code so that you can
612 without @code{\layout}, @code{\score}, etc.
615 Don't add additional code to complete LilyPond code in music snippets.
616 Since this is the default, @code{nofragment} is redundant normally.
618 @item indent=@var{size}\@var{unit}
619 Set indentation of the first music system to @var{size}, using
620 @var{unit} as units. @var{unit} is one of the following strings:
621 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
622 LilyPond, not the text layout.
625 Set indentation of the first music system to zero. This option affects
626 LilyPond, not the text layout. Since no indentation is the default,
627 @code{noindent} is redundant normally.
630 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
631 the output into a quotation block. The value @q{0.4@dmn{in}} can be
632 controlled with the @code{exampleindent} option.
635 Set the amount by which the @code{quote} option indents a music snippet.
638 @itemx relative=@var{n}
639 Use relative octave mode. By default, notes are specified relative to
640 middle@tie{}C. The optional integer argument specifies the octave of
641 the starting note, where the default @code{1} is middle C.
644 LilyPond also uses @command{lilypond-book} to produce its own
645 documentation. To do that, some more obscure music fragment options are
650 The argument of a LilyPond command is copied to the output file and
651 enclosed in a verbatim block, followed by any text given with the
652 @code{intertext} option (not implemented yet); then the actual music is
653 displayed. This option does not work well with @code{\lilypond@{@}} if
654 it is part of a paragraph.
657 (Only for Texinfo output.) If @command{lilypond} is called with the
658 @option{--header=@/texidoc} option, and the file to be processed is
659 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
660 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
661 option makes @command{lilypond-book} include such files, adding its
662 contents as a documentation block right before the music snippet.
664 Assuming the file @file{foo@/.ly} contains
668 texidoc = "This file demonstrates a single note."
674 and we have this in our Texinfo document @file{test.texinfo}
677 @@lilypondfile[texidoc]@{foo.ly@}
681 the following command line gives the expected result
684 lilypond-book --process="lilypond --format=tex --tex \
685 --header=texidoc test.texinfo
688 Most LilyPond test documents (in the @file{input} directory of the
689 distribution) are small @file{.ly} files which look exactly like this.
692 If a LilyPond input file is included with @code{\lilypondfile}, print
693 the file name right before the music snippet. For HTML output, this is
697 This option includes fonts in all of the generated EPS-files for this
698 snippet. This should be used if the snippet uses any font that LaTeX
699 cannot find on its own.
704 @node Invoking lilypond-book
705 @section Invoking @command{lilypond-book}
707 @command{lilypond-book} produces a file with one of the following
708 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
709 output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
712 @command{lilypond-book} can also create a PSFONTS file, which is required
713 by @command{dvips} to produce Postscript and PDF files.
715 To produce PDF output from the lilypond-book file (here called
716 @code{yourfile.lytex}) via LaTeX, you should do
719 lilypond-book --psfonts yourfile.lytex
721 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
725 The @file{.dvi} file created by this process will not contain
726 noteheads. This is normal; if you follow the instructions, they
727 will be included in the @file{.ps} and @file{.pdf} files.
729 To produce a PDF file through PDF(La)TeX, use
732 lilypond-book --pdf yourfile.pdftex
733 pdflatex yourfile.tex
737 To produce a Texinfo document (in any output format), follow the normal
738 procedures for Texinfo (this is, either call @command{texi2dvi} or
739 @command{makeinfo}, depending on the output format you want to
742 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
743 an Info File, , , texinfo, GNU Texinfo}.
746 See the documentation of Texinfo for further details.
750 @command{lilypond-book} accepts the following command line options:
753 @item -f @var{format}
754 @itemx --format=@var{format}
755 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
756 @command{lilypond-book} tries to detect the format automatically.
758 The @code{texi} document type produces a Texinfo file with music
759 fragments in the DVI output only. For getting images in the HTML
760 version, the format @code{texi-html} must be used instead.
762 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
764 @item -F @var{filter}
765 @itemx --filter=@var{filter}
766 Pipe snippets through @var{filter}. @code{lilypond-book} will
767 not --filter and --process at the same time.
771 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
776 Print a short help message.
779 @itemx --include=@var{dir}
780 Add @var{dir} to the include path.
783 @itemx --output=@var{dir}
784 Place generated files in directory @var{dir}. Running
785 @command{lilypond-book} generates lots of small files that LilyPond will
786 process. To avoid all that garbage in the source directory use the
787 @option{--output} command line option, and change to that directory
788 before running @command{latex} or @command{makeinfo}:
791 lilypond-book --output=out yourfile.lytex
796 @itemx --left-padding=@var{amount}
797 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
798 and is 3.0 by default. This option should be used if the lines of
799 music stick out of the right margin.
801 The width of a tightly clipped systems can vary, due to notation
802 elements that stick into the left margin, such as bar numbers and
803 instrument names. This option will shorten each line and move each
804 line to the right by the same amount.
807 @item -P @var{process}
808 @itemx --process=@var{command}
809 Process LilyPond snippets using @var{command}. The default command is
810 @code{lilypond}. @code{lilypond-book} will not --filter and --process
814 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
815 This is necessary for @command{dvips -h @var{file}.psfonts}.
823 Print version information.
828 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
829 @LaTeX{} commands that change margins and line widths after the preamble
832 Only the first @code{\score} of a LilyPond block is processed.
835 @node Filename extensions
836 @section Filename extensions
838 You can use any filename extension for the input file, but if you do not
839 use the recommended extension for a particular format you may need to
840 manually specify the output format. @xref{Invoking lilypond-book}, for
841 details. Otherwise, @command{lilypond-book} automatically selects the
842 output format based on the input filename's extension.
845 @multitable @columnfractions .2 .5
846 @item @strong{extension} @tab @strong{output format}
848 @item @file{.html} @tab HTML
849 @item @file{.itely} @tab Texinfo
850 @item @file{.latex} @tab @LaTeX{}
851 @item @file{.lytex} @tab @LaTeX{}
852 @item @file{.lyxml} @tab DocBook
853 @item @file{.tely} @tab Texinfo
854 @item @file{.tex} @tab @LaTeX{}
855 @item @file{.texi} @tab Texinfo
856 @item @file{.texinfo} @tab Texinfo
857 @item @file{.xml} @tab HTML
862 @node Alternate methods of mixing text and music
863 @section Alternative methods of mixing text and music
866 * Many quotes from a large score::
867 * Inserting LilyPond output into OpenOffice.org::
868 * Inserting LilyPond output into other programs::
871 @node Many quotes from a large score
872 @subsection Many quotes from a large score
874 If you need to quote many fragments from a large score, you can also use
875 the clip systems feature, see @ruser{Extracting fragments of notation}.
878 @node Inserting LilyPond output into OpenOffice.org
879 @subsection Inserting LilyPond output into OpenOffice.org
881 @cindex OpenOffice.org
883 LilyPond notation can be added to OpenOffice.org with
884 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
887 @node Inserting LilyPond output into other programs
888 @subsection Inserting LilyPond output into other programs
890 To insert LilyPond output in other programs, use @code{lilypond}
891 instead of @code{lilypond-book}. Each example must be created
892 individually and added to the document; consult the documentation for
893 that program. Most programs will be able to insert lilypond output in
894 @file{PNG}, @file{EPS}, or @file{PDF} formats.
896 To reduce the white space around your lilypond score, use
897 the following options
905 bookTitleMarkup = ##f
906 scoreTitleMarkup = ##f
912 To produce a useful @file{eps} file, use
915 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly