1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: 023d49bb18cbc21a03e7711186d961b8b4fc5e80
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
10 @c Translators: Reinhold Kainhofer
13 @chapter @command{lilypond-book}: Integrating text and music
16 Wenn Sie in ein Dokument Grafiken Ihres Musiksatzes einfügen möchten, so
17 können Sie genauso machen, wie Sie andere Grafiken einfügen würden: Die
18 Bilder werden getrennt vom Dokument im PostScript- oder PNG-Format erstellt
19 und können dann in @LaTeX{} oder HTML inkludiert werden.
21 @command{lilypond-book} automatisiert diesen Prozess: Dieses
22 Programm extrahiert Musik-Schnipsel aus Ihrem Dokument,
23 ruft @command{lilypond} auf und fügt die resultierenden Bilder
24 in Ihr Dokument ein. Die Länge der Zeilen und die Schriftgroße
25 werden dabei Ihrem Dokument angepasst.
27 @command{lilypond-book} ist ein eigenständiges Programm und wird
28 üblicherweise von der Kommandozeile aufgerufen. Nähere Informationen
29 hierzu finden sich in @ref{Command-line usage}.
31 Dieses Vorgehen kann bei @LaTeX{}, HTML, Texinfo oder DocBook Dokumenten
40 @cindex Dokument, Musik einfügen in
41 @cindex HTML, Musik in
42 @cindex Texinfo, Musik in
43 @cindex DocBook, Musik in
44 @cindex @LaTeX{}, Musik in
48 * An example of a musicological document::
49 * Integrating music and text::
50 * Music fragment options::
51 * Invoking lilypond-book::
52 * Filename extensions::
53 * Alternate methods of mixing text and music::
56 @node An example of a musicological document
57 @section An example of a musicological document
60 @cindex Musikwissenschaft
62 Zahlreiche Texte enthalten Musikbeispiele: musikwissenschaftliche
63 Abhandlungen, Liederbücher oder Handbücher wie dieses. Solche
64 Texte können händisch erzeugt werden, indem einfach die Musikbeispiele
65 als Grafik (PostScript, PNG, GIF, etc.) im Textverarbeitungsprogramm
66 eingefügt werden. Für HTML, @LaTeX{}, Texinfo und DocBook Dokumente
67 existiert jedoch ein Weg, dies automatisiert durchzuführen.
69 Das Programm @code{lilypond-book} extrahiert die Musikfragmente aus
70 dem Dokument, formatiert sie automatisiert in eine Grafik und fügt die
71 resultierenden Notenbeispiele dann wieder in das Dokument ein. Dies soll
72 hier an einem einfachen @LaTeX{}-Beispiel verdeutlicht werden. Das Beispiel
73 selbst enthält schon Erklärungen, sodass wir es hier nicht weiter diskutieren
80 \documentclass[a4paper]{article}
84 Dokumente für \verb+lilypond-book+ können Musik und Text nach Belieben
85 kombinieren. Zum Beispiel:
89 c2 g'2 \times 2/3 { f8 e d } c'2 g4
93 Optionen für \verb+lilypond+ werden dabei in eckige Klammern gesetzt.
95 \begin[fragment,quote,staffsize=26,verbatim]{lilypond}
99 Größere Beispiele können auch in einer eigenständigen Datei gespeichert
100 und dann mit \verb+\lilypondfile+ eingebunden werden.
102 \lilypondfile[quote,noindent]{screech-boink.ly}
104 (Falls nötig kann screech-boink.ly durch eine beliebige andere .ly
105 Datei im selben Verzeichnis wie diese Datei ersetzt werden.)
111 @subheading Processing
113 Speichern Sie den obigen @LaTeX{} Quellcode in eine Datei @file{lilybook.lytex}
114 und führen Sie dann in der Kommandozeile folgende Befehle aus:
116 @c keep space after @version{} so TeX doesn't choke
118 lilypond-book --output=out --pdf lilybook.lytex
119 @emph{lilypond-book (GNU LilyPond) @version{} }
120 @emph{Reading lilybook.lytex...}
121 @emph{..(viele Ausgabezeilen entfernt)..}
122 @emph{Compiling lilybook.tex...}
125 @emph{..(viele Ausgabezeilen entfernt)..}
127 @emph{(Ersetzen Sie @command{xpdf} durch Ihren PDF-Betrachter)}
130 Die Ausführung von @command{lilypond-book} und @command{latex} erzeugt
131 zahlreiche temporäre Dateien, die das Arbeitsverzeichnis unnötig
132 vollstopfen würden. Daher empfiehlt sich die Benutzung der @code{--output=@var{dir}}
133 Option, wodurch die Dateien im Unterverzeichnis @file{dir} erzeugt werden.
135 Das Endresultat des obigen @LaTeX{} Beispiels ist im nächsten Abschnitt
136 zu sehen.@footnote{Da dieses Handbuch mit Texinfo erzeugt wurde,
137 kann sich das Aussehen des Beispiels leicht von dem mit @LaTeX{}
138 erzeugten unterscheiden.}
144 Dokumente für @command{lilypond-book} können Musik und Text nach Belieben
145 kombinieren. Zum Beispiel:
149 c2 g'2 \times 2/3 { f8 e d } c'2 g4
153 Optionen für @command{lilypond} werden dabei in eckige Klammern gesetzt.
155 @lilypond[fragment,quote,staffsize=26,verbatim]
159 Größere Beispiele können auch in einer eigenständigen Datei gespeichert
160 und dann mit @code{\lilypondfile} eingebunden werden.
162 @lilypondfile[quote,noindent]{screech-boink.ly}
169 @node Integrating music and text
170 @section Integrating music and text
172 In diesem Abschnitt soll die Integration von LilyPond mit den
173 verschiedenen Dateiformaten detailliert erläutert werden.
187 @LaTeX{} ist der de-facto Standard zur Publikation von wissenschaftlichen Texten
188 in Naturwissenschaft und Technik. Es basiert auf dem Schriftsetzer @TeX{},
189 der die bestmögliche Typographie erzeugt.
191 Siehe die @uref{http://@/www@/.ctan@/.org/@/tex@/-archive/@/info/@/lshort/@/german/,
192 @emph{@LaTeX{}2e-Kurzbeschreibung}} für eine Einführung in die
193 Benutzung von @LaTeX{}.
195 Musikbeispiele können eingegeben werden als
198 \begin[Optionen,kommen,]@{lilypond@}
199 IHR LILYPOND QUELLCODE
207 \lilypondfile[Optionen,kommen,hier]@{@var{Dateiname}@}
214 \lilypond@{ IHR LILYPOND QUELLCODE @}
217 Der Aufruf von @command{lilypond-book} liefert eine Datei, die dann mit
218 @LaTeX{} weiter verarbeitet werden kann.
220 Dies soll hier an einigen Beispielen gezeigt werden. Die @code{lilypond} Umgebung
223 \begin[quote,fragment,staffsize=26]@{lilypond@}
231 @lilypond[quote,fragment,staffsize=26]
238 \lilypond[quote,fragment,staffsize=11]@{<c' e' g'>@}
244 @lilypond[quote,fragment,staffsize=11]{<c' e' g'>}
247 Innerhalb des @code{\lilypond@{@}} Befehls dürfen keine geschwungenen
248 Klammern @code{@{} oder @code{@}} vorkommen, weshalb dieser Befehl
249 nur mit der @code{fragment} Option Sinn macht.
251 Die Standardzeilenlänge wird bestimmt, indem die Angaben in der Dokumentpräambel,
252 also dem Teil der @LaTeX{} Datei vor dem @code{\begin@{document@}},
253 analysiert werden. Der @command{lilypond-book} Befehl sendet diese
254 Angaben an @LaTeX{}, um herauszufinden, wie breit der Text tatsächlich
255 ist. Die Breite der Notenzeilen wird dann an diese Textbreite angepasst.
256 Ein derartig heuristischer Algorithmus kann natürlich auch versagen,
257 wobei man in diesem Fall die Breite auch explizit durch die
258 @code{line-width} Option des @code{\lilypond@{@}} oder @code{\begin@{lilypond@}}
259 Befehls angeben kann.
261 @cindex titling and lilypond-book
262 @cindex \header in @LaTeX{} documents
264 Jedes Musikbeispiele ruft die folgenden Makros auf, wenn sie vom Benutzer
268 @item @code{\preLilyPondExample} -- wird vor der Musik aufgerufen,
270 @item @code{\postLilyPondExample} -- wird nach der Musik aufgerufen,
272 @item @code{\betweenLilyPondSystem[1]} -- wird zwischen den einzelnen
273 Systemen aufgerufen, wenn @code{lilypond-book} das Beispiel in verschiedene
274 PostScript Dateien getrennt hat. Dieser @LaTeX{}-Befehl muss so definiert
275 werden, dass er genau ein Argument erhält, nämlich die Zahl der bereits
276 in @LaTeX{} eingefügten Dateien dieses Beispiels. Als Standard wird einfach
277 ein @code{\linebreak} eingefügt.
283 @cindex Latex, Feta Schriftart
286 Um Zeichen wie Auflösungszeichen, Kreuze, Fermaten etc. aus der Feta-Schriftart
287 von LilyPond in @LaTeX{} einzufügen, muss @code{\input@{titledefs@}} benutzt werden,
288 wodurch dann der Befehl @code{\fetachar} zur Verfügung steht.
291 \documentclass[a4paper]@{article@}
302 Die Namen der Symbole sind in der Datei @file{feta20.tex} definiert. Sie finden
303 den Pfad zu dieser Datei mit dem Befehl
313 Manchmal ist es nötig, Musikelemente wie Halte- oder Bindebögen so darzustellen,
314 als ob sie am Ende des Musikausschnitten noch weitergehen würden. Eine solche
315 Ausgabe kann erreicht werden, indem ein Zeilenumbruch in die Notenzeile
316 eingefügt wird und die Ausgabe der folgenden Notenzeile unterdrückt wird.
318 In @LaTeX{} wird dazu der Befehl @code{\betweenLilyPondSystem} einfach derartig
319 programmiert, dass die Ausgabe der einzelnen Notensysteme abgebrochen wird,
320 sobald die gewünschte Anzahl an Systemen erreicht ist. Da
321 @code{\betweenLilyPondSystem} zum ersten Mal nach dem ersten System aufgerufen
322 wird, ist die Ausgabe nur eines Systems trivial.
325 \def\betweenLilyPondSystem#1@{\endinput@}
327 \begin[fragment]@{lilypond@}
328 c'1\( e'( c'~ \break c' d) e f\)
332 Um eine größere Zahl an System nötig, dann muss dementsprechend eine
333 @TeX{}-Bedingung vor dem @code{\endinput} benutzt werden:
336 \def\betweenLilyPondSystem#1@{
337 \ifnum##1<2\else\endinput\fi
341 Dieses Beispiel bricht nach genau zwei ausgegebenen Notenzeilen ab.
342 Für eine andere Anzahl braucht nur @q{2} durch die entsprechende
343 Anzahl ersetzt werden.
345 Die Definition von @code{\betweenLilyPondSystem} bleibt gültig,
346 bis @TeX{} die aktuelle Umgebung in @LaTeX{} verlässt oder der
347 Befehl durch eine neue Definition überschrieben wird.
348 Dies kann etwa folgendermaßen in der @LaTeX{}-Datei geschehen:
351 \let\betweenLilyPondSystem\undefined
354 Obige Definition von @code{\betweenLilyPondSystem} kann durch die
355 Definition eines @TeX{}-Makros auch verallgemeinert werden,
358 \def\onlyFirstNSystems#1@{
359 \def\betweenLilyPondSystem##1@{\ifnum##1<#1\else\endinput\fi@}
364 wobei diesem Makro @code{\onlyFirstNSystems} einfach die Anzahl der
365 gewünschten Systeme übergeben wird:
368 \onlyFirstNSystems@{3@}
369 \begin@{lilypond@}...\end@{lilypond@}
370 \onlyFirstNSystems@{1@}
371 \begin@{lilypond@}...\end@{lilypond@}
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{}-Dokumenten, siehe @ref{Invoking lilypond-book}.
384 Texinfo ist das Standard-Dokumentationsformat des GNU Projekts. Ein Beispiel
385 für ein Dokument im Texinfo Format ist dieses Handbuch, wobei die HTML-, PDF- und
386 Info-Versionen alle aus demselben Texinfo Dokument erzeugt werden.
388 In der Eingabedatei wir Musik eingegeben als
391 @@lilypond[Optionen,kommen,hier]
392 IHR LILYPOND QUELLCODE
400 @@lilypond[Optionen,kommen,hier]@{ IHR LILYPOND QUELLCODE @}
407 @@lilypondfile[Optionen,kommen,hier]@{@var{Dateiname}@}
410 Wenn @command{lilypond-book} eine derartige Datei verarbeitet,
411 wird eine Texinfo-Datei mit der Erweiterung @file{.texi} erzeugt,
412 die @code{@@image} Befehle für die Ausgabe nach HTML, Info und PDF
413 enthält. @command{lilypond-book} erzeugt die entsprechenden Grafiken
414 der Musikbeispiele im EPS- und PDF-Format für die Ausgabe nach PDF
415 und im PNG-Format für die Ausgabe nach HTML und Info.
417 Hier sollen zwei einfache Beispiele gezeigt werden. Eine @code{lilypond} Umgebung
435 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
441 @lilypond[fragment,staffsize=11]{<c' e' g'>}
443 Im Gegensatz zu @LaTeX{} erzeugt @code{@@lilypond@{...@}} allerdings keine Grafik
444 im Fließtext, sondern setzt sie immer in einen eigenen Absatz.
450 Musik wird eingegeben als
453 <lilypond fragment relative=2>
454 \key c \minor c4 es g2
459 @command{lilypond-book} erzeugt dann daraus eine HTML-Datei mit den entsprechenden
460 @code{<image>} Tags für die Musikbeispiele in jeweils einem eigenen Absatz.
463 @lilypond[fragment,relative=2]
464 \key c \minor c4 es g2
467 Für Grafiken im Fließtext kann @code{<lilypond ... />} benutzt werden, wobei
468 die Optionen durch einen Doppelpunkt von der Musik getrennt angegeben werden.
471 Musik <lilypond relative=2: a b c/> in derselben Zeile.
474 Um Dateien mit Musik einzubinden, kann folgendermaßen vorgegangen werden:
477 <lilypondfile @var{Option1} @var{Option2} ...>@var{Dateiname}</lilypondfile>
486 Bei der Einbindung von Musik im LilyPond-Format in DocBook soll die
487 Konformität unseres DocBook Dokuments erhalten bleiben und damit
488 die Bearbeiten mit DocBook-Editoren sowie die Validierung weiter
489 möglich bleiben. Aus diesem Grund werden in DocBook keine eigenen Tags
490 wie in HTML benutzt, sondern die von den vorhandenen DocBook-Elementen
491 vorgegebenen Konventionen entsprechend benützt.
493 @subheading Common conventions
495 Für die Einbindung von LilyPond Code werden in allen Fällen die
496 @code{mediaobject} und @code{inlinemediaobject} Elemente benutzt,
497 die unsere Beispiele in einem eigenen Absatz oder im Fließtext
498 einfügen. Die Optionen zur Formatierung mit LilyPond werden dabei
499 in der @code{role} Eigenschaft des innersten Elements angegeben,
500 wie im nächsten Abschnitt gezeigt wird. Die DocBook Datei, die
501 dann von @command{lilypond-book} verarbeitet wird, sollte der Klarheit
502 halber die Dateierweiterung @file{.lyxml} (jedenfalls nicht
503 @file{.xml}) besitzen.
505 @subheading Including a LilyPond file
507 Dies ist der einfachste Fall: Die LilyPond-Datei besitzt die Erweiterung
508 @file{.ly} und wird einfach als @code{imageobject} eingebettet:
513 <imagedata fileref="music1.ly" role="printfilename" />
518 Für das äußerste Element kann je nach Bedarf @code{mediaobject} oder
519 @code{inlinemediaobject} benutzt werden.
521 @subheading Including LilyPond code
523 Die Einbindung von LilyPond-Code direkt in der DocBook-Datei ist
524 durch die Benutzung von @code{programlisting} möglich,
525 wobei die Sprache auf @code{lilypond} gesetzt wird:
530 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
531 \context Staff \with @{
532 \remove Time_signature_engraver
533 \remove Clef_engraver@}
540 Das äußerste Element ist also @code{mediaobject} oder
541 @code{inlinemediaobject}, welches ein @code{textobject} mit dem
542 @code{programlisting} enthält.
544 @subheading Processing the DocBook document
546 Der Aufruf von @command{lilypond-book} mit der @file{.lyxml}-Datei
547 erzeugt ein gültiges DocBook-Dokument mit der Erweiterung @file{.xml},
548 welches normal weiterverarbeitet werden kann. Bei Benutzung von
549 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex} wird daraus
550 automatisch eine PDF-Datei erzeugt. Für die Erzeugung von HTML (HTML
551 Hilfe, JavaHelp, etc.) können die offiziellen DocBook XSL-Stylesheets
552 benutzt werden. Eventuell müssen dafür allerdings kleinere Anpassungen
556 @node Music fragment options
557 @section Music fragment options
559 Im Folgenden meint @q{LilyPond-Kommando} ein beliebiges in den vorgehenden
560 Abschnitten beschriebenes Kommando, welches ein LilyPond-Fragment in eine Datei
561 einfügt und von @command{lilypond-book} verarbeitet wird. Der Einfachheit
562 halber werden hier alle LilyPond-Kommandos in der Syntax von @LaTeX{}
565 Zu beachten ist, dass die Optionen eines LilyPond-Kommandos von links
566 nach rechts verarbeitet werden. Wenn eine Option also mehrfach angegeben
567 wird, wird nur die letzte benutzt.
569 Die folgenden Optionen können für LilyPond-Kommandos benutzt werden:
572 @item staffsize=@var{ht}
573 Setzt die Höhe einer Notenzeile auf @var{ht}, angegeben in Punkten.
576 Erzeugt Notenzeilen im Flattersatz mit natürlichem Abstand der Noten. In
577 anderen Worten: @code{ragged-right = ##t} wird in das Musikfragment
578 eingefügt. Dies ist die Standardeinstellung für das @code{\lilypond@{@}}
579 Kommando, wenn die Option @code{line-width} nicht angegeben wird.
580 Ebenso ist dies die Standardeinstellung für die @code{lilypond}-Umgebung,
581 wenn die Option @code{fragment}, aber keine Zeilenlänge
582 explizit angegeben ist.
585 Streckt Musikfragmente mit nur einer Notenzeile auf die volle Breite,
586 es wird also @code{ragged-right = ##f} in das Musikfragment eingefügt.
588 @c does this option still exist in lilypond? -jm
590 Erzeugt Notenzeilen mit möglichst engem Notenabstand, es wird also
591 @code{packed = ##t} in das Musikfragment eingefügt.
594 @itemx line-width=@var{Breite}\@var{Einheit}
595 Setzt die Breite der Notenzeilen auf @var{Breite}, gemessen in Vielfachen
596 der @var{Einheit}. Als Einheit können die folgenden Zeichenfolgen angegeben
597 werden: @code{cm}, @code{mm}, @code{in} oder @code{pt}. Diese Option hat
598 nur Einfluss auf die Breite von Notenzeilen und Text im Musikfragment, nicht
599 jedoch auf den restlichen Text des Dokuments.
601 Wird diese Option ohne einen Wert angegeben, wird die Zeilenbreite auf
602 einen Standardwert gesetzt, der durch einen heuristischen Algorithmus
605 Wenn die @code{line-width} Option nicht angegeben wird, versucht
606 @command{lilypond-book} einen geeigneten Standardwert für alle
607 @code{lilypond}-Umgebungen zu finden, die die @code{ragged-right} Option
611 Verhindert die Ausgabe der Taktangabe am Anfang des Fragments und schaltet
612 Taktstriche und alle Taktangaben im Fragment ab.
615 Bewirkt, dass @command{lilypond-book} Standardcode um das Fragment herum einfügt, sodass z. B.
622 ohne @code{\layout}, @code{\score}, etc. eingegeben werden kann.
625 Verhindert das Einfügen von Standardcode um das Fragment herum. Dies ist
626 die Standardeinstellung, insofern ist diese Option im Normalfall unnötig.
628 @item indent=@var{Einzug}\@var{Einheit}
629 Setzt den Einzug des ersten Notensystems auf @var{Einzug}, gemessen in
630 Vielfachen der @var{Einheit}. Als Einheit können die folgenden Zeichenfolgen
631 angegeben werden: @code{cm}, @code{mm}, @code{in} oder @code{pt}. Diese
632 Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im
633 Musikfragment, nicht jedoch auf den restlichen Text des Dokuments.
636 Setzt den Einzug des ersten Notensystems auf 0. Diese
637 Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im
638 Musikfragment, nicht jedoch auf den restlichen Text des Dokuments. Dies
639 ist die Standardeinstellung, insofern ist diese Option im Normalfall
643 Verringert die Zeilenlänge des Musikfragments um @math{2*0.4}@dmn{in}
644 und setzt das Fragment in einen Zitat-Block. Der Wert von @q{0.4@dmn{in}}
645 kann durch die @code{exampleindent} Option angepasst werden.
648 Setzt den Betrag, um den das Fragment bei Benutzung der @code{quote}
649 Option eingerückt wird.
652 @itemx relative=@var{n}
653 Benutzt relative Oktavenbezeichnungen. Standardmäßig werden Noten relativ
654 zum mittleren C angegeben. Das optionale ganzzahlige Argument
655 gibt die Oktave der ersten Note an, wobei die Standardeinstellung von
656 @code{1} das mittlere C bedeutet. Die @code{relative} Option macht nur
657 Sinn in Verbindung mit der @code{fragment} Option, weshalb @code{fragment}
658 automatisch durch die Angabe der @code{relative} Option impliziert wird.
659 Eine explizite Angabe der @code{(no)fragment} Option hat keinen Effekt.
662 LilyPond benutzt zur Erzeugung seiner eigenen Dokumentation ebenfalls
663 @command{lilypond-book}. Zu diesem Zweck stehen noch zahlreiche
664 spezialisierte Optionen zur Verfügung:
668 Der LilyPond-Code im LilyPond-Kommando wird zum einen benutzt, um das
669 Musikfragment in eine Grafik mit schönem Notensatz zu konvertieren,
670 andererseits aber auch wörtlich in das Dokument eingefügt. Dies
671 geschieht in einem @q{verbatim}-Block, gefolgt vom Text einer
672 möglicherweise angegebenen @code{intertext} Option@footnote{Die
673 @code{intertext} Option ist noch nicht implementiert.} und der
674 Grafik des tatsächlichen Notensatzes. Diese Option funktioniert nur
675 fehlerhaft, wenn @code{\lilypond@{@}} im Fließtext benutzt wird.
677 Wird @code{verbatim} in Verbindung mit einem @code{lilypondfile}-Kommando
678 benutzt, so ist es auch möglich, nur ein Teil der Datei wörtlich einfügen
679 zu lassen: Wenn die eingebundene LilyPond-Datei ein Kommentar mit dem Inhalt
680 @samp{begin verbatim} (ohne Anführungszeichen) enthält, wird nur der
681 Dateiinhalt ab dieser Position eingefügt. Enthält die Datei mehrere
682 solche Kommentare, wirkt nur das letzte. Analog wird nur der Dateiinhalt
683 bis zu einem etwaigen Kommentar mit dem Inhalt @samp{end verbatim}
684 eingefügt. Im folgenden Beispiel wird das gesamte Musik für die
685 Erzeugung der Grafik im relativen Oktavenmodus interpretiert, der
686 wörtlich in das Dokument kopierte LilyPond-Code zeigt den @code{relative}-Befehl jedoch nicht.
689 \relative c' @{ % begin verbatim
696 erzeugt ein Zitat der Form
704 (Nur innerhalb von Texinfo-Dateien.) Stellt @code{\version
705 @@w@{"@@version@{@}"@}} an den Beginn des Fragments der Ausgabe mit
709 (Nur innerhalb von Texinfo-Dateien.) Wird @command{lilypond} mit der
710 Kommandozeilenoption @option{--header=@/texidoc} für eine Datei
711 @file{foo@/.ly} und enthält die Datei ein @code{texidoc}-Feld im
712 @code{\header}-Block, so wird dessen Inhalt in die Datei
713 @file{foo@/.texidoc} ausgegeben. Die @code{texidoc} Option veranlasst
714 @code{lilypond-book}, den Inhalt dieser @file{.texidoc} Dateien innerhalb
715 eines Dokumentationsblocks direkt vor dem Musikfragment in das aktuelle
718 Enthält also die Datei @file{foo@/.ly} etwa den LilyPond-Code
722 texidoc = "Dieses Beispiel zeigt eine einzelne Note."
728 und das Texinfo-Dokument @file{text.texinfo}
731 @@lilypondfile[texidoc]@{foo.ly@}
735 so liefert der folgende Aufruf von @code{lilypond-book} das gewünschte
739 lilypond-book --process="lilypond --format=tex --tex \
740 --header=texidoc test.texinfo
743 Die meisten Test-Dateien (im @file{input/} Verzeichnis von LilyPond)
744 sind kleine @file{.ly} Dateien von genau dieser Form.
746 Auch die Übersetzung dieser zusätzlichen Kommentare ist möglich:
747 Dazu muss das Texinfo-Dokument den Befehl @code{@@documentlanguage @var{LANG}}
748 und der @code{\header} Block in der Datei @file{foo@/.ly}
749 die Übersetzung im Feld @code{texidoc@var{LANG}} enthalten. Wird nun
750 @command{lilypond} mit der Option @option{--header=@/texidoc@var{LANG}}
751 aufgerufen, so wird der Inhalt der Datei @file{foo@/.texidoc@var{LANG}} anstelle von @file{foo@/.texidoc} eingefügt.
754 (Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt wie die @code{quote} Option, außer dass nur das Musikfragment (und natürlich optional der
755 gesamte LilyPond-Code bei Benutzung von @code{verbatim}) in den Zitatblock eingefügt wird. Dies ist nützlich, wenn Sie ein Musikfragment zitieren möchten, nicht aber dessen @code{texidoc} Dokumentationsblock.
758 (Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt ähnlich wie die
759 @code{texidoc} Option: Wenn @command{lilypond} mit der Option
760 @option{--header=@/doctitle} aufgerufen wird und die Eingabedatei
761 @file{foo@/.ly} ein Feld @code{doctitle} im @code{\header}-Block enthält,
762 wird dessen Wert in die Datei @file{foo@/.doctitle} geschrieben. Wird die
763 @code{doctitle} Option für ein Musikfragment benutzt, so wird der Inhalt
764 dieser Datei, der eine einzelne Textzeile sein sollte, im Texinfo-Dokument
765 als @code{@@lydoctitle @var{Text}} eingefügt. @code{@@lydoctitle} muss
766 allerdings in Ihrem Texinfo-Dokument als Makro selbst definiert werden.
767 Die Übersetzung funktioniert völlig analog zu @code{texidoc}.
770 Wenn eine LilyPond-Datei mittels @code{\lilypondfile} und dieser Option
771 eingebunden wird, wird der Dateiname (ohne die Pfadangabe) unmittelbar vor
772 dem Musikfragment ausgegeben. In HTML-Dateien ist er außerdem ein Link
773 auf die LilyPond-Datei.
776 Diese Option inkludiert die Schriftarten in allen EPS-Dateien, die von
777 diesem Fragment erzeugt werden. Dies ist nötig, wenn das Fragment
778 Schriftarten benutzt, die @LaTeX{} nicht selbst findet.
783 @node Invoking lilypond-book
784 @section Invoking @command{lilypond-book}
786 @command{lilypond-book} erzeugt abhängig vom Ausgabeformat eine Datei mit
787 einer der folgenden Dateierweiterungen: @file{.tex}, @file{.texi},
788 @file{.html} oder @file{.xml}. Alle @file{.tex}, @file{.texi} und
789 @file{.xml} Dateien müssen noch mit den entsprechenden Programmen (@LaTeX{},
790 DocBook, etc.) weiter verarbeitet werden, um druckfähige Dateien zu erhalten.
793 @subheading Format-specific instructions
795 @subsubheading @LaTeX{}
797 Es existieren zwei Methoden, Ihr @LaTeX{}-Dokument weiter zu verarbeiten,
798 um zu einer druck- oder publikationsfähigen Datei zu gelangen:
799 Zum einen die direkte Erzeugung einer PDF-Datei mit PDF@LaTeX{}, zum
800 anderen die Erzeugung einer DVI daraus einer PostScript-Datei mittels
801 @LaTeX{} und einem DVI-nach-PostScript Konverters wie @command{dvips}.
802 Die erste Methode ist einfacher und daher empfehlenswert.@footnote{Manchmal
803 kann eine Datei entweder von PDF@LaTeX{} oder von @LaTeX{} nicht korrekt
804 verarbeitet werden, weshalb hier beide Methoden beschrieben werden.} Welche
805 Methode auch immer benutzt wird, die Konvertierung zwischen PostScript und
806 PDF kann leicht mit Hilfsprogrammen wie @command{ps2pdf} und @command{pdf2ps}
807 (aus dem Ghostscript Paket) erfolgen.
809 Um eine PDF-Datei mittels PDF@LaTeX{} zu erzeugen, kann folgendermaßen
813 lilypond-book --pdf Ihre_Datei.pdftex
814 pdflatex Ihre_Datei.tex
817 @cindex Konturschriften
818 @cindex Type1 Schriften
820 @cindex Aufruf von dvips
821 Um eine PDF-Datei mittels @LaTeX{}/@command{dvips}/@command{ps2pdf} zu
822 erhalten, sind folgende Befehle nötig:
825 lilypond-book Ihre_Datei.lytex
827 dvips -Ppdf Ihre_Datei.dvi
832 Die @file{.dvi}-Datei, die beim Aufruf von @command{latex} erzeugt wird,
833 scheint keine Notenköpfe zu enthalten, was in Ordnung ist. Wenn Sie die
834 Datei wie beschrieben weiter verarbeiten, erscheinen die Notenköpfe korrekt
835 in den @file{.ps} und @file{.pdf} Dateien.
837 Der Aufruf von @command{dvips} kann einige Warnungen über fehlende
838 Schriftarten ausgeben. Auch dies ist in Ordnung und kann ignoriert werden.
840 Wenn Sie in der @LaTeX{}-Datei das Papierformat auf Querformat eingestellt
841 haben, vergessen Sie nicht auf die @code{-t landscape} Option beim
842 Aufruf von @command{dvips}.
845 @subsubheading Texinfo
847 Um ein von @command{lilypond-book} erzeugtes Texinfo-Dokument zu
848 verarbeiten, gehen Sie wie für alle anderen Texinfo-Dokumente vor:
849 Rufen Sie -- abhängig vom gewünschten Ausgabeformat -- eines der Programme
850 @command{texi2pdf}, @command{texi2dvi}, @command{makeinfo} oder
851 @command{texi2html} auf.
854 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, und @ref{Creating
855 an Info File, , , texinfo, GNU Texinfo}.
858 Die Dokumentation von Texinfo liefert dazu nähere Informationen.
862 @subheading Command line options
864 @command{lilypond-book} unterstützt die folgenden Kommandozeilenoptionen:
867 @item -f @var{Format}
868 @itemx --format=@var{Format}
869 Gibt das Format des Eingabedokuments an: @code{html}, @code{latex},
870 @code{texi} (Standardeinstellung), @code{texi-html} oder @code{docbook}.
871 Ist diese Option nicht angegeben, versucht @command{lilypond-book} das
872 Format anhand des Dateinamens zu bestimmen. Im Moment bedeutet @code{texi}
873 praktisch dasselbe wie @code{texi-html}.
875 @c This complicated detail is not implemented, comment it out -jm
877 The @code{texi} document type produces a Texinfo file with music
878 fragments in the printed output only. For getting images in the HTML
879 version, the format @code{texi-html} must be used instead.
882 @item -F @var{Filter}
883 @itemx --filter=@var{Filter}
884 Leitet die Musikfragmente durch das Programm @var{filter} anstatt sie
885 mit Lilypond zu einer Grafik zu verarbeiten. @option{--filter} und
886 @option{--process} kann nicht gleichzeigt benutzt werden. Beispielaufruf:
889 lilypond-book --filter='convert-ly --from=2.0.0 -' Mein-Buch.tely
894 Gibt eine kurze Hilfemeldung aus.
897 @itemx --include=@var{Pfad}
898 Fügt @var{Pfad} zu den Include-Pfaden hinzu. @command{lilypond-book} sucht
899 auch in allen Include-Pfaden nach bereits erstellten Grafiken für die
900 Musikfragmente. Wird das aktuelle Fragment gefunden und hat sich seit der
901 letzten Erstellung nicht geändert, wird es nicht erneut erzeugt. Bei manchen
902 der Programme zur Weiterverarbeitung wie etwa @command{makeinfo} oder
903 @command{latex} muss dieselbe @code{-I @var{Pfad}} Option angegeben werden,
904 damit das entsprechende Programm die Grafiken ebenso findet.
906 @item -o @var{Verzeichnis}
907 @itemx --output=@var{Verzeichnis}
908 Erzeugt die Ausgabedateien in @var{Verzeichnis}. Der Aufruf von
909 @command{lilypond-book} erzeugt zahlreiche kleine Dateien, die von
910 LilyPond, @command{latex}, @command{makeinfo} etc. dann weiter benützt
911 werden. Um zu vermeiden, dass das Quellenverzeichnis durch diese
912 Dateien unübersichtlich wird, kann die @option{--output} Option benutzt
913 werden. Vor dem Aufruf von @command{latex} oder @command{makeinfo}
914 sollten Sie in dieses Verzeichnis wechseln.
917 lilypond-book --output=out IhreDatei.lytex
922 @itemx --skip-lily-check
923 Nicht mit einer Fehlermeldung abbrechen, wenn keine Ausgabe von LilyPond
924 gefunden wird. Dies wird benutzt für Dokumentation ohne Grafiken.
926 @itemx --skip-png-check
927 Nicht mit einer Fehlermeldung abbrechen, wenn für die EPS-Dateien keine
928 PNG-Grafiken gefunden werden. Dies wird benutzt für Dokumentation ohne
931 @itemx --lily-output-dir=@var{Verzeichnis}
932 Schreibt @file{lily-XXX} Dateien nach @var{Verzeichnis} und erzeugt
933 im mit @code{--output} angegebenen Verzeichnis Verknüpfungen darauf.
934 Diese Option ist nützlich, um Zeit zu sparen, wenn Dokumente in
935 verschiedenen Verzeichnissen viele identische Musikfragmente
938 @itemx --info-images-dir=@var{Verzeichnis}
939 Formatiert die Texinfo-Ausgabe dergestalt, dass Info in @var{Verzeichnis}
940 nach den Grafiken zu den Musikfragmenten sucht.
942 @itemx --latex-program=@var{Programm}
943 Führt @command{Programm} anstelle von @command{latex} aus. Dies ist
944 nützlichen, wenn das Dokument mit einer anderen @LaTeX{}-Variante
945 wie etwa @command{xelatex} verarbeitet werden soll.
947 @itemx --left-padding=@var{Einrückung}
948 Fügt @var{Einrückung} als zusätzlichen Einzug in die EPS-Box ein.
949 @var{Einrückung} wird in Millimetern angegeben, die Standardeinstellung
950 is 3.0 Millimeter. Diese Option kann benutzt werden, wenn die Notenzeilen
951 über den Rand des Dokuments hinausstehen.
953 Die Breite eines eng ausgeschnittenen Notensystems kann variieren
954 aufgrund von Notationselementen, die über den linken Rand hinausstehen,
955 wie etwa Taktzahlen und Bezeichnungen der Instrumente. Diese Option
956 verkürzt die Notenzeile und verschiebt sie um denselben Betrag nach
960 @item -P @var{Kommando}
961 @itemx --process=@var{Kommando}
962 Verarbeitet LilyPond-Fragmente mit @var{Kommando} anstelle des
963 Standardbefehls @code{lilypond}. @code{--filter} und @code{--process}
964 können nicht gleichzeitig angegeben werden.
967 Erzeugt PDF-Dateien mit PDF@LaTeX{}.
971 Gibt ausführliche informative Meldungen aus.
975 Gibt die Versionsnummer aus.
980 Der Texinfo-Befehl @code{@@pagesizes} wird ignoriert. Ebenso werden
981 @LaTeX{}-Befehle ignoriert, die den Seitenrand oder die Zeilenlänge
982 nach der Dokumentpräambel verändern.
984 Nur der erste @code{\score}-Block eines LilyPond-Fragments wird verarbeitet.
987 @node Filename extensions
988 @section Filename extensions
990 Für die Eingabedatei kann zwar jede beliebige Dateinamenserweiterung benutzt
991 werden, allerdings muss bei Verwendung einer nicht bekannten Erweiterung
992 das Ausgabeformat explizit an @command{lilypond-book} angegeben werden.
993 Details dazu finden sich im Abschnitt @ref{Invoking lilypond-book}.
994 Wird eine bekannte Erweiterung benutzt, wählt @command{lilypond-book}
995 automatisch das richtige Ausgabeformat basierend auf der Erweiterung der
999 @multitable @columnfractions .2 .5
1000 @item @strong{Erweiterung} @tab @strong{Ausgabeformat}
1002 @item @file{.html} @tab HTML
1003 @item @file{.itely} @tab Texinfo
1004 @item @file{.latex} @tab @LaTeX{}
1005 @item @file{.lytex} @tab @LaTeX{}
1006 @item @file{.lyxml} @tab DocBook
1007 @item @file{.tely} @tab Texinfo
1008 @item @file{.tex} @tab @LaTeX{}
1009 @item @file{.texi} @tab Texinfo
1010 @item @file{.texinfo} @tab Texinfo
1011 @item @file{.xml} @tab HTML
1015 Wird dieselbe Erweiterung für die Eingabedatei wie für die Ausgabedatei
1016 benutzt und befindet sich die Eingabedatei im aktuellen Arbeitsverzeichnis
1017 von @command{lilypond-book}, muss die @code{--output} Option für
1018 @command{lilypond-book} benutzt werden. Anderenfalls würde
1019 @command{lilypond-book} ja die Eingabedatei überschreiben, weshalb das
1020 Programm in diesem Fall mit einer Fehlermeldung wie @qq{Fehler: Ausgabe
1021 würde Eingabedatei überschreiben; verwenden Sie --output.} abbricht.
1024 @node Alternate methods of mixing text and music
1025 @section Alternative methods of mixing text and music
1027 Dieser Abschnitt stellt Methoden vor, wie Text und Musik auf andere
1028 Weise kombiniert werden können als dies durch @command{lilypond-book}
1029 automatisiert geschieht.
1033 * Many quotes from a large score::
1034 * Inserting LilyPond output into OpenOffice.org::
1035 * Inserting LilyPond output into other programs::
1038 @node Many quotes from a large score
1039 @subsection Many quotes from a large score
1041 Wenn aus einer großen Partitur viele kleine Fragmente eingefügt
1042 werden sollen, kann dazu das @q{clip systems} Feature benutzt werden.
1043 Siehe @ruser{Extracting fragments of music}.
1046 @node Inserting LilyPond output into OpenOffice.org
1047 @subsection Inserting LilyPond output into OpenOffice.org
1049 Musik im LilyPond-Format kann in OpenOffice.org eingefügt werden mittels
1050 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
1053 @node Inserting LilyPond output into other programs
1054 @subsection Inserting LilyPond output into other programs
1056 Im die Ausgabe von LilyPond in anderen Programmen einzufügen,
1057 sollte @code{lilypond} benutzt werden. Jedes Beispiel muss
1058 getrennt manuell erzeugt und ins Dokument eingefügt werden;
1059 für letzteres schlagen Sie bitte im Handbuch Ihrer
1060 Textverarbeitungs-Software nach. Die meisten Programme
1061 unterstützen das Einfügen von Grafiken im @file{PNG}-, @file{EPS}-
1062 oder @file{PDF}-Format.
1064 Um den leeren Rand um die Notenzeilen zu verringern, können folgende
1065 Einstellungen benutzt werden:
1073 bookTitleMarkup = ##f
1074 scoreTitleMarkup = ##f
1080 Eine @file{EPS}-Datei kann mit folgendem Befehl erzeugt werden:
1083 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts Dateiname.ly
1085 Eine @file{PNG}-Datei mittels:
1086 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png Dateiname.ly