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 Running @command{lilypond-book} and @command{latex} creates a lot of
120 temporary files, which would clutter up the working directory. To
121 remedy this, use the @code{--output=@var{dir}} option. It will create
122 the files in a separate subdirectory @file{dir}.
124 Running dvips will produce many warnings about fonts. They are not
125 harmful; please ignore them.
127 Finally the result of the La@TeX{} example shown above.@footnote{This
128 tutorial is processed with Texinfo, so the example gives slightly
129 different results in layout.} This finishes the tutorial section.
133 Documents for @command{lilypond-book} may freely mix music and text.
138 c2 g'2 \times 2/3 { f8 e d } c'2 g4
142 Options are put in brackets.
144 @lilypond[fragment,quote,staffsize=26,verbatim]
148 Larger examples can be put into a separate file, and introduced with
149 @code{\lilypondfile}.
151 @lilypondfile[quote,noindent]{screech-boink.ly}
161 @cindex documents, adding music to
164 @node Integrating LaTeX and music
165 @section Integrating La@TeX{} and music
167 La@TeX{} is the de-facto standard for publishing layouts in the exact
168 sciences. It is built on top of the @TeX{} typesetting engine,
169 providing the best typography available anywhere.
172 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
173 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
176 Music is entered using
179 \begin[options,go,here]@{lilypond@}
188 \lilypondfile[options,go,here]@{@var{filename}@}
195 \lilypond@{ YOUR LILYPOND CODE @}
198 Running @command{lilypond-book} yields a file that can be further
199 processed with La@TeX{}.
201 We show some examples here. The lilypond environment
204 \begin[quote,fragment,staffsize=26]@{lilypond@}
212 @lilypond[quote,fragment,staffsize=26]
219 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
225 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
228 Currently, you cannot include @code{@{} or @code{@}} within
229 @code{\lilypond@{@}}, so this command is only useful with the
230 @code{fragment} option.
232 The default line width of the music will be adjusted by examining the
233 commands in the document preamble, the part of the document before
234 @code{\begin@{document@}}. The @command{lilypond-book} command sends
235 these to La@TeX{} to find out how wide the text is. The line width for
236 the music fragments is then adjusted to the text width. Note that this
237 heuristic algorithm can fail easily; in such cases it is necessary to
238 use the @code{line-width} music fragment option.
240 @cindex titling and lilypond-book
241 @funindex \header in La@TeX{} documents
243 Each snippet will call the following macros if they have been defined by
246 @code{\preLilyPondExample} called before the music
248 @code{\postLilyPondExample} called after the music
250 @code{\betweenLilyPondSystem[1]} is called between systems if
251 @code{lilypond-book} has split the snippet into several postscript
252 files. It must be defined as taking one parameter and will be
253 passed the number of files already included in this snippet.
254 The default is to simply insert a @code{\linebreak}.
259 @cindex Latex, feta symbols
262 To include feta symbols (such as flat, segno, etc) in a LaTeX
263 document, use @code{\input@{titledefs@}}
266 \documentclass[a4paper]@{article@}
277 The font symbol names are defined in the file feta20.tex; to find
278 the location of this file, use the command
286 @cindex outline fonts
289 @cindex invoking dvips
291 For printing the La@TeX{} document you need a DVI to PostScript
292 translator like @command{dvips}. To use @command{dvips} to produce
293 a PostScript file, add the following options to the @command{dvips}
297 -o -Ppdf -h @var{file}.psfonts
301 where the @var{file}@command{psfonts} file is obtained from
302 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
303 can then be produced with a PostScript to PDF translator like
304 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
305 will produce some warnings about fonts; these are harmless and may
308 @cindex international characters
311 Sometimes it is useful to display music elements (such as ties and slurs)
312 as if they continued after the end of the fragment. This can be done by
313 breaking the staff and suppressing inclusion of the rest of the lilypond
316 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
317 inclusion of other systems is terminated once the required number of
318 systems are included. Since @code{\betweenLilypondSystem} is first
319 called @b{after} the first system, including only the first system
323 \def\betweenLilyPondSystem#1@{\endinput@}
325 \begin[fragment]@{lilypond@}
326 c'1\( e'( c'~ \break c' d) e f\)
330 If a greater number of systems is requested, a TeX conditional must be
331 used before the @code{\endinput}. In this example, replace "2" by
332 the numer of systems you want in the output,
335 \def\betweenLilyPondSystem#1@{
336 \ifnum##1<2\else\endinput\fi
340 Remember that the definition of @code{\betweenLilyPondSystem} is
341 effective until @TeX{} quits the current group (such as the La@TeX{}
342 environment) or is overridden by another definition (which is, in
343 most cases, for the rest of the document). To reset your
347 \let\betweenLilyPondSystem\undefined
351 in your LaTeX source.
353 This may be simplified by defining a @TeX{} macro
356 \def\onlyFirstNSystems#1@{
357 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
362 and then saying only how many systems you want before each fragment,
365 \onlyFirstNSystems@{3@}
366 \begin@{lilypond@}...\end@{lilypond@}
367 \onlyFirstNSystems@{1@}
368 \begin@{lilypond@}...\end@{lilypond@}
372 @node Integrating Texinfo and music
373 @section Integrating Texinfo and music
375 Texinfo is the standard format for documentation of the GNU project. An
376 example of a Texinfo document is this manual. The HTML, PDF, and Info
377 versions of the manual are made from the Texinfo document.
379 In the input file, music is specified with
382 @@lilypond[options,go,here]
391 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
398 @@lilypondfile[options,go,here]@{@var{filename}@}
401 When @command{lilypond-book} is run on it, this results in a Texinfo
402 file (with extension @file{.texi}) containing @code{@@image} tags for
403 HTML and info output. For the printed edition, the raw @TeX{} output of
404 LilyPond is included in the main document.
406 We show two simple examples here. A @code{lilypond} environment
424 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
430 @lilypond[fragment,staffsize=11]{<c' e' g'>}
432 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
433 in-line image. It always gets a paragraph of its own.
435 When using the Texinfo output format, @command{lilypond-book} also
436 generates bitmaps of the music (in PNG format), so you can make an HTML
437 document with embedded music.
440 @node Integrating HTML and music
441 @section Integrating HTML and music
443 Music is entered using
446 <lilypond fragment relative=2>
447 \key c \minor c4 es g2
452 @command{lilypond-book} then produces an HTML file with appropriate image
453 tags for the music fragments:
455 @lilypond[fragment,relative=2]
456 \key c \minor c4 es g2
459 For inline pictures, use @code{<lilypond ... />}, where the options
460 are separated by a colon from the music, for example
463 Some music in <lilypond relative=2: a b c/> a line of text.
466 To include separate files, say
469 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
472 @cindex titling in HTML
473 @cindex preview image
476 @node Integrating DocBook and music
477 @section Integrating DocBook and music
479 For inserting LilyPond snippets it is good to keep the conformity of
480 our DocBook document, thus allowing us to use DocBook editors,
481 validation etc. So we don't use custom tags, only specify a convention
482 based on the standard DocBook elements.
484 @unnumberedsubsec Common conventions
486 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
487 formatted inline or not inline.
488 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
489 chosen to allow DocBook editors format the content gracefully.
490 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
492 @unnumberedsubsec Including a LilyPond file
494 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},
495 with the following structure:
500 <imagedata fileref="music1.ly" role="printfilename" />
505 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
507 @unnumberedsubsec Including LilyPond code
509 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
514 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
515 \context Staff \with @{
516 \remove Time_signature_engraver
517 \remove Clef_engraver@}
524 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.
526 @unnumberedsubsec Processing the DocBook document
528 Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
529 If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
530 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.
532 @node Music fragment options
533 @section Music fragment options
535 In the following, a ``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 La@TeX{} 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., @code{ragged-right
551 = ##t} is added to the LilyPond snippet). This is the default for the
552 @code{\lilypond@{@}} command if no @code{line-width} option is present.
553 It is also the default for the @code{lilypond} environment if the
554 @code{fragment} option is set, and no line width is explicitly
558 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
559 to the LilyPond snippet).
562 @itemx line-width=@var{size}\@var{unit}
563 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
564 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
565 @code{pt}. This option affects LilyPond output (this is, the staff
566 length of the music snippet), not the text layout.
568 If used without an argument, set line width to a default value (as
569 computed with a heuristic algorithm).
571 If no @code{line-width} option is given, @command{lilypond-book} tries to
572 guess a default for @code{lilypond} environments which don't use the
573 @code{ragged-right} option.
576 Do not print the time signature, and turns off the timing (key signature,
577 bar lines) in the score.
580 Make @command{lilypond-book} add some boilerplate code so that you can
588 without @code{\layout}, @code{\score}, etc.
591 Don't add additional code to complete LilyPond code in music snippets.
592 Since this is the default, @code{nofragment} is redundant normally.
594 @item indent=@var{size}\@var{unit}
595 Set indentation of the first music system to @var{size}, using
596 @var{unit} as units. @var{unit} is one of the following strings:
597 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
598 LilyPond, not the text layout.
601 Set indentation of the first music system to zero. This option affects
602 LilyPond, not the text layout. Since no indentation is the default,
603 @code{noindent} is redundant normally.
606 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
607 the output into a quotation block. The value `0.4@dmn{in}' can be
608 controlled with the @code{exampleindent} option.
611 Set the amount by which the @code{quote} option indents a music snippet.
614 @itemx relative=@var{n}
615 Use relative octave mode. By default, notes are specified relative to
616 middle@tie{}C. The optional integer argument specifies the octave of
617 the starting note, where the default @code{1} is middle C.
620 LilyPond also uses @command{lilypond-book} to produce its own
621 documentation. To do that, some more obscure music fragment options are
626 The argument of a LilyPond command is copied to the output file and
627 enclosed in a verbatim block, followed by any text given with the
628 @code{intertext} option (not implemented yet); then the actual music is
629 displayed. This option does not work well with @code{\lilypond@{@}} if
630 it is part of a paragraph.
633 (Only for Texinfo output.) If @command{lilypond} is called with the
634 @option{--header=@/texidoc} option, and the file to be processed is
635 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
636 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
637 option makes @command{lilypond-book} include such files, adding its
638 contents as a documentation block right before the music snippet.
640 Assuming the file @file{foo@/.ly} contains
644 texidoc = "This file demonstrates a single note."
650 and we have this in our Texinfo document @file{test.texinfo}
653 @@lilypondfile[texidoc]@{foo.ly@}
657 the following command line gives the expected result
660 lilypond-book --process="lilypond --format=tex --tex \
661 --header=texidoc test.texinfo
664 Most LilyPond test documents (in the @file{input} directory of the
665 distribution) are small @file{.ly} files which look exactly like this.
668 If a LilyPond input file is included with @code{\lilypondfile}, print
669 the file name right before the music snippet. For HTML output, this is
673 This option includes fonts in all of the generated EPS-files for this
674 snippet. This should be used if the snippet uses any font that LaTeX
675 cannot find on its own.
680 @node Invoking lilypond-book
681 @section Invoking @command{lilypond-book}
683 @command{lilypond-book} produces a file with one of the following
684 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
685 output format. All of @file{.tex}, @file{.texi} and @{.xml} files need further
688 @command{lilypond-book} can also create a PSFONTS file, which is required
689 by @command{dvips} to produce Postscript and PDF files.
691 To produce PDF output from the lilypond-book file (here called
692 @code{yourfile.lytex}) via LaTeX, you should do
695 lilypond-book --psfonts yourfile.lytex
697 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
701 The @file{.dvi} file created by this process will not contain
702 noteheads. This is normal; if you follow the instructions, they
703 will be included in the @file{.ps} and @file{.pdf} files.
705 To produce a PDF file through PDF(La)TeX, use
708 lilypond-book --pdf yourfile.pdftex
709 pdflatex yourfile.tex
713 To produce a Texinfo document (in any output format), follow the normal
714 procedures for Texinfo (this is, either call @command{texi2dvi} or
715 @command{makeinfo}, depending on the output format you want to
718 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
719 an Info File, , , texinfo, GNU Texinfo}.
722 See the documentation of Texinfo for further details.
726 @command{lilypond-book} accepts the following command line options:
729 @item -f @var{format}
730 @itemx --format=@var{format}
731 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
732 @command{lilypond-book} tries to detect the format automatically.
734 The @code{texi} document type produces a Texinfo file with music
735 fragments in the DVI output only. For getting images in the HTML
736 version, the format @code{texi-html} must be used instead.
738 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
740 @item -F @var{filter}
741 @itemx --filter=@var{filter}
742 Pipe snippets through @var{filter}. @code{lilypond-book} will
743 not --filter and --process at the same time.
747 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
752 Print a short help message.
755 @itemx --include=@var{dir}
756 Add @var{dir} to the include path.
759 @itemx --output=@var{dir}
760 Place generated files in directory @var{dir}. Running
761 @command{lilypond-book} generates lots of small files that LilyPond will
762 process. To avoid all that garbage in the source directory use the
763 @option{--output} command line option, and change to that directory
764 before running @command{latex} or @command{makeinfo}:
767 lilypond-book --output=out yourfile.lytex
772 @item -P @var{process}
773 @itemx --process=@var{command}
774 Process LilyPond snippets using @var{command}. The default command is
775 @code{lilypond}. @code{lilypond-book} will not --filter and --process
779 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
780 This is necessary for @command{dvips -h @var{file}.psfonts}.
788 Print version information.
793 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
794 La@TeX{} commands that change margins and line widths after the preamble
797 Only the first @code{\score} of a LilyPond block is processed.
800 @node Filename extensions
801 @section Filename extensions
803 You can use any filename extension for the input file, but if you do not
804 use the recommended extension for a particular format you may need to
805 manually specify the output format. @xref{Invoking lilypond-book}, for
806 details. Otherwise, @command{lilypond-book} automatically selects the
807 output format based on the input filename's extension.
810 @multitable @columnfractions .2 .5
811 @item @strong{extension} @tab @strong{output format}
813 @item @file{.html} @tab HTML
814 @item @file{.itely} @tab Texinfo
815 @item @file{.latex} @tab La@TeX{}
816 @item @file{.lytex} @tab La@TeX{}
817 @item @file{.lyxml} @tab DocBook
818 @item @file{.tely} @tab Texinfo
819 @item @file{.tex} @tab La@TeX{}
820 @item @file{.texi} @tab Texinfo
821 @item @file{.texinfo} @tab Texinfo
822 @item @file{.xml} @tab HTML
826 @node Many quotes of a large score
827 @section Many quotes of a large score
829 If you need to quote many fragments of a large score, you can also use
830 the clip systems feature, see @ref{Extracting fragments of notation}.
832 @node Inserting LilyPond output into other programs
833 @section Inserting LilyPond output into other programs
835 To insert LilyPond output in other programs, use @code{lilypond}
836 instead of @code{lilypond-book}. Each example must be created
837 individually and added to the document; consult the documentation for
838 that program. Most programs will be able to insert lilypond output in
839 @file{PNG}, @file{EPS}, or @file{PDF} formats.
841 To reduce the white space around your lilypond score, use
842 the following options
850 bookTitleMarkup = ##f
851 scoreTitleMarkup = ##f
857 To produce a useful @file{eps} file, use
860 lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly