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