Merge remote branch 'origin/master' into release/unstable

[lilypond.git] / Documentation / de / usage / running.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-

@ignore
    Translation of GIT committish: e5a609e373eae846857f9a6d70a402a3d42b7d94

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.17.6"

@c Translators: Reinhold Kainhofer, Till Paala
@c Translation checkers: Till Paala

@node lilypond starten
@chapter @command{lilypond} starten
@translationof Running lilypond

Dieses Kapitel behandelt die technischen Details, wie Lilypond ausgeführt werden kann.


@menu
* Übliche Programmbenutzung::
* Benutzung auf der Kommandozeile::
* Fehlermeldungen::
* Häufige Fehlermeldungen::
@end menu

@node Übliche Programmbenutzung
@section Übliche Programmbenutzung
@translationof Normal usage

Die meisten Benutzer führen LilyPond von einer graphischen Benutzeroberfläche
aus. Siehe @rlearning{Übung}, falls Sie dies nicht bereits getan haben.  Wenn
Sie einen alternativen Editor für Ihre LilyPond-Dateien verwenden, lesen Sie
bitte die Dokumentation dieses Editors.


@node Benutzung auf der Kommandozeile
@section Benutzung auf der Kommandozeile
@translationof Command-line usage

Dieser Abschnitt enthält zusätzliche Informationen, wie Sie LilyPond
von der Kommandozeile ausführen können.  Dies kann erforderlich sein,
um etwa zusätzliche Optionen an das Programm zu übergeben.  Außerdem
sind einige Zusatzprogramme (wie etwa @code{midi2ly}) nur von der
Kommandozeile verfügbar.

Unter @q{Kommandozeile} verstehen wir die Kommandozeile des jeweiligen
Betriebssystems. Windows Benutzern ist sie vielleicht eher unter den
englischen Begriffen @q{DOS shell} oder @q{command shell} bekannt.
MacOS@tie{}X Benutzer kennen sie eher unter @q{Terminal} oder @q{Konsole}.
Einige zusätzliche Einrichtungsarbeiten werden unter MacOS@tie{}X,
siehe @rweb{MacOS X}.

Wie die Kommandozeile im jeweiligen Betriebssystem benutzt werden kann,
soll in diesem Handbuch nicht näher beschrieben werden. Sehen Sie bitte
im Handbuch Ihres Betriebssystems nach oder informieren Sie sich im
Internet, wenn Sie mit der Kommandozeile nicht vertraut sind.


@menu
* lilypond aufrufen::
* Grundlegende Optionen auf der Kommandozeile für LilyPond::
* Fortgeschrittene Optionen auf der Kommandozeile für LilyPond::
* Umgebungsvariablen::
* LilyPond in chroot-Kerker::
@end menu

@node lilypond aufrufen
@unnumberedsubsec @command{lilypond} aufrufen
@translationof Invoking lilypond

@cindex @command{lilypond} aufrufen
@cindex Kommandozeilen-Optionen für @command{lilypond}
@cindex Optionen an der Kommandozeile

Das @command{lilypond} Programm kann folgendermaßen von der Kommandozeile
aufgerufen werden.

@example
lilypond [@var{Option}]@dots{} @var{Dateiname}@dots{}
@end example


Wird ein @file{Dateiname} ohne Erweiterung angegeben, so wird @file{.ly} als
Standarderweiterung für LilyPond-Dateien benutzt.  Um Daten von
@code{stdin} einzulesen, benutzen Sie einfach einen Bindestrich (@code{-})
als @var{Dateiname}.

Wenn Lilypond die Datei @file{Dateiname.ly} verarbeitet, werden daraus
die Dateien @file{Dateiname.ps} und @file{Dateiname.pdf} erzeugt.
Es können an @code{lilypond} auch mehrere @file{.ly} Dateien übergeben
werden, die dann einzeln und voneinander unabhängig abgearbeitet
werden.@footnote{Der Zustand von GUILE wird allerdings nicht nach
jeder Datei zurückgesetzt, sodass Achtung geboten ist, wenn in einer
Datei globale Änderungen von Scheme aus durchgeführt werden.}

Falls @file{Dateiname.ly} mehr als eine @code{\book}-Umgebung enthält,
werden die weiteren Stücke in durchnummerierte Dateien der Form
@file{Dateiname-1.pdf} ausgegeben.  Zusätzlich wird der Wert der
Variable @code{output-suffix} zwischen den ursprünglichen Dateinamen
und der Zahl eingefügt.  Eine Lilypond-Datei @file{Dateiname.ly} mit dem Inhalt

@example
#(define output-suffix "Geige")
\score @{ @dots{} @}
#(define output-suffix "Cello")
\score @{ @dots{} @}
@end example

@noindent
erzeugt daher die Dateien @var{Dateiname}@file{-Geige.pdf} und
@var{Dateiname}@file{-Cello-1.pdf}.



@unnumberedsubsubsec Häufige Kommandozeilenbefehle

Wenn Ihre Kommandozeile normale Weiterleitungen unterstützt, können
Sie es nützlich finden, mit folgenden Befehlen die Ausgabe der
Kommandozeile in eine Datei zu leiten:

@itemize

@item
@code{lilypond file.ly 1>stdout.log} um normale Ausgabe zu erhalten
@item
@code{lilypond file.ly 2>stderr.log} um Fehlermeldungen zu erhalten

@item
@code{lilypond file.ly &>all.log} um alle Meldungen zu erhalten

@end itemize

Wenden Sie sich an die Dokumentation für Ihre Kommandozeile, um
zu sehen, ob derartige Optionen unterstützt werden oder die Syntax
unterschiedlich ist.  Beachten Sie, dass es sich hier um
reine Verwaltungsprogramme handelt, die nichts mit LilyPond zu tun
haben.


@node Grundlegende Optionen auf der Kommandozeile für LilyPond
@unnumberedsubsec Grundlegende Optionen auf der Kommandozeile für LilyPond
@translationof Basic command line options for LilyPond

Die folgenden Kommandozeilenoptionen werden von @command{lilypond} unterstützt:

@cindex @command{lilypond} auf der Kommandozeile
@cindex Kommandozeile, @command{lilypond} aufrufen
@cindex Optionen, Kommandozeile
@cindex Terminal, @command{lilypond} aufrufen

@table @code

@item -d, --define-default=@var{Variable}=@var{Wert}
Siehe @ref{Fortgeschrittene Optionen auf der Kommandozeile für LilyPond}.

@cindex Scheme, Auswertung von Ausdrücken
@cindex Auswertung von Ausdrücken, Scheme

@item -e, --evaluate=@var{expr}
Wertet den Scheme-Ausdruck @var{expr} aus, bevor die @file{.ly} Dateien
gelesen und interpretiert werden.
Die @code{-e} Option kann auch mehrfach angegeben werden, die Ausdrücke
werden nacheinander ausgewertet.

Da der Ausdruck im @code{guile-user} Modul ausgewertet wird, ist bei der
Definitionen innerhalb von @var{expr} folgendes Vorgehen nötig. An der
Kommandozeile wird z.B. @code{a} im @code{guile-user} Modul definiert:

@example
lilypond -e '(define-public a 42)'
@end example

@noindent
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:

@example
#(use-modules (guile-user))
@end example

@warning{Windows-Benutzer müssen doppelte anstelle der einfachen
Anführungsstriche einsetzen.}

@cindex Ausgabeformat

@item -f, --format=@var{Format}
Bestimmt das Ausgabeformat. Mögliche Werte von @var{Format} sind
@code{svg}, @code{ps}, @code{pdf} und @code{png}.

Beispiel: @code{lilypond -fpng @var{Dateiname}.ly}

@item -h, --help
Zeigt eine Zusammenfassung der Programmbenutzung und der Optionen.

@item -H, --header=@var{FELD}
Gibt den Inhalt eines Feldes aus dem @code{\header}-Block in die Datei
@file{Dateiname.@var{FELD}} aus.

@item -i, --init=@var{Initialisierungsdatei}
Benutzt @var{Initialisierungsdatei} zur gesamten Programminitialisierung. Der
Standardwert ist @file{init.ly}.

@item -I, --include=@var{Verzeichnis}
Fügt @var{Verzeichnis} zur Liste der Suchpfade hinzu.

@cindex Dateisuche
@cindex Suchpfad

Mehrere -I-Optionen können angegeben werden.  Die Suche beginnt mit dem
ersten definierten Verzeichnis und setzt in den weiteren Verzeichnissen
fort, wenn die gesuchte Datei nicht in dem Verzeichnis gefunden wird.

@cindex Kerker, Programm ausführen
@cindex Jail, Programm ausführen

@item -j, --jail=@var{Benutzer},@var{Gruppe},@var{Jail-Verzeichnis},@var{Arbeitsverzeichnis}
Führt @command{lilypond} in einem chroot-Jail aus.

Die @option{--jail} Option ist eine flexiblere Alternative zu @option{-dsafe}, wenn
LilyPond über das Internet verfügbar gemacht wird oder LilyPond Befehle ausführt,
die aus externe Quellen stammen (siehe @ref{Fortgeschrittene Optionen auf der Kommandozeile für LilyPond}).

Sie funktioniert dergestalt, dass das Wurzelverzeichnis von
@command{lilypond} auf @var{Jail-Verzeichnis} gesetzt wird, bevor die
tatsächliche Kompilierung der @file{.ly}-Datei beginnt. Der Benutzer und die Gruppe
werden auf die angegebenen Werte gesetzt und das aktuelle Arbeitsverzeichnis
wird ebenfalls auf den angegebenen Wert @var{Arbeitsverzeichnis} gesetzt.
Diese Einstellungen garantieren (zumindest in der Theorie), dass es nicht
möglich ist, aus dem Jail auszubrechen. Damit @option{--jail} funktioniert, muss
@command{lilypond} allerdings als root ausgeführt werden, was normalerweise
auf sichere Art mit dem Kommando @command{sudo} erreicht werden kann.

Das Jail-Verzeichnis zu erstellen ist etwas heikel, da LilyPond alle zur
Ausführung nötigen Bibliotheken und Dateien @emph{innerhalb des
Jail-Verzeichnisses} finden muss. Ein typisches Setup besteht aus folgenden
Punkten:

@table @asis

@item Erstellung eines getrennten Dateisystems
Ein eigenes Dateisystem muss für LilyPond erstellt werden, sodass es mit
sicheren Einstellungen wie @code{noexec}, @code{nodev} und @code{nosuid}
eingebunden werden kann. Damit ist es unmöglich, Programme von diesem
Dateisystem auszuführen oder direkt auf eine Hardware-Schnittstelle
zuzugreifen. Wenn Sie keine eigene Partition erstellen möchten, können Sie
auch eine Datei der entsprechenden Größe erstellen und sie als @q{loop}-Gerät
einbinden. Ein getrenntes Dateisystem garantiert auch, dass LilyPond nicht
mehr Festplattenspeicher benutzt als erlaubt.

@item Erstellung eines eigenen Benutzerkontos
Es sollte ein eigener Benutzer und eine eigene Gruppe (z. B.
@code{lily}/@code{lily}) mit geringen Rechten für die Ausführung von LilyPond
innerhalb des Jails benutzt werden. Nur ein einziges Verzeichnis des Jails sollte
für den Benutzer schreibbar sein und als @var{Arbeitsverzeichnis} an
@code{lilypond} übergeben werden.

@item Einrichtung des Jails
LilyPond muss zahlreiche Dateien für die Ausführung einlesen. All diese
Dateien müssen in das Jail-Verzeichnis kopiert werden (mit denselben Pfaden
wie im tatsächlichen Wurzel-Dateisystem). Die gesamte LilyPond-Installation
(typischerweise @file{/usr/share/lilypond}) sollte kopiert werden.

Falls Probleme auftreten, ist es am einfachsten, Lilypond mittels
@command{strace} zu starten, wodurch Sie relativ leicht feststellen können,
welche Dateien im Jail noch fehlen.

@item Ausführung von LilyPond
In einem mit @code{noexec} eingebundenen Jail ist es nicht möglich, externe
Programme auszuführen. Daher muss LilyPond auf eine Art gestartet werden,
die keine weitere Ausführung von Programmen benötigt. Wie bereits erwähnt
muss LilyPond mit Administrator-Rechten gestartet werden (die es allerdings
sofort wieder abgibt), beispielsweise mittels @command{sudo}. Außerdem
ist es eine gute Idee, die LilyPond zur Verfügung stehende CPU-Zeit zu
limitieren (z. B. mit @command{ulimit -t}) und -- falls das Betriebssystem
dies unterstützt -- auch den zur Verfügung stehenden Hauptspeicher.  Siehe
auch @ref{LilyPond in chroot-Kerker}

@end table

@cindex Logstufe
@cindex Ausgabe, Ausführlichkeit

@item -l, --loglevel=@var{Logstufe}
Passt die Ausführlichkeit der Ausgabe auf der Kommandozeile entsprechend
@var{Logstufe} an.  Mögliche Werte sind:

@table @code

@item NONE
Keine Ausgabe, nicht einmal Fehlermeldungen.

@item ERROR
Nur Fehlermeldungen, keine Warnungen oder Fortschrittsmeldungen.

@item WARN
Warnungen und Fehlermeldungen, keine Fortschrittsmeldungen.

@item BASIC_PROGRESS
Grundlegende Fortschrittsmeldungen (Erfolg), Warnungen und Fehler.

@item PROGRESS
Alle Fortschrittsmeldungen, Warnungen und Fehler.

@item INFO (Standard)
Fortschrittmeldungen, Warnungen, Fehlermeldungen und weiter
Information über die Ausführung.

@item DEBUG
Alle möglichen Meldungen, die auch mit der Fehlersuche (Debug) zu tun
haben können.

@end table


@cindex Verzeichnis, Ausgabe speichern in
@cindex Ausgabedateiname
@cindex Dateiname der Ausgabe bestimmen

@item -o, --output=@var{DATEI} oder @var{ORDNER}
Schreibt das Ergebnis der Verarbeitung mit LilyPond in die Ausgabedatei
@var{DATEI}.  Wenn ein Verzeichnis mit dem Namen existiert, werden die Ausgabedateien
in dieses Verzeichnis gespeichert, wobei der Dateiname der Eingabedatei
benutzt wird.  Die entsprechende Dateinamenserweiterung wird angehängt (z.B.
@code{.pdf} für pdf).

@cindex PostScript-Ausgabe

@item --ps
Erzeugt PostScript.

@cindex PNG-Ausgabe
@cindex Portable Network Graphics (PNG)

@item --png
Erzeugt eine Grafik-Datei im PNG-Format von jeder Seite. Diese Option
impliziert auch @code{--ps}. Die Auflösung in DPI der Grafik kann festgelegt
werden durch
@example
-dresolution=110
@end example

@cindex PDF-Ausgabe
@cindex Portable Document Format (PDF)

@item --pdf
Erzeugt PDF-Dateien. Dies impliziert @code{--ps}.

@item -v, --version
Gibt die Versionsnummer aus.

@item -V, --verbose
Gibt ausführliche informative Meldungen aus: Zeigt die vollen Dateipfade
aller gelesenen Dateien sowie Informationen über die Laufzeit.

@item -w, --warranty
Zeigt die Garantiebedingungen an, unter denen GNU LilyPond steht. (Es besteht
@strong{KEINERLEI GARANTIE}!)

@end table



@node Fortgeschrittene Optionen auf der Kommandozeile für LilyPond
@unnumberedsubsec Fortgeschrittene Optionen auf der Kommandozeile für LilyPond
@translationof Advanced command line options for LilyPond

@table @code

@item -d@var{[Optionsbezeichnung]}=@var{[Wert]},--define-default=@var{[Optionsbezeichnung]}=@var{[Wert]}
Hiermit wird die entsprechende interne Scheme-Funktion auf den @var{Wert}
gesetzt.  Wenn kein @var{value} angegeben wird, wird der Standardwert
eingesetzt.  Die Vorsilbe @code{no-} kann zur @var{Optionsbezeichnung}
hinzugefügt werden, um eine Funktion @qq{auszuschalten}.  Beispielsweise

@cindex Point and Click, Kommandozeile

@example
-dpoint-and-click=#f
@end example

@noindent
ist das gleiche wie
@example
-dno-point-and-click
@end example
@end table

@noindent Folgende Optionen sind mit ihren entsprechenden Standardwerten
unterstützt:

@multitable @columnfractions .33 .16 .51
@item @strong{Symbol}
@tab @strong{Wert}
@tab @strong{Erklärung/Optionen}

@item @code{anti-alias-factor}
@tab @code{1}
@tab Die Bilder in einer höheren Auflösung rendern (Faktor angegeben) und
das Resultat herunterrechnen, um @qq{Zacken} in @code{PNG}-Bildern zu
vermeiden.

@item @code{aux-files}
@tab @code{#t}
@tab Erstelle @code{.tex}, @code{.texi}, @code{.count}-Dateien im
@code{EPS}-Backend.

@item @code{backend}
@tab @code{'ps}
@tab Auswahl des Backend.  Poststscript-Dateien (Standart) enthalten
@code{TTF}, @code{Type1} und @code{OTF}-Schriftarten.  Ihr Zeichenvorrat
wird nicht reduziert (Subsetting).  Die Benutzung von östlichen
Schriftarten kann zu sehr großen Dateien führen.

@item
@tab @code{'eps}
@tab Encapsulated PostScript.  Hiermit wird jede Seite (System) als eine
eigene @file{EPS}-Datei gespeichert, ohne Schriftarten, sowie als eine
kombinierte @file{EPS}-Datei mit allen Seiten (Systemen) inclusive
Schriftarten.  Wird als Standard von @command{lilypond-book} benützt.

@item
@tab @code{'null}
@tab Keine graphische Partitur ausgeben; hat den gleichen Effekt wie
@code{-dno-print-pages}.

@item
@tab @code{'svg}
@tab Scalable Vector Graphics.  Hiermit wird eine einzelne @code{SVG}-Datei
für jede Seite der Ausgabe erstellt, ohne Schriftarten.  Es wird
empfohlen, die Century Schoolbook-Schriftarten zu installieren, welche
mit der LilyPond-Installation mitkommen, um optimales Rendern zu erreichen.
Unter UNIX kann man einfach die Schriftartdateien aus dem LilyPond-Verzeichnis
(üblicherweise @file{/usr/share/lilypond/VERSION/fonts/otf/}) nach
@file{~/.fonts/}.  Die @code{SVG}-Ausgabe sollte mit allen SVG-Programmen
oder -Editoren kompatibel sein.  Es gibt auch die Option @code{svg-woff}
(siehe unten) um woff-Schriftarten im SVG-Backend zu benützen.

@item
@tab @code{'scm}
@tab Ausgabe der rohen internen Scheme-basierten Zeichnungsbefehle.

@item @code{check-internal-types}
@tab @code{#f}
@tab Überprüfe jede Eigenschaftszuweisung für Typen.

@item @code{clip-systems}
@tab @code{#f}
@tab Erstelle ausgeschnittene Schnipsel einer Partitur.

@item @code{datadir}
@tab
@tab Präfix für Datendateien (read-only).

@item @code{debug-gc}
@tab @code{#f}
@tab Gebe Debugging-Statistik für Speicher aus.

@item @code{debug-gc-assert-parsed-dead}
@tab @code{#f}
@tab Für Speicher-Debugging: Gehe sicher, dass alle Referenzen zu geparsten
Objekten tot sind.  Das ist eine interne Option und sie wird automatisch
für @code{`-ddebug-gc'} angestellt.

@item @code{debug-lexer}
@tab @code{#f}
@tab Debugging des Flex-lexer.

@item @code{debug-page-breaking-scoring}
@tab @code{#f}
@tab Gebe viele unterschiedliche Seitenumbruchsituationen für Partituren
aus.

@item @code{debug-parser}
@tab @code{#f}
@tab Debugging des Bison-Parsers.

@item @code{debug-property-callbacks}
@tab @code{#f}
@tab Debugging von zyklischen Callback-Ketten.

@item @code{debug-skylines}
@tab @code{#f}
@tab Debugging von Skylines.

@item @code{delete-intermediate-files}
@tab @code{#t}
@tab Entferne unbenutzbare, zwischenzeitliche @code{.ps}-Dateien, die während
der Kompilations erstellt werden.

@item @code{dump-cpu-profile}
@tab @code{#f}
@tab Gebe CPU-Zeitinformation aus (abhängig vom System).

@item @code{dump-profile}
@tab @code{#f}
@tab Gebe Speicher- und CPU-Zeitbenutzung für jede Datei aus.

@item @code{dump-signatures}
@tab @code{#f}
@tab Gebe Ausgabesignaturen für jedes System aus.  Wird für das Prüfen
der Regressionsteste eingesetzt.

@item @code{eps-box-padding}
@tab @code{#f}
@tab Verschiebe die linke Ecke der ausgegebenen EPS-Boundingbox um die
angegebene Entfernung (in mm).

@item @code{gs-load-fonts}
@tab @code{#f}
@tab Lade die Schriftarten durch Ghostscript.

@item @code{gs-load-lily-fonts}
@tab @code{#f}
@tab Lade nur die LilyPond-Schriftarten durch Ghostscript.

@item @code{gui}
@tab @code{#f}
@tab Gibt keine Ausgabe auf der Kommandozeile aus, sondern schreibt alles in
die Log-Datei.
@end multitable

@noindent
@strong{Anmerkung für Windows-Benutzer:} Standardmäßig gibt @code{lilypond.exe} alle Fortschrittsinformation auf der Kommandozeile aus;
@code{lilypond-windows.exe} gibt aber keine Fortschrittinformation aus und
zeigt sofort den Prompt an.  Die Option @option{-dgui} kann hier benutzt
werden, um die Ausgabe in eine Log-Datei umzuleiten.

@multitable @columnfractions .33 .16 .51
@item @code{help}
@tab @code{#f}
@tab Zeige die Hilfe.

@item @code{include-book-title-preview}
@tab @code{#t}
@tab Füge Titel eines Buches (book) in die Vorschaubilder ein.

@item @code{include-eps-fonts}
@tab @code{#t}
@tab Füge Schriftarten in EPS-Dateien von einzelnen Systemen ein.

@item @code{include-settings}
@tab @code{#f}
@tab Füge eine Datei für globale Einstellungen ein, dieses wird gelesen, bevor die Partitur verarbeitet wird.

@item @code{job-count}
@tab @code{#f}
@tab Bearbeite Dateien parallel, mit der angegebenen Anzahl von Prozessen.

@item @code{log-file}
@tab @code{#f [file]}
@tab Wenn die Zeichenkette @code{FOO} als ein zweites Argument angegeben wird,
wird die Ausgabe in die Log-Datei @code{FOO.log} umgeleitet.

@item @code{max-markup-depth}
@tab @code{1024}
@tab Maximale Tiefe eines Beschriftungs-(markup)-Baumes.  Wenn eine
Beschriftung mehr Ebenen hat, wird angenommen, dass die Beschriftung
nicht von sich aus schließt, eine Warnung ausgegeben und eine leere
Beschriftung gesetzt.

@item @code{midi-extension}
@tab @code{"midi"}
@tab Schreibe als Standarddateierweiterung für MIDI die angegebene Zeichenkette.

@item @code{music-strings-to-paths}
@tab @code{#f}
@tab Konvertiere Textzeichenketten in Pfade, wenn die Glyphen einer
Musik-Schriftart gehören.

@item @code{old-relative}
@tab @code{#f}
@tab Lässt den @code{\relative}-Modus für simultane Musik ähnlich wie die
Akkord-Syntax funktionieren.

@item @code{paper-size}
@tab @code{\"a4\"}
@tab Stelle die Standardpapiergröße ein.  Beachten Sie, dass die Zeichenkette
von doppelten Anführungszeichen mit Backslash umgeben werden muss.

@item @code{pixmap-format}
@tab @code{png16m}
@tab Stellt das Ausgabeformat von GhostScript für Pixel-Bilder ein.

@item @code{point-and-click}
@tab @code{#f}
@tab Füge @q{point & click}-Links in die @code{PDF}-Ausgabedatei ein.  Siehe auch
@ref{Point and click}.

@item @code{preview}
@tab @code{#f}
@tab Erstelle Vorschaubilder zusätzlich zur normalen Ausgabe.
@end multitable

@noindent
Diese Option wird von allen Backends unterstützt: @code{pdf}, @code{png},
@code{ps}, @code{eps} und @code{svg}, allerdings nicht @code{scm}.  Hiermit
wird eine Ausgabedatei in der Form @code{meineDatei.preview.Dateierweiterung}
erstellt, die die Titel und das erste Notensystem enthält.  Wenn @code{\book}-
oder @code{\bookpart}-Umgebungen inegesetzt werden, werden die Titel von
@code{\book}, @code{\bookpart} oder @code{\score} in die Ausgabe aufgenommen,
sowie das erste System jeder @code{\score}-Umgebung, wenn die
Variable @code{print-all-headers} in der @code{paper}-Umgebung auf @code{#t}
eingesetllt ist.

Um die normale Ausgabe zu unterdrücken, können die Optionen @option{-dprint-pages}
oder @option{-dno-print-pages} eingesetzt werden.

@multitable @columnfractions .33 .16 .51
@item @code{print-pages}
@tab @code{#t}
@tab Erstelle vollständige Seiten, der Standard.  @option{-dno-print-pages} ist
hilfreich im Zusammenhang mit @option{-dpreview}.

@item @code{profile-property-accesses}
@tab @code{#f}
@tab Speichere Statistiken von @code{get_property()}-Funktionsaufrufen.

@item @code{protected-scheme-parsing}
@tab @code{#t}
@tab Fahre fort, wenn Fehler in eingefügtem Scheme-Code im Parser bemerkt
werden.  Wenn auf @code{#f} gesetzt, halte an Fehlern an und gebe einen
Stacktrace aus.

@item @code{read-file-list}
@tab @code{#f [file]}
@tab Gibt den Dateinamen einer Datei an, die eine Liste mit Eingabedateien
enthält, die kompiliert werden sollen.

@item @code{relative-includes}
@tab @code{#f}
@tab Wenn ein @code{\include}-Befehl bearbeitet wird, suche nach der
eingefügten Datei relativ zur aktuellen Datei (und nicht relativ zur untersten
Ebene).

@item @code{resolution}
@tab @code{101}
@tab Setzt die Auflösung, mit der @code{PNG}-Bilder erstellt werde, auf einen
bestimmten Wert (in dpi).

@item @code{safe}
@tab @code{#f}
@tab Der @code{.ly}-Eingabe nicht trauen.
@end multitable

@noindent
Wenn LilyPond-Notensatz über einen Webserver zur Verfügung gestellt wird,
@b{müssen} entweder die Option @option{--safe} oder die Option @option{--jail}
mitgegeben werden.  Die Option @option{--safe} verhindert eingefügten
Scheme-Code daran, Schaden auszuüben, etwa

@quotation
@verbatim
#(system "rm -rf /")
{
  c4^$(ly:gulp-file "/etc/passwd")
}
@end verbatim
@end quotation

Die Option @option{-dsafe} interpretiert eingefügte Scheme-Ausdrücke
in einem besonderen sicheren Modul.  Das ist aus dem GUILE
@file{safe-r5rs}-Modul abgeleitet, fügt aber einige Funktionen der
LilyPond API hinzu, welche sich in @file{scm/safe-lily.scm} aufgelistet finden.

Zusätzliche verbietet der sichere Modus @code{\include}-Befehle und
stellt die Benutzung von Backslash in @TeX{}-Zeichenketten aus.  Im sicheren
Modus ist es auch
nicht möglich, LilyPond-Variablen in Scheme zu importieren.

@option{-dsafe} kann jedoch @emph{nicht} Überbenutzung von Resourcen
entdecken, sodass man trotzdem das Programm abschießen kann, etwa
indem man eine sich wiederholende Datenstruktur in das Backend
leitet.  Darum sollte LilyPond sowohl in der CPU- als auch Speicherbenutzung
eingeschränkt betrieben werden, wenn es über einen Webserver öffentlich zugänglich
gemacht wird.

Der sichere Modus verhindert die Kompilierung von vielen nützlichen
LilyPond-Schnipseln.

die Option @option{--jail} ist noch sicherer, erfordert aber mehr Arbeit
beim Setup.  Siehe auch @ref{Grundlegende Optionen auf der Kommandozeile für LilyPond}.

@multitable @columnfractions .33 .16 .51
@item @code{separate-log-files}
@tab @code{#f}
@tab Für Eingabedateien @code{Datei1.ly}, @code{Datei2.ly} usw. die
Log-Daten in die Dateien @code{Datei1.log}, @code{Datei2.log} ... schreiben.

@item @code{show-available-fonts}
@tab @code{#f}
@tab Eine Liste der verfügbaren Schriftarten.

@item @code{strict-infinity-checking}
@tab @code{#f}
@tab Erzwinge einen Programmabsturz wenn @code{Inf} und @code{NaN} 
Fließkommaausnahmen gefunden werden.

@item @code{strip-output-dir}
@tab @code{#t}
@tab Verzeichnisse von Eingabedateien nicht in die Konstruktion der
Ausgabedateinamen einbeziehen.

@item @code{svg-woff}
@tab @code{#f}
@tab Woff-Schriftarten im SVG-Backend benuützen..

@item @code{trace-memory-frequency}
@tab @code{#f}
@tab Zeichnet die Benutzung von Scheme so oft pro Sekunde auf.  Das Resultat
wird in die Dateien @code{FILE.stacks} und @code{FILE.graph} ausgegeben.

@item @code{trace-scheme-coverage}
@tab @code{#f}
@tab Abdeckung der Scheme-Dateien in Datei @code{FILE.cov} schreiben.

@item @code{verbose}
@tab @code{#f}
@tab Ausfühliche Ausgabe, also Logstufe DEBUG (read-only).

@item @code{warning-as-error}
@tab @code{#f}
@tab Alle Warnungen und @q{Programmierfehler}-Nachrichten in Fehler ändern.
@end multitable



@node Umgebungsvariablen
@unnumberedsubsec Umgebungsvariablen
@translationof Environment variables

@cindex LANG
@cindex LILYPOND_LOGLEVEL
@cindex LILYPOND_DATADIR
@cindex Variablen, Umgebungs-
@cindex Umgebungsvariablen

@command{lilypond} erkennt und benützt die folgenden Umgebungsvariablen:
@table @code
@item LILYPOND_DATADIR
Diese Variable gibt das Verzeichnis an, wo Lilypond seine eigenen Dateien,
Meldungen und Übersetzungen finden kann.  Dieses Verzeichnis sollte
Unterverzeichnisse @file{ly/}, @file{ps/}, @file{tex/}, etc. beinhalten.

@item LANG
Gibt die Sprache an, in der Warnungen und Fehlermeldungen ausgegeben werden.

@item LILYPOND_LOGLEVEL
Die standardmäßige Logstufe.  Wenn LilyPond ohne eine explizite
Logstufe aufterufen wird (d. h. die Kommandozeilenoption @option{--loglevel}
nicht eingesetzt wird), wird dieser Wert benutzt.

@item LILYPOND_GC_YIELD
Eine Variable (von 1 bis 100), die die Speicherverwaltung regelt.  Bei
niedrigeren Werten wird mehr Prozessor-Zeit, dafür weniger Hauptspeicher
benötigt.  Voreinstellung ist ein Wert von @code{70}.

@end table



@node LilyPond in chroot-Kerker
@unnumberedsubsec LilyPond in chroot-Kerker
@translationof LilyPond in chroot jail

Einen Server einzurichten, der LilyPond in einem chroot-Kerker bedient, ist
recht kompliziert.  Die einzelnen Schritten finden sich unten aufgeliestet.
Beispiele sind für Ubuntu GNU/Linux und erfordern evtl. die Benutzung von
@code{sudo} an den entsprechenden Stellen.

@itemize

@item Installieren Sie die nötigen Pakete: LilyPond, GhostScript und ImageMagick.

@item Erstellen Sie einen neuen Benutzer mit dem Namen @code{lily}:

@example
adduser lily
@end example

@noindent
Hierdurch wird auch eine Gruppe @code{lily} und ein Heimat-Ordner
@code{/home/lily} für den neuen Benutzer erstellt.

@item Im Heimat-Ordner des Benutzers @code{lily} erstellen Sie eine Datei, die als
eigenes Dateisystem eingesetzt wird:

@example
dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
@end example

@noindent
In diesem Beispiel wird eine 200-MB-Datei als Kerker-Dateisystem erstellt.

@item Erstellen Sie ein loop device, erstellen Sie ein Dateisystem und
mounten Sie es, dann erstellen Sie dort einen Ordner, in dem der Benutzer
@code{lily} Schreibrechte hat:

@example
mkdir /mnt/lilyloop
losetup /dev/loop0 /home/lily/loopfile
mkfs -t ext3 /dev/loop0 200000
mount -t ext3 /dev/loop0 /mnt/lilyloop
mkdir /mnt/lilyloop/lilyhome
chown lily /mnt/lilyloop/lilyhome
@end example

@item In der Konfiguration des Servers ist der Kerker (JAIL) @code{/mnt/lilyloop}
und das Verzeichnis (DIR) @code{/lilyhome}.

@item Erstellen Sie einen großen Verzeichnisbaum in dem Kerker, indem Sie die
notwendigen Dateien dorthin kopiert, wie das Beispielskript unten zeigt.

Sie könne @code{sed} benutzen, um die notwendigen Kopierbefehle für ein
bestimmtes Programm zu erstellen:

@example
for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
  do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
    cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
      \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done
@end example

@end itemize

@subheading Beispiel-Skript für 32-bit Ubuntu 8.04

@example
#!/bin/sh
## defaults set here

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# the prefix (without the leading slash!)
lilyprefix=usr/local
# the directory where lilypond is installed on the system
lilydir=/$lilyprefix/lilypond/

userhome=$home/$username
loopfile=$userhome/loopfile
adduser $username
dd if=/dev/zero of=$loopfile bs=1k count=200000
mkdir $jaildir
losetup $loopdevice $loopfile
mkfs -t ext3 $loopdevice 200000
mount -t ext3 $loopdevice $jaildir
mkdir $jaildir/lilyhome
chown $username $jaildir/lilyhome
cd $jaildir

mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
chmod a+w tmp

cp -r -L $lilydir $lilyprefix
cp -L /bin/sh /bin/rm bin
cp -L /usr/bin/convert /usr/bin/gs usr/bin
cp -L /usr/share/fonts/truetype usr/share/fonts

# Now the library copying magic
for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
        | sed '/.*=>.*/d'; done | sh -s

# The shared files for ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# The shared files for ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Now, assuming that you have test.ly in /mnt/lilyloop/lilyhome,
### you should be able to run:
### Note that /$lilyprefix/bin/lilypond is a script, which sets the
### LD_LIBRARY_PATH - this is crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
@end example


@node Fehlermeldungen
@section Fehlermeldungen
@translationof Error messages

@cindex error messages
@cindex Fehlermeldungen

Während der Verarbeitung einer Dateien können diverse Meldungen an der
Kommandozeile auftreten:

@table @emph

@item Warnung (Warning)
@cindex Warnung
Irgendetwas ist verdächtig.  Wenn Sie etwas Ungewöhnliches in Ihrer
Datei durchführen, dann werden Sie die Meldung verstehen und können
sie gegebenenfalls ignorieren.  Im Normalfall jedoch bedeutet eine
Warnung, dass mit Ihrer Datei etwas nicht stimmt, LilyPond jedoch
trotzdem versucht, die Datei soweit wie möglich korrekt zu übersetzen.

@item Fehler (Error)
@cindex Fehler
Irgendetwas stimmt definitiv nicht.  Der aktuelle Bearbeitungsschritt
(Einlesen, Interpretieren oder Formatieren der Datei) wird noch fertig
ausgeführt, danach bricht die Bearbeitung aber ab.

@item Fataler Fehler (Fatal error)
@cindex Fataler Fehler
Irgendetwas stimmt definitiv nicht und LilyPond kann nicht weiter
ausgeführt werden.  Dies ist nur sehr selten der Fall, meist sind
die Schriftarten nicht korrekt installiert.

@item Scheme Fehler (Scheme error)
@cindex Fehlerprotokoll, Scheme
@cindex Scheme Fehler
Fehler, die während der Ausführung von Scheme-Code auftreten, werden
vom Scheme-Interpreter aufgefangen und an der Kommandozeile ausgegeben.
Wenn Sie LilyPond mit der @option{--verbose} Option (auch @code{-V})
ausführen, wird der sogenannte @q{Call trace} ausgegeben, der die
aufgerufenen Funktionen zur Zeit des Fehlers angibt.

@item Programmierfehler (Programming error)
@cindex Programmierfehler
Eine interne Inkonsistenz ist aufgetreten.  Diese Fehlermeldungen
sollen den Programmierern die Fehlersuche erleichtern und
können meistens einfach ignoriert werden.  In manchen Fällen werden
so viele Meldungen ausgegeben, dass die Lesbarkeit der restliche
Ausgabe davon beeinträchtigt wird.

@item Abgebrochen (core dumped)
Dies bezeichnet einen ernsten Programmierfehler, der das Programm
zum Absturz gebracht hat.  Solche Fehler werden als kritisch angesehen.
Falls daher einer auftritt, senden Sie bitte einen Bug-Report!

@end table

@cindex Fehlermeldung, Format
@cindex Form der Fehlermeldungen
Wenn Warnungen oder Fehlermeldungen mit einer konkreten Stelle in der
Eingabedatei verknüpft werden können, dann hat die Meldung die folgende
Form:

@example
@var{Dateiname}:@var{Zeile}:@var{Spalte}: @var{Meldung}
@var{Fehlerhafte Eingabezeile}
@end example

Ein Zeilenumbruch wird in der fehlerhaften Zeile an jener Stelle eingefügt,
wo der Fehler aufgetreten ist.  Zum Beispiel

@example
test.ly:2:19: Fehler: keine gültige Dauer: 5
  @{ c'4 e'
             5 g' @}
@end example

Diese Stellen sind LilyPonds Vermutung, wo die Warnung oder der Fehler
aufgetreten ist, allerdings treten Warnungen und Fehler ja gerade in
unerwarteten Fällen auf.  Manchmal kann Lilypond auch eine fehlerhafte
Stelle zwar noch problemlos verarbeiten, ein paar Zeilen später wirkt
sich der Fehler aber dann doch noch aus.  In solchen Fällen, wo Sie in
der angegebenen Zeile keinen Fehler erkennen, sollten Sie auch die Zeilen
oberhalb der angegebenen Stelle genauer unter die Lupe nehmen.

Mehr Information darüber findet sich in @ref{Häufige Fehlermeldungen}.



@node Häufige Fehlermeldungen
@section Häufige Fehlermeldungen
@translationof Common errors

Die Fehlermeldungen, die unten beschrieben werden, treten of auf,
es ist jedoch nicht immer einfach, die Urache zu finden.  Wenn
der Fehler einmal verstanden ist, kann er einfach behoben werden.


@menu
* Noten laufen aus der Seite heraus::
* Ein zusätzliches System erscheint::
* Offensichtlicher Fehler in ../ly/init.ly::
* Fehlermeldung Ungebundene Variable %::
* Fehlermeldung FT_Get_Glyph_Name::
* Warnung über absteigende staff affinities::
@end menu

@node Noten laufen aus der Seite heraus
@unnumberedsubsec Noten laufen aus der Seite heraus
@translationof Music runs off the page

Noten, die rechts aus der Seite herauslaufen oder sehr komprimiert
aussehen, liegen in fast allen Fällen an einer falschen Notendauer
einer Note, die dazu fürt, dass die letzte Note im Takt über die
Taktgrenze hinwegdauert.  Es ist nicht falsch, wenn die letzte
Note eines Taktes über den Takt hinausdauert, weil einfach angenommen
wird, dass sie im nächsten Takt fortgesetzt wird.  Aber wenn eine
längere Sequenz dieser überhängenden Noten auftritt, können die
Noten sehr gedrängt aussehen oder über den Seitenrand fließen, weil
die automatische Zeilenumbruchsfunktion einen Umbruch nur am Ende
eines vollständigen Taktes einfügen kann, also wenn alle Noten
zum Ende des Taktstriches auch wirklich aufhören.

@warning{Eine falsche Dauer kann dazu führen, dass Zeilenumbrüche
nicht möglich sein und die Zeile entweder sehr gedrängt dargestllt
wird oder über den Seitenrand fließt.}

Die falsche Dauer kann einfach gefunden werden, wenn Taktstrichüberprüfung
eingesetzt wird, siehe @ruser{Takt- und Taktzahlüberprüfung}.

If you actually intend to have a series of such carry-over measures
you will need to insert an invisible bar line where you want the
line to break.  For details, see @ruser{Taktstriche}.


@node Ein zusätzliches System erscheint
@unnumberedsubsec Ein zusätzliches System erscheint
@translationof An extra staff appears

Wenn Kontext nicht explizit mit @code{\new} oder
@code{\context} erstellt werden, werden sie vom Programm erstellt,
sobald ein Befehl angetroffen wird, der im aktuellen Kontext nicht
funktioniert.  In einfachen Partituren ist diese automatische
Erstellung sehr nützlich und die meisten Beispiele der LilyPond-Handbücher
benutzen diese Schreiberleicherterung.  Manchmal jedoch kann es
vorkommen, dass durch die automatische Erstellung von Systemen aufeinmal
unerwartete Notensysteme erstellt werden.  Beispielsweise könnte man
annehmen, dass folgendes Beispiel alle Notenköpfe in dem Notensystem
rot macht, aber als Resultat hat man zwei Systeme, während die
Notenköpfe immernoch schwarz im unteren System erscheinen.

@lilypond[quote,verbatim,relative=2]
\override Staff.NoteHead.color = #red
\new Staff { a }
@end lilypond

Das liegt daran, dass kein @code{Staff}-Kontext existiert, wenn
der @code{\override}-Befehl verarbeitet wird, sodass ein System
für diesen Befehl erstellt wird.  Dann aber erstellt @code{\new Staff}
noch ein zusätzliches System, wo die Noten gesetzt werden.  Die
richtige Schreibweise wäre:

@lilypond[quote,verbatim,relative=2]
\new Staff {
  \override Staff.NoteHead.color = #red
  a
}
@end lilypond

Ein zweites Beispiel zeigt, dass ein @code{\relative}-Befehl innerhalb
von @code{\repeat} zwei Systeme erstellt, wobei der zweite etwas verschoben
ist.  Das liegt daran, dass @code{\repeat} zwei @code{\relative}-Umgebungen
erstellt, die jede implizit einen @code{Staff}- und @code{Voice}-Kontext
erstellen.

@lilypond[quote,verbatim]
\repeat unfold 2 {
  \relative c' { c4 d e f }
}
@end lilypond

Indem man die @code{Voice}-Kontexte explizit erstellt, kann das Problem
umgangen werden.

@lilypond[quote,verbatim]
\new Voice {
  \repeat unfold 2 {
    \relative c' { c4 d e f }
  }
}
@end lilypond


@node Offensichtlicher Fehler in ../ly/init.ly
@unnumberedsubsec Offensichtlicher Fehler in ../ly/init.ly
@translationof Apparent error in @code{../ly/init.ly}

Verschiedene seltsame Fehlermeldungen können über Syntax-Fehler in
@file{../ly/init.ly} auftauchen, wenn die Eingabedatei nicht richtig
formuliert ist, wenn sie etwa nicht richtig passende Klammerpaare
oder Anführungszeichen enthält.

Der üblichste Fehler ist das Fehlen einer geschweiften Klammer
(@code{@}}) am Ende der @code{score}-Umbgebung.  Die Lösung ist hier
klar: überprüfen Sie, ob die @code{score}-Umgebung richtig beendet
wurde.  Die richtige Struktur einer Eingabedatei wird beschrieben
in @rlearning{Wie eine LilyPond-Eingabe-Datei funktioniert}.
Ein Editor, der die Klammerpaare automatisch anzeigt, ist sehr
hilfreich, um derartige Fehler zu vermeiden.

Eine weitere übliche Fehlerquelle ist kein Leerzeichen zwischen der
letzten Silbe einer @code{lyrics}-Umgebung und der schließenden
Klammer (@code{@}}).  Ohne diese Trennung wird die Klammer als
Teil der Silbe gewertet.  Es bietet sich immer an, Leerzeichen vor
und hinter @emph{jede} Klammer zu setzen.  Wie wichtig das ist, wenn
Gesangstext eingesetzt wird, siehe @ruser{Eingabe von Text}.

Diese Fehlermeldung kann auch mit einem fehlenden schließenden Anführungszeichen
(@code{"}) auftreten.  In diesem Fall sollte die begleitende Fehlermeldung
eine Zeilenzahl angeben, die dicht am Fehler liegt.  Die nicht paarigen
Anführungszeichen sind meistens ein oder zwei Zeilen darüber.


@node Fehlermeldung Ungebundene Variable %
@unnumberedsubsec Fehlermeldung Ungebundene Variable %
@translationof Error message Unbound variable %

Diese Fehlermeldung erscheint am Ende der Kommandozeilenausgabe oder in der
Log-Datei mit einer Meldung @qq{GUILE signalled an error ...}
jedes Mal, wenn eine Scheme-Routine aufgerufen wird, die
(falscherweise) ein @emph{LilyPond}-Kommentar und kein
@emph{Scheme}-Kommentar enthält.

LilyPond-Kommentare befginnen mit dem Prozent-Zeichen (@code{%}) und
dürfen nicht in Scheme-Routinen benutzt werden.  Scheme-Kommentare beginnen
mit einem Semikolon (@code{;}).

@node Fehlermeldung FT_Get_Glyph_Name
@unnumberedsubsec Fehlermeldung FT_Get_Glyph_Name
@translationof Error message FT_Get_Glyph_Name

Diese Fehlermeldung erscheint in der Kommandozeilenausgabe, wenn die
Datei ein Zeichen enthält, das nicht zu ASCII gehört und die Datei
nicht in UTF-8-Kodierung gespeichert wurd.  Sie auch @ruser{Zeichenkodierung}.


@node Warnung über absteigende staff affinities
@unnumberedsubsec Warnung über absteigende staff affinities
@translationof Warning staff affinities should only decrease

Diese Warnung erscheint, wenn keine Notensysteme in der Ausgabe vorhanden
sind, wenn etwa nur @code{ChordName}-Kontext und @code{Lyrics}-Kontext
in einem Liedblatt vorhanden sind.  Die Warnungen können vermieden werden,
indem man einen der Kontexte als System erscheinen lässt, indem man ihm
zu Beginn hinzufügt:

@example
\override VerticalAxisGroup.staff-affinity = ##f
@end example

Zu Einzelheiten siehe @qq{Abstand von Nicht-Notensystemzeilen} in
@ruser{Flexible vertikale Abstände in Systemgruppen}.