Documentation/de/user/lilypond-book.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
   2 @c This file is part of lilypond-program.tely
   3 @ignore
   4     Translation of GIT committish: 3ab56c82129c4e70a2a23af040be70817feb8b00
   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 @node LilyPond-book
  12 @chapter @command{lilypond-book}: Integrating text and music
  13
  14
  15 Wenn Sie in ein Dokument Bilder von Musiknoten einfügen möchten, so können
  16 Sie genauso machen, wie Sie andere Bilder einfügen würden: Die Bilder
  17 werden getrennt vom Dokument im PostSciprt oder PNG Format erstellt
  18 und können dann in @LaTeX{} oder HTML inkludiert werden.
  19
  20 @command{lilypond-book} automatisiert diesen Prozess: Dieses
  21 Programm extrahiert Musik-Schnipsel aus Ihrem Dokument,
  22 ruft @command{lilypond} auf und fügt die resultierenden Bilder
  23 in Ihr Dokument ein. Die Länge der Zeilen und die Schriftgroße
  24 werden dabei Ihrem Dokument angepasst.
  25
  26 @command{lilypond-book} ist ein eigenständiges Programm und wird
  27 üblicherweise von der Kommandozeile aufgerufen. Nähere Informationen
  28 hierzu finden sich in @ref{Command-line usage}.
  29
  30 Dieses Vorgehen kann bei @LaTeX{}, HTML, Texinfo oder DocBook Dokumenten
  31 angewendet werden.
  32
  33 @cindex texinfo
  34 @cindex latex
  35 @cindex texinfo
  36 @cindex texi
  37 @cindex html
  38 @cindex docbook
  39 @cindex Dokument, Musik einfügen in
  40 @cindex HTML, Musik in
  41 @cindex Texinfo, Musik in
  42 @cindex DocBook, Musik in
  43 @cindex @LaTeX{}, Musik in
  44
  45
  46 @menu
  47 * An example of a musicological document::
  48 * Integrating music and text::
  49 * Music fragment options::
  50 * Invoking lilypond-book::
  51 * Filename extensions::
  52 * Alternate methods of mixing text and music::
  53 @end menu
  54
  55 @node An example of a musicological document
  56 @section An example of a musicological document
  57
  58
  59 @cindex Musikwissenschaft
  60
  61 Zahlreiche Texte enthalten Musikbeispiele: musikwissenschaftliche
  62 Abhandlungen, Liederbücher oder Handbücher wie dieses. Solche
  63 Texte können händisch erzeugt werden, indem einfach die Musikbeispiele
  64 als Grafik (PostScript, PNG, GIF, etc.) im Textverarbeitungsprogramm
  65 eingefügt werden. Für HTML, @LaTeX{}, Texinfo und DocBook Dokumente
  66 existiert jedoch ein Weg, dies automatisiert durchzuführen.
  67
  68 Das Programm @code{lilypond-book} extrahiert die Musikfragmente aus
  69 dem Dokument, formatiert sie automatisiert in eine Grafik und fügt die
  70 resultierenden Notenbeispiele dann wieder in das Dokument ein. Dies soll
  71 hier an einem einfachen @LaTeX{}-Beispiel verdeutlicht werden. Das Beispiel
  72 selbst enhält schon Erklärungen, sodass wir es hier nicht weiter diskutieren
  73 müssen.
  74
  75 @subheading Input
  76
  77 @quotation
  78 @verbatim
  79 \documentclass[a4paper]{article}
  80
  81 \begin{document}
  82
  83 Dokumente für \verb+lilypond-book+ können Musik und Text nach Belieben
  84 kombinieren. Zum Beispiel:
  85
  86 \begin{lilypond}
  87 \relative c' {
  88   c2 g'2 \times 2/3 { f8 e d } c'2 g4
  89 }
  90 \end{lilypond}
  91
  92 Optionen für \verb+lilypond+ werden dabei in eckige Klammern gesetzt.
  93
  94 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
  95   c'4 f16
  96 \end{lilypond}
  97
  98 Größere Beispiele können auch in einer eigenständigen Datei gespeichert
  99 und dann mit \verb+\lilypondfile+ eingebunden werden.
 100
 101 \lilypondfile[quote,noindent]{screech-boink.ly}
 102
 103 (Falls nötig kann screech-boink.ly durch eine beliebige andere .ly
 104 Datei im selben Verzeichnis wie diese Datei ersetzt werden.)
 105
 106 \end{document}
 107 @end verbatim
 108 @end quotation
 109
 110 @subheading Processing
 111
 112 Speichern Sie den obigen @LaTeX{} Quellcode in eine Datei @file{lilybook.lytex}
 113 und führen Sie dann in der Kommandozeile folgende Befehle aus:
 114
 115 @c keep space after @version{} so TeX doesn't choke
 116 @example
 117 lilypond-book --output=out --pdf lilybook.lytex
 118 @emph{lilypond-book (GNU LilyPond) @version{} }
 119 @emph{Reading lilybook.lytex...}
 120 @emph{..(viele Ausgabezeilen entfernt)..}
 121 @emph{Compiling lilybook.tex...}
 122 cd out
 123 pdflatex lilybook
 124 @emph{..(viele Ausgabezeilen entfernt)..}
 125 xpdf lilybook
 126 @emph{(Ersetzen Sie @command{xpdf} durch Ihren PDF-Betrachter)}
 127 @end example
 128
 129 Die Ausführung von @command{lilypond-book} und @command{latex} erzeugt
 130 zahlreiche temporäre Dateien, die das Arbeitsverzeichnis unnötig
 131 vollstopfen würden. Daher empfiehlt sich die Benutztung der @code{--output=@var{dir}}
 132 Option, wodurch die Dateien im Unterverzeichnis @file{dir} erzeugt werden.
 133
 134 Das Endresultat des obigen @LaTeX{} Beispiels ist im nächsten Abschnitt
 135 zu sehen.@footnote{Da dieses Handbuch mit Texinfo erzeugt wurde,
 136 kann sich das Aussehen des Beispiels leicht von dem mit @LaTeX{}
 137 erzeugten unterscheiden.}
 138 tutorial is processed with Texinfo, so the example gives slightly
 139 different results in layout.}
 140
 141 @page
 142
 143 @subheading Output
 144
 145 Dokumente für @command{lilypond-book} können Musik und Text nach Belieben
 146 kombinieren. Zum Beispiel:
 147
 148 @lilypond
 149 \relative c' {
 150   c2 g'2 \times 2/3 { f8 e d } c'2 g4
 151 }
 152 @end lilypond
 153
 154 Optionen für @command{lilypond} werden dabei in eckige Klammern gesetzt.
 155
 156 @lilypond[fragment,quote,staffsize=26,verbatim]
 157 c'4 f16
 158 @end lilypond
 159
 160 Größere Beispiele können auch in einer eigenständigen Datei gespeichert
 161 und dann mit @code{\lilypondfile} eingebunden werden.
 162
 163 @lilypondfile[quote,noindent]{screech-boink.ly}
 164
 165
 166 @page
 167
 168
 169
 170 @node Integrating music and text
 171 @section Integrating music and text
 172
 173 In diesem Abschnitt soll die Integration von LilyPond mit den
 174 verschiedenen Dateiformaten detalliert erläutert werden.
 175
 176
 177 @menu
 178 * LaTeX::
 179 * Texinfo::
 180 * HTML::
 181 * DocBook::
 182 @end menu
 183
 184 @node LaTeX
 185 @subsection @LaTeX{}
 186
 187
 188 @LaTeX{} ist der de-facto Standard zur Publikation von wissenschaftlichen Texten
 189 in Naturwissenschaft und Technik. Es basiert auf dem Schriftsetzer @TeX{},
 190 der die bestmögliche Typographie erzeugt.
 191
 192 Siehe die @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/german/,
 193 @emph{@LaTeX{} 2@epsilon{}-Kurzbeschreibung}} für eine Einführung in die
 194 Benutzung von @LaTeX{}.
 195
 196 Musikbeispiele können eingegeben werden als
 197
 198 @example
 199 \begin[Optionen,kommen,]@{lilypond@}
 200   IHR LILYPOND QUELLCODE
 201 \end@{lilypond@}
 202 @end example
 203
 204 @noindent
 205 oder
 206
 207 @example
 208 \lilypondfile[Optionen,kommen,hier]@{@var{Dateiname}@}
 209 @end example
 210
 211 @noindent
 212 oder
 213
 214 @example
 215 \lilypond@{ IHR LILYPOND QUELLCODE @}
 216 @end example
 217
 218 Der Aufruf von @command{lilypond-book} liefert eine Datei, die dann mit
 219 @LaTeX{} weiter verarbeitet werden kann.
 220
 221 Dies soll hier an einigen Beispielen gezeigt werden. Die @code{lilypond} Umgebung
 222
 223 @example
 224 \begin[quote,fragment,staffsize=26]@{lilypond@}
 225   c' d' e' f' g'2 g'2
 226 \end@{lilypond@}
 227 @end example
 228
 229 @noindent
 230 erzeugt
 231
 232 @lilypond[quote,fragment,staffsize=26]
 233 c' d' e' f' g'2 g'2
 234 @end lilypond
 235
 236 Die Kurzversion
 237
 238 @example
 239 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
 240 @end example
 241
 242 @noindent
 243 erzeugt
 244
 245 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
 246
 247 @noindent
 248 Innerhalb des @code{\lilypond@{@}} Befehls dürfen keine geschwungenen
 249 Klammern @code{@{} oder @code{@}} vorkommen, weshalb dieser Befehl
 250 nur mit der @code{fragment} Option Sinn macht.
 251
 252 Die Standardzeilenlänge wird bestimmt, indem die Angaben in der Dokumentpräambel,
 253 alse dem Teil der @LaTeX{} Datei vor dem @code{\begin@{document@}},
 254 analysiert werden. Der @command{lilypond-book} Befehl sendet diese
 255 Angaben an @LaTeX{}, um herauszufinden, wie breit der Text tatsächlich
 256 ist. Die Breite der Notenzeilen wird dann an diese Textbreite angepasst.
 257 Ein derartig heuristischer Algorithmuss kann natürlich auch versagen,
 258 wobei man in diesem Fall die Breite auch explizit durch die
 259 @code{line-width} Option des @code{\lilypond@{@}} oder @code{\begin@{lilypond@}}
 260 Befehls angeben kann.
 261
 262 @cindex titling and lilypond-book
 263 @cindex \header in @LaTeX{} documents
 264
 265 Jedes Musikbeispiele ruft die folgenden Makros auf, wenn sie vom Benutzer
 266 definiert wurden:
 267
 268 @itemize bullet
 269 @item @code{\preLilyPondExample} -- wird vor der Musik aufgerufen,
 270
 271 @item @code{\postLilyPondExample} -- wird nach der Musik aufgerufen,
 272
 273 @item @code{\betweenLilyPondSystem[1]} -- wird zwischen den einzelnen
 274 Systemen aufgerufen, wenn @code{lilypond-book} das Beispiel in verschiedene
 275 PostScript Dateien getrennt hat. Dieser @LaTeX{}-Befehl muss so definiert
 276 werden, dass er genau ein Argument erhält, nämlich die Zahl der bereits
 277 in @LaTeX{} eingefügten Dateien dieses Beispiels. Als Standard wird einfach
 278 ein @code{\linebreak} eingefügt.
 279 @end itemize
 280
 281 @ignore
 282 Broken stuff.  :(
 283
 284 @cindex Latex, Feta Schriftart
 285 @cindex fetachar
 286
 287 Um Zeichen wie Auflösungszeichen, Kreuze, Fermaten etc. aus der Feta-Schriftart
 288 von LilyPond in @LaTeX{} einzufügen, muss @code{\input@{titledefs@}} benutzt werden,
 289 wodurch dann der Befehl @code{\fetachar} zur Verfügung steht.
 290
 291 @example
 292 \documentclass[a4paper]@{article@}
 293
 294 \input@{titledefs@}
 295
 296 \begin@{document@}
 297
 298 \fetachar\fetasharp
 299
 300 \end@{document@}
 301 @end example
 302
 303 Die Namen der Symbole sind in der Datei @file{feta20.tex} definiert. Sie finden
 304 den Pfad zu dieser Datei mit dem Befehl
 305
 306 @example
 307 kpsewhich feta20.tex
 308 @end example
 309
 310 @end ignore
 311
 312 @snippets
 313
 314 Manchmal ist es nötig, Musikelemente wie Halte- oder Bindebögen so darzustellen,
 315 als ob sie am Ende des Musikausschnitten noch weitergehen würden. Eine solche
 316 Ausgabe kann erreicht werden, indem ein Zeilenumbruch in die Notenzeile
 317 eingefügt wird und die Ausgabe der folgenden Notenzeile unterdrückt wird.
 318
 319 In @LaTeX{} wird dazu der Befehl @code{\betweenLilyPondSystem} einfach derartig
 320 programmiert, dass die Ausgabe der einzelnen Notensysteme abgebrochen wird,
 321 sobald die gewünschte Anzahl an Systemen erreicht ist. Da
 322 @code{\betweenLilyPondSystem} zum ersten Mal nach dem ersten System aufgerufen
 323 wird, ist die Ausgabe nur eines Systems trivial.
 324
 325 @example
 326 \def\betweenLilyPondSystem#1@{\endinput@}
 327
 328 \begin[fragment]@{lilypond@}
 329   c'1\( e'( c'~ \break c' d) e f\)
 330 \end@{lilypond@}
 331 @end example
 332
 333 Um eine größere Zahl an System nötig, dann muss dementsprechend eine
 334 @TeX{}-Bedingung vor dem @code{\endinput} benutzt werden:
 335
 336 @example
 337 \def\betweenLilyPondSystem#1@{
 338     \ifnum##1<2\else\endinput\fi
 339 @}
 340 @end example
 341
 342 Dieses Beispiel bricht nach genau zwei ausgegebenen Notenzeilen ab.
 343 Für eine andere Anzahl braucht nur @q{2} durch die entsprechende
 344 Anzahl ersetzt werden.
 345
 346 Die Definition von @code{\betweenLilyPondSystem} bleibt gültig,
 347 bis @TeX{} die aktuelle Umgebung in @LaTeX{} verlässt oder der
 348 Befehl durch eine neue Definition überschrieben wird.
 349 Dies kann etwa folgendermaßen in der @LaTeX{}-Datei geschehen:
 350
 351 @example
 352 \let\betweenLilyPondSystem\undefined
 353 @end example
 354
 355 Obige Definition von @code{\betweenLilyPondSystem} kann durch die
 356 Definition eines @TeX{}-Makros auch verallgemeinert werden,
 357
 358 @example
 359 \def\onlyFirstNSystems#1@{
 360     \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
 361 @}
 362 @end example
 363
 364 @noindent
 365 wobei diesem Makro @code{\onlyFirstNSystems} einfach die Anzahl der
 366 gewünschten Systeme übergeben wird:
 367
 368 @example
 369 \onlyFirstNSystems@{3@}
 370 \begin@{lilypond@}...\end@{lilypond@}
 371 \onlyFirstNSystems@{1@}
 372 \begin@{lilypond@}...\end@{lilypond@}
 373 @end example
 374
 375 @seealso
 376 @command{lilypond-book} stellt auch zahlreiche Kommandozeilen-Optionen zur
 377 Verfügung. Für eine Liste dieser Optionen und andere hilfreiche Details zur
 378 Verarbeitung von @LaTeX{}-Kokumenten, siehe @ref{Invoking lilypond-book}.
 379
 380
 381
 382
 383 @node Texinfo
 384 @subsection Texinfo
 385
 386 Texinfo ist das Standard-Dokumentationsformat des GNU Projekts. Ein Beispiel
 387 für ein Dokument im Texinfo Format ist dieses Handbuch, wobei die HTML-, PDF- und
 388 Info-Versionen alle aus demselben Texinfo Dokument erzeugt werden.
 389
 390 In der Eingabedatei wir Musik eingegeben als
 391
 392 @example
 393 @@lilypond[Optionen,kommen,hier]
 394   IHR LILYPOND QUELLCODE
 395 @@end lilypond
 396 @end example
 397
 398 @noindent
 399 oder
 400
 401 @example
 402 @@lilypond[Optionen,kommen,hier]@{ IHR LILYPOND QUELLCODE @}
 403 @end example
 404
 405 @noindent
 406 oder
 407
 408 @example
 409 @@lilypondfile[Optionen,kommen,hier]@{@var{Dateiname}@}
 410 @end example
 411
 412 Wenn @command{lilypond-book} eine derartige Datei verarbeitet,
 413 wird eine Texinfo-Datei mit der Erweiterung @file{.texi} erzeugt,
 414 die @code{@@image} Befehle für die Ausgabe nach HTML, Info und PDF
 415 enthält. @command{lilypond-book} erzeugt die entsprechenden Grafiken
 416 der Musikbeispiele im EPS- und PDF-Format für die Ausgabe nach PDF
 417 und im PNG-Format für die Ausgabe nach HTML und Info.
 418
 419 Hier sollen zwei einfache Beispiele gezeigt werden. Eine @code{lilypond} Umgebung
 420
 421 @example
 422 @@lilypond[fragment]
 423 c' d' e' f' g'2 g'
 424 @@end lilypond
 425 @end example
 426
 427 @noindent
 428 erzeugt
 429
 430 @lilypond[fragment]
 431 c' d' e' f' g'2 g'
 432 @end lilypond
 433
 434 Die Kurzversion
 435
 436 @example
 437 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
 438 @end example
 439
 440 @noindent
 441 erzeugt
 442
 443 @lilypond[fragment,staffsize=11]{<c' e' g'>}
 444
 445 Im Gegensatz zu @LaTeX{} erzeugt @code{@@lilypond@{...@}} allerdings keine Grafik
 446 im Fließtext, sondern setzt sie immer in einen eigenen Absatz.
 447
 448
 449 @node HTML
 450 @subsection HTML
 451
 452 Musik wird eingegeben als
 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} erzeugt dann daraud eine HTML-Datei mit den entsprechenden
 462 @code{<image>} Tags für die Musikbeispiele in jeweils einem eigenen Absatz.
 463
 464
 465 @lilypond[fragment,relative=2]
 466 \key c \minor c4 es g2
 467 @end lilypond
 468
 469 Für Grafiken im Fließtext kann @code{<lilypond ... />} benutzt werden, wobei
 470 die Optionen durch einen Doppelpunkt von der Musik getrennt angegeben werden.
 471
 472 @example
 473 Musik <lilypond relative=2: a b c/> in derselben Zeile.
 474 @end example
 475
 476 Um Dateien mit Musik einzubinden, kann folgendermaßen vorgegangen werden:
 477
 478 @example
 479 <lilypondfile @var{option1} @var{option2} ...>@var{filename}</lilypondfile>
 480 @end example
 481
 482
 483
 484 @node DocBook
 485 @subsection DocBook
 486
 487
 488 Bei der Einbindung von Musik im LilyPond-Format in DocBook soll die
 489 Konformität unseres DocBook Dokuments erhalten bleiben und damit
 490 die Bearbeiten mit DocBook-Editoren sowie die Validierung weiter
 491 möglich bleiben. Aus diesem Grund werden in DocBook keine eigenen Tags
 492 wie in HTML benutzt, sondern die von den vorhandenen DocBook-Elementen
 493 vorgegebenen Konventionen entsprechend benützt.
 494
 495 @subheading Common conventions
 496
 497 Für die Einbindung von LilyPond Code werden in allen Fällen die
 498 @code{mediaobject} und @code{inlinemediaobject} Elemente benutzt,
 499 die unsere Beispiele in einem eigenen Absatz oder im Fließtext
 500 einfügen. Die Optionen zur Formatierung mit LilyPond werden dabei
 501 in der @code{role} Eigenschaft des innersten Elements angegeben,
 502 wie im nächsten Abschnitt gezeigt wird. Die DocBook Datei, die
 503 dann von @command{lilypond-book} verarbeitet wird, sollte der Klarheit
 504 halber die  Dateierweiterung @file{.lyxml} (jedenfalls nicht
 505 @ref{.xml}) besitzen.
 506
 507 @subheading Including a LilyPond file
 508
 509 Dies ist der einfachste Fall: Die LilyPond-Datei besitzt die Erweiterung
 510 @file{.ly} und wird einfach als @code{imageobject} eingebettet:
 511
 512 @example
 513 <mediaobject>
 514   <imageobject>
 515     <imagedata fileref="music1.ly" role="printfilename" />
 516   </imageobject>
 517 </mediaobject>
 518 @end example
 519
 520 Für das äußerste Element kann je nach Bedarf @code{mediaobject} oder
 521 @code{inlinemediaobject} benutzt werden.
 522
 523 @subheading Including LilyPond code
 524
 525 Die Einbindung von LilyPond-Code direkt in der DocBook-Datei ist
 526 durch die Benutzung von @code{programlisting} möglich,
 527 wobei die Sprache auf @code{lilypond} gesetzt wird:
 528
 529 @example
 530 <inlinemediaobject>
 531   <textobject>
 532     <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
 533 \context Staff \with @{
 534   \remove Time_signature_engraver
 535   \remove Clef_engraver@}
 536   @{ c4( fis) @}
 537     </programlisting>
 538   </textobject>
 539 </inlinemediaobject>
 540 @end example
 541
 542 Das äußerste Element ist also @code{mediaobject} oder
 543 @code{inlinemediaobject}, welches ein @code{textobject} mit dem
 544 @code{programlisting} enthält.
 545
 546 @subheading Processing the DocBook document
 547
 548 Der Aufruf von @command{lilypond-book} mit der @file{.lyxml}-Datei
 549 erzeugt ein gültiges DocBook-Dokument mit der Erweiterung @file{.xml},
 550 welches normal weiterverarbeitet werden kann. Bei Benützung von
 551 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex} wird daraus
 552 automatisch eine PDF-Datei erzeugt. Für die Erzeugung von HTML (HTML
 553 Help, JavaHelp, etc.) können doe offiziellen DocBook XSL-Stylesheets
 554 benutzt werden. Eventuell müssen dafür allerdings kleinere Anpassungen
 555 vorgenommen werden.
 556
 557
 558 @node Music fragment options
 559 @section Music fragment options
 560
 561 @untranslated
 562
 563
 564 @node Invoking lilypond-book
 565 @section Invoking @command{lilypond-book}
 566
 567 @untranslated
 568
 569
 570 @subheading Format-specific instructions
 571 @subsubheading @LaTeX{}
 572 @subsubheading Texinfo
 573 @subheading Command line options
 574 @node Filename extensions
 575 @section Filename extensions
 576
 577 @untranslated
 578
 579
 580 @node Alternate methods of mixing text and music
 581 @section Alternative methods of mixing text and music
 582
 583 @untranslated
 584
 585
 586 @menu
 587 * Many quotes from a large score::
 588 * Inserting LilyPond output into OpenOffice.org::
 589 * Inserting LilyPond output into other programs::
 590 @end menu
 591
 592 @node Many quotes from a large score
 593 @subsection Many quotes from a large score
 594
 595 @untranslated
 596
 597
 598 @node Inserting LilyPond output into OpenOffice.org
 599 @subsection Inserting LilyPond output into OpenOffice.org
 600
 601 @untranslated
 602
 603
 604 @node Inserting LilyPond output into other programs
 605 @subsection Inserting LilyPond output into other programs
 606
 607 @untranslated
 608
 609
 610
 611 @c -- SKELETON FILE --