1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
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 @LaTeX{} 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 is a separate programs from lilypond itself, and is run
39 on the command-line; see @ref{Command-line usage} for more information.
41 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
44 * An example of a musicological document::
45 * Integrating LaTeX and music::
46 * Integrating Texinfo and music::
47 * Integrating HTML and music::
48 * Integrating DocBook and music::
49 * Music fragment options::
50 * Invoking lilypond-book::
51 * Filename extensions::
52 * Many quotes of a large score::
53 * Inserting LilyPond output into OpenOffice.org::
54 * Inserting LilyPond output into other programs::
58 @node An example of a musicological document
59 @section An example of a musicological document
62 @cindex @LaTeX{}, music in
63 @cindex HTML, music in
64 @cindex Texinfo, music in
65 @cindex DocBook, music in
66 Some texts contain music examples. These texts are musicological
67 treatises, songbooks, or manuals like this. Such texts can be made by
68 hand, simply by importing a PostScript figure into the word processor.
69 However, there is an automated procedure to reduce the amount of work
70 involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
72 A script called @code{lilypond-book} will extract the music fragments,
73 format them, and put back the resulting notation. Here we show a small
74 example for use with @LaTeX{}. The example also contains explanatory
75 text, so we will not comment on it further.
79 \documentclass[a4paper]{article}
83 Documents for @command{lilypond-book} may freely mix music and text.
88 c2 g'2 \times 2/3 { f8 e d } c'2 g4
92 Options are put in brackets.
94 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
98 Larger examples can be put into a separate file, and introduced with
101 \lilypondfile[quote,noindent]{screech-boink.ly}
107 Under Unix, you can view the results as follows
112 lilypond-book --output=out --psfonts lilybook.tex
113 @emph{lilypond-book (GNU LilyPond) 2.6.0}
114 @emph{Reading lilybook.tex...}
115 @emph{..lots of stuff deleted..}
116 @emph{Compiling out/lilybook.tex...}
119 @emph{lots of stuff deleted}
123 To convert the file into a PDF document, run the following commands
126 dvips -o -Ppdf -h lilybook.psfonts lilybook
130 If you are running latex in twocolumn mode, remember to add
131 @code{-t landscape} to the dvips options.
133 Running @command{lilypond-book} and @command{latex} creates a lot of
134 temporary files, which would clutter up the working directory. To
135 remedy this, use the @code{--output=@var{dir}} option. It will create
136 the files in a separate subdirectory @file{dir}.
138 Running dvips will produce many warnings about fonts. They are not
139 harmful; please ignore them.
141 Finally the result of the @LaTeX{} example shown above.@footnote{This
142 tutorial is processed with Texinfo, so the example gives slightly
143 different results in layout.} This finishes the tutorial section.
147 Documents for @command{lilypond-book} may freely mix music and text.
152 c2 g'2 \times 2/3 { f8 e d } c'2 g4
156 Options are put in brackets.
158 @lilypond[fragment,quote,staffsize=26,verbatim]
162 Larger examples can be put into a separate file, and introduced with
163 @code{\lilypondfile}.
165 @lilypondfile[quote,noindent]{screech-boink.ly}
175 @cindex documents, adding music to
178 @node Integrating LaTeX and music
179 @section Integrating @LaTeX{} and music
181 @LaTeX{} is the de-facto standard for publishing layouts in the exact
182 sciences. It is built on top of the @TeX{} typesetting engine,
183 providing the best typography available anywhere.
186 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
187 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
190 Music is entered using
193 \begin[options,go,here]@{lilypond@}
202 \lilypondfile[options,go,here]@{@var{filename}@}
209 \lilypond@{ YOUR LILYPOND CODE @}
212 Running @command{lilypond-book} yields a file that can be further
213 processed with @LaTeX{}.
215 We show some examples here. The lilypond environment
218 \begin[quote,fragment,staffsize=26]@{lilypond@}
226 @lilypond[quote,fragment,staffsize=26]
233 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
239 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
242 Currently, you cannot include @code{@{} or @code{@}} within
243 @code{\lilypond@{@}}, so this command is only useful with the
244 @code{fragment} option.
246 The default line width of the music will be adjusted by examining the
247 commands in the document preamble, the part of the document before
248 @code{\begin@{document@}}. The @command{lilypond-book} command sends
249 these to @LaTeX{} to find out how wide the text is. The line width for
250 the music fragments is then adjusted to the text width. Note that this
251 heuristic algorithm can fail easily; in such cases it is necessary to
252 use the @code{line-width} music fragment option.
254 @cindex titling and lilypond-book
255 @cindex \header in @LaTeX{} documents
257 Each snippet will call the following macros if they have been defined by
260 @code{\preLilyPondExample} called before the music
262 @code{\postLilyPondExample} called after the music
264 @code{\betweenLilyPondSystem[1]} is called between systems if
265 @code{lilypond-book} has split the snippet into several postscript
266 files. It must be defined as taking one parameter and will be
267 passed the number of files already included in this snippet.
268 The default is to simply insert a @code{\linebreak}.
273 @cindex Latex, feta symbols
276 To include feta symbols (such as flat, segno, etc) in a LaTeX
277 document, use @code{\input@{titledefs@}}
280 \documentclass[a4paper]@{article@}
291 The font symbol names are defined in the file feta20.tex; to find
292 the location of this file, use the command
300 @cindex outline fonts
303 @cindex invoking dvips
305 For printing the @LaTeX{} document you need a DVI to PostScript
306 translator like @command{dvips}. To use @command{dvips} to produce
307 a PostScript file, add the following options to the @command{dvips}
311 -o -Ppdf -h @var{file}.psfonts
315 where the @var{file}@command{psfonts} file is obtained from
316 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details. PDF
317 can then be produced with a PostScript to PDF translator like
318 @code{ps2pdf} (which is part of GhostScript). Running @command{dvips}
319 will produce some warnings about fonts; these are harmless and may
322 If you are running latex in twocolumn mode, remember to add
323 @code{-t landscape} to the dvips options.
325 @cindex international characters
328 Sometimes it is useful to display music elements (such as ties and slurs)
329 as if they continued after the end of the fragment. This can be done by
330 breaking the staff and suppressing inclusion of the rest of the lilypond
333 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
334 inclusion of other systems is terminated once the required number of
335 systems are included. Since @code{\betweenLilypondSystem} is first
336 called @b{after} the first system, including only the first system
340 \def\betweenLilyPondSystem#1@{\endinput@}
342 \begin[fragment]@{lilypond@}
343 c'1\( e'( c'~ \break c' d) e f\)
347 If a greater number of systems is requested, a TeX conditional must be
348 used before the @code{\endinput}. In this example, replace @q{2} by
349 the number of systems you want in the output,
352 \def\betweenLilyPondSystem#1@{
353 \ifnum##1<2\else\endinput\fi
357 Remember that the definition of @code{\betweenLilyPondSystem} is
358 effective until @TeX{} quits the current group (such as the @LaTeX{}
359 environment) or is overridden by another definition (which is, in
360 most cases, for the rest of the document). To reset your
364 \let\betweenLilyPondSystem\undefined
368 in your LaTeX source.
370 This may be simplified by defining a @TeX{} macro
373 \def\onlyFirstNSystems#1@{
374 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
379 and then saying only how many systems you want before each fragment,
382 \onlyFirstNSystems@{3@}
383 \begin@{lilypond@}...\end@{lilypond@}
384 \onlyFirstNSystems@{1@}
385 \begin@{lilypond@}...\end@{lilypond@}
389 @node Integrating Texinfo and music
390 @section Integrating Texinfo and music
392 Texinfo is the standard format for documentation of the GNU project. An
393 example of a Texinfo document is this manual. The HTML, PDF, and Info
394 versions of the manual are made from the Texinfo document.
396 In the input file, music is specified with
399 @@lilypond[options,go,here]
408 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
415 @@lilypondfile[options,go,here]@{@var{filename}@}
418 When @command{lilypond-book} is run on it, this results in a Texinfo
419 file (with extension @file{.texi}) containing @code{@@image} tags for
420 HTML and info output. For the printed edition, the raw @TeX{} output of
421 LilyPond is included in the main document.
423 We show two simple examples here. A @code{lilypond} environment
441 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
447 @lilypond[fragment,staffsize=11]{<c' e' g'>}
449 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
450 in-line image. It always gets a paragraph of its own.
452 When using the Texinfo output format, @command{lilypond-book} also
453 generates bitmaps of the music (in PNG format), so you can make an HTML
454 document with embedded music.
457 @node Integrating HTML and music
458 @section Integrating HTML and music
460 Music is entered using
463 <lilypond fragment relative=2>
464 \key c \minor c4 es g2
469 @command{lilypond-book} then produces an HTML file with appropriate image
470 tags for the music fragments:
472 @lilypond[fragment,relative=2]
473 \key c \minor c4 es g2
476 For inline pictures, use @code{<lilypond ... />}, where the options
477 are separated by a colon from the music, for example
480 Some music in <lilypond relative=2: a b c/> a line of text.
483 To include separate files, say
486 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
489 @cindex titling in HTML
490 @cindex preview image
493 @node Integrating DocBook and music
494 @section Integrating DocBook and music
496 For inserting LilyPond snippets it is good to keep the conformity of
497 our DocBook document, thus allowing us to use DocBook editors,
498 validation etc. So we don't use custom tags, only specify a convention
499 based on the standard DocBook elements.
501 @unnumberedsubsec Common conventions
503 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
504 formatted inline or not inline.
505 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections). Tags are
506 chosen to allow DocBook editors format the content gracefully.
507 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
509 @unnumberedsubsec Including a LilyPond file
511 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},
512 with the following structure:
517 <imagedata fileref="music1.ly" role="printfilename" />
522 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
524 @unnumberedsubsec Including LilyPond code
526 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
531 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
532 \context Staff \with @{
533 \remove Time_signature_engraver
534 \remove Clef_engraver@}
541 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.
543 @unnumberedsubsec Processing the DocBook document
545 Running @command{lilypond-book} on our @file{.lyxml} file will create a valid DocBook document to be further processed with @file{.xml} extension.
546 If you use @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a PDF file from this document automatically.
547 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.
549 @node Music fragment options
550 @section Music fragment options
552 In the following, a @q{LilyPond command} refers to any command described
553 in the previous sections which is handled by @command{lilypond-book} to
554 produce a music snippet. For simplicity, LilyPond commands are only
555 shown in @LaTeX{} syntax.
557 Note that the option string is parsed from left to right; if an option
558 occurs multiple times, the last one is taken.
560 The following options are available for LilyPond commands:
563 @item staffsize=@var{ht}
564 Set staff size to @var{ht}, which is measured in points.
567 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
568 = ##t} is added to the LilyPond snippet). This is the default for the
569 @code{\lilypond@{@}} command if no @code{line-width} option is present.
570 It is also the default for the @code{lilypond} environment if the
571 @code{fragment} option is set, and no line width is explicitly
575 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
576 to the LilyPond snippet).
579 @itemx line-width=@var{size}\@var{unit}
580 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
581 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
582 @code{pt}. This option affects LilyPond output (this is, the staff
583 length of the music snippet), not the text layout.
585 If used without an argument, set line width to a default value (as
586 computed with a heuristic algorithm).
588 If no @code{line-width} option is given, @command{lilypond-book} tries to
589 guess a default for @code{lilypond} environments which don't use the
590 @code{ragged-right} option.
593 Do not print the time signature, and turns off the timing (key signature,
594 bar lines) in the score.
597 Make @command{lilypond-book} add some boilerplate code so that you can
605 without @code{\layout}, @code{\score}, etc.
608 Don't add additional code to complete LilyPond code in music snippets.
609 Since this is the default, @code{nofragment} is redundant normally.
611 @item indent=@var{size}\@var{unit}
612 Set indentation of the first music system to @var{size}, using
613 @var{unit} as units. @var{unit} is one of the following strings:
614 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
615 LilyPond, not the text layout.
618 Set indentation of the first music system to zero. This option affects
619 LilyPond, not the text layout. Since no indentation is the default,
620 @code{noindent} is redundant normally.
623 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
624 the output into a quotation block. The value @q{0.4@dmn{in}} can be
625 controlled with the @code{exampleindent} option.
628 Set the amount by which the @code{quote} option indents a music snippet.
631 @itemx relative=@var{n}
632 Use relative octave mode. By default, notes are specified relative to
633 middle@tie{}C. The optional integer argument specifies the octave of
634 the starting note, where the default @code{1} is middle C.
637 LilyPond also uses @command{lilypond-book} to produce its own
638 documentation. To do that, some more obscure music fragment options are
643 The argument of a LilyPond command is copied to the output file and
644 enclosed in a verbatim block, followed by any text given with the
645 @code{intertext} option (not implemented yet); then the actual music is
646 displayed. This option does not work well with @code{\lilypond@{@}} if
647 it is part of a paragraph.
650 (Only for Texinfo output.) If @command{lilypond} is called with the
651 @option{--header=@/texidoc} option, and the file to be processed is
652 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
653 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
654 option makes @command{lilypond-book} include such files, adding its
655 contents as a documentation block right before the music snippet.
657 Assuming the file @file{foo@/.ly} contains
661 texidoc = "This file demonstrates a single note."
667 and we have this in our Texinfo document @file{test.texinfo}
670 @@lilypondfile[texidoc]@{foo.ly@}
674 the following command line gives the expected result
677 lilypond-book --process="lilypond --format=tex --tex \
678 --header=texidoc test.texinfo
681 Most LilyPond test documents (in the @file{input} directory of the
682 distribution) are small @file{.ly} files which look exactly like this.
685 If a LilyPond input file is included with @code{\lilypondfile}, print
686 the file name right before the music snippet. For HTML output, this is
690 This option includes fonts in all of the generated EPS-files for this
691 snippet. This should be used if the snippet uses any font that LaTeX
692 cannot find on its own.
697 @node Invoking lilypond-book
698 @section Invoking @command{lilypond-book}
700 @command{lilypond-book} produces a file with one of the following
701 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, depending on the
702 output format. All of @file{.tex}, @file{.texi} and @file{.xml} files need further
705 @command{lilypond-book} can also create a PSFONTS file, which is required
706 by @command{dvips} to produce Postscript and PDF files.
708 To produce PDF output from the lilypond-book file (here called
709 @code{yourfile.lytex}) via LaTeX, you should do
712 lilypond-book --psfonts yourfile.lytex
714 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
718 The @file{.dvi} file created by this process will not contain
719 noteheads. This is normal; if you follow the instructions, they
720 will be included in the @file{.ps} and @file{.pdf} files.
722 To produce a PDF file through PDF(La)TeX, use
725 lilypond-book --pdf yourfile.pdftex
726 pdflatex yourfile.tex
730 To produce a Texinfo document (in any output format), follow the normal
731 procedures for Texinfo (this is, either call @command{texi2dvi} or
732 @command{makeinfo}, depending on the output format you want to
735 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
736 an Info File, , , texinfo, GNU Texinfo}.
739 See the documentation of Texinfo for further details.
743 @command{lilypond-book} accepts the following command line options:
746 @item -f @var{format}
747 @itemx --format=@var{format}
748 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}. If this option is missing,
749 @command{lilypond-book} tries to detect the format automatically.
751 The @code{texi} document type produces a Texinfo file with music
752 fragments in the DVI output only. For getting images in the HTML
753 version, the format @code{texi-html} must be used instead.
755 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
757 @item -F @var{filter}
758 @itemx --filter=@var{filter}
759 Pipe snippets through @var{filter}. @code{lilypond-book} will
760 not --filter and --process at the same time.
764 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
769 Print a short help message.
772 @itemx --include=@var{dir}
773 Add @var{dir} to the include path.
776 @itemx --output=@var{dir}
777 Place generated files in directory @var{dir}. Running
778 @command{lilypond-book} generates lots of small files that LilyPond will
779 process. To avoid all that garbage in the source directory use the
780 @option{--output} command line option, and change to that directory
781 before running @command{latex} or @command{makeinfo}:
784 lilypond-book --output=out yourfile.lytex
789 @itemx --padding=@var{amount}
790 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
791 and is 3.0 by default. This option should be used if the lines of
792 music stick out of the right margin.
794 The width of a tightly clipped systems can vary, due to notation
795 elements that stick into the left margin, such as bar numbers and
796 instrument names. This option will shorten each line and move each
797 line to the right by the same amount.
800 @item -P @var{process}
801 @itemx --process=@var{command}
802 Process LilyPond snippets using @var{command}. The default command is
803 @code{lilypond}. @code{lilypond-book} will not --filter and --process
807 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
808 This is necessary for @command{dvips -h @var{file}.psfonts}.
816 Print version information.
821 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
822 @LaTeX{} commands that change margins and line widths after the preamble
825 Only the first @code{\score} of a LilyPond block is processed.
828 @node Filename extensions
829 @section Filename extensions
831 You can use any filename extension for the input file, but if you do not
832 use the recommended extension for a particular format you may need to
833 manually specify the output format. @xref{Invoking lilypond-book}, for
834 details. Otherwise, @command{lilypond-book} automatically selects the
835 output format based on the input filename's extension.
838 @multitable @columnfractions .2 .5
839 @item @strong{extension} @tab @strong{output format}
841 @item @file{.html} @tab HTML
842 @item @file{.itely} @tab Texinfo
843 @item @file{.latex} @tab @LaTeX{}
844 @item @file{.lytex} @tab @LaTeX{}
845 @item @file{.lyxml} @tab DocBook
846 @item @file{.tely} @tab Texinfo
847 @item @file{.tex} @tab @LaTeX{}
848 @item @file{.texi} @tab Texinfo
849 @item @file{.texinfo} @tab Texinfo
850 @item @file{.xml} @tab HTML
855 @node Many quotes of a large score
856 @section Many quotes of a large score
858 If you need to quote many fragments of a large score, you can also use
859 the clip systems feature, see @ruser{Extracting fragments of notation}.
862 @node Inserting LilyPond output into OpenOffice.org
863 @section Inserting LilyPond output into OpenOffice.org
865 @cindex OpenOffice.org
867 LilyPond notation can be added to OpenOffice.org with
868 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
871 @node Inserting LilyPond output into other programs
872 @section Inserting LilyPond output into other programs
874 To insert LilyPond output in other programs, use @code{lilypond}
875 instead of @code{lilypond-book}. Each example must be created
876 individually and added to the document; consult the documentation for
877 that program. Most programs will be able to insert lilypond output in
878 @file{PNG}, @file{EPS}, or @file{PDF} formats.
880 To reduce the white space around your lilypond score, use
881 the following options
889 bookTitleMarkup = ##f
890 scoreTitleMarkup = ##f
896 To produce a useful @file{eps} file, use
899 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly