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 OpenOffice.org::
44 * Inserting LilyPond output into other programs::
48 @node An example of a musicological document
49 @section An example of a musicological document
52 @cindex La@TeX{}, music in
53 @cindex HTML, music in
54 @cindex Texinfo, music in
55 @cindex DocBook, music in
56 Some texts contain music examples. These texts are musicological
57 treatises, songbooks, or manuals like this. Such texts can be made by
58 hand, simply by importing a PostScript figure into the word processor.
59 However, there is an automated procedure to reduce the amount of work
60 involved in HTML, La@TeX{}, Texinfo and DocBook documents.
62 A script called @code{lilypond-book} will extract the music fragments,
63 format them, and put back the resulting notation. Here we show a small
64 example for use with La@TeX{}. The example also contains explanatory
65 text, so we will not comment on it further.
69 \documentclass[a4paper]{article}
73 Documents for @command{lilypond-book} may freely mix music and text.
78 c2 g'2 \times 2/3 { f8 e d } c'2 g4
82 Options are put in brackets.
84 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
88 Larger examples can be put into a separate file, and introduced with
91 \lilypondfile[quote,noindent]{screech-boink.ly}
97 Under Unix, you can view the results as follows
102 lilypond-book --output=out --psfonts lilybook.tex
103 @emph{lilypond-book (GNU LilyPond) 2.6.0}
104 @emph{Reading lilybook.tex...}
105 @emph{..lots of stuff deleted..}
106 @emph{Compiling out/lilybook.tex...}
109 @emph{lots of stuff deleted}
113 To convert the file into a PDF document, run the following commands
116 dvips -o -Ppdf -h lilybook.psfonts lilybook
120 If you are running latex in twocolumn mode, remember to add
121 @code{-t landscape} to the dvips options.
123 Running @command{lilypond-book} and @command{latex} creates a lot of
124 temporary files, which would clutter up the working directory. To
125 remedy this, use the @code{--output=@var{dir}} option. It will create
126 the files in a separate subdirectory @file{dir}.
128 Running dvips will produce many warnings about fonts. They are not
129 harmful; please ignore them.
131 Finally the result of the La@TeX{} example shown above.@footnote{This
132 tutorial is processed with Texinfo, so the example gives slightly
133 different results in layout.} This finishes the tutorial section.
137 Documents for @command{lilypond-book} may freely mix music and text.
142 c2 g'2 \times 2/3 { f8 e d } c'2 g4
146 Options are put in brackets.
148 @lilypond[fragment,quote,staffsize=26,verbatim]
152 Larger examples can be put into a separate file, and introduced with
153 @code{\lilypondfile}.
155 @lilypondfile[quote,noindent]{screech-boink.ly}
165 @cindex documents, adding music to
168 @node Integrating LaTeX and music
169 @section Integrating La@TeX{} and music
171 La@TeX{} is the de-facto standard for publishing layouts in the exact
172 sciences. It is built on top of the @TeX{} typesetting engine,
173 providing the best typography available anywhere.
176 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
177 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
180 Music is entered using
183 \begin[options,go,here]@{lilypond@}
192 \lilypondfile[options,go,here]@{@var{filename}@}
199 \lilypond@{ YOUR LILYPOND CODE @}
202 Running @command{lilypond-book} yields a file that can be further
203 processed with La@TeX{}.
205 We show some examples here. The lilypond environment
208 \begin[quote,fragment,staffsize=26]@{lilypond@}
216 @lilypond[quote,fragment,staffsize=26]
223 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
229 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
232 Currently, you cannot include @code{@{} or @code{@}} within
233 @code{\lilypond@{@}}, so this command is only useful with the
234 @code{fragment} option.
236 The default line width of the music will be adjusted by examining the
237 commands in the document preamble, the part of the document before
238 @code{\begin@{document@}}. The @command{lilypond-book} command sends
239 these to La@TeX{} to find out how wide the text is. The line width for
240 the music fragments is then adjusted to the text width. Note that this
241 heuristic algorithm can fail easily; in such cases it is necessary to
242 use the @code{line-width} music fragment option.
244 @cindex titling and lilypond-book
245 @funindex \header in La@TeX{} documents
247 Each snippet will call the following macros if they have been defined by
250 @code{\preLilyPondExample} called before the music
252 @code{\postLilyPondExample} called after the music
254 @code{\betweenLilyPondSystem[1]} is called between systems if
255 @code{lilypond-book} has split the snippet into several postscript
256 files. It must be defined as taking one parameter and will be
257 passed the number of files already included in this snippet.
258 The default is to simply insert a @code{\linebreak}.
263 @cindex Latex, feta symbols
266 To include feta symbols (such as flat, segno, etc) in a LaTeX
267 document, use @code{\input@{titledefs@}}
270 \documentclass[a4paper]@{article@}
281 The font symbol names are defined in the file feta20.tex; to find
282 the location of this file, use the command
290 @cindex outline fonts
293 @cindex invoking dvips
295 For printing the La@TeX{} document you need a DVI to PostScript
296 translator like @command{dvips}. To use @command{dvips} to produce
297 a PostScript file, add the following options to the @command{dvips}
301 -o -Ppdf -h @var{file}.psfonts
305 where the @var{file}@command{psfonts} file is obtained from
306 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
307 can then be produced with a PostScript to PDF translator like
308 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
309 will produce some warnings about fonts; these are harmless and may
312 If you are running latex in twocolumn mode, remember to add
313 @code{-t landscape} to the dvips options.
315 @cindex international characters
318 Sometimes it is useful to display music elements (such as ties and slurs)
319 as if they continued after the end of the fragment. This can be done by
320 breaking the staff and suppressing inclusion of the rest of the lilypond
323 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
324 inclusion of other systems is terminated once the required number of
325 systems are included. Since @code{\betweenLilypondSystem} is first
326 called @b{after} the first system, including only the first system
330 \def\betweenLilyPondSystem#1@{\endinput@}
332 \begin[fragment]@{lilypond@}
333 c'1\( e'( c'~ \break c' d) e f\)
337 If a greater number of systems is requested, a TeX conditional must be
338 used before the @code{\endinput}. In this example, replace "2" by
339 the numer of systems you want in the output,
342 \def\betweenLilyPondSystem#1@{
343 \ifnum##1<2\else\endinput\fi
347 Remember that the definition of @code{\betweenLilyPondSystem} is
348 effective until @TeX{} quits the current group (such as the La@TeX{}
349 environment) or is overridden by another definition (which is, in
350 most cases, for the rest of the document). To reset your
354 \let\betweenLilyPondSystem\undefined
358 in your LaTeX source.
360 This may be simplified by defining a @TeX{} macro
363 \def\onlyFirstNSystems#1@{
364 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
369 and then saying only how many systems you want before each fragment,
372 \onlyFirstNSystems@{3@}
373 \begin@{lilypond@}...\end@{lilypond@}
374 \onlyFirstNSystems@{1@}
375 \begin@{lilypond@}...\end@{lilypond@}
379 @node Integrating Texinfo and music
380 @section Integrating Texinfo and music
382 Texinfo is the standard format for documentation of the GNU project. An
383 example of a Texinfo document is this manual. The HTML, PDF, and Info
384 versions of the manual are made from the Texinfo document.
386 In the input file, music is specified with
389 @@lilypond[options,go,here]
398 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
405 @@lilypondfile[options,go,here]@{@var{filename}@}
408 When @command{lilypond-book} is run on it, this results in a Texinfo
409 file (with extension @file{.texi}) containing @code{@@image} tags for
410 HTML and info output. For the printed edition, the raw @TeX{} output of
411 LilyPond is included in the main document.
413 We show two simple examples here. A @code{lilypond} environment
431 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
437 @lilypond[fragment,staffsize=11]{<c' e' g'>}
439 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
440 in-line image. It always gets a paragraph of its own.
442 When using the Texinfo output format, @command{lilypond-book} also
443 generates bitmaps of the music (in PNG format), so you can make an HTML
444 document with embedded music.
447 @node Integrating HTML and music
448 @section Integrating HTML and music
450 Music is entered using
453 <lilypond fragment relative=2>
454 \key c \minor c4 es g2
459 @command{lilypond-book} then produces an HTML file with appropriate image
460 tags for the music fragments:
462 @lilypond[fragment,relative=2]
463 \key c \minor c4 es g2
466 For inline pictures, use @code{<lilypond ... />}, where the options
467 are separated by a colon from the music, for example
470 Some music in <lilypond relative=2: a b c/> a line of text.
473 To include separate files, say
476 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
479 @cindex titling in HTML
480 @cindex preview image
483 @node Integrating DocBook and music
484 @section Integrating DocBook and music
486 For inserting LilyPond snippets it is good to keep the conformity of
487 our DocBook document, thus allowing us to use DocBook editors,
488 validation etc. So we don't use custom tags, only specify a convention
489 based on the standard DocBook elements.
491 @unnumberedsubsec Common conventions
493 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
494 formatted inline or not inline.
495 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
496 chosen to allow DocBook editors format the content gracefully.
497 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
499 @unnumberedsubsec Including a LilyPond file
501 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},
502 with the following structure:
507 <imagedata fileref="music1.ly" role="printfilename" />
512 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
514 @unnumberedsubsec Including LilyPond code
516 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
521 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
522 \context Staff \with @{
523 \remove Time_signature_engraver
524 \remove Clef_engraver@}
531 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.
533 @unnumberedsubsec Processing the DocBook document
535 Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
536 If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
537 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.
539 @node Music fragment options
540 @section Music fragment options
542 In the following, a ``LilyPond command'' refers to any command described
543 in the previous sections which is handled by @command{lilypond-book} to
544 produce a music snippet. For simplicity, LilyPond commands are only
545 shown in La@TeX{} syntax.
547 Note that the option string is parsed from left to right; if an option
548 occurs multiple times, the last one is taken.
550 The following options are available for LilyPond commands:
553 @item staffsize=@var{ht}
554 Set staff size to @var{ht}, which is measured in points.
557 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
558 = ##t} is added to the LilyPond snippet). This is the default for the
559 @code{\lilypond@{@}} command if no @code{line-width} option is present.
560 It is also the default for the @code{lilypond} environment if the
561 @code{fragment} option is set, and no line width is explicitly
565 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
566 to the LilyPond snippet).
569 @itemx line-width=@var{size}\@var{unit}
570 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
571 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
572 @code{pt}. This option affects LilyPond output (this is, the staff
573 length of the music snippet), not the text layout.
575 If used without an argument, set line width to a default value (as
576 computed with a heuristic algorithm).
578 If no @code{line-width} option is given, @command{lilypond-book} tries to
579 guess a default for @code{lilypond} environments which don't use the
580 @code{ragged-right} option.
583 Do not print the time signature, and turns off the timing (key signature,
584 bar lines) in the score.
587 Make @command{lilypond-book} add some boilerplate code so that you can
595 without @code{\layout}, @code{\score}, etc.
598 Don't add additional code to complete LilyPond code in music snippets.
599 Since this is the default, @code{nofragment} is redundant normally.
601 @item indent=@var{size}\@var{unit}
602 Set indentation of the first music system to @var{size}, using
603 @var{unit} as units. @var{unit} is one of the following strings:
604 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
605 LilyPond, not the text layout.
608 Set indentation of the first music system to zero. This option affects
609 LilyPond, not the text layout. Since no indentation is the default,
610 @code{noindent} is redundant normally.
613 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
614 the output into a quotation block. The value `0.4@dmn{in}' can be
615 controlled with the @code{exampleindent} option.
618 Set the amount by which the @code{quote} option indents a music snippet.
621 @itemx relative=@var{n}
622 Use relative octave mode. By default, notes are specified relative to
623 middle@tie{}C. The optional integer argument specifies the octave of
624 the starting note, where the default @code{1} is middle C.
627 LilyPond also uses @command{lilypond-book} to produce its own
628 documentation. To do that, some more obscure music fragment options are
633 The argument of a LilyPond command is copied to the output file and
634 enclosed in a verbatim block, followed by any text given with the
635 @code{intertext} option (not implemented yet); then the actual music is
636 displayed. This option does not work well with @code{\lilypond@{@}} if
637 it is part of a paragraph.
640 (Only for Texinfo output.) If @command{lilypond} is called with the
641 @option{--header=@/texidoc} option, and the file to be processed is
642 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
643 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
644 option makes @command{lilypond-book} include such files, adding its
645 contents as a documentation block right before the music snippet.
647 Assuming the file @file{foo@/.ly} contains
651 texidoc = "This file demonstrates a single note."
657 and we have this in our Texinfo document @file{test.texinfo}
660 @@lilypondfile[texidoc]@{foo.ly@}
664 the following command line gives the expected result
667 lilypond-book --process="lilypond --format=tex --tex \
668 --header=texidoc test.texinfo
671 Most LilyPond test documents (in the @file{input} directory of the
672 distribution) are small @file{.ly} files which look exactly like this.
675 If a LilyPond input file is included with @code{\lilypondfile}, print
676 the file name right before the music snippet. For HTML output, this is
680 This option includes fonts in all of the generated EPS-files for this
681 snippet. This should be used if the snippet uses any font that LaTeX
682 cannot find on its own.
687 @node Invoking lilypond-book
688 @section Invoking @command{lilypond-book}
690 @command{lilypond-book} produces a file with one of the following
691 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
692 output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
695 @command{lilypond-book} can also create a PSFONTS file, which is required
696 by @command{dvips} to produce Postscript and PDF files.
698 To produce PDF output from the lilypond-book file (here called
699 @code{yourfile.lytex}) via LaTeX, you should do
702 lilypond-book --psfonts yourfile.lytex
704 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
708 The @file{.dvi} file created by this process will not contain
709 noteheads. This is normal; if you follow the instructions, they
710 will be included in the @file{.ps} and @file{.pdf} files.
712 To produce a PDF file through PDF(La)TeX, use
715 lilypond-book --pdf yourfile.pdftex
716 pdflatex yourfile.tex
720 To produce a Texinfo document (in any output format), follow the normal
721 procedures for Texinfo (this is, either call @command{texi2dvi} or
722 @command{makeinfo}, depending on the output format you want to
725 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
726 an Info File, , , texinfo, GNU Texinfo}.
729 See the documentation of Texinfo for further details.
733 @command{lilypond-book} accepts the following command line options:
736 @item -f @var{format}
737 @itemx --format=@var{format}
738 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
739 @command{lilypond-book} tries to detect the format automatically.
741 The @code{texi} document type produces a Texinfo file with music
742 fragments in the DVI output only. For getting images in the HTML
743 version, the format @code{texi-html} must be used instead.
745 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
747 @item -F @var{filter}
748 @itemx --filter=@var{filter}
749 Pipe snippets through @var{filter}. @code{lilypond-book} will
750 not --filter and --process at the same time.
754 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
759 Print a short help message.
762 @itemx --include=@var{dir}
763 Add @var{dir} to the include path.
766 @itemx --output=@var{dir}
767 Place generated files in directory @var{dir}. Running
768 @command{lilypond-book} generates lots of small files that LilyPond will
769 process. To avoid all that garbage in the source directory use the
770 @option{--output} command line option, and change to that directory
771 before running @command{latex} or @command{makeinfo}:
774 lilypond-book --output=out yourfile.lytex
779 @itemx --padding=@var{amount}
780 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
781 and is 3.0 by default. This option should be used if the lines of
782 music stick out of the right margin.
784 The width of a tightly clipped systems can vary, due to notation
785 elements that stick into the left margin, such as bar numbers and
786 instrument names. This option will shorten each line and move each
787 line to the right by the same amount.
790 @item -P @var{process}
791 @itemx --process=@var{command}
792 Process LilyPond snippets using @var{command}. The default command is
793 @code{lilypond}. @code{lilypond-book} will not --filter and --process
797 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
798 This is necessary for @command{dvips -h @var{file}.psfonts}.
806 Print version information.
811 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
812 La@TeX{} commands that change margins and line widths after the preamble
815 Only the first @code{\score} of a LilyPond block is processed.
818 @node Filename extensions
819 @section Filename extensions
821 You can use any filename extension for the input file, but if you do not
822 use the recommended extension for a particular format you may need to
823 manually specify the output format. @xref{Invoking lilypond-book}, for
824 details. Otherwise, @command{lilypond-book} automatically selects the
825 output format based on the input filename's extension.
828 @multitable @columnfractions .2 .5
829 @item @strong{extension} @tab @strong{output format}
831 @item @file{.html} @tab HTML
832 @item @file{.itely} @tab Texinfo
833 @item @file{.latex} @tab La@TeX{}
834 @item @file{.lytex} @tab La@TeX{}
835 @item @file{.lyxml} @tab DocBook
836 @item @file{.tely} @tab Texinfo
837 @item @file{.tex} @tab La@TeX{}
838 @item @file{.texi} @tab Texinfo
839 @item @file{.texinfo} @tab Texinfo
840 @item @file{.xml} @tab HTML
845 @node Many quotes of a large score
846 @section Many quotes of a large score
848 If you need to quote many fragments of a large score, you can also use
849 the clip systems feature, see @ref{Extracting fragments of notation}.
852 @node Inserting LilyPond output into OpenOffice.org
853 @section Inserting LilyPond output into OpenOffice.org
855 @cindex OpenOffice.org
857 LilyPond notation can be added to OpenOffice.org with
858 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
861 @node Inserting LilyPond output into other programs
862 @section Inserting LilyPond output into other programs
864 To insert LilyPond output in other programs, use @code{lilypond}
865 instead of @code{lilypond-book}. Each example must be created
866 individually and added to the document; consult the documentation for
867 that program. Most programs will be able to insert lilypond output in
868 @file{PNG}, @file{EPS}, or @file{PDF} formats.
870 To reduce the white space around your lilypond score, use
871 the following options
879 bookTitleMarkup = ##f
880 scoreTitleMarkup = ##f
886 To produce a useful @file{eps} file, use
889 lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly