1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.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.
15 ** AARGH. We also have tutorial.itely: Integrating text and music.
17 Could also do with a cleanup. Lost inspiration to fix this manual
18 where to describe what?
23 @c Note: keep this node named so that `info lilypond-book' brings you here.
25 @chapter @command{lilypond-book}: Integrating text and music
27 If you want to add pictures of music to a document, you can simply do it
28 the way you would do with other types of pictures. The pictures are
29 created separately, yielding PostScript output or PNG images, and those
30 are included into a La@TeX{} or HTML document.
32 @command{lilypond-book} provides a way to automate this process: This
33 program extracts snippets of music from your document, runs
34 @command{lilypond} on them, and outputs the document with pictures
35 substituted for the music. The line width and font size definitions for
36 the music are adjusted to match the layout of your document.
38 This procedure may be applied to La@TeX{}, HTML, Texinfo or DocBook documents.
41 * An example of a musicological document::
42 * Integrating LaTeX and music::
43 * Integrating Texinfo and music::
44 * Integrating HTML and music::
45 * Integrating DocBook and music::
46 * Music fragment options::
47 * Invoking lilypond-book::
48 * Filename extensions::
49 * Many quotes of a large score::
50 * Inserting LilyPond output into OpenOffice.org::
51 * Inserting LilyPond output into other programs::
55 @node An example of a musicological document
56 @section An example of a musicological document
59 @cindex La@TeX{}, music in
60 @cindex HTML, music in
61 @cindex Texinfo, music in
62 @cindex DocBook, music in
63 Some texts contain music examples. These texts are musicological
64 treatises, songbooks, or manuals like this. Such texts can be made by
65 hand, simply by importing a PostScript figure into the word processor.
66 However, there is an automated procedure to reduce the amount of work
67 involved in HTML, La@TeX{}, Texinfo and DocBook documents.
69 A script called @code{lilypond-book} will extract the music fragments,
70 format them, and put back the resulting notation. Here we show a small
71 example for use with La@TeX{}. The example also contains explanatory
72 text, so we will not comment on it further.
76 \documentclass[a4paper]{article}
80 Documents for @command{lilypond-book} may freely mix music and text.
85 c2 g'2 \times 2/3 { f8 e d } c'2 g4
89 Options are put in brackets.
91 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
95 Larger examples can be put into a separate file, and introduced with
98 \lilypondfile[quote,noindent]{screech-boink.ly}
104 Under Unix, you can view the results as follows
109 lilypond-book --output=out --psfonts lilybook.tex
110 @emph{lilypond-book (GNU LilyPond) 2.6.0}
111 @emph{Reading lilybook.tex...}
112 @emph{..lots of stuff deleted..}
113 @emph{Compiling out/lilybook.tex...}
116 @emph{lots of stuff deleted}
120 To convert the file into a PDF document, run the following commands
123 dvips -o -Ppdf -h lilybook.psfonts lilybook
127 If you are running latex in twocolumn mode, remember to add
128 @code{-t landscape} to the dvips options.
130 Running @command{lilypond-book} and @command{latex} creates a lot of
131 temporary files, which would clutter up the working directory. To
132 remedy this, use the @code{--output=@var{dir}} option. It will create
133 the files in a separate subdirectory @file{dir}.
135 Running dvips will produce many warnings about fonts. They are not
136 harmful; please ignore them.
138 Finally the result of the La@TeX{} example shown above.@footnote{This
139 tutorial is processed with Texinfo, so the example gives slightly
140 different results in layout.} This finishes the tutorial section.
144 Documents for @command{lilypond-book} may freely mix music and text.
149 c2 g'2 \times 2/3 { f8 e d } c'2 g4
153 Options are put in brackets.
155 @lilypond[fragment,quote,staffsize=26,verbatim]
159 Larger examples can be put into a separate file, and introduced with
160 @code{\lilypondfile}.
162 @lilypondfile[quote,noindent]{screech-boink.ly}
172 @cindex documents, adding music to
175 @node Integrating LaTeX and music
176 @section Integrating La@TeX{} and music
178 La@TeX{} is the de-facto standard for publishing layouts in the exact
179 sciences. It is built on top of the @TeX{} typesetting engine,
180 providing the best typography available anywhere.
183 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
184 @emph{The Not So Short Introduction to La@TeX{}}} for an overview on how
187 Music is entered using
190 \begin[options,go,here]@{lilypond@}
199 \lilypondfile[options,go,here]@{@var{filename}@}
206 \lilypond@{ YOUR LILYPOND CODE @}
209 Running @command{lilypond-book} yields a file that can be further
210 processed with La@TeX{}.
212 We show some examples here. The lilypond environment
215 \begin[quote,fragment,staffsize=26]@{lilypond@}
223 @lilypond[quote,fragment,staffsize=26]
230 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
236 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
239 Currently, you cannot include @code{@{} or @code{@}} within
240 @code{\lilypond@{@}}, so this command is only useful with the
241 @code{fragment} option.
243 The default line width of the music will be adjusted by examining the
244 commands in the document preamble, the part of the document before
245 @code{\begin@{document@}}. The @command{lilypond-book} command sends
246 these to La@TeX{} to find out how wide the text is. The line width for
247 the music fragments is then adjusted to the text width. Note that this
248 heuristic algorithm can fail easily; in such cases it is necessary to
249 use the @code{line-width} music fragment option.
251 @cindex titling and lilypond-book
252 @funindex \header in La@TeX{} documents
254 Each snippet will call the following macros if they have been defined by
257 @code{\preLilyPondExample} called before the music
259 @code{\postLilyPondExample} called after the music
261 @code{\betweenLilyPondSystem[1]} is called between systems if
262 @code{lilypond-book} has split the snippet into several postscript
263 files. It must be defined as taking one parameter and will be
264 passed the number of files already included in this snippet.
265 The default is to simply insert a @code{\linebreak}.
270 @cindex Latex, feta symbols
273 To include feta symbols (such as flat, segno, etc) in a LaTeX
274 document, use @code{\input@{titledefs@}}
277 \documentclass[a4paper]@{article@}
288 The font symbol names are defined in the file feta20.tex; to find
289 the location of this file, use the command
297 @cindex outline fonts
300 @cindex invoking dvips
302 For printing the La@TeX{} document you need a DVI to PostScript
303 translator like @command{dvips}. To use @command{dvips} to produce
304 a PostScript file, add the following options to the @command{dvips}
308 -o -Ppdf -h @var{file}.psfonts
312 where the @var{file}@command{psfonts} file is obtained from
313 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
314 can then be produced with a PostScript to PDF translator like
315 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
316 will produce some warnings about fonts; these are harmless and may
319 If you are running latex in twocolumn mode, remember to add
320 @code{-t landscape} to the dvips options.
322 @cindex international characters
325 Sometimes it is useful to display music elements (such as ties and slurs)
326 as if they continued after the end of the fragment. This can be done by
327 breaking the staff and suppressing inclusion of the rest of the lilypond
330 In La@TeX{}, define @code{\betweenLilyPondSystem} in such a way that
331 inclusion of other systems is terminated once the required number of
332 systems are included. Since @code{\betweenLilypondSystem} is first
333 called @b{after} the first system, including only the first system
337 \def\betweenLilyPondSystem#1@{\endinput@}
339 \begin[fragment]@{lilypond@}
340 c'1\( e'( c'~ \break c' d) e f\)
344 If a greater number of systems is requested, a TeX conditional must be
345 used before the @code{\endinput}. In this example, replace "2" by
346 the numer of systems you want in the output,
349 \def\betweenLilyPondSystem#1@{
350 \ifnum##1<2\else\endinput\fi
354 Remember that the definition of @code{\betweenLilyPondSystem} is
355 effective until @TeX{} quits the current group (such as the La@TeX{}
356 environment) or is overridden by another definition (which is, in
357 most cases, for the rest of the document). To reset your
361 \let\betweenLilyPondSystem\undefined
365 in your LaTeX source.
367 This may be simplified by defining a @TeX{} macro
370 \def\onlyFirstNSystems#1@{
371 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
376 and then saying only how many systems you want before each fragment,
379 \onlyFirstNSystems@{3@}
380 \begin@{lilypond@}...\end@{lilypond@}
381 \onlyFirstNSystems@{1@}
382 \begin@{lilypond@}...\end@{lilypond@}
386 @node Integrating Texinfo and music
387 @section Integrating Texinfo and music
389 Texinfo is the standard format for documentation of the GNU project. An
390 example of a Texinfo document is this manual. The HTML, PDF, and Info
391 versions of the manual are made from the Texinfo document.
393 In the input file, music is specified with
396 @@lilypond[options,go,here]
405 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
412 @@lilypondfile[options,go,here]@{@var{filename}@}
415 When @command{lilypond-book} is run on it, this results in a Texinfo
416 file (with extension @file{.texi}) containing @code{@@image} tags for
417 HTML and info output. For the printed edition, the raw @TeX{} output of
418 LilyPond is included in the main document.
420 We show two simple examples here. A @code{lilypond} environment
438 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
444 @lilypond[fragment,staffsize=11]{<c' e' g'>}
446 Contrary to La@TeX{}, @code{@@lilypond@{...@}} does not generate an
447 in-line image. It always gets a paragraph of its own.
449 When using the Texinfo output format, @command{lilypond-book} also
450 generates bitmaps of the music (in PNG format), so you can make an HTML
451 document with embedded music.
454 @node Integrating HTML and music
455 @section Integrating HTML and music
457 Music is entered using
460 <lilypond fragment relative=2>
461 \key c \minor c4 es g2
466 @command{lilypond-book} then produces an HTML file with appropriate image
467 tags for the music fragments:
469 @lilypond[fragment,relative=2]
470 \key c \minor c4 es g2
473 For inline pictures, use @code{<lilypond ... />}, where the options
474 are separated by a colon from the music, for example
477 Some music in <lilypond relative=2: a b c/> a line of text.
480 To include separate files, say
483 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
486 @cindex titling in HTML
487 @cindex preview image
490 @node Integrating DocBook and music
491 @section Integrating DocBook and music
493 For inserting LilyPond snippets it is good to keep the conformity of
494 our DocBook document, thus allowing us to use DocBook editors,
495 validation etc. So we don't use custom tags, only specify a convention
496 based on the standard DocBook elements.
498 @unnumberedsubsec Common conventions
500 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
501 formatted inline or not inline.
502 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
503 chosen to allow DocBook editors format the content gracefully.
504 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
506 @unnumberedsubsec Including a LilyPond file
508 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},
509 with the following structure:
514 <imagedata fileref="music1.ly" role="printfilename" />
519 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
521 @unnumberedsubsec Including LilyPond code
523 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
528 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
529 \context Staff \with @{
530 \remove Time_signature_engraver
531 \remove Clef_engraver@}
538 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.
540 @unnumberedsubsec Processing the DocBook document
542 Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
543 If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
544 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.
546 @node Music fragment options
547 @section Music fragment options
549 In the following, a ``LilyPond command'' refers to any command described
550 in the previous sections which is handled by @command{lilypond-book} to
551 produce a music snippet. For simplicity, LilyPond commands are only
552 shown in La@TeX{} syntax.
554 Note that the option string is parsed from left to right; if an option
555 occurs multiple times, the last one is taken.
557 The following options are available for LilyPond commands:
560 @item staffsize=@var{ht}
561 Set staff size to @var{ht}, which is measured in points.
564 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
565 = ##t} is added to the LilyPond snippet). This is the default for the
566 @code{\lilypond@{@}} command if no @code{line-width} option is present.
567 It is also the default for the @code{lilypond} environment if the
568 @code{fragment} option is set, and no line width is explicitly
572 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
573 to the LilyPond snippet).
576 @itemx line-width=@var{size}\@var{unit}
577 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
578 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
579 @code{pt}. This option affects LilyPond output (this is, the staff
580 length of the music snippet), not the text layout.
582 If used without an argument, set line width to a default value (as
583 computed with a heuristic algorithm).
585 If no @code{line-width} option is given, @command{lilypond-book} tries to
586 guess a default for @code{lilypond} environments which don't use the
587 @code{ragged-right} option.
590 Do not print the time signature, and turns off the timing (key signature,
591 bar lines) in the score.
594 Make @command{lilypond-book} add some boilerplate code so that you can
602 without @code{\layout}, @code{\score}, etc.
605 Don't add additional code to complete LilyPond code in music snippets.
606 Since this is the default, @code{nofragment} is redundant normally.
608 @item indent=@var{size}\@var{unit}
609 Set indentation of the first music system to @var{size}, using
610 @var{unit} as units. @var{unit} is one of the following strings:
611 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
612 LilyPond, not the text layout.
615 Set indentation of the first music system to zero. This option affects
616 LilyPond, not the text layout. Since no indentation is the default,
617 @code{noindent} is redundant normally.
620 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
621 the output into a quotation block. The value `0.4@dmn{in}' can be
622 controlled with the @code{exampleindent} option.
625 Set the amount by which the @code{quote} option indents a music snippet.
628 @itemx relative=@var{n}
629 Use relative octave mode. By default, notes are specified relative to
630 middle@tie{}C. The optional integer argument specifies the octave of
631 the starting note, where the default @code{1} is middle C.
634 LilyPond also uses @command{lilypond-book} to produce its own
635 documentation. To do that, some more obscure music fragment options are
640 The argument of a LilyPond command is copied to the output file and
641 enclosed in a verbatim block, followed by any text given with the
642 @code{intertext} option (not implemented yet); then the actual music is
643 displayed. This option does not work well with @code{\lilypond@{@}} if
644 it is part of a paragraph.
647 (Only for Texinfo output.) If @command{lilypond} is called with the
648 @option{--header=@/texidoc} option, and the file to be processed is
649 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
650 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
651 option makes @command{lilypond-book} include such files, adding its
652 contents as a documentation block right before the music snippet.
654 Assuming the file @file{foo@/.ly} contains
658 texidoc = "This file demonstrates a single note."
664 and we have this in our Texinfo document @file{test.texinfo}
667 @@lilypondfile[texidoc]@{foo.ly@}
671 the following command line gives the expected result
674 lilypond-book --process="lilypond --format=tex --tex \
675 --header=texidoc test.texinfo
678 Most LilyPond test documents (in the @file{input} directory of the
679 distribution) are small @file{.ly} files which look exactly like this.
682 If a LilyPond input file is included with @code{\lilypondfile}, print
683 the file name right before the music snippet. For HTML output, this is
687 This option includes fonts in all of the generated EPS-files for this
688 snippet. This should be used if the snippet uses any font that LaTeX
689 cannot find on its own.
694 @node Invoking lilypond-book
695 @section Invoking @command{lilypond-book}
697 @command{lilypond-book} produces a file with one of the following
698 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
699 output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
702 @command{lilypond-book} can also create a PSFONTS file, which is required
703 by @command{dvips} to produce Postscript and PDF files.
705 To produce PDF output from the lilypond-book file (here called
706 @code{yourfile.lytex}) via LaTeX, you should do
709 lilypond-book --psfonts yourfile.lytex
711 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
715 The @file{.dvi} file created by this process will not contain
716 noteheads. This is normal; if you follow the instructions, they
717 will be included in the @file{.ps} and @file{.pdf} files.
719 To produce a PDF file through PDF(La)TeX, use
722 lilypond-book --pdf yourfile.pdftex
723 pdflatex yourfile.tex
727 To produce a Texinfo document (in any output format), follow the normal
728 procedures for Texinfo (this is, either call @command{texi2dvi} or
729 @command{makeinfo}, depending on the output format you want to
732 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
733 an Info File, , , texinfo, GNU Texinfo}.
736 See the documentation of Texinfo for further details.
740 @command{lilypond-book} accepts the following command line options:
743 @item -f @var{format}
744 @itemx --format=@var{format}
745 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
746 @command{lilypond-book} tries to detect the format automatically.
748 The @code{texi} document type produces a Texinfo file with music
749 fragments in the DVI output only. For getting images in the HTML
750 version, the format @code{texi-html} must be used instead.
752 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
754 @item -F @var{filter}
755 @itemx --filter=@var{filter}
756 Pipe snippets through @var{filter}. @code{lilypond-book} will
757 not --filter and --process at the same time.
761 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
766 Print a short help message.
769 @itemx --include=@var{dir}
770 Add @var{dir} to the include path.
773 @itemx --output=@var{dir}
774 Place generated files in directory @var{dir}. Running
775 @command{lilypond-book} generates lots of small files that LilyPond will
776 process. To avoid all that garbage in the source directory use the
777 @option{--output} command line option, and change to that directory
778 before running @command{latex} or @command{makeinfo}:
781 lilypond-book --output=out yourfile.lytex
786 @itemx --padding=@var{amount}
787 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
788 and is 3.0 by default. This option should be used if the lines of
789 music stick out of the right margin.
791 The width of a tightly clipped systems can vary, due to notation
792 elements that stick into the left margin, such as bar numbers and
793 instrument names. This option will shorten each line and move each
794 line to the right by the same amount.
797 @item -P @var{process}
798 @itemx --process=@var{command}
799 Process LilyPond snippets using @var{command}. The default command is
800 @code{lilypond}. @code{lilypond-book} will not --filter and --process
804 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
805 This is necessary for @command{dvips -h @var{file}.psfonts}.
813 Print version information.
818 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
819 La@TeX{} commands that change margins and line widths after the preamble
822 Only the first @code{\score} of a LilyPond block is processed.
825 @node Filename extensions
826 @section Filename extensions
828 You can use any filename extension for the input file, but if you do not
829 use the recommended extension for a particular format you may need to
830 manually specify the output format. @xref{Invoking lilypond-book}, for
831 details. Otherwise, @command{lilypond-book} automatically selects the
832 output format based on the input filename's extension.
835 @multitable @columnfractions .2 .5
836 @item @strong{extension} @tab @strong{output format}
838 @item @file{.html} @tab HTML
839 @item @file{.itely} @tab Texinfo
840 @item @file{.latex} @tab La@TeX{}
841 @item @file{.lytex} @tab La@TeX{}
842 @item @file{.lyxml} @tab DocBook
843 @item @file{.tely} @tab Texinfo
844 @item @file{.tex} @tab La@TeX{}
845 @item @file{.texi} @tab Texinfo
846 @item @file{.texinfo} @tab Texinfo
847 @item @file{.xml} @tab HTML
852 @node Many quotes of a large score
853 @section Many quotes of a large score
855 If you need to quote many fragments of a large score, you can also use
856 the clip systems feature, see @ref{Extracting fragments of notation}.
859 @node Inserting LilyPond output into OpenOffice.org
860 @section Inserting LilyPond output into OpenOffice.org
862 @cindex OpenOffice.org
864 LilyPond notation can be added to OpenOffice.org with
865 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
868 @node Inserting LilyPond output into other programs
869 @section Inserting LilyPond output into other programs
871 To insert LilyPond output in other programs, use @code{lilypond}
872 instead of @code{lilypond-book}. Each example must be created
873 individually and added to the document; consult the documentation for
874 that program. Most programs will be able to insert lilypond output in
875 @file{PNG}, @file{EPS}, or @file{PDF} formats.
877 To reduce the white space around your lilypond score, use
878 the following options
886 bookTitleMarkup = ##f
887 scoreTitleMarkup = ##f
893 To produce a useful @file{eps} file, use
896 lilypond -b eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly