]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/lilypond-book.itely
ef1176d435c688e7d582a8d08aaf93dc3b768d87
[lilypond.git] / Documentation / user / lilypond-book.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-program.tely
3 @ignore
4     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5
6     When revising a translation, copy the HEAD committish of the
7     version that you are working on.  See TRANSLATION for details.
8 @end ignore
9
10
11 @c Note: keep this node named so that `info lilypond-book' brings you here.
12 @node LilyPond-book
13 @chapter @command{lilypond-book}: Integrating text and music
14
15 If you want to add pictures of music to a document, you can simply do it
16 the way you would do with other types of pictures.  The pictures are
17 created separately, yielding PostScript output or PNG images, and those
18 are included into a @LaTeX{} or HTML document.
19
20 @command{lilypond-book} provides a way to automate this process: This
21 program extracts snippets of music from your document, runs
22 @command{lilypond} on them, and outputs the document with pictures
23 substituted for the music.  The line width and font size definitions for
24 the music are adjusted to match the layout of your document.
25
26 This is a separate programs from lilypond itself, and is run
27 on the command-line; see @ref{Command-line usage} for more information.
28
29 This procedure may be applied to @LaTeX{}, HTML, Texinfo or DocBook documents.
30
31 @cindex texinfo
32 @cindex latex
33 @cindex texinfo
34 @cindex texi
35 @cindex html
36 @cindex docbook
37 @cindex documents, adding music to
38 @cindex HTML, music in
39 @cindex Texinfo, music in
40 @cindex DocBook, music in
41 @cindex @LaTeX{}, music in
42
43 @menu
44 * An example of a musicological document::  
45 * Integrating music and text::  
46 * Music fragment options::      
47 * Invoking lilypond-book::      
48 * Filename extensions::         
49 * Alternate methods of mixing text and music::  
50 @end menu
51
52
53 @node An example of a musicological document
54 @section An example of a musicological document
55
56 @cindex musicology
57 Some texts contain music examples.  These texts are musicological
58 treatises, songbooks, or manuals like this.  Such texts can be made by
59 hand, simply by importing a PostScript figure into the word processor.
60 However, there is an automated procedure to reduce the amount of work
61 involved in HTML, @LaTeX{}, Texinfo and DocBook documents.
62
63 A script called @code{lilypond-book} will extract the music fragments,
64 format them, and put back the resulting notation.  Here we show a small
65 example for use with @LaTeX{}.  The example also contains explanatory
66 text, so we will not comment on it further.
67
68 @subheading Input
69
70 @quotation
71 @verbatim
72 \documentclass[a4paper]{article}
73
74 \begin{document}
75
76 Documents for @command{lilypond-book} may freely mix music and text.
77 For example,
78
79 \begin{lilypond}
80 \relative c' {
81   c2 g'2 \times 2/3 { f8 e d } c'2 g4
82 }
83 \end{lilypond}
84
85 Options are put in brackets.
86
87 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
88   c'4 f16
89 \end{lilypond}
90
91 Larger examples can be put into a separate file, and introduced with
92 \verb+\lilypondfile+.
93
94 \lilypondfile[quote,noindent]{screech-boink.ly}
95
96 \end{document}
97 @end verbatim
98 @end quotation
99
100 @subheading Processing
101
102 Under Unix, you can view the results as follows
103
104 @example
105 cd input/tutorial
106 mkdir -p out/
107 lilypond-book --output=out --psfonts lilybook.tex
108 @emph{lilypond-book (GNU LilyPond) 2.6.0}
109 @emph{Reading lilybook.tex...}
110 @emph{..lots of stuff deleted..}
111 @emph{Compiling out/lilybook.tex...}
112 cd out
113 latex lilybook
114 @emph{lots of stuff deleted}
115 xdvi lilybook
116 @end example
117
118 To convert the file into a PDF document, run the following commands
119
120 @example
121 dvips -o -Ppdf -h lilybook.psfonts lilybook
122 ps2pdf lilybook.ps
123 @end example
124
125 If you are running latex in twocolumn mode, remember to add
126 @code{-t landscape} to the dvips options.
127
128 Running @command{lilypond-book} and @command{latex} creates a lot of
129 temporary files, which would clutter up the working directory.  To
130 remedy this, use the @code{--output=@var{dir}} option.  It will create
131 the files in a separate subdirectory @file{dir}.
132
133 Running dvips will produce many warnings about fonts.  They are not
134 harmful; please ignore them.
135
136 Finally the result of the @LaTeX{} example shown above.@footnote{This
137 tutorial is processed with Texinfo, so the example gives slightly
138 different results in layout.}  This finishes the tutorial section.
139
140 @page
141
142 @subheading Output
143
144 Documents for @command{lilypond-book} may freely mix music and text.
145 For example,
146
147 @lilypond
148 \relative c' {
149   c2 g'2 \times 2/3 { f8 e d } c'2 g4
150 }
151 @end lilypond
152
153 Options are put in brackets.
154
155 @lilypond[fragment,quote,staffsize=26,verbatim]
156 c'4 f16
157 @end lilypond
158
159 Larger examples can be put into a separate file, and introduced with
160 @code{\lilypondfile}.
161
162 @lilypondfile[quote,noindent]{screech-boink.ly}
163
164
165 @page
166
167 @node Integrating music and text
168 @section Integrating music and text
169
170 Here we explain how to integrate LilyPond with various output formats.
171
172 @menu
173 * LaTeX::                       
174 * Texinfo::                     
175 * HTML::                        
176 * DocBook::                     
177 @end menu
178
179 @node LaTeX
180 @subsection @LaTeX{}
181
182 @LaTeX{} is the de-facto standard for publishing layouts in the exact
183 sciences.  It is built on top of the @TeX{} typesetting engine,
184 providing the best typography available anywhere.
185
186 See
187 @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/,
188 @emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how
189 to use @LaTeX{}.
190
191 Music is entered using
192
193 @example
194 \begin[options,go,here]@{lilypond@}
195   YOUR LILYPOND CODE
196 \end@{lilypond@}
197 @end example
198
199 @noindent
200 or
201
202 @example
203 \lilypondfile[options,go,here]@{@var{filename}@}
204 @end example
205
206 @noindent
207 or
208
209 @example
210 \lilypond@{ YOUR LILYPOND CODE @}
211 @end example
212
213 Running @command{lilypond-book} yields a file that can be further
214 processed with @LaTeX{}.
215
216 We show some examples here.  The lilypond environment
217
218 @example
219 \begin[quote,fragment,staffsize=26]@{lilypond@}
220   c' d' e' f' g'2 g'2
221 \end@{lilypond@}
222 @end example
223
224 @noindent
225 produces
226
227 @lilypond[quote,fragment,staffsize=26]
228 c' d' e' f' g'2 g'2
229 @end lilypond
230
231 The short version
232
233 @example
234 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
235 @end example
236
237 @noindent
238 produces
239
240 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
241
242 @noindent
243 Currently, you cannot include @code{@{} or @code{@}} within
244 @code{\lilypond@{@}}, so this command is only useful with the
245 @code{fragment} option.
246
247 The default line width of the music will be adjusted by examining the
248 commands in the document preamble, the part of the document before
249 @code{\begin@{document@}}.  The @command{lilypond-book} command sends
250 these to @LaTeX{} to find out how wide the text is.  The line width for
251 the music fragments is then adjusted to the text width.  Note that this
252 heuristic algorithm can fail easily; in such cases it is necessary to
253 use the @code{line-width} music fragment option.
254
255 @cindex titling and lilypond-book
256 @cindex \header in @LaTeX{} documents
257
258 Each snippet will call the following macros if they have been defined by
259 the user:
260
261 @code{\preLilyPondExample} called before the music
262
263 @code{\postLilyPondExample} called after the music
264
265 @code{\betweenLilyPondSystem[1]} is called between systems if
266 @code{lilypond-book} has split the snippet into several postscript
267 files.  It must be defined as taking one parameter and will be
268 passed the number of files already included in this snippet.
269 The default is to simply insert a @code{\linebreak}.
270
271 @ignore
272 Broken stuff.  :(
273
274 @cindex Latex, feta symbols
275 @cindex fetachar
276
277 To include feta symbols (such as flat, segno, etc) in a LaTeX
278 document, use @code{\input@{titledefs@}}
279
280 @example
281 \documentclass[a4paper]@{article@}
282
283 \input@{titledefs@}
284
285 \begin@{document@}
286
287 \fetachar\fetasharp
288
289 \end@{document@}
290 @end example
291
292 The font symbol names are defined in the file feta20.tex; to find
293 the location of this file, use the command
294
295 @example
296 kpsewhich feta20.tex
297 @end example
298
299 @end ignore
300
301 @cindex outline fonts
302 @cindex type1 fonts
303 @cindex dvips
304 @cindex invoking dvips
305
306 For printing the @LaTeX{} document you need a DVI to PostScript
307 translator like @command{dvips}.  To use @command{dvips} to produce
308 a PostScript file, add the following options to the @command{dvips}
309 command line:
310
311 @example
312 -o -Ppdf -h @var{file}.psfonts
313 @end example
314
315 @noindent
316 where the @var{file}@command{psfonts} file is obtained from
317 @command{lilypond-book}, @xref{Invoking lilypond-book}, for details.  PDF
318 can then be produced with a PostScript to PDF translator like
319 @code{ps2pdf} (which is part of GhostScript).  Running @command{dvips}
320 will produce some warnings about fonts; these are harmless and may
321 be ignored.
322
323 If you are running latex in twocolumn mode, remember to add
324 @code{-t landscape} to the dvips options.
325
326 @cindex international characters
327 @cindex latin1
328
329 Sometimes it is useful to display music elements (such as ties and slurs)
330 as if they continued after the end of the fragment.  This can be done by
331 breaking the staff and suppressing inclusion of the rest of the lilypond
332 output.
333
334 In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that
335 inclusion of other systems is terminated once the required number of
336 systems are included.  Since @code{\betweenLilypondSystem} is first
337 called @b{after} the first system, including only the first system
338 is trivial.
339
340 @example
341 \def\betweenLilyPondSystem#1@{\endinput@}
342
343 \begin[fragment]@{lilypond@}
344   c'1\( e'( c'~ \break c' d) e f\)
345 \end@{lilypond@}
346 @end example
347
348 If a greater number of systems is requested, a TeX conditional must be
349 used before the @code{\endinput}.  In this example, replace @q{2} by
350 the number of systems you want in the output,
351
352 @example
353 \def\betweenLilyPondSystem#1@{
354     \ifnum##1<2\else\endinput\fi
355 @}
356 @end example
357
358 Remember that the definition of @code{\betweenLilyPondSystem} is
359 effective until @TeX{} quits the current group (such as the @LaTeX{}
360 environment) or is overridden by another definition (which is, in
361 most cases, for the rest of the document).  To reset your
362 definition, write
363
364 @example
365 \let\betweenLilyPondSystem\undefined
366 @end example
367
368 @noindent
369 in your LaTeX source.
370
371 This may be simplified by defining a @TeX{} macro
372
373 @example
374 \def\onlyFirstNSystems#1@{
375     \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
376 @}
377 @end example
378
379 @noindent
380 and then saying only how many systems you want before each fragment,
381
382 @example
383 \onlyFirstNSystems@{3@}
384 \begin@{lilypond@}...\end@{lilypond@}
385 \onlyFirstNSystems@{1@}
386 \begin@{lilypond@}...\end@{lilypond@}
387 @end example
388
389
390 @node Texinfo
391 @subsection Texinfo
392
393 Texinfo is the standard format for documentation of the GNU project.  An
394 example of a Texinfo document is this manual.  The HTML, PDF, and Info
395 versions of the manual are made from the Texinfo document.
396
397 In the input file, music is specified with
398
399 @example
400 @@lilypond[options,go,here]
401   YOUR LILYPOND CODE
402 @@end lilypond
403 @end example
404
405 @noindent
406 or
407
408 @example
409 @@lilypond[options,go,here]@{ YOUR LILYPOND CODE @}
410 @end example
411
412 @noindent
413 or
414
415 @example
416 @@lilypondfile[options,go,here]@{@var{filename}@}
417 @end example
418
419 When @command{lilypond-book} is run on it, this results in a Texinfo
420 file (with extension @file{.texi}) containing @code{@@image} tags for
421 HTML and info output.  For the printed edition, the raw @TeX{} output of
422 LilyPond is included in the main document.
423
424 We show two simple examples here.  A @code{lilypond} environment
425
426 @example
427 @@lilypond[fragment]
428 c' d' e' f' g'2 g'
429 @@end lilypond
430 @end example
431
432 @noindent
433 produces
434
435 @lilypond[fragment]
436 c' d' e' f' g'2 g'
437 @end lilypond
438
439 The short version
440
441 @example
442 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
443 @end example
444
445 @noindent
446 produces
447
448 @lilypond[fragment,staffsize=11]{<c' e' g'>}
449
450 Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an
451 in-line image.  It always gets a paragraph of its own.
452
453 When using the Texinfo output format, @command{lilypond-book} also
454 generates bitmaps of the music (in PNG format), so you can make an HTML
455 document with embedded music.
456
457
458 @node HTML
459 @subsection HTML
460
461 Music is entered using
462
463 @example
464 <lilypond fragment relative=2>
465 \key c \minor c4 es g2
466 </lilypond>
467 @end example
468
469 @noindent
470 @command{lilypond-book} then produces an HTML file with appropriate image
471 tags for the music fragments:
472
473 @lilypond[fragment,relative=2]
474 \key c \minor c4 es g2
475 @end lilypond
476
477 For inline pictures, use @code{<lilypond ... />}, where the options
478 are separated by a colon from the music, for example
479
480 @example
481 Some music in <lilypond relative=2: a b c/> a line of text.
482 @end example
483
484 To include separate files, say
485
486 @example
487 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
488 @end example
489
490 @cindex titling in HTML
491 @cindex preview image
492 @cindex thumbnail
493
494 @node DocBook
495 @subsection DocBook
496
497 For inserting LilyPond snippets it is good to keep the conformity of
498 our DocBook document, thus allowing us to use DocBook editors,
499 validation etc. So we don't use custom tags, only specify a convention
500 based on the standard DocBook elements.
501
502 @subheading Common conventions
503
504 For inserting all type of snippets we use the @code{mediaobject} and @code{inlinemediaobject} element, so our snippets can be
505 formatted inline or not inline.
506 The snippet formatting options are always provided in the @code{role} property of the innermost element (see in next sections).  Tags are
507 chosen to allow DocBook editors format the content gracefully.
508 The DocBook files to be processed with @command{lilypond-book} should have the extension @file{.lyxml}.
509
510 @subheading Including a LilyPond file
511
512 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},
513 with the following structure:
514
515 @example
516 <mediaobject>
517   <imageobject>
518     <imagedata fileref="music1.ly" role="printfilename" />
519   </imageobject>
520 </mediaobject>
521 @end example
522
523 Note that you can use mediaobject or inlinemediaobject as the outermost element as you wish.
524
525 @subheading Including LilyPond code
526
527 Including LilyPond code is possible by using a @code{programlisting}, where the language is set to @code{lilypond} with the following structure:
528
529 @example
530 <inlinemediaobject>
531   <textobject>
532     <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
533 \context Staff \with @{
534   \remove Time_signature_engraver
535   \remove Clef_engraver@} 
536   @{ c4( fis) @}
537     </programlisting>
538   </textobject>
539 </inlinemediaobject>
540 @end example
541
542 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
544 @subheading Processing the DocBook document
545
546 Running @command{lilypond-book} on our @file{.lyxml} file will create a
547 valid DocBook document to be further processed with @file{.xml}
548 extension.  If you use
549 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a
550 PDF file from this document automatically.  For HTML (HTML Help,
551 JavaHelp etc.) generation you can use the official DocBook XSL
552 stylesheets, however, it is possible that you have to make some
553 customization for it.
554
555
556 @node Music fragment options
557 @section Music fragment options
558
559 In the following, a @q{LilyPond command} refers to any command described
560 in the previous sections which is handled by @command{lilypond-book} to
561 produce a music snippet.  For simplicity, LilyPond commands are only
562 shown in @LaTeX{} syntax.
563
564 Note that the option string is parsed from left to right; if an option
565 occurs multiple times, the last one is taken.
566
567 The following options are available for LilyPond commands:
568
569 @table @code
570 @item staffsize=@var{ht}
571 Set staff size to @var{ht}, which is measured in points.
572
573 @item ragged-right
574 Produce ragged-right lines with natural spacing (i.e., @code{ragged-right
575 = ##t} is added to the LilyPond snippet).  This is the default for the
576 @code{\lilypond@{@}} command if no @code{line-width} option is present.
577 It is also the default for the @code{lilypond} environment if the
578 @code{fragment} option is set, and no line width is explicitly
579 specified.
580
581 @item packed
582 Produce lines with packed spacing (i.e., @code{packed = ##t} is added
583 to the LilyPond snippet).
584
585 @item line-width
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.
591
592 If used without an argument, set line width to a default value (as
593 computed with a heuristic algorithm).
594
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.
598
599 @item notime
600 Do not print the time signature, and turns off the timing (key signature,
601 bar lines) in the score.
602
603 @item fragment
604 Make @command{lilypond-book} add some boilerplate code so that you can
605 simply enter, say,
606
607 @example
608 c'4
609 @end example
610
611 @noindent
612 without @code{\layout}, @code{\score}, etc.
613
614 @item nofragment
615 Don't add additional code to complete LilyPond code in music snippets.
616 Since this is the default, @code{nofragment} is redundant normally.
617
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.
623
624 @item noindent
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.
628
629 @item quote
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.
633
634 @c in lilypond-book.py at l.953, it is said that this option is broken.
635 @c remove?
636 @item exampleindent
637 Set the amount by which the @code{quote} option indents a music snippet.
638
639 @item relative
640 @itemx relative=@var{n}
641 Use relative octave mode.  By default, notes are specified relative to
642 middle@tie{}C.  The optional integer argument specifies the octave of
643 the starting note, where the default @code{1} is middle C.
644 @end table
645
646 LilyPond also uses @command{lilypond-book} to produce its own
647 documentation.  To do that, some more obscure music fragment options are
648 available.
649
650 @table @code
651 @item verbatim
652 The argument of a LilyPond command is copied to the output file and
653 enclosed in a verbatim block, followed by any text given with the
654 @code{intertext} option (not implemented yet); then the actual music is
655 displayed.  This option does not work well with @code{\lilypond@{@}} if
656 it is part of a paragraph.
657
658 @item texidoc
659 (Only for Texinfo output.)  If @command{lilypond} is called with the
660 @option{--header=@/texidoc} option, and the file to be processed is
661 called @file{foo@/.ly}, it creates a file @file{foo@/.texidoc} if there
662 is a @code{texidoc} field in the @code{\header}.  The @code{texidoc}
663 option makes @command{lilypond-book} include such files, adding its
664 contents as a documentation block right before the music snippet.
665
666 Assuming the file @file{foo@/.ly} contains
667
668 @example
669 \header @{
670   texidoc = "This file demonstrates a single note."
671 @}
672 @{ c'4 @}
673 @end example
674
675 @noindent
676 and we have this in our Texinfo document @file{test.texinfo}
677
678 @example
679 @@lilypondfile[texidoc]@{foo.ly@}
680 @end example
681
682 @noindent
683 the following command line gives the expected result
684
685 @example
686 lilypond-book --process="lilypond --format=tex --tex \
687               --header=texidoc test.texinfo
688 @end example
689
690 Most LilyPond test documents (in the @file{input} directory of the
691 distribution) are small @file{.ly} files which look exactly like this.
692
693 @item lilyquote
694 (Only for Texinfo output.)  This is the same option as quote, but only
695 the music snippet is put into a quotation block.  This option is useful
696 if you want to @code{quote} the music snippet but not the @code{texidoc}
697 documentation block.
698
699 @item printfilename
700 If a LilyPond input file is included with @code{\lilypondfile}, print
701 the file name right before the music snippet.  For HTML output, this is
702 a link.
703
704 @item fontload
705 This option includes fonts in all of the generated EPS-files for this
706 snippet.  This should be used if the snippet uses any font that LaTeX
707 cannot find on its own.
708
709 @end table
710
711
712 @node Invoking lilypond-book
713 @section Invoking @command{lilypond-book}
714
715 @command{lilypond-book} produces a file with one of the following
716 extensions: @file{.tex}, @file{.texi}, @file{.html}  or @file{.xml}, depending on the
717 output format.  All of @file{.tex}, @file{.texi} and @file{.xml} files need further
718 processing.
719
720 @command{lilypond-book} can also create a PSFONTS file, which is required
721 by @command{dvips} to produce Postscript and PDF files.
722
723 To produce PDF output from the lilypond-book file (here called
724 @code{yourfile.lytex}) via LaTeX, you should do
725
726 @example
727 lilypond-book --psfonts yourfile.lytex
728 latex yourfile.tex
729 dvips -o -h yourfile.psfonts -Ppdf yourfile.dvi
730 ps2pdf yourfile.ps
731 @end example
732
733 The @file{.dvi} file created by this process will not contain
734 noteheads.  This is normal; if you follow the instructions, they
735 will be included in the @file{.ps} and @file{.pdf} files.
736
737 To produce a PDF file through PDF(La)TeX, use
738  
739 @example
740 lilypond-book --pdf yourfile.pdftex
741 pdflatex yourfile.tex
742 @end example
743  
744
745 To produce a Texinfo document (in any output format), follow the normal
746 procedures for Texinfo (this is, either call @command{texi2dvi} or
747 @command{makeinfo}, depending on the output format you want to
748 create).
749 @ifinfo
750 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating
751 an Info File, , , texinfo, GNU Texinfo}.
752 @end ifinfo
753 @ifnotinfo
754 See the documentation of Texinfo for further details.
755 @end ifnotinfo
756
757
758 @command{lilypond-book} accepts the following command line options:
759
760 @table @code
761 @item -f @var{format}
762 @itemx --format=@var{format}
763 Specify the document type to process: @code{html}, @code{latex}, @code{texi} (the default) or @code{docbook}.  If this option is missing,
764 @command{lilypond-book} tries to detect the format automatically.
765
766 The @code{texi} document type produces a Texinfo file with music
767 fragments in the DVI output only.  For getting images in the HTML
768 version, the format @code{texi-html} must be used instead.
769
770 [Note: Currently, @code{texi} is the same as @code{texi-html}.]
771
772 @item -F @var{filter}
773 @itemx --filter=@var{filter}
774 Pipe snippets through @var{filter}.  @code{lilypond-book} will
775 not --filter and --process at the same time.
776
777 Example:
778 @example
779 lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely
780 @end example
781
782 @item -h
783 @itemx --help
784 Print a short help message.
785
786 @item -I @var{dir}
787 @itemx --include=@var{dir}
788 Add @var{dir} to the include path.
789
790 @item -o @var{dir}
791 @itemx --output=@var{dir}
792 Place generated files in directory @var{dir}.  Running
793 @command{lilypond-book} generates lots of small files that LilyPond will
794 process.  To avoid all that garbage in the source directory use the
795 @option{--output} command line option, and change to that directory
796 before running @command{latex} or @command{makeinfo}:
797
798 @example
799 lilypond-book --output=out yourfile.lytex
800 cd out
801 ...
802 @end example
803
804 @itemx --left-padding=@var{amount}
805 Pad EPS boxes by this much. @var{amount} is measured in milimeters,
806 and is 3.0 by default.  This option should be used if the lines of
807 music stick out of the right margin.
808
809 The width of a tightly clipped systems can vary, due to notation
810 elements that stick into the left margin, such as bar numbers and
811 instrument names.  This option will shorten each line and move each 
812 line to the right by the same amount.
813
814
815 @item -P @var{process}
816 @itemx --process=@var{command}
817 Process LilyPond snippets using @var{command}.  The default command is
818 @code{lilypond}.  @code{lilypond-book} will not --filter and --process
819 at the same time.
820
821 @itemx --psfonts
822 extract all PostScript fonts into @file{@var{file}.psfonts} for dvips.
823 This is necessary for @command{dvips -h @var{file}.psfonts}.
824
825 @item -V
826 @itemx --verbose
827 Be verbose.
828
829 @item -v
830 @itemx --version
831 Print version information.
832 @end table
833
834 @refbugs
835
836 The Texinfo command @code{@@pagesizes} is not interpreted.  Similarly,
837 @LaTeX{} commands that change margins and line widths after the preamble
838 are ignored.
839
840 Only the first @code{\score} of a LilyPond block is processed.
841
842
843 @node Filename extensions
844 @section Filename extensions
845
846 You can use any filename extension for the input file, but if you do not
847 use the recommended extension for a particular format you may need to
848 manually specify the output format.  @xref{Invoking lilypond-book}, for
849 details.  Otherwise, @command{lilypond-book} automatically selects the
850 output format based on the input filename's extension.
851
852 @quotation
853 @multitable @columnfractions .2 .5
854 @item @strong{extension} @tab @strong{output format}
855 @item
856 @item @file{.html} @tab HTML
857 @item @file{.itely} @tab Texinfo
858 @item @file{.latex} @tab @LaTeX{}
859 @item @file{.lytex} @tab @LaTeX{}
860 @item @file{.lyxml} @tab DocBook
861 @item @file{.tely} @tab Texinfo
862 @item @file{.tex} @tab @LaTeX{}
863 @item @file{.texi} @tab Texinfo
864 @item @file{.texinfo} @tab Texinfo
865 @item @file{.xml} @tab HTML
866 @end multitable
867 @end quotation
868
869
870 @node Alternate methods of mixing text and music
871 @section Alternative methods of mixing text and music
872
873 @menu
874 * Many quotes from a large score::  
875 * Inserting LilyPond output into OpenOffice.org::  
876 * Inserting LilyPond output into other programs::  
877 @end menu
878
879 @node Many quotes from a large score
880 @subsection Many quotes from a large score
881
882 If you need to quote many fragments from a large score, you can also use
883 the clip systems feature, see @ruser{Extracting fragments of notation}.
884
885
886 @node Inserting LilyPond output into OpenOffice.org
887 @subsection Inserting LilyPond output into OpenOffice.org
888
889 @cindex OpenOffice.org
890
891 LilyPond notation can be added to OpenOffice.org with
892 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}
893
894
895 @node Inserting LilyPond output into other programs
896 @subsection Inserting LilyPond output into other programs
897
898 To insert LilyPond output in other programs, use @code{lilypond}
899 instead of @code{lilypond-book}.  Each example must be created
900 individually and added to the document; consult the documentation for
901 that program.  Most programs will be able to insert lilypond output in
902 @file{PNG}, @file{EPS}, or @file{PDF} formats.
903
904 To reduce the white space around your lilypond score, use
905 the following options
906
907 @example
908 \paper@{
909   indent=0\mm
910   line-width=120\mm
911   oddFooterMarkup=##f
912   oddHeaderMarkup=##f
913   bookTitleMarkup = ##f
914   scoreTitleMarkup = ##f
915 @}
916
917 @{ c1 @}
918 @end example
919
920 To produce a useful @file{eps} file, use
921
922 @example
923 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts   myfile.ly
924 @end example
925