1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
4 Translation of GIT committish: 7b70644b95f383b4281e9ffa146d315d2ada11d3
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Translators: Reinhold Kainhofer, Till Paala
15 @node lilypond starten
16 @chapter @command{lilypond} starten
17 @translationof Running lilypond
19 Dieses Kapitel behandelt die technischen Details, wie Lilypond ausgeführt werden kann.
23 * Übliche Programmbenutzung::
24 * Benutzung auf der Kommandozeile::
28 @node Übliche Programmbenutzung
29 @section Übliche Programmbenutzung
30 @translationof Normal usage
32 Die meisten Benutzer führen LilyPond von einer graphischen Benutzeroberfläche
35 @c @rlearning{Erste Schritte},
36 falls Sie dies nicht bereits getan haben.
39 @node Benutzung auf der Kommandozeile
40 @section Benutzung auf der Kommandozeile
41 @translationof Command-line usage
43 Dieser Abschnitt enthält zusätzliche Informationen, wie Sie LilyPond
44 von der Kommandozeile ausführen können. Dies kann erforderlich sein,
45 um etwa zusätzliche Optionen an das Programm zu übergeben. Außerdem
46 sind einige Zusatzprogramme (wie etwa @code{midi2ly}) nur von der
47 Kommandozeile verfügbar.
49 Unter @q{Kommandozeile} verstehen wir die Kommandozeile des jeweiligen
50 Betriebssystems. Windows Benutzern ist sie vielleicht eher unter den
51 englischen Begriffen @q{DOS shell} oder @q{command shell} bekannt.
52 MacOS@tie{}X Benutzer kennen sie eher unter @q{Terminal} oder @q{Konsole}.
53 Sie sollten auch den Abschnitt
55 @c @ref{Einrichtung für MacOS X}
58 Wie die Kommandozeile im jeweiligen Betriebssystem benutzt werden kann,
59 soll in diesem Handbuch nicht näher beschrieben werden. Sehen Sie bitte
60 im Handbuch Ihres Betriebssystems nach oder informieren Sie sich im
61 Internet, wenn Sie mit der Kommandozeile nicht vertraut sind.
66 * Optionen von lilypond auf der Kommandozeile::
67 * Umgebungsvariablen::
70 @node lilypond aufrufen
71 @subsection @command{lilypond} aufrufen
72 @translationof Invoking lilypond
74 @cindex @command{lilypond} aufrufen
75 @cindex Kommandozeilen-Optionen für @command{lilypond}
76 @cindex Optionen an der Kommandozeile
78 Das @command{lilypond} Programm kann folgendermaßen von der Kommandozeile
82 lilypond [@var{Option}]@dots{} @var{Dateiname}@dots{}
86 Wird ein @file{Dateiname} ohne Erweiterung angegeben, so wird @file{.ly} als
87 Standarderweiterung für LilyPond-Dateien benutzt. Um Daten von
88 @code{stdin} einzulesen, benutzen Sie einfach einen Bindestrich (@code{-})
91 Wenn Lilypond die Datei @file{Dateiname.ly} verarbeitet, werden daraus
92 die Dateien @file{Dateiname.ps} und @file{Dateiname.pdf} erzeugt.
93 Es können an @code{lilypond} auch mehrere @file{.ly} Dateien übergeben
94 werden, die dann einzeln und voneinander unabhängig abgearbeitet
95 werden.@footnote{Der Zustand von GUILE wird allerdings nicht nach
96 jeder Datei zurückgesetzt, sodass Achtung geboten ist, wenn in einer
97 Datei globale Änderungen von Scheme aus durchgeführt werden.}
99 Falls @file{Dateiname.ly} mehr als einen @code{\score}-Block enthält,
100 werden die weiteren Stücke in durchnummerierte Dateien der Form
101 @file{Dateiname-1.pdf} ausgegeben. Zusätzlich wird der Wert der
102 Variable @code{output-suffix} zwischen den ursprünglichen Dateienamen
103 und der Zahl eingefügt. Eine Lilypond-Datei @var{Dateiname.ly} mit dem Inhalt
106 #(define output-suffix "Geige")
108 #(define output-suffix "Cello")
113 erzeugt daher die Dateien @var{Dateiname}@file{-Geige.pdf} und
114 @var{Dateiname}@file{-Cello-1.pdf}.
118 @node Optionen von lilypond auf der Kommandozeile
119 @subsection Optionen auf der Kommandozeile für @command{lilypond}
120 @translationof Command line options for lilypond
122 Die folgenden Kommandozeilenoptionen werden von @command{lilypond} unterstützt:
126 @item -e,--evaluate=@var{expr}
127 Wertet den Scheme-Ausdruck @var{expr} aus, bevor die @file{.ly} Dateien
128 gelesen und interpretiert werden.
129 Die @code{-e} Option kann auch mehrfach angegeben werden, die Ausdrücke
130 werden nacheinander ausgewertet.
132 Da der Ausdruck im @code{guile-user} Modul ausgewertet wird, ist bei der
133 Definitionen innerhalb von @var{expr} folgendes Vorgehen nötig. An der
134 Kommandozeile wird z.B. @code{a} im @code{guile-user} Modul definiert:
137 lilypond -e '(define-public a 42)'
141 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:
144 #(use-modules (guile-user))
148 @item -f,--format=@var{Format}
149 Bestimmt das Ausgabeformat. Mögliche Werte von @var{Format} sind
150 @code{svg}, @code{ps}, @code{pdf} und @code{png}.
152 Beispiel: @code{lilypond -fpng @var{Dateiname}.ly}
156 @item -d,--define-default=@var{Variable}=@var{Wert}
157 Damit wird die interne Programmoption @var{Variable} auf den Scheme-Wert
158 @var{Wert} gesetzt. Wird kein @var{Wert} angegeben, so wird @var{#t} benutzt.
159 Um eine Option auszuschalten, kann der Präfix @code{no-} dem Namen
160 @var{Variable} der Variable vorangestellt werden. So ist etwa
162 @cindex Point and Click, Kommandozeile
171 -dpoint-and-click='#f'
174 Hier sind ein paar interessante Optionen:
176 @cindex Hilfe, Kommandozeile
180 Die Ausführung von @code{lilypond -dhelp} zeigt alle verfügbaren @code{-d}
183 @cindex Papierformat, Kommandozeile
186 Setzt das Standard-Papierformat,
188 -dpaper-size=\"letter\"
192 Die Zeichenkette, die das Format angibt, muss in Anführungszeichen mit Backslash
193 ( @code{\"} ) stehen.
195 @cindex sicher, Kommandozeile
196 @cindex safe, Kommandozeile
199 Vertraut der @code{.ly} Datei nicht.
201 Wenn LilyPond über einen Webserver verfügbar gemacht wird, @b{MUSS} unbedingt
202 eine die Optionen @code{--safe} oder @code{--jail} angegeben werden.
203 Die @code{--safe} Option verhindert, dass in der .ly-Datei angegebener
204 Scheme-Code das System gefährden kann, wie etwa in folgendem Beispiel:
210 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
215 Mit der @code{-dsafe} Option werden alle Scheme-Ausdrücke einem speziellen
216 sicheren Modus ausgewertet. Dieser Modus ist vom GUILE @file{safe-r5rs} Modul
217 abgeleitet und fügt noch zahlreiche weitere erlaubte Funktionen der
218 LilyPond Programm-Schnittstelle hinzu. Diese Funktionen sind in
219 @file{scm/@/safe@/-lily@/.scm} angegeben.
221 Zusätzliche verbietet der sichere Modus auch @code{\include} Befehle.
223 Im sicheren Modus ist es nicht möglich, LilyPond-Variablen nach Scheme
226 @code{-dsafe} erkennt jedoch @emph{KEINE} Überbeanspruchung der verfügbaren
227 Ressourcen. In diesem Modus ist es also trotzdem möglich, dass LilyPond in einer
228 Endlosschleife hängt, z.B. wenn zyklische Datenstrukturen an das Backend
229 übergeben werden. Wenn LilyPond also auf einem öffentlich zugänglichen
230 Webserver verfügbar gemacht wird, sollte der Prozess sowohl in der CPU-
231 als auch in der Speichernutzung limitiert werden.
233 Der sichere Modus verhindert auch, dass zahlreiche nützliche
234 Musikfragmente von LilyPond verarbeitet werden. Die @code{--jail} Option ist
235 eine sicherere Alternative, benötigt allerdings auch mehr Aufwand zur
239 Gibt an, welches Ausgabeformat das LilyPond Backend benutzt. Mögliche Werte
240 für diese Option sind:
244 PostScript-Ausgabeformat.
246 @cindex PostScript Ausgabeformat
248 Postscript-Dateien enthalten auch TTF-, Type1- und OTF-Schriften. Allerdings
249 wird die gesamte Schriftart eingefügt und nicht nur die benötigten Zeichen.
250 Vor allem wenn nicht-westliche Zeichensätze benutzt werden, kann dies zu sehr
251 großen Dateien führen.
253 @cindex PostScript Ausgabeformat
254 @cindex EPS (encapsulated PostScript)
257 Erzeugt @q{encapsulated PostScript} (EPS). Jede Seite (oder jedes System) wird
258 als eigene @file{EPS}-Datei ausgegeben, inklusive Schriftarten. Außerdem wird
259 eine Datei mit allen Seiten (bzw. Systemen) und Schriftarten erzeugt.
261 Dies ist die Standardeinstellung von @command{lilypond-book}.
263 @cindex SVG (scalable vector graphics)
264 @cindex Vektorgraphik (SVG)
268 SVG-Ausgabe (Scalable Vector Graphics).
270 Hiermit wird eine einzelne SVG-Datei ohne eingebundene Schriften
271 für jede Seite der Partitur erstellt. Es wird empfohlen, Century
272 Schoolbook-Schriftarten zu installieren, die auch in der LilyPond-Installation
273 enthalten sind, um optimales Rendern zu erhalten. Unter UNIX können
274 diese Schriftarten einfach aus dem LilyPond-Verzeichnis (normalerweise
275 @file{/usr/share/lilypond/VERSION/fonts/otf/}) nach @file{~/.fonts}
276 kopiert werden. Die SVG-Ausgabe sollte mit allen SVG-Editoren oder
277 Betrachtungsprogrammen kompatibel sein.
282 gibt die rohen Scheme-basierenden Zeichenbefehle aus, wie sie intern von
283 LilyPond benutzt werden.
288 Keine Partitur wird ausgegeben, hat gleichen Effekt wie @code{-dno-print-pages}.
292 Beispiel: @code{lilypond -dbackend=svg @var{Dateiname}.ly}
294 @cindex Ausgabeformat
298 Erzeugt eine Ausgabedatei, die nur die Titelzeilen und das erste System
302 Erzeugt vollständige Seiten (Standardeinstellung). @code{-dno-print-pages}
303 ist in Verbindung mit @code{-dpreview} nützlich.
310 Zeigt eine Zusammenfassung der Programmbenutzung und der Optionen.
312 @item -H,--header=@var{FELD}
313 Gibt den Inhalt eines Feldes aus dem @code{\header}-Block in die Datei
314 @file{Dateiname.@var{FELD}} aus.
316 @item --include, -I=@var{Verzeichnis}
317 Fügt @var{Verzeichnis} zur Liste der Suchpfade hinzu.
321 @item -i,--init=@var{Initialisierungsdatei}
322 Benutzt @var{Initialisierungsdatei} zur gesamten Programminitialisierung. Der
323 Standardwert ist @file{init.ly}.
325 @item -o,--output=@var{DATEI}
326 Schreibt das Ergebnis der Verarbeitung mit LilyPond in die Ausgabedatei
327 @var{DATEI}. Die entsprechende Dateinamenserweiterung wird angehängt (z.B.
328 @code{.pdf} für pdf).
330 @cindex PostScript-Ausgabe
336 @cindex Portable Network Graphics (PNG)
339 Erzeugt eine Grafik-Datei im PNG-Format von jeder Seite. Diese Option
340 impliziert auch @code{--ps}. Die Auflösung in DPI der Grafik kann festgelegt
347 @cindex Portable Document (PDF)
350 Erzeugt PDF-Dateien. Dies impliziert @code{--ps}.
352 @item -j,--jail=@var{Benutzer},@var{Gruppe},@var{Jail-Verzeichnis},@var{Arbeitsverzeichnis}
353 Führt @command{lilypond} in einem chroot-Jail aus.
355 Die @code{--jail} Option ist eine flexiblere Alternative zu @code{--safe}, wenn
356 LilyPond über das Internet verfügbar gemacht wird oder LilyPond-Quelldateien
357 von Dritten automatisch vararbeitet werden.
359 Sie funktioniert dergestalt, dass das Wurzelverzeichnis von
360 @command{lilypond} auf @var{Jail-Verzeichnis} gesetzt wird, bevor die
361 tatsächliche Kompilierung der .ly-Datei beginnt. Der Benutzer und die Gruppe
362 werden auf die angegebenen Werte gesetzt und das aktuelle Arbeitsverzeichnis
363 wird ebenfalls auf den angegebenen Wert @var{Arbeitsverzeichnis} gesetzt.
364 Diese Einstellungen garantieren (zumindest in der Theorie), dass es nicht
365 möglich ist, aus dem Jail auszubrechen. Damit @code{--jail} funktioniert, muss
366 @command{lilypond} allerdings als root ausgeführt werden, was normalerweise
367 auf sichere Art mit dem Kommando @command{sudo} erreicht werden kann.
369 Das Jail-Verzeichnis zu erstellen ist etwas heikel, da LilyPond alle zur
370 Ausführung nötigen Bibliotheken und Dateien @emph{innerhalb des
371 Jail-Verzeichnisses} finden muss. Ein typisches Setup besteht aus folgenden
375 @item Erstellung eines getrennten Dateisystems
376 Ein eigenes Dateisystem muss für LilyPond erstellt werden, sodass es mit
377 sicheren Einstellungen wie @code{noexec}, @code{nodev} und @code{nosuid}
378 eingebunden werden kann. Damit ist es unmöglich, Programme von diesem
379 Dateisystem auszuführen oder direkt auf eine Hardware-Schnittstelle
380 zuzugreifen. Wenn Sie keine eigene Partition erstellen möchten, können Sie
381 auch eine Datei der entsprechenden Größe erstellen und sie als @q{loop}-Gerät
382 einbinden. Ein getrenntes Dateisystem garantiert auch, dass LilyPond nicht
383 mehr Festplattenspeicher benutzt als erlaubt.
385 @item Erstellung eines eigenen Benutzerkontos
386 Es sollte ein eigener Benutzer und eine eigene Gruppe (z. B.
387 @code{lily}/@code{lily}) mit geringen Rechten für die Ausführung von LilyPond
388 innerhalb des Jails benutzt werden. Nur ein einziges Verzeichnis des Jails sollte
389 für den Benutzer schreibbar sein und als @var{Arbeitsverzeichnis} an
390 @code{lilypond} übergeben werden.
392 @item Einrichtung des Jails
393 LilyPond muss zahlreiche Dateien für die Ausführung einlesen. All diese
394 Dateien müssen in das Jail-Verzeichnis kopiert werden (mit denselben Pfaden
395 wie im tatsächlichen Wurzel-Dateisystem). Die gesamte LilyPond-Installation
396 (typischerweise @file{/usr/share/lilypond}) sollte kopiert werden.
398 Falls Probleme auftreten, ist es am einfachsten, Lilypond mittels
399 @command{strace} zu starten, wodurch Sie relativ leicht feststellen können,
400 welche Dateien im Jail noch fehlen.
402 @item Ausführung von LilyPond
403 In einem mit @code{noexec} eingebundenen Jail ist es nicht möglich, externe
404 Programme auszuführen. Daher muss LilyPond auf eine Art gestartet werden,
405 die keine weitere Ausführung von Programmen benötigt. Wie bereits erwähnt
406 muss LilyPond mit Administrator-Rechten gestartet werden (die es allerdings
407 sofort wieder abgibt), beispielsweise mittels @command{sudo}. Außerdem
408 ist es eine gute Idee, die LilyPond zur Verfügung stehende CPU-Zeit zu
409 limitieren (z. B. mit @command{ulimit -t}) und -- falls das Betriebssystem
410 dies unterstützt -- auch den zur Verfügung stehenden Hauptspeicher.
415 Gibt die Versionsnummer aus.
418 Gibt ausführliche informative Meldungen aus: Zeigt die vollen Dateipfade
419 aller gelesenen Dateien sowie Informationen über die Laufzeit.
422 Zeigt die Garantiebedingungen an, unter denen GNU LilyPond steht. (Es besteht
423 @strong{KEINERLEI GARANTIE}!)
427 @node Umgebungsvariablen
428 @subsection Umgebungsvariablen
429 @translationof Environment variables
432 @cindex LILYPOND_DATADIR
434 @command{lilypond} erkennt und benützt die folgenden Umgebungsvariablen:
436 @item LILYPOND_DATADIR
437 Diese Variable gibt das Verzeichnis an, wo Lilypond seine eigenen Dateien,
438 Meldungen und Übersetzungen finden kann. Dieses Verzeichnis sollte
439 Unterverzeichnisse @file{ly/}, @file{ps/}, @file{tex/}, etc. beinhalten.
442 Gibt die Sprache an, in der Warnungen und Fehlermeldungen ausgegeben werden.
444 @item LILYPOND_GC_YIELD
445 Mit dieser Variable (mit Werten zwischen 0 und 100) kann die Feinabstimmung
446 zwischen dem Bedarf an Hauptspeicher und Rechenleistung bei der Ausführung
447 von LilyPond durchgeführt werden. Bei höheren Werten benutzt LilyPond
448 mehr Hauptspeicher, benötigt aber weniger Prozessor-Leistung. Bei
449 niedrigeren Werten wird mehr Prozessor-Zeit, dafür weniger Hauptspeicher
450 benötigt. Voreinstellung ist ein Wert von @code{70}.
455 @node Fehlermeldungen
456 @section Fehlermeldungen
457 @translationof Error messages
459 @cindex error messages
460 Während der Verarbeitung einer Dateien können diverse Meldungen an der
461 Kommandozeile auftreten:
467 Irgendetwas ist verdächtig. Wenn Sie etwas Ungewöhnliches in Ihrer
468 Datei durchführen, dann werden Sie die Meldung verstehen und können
469 sie gegebenenfalls ignorieren. Im Normalfall jedoch bedeutet eine
470 Warnung, dass mit Ihrer Datei etwas nicht stimmt, LilyPond jedoch
471 trotzdem versucht, die Datei soweit wie möglich korrekt zu übersetzen.
475 Irgendetwas stimmt definitiv nicht. Der aktuelle Bearbeitungsschritt
476 (Einlesen, Interpretieren oder Formatieren der Datei) wird noch fertig
477 ausgeführt, danach bricht die Bearbeitung aber ab.
480 @cindex Fataler Fehler
481 Irgendetwas stimmt definitiv nicht und LilyPond kann nicht weiter
482 ausgeführt werden. Dies ist nur sehr selten der Fall, meist sind
483 die Schriftarten nicht korrekt installiert.
486 @cindex Fehlerprotokoll, Scheme
487 @cindex Scheme Fehler
488 Fehler, die während der Ausführung von Scheme-Code auftreten, werden
489 vom Scheme-Interpreter aufgefangen und an der Kommandozeile ausgegeben.
490 Wenn Sie LilyPond mit der @code{--verbose} Option (auch @code{-V})
491 ausführen, wird der sogennante @q{Call trace} ausgegeben, der die
492 aufgerufenen Funktionen zur Zeit des Fehlers angibt.
494 @item Programmierfehler
495 @cindex Programmierfehler
496 Eine interne Inkonsistenz ist aufgetreten. Diese Fehlermeldungen
497 sollen den Programmierern die Fehlersuche erleichtern und
498 können meistens einfach ignoriert werden. In manchen Fällen werden
499 so viele Meldungen ausgegeben, dass die Lesbarkeit der restliche
500 Ausgabe davon beeinträchtigt wird.
502 @item Abgebrochen (core dumped)
503 Dies bezeichnet einen ernsten Programmierfehler, der das Programm
504 zum Absturz gebracht hat. Solche Fehler werden als kritisch angesehen.
505 Falls daher einer auftritt, senden Sie bitte einen Bug-Report!
508 @cindex Fehlermeldung, Format
509 @cindex Form der Fehlermeldungen
510 Wenn Warnungen oder Fehlermeldungen mit einer konkreten Stelle in der
511 Eingabedatei verknüpft werden können, dann hat die Meldung die folgende
515 @var{Dateiname}:@var{Zeile}:@var{Spalte}: @var{Meldung}
516 @var{Fehlerhafte Eingabezeile}
519 Ein Zeilenumbruch wird in der fehlerhaften Zeile an jener Stelle eingefügt,
520 wo der Fehler aufgetreten ist. Zum Beispiel
523 test.ly:2:19: Fehler: keine gültige Dauer: 5
528 Diese Stellen sind LilyPonds Vermutung, wo die Warnung oder der Fehler
529 aufgetreten ist, allerdings treten Warnungen und Fehler ja gerade in
530 unerwarteten Fällen auf. Manchmal kann Lilypond auch eine fehlerhafte
531 Stelle zwar noch problemlos verarbeiten, ein paar Zeilen später wirkt
532 sich der Fehler aber dann doch noch aus. In solchen Fällen, wo Sie in
533 der angegebenen Zeile keinen Fehler erkennen, sollten Sie auch die Zeilen
534 oberhalb der angegebenen Stelle genauer unter die Lupe nehmen.