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