1 @c -*- coding: utf-8; mode: texinfo; -*-
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.
12 @c Note: keep this node named so that `info lilypond-book' brings you here.
14 @chapter Running @command{lilypond-book}
16 If you want to add pictures of music to a document, you can simply do it
17 the way you would do with other types of pictures. The pictures are
18 created separately, yielding PostScript output or PNG images, and those
19 are included into a @LaTeX{} or HTML document.
21 @command{lilypond-book} provides a way to automate this process: This
22 program extracts snippets of music from your document, runs
23 @command{lilypond} on them, and outputs the document with pictures
24 substituted for the music. The line width and font size definitions for
25 the music are adjusted to match the layout of your document.
27 This is a separate program from @command{lilypond} itself, and is run
28 on the command line; for more information, see @ref{Command-line
29 usage}. If you have MacOS 10.3 or 10.4 and you have trouble running
30 @code{lilypond-book}, see @rweb{MacOS X}.
32 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook
41 @cindex documents, adding music to
42 @cindex HTML, music in
43 @cindex Texinfo, music in
44 @cindex DocBook, music in
45 @cindex @LaTeX{}, music in
48 * An example of a musicological document::
49 * Integrating music and text::
50 * Music fragment options::
51 * Invoking lilypond-book::
52 * Filename extensions::
53 * lilypond-book templates::
54 * Alternate methods of mixing text and music::
58 @node An example of a musicological document
59 @section An example of a musicological document
62 Some texts contain music examples. These texts are musicological
63 treatises, songbooks, or manuals like this. Such texts can be made by
64 hand, simply by importing a PostScript figure into the word processor.
65 However, there is an automated procedure to reduce the amount of work
66 involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
68 A script called @code{lilypond-book} will extract the music fragments,
69 format them, and put back the resulting notation. Here we show a small
70 example for use with @LaTeX{}. The example also contains explanatory
71 text, so we will not comment on it further.
77 \documentclass[a4paper]{article}
81 Documents for \verb+lilypond-book+ may freely mix music and text.
86 c2 g'2 \times 2/3 { f8 e d } c'2 g4
90 Options are put in brackets.
92 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
96 Larger examples can be put into a separate file, and introduced with
99 \lilypondfile[quote,noindent]{screech-boink.ly}
101 (If needed, replace screech-boink.ly by any .ly file you put in the same
102 directory as this file.)
108 @subheading Processing
110 Save the code above to a file called @file{lilybook.lytex}, then in a
113 @c keep space after @version{} so TeX doesn't choke
115 lilypond-book --output=out --pdf lilybook.lytex
116 @emph{lilypond-book (GNU LilyPond) @version{} }
117 @emph{Reading lilybook.lytex...}
118 @emph{..lots of stuff deleted..}
119 @emph{Compiling lilybook.tex...}
122 @emph{..lots of stuff deleted..}
124 @emph{(replace @command{xpdf} by your favorite PDF viewer)}
127 Running @command{lilypond-book} and @command{latex} creates a lot of
128 temporary files, which would clutter up the working directory. To
129 remedy this, use the @code{--output=@var{dir}} option. It will create
130 the files in a separate subdirectory @file{dir}.
132 Finally the result of the @LaTeX{} example shown above.@footnote{This
133 tutorial is processed with Texinfo, so the example gives slightly
134 different results in layout.} This finishes the tutorial section.
140 Documents for @command{lilypond-book} may freely mix music and text.
145 c2 g'2 \times 2/3 { f8 e d } c'2 g4
149 Options are put in brackets.
151 @lilypond[fragment,quote,staffsize=26,verbatim]
155 Larger examples can be put into a separate file, and introduced with
156 @code{\lilypondfile}.
158 @lilypondfile[quote,noindent]{screech-boink.ly}
163 @node Integrating music and text
164 @section Integrating music and text
166 Here we explain how to integrate LilyPond with various output formats.
178 @LaTeX{} 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 @LaTeX{}}} 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[options,go,here]@{ YOUR LILYPOND CODE @}
209 Additionally, @code{\lilypondversion} displays the current version
211 Running @command{lilypond-book} yields a file that can be further
212 processed with @LaTeX{}.
214 We show some examples here. The @code{lilypond} environment
217 \begin[quote,fragment,staffsize=26]@{lilypond@}
225 @lilypond[quote,fragment,staffsize=26]
232 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
238 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
241 Currently, you cannot include @code{@{} or @code{@}} within
242 @code{\lilypond@{@}}, so this command is only useful with the
243 @code{fragment} option.
245 The default line width of the music will be adjusted by examining the
246 commands in the document preamble, the part of the document before
247 @code{\begin@{document@}}. The @command{lilypond-book} command sends
248 these to @LaTeX{} to find out how wide the text is. The line width for
249 the music fragments is then adjusted to the text width. Note that this
250 heuristic algorithm can fail easily; in such cases it is necessary to
251 use the @code{line-width} music fragment option.
253 @cindex titling and lilypond-book
254 @cindex \header in @LaTeX{} documents
256 Each snippet will call the following macros if they have been defined by
260 @item @code{\preLilyPondExample} called before the music,
262 @item @code{\postLilyPondExample} called after the music,
264 @item @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}.
274 @cindex Latex, feta symbols
277 To include feta symbols (such as flat, segno, etc) in a LaTeX
278 document, use @code{\input@{titledefs@}}
281 \documentclass[a4paper]@{article@}
292 The font symbol names are defined in the file feta20.tex; to find
293 the location of this file, use the command
303 Sometimes it is useful to display music elements (such as ties and slurs)
304 as if they continued after the end of the fragment. This can be done by
305 breaking the staff and suppressing inclusion of the rest of the LilyPond
308 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
309 inclusion of other systems is terminated once the required number of
310 systems are included. Since @code{\betweenLilyPondSystem} is first
311 called @emph{after} the first system, including only the first system
315 \def\betweenLilyPondSystem#1@{\endinput@}
317 \begin[fragment]@{lilypond@}
318 c'1\( e'( c'~ \break c' d) e f\)
322 If a greater number of systems is requested, a @TeX{} conditional must
323 be used before the @code{\endinput}. In this example, replace @q{2} by
324 the number of systems you want in the output.
327 \def\betweenLilyPondSystem#1@{
328 \ifnum##1<2\else\expandafter\endinput\fi
333 (Since @code{\endinput} immediately stops the processing of the current
334 input file we need @code{\expandafter} to delay the call of @code{\endinput}
335 after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is
338 Remember that the definition of @code{\betweenLilyPondSystem} is
339 effective until @TeX{} quits the current group (such as the @LaTeX{}
340 environment) or is overridden by another definition (which is, in
341 most cases, for the rest of the document). To reset your
345 \let\betweenLilyPondSystem\undefined
349 in your @LaTeX{} source.
351 This may be simplified by defining a @TeX{} macro
354 \def\onlyFirstNSystems#1@{
355 \def\betweenLilyPondSystem##1@{%
356 \ifnum##1<#1\else\expandafter\endinput\fi@}
361 and then saying only how many systems you want before each fragment,
364 \onlyFirstNSystems@{3@}
365 \begin@{lilypond@}...\end@{lilypond@}
366 \onlyFirstNSystems@{1@}
367 \begin@{lilypond@}...\end@{lilypond@}
372 There are specific @command{lilypond-book} command line options and
373 other details to know when processing @LaTeX{} documents, see
374 @ref{Invoking lilypond-book}.
380 Texinfo is the standard format for documentation of the GNU project. An
381 example of a Texinfo document is this manual. The HTML, PDF, and Info
382 versions of the manual are made from the Texinfo document.
384 In the input file, music is specified with
387 @@lilypond[options,go,here]
396 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
403 @@lilypondfile[options,go,here]@{@var{filename}@}
406 Additionally, @code{@@lilypondversion} displays the current version
409 When @command{lilypond-book} is run on it, this results in a Texinfo
410 file (with extension @file{.texi}) containing @code{@@image} tags for
411 HTML, Info and printed output. @command{lilypond-book} generates images
412 of the music in EPS and PDF formats for use in the printed output, and
413 in PNG format for use in HTML and Info output.
415 We show two simple examples here. A @code{lilypond} environment
433 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
439 @lilypond[fragment,staffsize=11]{<c' e' g'>}
441 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
442 in-line image. It always gets a paragraph of its own.
448 Music is entered using
451 <lilypond fragment relative=2>
452 \key c \minor c4 es g2
456 @command{lilypond-book} then produces an HTML file with appropriate image
457 tags for the music fragments:
459 @lilypond[fragment,relative=2]
460 \key c \minor c4 es g2
463 For inline pictures, use @code{<lilypond ... />}, where the options
464 are separated by a colon from the music, for example
467 Some music in <lilypond relative=2: a b c/> a line of text.
471 To include separate files, say
474 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
477 Additionally, @code{<lilypondversion/>} displays the current version
481 @cindex titling in HTML
482 @cindex preview image
488 For inserting LilyPond snippets it is good to keep the conformity of our
489 DocBook document, thus allowing us to use DocBook editors, validation
490 etc. So we don't use custom tags, only specify a convention based on the
491 standard DocBook elements.
493 @subheading Common conventions
495 For inserting all type of snippets we use the @code{mediaobject} and
496 @code{inlinemediaobject} element, so our snippets can be formatted
497 inline or not inline. The snippet formatting options are always
498 provided in the @code{role} property of the innermost element (see in
499 next sections). Tags are chosen to allow DocBook editors format the
500 content gracefully. The DocBook files to be processed with
501 @command{lilypond-book} should have the extension @file{.lyxml}.
503 @subheading Including a LilyPond file
505 This is the most simple case. We must use the @file{.ly} extension for
506 the included file, and insert it as a standard @code{imageobject}, with
507 the following structure:
512 <imagedata fileref="music1.ly" role="printfilename" />
517 Note that you can use @code{mediaobject} or @code{inlinemediaobject}
518 as the outermost element as you wish.
520 @subheading Including LilyPond code
522 Including LilyPond code is possible by using a @code{programlisting},
523 where the language is set to @code{lilypond} with the following
529 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
530 \context Staff \with @{
531 \remove Time_signature_engraver
532 \remove Clef_engraver@}
539 As you can see, the outermost element is a @code{mediaobject} or
540 @code{inlinemediaobject}, and there is a @code{textobject} containing
541 the @code{programlisting} inside.
543 @subheading Processing the DocBook document
545 Running @command{lilypond-book} on our @file{.lyxml} file will create a
546 valid DocBook document to be further processed with @file{.xml}
547 extension. If you use
548 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
549 PDF file from this document automatically. For HTML (HTML Help,
550 JavaHelp etc.) generation you can use the official DocBook XSL
551 stylesheets, however, it is possible that you have to make some
552 customization for it.
555 @node Music fragment options
556 @section Music fragment options
558 In the following, a @q{LilyPond command} refers to any command described
559 in the previous sections which is handled by @command{lilypond-book} to
560 produce a music snippet. For simplicity, LilyPond commands are only
561 shown in @LaTeX{} syntax.
563 Note that the option string is parsed from left to right; if an option
564 occurs multiple times, the last one is taken.
566 The following options are available for LilyPond commands:
569 @item staffsize=@var{ht}
570 Set staff size to @var{ht}, which is measured in points.
573 Produce ragged-right lines with natural spacing, i.e.,
574 @code{ragged-right = ##t} is added to the LilyPond snippet. This is the
575 default for the @code{\lilypond@{@}} command if no @code{line-width}
576 option is present. It is also the default for the @code{lilypond}
577 environment if the @code{fragment} option is set, and no line width is
578 explicitly specified.
581 For single-line snippets, allow the staff length to be stretched to
582 equal that of the line width, i.e., @code{ragged-right = ##f} is
583 added to the LilyPond snippet.
586 @itemx line-width=@var{size}\@var{unit}
587 Set line width to @var{size}, using @var{unit} as units. @var{unit} is
588 one of the following strings: @code{cm}, @code{mm}, @code{in}, or
589 @code{pt}. This option affects LilyPond output (this is, the staff
590 length of the music snippet), not the text layout.
592 If used without an argument, set line width to a default value (as
593 computed with a heuristic algorithm).
595 If no @code{line-width} option is given, @command{lilypond-book} tries to
596 guess a default for @code{lilypond} environments which don't use the
597 @code{ragged-right} option.
600 Do not print the time signature, and turns off the timing (time signature,
601 bar lines) in the score.
604 Make @command{lilypond-book} add some boilerplate code so that you can
612 without @code{\layout}, @code{\score}, etc.
615 Do not add additional code to complete LilyPond code in music snippets.
616 Since this is the default, @code{nofragment} is redundant normally.
618 @item indent=@var{size}\@var{unit}
619 Set indentation of the first music system to @var{size}, using
620 @var{unit} as units. @var{unit} is one of the following strings:
621 @code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects
622 LilyPond, not the text layout.
625 Set indentation of the first music system to zero. This option affects
626 LilyPond, not the text layout. Since no indentation is the default,
627 @code{noindent} is redundant normally.
630 Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
631 the output into a quotation block. The value @q{0.4@dmn{in}} can be
632 controlled with the @code{exampleindent} option.
635 Set the amount by which the @code{quote} option indents a music snippet.
638 @itemx relative=@var{n}
639 Use relative octave mode. By default, notes are specified relative to
640 middle@tie{}C. The optional integer argument specifies the octave of
641 the starting note, where the default @code{1} is middle C.
642 @code{relative} option only works when @code{fragment} option is set,
643 so @code{fragment} is automatically implied by @code{relative},
644 regardless of the presence of any @code{(no)fragment} option in the
648 LilyPond also uses @command{lilypond-book} to produce its own
649 documentation. To do that, some more obscure music fragment options are
654 The argument of a LilyPond command is copied to the output file and
655 enclosed in a verbatim block, followed by any text given with the
656 @code{intertext} option (not implemented yet); then the actual music is
657 displayed. This option does not work well with @code{\lilypond@{@}} if
658 it is part of a paragraph.
660 If @code{verbatim} is used in a @code{lilypondfile} command, it is
661 possible to enclose verbatim only a part of the source file. If the
662 source file contain a comment containing @samp{begin verbatim} (without
663 quotes), quoting the source in the verbatim block will start after the
664 last occurrence of such a comment; similarly, quoting the source verbatim
665 will stop just before the first occurrence of a comment containing
666 @samp{end verbatim}, if there is any. In the following source file
667 example, the music will be interpreted in relative mode, but the
668 verbatim quote will not show the @code{relative} block, i.e.
671 \relative c' @{ % begin verbatim
678 will be printed with a verbatim block like
686 If you would like to translate comments and variable names in verbatim
687 output but not in the sources, you may set the environment variable
688 @code{LYDOC_LOCALEDIR} to a directory path; the directory should
689 contain a tree of @file{.mo} message catalogs with @code{lilypond-doc}
693 (Only for Texinfo output.) Prepend line @code{\version
694 @@w@{"@@version@{@}"@}} to @code{verbatim} output.
697 (Only for Texinfo output.) If @command{lilypond} is called with the
698 @option{--header=@/texidoc} option, and the file to be processed is
699 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
700 is a @code{texidoc} field in the @code{\header}. The @code{texidoc}
701 option makes @command{lilypond-book} include such files, adding its
702 contents as a documentation block right before the music snippet.
704 Assuming the file @file{foo@/.ly} contains
708 texidoc = "This file demonstrates a single note."
714 and we have this in our Texinfo document @file{test.texinfo}
717 @@lilypondfile[texidoc]@{foo.ly@}
721 the following command line gives the expected result
724 lilypond-book --pdf --process="lilypond \
725 -dbackend=eps --header=texidoc" test.texinfo
728 Most LilyPond test documents (in the @file{input} directory of the
729 distribution) are small @file{.ly} files which look exactly like this.
731 For localization purpose, if the Texinfo document contains
732 @code{@@documentlanguage @var{LANG}} and @file{foo@/.ly} header
733 contains a @code{texidoc@var{LANG}} field, and if @command{lilypond}
734 is called with @option{--header=@/texidoc@var{LANG}}, then
735 @file{foo@/.texidoc@var{LANG}} will be included instead of
736 @file{foo@/.texidoc}.
739 (Only for Texinfo output.) This option is similar to quote, but only
740 the music snippet (and the optional verbatim block implied by
741 @code{verbatim} option) is put into a quotation block. This option is
742 useful if you want to @code{quote} the music snippet but not the
743 @code{texidoc} documentation block.
746 (Only for Texinfo output.) This option works similarly to
747 @code{texidoc} option: if @command{lilypond} is called with the
748 @option{--header=@/doctitle} option, and the file to be processed is
749 called @file{foo@/.ly} and contains a @code{doctitle} field in the
750 @code{\header}, it creates a file @file{foo@/.doctitle}. When
751 @code{doctitle} option is used, the contents of @file{foo@/.doctitle},
752 which should be a single line of @var{text}, is inserted in the
753 Texinfo document as @code{@@lydoctitle @var{text}}.
754 @code{@@lydoctitle} should be a macro defined in the Texinfo document.
755 The same remark about @code{texidoc} processing with localized
756 languages also applies to @code{doctitle}.
759 (Only for Texinfo output.) Do not translate comments and variable
760 names in the snippet quoted verbatim.
763 If a LilyPond input file is included with @code{\lilypondfile}, print
764 the file name right before the music snippet. For HTML output, this
765 is a link. Only the base name of the file is printed, i.e. the
766 directory part of the file path is stripped.
771 @node Invoking lilypond-book
772 @section Invoking @command{lilypond-book}
774 @command{lilypond-book} produces a file with one of the following
775 extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml},
776 depending on the output format. All of @file{.tex}, @file{.texi} and
777 @file{.xml} files need further processing.
779 @subheading Format-specific instructions
781 @subsubheading @LaTeX{}
783 There are two ways of processing your @LaTeX{} document for printing or
784 publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a
785 PostScript file with @LaTeX{} via a DVI to PostScript translator like
786 @command{dvips}. The first way is simpler and recommended@footnote{Note
787 that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any
788 @LaTeX{} document, that is why we explain the two ways.}, and whichever
789 way you use, you can easily convert between PostScript and PDF with
790 tools, like @command{ps2pdf} and @command{pdf2ps} included in
793 To produce a PDF file through PDF@LaTeX{}, use
796 lilypond-book --pdf yourfile.pdftex
797 pdflatex yourfile.tex
800 @cindex outline fonts
803 @cindex invoking dvips
804 To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you
808 lilypond-book yourfile.lytex
810 dvips -Ppdf yourfile.dvi
815 The @file{.dvi} file created by this process will not contain
816 note heads. This is normal; if you follow the instructions, they
817 will be included in the @file{.ps} and @file{.pdf} files.
819 Running @command{dvips} may produce some warnings about fonts; these
820 are harmless and may be ignored. If you are running @command{latex} in
821 twocolumn mode, remember to add @code{-t landscape} to the
822 @command{dvips} options.
824 @subsubheading Texinfo
826 To produce a Texinfo document (in any output format), follow the normal
827 procedures for Texinfo; this is, either call @command{texi2pdf} or
828 @command{texi2dvi} or @command{makeinfo}, depending on the output format
831 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
832 an Info File, , , texinfo, GNU Texinfo}.
835 See the documentation of Texinfo for further details.
839 @subheading Command line options
841 @command{lilypond-book} accepts the following command line options:
844 @item -f @var{format}
845 @itemx --format=@var{format}
846 Specify the document type to process: @code{html}, @code{latex},
847 @code{texi} (the default) or @code{docbook}. If this option is missing,
848 @command{lilypond-book} tries to detect the format automatically, see
849 @ref{Filename extensions}. Currently, @code{texi} is the same as
852 @c This complicated detail is not implemented, comment it out -jm
854 The @code{texi} document type produces a Texinfo file with music
855 fragments in the printed output only. For getting images in the HTML
856 version, the format @code{texi-html} must be used instead.
859 @item -F @var{filter}
860 @itemx --filter=@var{filter}
861 Pipe snippets through @var{filter}. @code{lilypond-book} will
862 not --filter and --process at the same time. For example,
865 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
870 Print a short help message.
873 @itemx --include=@var{dir}
874 Add @var{dir} to the include path. @command{lilypond-book} also looks
875 for already compiled snippets in the include path, and does not write
876 them back to the output directory, so in some cases it is necessary to
877 invoke further processing commands such as @command{makeinfo} or
878 @command{latex} with the same @code{-I @var{dir}} options.
881 @itemx --output=@var{dir}
882 Place generated files in directory @var{dir}. Running
883 @command{lilypond-book} generates lots of small files that LilyPond will
884 process. To avoid all that garbage in the source directory, use the
885 @option{--output} command line option, and change to that directory
886 before running @command{latex} or @command{makeinfo}.
889 lilypond-book --output=out yourfile.lytex
894 @itemx --skip-lily-check
895 Do not fail if no lilypond output is found. It is used for LilyPond
896 Info documentation without images.
898 @itemx --skip-png-check
899 Do not fail if no PNG images are found for EPS files. It is used for
900 LilyPond Info documentation without images.
902 @itemx --lily-output-dir=@var{dir}
903 Write lily-XXX files to directory @var{dir}, link into @code{--output}
904 directory. Use this option to save building time for documents in
905 different directories which share a lot of identical snippets.
907 @itemx --info-images-dir=@var{dir}
908 Format Texinfo output so that Info will look for images of music in
911 @itemx --latex-program=@var{prog}
912 Run executable @command{prog} instead of @command{latex}. This is
913 useful if your document is processed with @command{xelatex}, for
916 @itemx --left-padding=@var{amount}
917 Pad EPS boxes by this much. @var{amount} is measured in millimeters,
918 and is 3.0 by default. This option should be used if the lines of
919 music stick out of the right margin.
921 The width of a tightly clipped system can vary, due to notation
922 elements that stick into the left margin, such as bar numbers and
923 instrument names. This option will shorten each line and move each
924 line to the right by the same amount.
927 @item -P @var{command}
928 @itemx --process=@var{command}
929 Process LilyPond snippets using @var{command}. The default command is
930 @code{lilypond}. @code{lilypond-book} will not @code{--filter} and
931 @code{--process} at the same time.
934 Create PDF files for use with PDF@LaTeX{}.
942 Print version information.
947 The Texinfo command @code{@@pagesizes} is not interpreted. Similarly,
948 @LaTeX{} commands that change margins and line widths after the preamble
951 Only the first @code{\score} of a LilyPond block is processed.
954 @node Filename extensions
955 @section Filename extensions
957 You can use any filename extension for the input file, but if you do not
958 use the recommended extension for a particular format you may need to
959 manually specify the output format; for details, see @ref{Invoking
960 lilypond-book}. Otherwise, @command{lilypond-book} automatically
961 selects the output format based on the input filename's extension.
964 @multitable @columnfractions .2 .5
965 @item @strong{extension} @tab @strong{output format}
967 @item @file{.html} @tab HTML
968 @item @file{.itely} @tab Texinfo
969 @item @file{.latex} @tab @LaTeX{}
970 @item @file{.lytex} @tab @LaTeX{}
971 @item @file{.lyxml} @tab DocBook
972 @item @file{.tely} @tab Texinfo
973 @item @file{.tex} @tab @LaTeX{}
974 @item @file{.texi} @tab Texinfo
975 @item @file{.texinfo} @tab Texinfo
976 @item @file{.xml} @tab HTML
980 If you use the same filename extension for the input file than the
981 extension @command{lilypond-book} uses for the output file, and if the
982 input file is in the same directory as @command{lilypond-book} working
983 directory, you must use @code{--output} option to make
984 @command{lilypond-book} running, otherwise it will exit with an error
985 message like @qq{Output would overwrite input file}.
988 @node lilypond-book templates
989 @section lilypond-book templates
991 These templates are for use with @code{lilypond-book}. If you're not familiar
992 with this program, please refer to
997 You can include LilyPond fragments in a LaTeX document.
1000 \documentclass[]@{article@}
1024 You can include LilyPond fragments in Texinfo; in fact, this entire manual
1025 is written in Texinfo.
1033 @@lilypond[verbatim,fragment,ragged-right]
1039 @@lilypond[verbatim,fragment,ragged-right]
1050 \documentclass{article}
1051 \usepackage{ifxetex}
1053 %xetex specific stuff
1054 \usepackage{xunicode,fontspec,xltxtra}
1055 \setmainfont[Numbers=OldStyle]{Times New Roman}
1058 %This can be empty if you are not going to use pdftex
1059 \usepackage[T1]{fontenc}
1060 \usepackage[utf8]{inputenc}
1061 \usepackage{mathptmx}%Times
1062 \usepackage{helvet}%Helvetica
1064 %Here you can insert all packages that pdftex also understands
1065 \usepackage[ngerman,finnish,english]{babel}
1066 \usepackage{graphicx}
1069 \title{A short document with LilyPond and xelatex}
1072 Normal \textbf{font} commands inside the \emph{text} work,
1073 because they \textsf{are supported by \LaTeX{} and XeteX.}
1074 If you want to use specific commands like \verb+\XeTeX+, you
1075 should include them again in a \verb+\ifxetex+ environment.
1076 You can use this to print the \ifxetex \XeTeX{} command \else
1077 XeTeX command \fi which is not known to normal \LaTeX .
1079 In normal text you can easily use LilyPond commands, like this:
1088 The fonts of snippets set with LilyPond will have to be set from
1090 of the snippet. For this you should read the AU on how to use
1093 \selectlanguage{ngerman}
1094 Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle
1096 seltsamen Zeichen: __ ______, wenn sie von der Schriftart
1097 unterst__tzt werden.
1102 @node Alternate methods of mixing text and music
1103 @section Alternative methods of mixing text and music
1105 This section shows methods to integrate text and music, different than
1106 the automated method with @command{lilypond-book}.
1109 * Many quotes from a large score::
1110 * Inserting LilyPond output into OpenOffice.org::
1111 * Inserting LilyPond output into other programs::
1114 @node Many quotes from a large score
1115 @unnumberedsubsec Many quotes from a large score
1117 If you need to quote many fragments from a large score, you can also use
1118 the clip systems feature, see @ruser{Extracting fragments of music}.
1121 @node Inserting LilyPond output into OpenOffice.org
1122 @unnumberedsubsec Inserting LilyPond output into OpenOffice.org
1124 @cindex OpenOffice.org
1126 LilyPond notation can be added to OpenOffice.org with
1127 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
1130 @node Inserting LilyPond output into other programs
1131 @unnumberedsubsec Inserting LilyPond output into other programs
1133 To insert LilyPond output in other programs, use @code{lilypond}
1134 instead of @code{lilypond-book}. Each example must be created
1135 individually and added to the document; consult the documentation for
1136 that program. Most programs will be able to insert LilyPond output in
1137 @file{PNG}, @file{EPS}, or @file{PDF} formats.
1139 To reduce the white space around your LilyPond score, use
1140 the following options
1148 bookTitleMarkup = ##f
1149 scoreTitleMarkup = ##f
1155 To produce a useful @file{EPS} file, use
1158 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts myfile.ly
1161 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png myfile.ly