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, Texinfo or DocBook documents.
34 * An example of a musicological document::
35 * Integrating LaTeX and music::
36 * Integrating Texinfo and music::
37 * Integrating HTML and music::
38 * Integrating DocBook and music::
39 * Music fragment options::
40 * Invoking lilypond-book::
41 * Filename extensions::
42 * Many quotes of a large score::
43 * Inserting LilyPond output into other programs::
47 @node An example of a musicological document
48 @section An example of a musicological document
51 @cindex La@TeX{}, music in
52 @cindex HTML, music in
53 @cindex Texinfo, music in
54 @cindex DocBook, music in
55 Some texts contain music examples. These texts are musicological
56 treatises, songbooks, or manuals like this. Such texts can be made by
57 hand, simply by importing a PostScript figure into the word processor.
58 However, there is an automated procedure to reduce the amount of work
59 involved in HTML, La@TeX{}, Texinfo and DocBook documents.
61 A script called @code{lilypond-book} will extract the music fragments,
62 format them, and put back the resulting notation. Here we show a small
63 example for use with La@TeX{}. The example also contains explanatory
64 text, so we will not comment on it further.
68 \documentclass[a4paper]{article}
72 Documents for @command{lilypond-book} may freely mix music and text.
77 c2 g'2 \times 2/3 { f8 e d } c'2 g4
81 Options are put in brackets.
83 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
87 Larger examples can be put into a separate file, and introduced with
90 \lilypondfile[quote,noindent]{screech-boink.ly}
96 Under Unix, you can view the results as follows
101 lilypond-book --output=out --psfonts lilybook.tex
102 @emph{lilypond-book (GNU LilyPond) 2.6.0}
103 @emph{Reading lilybook.tex...}
104 @emph{..lots of stuff deleted..}
105 @emph{Compiling out/lilybook.tex...}
108 @emph{lots of stuff deleted}
112 To convert the file into a PDF document, run the following commands
115 dvips -o -Ppdf -h lilybook.psfonts lilybook
119 If you are running latex in twocolumn mode, remember to add
120 @code{-t landscape} to the dvips options.
122 Running @command{lilypond-book} and @command{latex} creates a lot of
123 temporary files, which would clutter up the working directory. To
124 remedy this, use the @code{--output=@var{dir}} option. It will create
125 the files in a separate subdirectory @file{dir}.
127 Running dvips will produce many warnings about fonts. They are not
128 harmful; please ignore them.
130 Finally the result of the La@TeX{} example shown above.@footnote{This
131 tutorial is processed with Texinfo, so the example gives slightly
132 different results in layout.} This finishes the tutorial section.
136 Documents for @command{lilypond-book} may freely mix music and text.
141 c2 g'2 \times 2/3 { f8 e d } c'2 g4
145 Options are put in brackets.
147 @lilypond[fragment,quote,staffsize=26,verbatim]
151 Larger examples can be put into a separate file, and introduced with
152 @code{\lilypondfile}.
154 @lilypondfile[quote,noindent]{screech-boink.ly}
164 @cindex documents, adding music to
167 @node Integrating LaTeX and music
168 @section Integrating La@TeX{} and music
170 La@TeX{} is the de-facto standard for publishing layouts in the exact
171 sciences. It is built on top of the @TeX{} typesetting engine,
172 providing the best typography available anywhere.
175 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
176 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
179 Music is entered using
182 \begin[options,go,here]@{lilypond@}
191 \lilypondfile[options,go,here]@{@var{filename}@}
198 \lilypond@{ YOUR LILYPOND CODE @}
201 Running @command{lilypond-book} yields a file that can be further
202 processed with La@TeX{}.
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 line width 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{line-width} music fragment option.
243 @cindex titling and lilypond-book
244 @funindex \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.
257 The default is to simply insert a @code{\linebreak}.
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 -o -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 If you are running latex in twocolumn mode, remember to add
312 @code{-t landscape} to the dvips options.
314 @cindex international characters
317 Sometimes it is useful to display music elements (such as ties and slurs)
318 as if they continued after the end of the fragment. This can be done by
319 breaking the staff and suppressing inclusion of the rest of the lilypond
322 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
323 inclusion of other systems is terminated once the required number of
324 systems are included. Since @code{\betweenLilypondSystem} is first
325 called @b{after} the first system, including only the first system
329 \def\betweenLilyPondSystem#1@{\endinput@}
331 \begin[fragment]@{lilypond@}
332 c'1\( e'( c'~ \break c' d) e f\)
336 If a greater number of systems is requested, a TeX conditional must be
337 used before the @code{\endinput}. In this example, replace "2" by
338 the numer of systems you want in the output,
341 \def\betweenLilyPondSystem#1@{
342 \ifnum##1<2\else\endinput\fi
346 Remember that the definition of @code{\betweenLilyPondSystem} is
347 effective until @TeX{} quits the current group (such as the La@TeX{}
348 environment) or is overridden by another definition (which is, in
349 most cases, for the rest of the document). To reset your
353 \let\betweenLilyPondSystem\undefined
357 in your LaTeX source.
359 This may be simplified by defining a @TeX{} macro
362 \def\onlyFirstNSystems#1@{
363 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
368 and then saying only how many systems you want before each fragment,
371 \onlyFirstNSystems@{3@}
372 \begin@{lilypond@}...\end@{lilypond@}
373 \onlyFirstNSystems@{1@}
374 \begin@{lilypond@}...\end@{lilypond@}
378 @node Integrating Texinfo and music
379 @section Integrating Texinfo and music
381 Texinfo is the standard format for documentation of the GNU project. An
382 example of a Texinfo document is this manual. The HTML, PDF, and Info
383 versions of the manual are made from the Texinfo document.
385 In the input file, music is specified with
388 @@lilypond[options,go,here]
397 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
404 @@lilypondfile[options,go,here]@{@var{filename}@}
407 When @command{lilypond-book} is run on it, this results in a Texinfo
408 file (with extension @file{.texi}) containing @code{@@image} tags for
409 HTML and info output. For the printed edition, the raw @TeX{} output of
410 LilyPond is included in the main document.
412 We show two simple examples here. A @code{lilypond} environment
430 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
436 @lilypond[fragment,staffsize=11]{<c' e' g'>}
438 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
439 in-line image. It always gets a paragraph of its own.
441 When using the Texinfo output format, @command{lilypond-book} also
442 generates bitmaps of the music (in PNG format), so you can make an HTML
443 document with embedded music.
446 @node Integrating HTML and music
447 @section Integrating HTML and music
449 Music is entered using
452 <lilypond fragment relative=2>
453 \key c \minor c4 es g2
458 @command{lilypond-book} then produces an HTML file with appropriate image
459 tags for the music fragments:
461 @lilypond[fragment,relative=2]
462 \key c \minor c4 es g2
465 For inline pictures, use @code{<lilypond ... />}, where the options
466 are separated by a colon from the music, for example
469 Some music in <lilypond relative=2: a b c/> a line of text.
472 To include separate files, say
475 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
478 @cindex titling in HTML
479 @cindex preview image
482 @node Integrating DocBook and music
483 @section Integrating DocBook and music
485 For inserting LilyPond snippets it is good to keep the conformity of
486 our DocBook document, thus allowing us to use DocBook editors,
487 validation etc. So we don't use custom tags, only specify a convention
488 based on the standard DocBook elements.
490 @unnumberedsubsec Common conventions
492 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
493 formatted inline or not inline.
494 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
495 chosen to allow DocBook editors format the content gracefully.
496 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
498 @unnumberedsubsec Including a LilyPond file
500 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},
501 with the following structure:
506 <imagedata fileref="music1.ly" role="printfilename" />
511 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
513 @unnumberedsubsec Including LilyPond code
515 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
520 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
521 \context Staff \with @{
522 \remove Time_signature_engraver
523 \remove Clef_engraver@}
530 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.
532 @unnumberedsubsec Processing the DocBook document
534 Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
535 If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
536 For HTML (HTML Help, JavaHelp etc.) generation you can use the official DocBook XSL stylesheets, however, it is possible that you have to make some customization for it.
538 @node Music fragment options
539 @section Music fragment options
541 In the following, a ``LilyPond command'' refers to any command described
542 in the previous sections which is handled by @command{lilypond-book} to
543 produce a music snippet. For simplicity, LilyPond commands are only
544 shown in La@TeX{} syntax.
546 Note that the option string is parsed from left to right; if an option
547 occurs multiple times, the last one is taken.
549 The following options are available for LilyPond commands:
552 @item staffsize=@var{ht}
553 Set staff size to @var{ht}, which is measured in points.
556 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
557 = ##t} is added to the LilyPond snippet). This is the default for the
558 @code{\lilypond@{@}} command if no @code{line-width} option is present.
559 It is also the default for the @code{lilypond} environment if the
560 @code{fragment} option is set, and no line width is explicitly
564 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
565 to the LilyPond snippet).
568 @itemx line-width=@var{size}\@var{unit}
569 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
570 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
571 @code{pt}. This option affects LilyPond output (this is, the staff
572 length of the music snippet), not the text layout.
574 If used without an argument, set line width to a default value (as
575 computed with a heuristic algorithm).
577 If no @code{line-width} option is given, @command{lilypond-book} tries to
578 guess a default for @code{lilypond} environments which don't use the
579 @code{ragged-right} option.
582 Do not print the time signature, and turns off the timing (key signature,
583 bar lines) in the score.
586 Make @command{lilypond-book} add some boilerplate code so that you can
594 without @code{\layout}, @code{\score}, etc.
597 Don't add additional code to complete LilyPond code in music snippets.
598 Since this is the default, @code{nofragment} is redundant normally.
600 @item indent=@var{size}\@var{unit}
601 Set indentation of the first music system to @var{size}, using
602 @var{unit} as units. @var{unit} is one of the following strings:
603 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
604 LilyPond, not the text layout.
607 Set indentation of the first music system to zero. This option affects
608 LilyPond, not the text layout. Since no indentation is the default,
609 @code{noindent} is redundant normally.
612 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
613 the output into a quotation block. The value `0.4@dmn{in}' can be
614 controlled with the @code{exampleindent} option.
617 Set the amount by which the @code{quote} option indents a music snippet.
620 @itemx relative=@var{n}
621 Use relative octave mode. By default, notes are specified relative to
622 middle@tie{}C. The optional integer argument specifies the octave of
623 the starting note, where the default @code{1} is middle C.
626 LilyPond also uses @command{lilypond-book} to produce its own
627 documentation. To do that, some more obscure music fragment options are
632 The argument of a LilyPond command is copied to the output file and
633 enclosed in a verbatim block, followed by any text given with the
634 @code{intertext} option (not implemented yet); then the actual music is
635 displayed. This option does not work well with @code{\lilypond@{@}} if
636 it is part of a paragraph.
639 (Only for Texinfo output.) If @command{lilypond} is called with the
640 @option{--header=@/texidoc} option, and the file to be processed is
641 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
642 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
643 option makes @command{lilypond-book} include such files, adding its
644 contents as a documentation block right before the music snippet.
646 Assuming the file @file{foo@/.ly} contains
650 texidoc = "This file demonstrates a single note."
656 and we have this in our Texinfo document @file{test.texinfo}
659 @@lilypondfile[texidoc]@{foo.ly@}
663 the following command line gives the expected result
666 lilypond-book --process="lilypond --format=tex --tex \
667 --header=texidoc test.texinfo
670 Most LilyPond test documents (in the @file{input} directory of the
671 distribution) are small @file{.ly} files which look exactly like this.
674 If a LilyPond input file is included with @code{\lilypondfile}, print
675 the file name right before the music snippet. For HTML output, this is
679 This option includes fonts in all of the generated EPS-files for this
680 snippet. This should be used if the snippet uses any font that LaTeX
681 cannot find on its own.
686 @node Invoking lilypond-book
687 @section Invoking @command{lilypond-book}
689 @command{lilypond-book} produces a file with one of the following
690 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
691 output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
694 @command{lilypond-book} can also create a PSFONTS file, which is required
695 by @command{dvips} to produce Postscript and PDF files.
697 To produce PDF output from the lilypond-book file (here called
698 @code{yourfile.lytex}) via LaTeX, you should do
701 lilypond-book --psfonts yourfile.lytex
703 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
707 The @file{.dvi} file created by this process will not contain
708 noteheads. This is normal; if you follow the instructions, they
709 will be included in the @file{.ps} and @file{.pdf} files.
711 To produce a PDF file through PDF(La)TeX, use
714 lilypond-book --pdf yourfile.pdftex
715 pdflatex yourfile.tex
719 To produce a Texinfo document (in any output format), follow the normal
720 procedures for Texinfo (this is, either call @command{texi2dvi} or
721 @command{makeinfo}, depending on the output format you want to
724 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
725 an Info File, , , texinfo, GNU Texinfo}.
728 See the documentation of Texinfo for further details.
732 @command{lilypond-book} accepts the following command line options:
735 @item -f @var{format}
736 @itemx --format=@var{format}
737 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
738 @command{lilypond-book} tries to detect the format automatically.
740 The @code{texi} document type produces a Texinfo file with music
741 fragments in the DVI output only. For getting images in the HTML
742 version, the format @code{texi-html} must be used instead.
744 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
746 @item -F @var{filter}
747 @itemx --filter=@var{filter}
748 Pipe snippets through @var{filter}. @code{lilypond-book} will
749 not --filter and --process at the same time.
753 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
758 Print a short help message.
761 @itemx --include=@var{dir}
762 Add @var{dir} to the include path.
765 @itemx --output=@var{dir}
766 Place generated files in directory @var{dir}. Running
767 @command{lilypond-book} generates lots of small files that LilyPond will
768 process. To avoid all that garbage in the source directory use the
769 @option{--output} command line option, and change to that directory
770 before running @command{latex} or @command{makeinfo}:
773 lilypond-book --output=out yourfile.lytex
778 @itemx --padding=@var{amount}
779 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
780 and is 3.0 by default. This option should be used if the lines of
781 music stick out of the right margin.
783 The width of a tightly clipped systems can vary, due to notation
784 elements that stick into the left margin, such as bar numbers and
785 instrument names. This option will shorten each line and move each
786 line to the right by the same amount.
789 @item -P @var{process}
790 @itemx --process=@var{command}
791 Process LilyPond snippets using @var{command}. The default command is
792 @code{lilypond}. @code{lilypond-book} will not --filter and --process
796 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
797 This is necessary for @command{dvips -h @var{file}.psfonts}.
805 Print version information.
810 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
811 La@TeX{} commands that change margins and line widths after the preamble
814 Only the first @code{\score} of a LilyPond block is processed.
817 @node Filename extensions
818 @section Filename extensions
820 You can use any filename extension for the input file, but if you do not
821 use the recommended extension for a particular format you may need to
822 manually specify the output format. @xref{Invoking lilypond-book}, for
823 details. Otherwise, @command{lilypond-book} automatically selects the
824 output format based on the input filename's extension.
827 @multitable @columnfractions .2 .5
828 @item @strong{extension} @tab @strong{output format}
830 @item @file{.html} @tab HTML
831 @item @file{.itely} @tab Texinfo
832 @item @file{.latex} @tab La@TeX{}
833 @item @file{.lytex} @tab La@TeX{}
834 @item @file{.lyxml} @tab DocBook
835 @item @file{.tely} @tab Texinfo
836 @item @file{.tex} @tab La@TeX{}
837 @item @file{.texi} @tab Texinfo
838 @item @file{.texinfo} @tab Texinfo
839 @item @file{.xml} @tab HTML
844 @node Many quotes of a large score
845 @section Many quotes of a large score
847 If you need to quote many fragments of a large score, you can also use
848 the clip systems feature, see @ref{Extracting fragments of notation}.
852 @n ode Inserting LilyPond output into OpenOffice.org
853 @s ection Inserting LilyPond output into OpenOffice.org
855 @c index OpenOffice.org
857 LilyPond notation can be added to OpenOffice.org with
858 @u ref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
863 @node Inserting LilyPond output into other programs
864 @section Inserting LilyPond output into other programs
866 To insert LilyPond output in other programs, use @code{lilypond}
867 instead of @code{lilypond-book}. Each example must be created
868 individually and added to the document; consult the documentation for
869 that program. Most programs will be able to insert lilypond output in
870 @file{PNG}, @file{EPS}, or @file{PDF} formats.
872 To reduce the white space around your lilypond score, use
873 the following options
881 bookTitleMarkup = ##f
882 scoreTitleMarkup = ##f
888 To produce a useful @file{eps} file, use
891 lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly