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.
589 @itemx line-width=@var{Breite}\@var{Einheit}
590 Setzt die Breite der Notenzeilen auf @var{Breite}, gemessen in Vielfachen
591 der @var{Einheit}. Als Einheit können die folgenden Zeichenfolgen angegeben
592 werden: @code{cm}, @code{mm}, @code{in} oder @code{pt}. Diese Option hat
593 nur Einfluss auf die Breite von Notenzeilen und Text im Musikfragment, nicht
594 jedoch auf den restlichen Text des Dokuments.
596 Wird diese Option ohne einen Wert angegeben, wird die Zeilenbreite auf
597 einen Standardwert gesetzt, der durch einen heuristischen Algorithmus
600 Wenn die @code{line-width} Option nicht angegeben wird, versucht
601 @command{lilypond-book} einen geeigneten Standardwert für alle
602 @code{lilypond}-Umgebungen zu finden, die die @code{ragged-right} Option
606 Verhindert die Ausgabe der Taktangabe am Anfang des Fragments und schaltet
607 Taktstriche und alle Taktangaben im Fragment ab.
610 Bewirkt, dass @command{lilypond-book} Standardcode um das Fragment herum einfügt, sodass z. B.
617 ohne @code{\layout}, @code{\score}, etc. eingegeben werden kann.
620 Verhindert das Einfügen von Standardcode um das Fragment herum. Dies ist
621 die Standardeinstellung, insofern ist diese Option im Normalfall unnötig.
623 @item indent=@var{Einzug}\@var{Einheit}
624 Setzt den Einzug des ersten Notensystems auf @var{Einzug}, gemessen in
625 Vielfachen der @var{Einheit}. Als Einheit können die folgenden Zeichenfolgen
626 angegeben werden: @code{cm}, @code{mm}, @code{in} oder @code{pt}. Diese
627 Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im
628 Musikfragment, nicht jedoch auf den restlichen Text des Dokuments.
631 Setzt den Einzug des ersten Notensystems auf 0. Diese
632 Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im
633 Musikfragment, nicht jedoch auf den restlichen Text des Dokuments. Dies
634 ist die Standardeinstellung, insofern ist diese Option im Normalfall
638 Verringert die Zeilenlänge des Musikfragments um @math{2*0.4}@dmn{in}
639 und setzt das Fragment in einen Zitat-Block. Der Wert von @q{0.4@dmn{in}}
640 kann durch die @code{exampleindent} Option angepasst werden.
643 Setzt den Betrag, um den das Fragment bei Benutzung der @code{quote}
644 Option eingerückt wird.
647 @itemx relative=@var{n}
648 Benutzt relative Oktavenbezeichnungen. Standardmäßig werden Noten relativ
649 zum mittleren C angegeben. Das optionale ganzzahlige Argument
650 gibt die Oktave der ersten Note an, wobei die Standardeinstellung von
651 @code{1} das mittlere C bedeutet. Die @code{relative} Option macht nur
652 Sinn in Verbindung mit der @code{fragment} Option, weshalb @code{fragment}
653 automatisch durch die Angabe der @code{relative} Option impliziert wird.
654 Eine explizite Angabe der @code{(no)fragment} Option hat keinen Effekt.
657 LilyPond benutzt zur Erzeugung seiner eigenen Dokumentation ebenfalls
658 @command{lilypond-book}. Zu diesem Zweck stehen noch zahlreiche
659 spezialisierte Optionen zur Verfügung:
663 Der LilyPond-Code im LilyPond-Kommando wird zum einen benutzt, um das
664 Musikfragment in eine Grafik mit schönem Notensatz zu konvertieren,
665 andererseits aber auch wörtlich in das Dokument eingefügt. Dies
666 geschieht in einem @q{verbatim}-Block, gefolgt vom Text einer
667 möglicherweise angegebenen @code{intertext} Option@footnote{Die
668 @code{intertext} Option ist noch nicht implementiert.} und der
669 Grafik des tatsächlichen Notensatzes. Diese Option funktioniert nur
670 fehlerhaft, wenn @code{\lilypond@{@}} im Fließtext benutzt wird.
672 Wird @code{verbatim} in Verbindung mit einem @code{lilypondfile}-Kommando
673 benutzt, so ist es auch möglich, nur ein Teil der Datei wörtlich einfügen
674 zu lassen: Wenn die eingebundene LilyPond-Datei ein Kommentar mit dem Inhalt
675 @samp{begin verbatim} (ohne Anführungszeichen) enthält, wird nur der
676 Dateiinhalt ab dieser Position eingefügt. Enthält die Datei mehrere
677 solche Kommentare, wirkt nur das letzte. Analog wird nur der Dateiinhalt
678 bis zu einem etwaigen Kommentar mit dem Inhalt @samp{end verbatim}
679 eingefügt. Im folgenden Beispiel wird das gesamte Musik für die
680 Erzeugung der Grafik im relativen Oktavenmodus interpretiert, der
681 wörtlich in das Dokument kopierte LilyPond-Code zeigt den @code{relative}-Befehl jedoch nicht.
684 \relative c' @{ % begin verbatim
691 erzeugt ein Zitat der Form
699 (Nur innerhalb von Texinfo-Dateien.) Stellt @code{\version
700 @@w@{"@@version@{@}"@}} an den Beginn des Fragments der Ausgabe mit
704 (Nur innerhalb von Texinfo-Dateien.) Wird @command{lilypond} mit der
705 Kommandozeilenoption @option{--header=@/texidoc} für eine Datei
706 @file{foo@/.ly} und enthält die Datei ein @code{texidoc}-Feld im
707 @code{\header}-Block, so wird dessen Inhalt in die Datei
708 @file{foo@/.texidoc} ausgegeben. Die @code{texidoc} Option veranlasst
709 @code{lilypond-book}, den Inhalt dieser @file{.texidoc} Dateien innerhalb
710 eines Dokumentationsblocks direkt vor dem Musikfragment in das aktuelle
713 Enthält also die Datei @file{foo@/.ly} etwa den LilyPond-Code
717 texidoc = "Dieses Beispiel zeigt eine einzelne Note."
723 und das Texinfo-Dokument @file{text.texinfo}
726 @@lilypondfile[texidoc]@{foo.ly@}
730 so liefert der folgende Aufruf von @code{lilypond-book} das gewünschte
734 lilypond-book --process="lilypond --format=tex --tex \
735 --header=texidoc test.texinfo
738 Die meisten Test-Dateien (im @file{input/} Verzeichnis von LilyPond)
739 sind kleine @file{.ly} Dateien von genau dieser Form.
741 Auch die Übersetzung dieser zusätzlichen Kommentare ist möglich:
742 Dazu muss das Texinfo-Dokument den Befehl @code{@@documentlanguage @var{LANG}}
743 und der @code{\header} Block in der Datei @file{foo@/.ly}
744 die Übersetzung im Feld @code{texidoc@var{LANG}} enthalten. Wird nun
745 @command{lilypond} mit der Option @option{--header=@/texidoc@var{LANG}}
746 aufgerufen, so wird der Inhalt der Datei @file{foo@/.texidoc@var{LANG}} anstelle von @file{foo@/.texidoc} eingefügt.
749 (Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt wie die @code{quote} Option, außer dass nur das Musikfragment (und natürlich optional der
750 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.
753 (Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt ähnlich wie die
754 @code{texidoc} Option: Wenn @command{lilypond} mit der Option
755 @option{--header=@/doctitle} aufgerufen wird und die Eingabedatei
756 @file{foo@/.ly} ein Feld @code{doctitle} im @code{\header}-Block enthält,
757 wird dessen Wert in die Datei @file{foo@/.doctitle} geschrieben. Wird die
758 @code{doctitle} Option für ein Musikfragment benutzt, so wird der Inhalt
759 dieser Datei, der eine einzelne Textzeile sein sollte, im Texinfo-Dokument
760 als @code{@@lydoctitle @var{Text}} eingefügt. @code{@@lydoctitle} muss
761 allerdings in Ihrem Texinfo-Dokument als Makro selbst definiert werden.
762 Die Übersetzung funktioniert völlig analog zu @code{texidoc}.
765 Wenn eine LilyPond-Datei mittels @code{\lilypondfile} und dieser Option
766 eingebunden wird, wird der Dateiname (ohne die Pfadangabe) unmittelbar vor
767 dem Musikfragment ausgegeben. In HTML-Dateien ist er außerdem ein Link
768 auf die LilyPond-Datei.
771 Diese Option inkludiert die Schriftarten in allen EPS-Dateien, die von
772 diesem Fragment erzeugt werden. Dies ist nötig, wenn das Fragment
773 Schriftarten benutzt, die @LaTeX{} nicht selbst findet.
778 @node Invoking lilypond-book
779 @section Invoking @command{lilypond-book}
781 @command{lilypond-book} erzeugt abhängig vom Ausgabeformat eine Datei mit
782 einer der folgenden Dateierweiterungen: @file{.tex}, @file{.texi},
783 @file{.html} oder @file{.xml}. Alle @file{.tex}, @file{.texi} und
784 @file{.xml} Dateien müssen noch mit den entsprechenden Programmen (@LaTeX{},
785 DocBook, etc.) weiter verarbeitet werden, um druckfähige Dateien zu erhalten.
788 @subheading Format-specific instructions
790 @subsubheading @LaTeX{}
792 Es existieren zwei Methoden, Ihr @LaTeX{}-Dokument weiter zu verarbeiten,
793 um zu einer druck- oder publikationsfähigen Datei zu gelangen:
794 Zum einen die direkte Erzeugung einer PDF-Datei mit PDF@LaTeX{}, zum
795 anderen die Erzeugung einer DVI daraus einer PostScript-Datei mittels
796 @LaTeX{} und einem DVI-nach-PostScript Konverters wie @command{dvips}.
797 Die erste Methode ist einfacher und daher empfehlenswert.@footnote{Manchmal
798 kann eine Datei entweder von PDF@LaTeX{} oder von @LaTeX{} nicht korrekt
799 verarbeitet werden, weshalb hier beide Methoden beschrieben werden.} Welche
800 Methode auch immer benutzt wird, die Konvertierung zwischen PostScript und
801 PDF kann leicht mit Hilfsprogrammen wie @command{ps2pdf} und @command{pdf2ps}
802 (aus dem Ghostscript Paket) erfolgen.
804 Um eine PDF-Datei mittels PDF@LaTeX{} zu erzeugen, kann folgendermaßen
808 lilypond-book --pdf Ihre_Datei.pdftex
809 pdflatex Ihre_Datei.tex
812 @cindex Konturschriften
813 @cindex Type1 Schriften
815 @cindex Aufruf von dvips
816 Um eine PDF-Datei mittels @LaTeX{}/@command{dvips}/@command{ps2pdf} zu
817 erhalten, sind folgende Befehle nötig:
820 lilypond-book Ihre_Datei.lytex
822 dvips -Ppdf Ihre_Datei.dvi
827 Die @file{.dvi}-Datei, die beim Aufruf von @command{latex} erzeugt wird,
828 scheint keine Notenköpfe zu enthalten, was in Ordnung ist. Wenn Sie die
829 Datei wie beschrieben weiter verarbeiten, erscheinen die Notenköpfe korrekt
830 in den @file{.ps} und @file{.pdf} Dateien.
832 Der Aufruf von @command{dvips} kann einige Warnungen über fehlende
833 Schriftarten ausgeben. Auch dies ist in Ordnung und kann ignoriert werden.
835 Wenn Sie in der @LaTeX{}-Datei das Papierformat auf Querformat eingestellt
836 haben, vergessen Sie nicht auf die @code{-t landscape} Option beim
837 Aufruf von @command{dvips}.
840 @subsubheading Texinfo
842 Um ein von @command{lilypond-book} erzeugtes Texinfo-Dokument zu
843 verarbeiten, gehen Sie wie für alle anderen Texinfo-Dokumente vor:
844 Rufen Sie -- abhängig vom gewünschten Ausgabeformat -- eines der Programme
845 @command{texi2pdf}, @command{texi2dvi}, @command{makeinfo} oder
846 @command{texi2html} auf.
849 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, und @ref{Creating
850 an Info File, , , texinfo, GNU Texinfo}.
853 Die Dokumentation von Texinfo liefert dazu nähere Informationen.
857 @subheading Command line options
859 @command{lilypond-book} unterstützt die folgenden Kommandozeilenoptionen:
862 @item -f @var{Format}
863 @itemx --format=@var{Format}
864 Gibt das Format des Eingabedokuments an: @code{html}, @code{latex},
865 @code{texi} (Standardeinstellung), @code{texi-html} oder @code{docbook}.
866 Ist diese Option nicht angegeben, versucht @command{lilypond-book} das
867 Format anhand des Dateinamens zu bestimmen. Im Moment bedeutet @code{texi}
868 praktisch dasselbe wie @code{texi-html}.
870 @c This complicated detail is not implemented, comment it out -jm
872 The @code{texi} document type produces a Texinfo file with music
873 fragments in the printed output only. For getting images in the HTML
874 version, the format @code{texi-html} must be used instead.
877 @item -F @var{Filter}
878 @itemx --filter=@var{Filter}
879 Leitet die Musikfragmente durch das Programm @var{filter} anstatt sie
880 mit Lilypond zu einer Grafik zu verarbeiten. @option{--filter} und
881 @option{--process} kann nicht gleichzeigt benutzt werden. Beispielaufruf:
884 lilypond-book --filter='convert-ly --from=2.0.0 -' Mein-Buch.tely
889 Gibt eine kurze Hilfemeldung aus.
892 @itemx --include=@var{Pfad}
893 Fügt @var{Pfad} zu den Include-Pfaden hinzu. @command{lilypond-book} sucht
894 auch in allen Include-Pfaden nach bereits erstellten Grafiken für die
895 Musikfragmente. Wird das aktuelle Fragment gefunden und hat sich seit der
896 letzten Erstellung nicht geändert, wird es nicht erneut erzeugt. Bei manchen
897 der Programme zur Weiterverarbeitung wie etwa @command{makeinfo} oder
898 @command{latex} muss dieselbe @code{-I @var{Pfad}} Option angegeben werden,
899 damit das entsprechende Programm die Grafiken ebenso findet.
901 @item -o @var{Verzeichnis}
902 @itemx --output=@var{Verzeichnis}
903 Erzeugt die Ausgabedateien in @var{Verzeichnis}. Der Aufruf von
904 @command{lilypond-book} erzeugt zahlreiche kleine Dateien, die von
905 LilyPond, @command{latex}, @command{makeinfo} etc. dann weiter benützt
906 werden. Um zu vermeiden, dass das Quellenverzeichnis durch diese
907 Dateien unübersichtlich wird, kann die @option{--output} Option benutzt
908 werden. Vor dem Aufruf von @command{latex} oder @command{makeinfo}
909 sollten Sie in dieses Verzeichnis wechseln.
912 lilypond-book --output=out IhreDatei.lytex
917 @itemx --skip-lily-check
918 Nicht mit einer Fehlermeldung abbrechen, wenn keine Ausgabe von LilyPond
919 gefunden wird. Dies wird benutzt für Dokumentation ohne Grafiken.
921 @itemx --skip-png-check
922 Nicht mit einer Fehlermeldung abbrechen, wenn für die EPS-Dateien keine
923 PNG-Grafiken gefunden werden. Dies wird benutzt für Dokumentation ohne
926 @itemx --lily-output-dir=@var{Verzeichnis}
927 Schreibt @file{lily-XXX} Dateien nach @var{Verzeichnis} und erzeugt
928 im mit @code{--output} angegebenen Verzeichnis Verknüpfungen darauf.
929 Diese Option ist nützlich, um Zeit zu sparen, wenn Dokumente in
930 verschiedenen Verzeichnissen viele identische Musikfragmente
933 @itemx --info-images-dir=@var{Verzeichnis}
934 Formatiert die Texinfo-Ausgabe dergestalt, dass Info in @var{Verzeichnis}
935 nach den Grafiken zu den Musikfragmenten sucht.
937 @itemx --latex-program=@var{Programm}
938 Führt @command{Programm} anstelle von @command{latex} aus. Dies ist
939 nützlichen, wenn das Dokument mit einer anderen @LaTeX{}-Variante
940 wie etwa @command{xelatex} verarbeitet werden soll.
942 @itemx --left-padding=@var{Einrückung}
943 Fügt @var{Einrückung} als zusätzlichen Einzug in die EPS-Box ein.
944 @var{Einrückung} wird in Millimetern angegeben, die Standardeinstellung
945 is 3.0 Millimeter. Diese Option kann benutzt werden, wenn die Notenzeilen
946 über den Rand des Dokuments hinausstehen.
948 Die Breite eines eng ausgeschnittenen Notensystems kann variieren
949 aufgrund von Notationselementen, die über den linken Rand hinausstehen,
950 wie etwa Taktzahlen und Bezeichnungen der Instrumente. Diese Option
951 verkürzt die Notenzeile und verschiebt sie um denselben Betrag nach
955 @item -P @var{Kommando}
956 @itemx --process=@var{Kommando}
957 Verarbeitet LilyPond-Fragmente mit @var{Kommando} anstelle des
958 Standardbefehls @code{lilypond}. @code{--filter} und @code{--process}
959 können nicht gleichzeitig angegeben werden.
962 Erzeugt PDF-Dateien mit PDF@LaTeX{}.
966 Gibt ausführliche informative Meldungen aus.
970 Gibt die Versionsnummer aus.
975 Der Texinfo-Befehl @code{@@pagesizes} wird ignoriert. Ebenso werden
976 @LaTeX{}-Befehle ignoriert, die den Seitenrand oder die Zeilenlänge
977 nach der Dokumentpräambel verändern.
979 Nur der erste @code{\score}-Block eines LilyPond-Fragments wird verarbeitet.
982 @node Filename extensions
983 @section Filename extensions
985 Für die Eingabedatei kann zwar jede beliebige Dateinamenserweiterung benutzt
986 werden, allerdings muss bei Verwendung einer nicht bekannten Erweiterung
987 das Ausgabeformat explizit an @command{lilypond-book} angegeben werden.
988 Details dazu finden sich im Abschnitt @ref{Invoking lilypond-book}.
989 Wird eine bekannte Erweiterung benutzt, wählt @command{lilypond-book}
990 automatisch das richtige Ausgabeformat basierend auf der Erweiterung der
994 @multitable @columnfractions .2 .5
995 @item @strong{Erweiterung} @tab @strong{Ausgabeformat}
997 @item @file{.html} @tab HTML
998 @item @file{.itely} @tab Texinfo
999 @item @file{.latex} @tab @LaTeX{}
1000 @item @file{.lytex} @tab @LaTeX{}
1001 @item @file{.lyxml} @tab DocBook
1002 @item @file{.tely} @tab Texinfo
1003 @item @file{.tex} @tab @LaTeX{}
1004 @item @file{.texi} @tab Texinfo
1005 @item @file{.texinfo} @tab Texinfo
1006 @item @file{.xml} @tab HTML
1010 Wird dieselbe Erweiterung für die Eingabedatei wie für die Ausgabedatei
1011 benutzt und befindet sich die Eingabedatei im aktuellen Arbeitsverzeichnis
1012 von @command{lilypond-book}, muss die @code{--output} Option für
1013 @command{lilypond-book} benutzt werden. Anderenfalls würde
1014 @command{lilypond-book} ja die Eingabedatei überschreiben, weshalb das
1015 Programm in diesem Fall mit einer Fehlermeldung wie @qq{Fehler: Ausgabe
1016 würde Eingabedatei überschreiben; verwenden Sie --output.} abbricht.
1019 @node Alternate methods of mixing text and music
1020 @section Alternative methods of mixing text and music
1022 Dieser Abschnitt stellt Methoden vor, wie Text und Musik auf andere
1023 Weise kombiniert werden können als dies durch @command{lilypond-book}
1024 automatisiert geschieht.
1028 * Many quotes from a large score::
1029 * Inserting LilyPond output into OpenOffice.org::
1030 * Inserting LilyPond output into other programs::
1033 @node Many quotes from a large score
1034 @subsection Many quotes from a large score
1036 Wenn aus einer großen Partitur viele kleine Fragmente eingefügt
1037 werden sollen, kann dazu das @q{clip systems} Feature benutzt werden.
1038 Siehe @ruser{Extracting fragments of music}.
1041 @node Inserting LilyPond output into OpenOffice.org
1042 @subsection Inserting LilyPond output into OpenOffice.org
1044 Musik im LilyPond-Format kann in OpenOffice.org eingefügt werden mittels
1045 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
1048 @node Inserting LilyPond output into other programs
1049 @subsection Inserting LilyPond output into other programs
1051 Im die Ausgabe von LilyPond in anderen Programmen einzufügen,
1052 sollte @code{lilypond} benutzt werden. Jedes Beispiel muss
1053 getrennt manuell erzeugt und ins Dokument eingefügt werden;
1054 für letzteres schlagen Sie bitte im Handbuch Ihrer
1055 Textverarbeitungs-Software nach. Die meisten Programme
1056 unterstützen das Einfügen von Grafiken im @file{PNG}-, @file{EPS}-
1057 oder @file{PDF}-Format.
1059 Um den leeren Rand um die Notenzeilen zu verringern, können folgende
1060 Einstellungen benutzt werden:
1068 bookTitleMarkup = ##f
1069 scoreTitleMarkup = ##f
1075 Eine @file{EPS}-Datei kann mit folgendem Befehl erzeugt werden:
1078 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts Dateiname.ly
1080 Eine @file{PNG}-Datei mittels:
1081 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png Dateiname.ly