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