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@}
375 @command{lilypond-book} stellt auch zahlreiche Kommandozeilen-Optionen zur
376 Verfügung. Für eine Liste dieser Optionen und andere hilfreiche Details zur
377 Verarbeitung von @LaTeX{}-Dokumenten, siehe @ref{Invoking lilypond-book}.
385 Texinfo ist das Standard-Dokumentationsformat des GNU Projekts. Ein Beispiel
386 für ein Dokument im Texinfo Format ist dieses Handbuch, wobei die HTML-, PDF- und
387 Info-Versionen alle aus demselben Texinfo Dokument erzeugt werden.
389 In der Eingabedatei wir Musik eingegeben als
392 @@lilypond[Optionen,kommen,hier]
393 IHR LILYPOND QUELLCODE
401 @@lilypond[Optionen,kommen,hier]@{ IHR LILYPOND QUELLCODE @}
408 @@lilypondfile[Optionen,kommen,hier]@{@var{Dateiname}@}
411 Wenn @command{lilypond-book} eine derartige Datei verarbeitet,
412 wird eine Texinfo-Datei mit der Erweiterung @file{.texi} erzeugt,
413 die @code{@@image} Befehle für die Ausgabe nach HTML, Info und PDF
414 enthält. @command{lilypond-book} erzeugt die entsprechenden Grafiken
415 der Musikbeispiele im EPS- und PDF-Format für die Ausgabe nach PDF
416 und im PNG-Format für die Ausgabe nach HTML und Info.
418 Hier sollen zwei einfache Beispiele gezeigt werden. Eine @code{lilypond} Umgebung
436 @@lilypond[fragment,staffsize=11]@{<c' e' g'>@}
442 @lilypond[fragment,staffsize=11]{<c' e' g'>}
444 Im Gegensatz zu @LaTeX{} erzeugt @code{@@lilypond@{...@}} allerdings keine Grafik
445 im Fließtext, sondern setzt sie immer in einen eigenen Absatz.
451 Musik wird eingegeben als
454 <lilypond fragment relative=2>
455 \key c \minor c4 es g2
460 @command{lilypond-book} erzeugt dann daraus eine HTML-Datei mit den entsprechenden
461 @code{<image>} Tags für die Musikbeispiele in jeweils einem eigenen Absatz.
464 @lilypond[fragment,relative=2]
465 \key c \minor c4 es g2
468 Für Grafiken im Fließtext kann @code{<lilypond ... />} benutzt werden, wobei
469 die Optionen durch einen Doppelpunkt von der Musik getrennt angegeben werden.
472 Musik <lilypond relative=2: a b c/> in derselben Zeile.
475 Um Dateien mit Musik einzubinden, kann folgendermaßen vorgegangen werden:
478 <lilypondfile @var{Option1} @var{Option2} ...>@var{Dateiname}</lilypondfile>
487 Bei der Einbindung von Musik im LilyPond-Format in DocBook soll die
488 Konformität unseres DocBook Dokuments erhalten bleiben und damit
489 die Bearbeiten mit DocBook-Editoren sowie die Validierung weiter
490 möglich bleiben. Aus diesem Grund werden in DocBook keine eigenen Tags
491 wie in HTML benutzt, sondern die von den vorhandenen DocBook-Elementen
492 vorgegebenen Konventionen entsprechend benützt.
494 @subheading Common conventions
496 Für die Einbindung von LilyPond Code werden in allen Fällen die
497 @code{mediaobject} und @code{inlinemediaobject} Elemente benutzt,
498 die unsere Beispiele in einem eigenen Absatz oder im Fließtext
499 einfügen. Die Optionen zur Formatierung mit LilyPond werden dabei
500 in der @code{role} Eigenschaft des innersten Elements angegeben,
501 wie im nächsten Abschnitt gezeigt wird. Die DocBook Datei, die
502 dann von @command{lilypond-book} verarbeitet wird, sollte der Klarheit
503 halber die Dateierweiterung @file{.lyxml} (jedenfalls nicht
504 @file{.xml}) besitzen.
506 @subheading Including a LilyPond file
508 Dies ist der einfachste Fall: Die LilyPond-Datei besitzt die Erweiterung
509 @file{.ly} und wird einfach als @code{imageobject} eingebettet:
514 <imagedata fileref="music1.ly" role="printfilename" />
519 Für das äußerste Element kann je nach Bedarf @code{mediaobject} oder
520 @code{inlinemediaobject} benutzt werden.
522 @subheading Including LilyPond code
524 Die Einbindung von LilyPond-Code direkt in der DocBook-Datei ist
525 durch die Benutzung von @code{programlisting} möglich,
526 wobei die Sprache auf @code{lilypond} gesetzt wird:
531 <programlisting language="lilypond" role="fragment verbatim staffsize=16 ragged-right relative=2">
532 \context Staff \with @{
533 \remove Time_signature_engraver
534 \remove Clef_engraver@}
541 Das äußerste Element ist also @code{mediaobject} oder
542 @code{inlinemediaobject}, welches ein @code{textobject} mit dem
543 @code{programlisting} enthält.
545 @subheading Processing the DocBook document
547 Der Aufruf von @command{lilypond-book} mit der @file{.lyxml}-Datei
548 erzeugt ein gültiges DocBook-Dokument mit der Erweiterung @file{.xml},
549 welches normal weiterverarbeitet werden kann. Bei Benutzung von
550 @uref{http://@/dblatex@/.sourceforge@/.net@/,dblatex} wird daraus
551 automatisch eine PDF-Datei erzeugt. Für die Erzeugung von HTML (HTML
552 Hilfe, JavaHelp, etc.) können die offiziellen DocBook XSL-Stylesheets
553 benutzt werden. Eventuell müssen dafür allerdings kleinere Anpassungen
557 @node Music fragment options
558 @section Music fragment options
560 Im Folgenden meint @q{LilyPond-Kommando} ein beliebiges in den vorgehenden
561 Abschnitten beschriebenes Kommando, welches ein LilyPond-Fragment in eine Datei
562 einfügt und von @command{lilypond-book} verarbeitet wird. Der Einfachheit
563 halber werden hier alle LilyPond-Kommandos in der Syntax von @LaTeX{}
566 Zu beachten ist, dass die Optionen eines LilyPond-Kommandos von links
567 nach rechts verarbeitet werden. Wenn eine Option also mehrfach angegeben
568 wird, wird nur die letzte benutzt.
570 Die folgenden Optionen können für LilyPond-Kommandos benutzt werden:
573 @item staffsize=@var{ht}
574 Setzt die Höhe einer Notenzeile auf @var{ht}, angegeben in Punkten.
577 Erzeugt Notenzeilen im Flattersatz mit natürlichem Abstand der Noten. In
578 anderen Worten: @code{ragged-right = ##t} wird in das Musikfragment
579 eingefügt. Dies ist die Standardeinstellung für das @code{\lilypond@{@}}
580 Kommando, wenn die Option @code{line-width} nicht angegeben wird.
581 Ebenso ist dies die Standardeinstellung für die @code{lilypond}-Umgebung,
582 wenn die Option @code{fragment}, aber keine Zeilenlänge
583 explizit angegeben ist.
586 Streckt Musikfragmente mit nur einer Notenzeile auf die volle Breite,
587 es wird also @code{ragged-right = ##f} in das Musikfragment eingefügt.
589 @c does this option still exist in lilypond? -jm
591 Erzeugt Notenzeilen mit möglichst engem Notenabstand, es wird also
592 @code{packed = ##t} in das Musikfragment eingefügt.
595 @itemx line-width=@var{Breite}\@var{Einheit}
596 Setzt die Breite der Notenzeilen auf @var{Breite}, gemessen in Vielfachen
597 der @var{Einheit}. Als Einheit können die folgenden Zeichenfolgen angegeben
598 werden: @code{cm}, @code{mm}, @code{in} oder @code{pt}. Diese Option hat
599 nur Einfluss auf die Breite von Notenzeilen und Text im Musikfragment, nicht
600 jedoch auf den restlichen Text des Dokuments.
602 Wird diese Option ohne einen Wert angegeben, wird die Zeilenbreite auf
603 einen Standardwert gesetzt, der durch einen heuristischen Algorithmus
606 Wenn die @code{line-width} Option nicht angegeben wird, versucht
607 @command{lilypond-book} einen geeigneten Standardwert für alle
608 @code{lilypond}-Umgebungen zu finden, die die @code{ragged-right} Option
612 Verhindert die Ausgabe der Taktangabe am Anfang des Fragments und schaltet
613 Taktstriche und alle Taktangaben im Fragment ab.
616 Bewirkt, dass @command{lilypond-book} Standardcode um das Fragment herum einfügt, sodass z. B.
623 ohne @code{\layout}, @code{\score}, etc. eingegeben werden kann.
626 Verhindert das Einfügen von Standardcode um das Fragment herum. Dies ist
627 die Standardeinstellung, insofern ist diese Option im Normalfall unnötig.
629 @item indent=@var{Einzug}\@var{Einheit}
630 Setzt den Einzug des ersten Notensystems auf @var{Einzug}, gemessen in
631 Vielfachen der @var{Einheit}. Als Einheit können die folgenden Zeichenfolgen
632 angegeben werden: @code{cm}, @code{mm}, @code{in} oder @code{pt}. Diese
633 Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im
634 Musikfragment, nicht jedoch auf den restlichen Text des Dokuments.
637 Setzt den Einzug des ersten Notensystems auf 0. Diese
638 Option hat nur Einfluss auf den Einzug von Notenzeilen und Text im
639 Musikfragment, nicht jedoch auf den restlichen Text des Dokuments. Dies
640 ist die Standardeinstellung, insofern ist diese Option im Normalfall
644 Verringert die Zeilenlänge des Musikfragments um @math{2*0.4}@dmn{in}
645 und setzt das Fragment in einen Zitat-Block. Der Wert von @q{0.4@dmn{in}}
646 kann durch die @code{exampleindent} Option angepasst werden.
649 Setzt den Betrag, um den das Fragment bei Benutzung der @code{quote}
650 Option eingerückt wird.
653 @itemx relative=@var{n}
654 Benutzt relative Oktavenbezeichnungen. Standardmäßig werden Noten relativ
655 zum mittleren C angegeben. Das optionale ganzzahlige Argument
656 gibt die Oktave der ersten Note an, wobei die Standardeinstellung von
657 @code{1} das mittlere C bedeutet. Die @code{relative} Option macht nur
658 Sinn in Verbindung mit der @code{fragment} Option, weshalb @code{fragment}
659 automatisch durch die Angabe der @code{relative} Option impliziert wird.
660 Eine explizite Angabe der @code{(no)fragment} Option hat keinen Effekt.
663 LilyPond benutzt zur Erzeugung seiner eigenen Dokumentation ebenfalls
664 @command{lilypond-book}. Zu diesem Zweck stehen noch zahlreiche
665 spezialisierte Optionen zur Verfügung:
669 Der LilyPond-Code im LilyPond-Kommando wird zum einen benutzt, um das
670 Musikfragment in eine Grafik mit schönem Notensatz zu konvertieren,
671 andererseits aber auch wörtlich in das Dokument eingefügt. Dies
672 geschieht in einem @q{verbatim}-Block, gefolgt vom Text einer
673 möglicherweise angegebenen @code{intertext} Option@footnote{Die
674 @code{intertext} Option ist noch nicht implementiert.} und der
675 Grafik des tatsächlichen Notensatzes. Diese Option funktioniert nur
676 fehlerhaft, wenn @code{\lilypond@{@}} im Fließtext benutzt wird.
678 Wird @code{verbatim} in Verbindung mit einem @code{lilypondfile}-Kommando
679 benutzt, so ist es auch möglich, nur ein Teil der Datei wörtlich einfügen
680 zu lassen: Wenn die eingebundene LilyPond-Datei ein Kommentar mit dem Inhalt
681 @samp{begin verbatim} (ohne Anführungszeichen) enthält, wird nur der
682 Dateiinhalt ab dieser Position eingefügt. Enthält die Datei mehrere
683 solche Kommentare, wirkt nur das letzte. Analog wird nur der Dateiinhalt
684 bis zu einem etwaigen Kommentar mit dem Inhalt @samp{end verbatim}
685 eingefügt. Im folgenden Beispiel wird das gesamte Musik für die
686 Erzeugung der Grafik im relativen Oktavenmodus interpretiert, der
687 wörtlich in das Dokument kopierte LilyPond-Code zeigt den @code{relative}-Befehl jedoch nicht.
690 \relative c' @{ % begin verbatim
697 erzeugt ein Zitat der Form
705 (Nur innerhalb von Texinfo-Dateien.) Stellt @code{\version
706 @@w@{"@@version@{@}"@}} an den Beginn des Fragments der Ausgabe mit
710 (Nur innerhalb von Texinfo-Dateien.) Wird @command{lilypond} mit der
711 Kommandozeilenoption @option{--header=@/texidoc} für eine Datei
712 @file{foo@/.ly} und enthält die Datei ein @code{texidoc}-Feld im
713 @code{\header}-Block, so wird dessen Inhalt in die Datei
714 @file{foo@/.texidoc} ausgegeben. Die @code{texidoc} Option veranlasst
715 @code{lilypond-book}, den Inhalt dieser @file{.texidoc} Dateien innerhalb
716 eines Dokumentationsblocks direkt vor dem Musikfragment in das aktuelle
719 Enthält also die Datei @file{foo@/.ly} etwa den LilyPond-Code
723 texidoc = "Dieses Beispiel zeigt eine einzelne Note."
729 und das Texinfo-Dokument @file{text.texinfo}
732 @@lilypondfile[texidoc]@{foo.ly@}
736 so liefert der folgende Aufruf von @code{lilypond-book} das gewünschte
740 lilypond-book --process="lilypond --format=tex --tex \
741 --header=texidoc test.texinfo
744 Die meisten Test-Dateien (im @file{input/} Verzeichnis von LilyPond)
745 sind kleine @file{.ly} Dateien von genau dieser Form.
747 Auch die Übersetzung dieser zusätzlichen Kommentare ist möglich:
748 Dazu muss das Texinfo-Dokument den Befehl @code{@@documentlanguage @var{LANG}}
749 und der @code{\header} Block in der Datei @file{foo@/.ly}
750 die Übersetzung im Feld @code{texidoc@var{LANG}} enthalten. Wird nun
751 @command{lilypond} mit der Option @option{--header=@/texidoc@var{LANG}}
752 aufgerufen, so wird der Inhalt der Datei @file{foo@/.texidoc@var{LANG}} anstelle von @file{foo@/.texidoc} eingefügt.
755 (Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt wie die @code{quote} Option, außer dass nur das Musikfragment (und natürlich optional der
756 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.
759 (Nur innerhalb von Texinfo-Dateien.) Diese Option wirkt ähnlich wie die
760 @code{texidoc} Option: Wenn @command{lilypond} mit der Option
761 @option{--header=@/doctitle} aufgerufen wird und die Eingabedatei
762 @file{foo@/.ly} ein Feld @code{doctitle} im @code{\header}-Block enthält,
763 wird dessen Wert in die Datei @file{foo@/.doctitle} geschrieben. Wird die
764 @code{doctitle} Option für ein Musikfragment benutzt, so wird der Inhalt
765 dieser Datei, der eine einzelne Textzeile sein sollte, im Texinfo-Dokument
766 als @code{@@lydoctitle @var{Text}} eingefügt. @code{@@lydoctitle} muss
767 allerdings in Ihrem Texinfo-Dokument als Makro selbst definiert werden.
768 Die Übersetzung funktioniert völlig analog zu @code{texidoc}.
771 Wenn eine LilyPond-Datei mittels @code{\lilypondfile} und dieser Option
772 eingebunden wird, wird der Dateiname (ohne die Pfadangabe) unmittelbar vor
773 dem Musikfragment ausgegeben. In HTML-Dateien ist er außerdem ein Link
774 auf die LilyPond-Datei.
777 Diese Option inkludiert die Schriftarten in allen EPS-Dateien, die von
778 diesem Fragment erzeugt werden. Dies ist nötig, wenn das Fragment
779 Schriftarten benutzt, die @LaTeX{} nicht selbst findet.
784 @node Invoking lilypond-book
785 @section Invoking @command{lilypond-book}
787 @command{lilypond-book} erzeugt abhängig vom Ausgabeformat eine Datei mit
788 einer der folgenden Dateierweiterungen: @file{.tex}, @file{.texi},
789 @file{.html} oder @file{.xml}. Alle @file{.tex}, @file{.texi} und
790 @file{.xml} Dateien müssen noch mit den entsprechenden Programmen (@LaTeX{},
791 DocBook, etc.) weiter verarbeitet werden, um druckfähige Dateien zu erhalten.
794 @subheading Format-specific instructions
796 @subsubheading @LaTeX{}
798 Es existieren zwei Methoden, Ihr @LaTeX{}-Dokument weiter zu verarbeiten,
799 um zu einer druck- oder publikationsfähigen Datei zu gelangen:
800 Zum einen die direkte Erzeugung einer PDF-Datei mit PDF@LaTeX{}, zum
801 anderen die Erzeugung einer DVI daraus einer PostScript-Datei mittels
802 @LaTeX{} und einem DVI-nach-PostScript Konverters wie @command{dvips}.
803 Die erste Methode ist einfacher und daher empfehlenswert.@footnote{Manchmal
804 kann eine Datei entweder von PDF@LaTeX{} oder von @LaTeX{} nicht korrekt
805 verarbeitet werden, weshalb hier beide Methoden beschrieben werden.} Welche
806 Methode auch immer benutzt wird, die Konvertierung zwischen PostScript und
807 PDF kann leicht mit Hilfsprogrammen wie @command{ps2pdf} und @command{pdf2ps}
808 (aus dem Ghostscript Paket) erfolgen.
810 Um eine PDF-Datei mittels PDF@LaTeX{} zu erzeugen, kann folgendermaßen
814 lilypond-book --pdf Ihre_Datei.pdftex
815 pdflatex Ihre_Datei.tex
818 @cindex Konturschriften
819 @cindex Type1 Schriften
821 @cindex Aufruf von dvips
822 Um eine PDF-Datei mittels @LaTeX{}/@command{dvips}/@command{ps2pdf} zu
823 erhalten, sind folgende Befehle nötig:
826 lilypond-book Ihre_Datei.lytex
828 dvips -Ppdf Ihre_Datei.dvi
833 Die @file{.dvi}-Datei, die beim Aufruf von @command{latex} erzeugt wird,
834 scheint keine Notenköpfe zu enthalten, was in Ordnung ist. Wenn Sie die
835 Datei wie beschrieben weiter verarbeiten, erscheinen die Notenköpfe korrekt
836 in den @file{.ps} und @file{.pdf} Dateien.
838 Der Aufruf von @command{dvips} kann einige Warnungen über fehlende
839 Schriftarten ausgeben. Auch dies ist in Ordnung und kann ignoriert werden.
841 Wenn Sie in der @LaTeX{}-Datei das Papierformat auf Querformat eingestellt
842 haben, vergessen Sie nicht auf die @code{-t landscape} Option beim
843 Aufruf von @command{dvips}.
846 @subsubheading Texinfo
848 Um ein von @command{lilypond-book} erzeugtes Texinfo-Dokument zu
849 verarbeiten, gehen Sie wie für alle anderen Texinfo-Dokumente vor:
850 Rufen Sie -- abhängig vom gewünschten Ausgabeformat -- eines der Programme
851 @command{texi2pdf}, @command{texi2dvi}, @command{makeinfo} oder
852 @command{texi2html} auf.
855 @xref{Format with texi2dvi, , , texinfo, GNU Texinfo}, und @ref{Creating
856 an Info File, , , texinfo, GNU Texinfo}.
859 Die Dokumentation von Texinfo liefert dazu nähere Informationen.
863 @subheading Command line options
865 @command{lilypond-book} unterstützt die folgenden Kommandozeilenoptionen:
868 @item -f @var{Format}
869 @itemx --format=@var{Format}
870 Gibt das Format des Eingabedokuments an: @code{html}, @code{latex},
871 @code{texi} (Standardeinstellung), @code{texi-html} oder @code{docbook}.
872 Ist diese Option nicht angegeben, versucht @command{lilypond-book} das
873 Format anhand des Dateinamens zu bestimmen. Im Moment bedeutet @code{texi}
874 praktisch dasselbe wie @code{texi-html}.
876 @c This complicated detail is not implemented, comment it out -jm
878 The @code{texi} document type produces a Texinfo file with music
879 fragments in the printed output only. For getting images in the HTML
880 version, the format @code{texi-html} must be used instead.
883 @item -F @var{Filter}
884 @itemx --filter=@var{Filter}
885 Leitet die Musikfragmente durch das Programm @var{filter} anstatt sie
886 mit Lilypond zu einer Grafik zu verarbeiten. @option{--filter} und
887 @option{--process} kann nicht gleichzeigt benutzt werden. Beispielaufruf:
890 lilypond-book --filter='convert-ly --from=2.0.0 -' Mein-Buch.tely
895 Gibt eine kurze Hilfemeldung aus.
898 @itemx --include=@var{Pfad}
899 Fügt @var{Pfad} zu den Include-Pfaden hinzu. @command{lilypond-book} sucht
900 auch in allen Include-Pfaden nach bereits erstellten Grafiken für die
901 Musikfragmente. Wird das aktuelle Fragment gefunden und hat sich seit der
902 letzten Erstellung nicht geändert, wird es nicht erneut erzeugt. Bei manchen
903 der Programme zur Weiterverarbeitung wie etwa @command{makeinfo} oder
904 @command{latex} muss dieselbe @code{-I @var{Pfad}} Option angegeben werden,
905 damit das entsprechende Programm die Grafiken ebenso findet.
907 @item -o @var{Verzeichnis}
908 @itemx --output=@var{Verzeichnis}
909 Erzeugt die Ausgabedateien in @var{Verzeichnis}. Der Aufruf von
910 @command{lilypond-book} erzeugt zahlreiche kleine Dateien, die von
911 LilyPond, @command{latex}, @command{makeinfo} etc. dann weiter benützt
912 werden. Um zu vermeiden, dass das Quellenverzeichnis durch diese
913 Dateien unübersichtlich wird, kann die @option{--output} Option benutzt
914 werden. Vor dem Aufruf von @command{latex} oder @command{makeinfo}
915 sollten Sie in dieses Verzeichnis wechseln.
918 lilypond-book --output=out IhreDatei.lytex
923 @itemx --skip-lily-check
924 Nicht mit einer Fehlermeldung abbrechen, wenn keine Ausgabe von LilyPond
925 gefunden wird. Dies wird benutzt für Dokumentation ohne Grafiken.
927 @itemx --skip-png-check
928 Nicht mit einer Fehlermeldung abbrechen, wenn für die EPS-Dateien keine
929 PNG-Grafiken gefunden werden. Dies wird benutzt für Dokumentation ohne
932 @itemx --lily-output-dir=@var{Verzeichnis}
933 Schreibt @file{lily-XXX} Dateien nach @var{Verzeichnis} und erzeugt
934 im mit @code{--output} angegebenen Verzeichnis Verknüpfungen darauf.
935 Diese Option ist nützlich, um Zeit zu sparen, wenn Dokumente in
936 verschiedenen Verzeichnissen viele identische Musikfragmente
939 @itemx --info-images-dir=@var{Verzeichnis}
940 Formatiert die Texinfo-Ausgabe dergestalt, dass Info in @var{Verzeichnis}
941 nach den Grafiken zu den Musikfragmenten sucht.
943 @itemx --latex-program=@var{Programm}
944 Führt @command{Programm} anstelle von @command{latex} aus. Dies ist
945 nützlichen, wenn das Dokument mit einer anderen @LaTeX{}-Variante
946 wie etwa @command{xelatex} verarbeitet werden soll.
948 @itemx --left-padding=@var{Einrückung}
949 Fügt @var{Einrückung} als zusätzlichen Einzug in die EPS-Box ein.
950 @var{Einrückung} wird in Millimetern angegeben, die Standardeinstellung
951 is 3.0 Millimeter. Diese Option kann benutzt werden, wenn die Notenzeilen
952 über den Rand des Dokuments hinausstehen.
954 Die Breite eines eng ausgeschnittenen Notensystems kann variieren
955 aufgrund von Notationselementen, die über den linken Rand hinausstehen,
956 wie etwa Taktzahlen und Bezeichnungen der Instrumente. Diese Option
957 verkürzt die Notenzeile und verschiebt sie um denselben Betrag nach
961 @item -P @var{Kommando}
962 @itemx --process=@var{Kommando}
963 Verarbeitet LilyPond-Fragmente mit @var{Kommando} anstelle des
964 Standardbefehls @code{lilypond}. @code{--filter} und @code{--process}
965 können nicht gleichzeitig angegeben werden.
968 Erzeugt PDF-Dateien mit PDF@LaTeX{}.
972 Gibt ausführliche informative Meldungen aus.
976 Gibt die Versionsnummer aus.
981 Der Texinfo-Befehl @code{@@pagesizes} wird ignoriert. Ebenso werden
982 @LaTeX{}-Befehle ignoriert, die den Seitenrand oder die Zeilenlänge
983 nach der Dokumentpräambel verändern.
985 Nur der erste @code{\score}-Block eines LilyPond-Fragments wird verarbeitet.
988 @node Filename extensions
989 @section Filename extensions
991 Für die Eingabedatei kann zwar jede beliebige Dateinamenserweiterung benutzt
992 werden, allerdings muss bei Verwendung einer nicht bekannten Erweiterung
993 das Ausgabeformat explizit an @command{lilypond-book} angegeben werden.
994 Details dazu finden sich im Abschnitt @ref{Invoking lilypond-book}.
995 Wird eine bekannte Erweiterung benutzt, wählt @command{lilypond-book}
996 automatisch das richtige Ausgabeformat basierend auf der Erweiterung der
1000 @multitable @columnfractions .2 .5
1001 @item @strong{Erweiterung} @tab @strong{Ausgabeformat}
1003 @item @file{.html} @tab HTML
1004 @item @file{.itely} @tab Texinfo
1005 @item @file{.latex} @tab @LaTeX{}
1006 @item @file{.lytex} @tab @LaTeX{}
1007 @item @file{.lyxml} @tab DocBook
1008 @item @file{.tely} @tab Texinfo
1009 @item @file{.tex} @tab @LaTeX{}
1010 @item @file{.texi} @tab Texinfo
1011 @item @file{.texinfo} @tab Texinfo
1012 @item @file{.xml} @tab HTML
1016 Wird dieselbe Erweiterung für die Eingabedatei wie für die Ausgabedatei
1017 benutzt und befindet sich die Eingabedatei im aktuellen Arbeitsverzeichnis
1018 von @command{lilypond-book}, muss die @code{--output} Option für
1019 @command{lilypond-book} benutzt werden. Anderenfalls würde
1020 @command{lilypond-book} ja die Eingabedatei überschreiben, weshalb das
1021 Programm in diesem Fall mit einer Fehlermeldung wie @qq{Fehler: Ausgabe
1022 würde Eingabedatei überschreiben; verwenden Sie --output.} abbricht.
1025 @node Alternate methods of mixing text and music
1026 @section Alternative methods of mixing text and music
1028 Dieser Abschnitt stellt Methoden vor, wie Text und Musik auf andere
1029 Weise kombiniert werden können als dies durch @command{lilypond-book}
1030 automatisiert geschieht.
1034 * Many quotes from a large score::
1035 * Inserting LilyPond output into OpenOffice.org::
1036 * Inserting LilyPond output into other programs::
1039 @node Many quotes from a large score
1040 @subsection Many quotes from a large score
1042 Wenn aus einer großen Partitur viele kleine Fragmente eingefügt
1043 werden sollen, kann dazu das @q{clip systems} Feature benutzt werden.
1044 Siehe @ruser{Extracting fragments of music}.
1047 @node Inserting LilyPond output into OpenOffice.org
1048 @subsection Inserting LilyPond output into OpenOffice.org
1050 Musik im LilyPond-Format kann in OpenOffice.org eingefügt werden mittels
1051 @uref{http://@/ooolilypond@/.sourceforge@/.net@/,OOoLilyPond}.
1054 @node Inserting LilyPond output into other programs
1055 @subsection Inserting LilyPond output into other programs
1057 Im die Ausgabe von LilyPond in anderen Programmen einzufügen,
1058 sollte @code{lilypond} benutzt werden. Jedes Beispiel muss
1059 getrennt manuell erzeugt und ins Dokument eingefügt werden;
1060 für letzteres schlagen Sie bitte im Handbuch Ihrer
1061 Textverarbeitungs-Software nach. Die meisten Programme
1062 unterstützen das Einfügen von Grafiken im @file{PNG}-, @file{EPS}-
1063 oder @file{PDF}-Format.
1065 Um den leeren Rand um die Notenzeilen zu verringern, können folgende
1066 Einstellungen benutzt werden:
1074 bookTitleMarkup = ##f
1075 scoreTitleMarkup = ##f
1081 Eine @file{EPS}-Datei kann mit folgendem Befehl erzeugt werden:
1084 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts Dateiname.ly
1086 Eine @file{PNG}-Datei mittels:
1087 lilypond -dbackend=eps -dno-gs-load-fonts -dinclude-eps-fonts --png Dateiname.ly