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 program from @command{lilypond} itself, and is run on
27 the command-line; for more information, see @ref{Command-line usage}.
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 \verb+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}
96 (If needed, replace screech-boink.ly by any .ly file you put in the same
97 directory as this file.)
103 @subheading Processing
105 Save the code above to a file called @file{lilybook.lytex}, then in a
109 lilypond-book --output=out --pdf lilybook.lytex
110 @emph{lilypond-book (GNU LilyPond) 2.11.37}
111 @emph{Reading lilybook.lytex...}
112 @emph{..lots of stuff deleted..}
113 @emph{Compiling lilybook.tex...}
116 @emph{..lots of stuff deleted..}
118 @emph{(replace @command{xpdf} by your favorite PDF viewer)}
121 Running @command{lilypond-book} and @command{latex} creates a lot of
122 temporary files, which would clutter up the working directory. To
123 remedy this, use the @code{--output=@var{dir}} option. It will create
124 the files in a separate subdirectory @file{dir}.
126 Finally the result of the @LaTeX{} example shown above.@footnote{This
127 tutorial is processed with Texinfo, so the example gives slightly
128 different results in layout.} This finishes the tutorial section.
134 Documents for @command{lilypond-book} may freely mix music and text.
139 c2 g'2 \times 2/3 { f8 e d } c'2 g4
143 Options are put in brackets.
145 @lilypond[fragment,quote,staffsize=26,verbatim]
149 Larger examples can be put into a separate file, and introduced with
150 @code{\lilypondfile}.
152 @lilypondfile[quote,noindent]{screech-boink.ly}
157 @node Integrating music and text
158 @section Integrating music and text
160 Here we explain how to integrate LilyPond with various output formats.
172 @LaTeX{} is the de-facto standard for publishing layouts in the exact
173 sciences. It is built on top of the @TeX{} typesetting engine,
174 providing the best typography available anywhere.
177 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
178 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
181 Music is entered using
184 \begin[options,go,here]@{lilypond@}
193 \lilypondfile[options,go,here]@{@var{filename}@}
200 \lilypond@{ YOUR LILYPOND CODE @}
203 Running @command{lilypond-book} yields a file that can be further
204 processed with @LaTeX{}.
206 We show some examples here. The @code{lilypond} environment
209 \begin[quote,fragment,staffsize=26]@{lilypond@}
217 @lilypond[quote,fragment,staffsize=26]
224 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
230 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
233 Currently, you cannot include @code{@{} or @code{@}} within
234 @code{\lilypond@{@}}, so this command is only useful with the
235 @code{fragment} option.
237 The default line width of the music will be adjusted by examining the
238 commands in the document preamble, the part of the document before
239 @code{\begin@{document@}}. The @command{lilypond-book} command sends
240 these to @LaTeX{} to find out how wide the text is. The line width for
241 the music fragments is then adjusted to the text width. Note that this
242 heuristic algorithm can fail easily; in such cases it is necessary to
243 use the @code{line-width} music fragment option.
245 @cindex titling and lilypond-book
246 @cindex \header in @LaTeX{} documents
248 Each snippet will call the following macros if they have been defined by
252 @item @code{\preLilyPondExample} called before the music,
254 @item @code{\postLilyPondExample} called after the music,
256 @item @code{\betweenLilyPondSystem[1]} is called between systems if
257 @code{lilypond-book} has split the snippet into several postscript
258 files. It must be defined as taking one parameter and will be
259 passed the number of files already included in this snippet.
260 The default is to simply insert a @code{\linebreak}.
266 @cindex Latex, feta symbols
269 To include feta symbols (such as flat, segno, etc) in a LaTeX
270 document, use @code{\input@{titledefs@}}
273 \documentclass[a4paper]@{article@}
284 The font symbol names are defined in the file feta20.tex; to find
285 the location of this file, use the command
295 Sometimes it is useful to display music elements (such as ties and slurs)
296 as if they continued after the end of the fragment. This can be done by
297 breaking the staff and suppressing inclusion of the rest of the lilypond
300 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
301 inclusion of other systems is terminated once the required number of
302 systems are included. Since @code{\betweenLilypondSystem} is first
303 called @emph{after} the first system, including only the first system
307 \def\betweenLilyPondSystem#1@{\endinput@}
309 \begin[fragment]@{lilypond@}
310 c'1\( e'( c'~ \break c' d) e f\)
314 If a greater number of systems is requested, a @TeX{} conditional must
315 be used before the @code{\endinput}. In this example, replace @q{2} by
316 the number of systems you want in the output,
319 \def\betweenLilyPondSystem#1@{
320 \ifnum##1<2\else\endinput\fi
324 Remember that the definition of @code{\betweenLilyPondSystem} is
325 effective until @TeX{} quits the current group (such as the @LaTeX{}
326 environment) or is overridden by another definition (which is, in
327 most cases, for the rest of the document). To reset your
331 \let\betweenLilyPondSystem\undefined
335 in your @LaTeX{} source.
337 This may be simplified by defining a @TeX{} macro
340 \def\onlyFirstNSystems#1@{
341 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
346 and then saying only how many systems you want before each fragment,
349 \onlyFirstNSystems@{3@}
350 \begin@{lilypond@}...\end@{lilypond@}
351 \onlyFirstNSystems@{1@}
352 \begin@{lilypond@}...\end@{lilypond@}
356 There are specific @command{lilypond-book} command line options and
357 other details to know when processing @LaTeX{} documents, see
358 @ref{Invoking lilypond-book}.
364 Texinfo is the standard format for documentation of the GNU project. An
365 example of a Texinfo document is this manual. The HTML, PDF, and Info
366 versions of the manual are made from the Texinfo document.
368 In the input file, music is specified with
371 @@lilypond[options,go,here]
380 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
387 @@lilypondfile[options,go,here]@{@var{filename}@}
390 When @command{lilypond-book} is run on it, this results in a Texinfo
391 file (with extension @file{.texi}) containing @code{@@image} tags for
392 HTML, Info and printed output. @command{lilypond-book} generates images
393 of the music in EPS and PDF formats for use in the printed output, and
394 in PNG format for use in HTML and Info output.
396 We show two simple examples here. A @code{lilypond} environment
414 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
420 @lilypond[fragment,staffsize=11]{<c' e' g'>}
422 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
423 in-line image. It always gets a paragraph of its own.
429 Music is entered using
432 <lilypond fragment relative=2>
433 \key c \minor c4 es g2
438 @command{lilypond-book} then produces an HTML file with appropriate image
439 tags for the music fragments:
441 @lilypond[fragment,relative=2]
442 \key c \minor c4 es g2
445 For inline pictures, use @code{<lilypond ... />}, where the options
446 are separated by a colon from the music, for example
449 Some music in <lilypond relative=2: a b c/> a line of text.
452 To include separate files, say
455 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
458 @cindex titling in HTML
459 @cindex preview image
465 For inserting LilyPond snippets it is good to keep the conformity of our
466 DocBook document, thus allowing us to use DocBook editors, validation
467 etc. So we don't use custom tags, only specify a convention based on the
468 standard DocBook elements.
470 @subheading Common conventions
472 For inserting all type of snippets we use the @code{mediaobject} and
473 @code{inlinemediaobject} element, so our snippets can be formatted
474 inline or not inline. The snippet formatting options are always
475 provided in the @code{role} property of the innermost element (see in
476 next sections). Tags are chosen to allow DocBook editors format the
477 content gracefully. The DocBook files to be processed with
478 @command{lilypond-book} should have the extension @file{.lyxml}.
480 @subheading Including a LilyPond file
482 This is the most simple case. We must use the @file{.ly} extension for
483 the included file, and insert it as a standard @code{imageobject}, with
484 the following structure:
489 <imagedata fileref="music1.ly" role="printfilename" />
494 Note that you can use mediaobject or inlinemediaobject as the outermost
497 @subheading Including LilyPond code
499 Including LilyPond code is possible by using a @code{programlisting},
500 where the language is set to @code{lilypond} with the following
506 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
507 \context Staff \with @{
508 \remove Time_signature_engraver
509 \remove Clef_engraver@}
516 As you can see, the outermost element is a @code{mediaobject} or
517 @code{inlinemediaobject}, and there is a @code{textobject} containing
518 the @code{programlisting} inside.
520 @subheading Processing the DocBook document
522 Running @command{lilypond-book} on our @file{.lyxml} file will create a
523 valid DocBook document to be further processed with @file{.xml}
524 extension. If you use
525 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
526 PDF file from this document automatically. For HTML (HTML Help,
527 JavaHelp etc.) generation you can use the official DocBook XSL
528 stylesheets, however, it is possible that you have to make some
529 customization for it.
532 @node Music fragment options
533 @section Music fragment options
535 In the following, a @q{LilyPond command} refers to any command described
536 in the previous sections which is handled by @command{lilypond-book} to
537 produce a music snippet. For simplicity, LilyPond commands are only
538 shown in @LaTeX{} syntax.
540 Note that the option string is parsed from left to right; if an option
541 occurs multiple times, the last one is taken.
543 The following options are available for LilyPond commands:
546 @item staffsize=@var{ht}
547 Set staff size to @var{ht}, which is measured in points.
550 Produce ragged-right lines with natural spacing, i.e.,
551 @code{ragged-right = ##t} is added to the LilyPond snippet. This is the
552 default for the @code{\lilypond@{@}} command if no @code{line-width}
553 option is present. It is also the default for the @code{lilypond}
554 environment if the @code{fragment} option is set, and no line width is
555 explicitly specified.
557 @c does this option still exist in lilypond? -jm
559 Produce lines with packed spacing, i.e., @code{packed = ##t} is added
560 to the LilyPond snippet.
563 @itemx line-width=@var{size}\@var{unit}
564 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
565 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
566 @code{pt}. This option affects LilyPond output (this is, the staff
567 length of the music snippet), not the text layout.
569 If used without an argument, set line width to a default value (as
570 computed with a heuristic algorithm).
572 If no @code{line-width} option is given, @command{lilypond-book} tries to
573 guess a default for @code{lilypond} environments which don't use the
574 @code{ragged-right} option.
577 Do not print the time signature, and turns off the timing (key signature,
578 bar lines) in the score.
581 Make @command{lilypond-book} add some boilerplate code so that you can
589 without @code{\layout}, @code{\score}, etc.
592 Do not add additional code to complete LilyPond code in music snippets.
593 Since this is the default, @code{nofragment} is redundant normally.
595 @item indent=@var{size}\@var{unit}
596 Set indentation of the first music system to @var{size}, using
597 @var{unit} as units. @var{unit} is one of the following strings:
598 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
599 LilyPond, not the text layout.
602 Set indentation of the first music system to zero. This option affects
603 LilyPond, not the text layout. Since no indentation is the default,
604 @code{noindent} is redundant normally.
607 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
608 the output into a quotation block. The value @q{0.4@dmn{in}} can be
609 controlled with the @code{exampleindent} option.
612 Set the amount by which the @code{quote} option indents a music snippet.
615 @itemx relative=@var{n}
616 Use relative octave mode. By default, notes are specified relative to
617 middle@tie{}C. The optional integer argument specifies the octave of
618 the starting note, where the default @code{1} is middle C.
621 LilyPond also uses @command{lilypond-book} to produce its own
622 documentation. To do that, some more obscure music fragment options are
627 The argument of a LilyPond command is copied to the output file and
628 enclosed in a verbatim block, followed by any text given with the
629 @code{intertext} option (not implemented yet); then the actual music is
630 displayed. This option does not work well with @code{\lilypond@{@}} if
631 it is part of a paragraph.
633 If @code{verbatim} is used in a @code{lilypondfile} command, it is
634 possible to enclose verbatim only a part of the source file. If the
635 source file contain a comment containing @samp{begin verbatim} (without
636 quotes), quoting the source in the verbatim block will start after the
637 last occurence of such a comment; similarly, quoting the source verbatim
638 will stop just before the first occurence of a comment containing
639 @samp{end verbatim}, it there is any. In the following source file
640 example, the music will be interpreted in relative mode, but the
641 verbatim quote will not show the @code{relative} block, i.e.
644 \relative c' @{ % begin verbatim
651 will be printed with a verbatim block like
659 (Only for Texinfo output.) If @command{lilypond} is called with the
660 @option{--header=@/texidoc} option, and the file to be processed is
661 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
662 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
663 option makes @command{lilypond-book} include such files, adding its
664 contents as a documentation block right before the music snippet.
666 Assuming the file @file{foo@/.ly} contains
670 texidoc = "This file demonstrates a single note."
676 and we have this in our Texinfo document @file{test.texinfo}
679 @@lilypondfile[texidoc]@{foo.ly@}
683 the following command line gives the expected result
686 lilypond-book --process="lilypond --format=tex --tex \
687 --header=texidoc test.texinfo
690 Most LilyPond test documents (in the @file{input} directory of the
691 distribution) are small @file{.ly} files which look exactly like this.
694 (Only for Texinfo output.) This option is similar to quote, but only
695 the music snippet (and the optional verbatim block implied by
696 @code{verbatim} option) is put into a quotation block. This option is
697 useful if you want to @code{quote} the music snippet but not the
698 @code{texidoc} documentation block.
701 If a LilyPond input file is included with @code{\lilypondfile}, print
702 the file name right before the music snippet. For HTML output, this is
706 This option includes fonts in all of the generated EPS-files for this
707 snippet. This should be used if the snippet uses any font that LaTeX
708 cannot find on its own.
713 @node Invoking lilypond-book
714 @section Invoking @command{lilypond-book}
716 @command{lilypond-book} produces a file with one of the following
717 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
718 depending on the output format. All of @file{.tex}, @file{.texi} and
719 @file{.xml} files need further processing.
721 @command{lilypond-book} can also create a @file{.psfonts} file, which is
722 required by @command{dvips} to produce PostScript and PDF files.
724 @subheading Format-specific instructions
726 @subsubheading @LaTeX{}
728 There are two ways of processing your @LaTeX{} document for printing or
729 publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
730 PostScript file with @LaTeX{} via a DVI to PostScript translator like
731 @command{dvips}. The first way is simpler and recommended@footnote{Note
732 that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
733 @LaTeX{} document, that is why we explain the two ways.}, and whichever
734 way you use, you can easily convert between PostScript and PDF with
735 tools, like @command{ps2pdf} and @command{pdf2ps} included in
738 To produce a PDF file through PDF@LaTeX{}, use
741 lilypond-book --pdf yourfile.pdftex
742 pdflatex yourfile.tex
745 @cindex outline fonts
748 @cindex invoking dvips
749 To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
753 lilypond-book --psfonts yourfile.lytex
755 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
760 The @file{.dvi} file created by this process will not contain
761 note heads. This is normal; if you follow the instructions, they
762 will be included in the @file{.ps} and @file{.pdf} files.
764 Running @command{dvips} will produce some warnings about fonts; these
765 are harmless and may be ignored. If you are running @command{latex} in
766 twocolumn mode, remember to add @code{-t landscape} to the
767 @command{dvips} options.
769 @subsubheading Texinfo
771 To produce a Texinfo document (in any output format), follow the normal
772 procedures for Texinfo; this is, either call @command{texi2pdf} or
773 @command{texi2dvi} or @command{makeinfo}, depending on the output format
776 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
777 an Info File, , , texinfo, GNU Texinfo}.
780 See the documentation of Texinfo for further details.
784 @subheading Command line options
786 @command{lilypond-book} accepts the following command line options:
789 @item -f @var{format}
790 @itemx --format=@var{format}
791 Specify the document type to process: @code{html}, @code{latex},
792 @code{texi} (the default) or @code{docbook}. If this option is missing,
793 @command{lilypond-book} tries to detect the format automatically, see
794 @ref{Filename extensions}. Currently, @code{texi} is the same as
797 @c This complicated detail is not implemented, comment it out -jm
799 The @code{texi} document type produces a Texinfo file with music
800 fragments in the printed output only. For getting images in the HTML
801 version, the format @code{texi-html} must be used instead.
804 @item -F @var{filter}
805 @itemx --filter=@var{filter}
806 Pipe snippets through @var{filter}. @code{lilypond-book} will
807 not --filter and --process at the same time. For example,
810 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
815 Print a short help message.
818 @itemx --include=@var{dir}
819 Add @var{dir} to the include path.
822 @itemx --output=@var{dir}
823 Place generated files in directory @var{dir}. Running
824 @command{lilypond-book} generates lots of small files that LilyPond will
825 process. To avoid all that garbage in the source directory use the
826 @option{--output} command line option, and change to that directory
827 before running @command{latex} or @command{makeinfo}.
830 lilypond-book --output=out yourfile.lytex
835 @itemx --left-padding=@var{amount}
836 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
837 and is 3.0 by default. This option should be used if the lines of
838 music stick out of the right margin.
840 The width of a tightly clipped systems can vary, due to notation
841 elements that stick into the left margin, such as bar numbers and
842 instrument names. This option will shorten each line and move each
843 line to the right by the same amount.
846 @item -P @var{process}
847 @itemx --process=@var{command}
848 Process LilyPond snippets using @var{command}. The default command is
849 @code{lilypond}. @code{lilypond-book} will not @code{--filter} and
850 @code{--process} at the same time.
853 Create PDF files for use with PDFLaTeX.
856 Extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
857 This is necessary for @command{dvips -h @var{file}.psfonts}.
865 Print version information.
870 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
871 @LaTeX{} commands that change margins and line widths after the preamble
874 Only the first @code{\score} of a LilyPond block is processed.
877 @node Filename extensions
878 @section Filename extensions
880 You can use any filename extension for the input file, but if you do not
881 use the recommended extension for a particular format you may need to
882 manually specify the output format; for details, see @ref{Invoking
883 lilypond-book}. Otherwise, @command{lilypond-book} automatically
884 selects the output format based on the input filename's extension.
887 @multitable @columnfractions .2 .5
888 @item @strong{extension} @tab @strong{output format}
890 @item @file{.html} @tab HTML
891 @item @file{.itely} @tab Texinfo
892 @item @file{.latex} @tab @LaTeX{}
893 @item @file{.lytex} @tab @LaTeX{}
894 @item @file{.lyxml} @tab DocBook
895 @item @file{.tely} @tab Texinfo
896 @item @file{.tex} @tab @LaTeX{}
897 @item @file{.texi} @tab Texinfo
898 @item @file{.texinfo} @tab Texinfo
899 @item @file{.xml} @tab HTML
903 If you use the same filename extension for the input file than the
904 extension @command{lilypond-book} uses for the output file, and if the
905 input file is in the same directory as @command{lilypond-book} working
906 directory, you must use @code{--output} option to make
907 @command{lilypond-book} running, otherwise the will exit with an error
908 message like @qq{Output would overwrite input file}.
911 @node Alternate methods of mixing text and music
912 @section Alternative methods of mixing text and music
914 This section shows methods to integrate text and music, different than
915 the automated method with @command{lilypond-book}.
918 * Many quotes from a large score::
919 * Inserting LilyPond output into OpenOffice.org::
920 * Inserting LilyPond output into other programs::
923 @node Many quotes from a large score
924 @subsection Many quotes from a large score
926 If you need to quote many fragments from a large score, you can also use
927 the clip systems feature, see @ruser{Extracting fragments of notation}.
930 @node Inserting LilyPond output into OpenOffice.org
931 @subsection Inserting LilyPond output into OpenOffice.org
933 @cindex OpenOffice.org
935 LilyPond notation can be added to OpenOffice.org with
936 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
939 @node Inserting LilyPond output into other programs
940 @subsection Inserting LilyPond output into other programs
942 To insert LilyPond output in other programs, use @code{lilypond}
943 instead of @code{lilypond-book}. Each example must be created
944 individually and added to the document; consult the documentation for
945 that program. Most programs will be able to insert lilypond output in
946 @file{PNG}, @file{EPS}, or @file{PDF} formats.
948 To reduce the white space around your lilypond score, use
949 the following options
957 bookTitleMarkup = ##f
958 scoreTitleMarkup = ##f
964 To produce a useful EPS file, use
967 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly