1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: 317e451cbe00c0fa25e177976327e260f3dc6539
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
12 @node Running LilyPond
13 @chapter Running LilyPond
15 Dieses Kapitel behandelt die technischen Details, wie Lilypond ausgeführt werden kann.
20 * Command-line usage::
22 * Updating files with convert-ly::
29 Die meisten Benutzer führen LilyPond von einer graphischen Benutzeroberfläche
30 aus. Siehe @rlearning{First steps}, falls Sie dies nicht bereits getan haben.
33 @node Command-line usage
34 @section Command-line usage
36 Dieser Abschnitt enthält zusätzliche Informationen, wie Sie LilyPond
37 von der Kommandozeile ausführen können. Dies kann erforderlich sein,
38 um etwa zusätzliche Optionen an das Programm zu übergeben. Außerdem
39 sind einige Zusatzprogramme (wie etwa @code{midi2ly}) nur von der
40 Kommandozeile verfügbar.
42 Unter @q{Kommandozeile} verstehen wir die Kommandozeile des jeweiligen
43 Betriebssystems. Windows Benutzern ist sie vielleicht eher unter den
44 englischen Begriffen @q{DOS shell} oder @q{command shell} bekannt.
45 MacOS@tie{}X Benutzer kennen sie eher unter @q{Terminal} oder @q{Konsole}.
46 Sie sollten auch den Abschnitt @ref{MacOS X on the command-line} konsultieren.
48 Wie die Kommandozeile im jeweiligen Betriebssystem benutzt werden kann,
49 soll in diesem Handbuch nicht näher beschrieben werden. Sehen Sie bitte
50 im Handbuch Ihres Betriebssystems nach oder informieren Sie sich im
51 Internet, wenn Sie mit der Kommandozeile nicht vertraut sind.
56 * Command line options::
57 * Environment variables::
60 @node Invoking lilypond
61 @subsection Invoking lilypond
63 @cindex LilyPond aufrufen
64 @cindex Kommandozeilen-Optionen
65 @cindex Optionen an der Kommandozeile
67 Das @command{lilypond} Programm kann folgendermaßen von der Kommandozeile
71 lilypond [@var{Option}]@dots{} @var{Dateiname}@dots{}
75 Wird ein @file{Dateiname} ohne Erweiterung angegeben, so wird @file{.ly} als
76 Standarderweiterung für LilyPond-Dateien benutzt. Um Daten von
77 @code{stdin} einzulesen, benutzen Sie einfach einen Bindestrich (@code{-})
80 Wenn Lilypond die Datei @file{Dateiname.ly} verarbeitet, werden daraus
81 die Dateien @file{Dateiname.ps} und @file{Dateiname.pdf} erzeugt.
82 Es können an @code{lilypond} auch mehrere @file{.ly} Dateien übergeben
83 werden, die dann einzeln und voneinander unabhängig abgearbeitet
84 werden.@footnote{Der Zustand von GUILE wird allerdings nicht nach
85 jeder Datei zurückgesetzt, sodass Achtung geboten ist, wenn in einer
86 Datei globale Änderungen von Scheme aus durchgeführt werden.}
88 Falls @file{Dateiname.ly} mehr als einen @code{\score}-Block enthält,
89 werden die weiteren Stücke in durchnummerierte Dateien der Form
90 @file{Dateiname-1.pdf} ausgegeben. Zusätzlich wird der Wert der
91 Variable @code{output-suffix} zwischen den ursprünglichen Dateienamen
92 und der Zahl eingefügt. Eine Lilypond-Datei @var{Dateiname.ly} mit dem Inhalt
95 #(define output-suffix "Geige")
97 #(define output-suffix "Cello")
102 erzeugt daher die Dateien @var{Dateiname}@file{-Geige.pdf} und
103 @var{Dateiname}@file{-Cello-1.pdf}.
107 @node Command line options
108 @subsection Command line options
110 Die folgenden Kommandozeilenoptionen werden von @command{lilypond} unterstützt:
114 @item -e,--evaluate=@var{expr}
115 Wertet den Scheme-Ausdruck @var{expr} aus, bevor die @file{.ly} Dateien
116 gelesen und interpretiert werden.
117 Die @code{-e} Option kann auch mehrfach angegeben werden, die Ausdrücke
118 werden nacheinander ausgewertet.
120 Da der Ausdruck im @code{guile-user} Modul ausgewertet wird, ist bei der
121 Definitionen innerhalb von @var{expr} folgendes Vorgehen nötig. An der
122 Kommandozeile wird z.B. @code{a} im @code{guile-user} Modul definiert:
125 lilypond -e '(define-public a 42)'
129 Am Beginn der @file{.ly}-Datei muss dann das @code{guile-user} Modul noch geladen werden, bevor die Definition von @var{a} verfügbar ist:
132 #(use-modules (guile-user))
136 @item -f,--format=@var{Format}
137 Bestimmt das Ausgabeformat. Mögliche Werte von @var{Format} sind
138 @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex} und @code{dvi}.
140 Beispiel: @code{lilypond -fpng @var{Dateiname}.ly}
144 @item -d,--define-default=@var{Variable}=@var{Wert}
145 Damit wird die interne Programmoption @var{Variable} auf den Scheme-Wert
146 @var{Wert} gesetzt. Wird kein @var{Wert} angegeben, so wird @var{#t} benutzt.
147 Um eine Option auszuschalten, kann der Präfix @code{no-} dem Namen
148 @var{Variable} der Variable vorangestellt werden. So ist etwa
150 @cindex Point and Click, Kommandozeile
159 -dpoint-and-click='#f'
162 Hier sind ein paar interessante Optionen:
166 Die Ausführung von @code{lilypond -dhelp} zeigt alle verfügbaren @code{-d}
170 Setzt das Standard-Papierformat,
172 -dpaper-size=\"letter\"
176 Die Zeichenkette, die das Format angibt, muss in Anführungszeichen mit Backslash
177 ( @code{\"} ) stehen.
181 Vertraut der @code{.ly} Datei nicht.
183 Wenn LilyPond über einen Webserver verfügbar gemacht wird, @b{MUSS} unbedingt
184 eine die Optionen @code{--safe} oder @code{--jail} angegeben werden.
185 Die @code{--safe} Option verhindert, dass in der .ly-Datei angegebener
186 Scheme-Code das System gefährden kann, wie etwa in folgendem Beispiel:
192 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
197 Mit der @code{-dsafe} Option werden alle Scheme-Ausdrücke einem speziellen
198 sicheren Modus ausgewertet. Dieser Modus ist vom GUILE @file{safe-r5rs} Modul
199 abgeleitet und fügt noch zahlreiche weitere erlaubte Funktionen der
200 LilyPond Programm-Schnittstelle hinzu. Diese Funktionen sind in
201 @file{scm/@/safe@/-lily@/.scm} angegeben.
203 Zusätzliche verbietet der sichere Modus auch @code{\include} Befehle sowie
204 die Benutzung eines Backslashs in @TeX{} Zeichenketten.
206 Im sicheren Modus ist es nicht möglich, LilyPond-Variablen nach Scheme
209 @code{-dsafe} erkennt jedoch @emph{KEINE} Überbeanspruchung der verfügbaren
210 Ressourcen. In diesem Modus ist es also trotzdem möglich, dass LilyPond in einer
211 Endlosschleife hängt, z.B. wenn zyklische Datenstrukturen an das Backend
212 übergeben werden. Wenn LilyPond also auf einem öffentlich zugänglichen
213 Webserver verfügbar gemacht wird, sollte der Prozess sowohl in der CPU-
214 als auch in der Speichernutzung limitiert werden.
216 Der sichere Modus verhindert auch, dass zahlreiche nützliche
217 Musikfragmente von LilyPond verarbeitet werden. Die @code{--jail} Option ist
218 eine sicherere Alternative, benötigt allerdings auch mehr Aufwand zur
222 Gibt an, welches Ausgabeformat das LilyPond Backend benutzt. Mögliche Werte
223 für diese Option sind:
226 @TeX{}-Ausgabeformat, das mit La@TeX{} weiterverarbeitet werden kann. Falls sie
227 existiert, wird die Datei @file{file.textmetrics} gelesen, um die Textweiten
230 Schreibt alle Zeichenketten in eine @file{.texstr}-Datei, die mit (La)@TeX{}
231 verarbeitet werden kann, um eine @code{.textmetrics}-Datei mit den Textweiten
232 zu erstellen. @strong{Achtung:} Diese Funktionalität ist momentan nicht
233 verfügbar, da der Quellcode stark umstrukturiert wurde.
235 PostScript-Ausgabeformat.
236 @cindex PostScript Ausgabeformat
238 Postscript-Dateien enthalten auch TTF-, Type1- und OTF-Schriften. Allerdings
239 wird die gesamte Schriftart eingefügt und nicht nur die benötigten Zeichen.
240 Vor allem wenn nicht-westliche Zeichensätze benutzt werden, kann dies zu sehr
241 großen Dateien führen.
244 Erzeugt @q{encapsulated PostScript} (EPS). Jede Seite (oder jedes System) wird
245 als eigene @file{EPS}-Datei ausgegeben, inklusive Schriftarten. Außerdem wird
246 eine Datei mit allen Seiten (bzw. Systemen) und Schriftarten erzeugt.
248 Dies ist die Standardeinstellung von @command{lilypond-book}.
251 SVG-Ausgabe (Scalable Vector Graphics). Jede Seite wird als eigene
252 @file{SVG}-Datei ausgegeben, inklusive eingebetteten Schriftarten.
253 @cindex SVG (Scalable Vector Graphics)
254 Sie benötigen einen SVG-Betrachter, der eingebettete Schriftarten unterstützt,
255 oder einen SVG-Betrachter, der eingebettete Schriftarten durch OTF-Schriften
256 ersetzen kann. In UNIX und Linux kann z.B. @uref{http://www.inkscape.org,Inkscape}
257 (ab Version 0.42) benutzt werden, nachdem die OTF-Schriften aus dem
258 LilyPond-Verzeichnis (typischerweise @file{/usr/share/lilypond/VERSION/fonts/otf/})
259 in das Verzeichnis @file{~/.fonts/} kopiert wurden.
261 Gibt die rohen Scheme-basierenden Zeichenbefehle aus, wie sie intern von
262 LilyPond benutzt werden.
266 Beispiel: @code{lilypond -dbackend=svg @var{Dateiname}.ly}
268 @cindex Ausgabeformat
271 Erzeugt eine Ausgabedatei, die nur die Titelzeilen und das erste System
275 Erzeugt vollständige Seiten (Standardeinstellung). @code{-dno-print-pages}
276 ist in Verbindung mit @code{-dpreview} nützlich.
283 Zeigt eine Zusammenfassung der Programmbenutzung und der Optionen.
285 @item -H,--header=@var{FELD}
286 Gibt den Inhalt eines Feldes aus dem @code{\header}-Block in die Datei
287 @file{Dateiname.@var{FELD}} aus.
289 @item --include, -I=@var{Verzeichnis}
290 Fügt @var{Verzeichnis} zur Liste der Suchpfade hinzu.
294 @item -i,--init=@var{Initialisierungsdatei}
295 Benutzt @var{Initialisierungsdatei} zur gesamten Programminitialisierung. Der
296 Standardwert ist @file{init.ly}.
298 @item -o,--output=@var{DATEI}
299 Schreibt das Ergebnis der Verarbeitung mit LilyPond in die Ausgabedatei
300 @var{DATEI}. Die entsprechende Dateinamenserweiterung wird angehängt (z.B.
301 @code{.pdf} für pdf, @code{.tex} für tex, etc.).
307 Erzeugt DVI-Dateien. In diesem Fall sollte das @TeX{}-Backend angegeben werden,
308 d.h. auch @code{-dbackend=tex}.
311 Erzeugt eine Grafik-Datei im PNG-Format von jeder Seite. Diese Option
312 impliziert auch @code{--ps}. Die Auflösung in DPI der Grafik kann festgelegt
319 Erzeugt PDF-Dateien. Dies impliziert @code{--ps}.
323 @item -j,--jail=@var{Benutzer},@var{Gruppe},@var{Jail-Verzeichnis},@var{Arbeitsverzeichnis}
324 Führt @command{lilypond} in einem chroot-Jail aus.
326 Die @code{--jail} Option ist eine flexiblere Alternative zu @code{--safe}, wenn
327 LilyPond über das Internet verfügbar gemacht wird oder LilyPond-Quelldateien
328 von Dritten automatisch vararbeitet werden.
330 Sie funktioniert dergestalt, dass das Wurzelverzeichnis von
331 @command{lilypond} auf @var{Jail-Verzeichnis} gesetzt wird, bevor die
332 tatsächliche Kompilierung der .ly-Datei beginnt. Der Benutzer und die Gruppe
333 werden auf die angegebenen Werte gesetzt und das aktuelle Arbeitsverzeichnis
334 wird ebenfalls auf den angegebenen Wert @var{Arbeitsverzeichnis} gesetzt.
335 Diese Einstellungen garantieren (zumindest in der Theorie), dass es nicht
336 möglich ist, aus dem Jail auszubrechen. Damit @code{--jail} funktioniert, muss
337 @command{lilypond} allerdings als root ausgeführt werden, was normalerweise
338 auf sichere Art mit dem Kommando @command{sudo} erreicht werden kann.
340 Das Jail-Verzeichnis zu erstellen ist etwas heikel, da LilyPond alle zur
341 Ausführung nötigen Bibliotheken und Dateien @emph{innerhalb des
342 Jail-Verzeichnisses} finden muss. Ein typisches Setup besteht aus folgenden
346 @item Erstellung eines getrennten Dateisystems
347 Ein eigenes Dateisystem muss für LilyPond erstellt werden, sodass es mit
348 sicheren Einstellungen wie @code{noexec}, @code{nodev} und @code{nosuid}
349 eingebunden werden kann. Damit ist es unmöglich, Programme von diesem
350 Dateisystem auszuführen oder direkt auf eine Hardware-Schnittstelle
351 zuzugreifen. Wenn Sie keine eigene Partition erstellen möchten, können Sie
352 auch eine Datei der entsprechenden Größe erstellen und sie als @q{loop}-Gerät
353 einbinden. Ein getrenntes Dateisystem garantiert auch, dass LilyPond nicht
354 mehr Festplattenspeicher benutzt als erlaubt.
356 @item Erstellung eines eigenen Benutzerkontos
357 Es sollte ein eigener Benutzer und eine eigene Gruppe (z. B.
358 @code{lily}/@code{lily}) mit geringen Rechten für die Ausführung von LilyPond
359 innerhalb des Jails benutzt werden. Nur ein einziges Verzeichnis des Jails sollte
360 für den Benutzer schreibbar sein und als @var{Arbeitsverzeichnis} an
361 @code{lilypond} übergeben werden.
363 @item Einrichtung des Jails
364 LilyPond muss zahlreiche Dateien für die Ausführung einlesen. All diese
365 Dateien müssen in das Jail-Verzeichnis kopiert werden (mit denselben Pfaden
366 wie im tatsächlichen Wurzel-Dateisystem). Die gesamte LilyPond-Installation
367 (typischerweise @file{/usr/share/lilypond}) sollte kopiert werden.
369 Falls Probleme auftreten, ist es am einfachsten, Lilypond mittels
370 @command{strace} zu starten, wodurch Sie relativ leicht feststellen können,
371 welche Dateien im Jail noch fehlen.
373 @item Ausführung von LilyPond
374 In einem mit @code{noexec} eingebundenen Jail ist es nicht möglich, externe
375 Programme auszuführen. Daher muss LilyPond auf eine Art gestartet werden,
376 die keine weitere Ausführung von Programmen benötigt. Wie bereits erwähnt
377 muss LilyPond mit Administrator-Rechten gestartet werden (die es allerdings
378 sofort wieder abgibt), beispielsweise mittels @command{sudo}. Außerdem
379 ist es eine gute Idee, die LilyPond zur Verfügung stehende CPU-Zeit zu
380 limitieren (z. B. mit @command{ulimit -t}) und -- falls das Betriebssystem
381 dies unterstützt -- auch den zur Verfügung stehenden Hauptspeicher.
386 Gibt die Versionsnummer aus.
389 Gibt ausführliche informative Meldungen aus: Zeigt die vollen Dateipfade
390 aller gelesenen Dateien sowie Informationen über die Laufzeit.
393 Zeigt die Garantiebedingungen an, unter denen GNU LilyPond steht. (Es besteht
394 @strong{KEINERLEI GARANTIE}!)
398 @node Environment variables
399 @subsection Environment variables
402 @cindex LILYPOND_DATADIR
404 @command{lilypond} erkennt und benützt die folgenden Umgebungsvariablen:
406 @item LILYPOND_DATADIR
407 Diese Variable gibt das Verzeichnis an, wo Lilypond seine eigenen Dateien,
408 Meldungen und Übersetzungen finden kann. Dieses Verzeichnis sollte
409 Unterverzeichnisse @file{ly/}, @file{ps/}, @file{tex/}, etc. beinhalten.
412 Gibt die Sprache an, in der Warnungen und Fehlermeldungen ausgegeben werden.
414 @item LILYPOND_GC_YIELD
415 Mit dieser Variable (mit Werten zwischen 0 und 100) kann die Feinabstimmung
416 zwischen dem Bedarf an Hauptspeicher und Rechenleistung bei der Ausführung
417 von LilyPond durchgeführt werden. Bei höheren Werten benutzt LilyPond
418 mehr Hauptspeicher, benötigt aber weniger Prozessor-Leistung. Bei
419 niedrigeren Werten wird mehr Prozessor-Zeit, dafür weniger Hauptspeicher
420 benötigt. Voreinstellung ist ein Wert von @code{70}.
426 @section Error messages
428 @cindex error messages
429 Während der Verarbeitung einer Dateien können diverse Meldungen an der
430 Kommandozeile auftreten:
436 Irgendetwas ist verdächtig. Wenn Sie etwas Ungewöhnliches in Ihrer
437 Datei durchführen, dann werden Sie die Meldung verstehen und können
438 sie gegebenenfalls ignorieren. Im Normalfall jedoch bedeutet eine
439 Warnung, dass mit Ihrer Datei etwas nicht stimmt, LilyPond jedoch
440 trotzdem versucht, die Datei soweit wie möglich korrekt zu übersetzen.
444 Irgendetwas stimmt definitiv nicht. Der aktuelle Bearbeitungsschritt
445 (Einlesen, Interpretieren oder Formatieren der Datei) wird noch fertig
446 ausgeführt, danach bricht die Bearbeitung aber ab.
449 @cindex Fataler Fehler
450 Irgendetwas stimmt definitiv nicht und LilyPond kann nicht weiter
451 ausgeführt werden. Dies ist nur sehr selten der Fall, meist sind
452 die Schriftarten nicht korrekt installiert.
455 @cindex Fehlerprotokoll, Scheme
456 @cindex Scheme Fehler
457 Fehler, die während der Ausführung von Scheme-Code auftreten, werden
458 vom Scheme-Interpreter aufgefangen und an der Kommandozeile ausgegeben.
459 Wenn Sie LilyPond mit der @code{--verbose} Option (auch @code{-V})
460 ausführen, wird der sogennante @q{Call trace} ausgegeben, der die
461 aufgerufenen Funktionen zur Zeit des Fehlers angibt.
463 @item Programmierfehler
464 @cindex Programmierfehler
465 Eine interne Inkonsistenz ist aufgetreten. Diese Fehlermeldungen
466 sollen den Programmierern die Fehlersuche erleichtern und
467 können meistens einfach ignoriert werden. In manchen Fällen werden
468 so viele Meldungen ausgegeben, dass die Lesbarkeit der restliche
469 Ausgabe davon beeinträchtigt wird.
471 @item Abgebrochen (core dumped)
472 Dies bezeichnet einen ernsten Programmierfehler, der das Programm
473 zum Absturz gebracht hat. Solche Fehler werden als kritisch angesehen.
474 Falls daher einer auftritt, senden Sie bitte einen Bug-Report!
477 @cindex Fehlermeldung, Format
478 @cindex Form der Fehlermeldungen
479 Wenn Warnungen oder Fehlermeldungen mit einer konkreten Stelle in der
480 Eingabedatei verknüpft werden können, dann hat die Meldung die folgende
484 @var{Dateiname}:@var{Zeile}:@var{Spalte}: @var{Meldung}
485 @var{Fehlerhafte Eingabezeile}
488 Ein Zeilenumbruch wird in der fehlerhaften Zeile an jener Stelle eingefügt,
489 wo der Fehler aufgetreten ist. Zum Beispiel
492 test.ly:2:19: Fehler: keine gültige Dauer: 5
497 Diese Stellen sind LilyPonds Vermutung, wo die Warnung oder der Fehler
498 aufgetreten ist, allerdings treten Warnungen und Fehler ja gerade in
499 unerwarteten Fällen auf. Manchmal kann Lilypond auch eine fehlerhafte
500 Stelle zwar noch problemlos verarbeiten, ein paar Zeilen später wirkt
501 sich der Fehler aber dann doch noch aus. In solchen Fällen, wo Sie in
502 der angegebenen Zeile keinen Fehler erkennen, sollten Sie auch die Zeilen
503 oberhalb der angegebenen Stelle genauer unter die Lupe nehmen.
506 @node Updating files with convert-ly
507 @section Updating with @command{convert-ly}
512 @subsection Command line options
514 * Problems with convert-ly::
517 @node Problems with convert-ly
518 @subsection Problems with @code{convert-ly}
524 @section Reporting bugs
528 @cindex Fehler melden
530 Wenn Sie eine Datei haben, die zu einem Absturz von LilyPond oder zu einer
531 fehlerhaften Ausgabe führt, so ist dies ein @q{Bug}. Die List der aktuell
532 bekannten derartigen Fehler findet sich in unserem @q{Google Bug Tracker}:
534 @uref{http://code.google.com/p/lilypond/issues/list}
536 Wenn Sie einen Fehler gefunden haben, der noch nicht aufgelistet ist, melden
537 Sie dies bitte anhand der Anweisungen auf der Seite
539 @uref{http://lilypond.org/web/devel/participating/bugs}
541 Wenn Sie Beispieldateien für den Fehler erstellen, versuchen Sie bitte, die
542 Datei möglichst minimal zu halten und nur jenen LilyPond Code aufzunehmen,
543 der auch wirklich für den Fehler verantwortlich ist. Meldungen mit
544 Beispieldateien, die nicht minimal sind, können wir meist aus Zeitgründen
545 nicht effektiv bearbeiten.