1@c -*- coding: utf-8; mode: texinfo; -*- 2 3@ignore 4 Translation of GIT committish: f77212d801fa4603bf596a19cecf5a068f1d9d85 5 6 When revising a translation, copy the HEAD committish of the 7 version that you are working on. For details, see the Contributors' 8 Guide, node Updating translation committishes.. 9@end ignore 10 11@c \version "2.19.22" 12 13@c Note: keep this node named so that `info lilypond-book' brings you here. 14@node lilypond-book 15@chapter A @command{lilypond-book} használata 16@translationof lilypond-book 17 18Amennyiben egy dokumentumba kottapéldákat szeretnénk beszúrni, megtehetjük, 19hogy azok képeit egyesével létrehozzuk a LilyPond segítségével PostScript 20vagy PNG formátumban, és mint bármilyen más képeket, beillesztjük azokat egy 21@LaTeX{} vagy HTML dokumentumba. 22 23A @command{lilypond-book} ennek a folyamatnak az automatizálására szolgál: 24ez a program kiszedi a LilyPond kódrészleteket egy dokumentumból, lefordítja 25őket a @command{lilypond} segítségével, és az így kapott képeket beilleszti 26az eredeti kódrészletek helyére. A kottakép méretei igazodnak a dokumentum 27elrendezéséhez. 28 29A @command{lilypond-book} egy különálló parancssori program; a parancssoros 30programok futtatásának módját a @ref{Parancssori használat} írja le bővebben. 31 32A @command{lilypond-book} jelenleg a @LaTeX{}, HTML, Texinfo és DocBook 33formátumokat támogatja. 34 35@cindex texinfo 36@cindex latex 37@cindex texinfo 38@cindex texi 39@cindex html 40@cindex docbook 41@cindex dokumentumok, kottapéldák 42@cindex HTML, kottapéldák 43@cindex Texinfo, kottapéldák 44@cindex DocBook, kottapéldák 45@cindex @LaTeX{}, kottapéldák 46 47@menu 48* Egy kottapéldákat tartalmazó dokumentum:: 49* Zene és szöveg integrációja:: 50* Kottapéldák paraméterei:: 51* A lilypond-book futtatása:: 52* Fájlkiterjesztések:: 53* lilypond-book sablonok:: 54* Közös tartalomjegyzék:: 55* További módszerek zene és szöveg kombinálására:: 56@end menu 57 58 59@node Egy kottapéldákat tartalmazó dokumentum 60@section Egy kottapéldákat tartalmazó dokumentum 61@translationof An example of a musicological document 62 63@cindex zenetudomány 64Bizonyos dokumentumok kottapéldákat tartalmaznak. Ezek között vannak 65zenetudományi értekezések, énekeskönyvek, vagy ehhez hasonló kézikönyvek. 66Ezeket úgy is el lehet készíteni, hogy a szövegbe beillesztjük a kottaábrákat. 67Azonban ahhoz, hogy ne kelljen minden egyes kottarészlet szedését külön 68elvégezni, a HTML, @LaTeX{}, Texinfo és DocBook formátumú dokumentumok esetén 69mód nyílik ennek automatizálására. 70 71Egy @code{lilypond-book} nevű parancsfájl a LilyPond nyelvén írt 72kódrészleteket szépen formázott kottapéldákká alakítja át. Íme egy rövid, 73magyarázatokkal ellátott @LaTeX{} példa. 74 75@subheading Bemenet 76 77@quotation 78@verbatim 79\documentclass[a4paper]{article} 80 81\begin{document} 82 83A \verb+lilypond-book+ segítségével feldolgozott dokumentumok 84kottapéldákat tartalmazhatnak. Például: 85 86\begin{lilypond} 87\relative { 88 c'2 e2 \tuplet 3/2 { f8 a b } a2 e4 89} 90\end{lilypond} 91 92A beállításokat szögletes zárójelbe kell tenni: 93 94\begin{lilypond}[fragment,quote,staffsize=26,verbatim] 95 c'4 f16 96\end{lilypond} 97 98A nagyobb kottapéldákat ki lehet emelni külön fájlba, majd beilleszteni 99őket a \verb+\lilypondfile+ paranccsal: 100 101\lilypondfile[quote,noindent]{screech-and-boink.ly} 102 103\end{document} 104@end verbatim 105@end quotation 106 107@subheading Feldolgozás 108 109A fenti dokumentumot egy @file{lilybook.lytex} nevű fájlba mentve futtassuk le 110a következő parancsokat: 111 112@c keep space after @version{} so TeX doesn't choke 113@example 114lilypond-book --output=out --pdf lilybook.lytex 115@emph{lilypond-book (GNU LilyPond) @version{} } 116@emph{Reading lilybook.lytex...} 117@emph{...} 118@emph{Compiling lilybook.tex...} 119cd out 120pdflatex lilybook 121@emph{...} 122xpdf lilybook 123@emph{(az @command{xpdf} helyére értelemszerűen tetszőleges PDF-nézegető 124kerülhet)} 125@end example 126 127A @command{lilypond-book} és a @command{latex} rengeteg ideiglenes fájlt 128hoznak létre. Annak érdekében, hogy ezek külön alkönyvtárba kerüljenek, a 129@code{--output=@var{alkönyvtár}} opciót kell megadni. 130 131Lent látható a fenti @LaTeX{} példa kimenete.@footnote{Ezt a dokumentumot a 132Texinfo generálta, így apró eltérések lehetnek.} Ezzel elsajátítottuk a 133lilypond-book használatának alapjait. 134 135@page 136 137@subheading Kimenet 138 139A @command{lilypond-book} segítségével feldolgozott dokumentumok 140kottapéldákat tartalmazhatnak. Például: 141 142@lilypond 143\relative { 144 c'2 e2 \tuplet 3/2 { f8 a b } a2 e4 145} 146@end lilypond 147 148A beállításokat szögletes zárójelbe kell tenni: 149 150@lilypond[fragment,quote,staffsize=26,verbatim] 151c'4 f16 152@end lilypond 153 154A nagyobb kottapéldákat ki lehet emelni külön fájlba, majd beilleszteni 155őket a @code{\lilypondfile} paranccsal: 156 157@lilypondfile[quote,noindent]{snippets/screech-and-boink.ly} 158 159 160@page 161 162@node Zene és szöveg integrációja 163@section Zene és szöveg integrációja 164@translationof Integrating music and text 165@untranslated 166 167Here we explain how to integrate LilyPond with various output formats. 168 169@menu 170* LaTeX:: 171* Texinfo:: 172* HTML:: 173* DocBook:: 174@end menu 175 176@node LaTeX 177@subsection @LaTeX{} 178@untranslated 179 180@LaTeX{} is the de-facto standard for publishing layouts in the exact 181sciences. It is built on top of the @TeX{} typesetting engine, 182providing the best typography available anywhere. 183 184See 185@uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/english/, 186@emph{The Not So Short Introduction to @LaTeX{}}} for an overview on how 187to use @LaTeX{}. 188 189Music is entered using 190 191@example 192\begin@{lilypond@}[options,go,here] 193 YOUR LILYPOND CODE 194\end@{lilypond@} 195@end example 196 197@noindent 198or 199 200@example 201\lilypondfile[options,go,here]@{@var{filename}@} 202@end example 203 204@noindent 205or 206 207@example 208\lilypond[options,go,here]@{ YOUR LILYPOND CODE @} 209@end example 210 211Additionally, @code{\lilypondversion} displays the current version 212of lilypond. 213Running @command{lilypond-book} yields a file that can be further 214processed with @LaTeX{}. 215 216We show some examples here. The @code{lilypond} environment 217 218@example 219\begin@{lilypond@}[quote,fragment,staffsize=26] 220 c' d' e' f' g'2 g'2 221\end@{lilypond@} 222@end example 223 224@noindent 225produces 226 227@lilypond[quote,fragment,staffsize=26] 228c' d' e' f' g'2 g'2 229@end lilypond 230 231The short version 232 233@example 234\lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@} 235@end example 236 237@noindent 238produces 239 240@lilypond[quote,fragment,staffsize=11]{<c' e' g'>} 241 242@noindent 243Currently, you cannot include @code{@{} or @code{@}} within 244@code{\lilypond@{@}}, so this command is only useful with the 245@code{fragment} option. 246 247The default line width of the music will be adjusted by examining the 248commands in the document preamble, the part of the document before 249@code{\begin@{document@}}. The @command{lilypond-book} command sends 250these to @LaTeX{} to find out how wide the text is. The line width for 251the music fragments is then adjusted to the text width. Note that this 252heuristic algorithm can fail easily; in such cases it is necessary to 253use the @code{line-width} music fragment option. 254 255@cindex titling and lilypond-book 256@cindex \header in @LaTeX{} documents 257 258Each snippet will call the following macros if they have been defined by 259the user: 260 261@itemize @bullet 262@item @code{\preLilyPondExample} called before the music, 263 264@item @code{\postLilyPondExample} called after the music, 265 266@item @code{\betweenLilyPondSystem[1]} is called between systems if 267@code{lilypond-book} has split the snippet into several PostScript 268files. It must be defined as taking one parameter and will be 269passed the number of files already included in this snippet. 270The default is to simply insert a @code{\linebreak}. 271@end itemize 272 273@ignore 274Broken stuff. :( 275 276@cindex Latex, feta symbols 277@cindex fetachar 278 279To include feta symbols (such as flat, segno, etc) in a LaTeX 280document, use @code{\input@{titledefs@}} 281 282@example 283\documentclass[a4paper]@{article@} 284 285\input@{titledefs@} 286 287\begin@{document@} 288 289\fetachar\fetasharp 290 291\end@{document@} 292@end example 293 294The font symbol names are defined in the file feta20.tex; to find 295the location of this file, use the command 296 297@example 298kpsewhich feta20.tex 299@end example 300 301@end ignore 302 303@snippets 304 305Sometimes it is useful to display music elements (such as ties and slurs) 306as if they continued after the end of the fragment. This can be done by 307breaking the staff and suppressing inclusion of the rest of the LilyPond 308output. 309 310In @LaTeX{}, define @code{\betweenLilyPondSystem} in such a way that 311inclusion of other systems is terminated once the required number of 312systems are included. Since @code{\betweenLilyPondSystem} is first 313called @emph{after} the first system, including only the first system 314is trivial. 315 316@example 317\def\betweenLilyPondSystem#1@{\endinput@} 318 319\begin@{lilypond@}[fragment] 320 c'1\( e'( c'~ \break c' d) e f\) 321\end@{lilypond@} 322@end example 323 324If a greater number of systems is requested, a @TeX{} conditional must 325be used before the @code{\endinput}. In this example, replace @q{2} by 326the number of systems you want in the output. 327 328@example 329\def\betweenLilyPondSystem#1@{ 330 \ifnum#1<2\else\expandafter\endinput\fi 331@} 332@end example 333 334@noindent 335(Since @code{\endinput} immediately stops the processing of the current 336input file we need @code{\expandafter} to delay the call of @code{\endinput} 337after executing @code{\fi} so that the @code{\if}-@code{\fi} clause is 338balanced.) 339 340Remember that the definition of @code{\betweenLilyPondSystem} is 341effective until @TeX{} quits the current group (such as the @LaTeX{} 342environment) or is overridden by another definition (which is, in 343most cases, for the rest of the document). To reset your 344definition, write 345 346@example 347\let\betweenLilyPondSystem\undefined 348@end example 349 350@noindent 351in your @LaTeX{} source. 352 353This may be simplified by defining a @TeX{} macro 354 355@example 356\def\onlyFirstNSystems#1@{ 357 \def\betweenLilyPondSystem##1@{% 358 \ifnum##1<#1\else\expandafter\endinput\fi@} 359@} 360@end example 361 362@noindent 363and then saying only how many systems you want before each fragment, 364 365@example 366\onlyFirstNSystems@{3@} 367\begin@{lilypond@}...\end@{lilypond@} 368\onlyFirstNSystems@{1@} 369\begin@{lilypond@}...\end@{lilypond@} 370@end example 371 372 373@morerefs 374There are specific @command{lilypond-book} command line options and 375other details to know when processing @LaTeX{} documents, see 376@ref{Invoking lilypond-book}. 377 378 379@node Texinfo 380@subsection Texinfo 381@untranslated 382 383Texinfo is the standard format for documentation of the GNU project. An 384example of a Texinfo document is this manual. The HTML, PDF, and Info 385versions of the manual are made from the Texinfo document. 386 387In the input file, music is specified with 388 389@example 390@@lilypond[options,go,here] 391 YOUR LILYPOND CODE 392@@end lilypond 393@end example 394 395@noindent 396or 397 398@example 399@@lilypond[options,go,here]@{ YOUR LILYPOND CODE @} 400@end example 401 402@noindent 403or 404 405@example 406@@lilypondfile[options,go,here]@{@var{filename}@} 407@end example 408 409Additionally, @code{@@lilypondversion} displays the current version 410of lilypond. 411 412When @command{lilypond-book} is run on it, this results in a Texinfo 413file (with extension @file{.texi}) containing @code{@@image} tags for 414HTML, Info and printed output. @command{lilypond-book} generates images 415of the music in EPS and PDF formats for use in the printed output, and 416in PNG format for use in HTML and Info output. 417 418We show two simple examples here. A @code{lilypond} environment 419 420@example 421@@lilypond[fragment] 422c' d' e' f' g'2 g' 423@@end lilypond 424@end example 425 426@noindent 427produces 428 429@lilypond[fragment] 430c' d' e' f' g'2 g' 431@end lilypond 432 433The short version 434 435@example 436@@lilypond[fragment,staffsize=11]@{<c' e' g'>@} 437@end example 438 439@noindent 440produces 441 442@lilypond[fragment,staffsize=11]{<c' e' g'>} 443 444Contrary to @LaTeX{}, @code{@@lilypond@{...@}} does not generate an 445in-line image. It always gets a paragraph of its own. 446 447 448@node HTML 449@subsection HTML 450@untranslated 451 452Music is entered using 453 454@example 455<lilypond fragment relative=2> 456\key c \minor c4 es g2 457</lilypond> 458@end example 459 460@noindent 461@command{lilypond-book} then produces an HTML file with appropriate image 462tags for the music fragments: 463 464@lilypond[fragment,relative=2] 465\key c \minor c4 es g2 466@end lilypond 467 468For inline pictures, use @code{<lilypond ... />}, where the options 469are separated by a colon from the music, for example 470 471@example 472Some music in <lilypond relative=2: a b c/> a line of text. 473@end example 474 475To include separate files, say 476 477@example 478<lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile> 479@end example 480 481For a list of options to use with the @code{lilypond} or 482@code{lilypondfile} tags, see @ref{Music fragment options}. 483 484Additionally, @code{<lilypondversion/>} displays the current version 485of lilypond. 486 487 488@cindex titling in HTML 489@cindex preview image 490@cindex thumbnail 491 492@node DocBook 493@subsection DocBook 494@untranslated 495 496For inserting LilyPond snippets it is good to keep the conformity of our 497DocBook document, thus allowing us to use DocBook editors, validation 498etc. So we don't use custom tags, only specify a convention based on the 499standard DocBook elements. 500 501@subheading Common conventions 502 503For inserting all type of snippets we use the @code{mediaobject} and 504@code{inlinemediaobject} element, so our snippets can be formatted 505inline or not inline. The snippet formatting options are always 506provided in the @code{role} property of the innermost element (see in 507next sections). Tags are chosen to allow DocBook editors format the 508content gracefully. The DocBook files to be processed with 509@command{lilypond-book} should have the extension @file{.lyxml}. 510 511@subheading Including a LilyPond file 512 513This is the most simple case. We must use the @file{.ly} extension for 514the included file, and insert it as a standard @code{imageobject}, with 515the following structure: 516 517@example 518<mediaobject> 519 <imageobject> 520 <imagedata fileref="music1.ly" role="printfilename" /> 521 </imageobject> 522</mediaobject> 523@end example 524 525Note that you can use @code{mediaobject} or @code{inlinemediaobject} 526as the outermost element as you wish. 527 528@subheading Including LilyPond code 529 530Including LilyPond code is possible by using a @code{programlisting}, 531where the language is set to @code{lilypond} with the following 532structure: 533 534@example 535<inlinemediaobject> 536 <textobject> 537 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2"> 538\context Staff \with @{ 539 \remove "Time_signature_engraver" 540 \remove "Clef_engraver"@} 541 @{ c4( fis) @} 542 </programlisting> 543 </textobject> 544</inlinemediaobject> 545@end example 546 547As you can see, the outermost element is a @code{mediaobject} or 548@code{inlinemediaobject}, and there is a @code{textobject} containing 549the @code{programlisting} inside. 550 551@subheading Processing the DocBook document 552 553Running @command{lilypond-book} on our @file{.lyxml} file will create a 554valid DocBook document to be further processed with @file{.xml} 555extension. If you use 556@uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex}, it will create a 557PDF file from this document automatically. For HTML (HTML Help, 558JavaHelp etc.) generation you can use the official DocBook XSL 559stylesheets, however, it is possible that you have to make some 560customization for it. 561 562 563@node Kottapéldák paraméterei 564@section Kottapéldák paraméterei 565@translationof Music fragment options 566@untranslated 567 568In the following, a @q{LilyPond command} refers to any command described 569in the previous sections which is handled by @command{lilypond-book} to 570produce a music snippet. For simplicity, LilyPond commands are only 571shown in @LaTeX{} syntax. 572 573Note that the option string is parsed from left to right; if an option 574occurs multiple times, the last one is taken. 575 576The following options are available for LilyPond commands: 577 578@table @code 579@item staffsize=@var{ht} 580Set staff size to @var{ht}, which is measured in points. 581 582@item ragged-right 583Produce ragged-right lines with natural spacing, i.e., 584@code{ragged-right = ##t} is added to the LilyPond snippet. This is the 585default for the @code{\lilypond@{@}} command if no @code{line-width} 586option is present. It is also the default for the @code{lilypond} 587environment if the @code{fragment} option is set, and no line width is 588explicitly specified. 589 590@item noragged-right 591For single-line snippets, allow the staff length to be stretched to 592equal that of the line width, i.e., @code{ragged-right = ##f} is 593added to the LilyPond snippet. 594 595@item line-width 596@itemx line-width=@var{size}\@var{unit} 597Set line width to @var{size}, using @var{unit} as units. @var{unit} is 598one of the following strings: @code{cm}, @code{mm}, @code{in}, or 599@code{pt}. This option affects LilyPond output (this is, the staff 600length of the music snippet), not the text layout. 601 602If used without an argument, set line width to a default value (as 603computed with a heuristic algorithm). 604 605If no @code{line-width} option is given, @command{lilypond-book} tries to 606guess a default for @code{lilypond} environments which don't use the 607@code{ragged-right} option. 608 609@item notime 610Do not print the time signature, and turns off the timing (time signature, 611bar lines) in the score. 612 613@item fragment 614Make @command{lilypond-book} add some boilerplate code so that you can 615simply enter, say, 616 617@example 618c'4 619@end example 620 621@noindent 622without @code{\layout}, @code{\score}, etc. 623 624@item nofragment 625Do not add additional code to complete LilyPond code in music snippets. 626Since this is the default, @code{nofragment} is redundant normally. 627 628@item indent=@var{size}\@var{unit} 629Set indentation of the first music system to @var{size}, using 630@var{unit} as units. @var{unit} is one of the following strings: 631@code{cm}, @code{mm}, @code{in}, or @code{pt}. This option affects 632LilyPond, not the text layout. 633 634@item noindent 635Set indentation of the first music system to zero. This option affects 636LilyPond, not the text layout. Since no indentation is the default, 637@code{noindent} is redundant normally. 638 639@item quote 640Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put 641the output into a quotation block. The value @q{0.4@dmn{in}} can be 642controlled with the @code{exampleindent} option. 643 644@item exampleindent 645Set the amount by which the @code{quote} option indents a music snippet. 646 647@item relative 648@itemx relative=@var{n} 649Use relative octave mode. By default, notes are specified relative to 650middle@tie{}C. The optional integer argument specifies the octave of 651the starting note, where the default @code{1} is middle C. 652@code{relative} option only works when @code{fragment} option is set, 653so @code{fragment} is automatically implied by @code{relative}, 654regardless of the presence of any @code{(no)fragment} option in the 655source. 656@end table 657 658LilyPond also uses @command{lilypond-book} to produce its own 659documentation. To do that, some more obscure music fragment options are 660available. 661 662@table @code 663@item verbatim 664The argument of a LilyPond command is copied to the output file and 665enclosed in a verbatim block, followed by any text given with the 666@code{intertext} option (not implemented yet); then the actual music is 667displayed. This option does not work well with @code{\lilypond@{@}} if 668it is part of a paragraph. 669 670If @code{verbatim} is used in a @code{lilypondfile} command, it is 671possible to enclose verbatim only a part of the source file. If the 672source file contain a comment containing @samp{begin verbatim} (without 673quotes), quoting the source in the verbatim block will start after the 674last occurrence of such a comment; similarly, quoting the source verbatim 675will stop just before the first occurrence of a comment containing 676@samp{end verbatim}, if there is any. In the following source file 677example, the music will be interpreted in relative mode, but the 678verbatim quote will not show the @code{relative} block, i.e. 679 680@example 681\relative @{ % begin verbatim 682 c'4 e2 g4 683 f2 e % end verbatim 684@} 685@end example 686 687@noindent 688will be printed with a verbatim block like 689 690@example 691 c4 e2 g4 692 f2 e 693@end example 694 695@noindent 696If you would like to translate comments and variable names in verbatim 697output but not in the sources, you may set the environment variable 698@code{LYDOC_LOCALEDIR} to a directory path; the directory should 699contain a tree of @file{.mo} message catalogs with @code{lilypond-doc} 700as a domain. 701 702@item texidoc 703(Only for Texinfo output.) If @command{lilypond} is called with the 704@option{--header=@/texidoc} option, and the file to be processed is 705called @file{foo.ly}, it creates a file @file{foo.texidoc} if there 706is a @code{texidoc} field in the @code{\header}. The @code{texidoc} 707option makes @command{lilypond-book} include such files, adding its 708contents as a documentation block right before the music snippet. 709 710Assuming the file @file{foo.ly} contains 711 712@example 713\header @{ 714 texidoc = "This file demonstrates a single note." 715@} 716@{ c'4 @} 717@end example 718 719@noindent 720and we have this in our Texinfo document @file{test.texinfo} 721 722@example 723@@lilypondfile[texidoc]@{foo.ly@} 724@end example 725 726@noindent 727the following command line gives the expected result 728 729@example 730lilypond-book --pdf --process="lilypond \ 731 -dbackend=eps --header=texidoc" test.texinfo 732@end example 733 734Most LilyPond test documents (in the @file{input} directory of the 735distribution) are small @file{.ly} files which look exactly like this. 736 737For localization purpose, if the Texinfo document contains 738@code{@@documentlanguage @var{LANG}} and @file{foo.ly} header 739contains a @code{texidoc@var{LANG}} field, and if @command{lilypond} 740is called with @option{--header=@/texidoc@var{LANG}}, then 741@file{foo.texidoc@var{LANG}} will be included instead of 742@file{foo.texidoc}. 743 744@item doctitle 745(Only for Texinfo output.) This option works similarly to 746@code{texidoc} option: if @command{lilypond} is called with the 747@option{--header=@/doctitle} option, and the file to be processed is 748called @file{foo.ly} and contains a @code{doctitle} field in the 749@code{\header}, it creates a file @file{foo.doctitle}. When 750@code{doctitle} option is used, the contents of @file{foo.doctitle}, 751which should be a single line of @var{text}, is inserted in the 752Texinfo document as @code{@@lydoctitle @var{text}}. 753@code{@@lydoctitle} should be a macro defined in the Texinfo document. 754The same remark about @code{texidoc} processing with localized 755languages also applies to @code{doctitle}. 756 757@item nogettext 758(Only for Texinfo output.) Do not translate comments and variable 759names in the snippet quoted verbatim. 760 761@item printfilename 762If a LilyPond input file is included with @code{\lilypondfile}, print 763the file name right before the music snippet. For HTML output, this 764is a link. Only the base name of the file is printed, i.e. the 765directory part of the file path is stripped. 766 767@end table 768 769 770@node A lilypond-book futtatása 771@section A @command{lilypond-book} futtatása 772@translationof Invoking lilypond-book 773@untranslated 774 775@command{lilypond-book} produces a file with one of the following 776extensions: @file{.tex}, @file{.texi}, @file{.html} or @file{.xml}, 777depending on the output format. All of @file{.tex}, @file{.texi} and 778@file{.xml} files need further processing. 779 780@subheading Format-specific instructions 781 782@subsubheading @LaTeX{} 783 784There are two ways of processing your @LaTeX{} document for printing or 785publishing: getting a PDF file directly with PDF@LaTeX{}, or getting a 786PostScript file with @LaTeX{} via a DVI to PostScript translator like 787@command{dvips}. The first way is simpler and recommended@footnote{Note 788that PDF@LaTeX{} and @LaTeX{} may not be both usable to compile any 789@LaTeX{} document, that is why we explain the two ways.}, and whichever 790way you use, you can easily convert between PostScript and PDF with 791tools, like @command{ps2pdf} and @command{pdf2ps} included in 792Ghostscript package. 793 794To produce a PDF file through PDF@LaTeX{}, use 795 796@example 797lilypond-book --pdf yourfile.lytex 798pdflatex yourfile.tex 799@end example 800 801@cindex outline fonts 802@cindex type1 fonts 803@cindex dvips 804@cindex invoking dvips 805To produce PDF output via @LaTeX{}/@command{dvips}/@command{ps2pdf}, you 806should do 807 808@example 809lilypond-book yourfile.lytex 810latex yourfile.tex 811dvips -Ppdf yourfile.dvi 812ps2pdf yourfile.ps 813@end example 814 815@noindent 816The @file{.dvi} file created by this process will not contain 817 note heads. This is normal; if you follow the instructions, they 818will be included in the @file{.ps} and @file{.pdf} files. 819 820Running @command{dvips} may produce some warnings about fonts; these 821are harmless and may be ignored. If you are running @command{latex} in 822twocolumn mode, remember to add @code{-t landscape} to the 823@command{dvips} options. 824 825@subsubheading Texinfo 826 827To produce a Texinfo document (in any output format), follow the normal 828procedures for Texinfo; this is, either call @command{texi2pdf} or 829@command{texi2dvi} or @command{makeinfo}, depending on the output format 830you want to create. 831@ifinfo 832@xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, and @ref{Creating 833an Info File, , , texinfo, GNU Texinfo}. 834@end ifinfo 835@ifnotinfo 836See the documentation of Texinfo for further details. 837@end ifnotinfo 838 839 840@subheading Command line options 841 842@command{lilypond-book} accepts the following command line options: 843 844@table @code 845@item -f @var{format} 846@itemx --format=@var{format} 847Specify the document type to process: @code{html}, @code{latex}, 848@code{texi} (the default) or @code{docbook}. If this option is missing, 849@command{lilypond-book} tries to detect the format automatically, see 850@ref{Filename extensions}. Currently, @code{texi} is the same as 851@code{texi-html}. 852 853@c This complicated detail is not implemented, comment it out -jm 854@ignore 855The @code{texi} document type produces a Texinfo file with music 856fragments in the printed output only. For getting images in the HTML 857version, the format @code{texi-html} must be used instead. 858@end ignore 859 860@item -F @var{filter} 861@itemx --filter=@var{filter} 862Pipe snippets through @var{filter}. @code{lilypond-book} will 863not --filter and --process at the same time. For example, 864 865@example 866lilypond-book --filter='convert-ly --from=2.0.0 -' my-book.tely 867@end example 868 869@item -h 870@itemx --help 871Print a short help message. 872 873@item -I @var{dir} 874@itemx --include=@var{dir} 875Add @var{dir} to the include path. @command{lilypond-book} also looks 876for already compiled snippets in the include path, and does not write 877them back to the output directory, so in some cases it is necessary to 878invoke further processing commands such as @command{makeinfo} or 879@command{latex} with the same @code{-I @var{dir}} options. 880 881@item -o @var{dir} 882@itemx --output=@var{dir} 883Place generated files in directory @var{dir}. Running 884@command{lilypond-book} generates lots of small files that LilyPond will 885process. To avoid all that garbage in the source directory, use the 886@option{--output} command line option, and change to that directory 887before running @command{latex} or @command{makeinfo}. 888 889@example 890lilypond-book --output=out yourfile.lytex 891cd out 892... 893@end example 894 895@itemx --skip-lily-check 896Do not fail if no lilypond output is found. It is used for LilyPond 897Info documentation without images. 898 899@itemx --skip-png-check 900Do not fail if no PNG images are found for EPS files. It is used for 901LilyPond Info documentation without images. 902 903@itemx --lily-output-dir=@var{dir} 904Write lily-XXX files to directory @var{dir}, link into @code{--output} 905directory. Use this option to save building time for documents in 906different directories which share a lot of identical snippets. 907 908@itemx --info-images-dir=@var{dir} 909Format Texinfo output so that Info will look for images of music in 910@var{dir}. 911 912@itemx --latex-program=@var{prog} 913Run executable @command{prog} instead of @command{latex}. This is 914useful if your document is processed with @command{xelatex}, for 915example. 916 917@itemx --left-padding=@var{amount} 918Pad EPS boxes by this much. @var{amount} is measured in millimeters, 919and is 3.0 by default. This option should be used if the lines of 920music stick out of the right margin. 921 922The width of a tightly clipped system can vary, due to notation 923elements that stick into the left margin, such as bar numbers and 924instrument names. This option will shorten each line and move each 925line to the right by the same amount. 926 927@item -P @var{command} 928@itemx --process=@var{command} 929Process LilyPond snippets using @var{command}. The default command is 930@code{lilypond}. @code{lilypond-book} will not @code{--filter} and 931@code{--process} at the same time. 932 933@item --pdf 934Create PDF files for use with PDF@LaTeX{}. 935 936@itemx --use-source-file-names 937Write snippet output files with the same base name as their source file. 938This option works only for snippets included with @code{lilypondfile} 939and only if directories implied by @code{--output-dir} and 940@code{--lily-output-dir} options are different. 941 942@item -V 943@itemx --verbose 944Be verbose. 945 946@item -v 947@itemx --version 948Print version information. 949@end table 950 951@knownissues 952 953The Texinfo command @code{@@pagesizes} is not interpreted. Similarly, 954@LaTeX{} commands that change margins and line widths after the preamble 955are ignored. 956 957Only the first @code{\score} of a LilyPond block is processed. 958 959 960@node Fájlkiterjesztések 961@section Fájlkiterjesztések 962@translationof Filename extensions 963@untranslated 964 965You can use any filename extension for the input file, but if you do not 966use the recommended extension for a particular format you may need to 967manually specify the output format; for details, see @ref{Invoking 968lilypond-book}. Otherwise, @command{lilypond-book} automatically 969selects the output format based on the input filename's extension. 970 971@quotation 972@multitable @columnfractions .2 .5 973@item @strong{extension} @tab @strong{output format} 974@item 975@item @file{.html} @tab HTML 976@item @file{.htmly} @tab HTML 977@item @file{.itely} @tab Texinfo 978@item @file{.latex} @tab @LaTeX{} 979@item @file{.lytex} @tab @LaTeX{} 980@item @file{.lyxml} @tab DocBook 981@item @file{.tely} @tab Texinfo 982@item @file{.tex} @tab @LaTeX{} 983@item @file{.texi} @tab Texinfo 984@item @file{.texinfo} @tab Texinfo 985@item @file{.xml} @tab HTML 986@end multitable 987@end quotation 988 989If you use the same filename extension for the input file than the 990extension @command{lilypond-book} uses for the output file, and if the 991input file is in the same directory as @command{lilypond-book} working 992directory, you must use @code{--output} option to make 993@command{lilypond-book} running, otherwise it will exit with an error 994message like @qq{Output would overwrite input file}. 995 996 997@node lilypond-book sablonok 998@section lilypond-book sablonok 999@translationof lilypond-book templates 1000@untranslated 1001 1002These templates are for use with @code{lilypond-book}. If you're not familiar 1003with this program, please refer to 1004@ref{lilypond-book}. 1005 1006@subsection LaTeX 1007 1008You can include LilyPond fragments in a LaTeX document. 1009 1010@example 1011\documentclass[]@{article@} 1012 1013\begin@{document@} 1014 1015Normal LaTeX text. 1016 1017\begin@{lilypond@} 1018\relative @{ 1019 a'4 b c d 1020@} 1021\end@{lilypond@} 1022 1023More LaTeX text, and options in square brackets. 1024 1025\begin@{lilypond@}[fragment,relative=2,quote,staffsize=26,verbatim] 1026d4 c b a 1027\end@{lilypond@} 1028\end@{document@} 1029@end example 1030 1031@subsection Texinfo 1032 1033You can include LilyPond fragments in Texinfo; in fact, this entire manual 1034is written in Texinfo. 1035 1036@example 1037\input texinfo @c -*-texinfo-*- 1038@@node Top 1039@@top 1040 1041Texinfo text 1042 1043@@lilypond 1044\relative @{ 1045 a4 b c d 1046@} 1047@@end lilypond 1048 1049More Texinfo text, and options in brackets. 1050 1051@@lilypond[verbatim,fragment,ragged-right] 1052d4 c b a 1053@@end lilypond 1054 1055@@bye 1056@end example 1057 1058 1059@subsection html 1060 1061@example 1062<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 1063<!-- header_tag --> 1064<HTML> 1065<body> 1066 1067<p> 1068Documents for lilypond-book may freely mix music and text. For 1069example, 1070<lilypond> 1071\relative @{ 1072 a'4 b c d 1073@} 1074</lilypond> 1075</p> 1076 1077<p> 1078Another bit of lilypond, this time with options: 1079 1080<lilypond fragment quote staffsize=26 verbatim> 1081a4 b c d 1082</lilypond> 1083</p> 1084 1085</body> 1086</html> 1087 1088 1089@end example 1090 1091@subsection xelatex 1092 1093@verbatim 1094\documentclass{article} 1095\usepackage{ifxetex} 1096\ifxetex 1097%xetex specific stuff 1098\usepackage{xunicode,fontspec,xltxtra} 1099\setmainfont[Numbers=OldStyle]{Times New Roman} 1100\setsansfont{Arial} 1101\else 1102%This can be empty if you are not going to use pdftex 1103\usepackage[T1]{fontenc} 1104\usepackage[utf8]{inputenc} 1105\usepackage{mathptmx}%Times 1106\usepackage{helvet}%Helvetica 1107\fi 1108%Here you can insert all packages that pdftex also understands 1109\usepackage[ngerman,finnish,english]{babel} 1110\usepackage{graphicx} 1111 1112\begin{document} 1113\title{A short document with LilyPond and xelatex} 1114\maketitle 1115 1116Normal \textbf{font} commands inside the \emph{text} work, 1117because they \textsf{are supported by \LaTeX{} and XeteX.} 1118If you want to use specific commands like \verb+\XeTeX+, you 1119should include them again in a \verb+\ifxetex+ environment. 1120You can use this to print the \ifxetex \XeTeX{} command \else 1121XeTeX command \fi which is not known to normal \LaTeX . 1122 1123In normal text you can easily use LilyPond commands, like this: 1124 1125\begin{lilypond} 1126{a2 b c'8 c' c' c'} 1127\end{lilypond} 1128 1129\noindent 1130and so on. 1131 1132The fonts of snippets set with LilyPond will have to be set from 1133inside 1134of the snippet. For this you should read the AU on how to use 1135lilypond-book. 1136 1137\selectlanguage{ngerman} 1138Auch Umlaute funktionieren ohne die \LaTeX -Befehle, wie auch alle 1139anderen 1140seltsamen Zeichen: __ ______, wenn sie von der Schriftart 1141unterst__tzt werden. 1142\end{document} 1143@end verbatim 1144 1145 1146@node Közös tartalomjegyzék 1147@section Közös tartalomjegyzék 1148@translationof Sharing the table of contents 1149@untranslated 1150 1151These functions already exist in the OrchestralLily package: 1152 1153@example 1154@url{http://repo.or.cz/w/orchestrallily.git} 1155@end example 1156 1157For greater flexibility in text handling, some users prefer to 1158export the table of contents from lilypond and read it into 1159@LaTeX{}. 1160 1161@subsubheading Exporting the ToC from LilyPond 1162 1163This assumes that your score has multiple movements in the same lilypond 1164output file. 1165 1166@smallexample 1167#(define (oly:create-toc-file layout pages) 1168 (let* ((label-table (ly:output-def-lookup layout 'label-page-table))) 1169 (if (not (null? label-table)) 1170 (let* ((format-line (lambda (toc-item) 1171 (let* ((label (car toc-item)) 1172 (text (caddr toc-item)) 1173 (label-page (and (list? label-table) 1174 (assoc label label-table))) 1175 (page (and label-page (cdr label-page)))) 1176 (format #f "~a, section, 1, @{~a@}, ~a" page text label)))) 1177 (formatted-toc-items (map format-line (toc-items))) 1178 (whole-string (string-join formatted-toc-items ",\n")) 1179 (output-name (ly:parser-output-name)) 1180 (outfilename (format #f "~a.toc" output-name)) 1181 (outfile (open-output-file outfilename))) 1182 (if (output-port? outfile) 1183 (display whole-string outfile) 1184 (ly:warning (_ "Unable to open output file ~a for the TOC information") outfilename)) 1185 (close-output-port outfile))))) 1186 1187\paper @{ 1188 #(define (page-post-process layout pages) (oly:create-toc-file layout pages)) 1189@} 1190@end smallexample 1191 1192@subsubheading Importing the ToC into LaTeX 1193 1194In LaTeX, the header should include: 1195 1196@c no, this doesn't require the smallexample, but since the other 1197@c two blocks on this page use it, I figured I might as well 1198@c user it here as well, for consistency. -gp 1199@smallexample 1200\usepackage@{pdfpages@} 1201\includescore@{nameofthescore@} 1202@end smallexample 1203 1204@noindent 1205where @code{\includescore} is defined as: 1206 1207@smallexample 1208%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1209% \includescore@{PossibleExtension@} 1210%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 1211 1212% Read in the TOC entries for a PDF file from the corresponding .toc file. 1213% This requires some heave latex tweaking, since reading in things from a file 1214% and inserting it into the arguments of a macro is not (easily) possible 1215 1216% Solution by Patrick Fimml on #latex on April 18, 2009: 1217% \readfile@{filename@}@{\variable@} 1218% reads in the contents of the file into \variable (undefined if file 1219% doesn't exist) 1220\newread\readfile@@f 1221\def\readfile@@line#1@{% 1222@{\catcode`\^^M=10\global\read\readfile@@f to \readfile@@tmp@}% 1223\edef\do@{\noexpand\g@@addto@@macro@{\noexpand#1@}@{\readfile@@tmp@}@}\do% 1224\ifeof\readfile@@f\else% 1225\readfile@@line@{#1@}% 1226\fi% 1227@} 1228\def\readfile#1#2@{% 1229\openin\readfile@@f=#1 % 1230\ifeof\readfile@@f% 1231\typeout@{No TOC file #1 available!@}% 1232\else% 1233\gdef#2@{@}% 1234\readfile@@line@{#2@}% 1235\fi 1236\closein\readfile@@f% 1237@}% 1238 1239 1240\newcommand@{\includescore@}[1]@{ 1241\def\oly@@fname@{\oly@@basename\@@ifmtarg@{#1@}@{@}@{_#1@}@} 1242\let\oly@@addtotoc\undefined 1243\readfile@{\oly@@xxxxxxxxx@}@{\oly@@addtotoc@} 1244\ifx\oly@@addtotoc\undefined 1245\includepdf[pages=-]@{\oly@@fname@} 1246\else 1247\edef\includeit@{\noexpand\includepdf[pages=-,addtotoc=@{\oly@@addtotoc@}] 1248@{\oly@@fname@}@}\includeit 1249\fi 1250@} 1251@end smallexample 1252 1253 1254@node További módszerek zene és szöveg kombinálására 1255@section További módszerek zene és szöveg kombinálására 1256@translationof Alternate methods of mixing text and music 1257@untranslated 1258 1259Other means of mixing text and music (without 1260@command{lilypond-book}) are discussed in 1261@ref{LilyPond output in other programs}. 1262