@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.23.4"

@c Translators: Till Paala

@node Allgemeine Eingabe und Ausgabe
@chapter Allgemeine Eingabe und Ausgabe
@translationof General input and output

Dieses Kapitel erklärt allgemeine Fragen zur Eingabe und Ausgabe von
Notation mit LilyPond und weniger direkte Fragen der Notation.

@menu
* Eingabestruktur::
* Titel::
* Arbeiten an Eingabe-Dateien::
* Ausgabe kontrollieren::
* MIDI-Ausgabe::
* Musikalische Information extrahieren::
@end menu


@node Eingabestruktur
@section Eingabestruktur
@translationof Input structure

Das hauptsächliche Eingabeformat von LilyPond sind Textdateien.
Üblicherweise werden diese Dateien mit der Endung @file{.ly}
versehen.

@menu
* Struktur einer Partitur::
* Mehrere Partituren in einem Buch::
* Mehrere Ausgabedateien aus einer Eingabedatei::
* Dateinamen der Ausgabedateien::
* Die Dateistruktur::
@end menu


@node Struktur einer Partitur
@subsection Struktur einer Partitur
@translationof Structure of a score

@funindex \score

Eine @code{\score}-Umgebung muss einen einzelnen musikalischen
Ausdruck beinhalten, der durch geschweifte Klammern begrenzt wird:

@example
\score @{
...
@}
@end example

@warning{Es darf @strong{nur ein} äußerer musikalischer Ausdruck
in der @code{@bs{}score}-Umgebung geschrieben werden, und er @strong{muss}
von geschweiften Klammern umgeben sein.}

Dieser einzelne musikalische Ausdruck kann beliebige Größe annehmen und
andere musikalische Ausdrücke von beliebiger Komplexität beinhalten.
Alle diese Beispiele sind musikalische Ausdrücke:

@example
@{ c'4 c' c' c' @}
@end example

@lilypond[verbatim,quote]
{
  { c'4 c' c' c' }
  { d'4 d' d' d' }
}
@end lilypond

@lilypond[verbatim,quote]
<<
  \new Staff { c'4 c' c' c' }
  \new Staff { d'4 d' d' d' }
>>
@end lilypond

@example
@{
  \new GrandStaff <<
    \new StaffGroup <<
      \new Staff @{ \Flöte @}
      \new Staff @{ \Oboe @}
    >>
    \new StaffGroup <<
      \new Staff @{ \GeigeI @}
      \new Staff @{ \GeigeII @}
    >>
  >>
@}
@end example

Kommentare bilden eine Ausnahme dieser Regel.  (Andere Ausnahmen
siehe @ref{Die Dateistruktur}.)  Sowohl einzeilige als auch
Blockkommentare (eingegrenzt durch @code{%@{ .. %@}}) können
an beliebiger Stelle einer Eingabedatei geschrieben werden.  Sie
können innerhalb oder außerhalb der @code{\score}-Umgebung vorkommen,
und innerhalb oder außerhalb des einzelnen musikalischen Ausdrucks
innerhalb der @code{\score}-Umgebung.

Denken Sie daran, dass auch eine Datei, die nur eine @code{\score}-Umgebung
enhält, implizit in eine @code{\book}-Umgebung eingeschlossen wird.  Eine
@code{\book}-Umgebung in einer Eingabdatei produziert wenigstens eine
Ausgabedatei, und standardmäßig wird der Name der Ausagabedatei aus dem
Namen der Eingabedatei abgeleitet.  @file{fandangoforelephants.ly} produziert
also @file{fandangoforelephants.pdf}.

Zu weiteren Einzelheiten zu @code{\book}-Umgebungen siehe
@ref{Mehrere Partituren in einem Buch},
@ref{Mehrere Ausgabedateien aus einer Eingabedatei} und
@ref{Die Dateistruktur}.


@morerefs
Handbuch zum Lernen:
@rlearning{Arbeiten an Eingabe-Dateien},
@rlearning{Musikalische Ausdrücke erklärt},
@rlearning{Score ist ein (einziger)  zusammengesetzter musikalischer Ausdruck}.

Notationsreferenz:
@ref{Mehrere Partituren in einem Buch},
@ref{Mehrere Ausgabedateien aus einer Eingabedatei} und
@ref{Die Dateistruktur}.


@node Mehrere Partituren in einem Buch
@subsection Mehrere Partituren in einem Buch
@translationof Multiple scores in a book

@funindex \book
@cindex Sätze, mehrere

Eine Partitur kann mehrere musikalische Stücke und verschiedene
Texte beinhalten.  Beispiele hierzu sind etwa eine Etüdensammlung
oder ein Orchesterstück mit mehreren Sätzen.  Jeder Satz wird
in einer eigenen @code{\score}-Umgebung notiert:

@example
\score @{
  @var{..Noten..}
@}
@end example

@noindent
und Texte werden mit einer @code{\markup}-Umgebung geschrieben:

@example
\markup @{
  @var{..Text..}
@}
@end example

@funindex \book

Alle Sätze und Texte, die in derselben @file{.ly}-Datei vorkommen,
werden normalerweise in eine einzige Ausgabedatei gesetzt.

@example
\score @{
  @var{..}
@}
\markup @{
  @var{..}
@}
\score @{
  @var{..}
@}
@end example

Eine wichtige Ausnahme stellen Dokumente dar,
die mit lilypond-book erstellt werden, für die Sie explizit
@code{\book}-Umgebungen notieren müssen, weil sonst nur die erste
@code{\score}- bzw. @code{\markup}-Umgebung angezeigt wird.

Der Kopfbereich für jedes Musikstück kann innerhalb der @code{\score}-Umgebung
definiert werden.  Die @code{piece}-(Stück)-Bezeichnung aus dieser
@code{\header}-Umgebung wird vor jedem Satz ausgegeben.  Die Überschrift für
ein ganzes Buch kann innerhalb von @code{\book} notiert werden, aber wenn
diese Umgebung fehlt, wird die @code{\header}-Umgebung genommen, die auf
erster Ebene der Datei notiert ist.

@example
\header @{
  title = "Acht Miniaturen"
  composer = "Igor Stravinsky"
@}
\score @{
  \header @{ piece = "Romanze" @}
  @dots{}
@}
\markup @{
   ..Text der zweiten Strophe..
@}
\markup @{
   ..Text der dritten Strophe..
@}
\score @{
  \header @{ piece = "Menuetto" @}
  @dots{}
@}
@end example

@funindex \bookpart

Stücke können innerhalb eines Buches mit @code{\bookpart} gruppiert
werden.  Derartige Buchabschnitte werden durch einen Seitenumbruch
voneinander getrennt und können wie auch das ganze Buch selber mit
einem Titel innerhalb einer @code{\header}-Umgebung beginnen.

@example
\bookpart @{
  \header @{
    title = "Buchtitel"
    subtitle = "Erster Teil"
  @}
  \score @{ @dots{} @}
  @dots{}
@}
\bookpart @{
  \header @{
    subtitle = "Zweiter Teil"
  @}
  \score @{ @dots{} @}
  @dots{}
@}
@end example


@node Mehrere Ausgabedateien aus einer Eingabedatei
@subsection Mehrere Ausgabedateien aus einer Eingabedatei
@translationof Multiple output files from one input file

Wenn Sie mehrere Ausgabedateien aus derselben @file{.ly}-Datei haben
wollen, können Sie mehrere @code{\book}-Umgebungen hinzufügen, wobei
jede Umgebung eine neue Ausgabedatei produziert.  Wenn Sie keine
@code{\book}-Umgebung in der Eingabedatei angeben, wird die Datei von
LilyPond implizit als eine große @code{\book}-Umgebung behandelt, siehe
auch @ref{Die Dateistruktur}.

Wenn man mehrere Dateien aus einer einzigen Eingabedatei erstellt, stellt
LilyPond sicher, dass keine der Ausgabedateien der vorhandenen
@code{\book}-Umgebungen eine andere Ausgabedatei, etwa von der vorherigen
@code{\book}-Umgebung, überschreibt.

Dies geschieht, indem ein Suffix an den Ausgabenamen für jede
@code{\book}-Umgebung gehängt wird, die den Dateinamen der Eingabdatei
als Grundlage nimmt.

Das Standardverhalten ist es, einen Zahlen-Suffix für die Namen hinzuzufügen,
die in Konflikt stehen.  Der Code

@example
\book @{
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
@end example

@noindent
produziert also

@itemize
@item
@file{eightminiatures.pdf},
@item
@file{eightminiatures-1.pdf} and
@item
@file{eightminiatures-2.pdf}.
@end itemize


@node Dateinamen der Ausgabedateien
@subsection Dateinamen der Ausgabedateien
@translationof Output file names

@funindex \bookOutputSuffix
@funindex \bookOutputName

LilyPond stellt die Möglichkeit zur Verfügung zu kontrollieren, welche
Dateinamen für welche Back-ends benutzt werden sollen, wenn die Ausgabedateien
erstellt werden.

Im vorhergehenden Abschnitt wurde gezeigt, wir LilyPond gleichnamige
Ausgabedateien verhindert, wenn mehrere Ausgabedateien aus derselben
Eingabedatei erstellt werden.  Es gibt auch die Möglichkeit, eigene
Suffixe für jeden @code{\book}-Abschnitt zu definieren, sodass man etwa
Dateinamen wie @file{eightminiatures-Romanze.pdf}, @file{eightminiatures-Menuetto.pdf}
und @file{eightminiatures-Nocturne.pdf} produzieren kann, indem man
eine @code{\bookOutputSuffix}-Angabe in jede @code{\book}-Umgebung
einfügt.

@example
\book @{
  \bookOutputSuffix "Romanze"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputSuffix "Menuetto"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputSuffix "Nocturne"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
@end example

Man kann auch einen anderen Dateinamen für die Ausgabedatei einer
@code{\book}-Umgebung erstellen, indem man @code{\bookOutputName}-Angabe
macht:

@example
\book @{
  \bookOutputName "Romanze"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputName "Menuetto"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
\book @{
  \bookOutputName "Nocturne"
  \score @{ @dots{} @}
  \layout @{ @dots{} @}
@}
@end example

Die obige Datei produziert folgene Ausgabedateien:

@itemize
@item
@file{Romanze.pdf},
@item
@file{Menuetto.pdf} and
@item
@file{Nocturne.pdf}.
@end itemize
@node Die Dateistruktur
@subsection Die Dateistruktur
@translationof File structure

@funindex \paper
@funindex \midi
@funindex \layout
@funindex \header
@funindex \score
@funindex \book
@funindex \bookpart

@cindex Dateistruktur
@cindex Struktur, Datei
@cindex Eingabedatei, Struktur
@cindex Quelldatei, Struktur

Eine @file{.ly}-Datei kann eine beliebige Anzahl an Ausdrücken
auf der obersten Ebene beinhalten, wobei ein Ausdruck der obersten
Ebene einer der folgenden sein kann:

@itemize
@item
Eine Ausgabedefinition, wie @code{\paper}, @code{\midi} und
@code{\layout}.  Derartige Definitionen auf oberster Ebene verändern
die globalen Einstellungen für das ganze @qq{Buch}.  Wenn mehr
als eine derartige Definition desselben Typs auf oberster Ebene
angegeben wird, hat die spätere Vorrang.  Für Einzelheiten, wie dadurch
die @code{\layout}-Umgebung beeinflusst wird, siehe
@ref{Die layout-Umgebung}.

@item
Ein direkter Scheme-Ausdruck, wie etwa
@code{#(set-default-paper-size "a7" 'landscape)} oder
@code{#(ly:set-option 'point-and-click #f)}.

@item
Eine @code{\header}-Umgebung.  Damit wird die globale Titelei
eingestellt.  Das ist die Umgebung, in der sich Definition für
das ganze Buch befinden, wie Komponist, Titel usw.

@item
Eine @code{\score}-Umgebung.  Die in ihr enthaltene Partitur wird
zusammen mit anderen vorkommenden @code{\score}-Umgebungen gesammelt
und in ein @code{\book} zusammengefasst.  Dieses Verhalten kann
verändert werden, indem die Variable @code{toplevel-score-handler}
auf höchster Ebene gesetzt wird.  Die Definition des Standards findet sich
in der Datei @file{../scm/lily.scm}.

@item
Eine @code{\book}-Umgebung fasst mehrere Sätze (d. h. mehrere
@code{\score}-Umgebungen) logisch in ein Dokument zusammen.
Wenn mehrere @code{\score}-Partituren vorkommen, wird für jede
@code{\book}-Umgebung eine eigene Ausgabedatei erstellt, in der
alle in der Umgebung enthaltenen Partituren zusammengefasst sind.
Der einzige Grund, explizit eine @code{\book}-Umgebung zu setzen,
ist, wenn mehrere Ausgabedateien aus einer einzigen Quelldatei
erstellt werden sollen.  Eine Ausnahme sind lilypond-book-Dokumente,
in denen eine @code{\book}-Umgebung explizit hinzugefügt werden
muss, wenn mehr als eine @code{\score}- oder @code{\markup}-Umgebung
im gleichen Beispiel angezeigt werden soll.  Dieses Verhalten
kann verändert werden, indem die Variable @code{toplevel-book-handler}
auf höchster Ebene gesetzt wird.  Die Definition des Standards
findet sich in der Datei @file{../scm/lily.scm}.

@item
Eine @code{\bookpart}-Umgebung.  Ein Buch (@code{\book}) kann in
mehrere Teile untergliedert sein, indem @code{\bookpart}-Umgebungen
eingesetzt werden. Jeder Buchabschnitt beginnt auf einer neuen
Seite und kann eigene Papierdefinitionen in einer @code{\paper}-Umgebung
haben.

@item
Ein zusammengesetzter musikalischer Ausdruck wie etwa
@example
@{ c'4 d' e'2 @}
@end example

Dieses Beispiel wird von LilyPond automatisch in einer
@code{\score}-Umgebung in einem Buch interpretiert und
mit anderen @code{\score}-Umgebungen und musikalischen
Ausdrücken auf der höchsten Ebene zusammen ausgegeben.
Anders gesagt: eine Datei, die nur das obige Beispiel
beinhaltet, wird übersetzt zu

@example
\book @{
  \score @{
    \new Staff @{
      \new Voice @{
        @{ c'4 d' e'2 @}
      @}
    @}
    \layout @{ @}
  @}
  \paper @{ @}	
  \header @{ @}
@}
@end example

Dieses Verhalten kann verändert werden, indem die Variable
@code{toplevel-music-handler} auf der obersten Ebene gesetzt
wird.  Die Definition des Standards findet sich in der Datei
@file{../scm/lily.scm}.

@item
Eine Textbeschriftung, eine Strophe etwa:
@example
\markup @{
   2.  Die erste Zeile der zweiten Strophe.
@}
@end example

Textbeschriftungen werden über, zwischen oder unter musikalischen
Ausdrücken gesetzt, so wie sie notiert werde.

@cindex Variablen

@item
Eine Variable, wie
@example
foo = @{ c4 d e d @}
@end example

Sie kann dann später in der Datei eingesetzt werden, indem @code{\foo}
geschrieben wird.  Die Bezeichnung der Variable darf nur aus
alphabetischen Zeichen bestehen, keine Zahlen, Unter- oder Bindestriche.

@end itemize

Das folgende Beispiel zeigt drei Dinge, die auf der obersten Ebene
notiert werden können:

@example
\layout @{
  % Zeilen rechtsbündig setzen
  ragged-right = ##t
@}

\header @{
   title = "Do-re-mi"
@}

@{ c'4 d' e2 @}
@end example

An einer beliebigen Stelle der Datei kann jede der folgenden lexikalen
Anweisungen notiert werden:

@itemize
@item @code{\version}
@item @code{\include}
@item @code{\sourcefilename}
@item @code{\sourcefileline}
@item
Ein einzeiliger Kommentar, beginnend mit @code{%}.

@item
Ein mehrzeiliger Kommentar, umgeben von @code{%@{ .. %@}}.

@end itemize

@cindex Leerzeichen

Leerzeichen zwischen Einheiten in der Eingabe werden generell ignoriert
und können nach Belieben weggelassen werden oder hinzugefügt werden,
um die Lesbarkeit des Codes zu verbessern.  Mindestens ein Leerzeichen
sollte jedoch unter folgenden Umständen immer eingesetzt werden, um
Fehler zu vermeiden:

@itemize
@item
Vor und hinter jeder schließenden oder öffnenden Klammer,
@item
nach jedem Befehl oder jeder Variable, also jeder Einheit, die mit
@code{\} beginnt,
@item
nach jeder Einheit, die als Scheme-Ausdruck interpretiert werden,
also alle Einheiten, die mit@tie{}@code{#} beginnen.
@item
Alle Einheiten von Scheme-Ausdrücken müssen mit Leerzeichen getrennt
werden,
@item
in Gesangstextabschnitten (@code{lyricmode}) müssen Leerzeichen
zwischen alle Ausdrücke in @code{\override}- und @code{\set}-Befehlen
gesetzt werden.  Insbesondere müssen um Punkte und Gleichzeitszeichen
in Befehlen wie @code{\override Score.LyricText.font-size = #5)}
und vor dem gesamten Befehl geschrieben werden.

@end itemize

@morerefs
Handbuch zum Lernen:
@rlearning{Wie eine LilyPond-Eingabe-Datei funktioniert}.

Notationsreferenz:
@ref{Die layout-Umgebung}.


@node Titel
@section Titel
@translationof Titles and headers

Fast alle gedruckten Noten beinhalten einen Titel und den Namen
des Komponisten, teilweise wird auch noch sehr viel mehr Information
zur Verfügung gestellt.

@menu
* Titel Kopf und Fußzeilen erstellen::
* Eigene Kopf und Fußzeilen sowie Titel::
* Fußnoten erstellen::
* Verweis auf die Seitenzahlen::
* Inhaltsverzeichnis::
@end menu


@node Titel Kopf und Fußzeilen erstellen
@subsection Titel, Kopf- und Fußzeilen erstellen
@translationof Creating titles headers and footers

@menu
* Wie funktioniert die Titel-Umgebung?::
* Standardlayout von book und Partitur Titelumgebungen::
* Standardlayout von Kopf und Fußzeilen::
@end menu


@node Wie funktioniert die Titel-Umgebung?
@unnumberedsubsubsec Wie funktioniert die Titel-Umgebung?
@translationof Title blocks explained

@c TODO: figure out how \bookpart titles work

Es gibt zwei Arten von Titelumgebungen: die Hauptumgebung, die über
der ersten @code{\score}-Umgebung innerhalb eines @qq{book} notiert
wird, und individuelle Titelumgebungen, die innerhalb von
@code{\score} auftreten können.  Textfelder für beide Typen werden
in der @code{\header}-Umgebung eingegeben.

Wenn in dem @qq{book} nur eine einzelne Partitur vorkommt,
kann die @code{\header}-Umgebung innheralb oder außerhalb der
@code{\score}-Umgebung geschrieben werden.

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\header {
  title = "SUITE I."
  composer = "J. S. Bach."
}

\score {
  \header {
    piece = "Prélude."
  }
  \new Staff \relative {
    \clef bass
    \key g \major
    \repeat unfold 2 { g,16( d' b') a b d, b' d, } |
    \repeat unfold 2 { g,16( e' c') b c e, c' e, } |
  }
}

\score {
  \header {
    piece = "Allemande."
  }
  \new Staff \relative {
    \clef bass
    \key g \major
    \partial 16 b16 |
    <g, d' b'~>4 b'16 a( g fis) g( d e fis) g( a b c) |
    d16( b g fis) g( e d c) b(c d e) fis( g a b) |
  }
}
@end lilypond

Textfelder der Haupttitelumgebung können in allen @code{\score}-Umgebungen
gesetzt oder manuell unterdrückt werden:

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    print-all-headers = ##t
  }
  \header {
    title = "DAS WOHLTEMPERIRTE CLAVIER"
    subtitle = "TEIL I"
    % Do not display the tagline for this book
    tagline = ##f
  }
  \markup { \vspace #1 }
  \score {
    \header {
      title = "PRAELUDIUM I"
      opus = "BWV 846"
      % Do not display the subtitle for this score
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
  \score {
    \header {
      title = "FUGA I"
      subsubtitle = "A 4 VOCI"
      opus = "BWV 846"
      % Do not display the subtitle for this score
      subtitle = ##f
    }
    \new PianoStaff <<
      \new Staff { s1 }
      \new Staff { \clef "bass" s1 }
    >>
  }
}
@end lilypond

@morerefs
Notationsreferenz:
@ref{Die Dateistruktur},
@ref{Angepasstes Layout für Titelumgebungen}.


@node Standardlayout von book und Partitur Titelumgebungen
@unnumberedsubsubsec Standardlayout von @code{book}- und Partitur-Titelumgebungen
@translationof Default layout of book and score title blocks

Dieses Beispiel zeigt alle @code{\header}-(Überschrifen)-Variablen:

@lilypond[papersize=a7,quote,verbatim,noragged-right]
\book {
  \header {
      % The following fields are centered
    dedication = "Dedication"
    title = "Title"
    subtitle = "Subtitle"
    subsubtitle = "Subsubtitle"
      % The following fields are evenly spread on one line
      % the field "instrument" also appears on following pages
    instrument = \markup \with-color #green "Instrument"
    poet = "Poet"
    composer = "Composer"
      % The following fields are placed at opposite ends of the same line
    meter = "Meter"
    arranger = "Arranger"
      % The following fields are centered at the bottom
    tagline = "tagline goes at the bottom of the last page"
    copyright = "copyright goes at the bottom of the first page"
  }
  \score {
    \header {
        % The following fields are placed at opposite ends of the same line
      piece = "Piece 1"
      opus = "Opus 1"
    }
    { s1 }
  }
  \score {
    \header {
        % The following fields are placed at opposite ends of the same line
      piece = "Piece 2 on the same page"
      opus = "Opus 2"
    }
    { s1 }
  }
  \pageBreak
  \score {
    \header {
        % The following fields are placed at opposite ends of the same line
      piece = "Piece 3 on a new page"
      opus = "Opus 3"
    }
    { s1 }
  }
}
@end lilypond

Beachten Sie:

@itemize
@item
Die Instrumentenbezeichnung wird auf jeder Seite wiederholt.

@item
Nur @code{piece} (Stück)uand @code{opus} werden für eine Partitur 
(@code{\score}) gesetzt, wenn die @code{\paper}-Variable
@code{print-all-headers} auf @code{##f} gesetzt ist (Standardeinstellung).

@item
@c Is the bit about \null markups true? -mp
Textfelder, die in einer @code{\header}-Umgebung nicht benutzt werden,
werden durch @code{\null}-Textbeschriftung ersetzt, sodass sie keinen
leeren Platz belegen.

@item
Die Standardeinstellungen von @code{scoreTitleMarkup} platzieren
die Felder @code{piece} (Stück) und @code{opus} zu den gegenüberliegenden
Seiten der selben Zeile.

@end itemize

Um die Standardeinstellungen des Layouts zu ändern, siehe
@ref{Angepasstes Layout für Titelumgebungen}.

@funindex breakbefore

Mit der Variable @code{breakbefore} innerhalb einer @code{\header}-Umgebung,
die für sich auch eine @code{\score}-Umgebung darstellt, kann man
die Hauptüberschriften auf der ersten Seite allein ausgeben, sodass die
Noten (in der @code{score}-Umgebung definiert) erst auf der folgenden
Seite beginnen.

@lilypond[papersize=a8landscape,verbatim,noragged-right]
\book {
  \header {
    title = "This is my Title"
    subtitle = "This is my Subtitle"
    copyright = "This is the bottom of the first page"
  }
  \score {
    \header {
      piece = "This is the Music"
      breakbefore = ##t
    }
    \repeat unfold 4 { e'' e'' e'' e'' }
  }
}
@end lilypond

@morerefs
Handbuch zum Lernen:
@rlearning{Wie eine LilyPond-Eingabe-Datei funktioniert},

Notationsreferenz:
@ref{Die Dateistruktur},
@ref{Angepasstes Layout für Titelumgebungen}.

Installierte Dateien:
@file{ly/titling-init.ly}.


@node Standardlayout von Kopf und Fußzeilen
@unnumberedsubsubsec Standardlayout von Kopf- und Fußzeilen
@translationof Default layout of headers and footers

@emph{Kopf-} und @emph{Fußzeilen} sind Textzeilen, die ganz oben
und ganz unten auf der Seite stehen, unabhängig vom Textbereich eines
Buches.  Sie können mit folgenden @code{\paper}-Variablen kontrolliert
werden:

@itemize
@item @code{oddHeaderMarkup}
@item @code{evenHeaderMarkup}
@item @code{oddFooterMarkup}
@item @code{evenFooterMarkup}
@end itemize

Diese Beschriftungsvariablen können nur auf Textfelder einer
Haupttitelumgebung (eine @code{\header}-Umgebung auf höchster Ebene, die
sich auf alle @code{\score}-Umgebungen einer Datei bezieht)
zugreifen und sind definiert in der Datei @file{ly/titling-init.ly}.  In
den Standardeinstellungen

@itemize

@item
werden Seitenzahlen automatisch ganz oben links (wenn gerade) oder ganz
oben rechts (wenn ungerade) gesetzt, beginnend mit der zweiten Seite.

@item
wird das @code{instrument}-Textfeld auf jeder Seite zentriert, beginnend
mit der zweiten Seite.

@item
wird der @code{copyright}-Text unten auf der ersten Zeite zentriert.

@item
wird der Inhalt von @code{tagline} unten auf der letzten Seite zentriert
und unterhalb des @code{copyright}-Texts, wenn es sich nur um eine Seite
handelt.

@end itemize

@lilypond[papersize=a8landscape]
\book {
  \score {
    \relative {
      c'4 d e f
    }
  }
}
@end lilypond

Die Standardeinstellung von @code{tagline} kann verändert werden,
indem man ein @code{tagline}-Feld in die @code{\header}-Umgebung auf
höchster Ebene schreibt.

@lilypond[papersize=a8landscape,verbatim]
\book {
  \header {
    tagline = "... music notation for Everyone"
  }
  \score {
    \relative {
      c'4 d e f
    }
  }
}
@end lilypond

Um die @emph{tagline} ganz zu entfernen, wird ihr Inhalb als @code{##f}
(falsch) definiert.


@node Eigene Kopf und Fußzeilen sowie Titel
@subsection Eigene Kopf- und Fußzeilen sowie Titel
@translationof Custom headers footers and titles

@c TODO: somewhere put a link to header spacing info
@c       (you'll have to explain it more in NR 4).

@menu
* Angepasste Textformatierung für Titelumgebungen::
* Angepasstes Layout für Titelumgebungen::
* Angepasstes Layout für Kopf und Fußzeilen::
@end menu


@node Angepasste Textformatierung für Titelumgebungen
@unnumberedsubsubsec Angepasste Textformatierung für Titelumgebungen
@translationof Custom text formatting for title blocks

Standard-@code{\markup}-Befehle können eingesetzt werden, um jeglichen
Text in Titeln, Kopf- und Fußzeilen innerhalb der @code{\header}-Umgebung
zu verändern.

@lilypond[quote,verbatim,noragged-right]
\score {
  \header {
    piece = \markup { \fontsize #4 \bold "PRAELUDIUM I" }
    subtitle = \markup { \italic "(Excerpt)" }
  }
  { s1 }
}
@end lilypond

@morerefs
Notationsreferenz:
@ref{Text formatieren}.


@node Angepasstes Layout für Titelumgebungen
@unnumberedsubsubsec Angepasstes Layout für Titelumgebungen
@translationof Custom layout for title blocks

@cindex bookTitleMarkup
@cindex scoreTitleMarkup
@funindex bookTitleMarkup
@funindex scoreTitleMarkup

@code{\markup}-Befehle in der @code{\header}-Umgebung sind sinnvoll
für einfaches Formatieren von Text, aber sie gewähren keine genaue
Kontrolle über die Positionierung von Titeln.  Um die Positionierung
von Titeltextfeldern vorzunehmen, eignen sich beide oder eine von
folgenden Variablen (die man in der @code{\paper}-Umgebung einsetzen muss):

@itemize
@item @code{bookTitleMarkup}
@item @code{scoreTitleMarkup}
@end itemize

Die Positionierung von Titeln, wenn die Standardeinstellung dieser
Variablen benützt werden, wird anhand einem Beispiel gezeigt in
@ref{Standardlayout von book und Partitur Titelumgebungen}.

Die Standardeinstellungen von @code{scoreTitleMarkup}, wie in der
Datei @file{ly/titling-init.ly} definiert, sind:

@example
scoreTitleMarkup = \markup @{ \column @{
  \if \should-print-all-headers @{ \bookTitleMarkup \hspace #1 @}
  \fill-line @{
    \fromproperty #'header:piece
    \fromproperty #'header:opus
  @}
@}
@}
@end example

Dadurch werden die Textfelder @code{piece} (Stück) und @code{opus}
an den gegenüberliegenden Enden der gleichen Zeile platziert:

@lilypond[quote,verbatim,noragged-right]
\score {
  \header {
    piece = "PRAELUDIUM I"
    opus = "BWV 846"
  }
  { s1 }
}
@end lilypond

Das folgende Beispiel verändert die Einstellungen von
@code{scoreTitleMarkup}, sodass das Textfeld @code{piece}
zentriert wird und in fetter, größerer Schrift erscheint.

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    indent = 0\mm
    scoreTitleMarkup = \markup {
      \fill-line {
        \null
        \fontsize #4 \bold \fromproperty #'header:piece
        \fromproperty #'header:opus
      }
    }
  }
  \header { tagline = ##f }
  \score {
    \header {
      piece = "PRAELUDIUM I"
      opus = "BWV 846"
    }
    { s1 }
  }
}
@end lilypond

Textfelder, die normalerweise nur im Haupttitel ausgegeben werden,
können auch in die Titel einzelner Partituren aufgenommen werden,
indem man @code{print-all-headers} in die @code{\paper}-Umgebung einfügt.
Ein Nachteil dieser Methode ist, dass Textfelder, die tatsächlich nur
im Haupttitel erscheinen sollen, manuell für jede Partitur unterdrückt
werden müssen.  Siehe auch @ref{Wie funktioniert die Titel-Umgebung?}.

Um das zu vermeiden, kann das gewünschte Feld zur Definition von
@code{scoreTitleMarkup} hinzugefügt werden.  Im folgenden Beispiel
wird das Komponistenfeld (@code{composer}) (normalerweise mit
@code{bookTitleMarkup} assoziiert) zu @code{scoreTitleMarkup}
hinzugefügt, sodass jede Partitur einen eigenen Komponisten haben kann.

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    indent = 0\mm
    scoreTitleMarkup = \markup {
      \fill-line {
        \null
        \fontsize #4 \bold \fromproperty #'header:piece
        \fromproperty #'header:composer
      }
    }
  }
  \header { tagline = ##f }
  \score {
    \header {
      piece = "MENUET"
      composer = "Christian Petzold"
    }
    { s1 }
  }
  \score {
    \header {
      piece = "RONDEAU"
      composer = "François Couperin"
    }
    { s1 }
  }
}
@end lilypond

Es ist auch möglich, eigene Textfelder zu erstellen und dann auf sie
in der Beschriftungsdefinition zu verweisen:

@lilypond[papersize=a5,quote,verbatim,noragged-right]
\book {
  \paper {
    indent = 0\mm
    scoreTitleMarkup = \markup {
      \fill-line {
        \null
        \override #`(direction . ,UP)
        \dir-column {
          \center-align \fontsize #-1 \bold
            \fromproperty #'header:mycustomtext %% User-defined field
          \center-align \fontsize #4 \bold
            \fromproperty #'header:piece
        }
        \fromproperty #'header:opus
      }
    }
  }
  \header { tagline = ##f }
  \score {
    \header {
      piece = "FUGA I"
      mycustomtext = "A 4 VOCI" %% User-defined field
      opus = "BWV 846"
    }
    { s1 }
  }
}
@end lilypond

@morerefs
Notationsreferenz:
@ref{Wie funktioniert die Titel-Umgebung?}.


@node Angepasstes Layout für Kopf und Fußzeilen
@unnumberedsubsubsec Angepasstes Layout für Kopf- und Fußzeilen
@translationof Custom layout for headers and footers

@c can make-header and make-footer be removed from
@c paper-defaults-init.ly? -mp

@code{\markup}-Befehle in der @code{\header}-Umgebung sind nützlich
um einfachen Text zu formatieren, erlauben aber keine Kontrolle
über die Positionierung von Kopf- und Fußzeilen.  Um die Positionierung
der Textfelder zu ändern, eignen sich beide oder eine von
folgenden Variablen (die man in der @code{\paper}-Umgebung einsetzen muss):

@itemize
@item @code{oddHeaderMarkup}
@item @code{evenHeaderMarkup}
@item @code{oddFooterMarkup}
@item @code{evenFooterMarkup}
@end itemize

@cindex Beschriftung mit Bedingung
@cindex on-the-fly
@funindex \on-the-fly

Der @code{\markup}-Befehl @code{\on-the-fly} kann eingesetzt werden,
um Beschriftung anhand einer Bedingung zu Kopf- und Fußzeilentext
innerhalb der @code{\paper}-Umgebung hinzuzufügen.  Hierzu wird folgende
Syntax eingesetzt:

@example
Variable = \markup @{
  ...
  \on-the-fly  #@var{Prozedur}  @var{Beschriftung}
  ...
@}
@end example

Die @var{Prozedur} wird jedes mal aufgerufen, wenn dar
@code{\markup}-Befehl, auf den sie sich auswirkt, ausgewertet wird.
Die @var{Prozedur} sollte nach einer bestimmten Bedingung fragen und
das @var{Beschriftung}-Argument ausführen (also setzen), wenn diese
Bedinung wahr ist.

Eine Anzahl von fertigen Prozeduren, um verschiedene Bedinungen zu testen,
werden bereitgestellt:

@quotation
@multitable {print-page-number-check-first-----} {should this page be printed-----}

@headitem  Prozedurbezeichnung      @tab  Getestete Bedinung

@item print-page-number-check-first @tab  sollte diese Seitenzahl gesetzt werden?
@item create-page-number-stencil    @tab  'print-page-numbers wahr?
@item print-all-headers             @tab  'print-all-headers wahr?
@item first-page                    @tab  erste Seite im Buch?
@item (on-page nmbr)                @tab  Seitenzahl = nmbr?
@item last-page                     @tab  letzte Seite im Buch?
@item not-first-page                @tab  nicht erste Seite im Buch?
@item part-first-page               @tab  erste Seite im book part?
@item part-last-page                @tab  letzte Seite im book part?
@item not-single-page               @tab  Seiten im book part > 1?

@end multitable
@end quotation

Das folgende Beispiel zentriert die Seitenzahlen unten auf jeder Seite.
Zuerst werden die Standardeinstellungen von @code{oddHeaderMarkup} und
@code{evenHeaderMarkup} entfernt, indem sie als @qq{Null}-Beschriftung
definiert werden.  Dann wird @code{oddFooterMarkup} mit zentrierter
Seitennummer neu definiert.  Schließlich erhält @code{evenFooterMarkup} 
die selbe Layoutdefinition wie @code{\oddFooterMarkup}:

@lilypond[papersize=a8,quote,verbatim,noragged-right]
\book {
  \paper {
    print-page-number = ##t
    print-first-page-number = ##t
    oddHeaderMarkup = \markup \null
    evenHeaderMarkup = \markup \null
    oddFooterMarkup = \markup {
      \fill-line {
        \if \should-print-page-number
        \fromproperty #'page:page-number-string
      }
    }
    evenFooterMarkup = \oddFooterMarkup
  }
  \score {
    \new Staff { s1 \break s1 \break s1 }
  }
}
@end lilypond

Verschiedene @code{\on-the-fly}-Bedingungen können mit dem Operator
@qq{UND} verknüpft werden, beispielsweise bestimmt

@example
  \if \on-first-page
  \if \on-last-page
  @{ \markup ... \fromproperty #'header: ... @}
@end example

@noindent
ob es sich um eine einzelne Seite bei der Ausgabe handelt.

@morerefs
Notationsreferenz:
@ref{Wie funktioniert die Titel-Umgebung?},
@ref{Standardlayout von book und Partitur Titelumgebungen}.

Installierte Dateien:
@file{../ly/titling-init.ly}.


@node Fußnoten erstellen
@subsection Fußnoten erstellen
@translationof Creating footnotes

Zwei Arten an Fußnoten können erstellt werden: automatische und
manuelle Fußnoten.

@menu
* Übersicht über Fußnoten::
* Automatische Fußnoten::
* Manuelle Fußnoten::
@end menu

@node Übersicht über Fußnoten
@unnumberedsubsubsec Übersicht über Fußnoten
@translationof Footnotes overview

Automatische Fußnoten erstellen aufsteigende Zahlenverweise, während
mit manuellen Fußnoten eigene angepasste Verweise erstellt werden
können.  Fußnoten werden normalerweise wie ein @code{\tweak}-Befehl
an Noten gehängt und können deshalb auch direkt mit den Grobs
(graphischen Objekten) verknüpft werden, die von den meisten
musikalischen Elementen und Postelementen erstellt werden.  In Fällen, wo
das nicht funktioniert (etwa bei Taktstrichen und Taktartänderungen, wo
die Grobs als Folge einer Eigenschaftsänderung erstellt werden), können
Fußnoten als einzelnstehendes musikalisches Ereigenis ersetllt werden,
das sich auf alle Grobs eines bestimmten Typs zu einer bestimmten Zeit
bezieht.

Der vollständige Befehl ist:

@example
\footnote @var{Zeichen} @var{Verschiebung} @var{Grob-Bezeichnung} @var{Fußnote}
@var{Noten}
@end example

Die Elemente sind folgende:

@table @var
@item
Zeichen
ist eine Beschriftung oder Zeichenkette, die das Fußnotenzeichen
angbit, welches für den Referenzpunkt als auch für die Fußnote
unten auf der Seite benützt wird.  Es kann ausgelassen werden
(oder durch @code{\default} ersetzt werden); in diesem Fall wird
eine aufsteigende Zahlenfolge erstellt.

@item Verschiebung (offset)
ist ein Zahlenpaar wie etwa @samp{#(2 . 1)}, das die X- und Y-Verschiebung
vom Referenzpunkt aus angibt, wo das Zeichen gesetzt werden soll.

@item Grob-Bezeichnung
gibt die Grob-Art an, der ein Fußnotenzeichen hinzugefügt werden soll
(wie etwa @samp{#'Flag}).  Wenn sie angegeben wird, wird der entsprechende
Grob als Referenzpunkt eingesetzt, auch wenn das referenzierte Element
nicht die @var{Noten} selber sind, sondern ein Grob, der durch sie
erstellt wird.  Das Element kann ausgelassen werden (oder durch
@code{\default} ersetzt werden); dann wird nur ein direkt erstellter Grob
mit Fußnote versehen.

@item Fußnote
Diese Beschriftung oder Zeichenkette bezeichnet den Fußnotentext, der
am unteren Seitenrand gesetzt werden soll.

@item Noten
Das ist das Element, ein musikalisches Ereignis oder eine Akkordkonstruktion
oder ein Post-Ereignis, das die Fußnote erhält.  Man kann es nicht auslassen,
aber man @emph{kann} es durch @code{\default} ersetzten.  In diesem Fall
wird die Fußnote aber nicht an einen bestimmten musikalischen Ausdruck
angehänt, sondern an einen zeitlichen Moment.  In diesem Fall muss man
zwingend die @var{Grob-Bezeichnung} angeben, um den Grob-Typ auszuwählen, auf
den sich die Fußnote bezieht (etwa @samp{#'TimeSignature}).
@end table

Wie auch mit @code{\tweak} muss dem @code{\footnote}-Befehl @code{-}
vorangestellt werde,n wenn er an ein Post-Ereignis oder eine
Artikulation angehängt werden soll, damit der Parser das Ergebnis
der vorherigen Note oder Pause zuordnen kann.


@node Automatische Fußnoten
@unnumberedsubsubsec Automatische Fußnoten
@translationof Automatic footnotes

@cindex Fußnoten, automatisch

Automatische Fußnoten haben vier Argumente: die @var{(x . y)}-Position des Indikators,
die optionale @var{Grob-Bezeichnung}, die die Anmerkung erhalten soll,
die @var{Fußnote}-Beschriftung, die den Inhalt der Fußnote enthält, und
natürlich die @var{Noten}, welche mit einer Fußnote versehen werden sollen.

Der Befehl @code{\footnote} muss @emph{vor} dem Grob geschrieben
werden, auf den sich die Fußnote bezieht.

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote #'(0.5 . -2)
      \markup { Die erste Note }
    a'4 b8
    \footnote #'(0.5 . 1)
      \markup { Die dritte Note } Flag
    e\noBeam c4 d4
  }
}
@end lilypond

Noten in Akkorden stellen keine Schwierigkeit dar:

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    <
    \footnote #'(1 . -1.25) "Hier ein C" c
    \footnote #'(2 . -0.25) \markup { \italic "Ein Es" } es
    \footnote #'(2 . 3) \markup { \bold "Das ist ein G" } g
    >1
  }
}
@end lilypond

@warning {Wenn Fußnoten die selbe vertikale Position haben, werden
sie von oben nach unten nummeriert.}

Hier noch einige Beispiele von Grobs, die mit Fußnoten
versehen sind, wobei auch die Position des Fußnotentextes relativ zu
Tagline und Copyright gezeigt wird.

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { copyright = \markup { "Copyright 1970" } }
  \relative {
    a'4-\footnote #'(-3 . 0) \markup { \bold Forte } \f
    -\footnote #'(0 . 1.5) \markup { Ein Bogen } (
    b8)-\footnote #'(0 . -2) \markup { Balken } [ e]
    \single\footnote #'(1 . -1)
      \markup  { \teeny { Das ist ein Hals } } Stem
    c4
    \single\footnote #'(0 . 0.5)
      \markup \italic { Ein warnendes Versetzungszeichen } AccidentalCautionary
    \footnote #'(1 . 1) "Die Note selber"
    dis?4-\footnote #'(0.5 . -0.5) \markup \italic { langsamer werden }
         _"rit."
  }
}
@end lilypond

Für eine @code{\markup}-Beschriftung auf oberster Ebene braucht man
den Befehl @code{\footnote}:

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \markup { \footnote "Eine einfache Melodie" \italic "Von mir" }
  \relative {
    a'4 b8 e c4 d
  }
}
@end lilypond


@node Manuelle Fußnoten
@unnumberedsubsubsec Manuelle Fußnoten
@translationof Manual footnotes

@cindex Fußnoten, manuell

Manuell erstellte Fußnoten haben ein zusätzliches erstes Argument
@var{Zeichen}, das das Fußnotenzeichen erstellt.  Im Gegensatz zu
automatisch erstellten Fußnotenzeichen erscheinen sie nicht unbedingt
vor dem Fußnotentext unten auf der Seite -- das Herstellen eines visualen
Zusammenhanges ist dem Setzer überlassen.  LilyPond stellt nur ischer, dass
der zugehörige Text unten auf der selben Seite erscheint.

Davon abgesehen ist die Benutzung identisch mit automatischen Fußnoten.

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    \footnote
          "1" #'(0.5 . -2)
          \markup { \italic "1. Die erste Note" }
    a'4
    b8
    \footnote
          \markup { \bold "2" } #'(0.5 . 1)
          "2. Die zweite Note"
    e
    c4
    d-\footnote "3" #'(0.5 . -1) "3. Piano" \p
  }
}
@end lilypond

Fußnoten für Akkordnoten werden wie folgt notiert:

@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative c' {
    <
    \footnote "1" #'(1 . -1.25) "1. C" c
    \footnote
       \markup { \bold "b" } #'(2 . -0.25) "b. E-flat" es
    \footnote "3" #'(2 . 3) \markup { \italic "iii. G" } g
    >1
  }
}
@end lilypond

@warning {Wenn Fußnoten die selbe vertikale Position haben, werden
sie von oben nach unten nummeriert.}

Hier einige Beispiele manueller Fußnoten, die auch die relative
Position der Fußnotentexte zu Tagline und Copyright anzeigen:

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \relative {
    a'4-\footnote
      \markup { \teeny 1 } #'(-3 . 0)
      \markup { 1. \bold Forte } \f
    -\footnote
      \markup { \teeny b } #'(0 . 1.5)
      \markup { b. Ein Bogen } (
    b8)-\footnote
      \markup { \teeny 3 } #'(0 . -2)
      \markup { 3. Balken } [
    e]
    \single\footnote
      \markup { 4 } #'(1 . -1)
      \markup  { \bold 4. { Das ist ein Hals } } Stem
    c4
    \single\footnote
      \markup \concat \teeny { "sharp (v)" }
          #'(0 . 0.5)
      \markup \italic { v. Ein warndendes Versetzungszeichen } AccidentalCautionary
    dis?4-\footnote
      \markup \concat \teeny { "a" } #'(0.5 . -0.5)
      \markup \italic { a. Langsamer werden } _"rit."
    \footnote
      \markup { \teeny \musicglyph "rests.4" }
          #'(1.5 . -0.25)
      \markup { \null } \breathe
  }
}
@end lilypond

Eine @code{\markup}-Beschriftung der höchsten Ebene wird wie folgt
annotiert:

@c KEEP LY
@lilypond[verbatim,quote,ragged-right,papersize=a8]
\book {
  \header { tagline = ##f }
  \markup { "Eine einfache Melodie" \footnote "*" \italic "* Von mir" }
  \relative {
    a'4 b8 e c4 d4
  }
}
@end lilypond

@morerefs
Handbuch zum Lernen:
@rlearning{Objekte und Schnittstellen}.

Notationsreferenz:
@ref{Erklärungen in Ballonform},
@ref{Seitenlayout},
@ref{Textartige Zeichen},
@ref{Textarten},
@ref{Titel}.

Referenz der Interna:
@rinternals{FootnoteEvent},
@rinternals{Footnote},
@rinternals{Footnote_engraver}.

@knownissues
Mehrere Fußnoten auf einer Seite können ausschließlich übereinander
gedruckt werden und nicht auf der gleiche Zeile gesetzt werden.
Fußnoten können nicht an @code{MultiMeasureRests} (mehrtaktige Pause)
angehängt werden und können mit @code{Staff}-(Notensystem)-,
@code{\markup}-(Beschriftungs)-Objekten und anderen Fußnoten
zusammenstoßen.  Wenn man den manuellen Fußnotenbefehl einsetzt,
braucht man in der @code{\paper}-Umgebung den Eintrag
@code{footnote-auto-number = ##f}.


@node Verweis auf die Seitenzahlen
@subsection Verweis auf die Seitenzahlen
@translationof Reference to page numbers

Eine bestimmte Stelle der Partitur kann mit einem @code{\label}-Befehl
markiert werden, sowohl auf oberster Ebene als auch innerhalb eines
musikalischen Ausdrucks.  Auf diese Marke kann dann verwiesen werden,
um die Seitenzahl zu erhalten, auf der die Marke vorkommt.  Der
Verweis wird mit dem Befehl @code{\page-ref} gefordert (innerhalb
von @code{\markup}).

@c KEEP LY
@lilypond[verbatim]
\header { tagline = ##f }
\book {
  \label #'ErstePartitur
  \score {
    {
      c'1
      \pageBreak \mark A \label #'ZeichenA
      c'1
    }
  }
  \markup { Die erste Partitur fängt auf
            Seite \page-ref #'ErstePartitur "0" "?" an.}
  \markup { Zeichen A befindet sich auf Seite
            \concat { \page-ref #'ZeichenA "0" "?" . } }
}
@end lilypond

Der @code{\page-ref}-Textbeschriftungsbefehl braucht drei Argumente:

@enumerate

@item die Marke, ein Scheme-Symbol, etwa @code{#'ErstePartitur},
@item eine Beschriftung, die als Platzhalter benutzt wird, um die Breite des Verweisen zu schätzen,
@item eine Beschriftung, die anstelle der Seitenzahl gesetzt wird, wenn die Marke unbekannt ist.
@end enumerate

Der Grund, warum ein Platzhalter benötigt wird, ist dass zu dem Zeitpunkt,
an dem die Textbeschriftungen ausgewertet werden, noch keine Seitenumbrüche
vorgenommen wurden und die Seitenzahlen deshalb noch nicht bekannt sind.
Um hier ein Problem zu vermeiden, wird die eigentliche Auswertung der
Textbeschriftung erst später ausgeführt, die Größe des Textes muss aber
schon vorher bekannt sein.  Die Größe wird mithilfe des Platzhalters
bestimmt.  Wenn eine Partitur zwischen 10 und 99 Seiten hat, kann man
"00" schreiben, also eine zweistellige Zahl.

@code{\label}
@code{\page-ref}

@predefined
@funindex \label,
@funindex \page-ref.
@endpredefined


@node Inhaltsverzeichnis
@subsection Inhaltsverzeichnis
@translationof Table of contents

Ein Inhaltsverzeichnis kann eingefügt werden mit dem Befehl
@code{\markuplist \table-of-contents}.  Die Elemente, die im
Inhaltsverzeichnis aufgelistet werden sollen, werden mit dem
@code{\tocItem}-Befehl markiert, welches sowohl auf höchster
Ebene als auch in einem musikalischen Ausdruck verwendet werden
kann.

@verbatim
\markuplist \table-of-contents
\pageBreak

\tocItem \markup "Erste Partitur"
\score {
  {
    c'4  % ...
    \tocItem \markup "Ein bestimmter Punkt innerhalb der ersten Partitur"
    d'4  % ...
  }
}

\tocItem \markup "zweite Partitur"
\score {
  {
    e'4 % ...
  }
}
@end verbatim

Die Beschriftungen, die benutzt werden um das Inhaltsverzeichnis
zu formatieren, sind in der @code{\paper}-Umgebung definiert.
Die Standardformatierungselemente sind @code{tocTitleMarkup}
um die Überschrift zu formatieren und @code{tocItemMarkup} um
die einzelnen Inhaltselemente zu formatieren, bestehend aus
dem Titelelement und einer Seitenzahl.  Die Variablen können
durch den Benutzer geändert werden:

@verbatim
\paper {
  %% Übersetzung der Inhaltsverzeichnisüberschrift nach französisch:
  tocTitleMarkup = \markup \huge \column {
    \fill-line { \null "Table des matières" \null }
    \hspace #1
  }
  %% hier größere Schriftarten
  tocItemMarkup = \markup \large \fill-line {
    \fromproperty #'toc:text \fromproperty #'toc:page
  }
}
@end verbatim

Die Inhaltsverzeichniselemente Text und Seitenzahl werden
in der Definition von @code{tocItemMarkup} aufgerufen mit
@code{#'toc:text} und @code{#'toc:page}.

Neue Befehle und Beschriftungen können auch definiert werden,
um eigene Inhaltsverzeichnisse zu gestalten:

@itemize

@item zuerst muss eine neue Beschriftungsvariable in der
@code{\paper}-Umgebung definiert werden

@item dann muss die musikalische Funktion definiert werden, die
ein Element zum Inhaltsverzeichnis hinzufügt, indem die neue
Variable benutzt wird.

@end itemize

Das folgende Beispiel definiert einen neuen Stil um Akt-Bezeichnungen
einer Oper in das Inhaltsverzeichnis aufzunehmen:

@verbatim
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct =
#(define-music-function (text) (markup?)
   (add-toc-item! 'tocActMarkup text))
@end verbatim

@lilypond[line-width=10.0\cm]
\header { tagline = ##f }
\paper {
  tocActMarkup = \markup \large \column {
    \hspace #1
    \fill-line { \null \italic \fromproperty #'toc:text \null }
    \hspace #1
  }
}

tocAct =
#(define-music-function (text) (markup?)
   (add-toc-item! 'tocActMarkup text))

\book {
  \markuplist \table-of-contents
  \tocAct \markup { Atto Primo }
  \tocItem \markup { Coro. Viva il nostro Alcide }
  \tocItem \markup { Cesare. Presti omai l'Egizzia terra }
  \tocAct \markup { Atto Secondo }
  \tocItem \markup { Sinfonia }
  \tocItem \markup { Cleopatra. V'adoro, pupille, saette d'Amore }
  \markup \null
}
@end lilypond

Die Zeile zwischen dem Inhalt und der Seitenzahl kann mit einer gepunkteten
Linie gefüllt werden:

@lilypond[verbatim,quote,line-width=10.0\cm]
\header { tagline = ##f }
\paper {
  tocItemMarkup = \tocItemWithDotsMarkup
}

\book {
  \markuplist \table-of-contents
  \tocItem \markup { Allegro }
  \tocItem \markup { Largo }
  \markup \null
}
@end lilypond


@morerefs
Installierte Dateien:
@file{ly/toc-init.ly}.

@funindex \table-of-contents
@funindex \tocItem

@predefined
@code{\table-of-contents},
@code{\tocItem}.
@endpredefined


@node Arbeiten an Eingabe-Dateien
@section Arbeiten an Eingabe-Dateien
@translationof Working with input files

@menu
* LilyPond-Dateien einfügen::
* Verschiedene Editionen aus einer Quelldatei::
* Sonderzeichen::
@end menu


@node LilyPond-Dateien einfügen
@subsection LilyPond-Dateien einfügen
@translationof Including LilyPond files

@funindex \include
@cindex einfügen  von Dateien
@cindex Dateien einfügen

Ein größeres Projekt kann in einzelne Dateien aufgeteilt werden.
Um eine andere Datei einzubinden, kann der Befehl

@example
\include "andereDatei.ly"
@end example

@noindent
benutzt werden.

Die Zeile @code{\include "andereDatei.ly"} benimmt sich genauso,
also ob der Inhalt der Datei @file{andereDatei.ly} komplett in die
Hauptdatei eingefügt werden würde.  So kann man für ein größeres
Projekt die einzelnen Stimmen der Instrumente getrennt notieren
und sie dann in einer Partitur-Datei benutzen.  Meistens werden
in den eingefügten Dateien einige Variablen definiert, die dann
auch in der Hauptdatei eingesetzt werden können.  Mit Marken (Tags)
gekennzeichnete Abschnitte können eingesetzt werden, um die
entsprechenden Noten etc. an verschiedenen Stellen in der Datei
zur Verfügung zu stellen. Siehe auch @ref{Verschiedene Editionen aus einer Quelldatei}.

Auf Dateien im aktuellen Verzeichnis kann einfach mit dem Dateinamen
nach dem @code{\include}-Befehl verwiesen werden.  Dateien an anderen
Stellen können eingebunden werden, indem entweder ein vollständiger
Pfad oder ein relativer Pfad zu der Datei angegeben wird.  Hierbei
sollten die für UNIX typischen Schrägstriche (/) und nicht die
rückwärtsgeneigten von Windows (\) verwendet werden, um die Verzeichnisse
zu trennen.  Wenn etwa die Datei @file{kram.ly} ein Verzeichnis
höher liegt als das aktuelle Verzeichnis, sollte der Befehl so
aussehen:

@example
\include "../kram.ly"
@end example

@noindent
Wenn die Orchesterstimmen andererseits in einem Unterordner mit
der Bezeichnung @code{stimmen} liegen, sieht er folgendermaßen
aus:

@example
\include "stimmen/VI.ly"
\include "stimmen/VII.ly"
... etc
@end example

Dateien, die eingebunden werden sollen, können selber auch wiederum
ein @code{\include} enthalten.  Diese Einbindung zweiter Ebene
werden erst interpretiert, wenn sie sich in der Hauptdatei befinden,
sodass die Pfadangaben hier nicht relativ zur eingebundenen Datei,
sondern relativ zur Hauptdatei gesetzt werden müssen.  Dieses Verhalten
kann jedoch auch verändert werden, indem man lilypond die Option
@option{-drelative-includes} auf der Kommandozeile zuweist (oder indem
man den Befehl @code{#(ly:set-option 'relative-includes #t)} an den
Beginn der Quelldatei schreibt).  Mit @code{relative-includes} wird
der Pfad jedes @code{\include}-Befehls als relativ zu der Datei angenommen,
in der sich der Befehl befindet.  Dieses Verhalten wird empfohlen und wird
in zukünftigen Versionen von LilyPond den Standard darstellen.

Dateien können auch aus einem Verzeichnis eingebunden werden,
dass im Suchpfad von LilyPond liegt.  Hierzu muss auf der
Kommandozeile das entsprechende Verzeichnis angegeben werden
und die Dateien, die eingebunden werden, müssen nur mit ihrem Namen
notiert sein.  Wenn etwa die Datei @file{Haupt.ly} kompiliert
werden soll, die Dateien aus dem Unterverzeichnis @file{stimmen}
einbindet, müssen sie sich im Verzeichnis von @file{Haupt.ly}
befinden und dann LilyPond folgendermaßen aufrufen:

@example
lilypond --include=stimmen Haupt.ly
@end example

@noindent
In @file{Haupt.ly} steht:

@example
\include "VI.ly"
\include "VII.ly"
... usw.
@end example

Dateien, die in vielen Partituren verwendet werden sollen, können
im LilyPond-Verzeichnis @file{../ly} gespeichert werden.  (Die
Stelle, an der dieses Verzeichnis sich befindet, hängt vom Betriebssystem
ab, siehe hierzu @rlearning{Mehr Information}).  Dateien
in diesem Verzeichnis können einfach mit ihrem Namen eingefügt werden.
So werden auch die Sprachdateien wie etwa @file{deutsch.ly} eingefügt.

LilyPond lädt eine Anzahl an Dateien, wenn das Programm aufgerufen wird.
Diese Dateien sind für den Benutzer nicht ersichtlich, aber die Dateien
können identifiziert werden, indem LilyPond auf der Kommandozeile mit
Option aufgerufen wird: @code{lilypond --verbose}.  Hiermit wird
neben anderer Information auch eine Liste von Pfaden und Dateien
aufgeführt, die LilyPond benutzt.  Die wichtigeren Dateien werden
im Abschnitt @rlearning{Mehr Information} besprochen.
Diese Dateien können verändert werden, aber Änderungen gehen verloren,
wenn eine neue LilyPond-Version installiert wird.

Einige einfache Beispiele, die die Benutzung von @code{\include} demonstrieren,
sind dargestellt in
@rlearning{Partituren und Stimmen}.

@morerefs
Handbuch zum Lernen:
@rlearning{Mehr Information},
@rlearning{Partituren und Stimmen}.

@knownissues
Wenn eine Datei eingebunden wird, deren Name einer Datei aus
dem Installationsverzeichnis von LilyPond entspricht, wird die
installierte Datei anstelle der eigenen verwendet.


@node Verschiedene Editionen aus einer Quelldatei
@subsection Verschiedene Editionen aus einer Quelldatei
@translationof Different editions from one source

Es gibt verschiedene Funktionen, die es möglich machen, unterschiedliche
Versionen einer Partitur aus der gleichen Quelldatei zu produzieren.
Variablen werden am besten eingesetzt, wenn es darum geht, längere
Notenpassagen und/oder Anmerkungen/Textmarken miteinander auf
verschiedene Weise zu kombinieren.  Tag-Marken dagegen werden am
besten eingesetzt, wenn eine von mehreren kurzen alternativen
Notenabschnitten ausgewählt werden soll und können auch eingesetzt
werden, um Musikabschnitte an unterschiedlichen Stellen zusammenzufügen.  

Egal welche Methode am
Ende eingesetzt wird: Es erleichtert die Arbeit in jedem Fall, wenn
die eigentlichen Noten und die Struktur der Partitur voneinander
getrennt notiert werden -- so kann die Struktur geändert werden,
ohne dass man Änderungen an den Noten vornehmen muss.

@menu
* Variablen benutzen::
* Marken benutzen::
* Globale Einstellungen benutzen::
@end menu

@node Variablen benutzen
@unnumberedsubsubsec Variablen benutzen
@translationof Using variables

@cindex Variablen, Benutzung

Wenn Notenabschnitt in Variablen definiert werden, können sie
an unterschiedlichen Stellen in der Partitur eingesetzt werden,
siehe auch @rlearning{Stücke durch Variablen organisieren}.  Zum
Beispiel enthält eine Vokalpartitur für ein @notation{a cappella}
Stück oft einen Klavierauszug, der das Einüben einfacher macht.
Der Klavierauszug enthält die gleichen Noten, sodass man sie nur
einmal notieren muss.  Noten aus zwei Variablen können auf einem
System kombiniert werden, siehe @ref{Automatische Kombination von Stimmen}.
Hier ein Beispiel:

@lilypond[verbatim,quote]
sopranoMusic = \relative { a'4 b c b8( a) }
altoMusic = \relative { e'4 e e f }
tenorMusic = \relative { c'4 b e d8( c) }
bassMusic = \relative { a4 gis a d, }
allLyrics = \lyricmode {King of glo -- ry }
<<
  \new Staff = "Soprano" \sopranoMusic
  \new Lyrics \allLyrics
  \new Staff = "Alto" \altoMusic
  \new Lyrics \allLyrics
  \new Staff = "Tenor" {
    \clef "treble_8"
    \tenorMusic
  }
  \new Lyrics \allLyrics
  \new Staff = "Bass" {
    \clef "bass"
    \bassMusic
  }
  \new Lyrics \allLyrics
  \new PianoStaff <<
    \new Staff = "RH" {
      \set Staff.printPartCombineTexts = ##f
      \partCombine
      \sopranoMusic
      \altoMusic
    }
    \new Staff = "LH" {
      \set Staff.printPartCombineTexts = ##f
      \clef "bass"
      \partCombine
      \tenorMusic
      \bassMusic
    }
  >>
>>
@end lilypond

Unterschiedliche Partituren, die entweder nur den Chor oder das
Klavier zeigen, können produziert werden, indem die Struktur
verändert wird; die Noten müssen dazu nicht verändert werden.

Für längere Partituren können Variablen in eigene Dateien notiert
werden, die dann eingebunden werden, siehe @ref{LilyPond-Dateien einfügen}.


@node Marken benutzen
@unnumberedsubsubsec Marken benutzen
@translationof Using tags

@cindex Tag
@cindex Marke
@cindex markierte Noten entfernen
@cindex markierte Noten behalten
@cindex in markierte Noten einfügen

@funindex \tag
@funindex \keepWithTag
@funindex \removeWithTag
@funindex \pushToTag
@funindex \appendToTag
@funindex tag
@funindex keepWithTag
@funindex removeWithTag


Der @code{\tag #'@var{TeilA}}-Befehl markiert einen musikalischen
Ausdruck mit der Bezeichnung @var{TeilA}.  Ausdrücke, die auf diese
Weise markiert werden, können mit ihrer Bezeichnung später ausgewählt
bzw. ausgefiltert werden.  Das geschieht mit den Befehlen
@code{\keepWithTag #'@var{Bezeichnung}} bzw. @code{\removeWithTag #'@var{Bezeichnung}}.
Die Wirkung dieser Filter auf die markierten Notenabschnitte ist
wie folgt:

@multitable @columnfractions .5 .5

@headitem Filter
  @tab Resultat

@item
Markierte Noten mit vorgesetztem @code{\keepWithTag #'@var{Bezeichnung}}
  @tab Unmarkierte Noten und Noten mit der Marke @var{Bezeichnung} werden
  gesetzt, Noten mit einer anderen Marke werden nicht angezeigt.

@item
Markierte Noten mit vorgesetztem @code{\removeWithTag #'@var{Bezeichnung}}
  @tab Unmarkierte Noten und Noten mit einer anderen Marke als
  @var{Bezeichnung} wird angezeigt, Noten markiert mit @var{Bezeichnung}
  werden nicht angezeigt.

@item
Markierte Noten, weder mit vorgesetztem @code{\keepWithTag} noch
@code{\removeWithTag}
  @tab Alle markierten und unmarkierten Noten werden angezeigt.

@end multitable

Die Argumente der Befehle @code{\tag}, @code{\keepWithTag} und
@code{\removeWithTag} sollten ein Symbol sein (wie etwa
@code{#'score} oder @code{#'part}), gefolgt von einem musikalischen
Ausdruck.

Im folgenden Beispiel erscheinen zwei Versionen der Noten, eine
zeigt Triller in normaler Notation, die andere zeigt sie ausgeschrieben:

@lilypond[verbatim,quote]
music = \relative {
  g'8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand { \repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \keepWithTag #'trills \music
}
\score {
  \keepWithTag #'expand \music
}
@end lilypond

@noindent
Entsprechend können auch Abschnitte ausgeschlossen werden; das
erfordert manchmal weniger Schreibarbeit:

@lilypond[verbatim,quote]
music = \relative {
  g'8. c32 d
  \tag #'trills { d8.\trill }
  \tag #'expand {\repeat unfold 3 { e32 d } }
  c32 d
 }

\score {
  \removeWithTag #'expand
  \music
}
\score {
  \removeWithTag #'trills
  \music
}
@end lilypond

Marken können auch auf Artikulationen, Text usw angewendet werden,
indem man ihnen

@example
-\tag #'@var{your-tag}
@end example

@noindent
voranstellt (jedoch nach der Note, an die sie gebunden sind).  Mit
diesem Code etwa könnte man entweder Fingersatz oder aber einen
Text ausgeben:

@example
c1-\tag #'finger ^4
c1-\tag #'warn ^"Achtung!"
@end example

Mehrfache Marken können mithilfe von mehreren @code{\tag}-Befehlen
notiert werden:

@lilypond[quote,verbatim]
music = \relative c'' {
  \tag #'a \tag #'both { a4 a a a }
  \tag #'b \tag #'both { b4 b b b }
}
<<
\keepWithTag #'a \music
\keepWithTag #'b \music
\keepWithTag #'both \music
>>
@end lilypond

Mehrfache @code{\removeWithTag}-Filter können auf einen
musikalischen Ausdruck angewendet werden, um mehrere unterschiedliche
markierte Abschnitte aus dem Druckbild zu entfernen.

@lilypond[verbatim,quote]
music = \relative c'' {
\tag #'A { a4 a a a }
\tag #'B { b4 b b b }
\tag #'C { c4 c c c }
\tag #'D { d4 d d d }
}
{
\removeWithTag #'B
\removeWithTag #'C
\music
}
@end lilypond

Zwei oder mehr @code{\keepWithTag}-Filter in einem musikalischen
Ausdruck bewirken, dass @emph{alle} markierten Abschnitte entfernt
werden, weil der erste Befehl alle markierten Abschnitt außer dem
im Befehl genannten wegfiltert und der zweite Befehl dann auch diesen
eben genannten zusätzlich entfernt.

Manchmal will man Noten an einem bestimmen Platz in existierenden
Noten einfügen.  Dafür kann entweder @code{\pushToTag} oder
@code{\appendToTag} benutzt werden, um Material hinter bzw. vor den
Elementen (@code{elements}) der existierenden Noten einzufügen.  Nicht
alle musikalischen Konstruktionen haben Elemente, aber sequentielle und
simultane Noten sind ziemlich gute Kandidaten:

@lilypond[verbatim,quote]
test = { \tag #'here { \tag #'here <<c''>> } }

{
  \pushToTag #'here c'
  \pushToTag #'here e'
  \pushToTag #'here g' \test
  \appendToTag #'here c'
  \appendToTag #'here e'
  \appendToTag #'here g' \test
}
@end lilypond

Beide Befehle erhalten einen Tag, das Material, das bei jedem Auftreten
des Tags eingefügt werden soll und den Ausdruck, der mit dem Tag versehen
ist.  Der Befehl stellt sicher, dass alle Änderungen kopiert werden, sodass
das ursprüngliche @code{\test} seine Bedeutung behält.

@morerefs
Handbuch zum Lernen:
@rlearning{Stücke durch Variablen organisieren}.

Notationsreferenz:
@ref{Automatische Kombination von Stimmen},
@ref{LilyPond-Dateien einfügen}.


@ignore
@c This warning is more general than this placement implies.
@c Rests are not merged whether or not they come from tagged sections.
@c Should be deleted?  -td

@knownissues

Multiple rests are not merged if you create a score with more
than one tagged section at the same place.

@end ignore


@node Globale Einstellungen benutzen
@unnumberedsubsubsec Globale Einstellungen benutzen
@translationof Using global settings

@funindex include-settings

Man kann globale Einstellungen aus einer externen Datei einfügen:

@example
lilypond -dinclude-settings=MY_SETTINGS.ly MY_SCORE.ly
@end example


Einstellungsgruppen, wie etwa Seitengröße, Schriftart oder Schriftschnitt, können
in eigenen Dateien gespeichert werden.  Das ermöglicht es, aus der gleichen
Partitur unterschiedliche Editionen zu erstellen bzw. Standardeinstellungen
für eine ganze Anzahl von Partituren wiederzuverwenden, indem man einfach
die entsprechende Einstellungsdatei angibt.

Diese Technik funktioniert auch gut für Formatvorlagen, wie
in @rlearning{Formatvorlagen} behandelt.

@morerefs
Handbuch zum Lernen:
@rlearning{Stücke durch Variablen organisieren},
@rlearning{Formatvorlagen}.

Notationsreferenz:
@ref{LilyPond-Dateien einfügen}.


@node Sonderzeichen
@subsection Sonderzeichen
@translationof Special characters

@cindex Sonderzeichen
@cindex Nicht-ASCII-Zeichen

@menu
* Zeichenkodierung::
* Unicode::
* ASCII-Aliase::
@end menu


@node Zeichenkodierung
@unnumberedsubsubsec Zeichenkodierung
@translationof Text encoding


@cindex UTF-8

LilyPond benutzt alle Zeichen, die durch das Unicode-Konsortium
und ISO/IEC 10646 definiert sind.  Hiermit wird den Zeichen
fast aller Schriftsysteme der Welt ein eindeutiger Name und ein
Code-Punkt zugewiesen, mit dem sie identifizierbar sind.  Unicode
kann mit mehreren Zeichenkodierungen verwirklicht werden.  LilyPond
benutzt die UTF-8-Kodierung (UTF = Unicode Transformation Format),
in der die normalen Zeichen des lateinischen Alphabets mit einem
Byte dargestellt werden, während alle anderen Zeichen zwischen
zwei und vier Byte Länge haben.

Das Aussehen des Zeichens wird bestimmt durch die gerade benutzte
Schriftart (engl. font).  In einer Schriftartdatei werden die
Nummern der Unicode-Zeichen einem bestimmten Glyphen zugeordnet.
LilyPond verwendet die Pango-Bibliothek um mehrsprachige Texte
und komplexe Skripte korrekt zu setzen.

LilyPond verändert die Kodierung der Eingabedatei nicht.  Das heißt,
dass jeder Text -- Überschriften, Gesangstext, Spielanweisungen etc. --
der nicht nur aus ASCII-Zeichen besteht, in UTF-8 kodiert sein
musst.  Am einfachsten geht das, indem man einen Texteditor
einsetzt, der mit Unicode-Zeichen umgehen kann.  Die meisten
modernen weit verbreiteten Editoren besitzen heute UTF-8-Unterstützung,
wie etwa vim, Emacs, jEdit oder GEdit.  Alle MS Windows-Systeme
nach NT benutzen Unicode intern, sodass sogar Notepad Dateien
in UTF-8 lesen und speichern kann.  Ein Editor mit mehr
Funktionen unter Windows ist BabelPad oder Notepad++.

Wenn eine LilyPond-Eingabedatei nicht-ASCII-Zeichen enthält
und nicht in UTF-8 gespeichert ist, gibt es folgende Fehlermeldung:

@example
FT_Get_Glyph_Name () error: invalid argument
@end example

Heir ein Beispiel mit Kyrilliza, hebräischem und portugiesischem Text:

@lilypond[quote]
%c No verbatim here as the code does not display correctly in PDF
% Font settings for Cyrillic and Hebrew
% Linux Libertine fonts contain Cyrillic and Hebrew glyphs.
\paper {
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O,serif"
     #:sans "Linux Biolinum O,sans-serif"
     #:typewriter "Linux Libertine Mono O,monospace"
   ))
}

% Cyrillic
bulgarian = \lyricmode {
  Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
}

% Hebrew
hebrew = \lyricmode {
  זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
}

% Portuguese
portuguese = \lyricmode {
  à vo -- cê uma can -- ção legal
}

\relative {
  c'2 d e f g f e
}
\addlyrics { \bulgarian }
\addlyrics { \hebrew }
\addlyrics { \portuguese }
@end lilypond


@node Unicode
@unnumberedsubsubsec Unicode
@translationof Unicode

@cindex Unicode

Um einen einzelnen Buchstaben zu notieren, für den die Unicode-Ziffernfolge
bekannt ist, der aber nicht auf der Tastatur zu finden ist, kann
der Befehl @code{\char ##xhhhh} oder @code{\char #dddd} innerhalb einer
@code{\markup}-Umgebung benutzt werden.  Hierbei bedeutet @code{hhhh} die
hexadezimale Zahl und @code{ddd} die entsprechende dezimale Zahl
für das erforderliche Zeichen.  Nullen zu Beginn können ausgelassen werden,
aber normalerweise werden alle vier Zeichen der hexadezimalen Notation
notiert. (Achten Sie darauf, dass Sie @emph{nicht} UTF-8-Codepunkte
einsetzen, weil UTF-8 zusätzliche Bits enthält, die die Nummer der Oktets bezeichnet.)  Unicode-Tabellen und ein Verzeichnis der Zeichenbezeichnungen
mit einer hexadezimalen Verweiszahl finden sich auf der Internetseite
des Unicode Consortiums: @uref{https://www.unicode.org/}.

Mit @code{\char ##x03BE} und @code{\char #958} wird
beispielsweise das Unicode-Zeichen U+03BE notiert, welches die
Unicode-Bezeichnung @qq{Greek Small Letter Xi} hat.

Alle existierenden
Unicode-Zeichen können auf diese Weise notiert werden, und wenn für alle
Zeichen dieses Format angewandt wird, muss die Datei nicht im utf-8-Format
gespeichert werden.  Es muss natürlich auch noch eine Schriftart auf
dem System installiert sein, die die notierten Zeichen darstellen kann.

Das nächste Beispiel zeigt, wie Unicode-Zeichen an vier Stellen mit dem
hexadezimalen Code notiert werden: in einem Übungszeichen, als Artikulationszeichen,
im Gesangstext und als normaler Text außerhalb der Partitur.

@lilypond[quote,verbatim]
\score {
  \relative {
    c''1 \mark \markup { \char ##x03A8 }
    c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
  }
  \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
}
\markup { "Copyright 2008--2022" \char ##x00A9 }
@end lilypond

@cindex Copyright-Zeichen

Um das Copyright-Zeichen zu notieren, kann folgender Code eingesetzt werden:

@example
\header @{
  copyright = \markup @{ \char ##x00A9 "2008" @}
@}
@end example


@node ASCII-Aliase
@unnumberedsubsubsec ASCII-Aliase
@translationof ASCII aliases

Eine Liste von ASCII-Befehlen für Sonderzeichen kann
eingefügt werden:

@lilypond[quote,verbatim]
\paper {
  #(include-special-characters)
}

\markup "&flqq; &ndash; &OE;uvre incomplète&hellip; &frqq;"

\score {
  \new Staff { \repeat unfold 9 a'4 }
  \addlyrics {
    This is al -- so wor -- kin'~in ly -- rics: &ndash;_&OE;&hellip;
  }
}

\markup \column {
  "The replacement can be disabled:"
  "&ndash; &OE; &hellip;"
  \override #'(replacement-alist . ()) "&ndash; &OE; &hellip;"
}
@end lilypond

Man kann auch eigen Aliase erstellen, entweder global:

@lilypond[quote,verbatim]
\paper {
  #(add-text-replacements!
    '(("100" . "hundred")
      ("dpi" . "dots per inch")))
}
\markup "A 100 dpi."
@end lilypond

@noindent
oder lokal:

@lilypond[quote,verbatim]
\markup \replace #'(("100" . "hundred")
                    ("dpi" . "dots per inch")) "A 100 dpi."
@end lilypond

@morerefs
Notationsreferenz:
@ref{Liste der Sonderzeichen}.

Installierte Dateien:
@file{ly/text-replacements.ly}.


@node Ausgabe kontrollieren
@section Ausgabe kontrollieren
@translationof Controlling output

@menu
* Notationsfragmente extrahieren::
* Korrigierte Musik überspringen::
* Alternative Ausgabeformate::
* Die Notationsschriftart verändern::
@end menu


@node Notationsfragmente extrahieren
@subsection Notationsfragmente extrahieren
@translationof Extracting fragments of music

Es ist möglich, kleine Abschnitte einer großen Partitur direkt aus der
Quelldatei zu erzeugen.  Das kann damit verglichen werden, dass man
mit der Schere bestimmte Regionen ausschneidet.

Es wird erreicht, indem man die Takte, die ausgeschnitten werden sollen
(engl. to clip = ausschneiden), extra definiert.  Mit folgender
Definition beispielsweise

@verbatim
\layout {
  clip-regions
  = #(list
      (cons
       (make-rhythmic-location 5 1 2)
       (make-rhythmic-location 7 3 4)))
}
@end verbatim

@noindent
wird ein Fragment ausgeschnitten, dass auf der Mitte des fünften Taktes
beginnt und im siebten Takt endet.  Die Bedeutung von @code{5 1 2} ist:
nach einer Halben in Takt fünf, @code{7 3 4} heißt: nach drei Vierteln
in Takt 7.

Weitere Bereiche, die ausgeschnitten werden sollen, können definiert
werden, indem mehrere derartige Paare definiert werden.

Um diese Funktion auch nutzen zu können, muss LilyPond mit dem
Parameter @option{-dclip-systems} aufgerufen werden.  Die Schnipsel
werden als EPS ausgegeben und dann zu PDF und PNG konvertiert, wenn
diese Formate auch als Parameter angegeben werden.

Zu mehr Information über Ausgabeformate siehe @rprogram{lilypond aufrufen}.


@node Korrigierte Musik überspringen
@subsection Korrigierte Musik überspringen
@translationof Skipping corrected music


@funindex skipTypesetting
@funindex showFirstLength
@funindex showLastLength

Wenn man Noten eingibt oder kopiert, sind meistens nur die Noten nahe dem
Ende (wo gerade neue Noten notiert wurden) wichtig für Kontrolle und
Korrektur.  Um die Korrektur zu beschleunigen, kann eingestellt werden,
dass nur die letzten paar Takte angezeigt werden.  Das erreicht man
mit dem Befehl

@verbatim
showLastLength = R1*5
\score { ... }
@end verbatim

@noindent
in der Quelldatei.  Damit werden nur die letzten fünf Takte (in einem
4/4-Takt) eines jeden @code{\score}-Abschnitts übersetzt.  Besonders
bei längeren Stücken ist es meistens sehr viel schneller, nur einen
kleinen Teil des Stückes zu setzen als die gesamte Länge.  Wenn man
am Anfang eines Stückes arbeitet (weil etwa ein neuer Teil hinzugefügt
werden soll), kann auch die @code{showFirstLength}-Eigenschaft
nützlich sein.

Nur bestimmte Teile einer Partitur zu überspringen, kann mit der
Eigenschaft @code{Score.skipTypesetting} sehr genau kontrolliert
werden.  Für den Bereich, für den sie auf @qq{wahr} gesetzt wird,
wird kein Notensatz ausgegeben.

Diese Eigenschaft kann auch benutzt werden, um die MIDI-Ausgabe zu
kontrollieren.  Hiermit werden alle Ereignisse, auch Tempo- und
Instrumentenwechsel ausgelassen.  Man muss also sehr genau darauf
achten, dass nichts unerwartetes geschieht.

@lilypond[quote,ragged-right,verbatim]
\relative {
  c''8 d
  \set Score.skipTypesetting = ##t
  e8 e e e e e e e
  \set Score.skipTypesetting = ##f
  c8 d b bes a g c2
}
@end lilypond

In polyphoner Notation wirkt sich @code{Score.skipTypesetting} auf
alle Stimmen und Systeme aus, sodass noch mehr Zeit bei der
Übersetzung der Datei gespart wird.


@node Alternative Ausgabeformate
@subsection Alternative Ausgabeformate
@translationof Alternative output formats

@cindex scalable vector graphics output
@cindex skalierbare Vektorgraphik-Ausgabe
@cindex SVG-Ausgabe
@cindex encapsulated postscript output
@cindex EPS-Ausgabe
@cindex PNG-Ausgabe

Das Standardausgabeformat für gedruckte Partituren ist PDF (Portable
Document Forma) und PS (PostScript).  SVG (Scalable Vector
Graphics), EPS (Encapsulated PostScript) und PNG (Portable
Network Graphics) gibt es auch als Ausgabeformate über die
Kommandozeile.  Siehe @rprogram{Grundlegende Optionen auf der Kommandozeile für LilyPond}.


@node Die Notationsschriftart verändern
@subsection Die Notationsschriftart verändern
@translationof Replacing the notation font

Gonville ist eine Alternative zu der Emmentaler-Schriftart, die in
LilyPond eingesetzt wird und kann unter der Adresse
@example
@uref{http://www.chiark.greenend.org.uk/~sgtatham/gonville/ ,http://www.chiark.greenend.org.uk/~sgtatham/gonville/}
@end example

@noindent
heruntergeladen werden.  Hier einige Takte Noten mit der Gonville-Schriftart:

@c NOTE: these images are a bit big, but that's important
@c       for the font comparison.  -gp
@sourceimage{Gonville_after,,}

Und hier einige Beispieltakte in der Feta-Glyphe:

@sourceimage{Gonville_before,,}

@subsubheading Installationsanweisungen für MacOS

Laden Sie die Datei herunter und entpacken Sie die ZIP-Datei.
Kopieren Sie das @code{lilyfonts}-Verzeichnis nach
@file{@var{SHARE_DIR}/lilypond/current}; für mehr Information
siehe @rlearning{Mehr Information}.
Benennen Sie das existierende @code{fonts}-Verzeichnis in
@code{fonts_orig} um und benennen Sie das Verzeichnis
@code{lilyfonts} in @code{fonts}.  Das alte Verzeichnis
@code{fonts_orig} können Sie einfach in @code{fonts}
zurückbenennen, um wieder nach Feta zu wechseln.

@morerefs
Handbuch zum Lernen:
@rlearning{Mehr Information}.

@knownissues

Gonville kann nicht verwendet werden, um Alte Notation zu setzen und es
ist wahrscheinlich, dass neuere Glyphen in späteren Versionen von
LilyPond nicht in Gonville enthalten sein werden.
Bitte lesen Sie die Webseite des Autoren zu mehr Information hierzu
und zu anderen Einzelheiten, wie auch der Lizenz von Gonville.


@node MIDI-Ausgabe
@section MIDI-Ausgabe
@translationof MIDI output

@cindex Klang
@cindex MIDI

MIDI (Musical Instrument Digital Interface) ist ein Standard zur
Kontrolle und Interaktion mit digitalen Instrumenten.  Eine
MIDI-Datei ist eine Anzahl von Noten auf einer Anzahl von
Bändern/Stimmen.  Es ist keine eigentliche Klangdatei, denn man
benötigt spezielle Programme die die Notenereignisse in Klang
umwandeln können.

Der Notensatz von LilyPond kann in MIDI umgewandelt werden, so dass
man sich anhören kann, was man notiert hat.  Das hilft oft sehr gut
bei der Überprüfung: falsche Oktaven oder falsche Versetzungszeichen
lassen sich meist sehr gut hören.

Normale MIDI-Ausgabe ist etwas roh; optional kann eine verbesserte und
realistischere MIDI-Ausgabe mit einem @ref{Artikuliere-Skript}
erzeugt werden.

Die MIDI-Ausgabe benötigt einen Kanal für jedes System und reserviert
Kanal 10 für Schlagzeug.  Es gibt nur 16 MIDI-Kanäle pro Gerät,
sodass MIDI-Kanäle mehrfach benutzt werden, wenn eine Partitur mehr
als 15 Notensysteme hat.

@menu
* MIDI-Dateien erstellen::
* Der MIDI-Block::
* Was geht in die MIDI-Ausgabe::
* Wiederholungen im MIDI::
* MIDI-Lautstärke kontrollieren::
* Schlagzeug in MIDI::
* Artikuliere-Skript::
@end menu


@node MIDI-Dateien erstellen
@subsection MIDI-Dateien erstellen
@translationof Creating MIDI files

Um eine MIDI-Datei aus einer LilyPond-Quelldatei zu erstellen, muss
eine @code{\midi}-Umgebung zu der @code{\score}-Umgebung hinzugefügt
werden, etwa so:

@example
\score @{
  @var{...Noten...}
  \midi @{ @}
@}
@end example

Wenn in einer @code{\score}-Umgebung nur eine @code{\midi}-Umgebung,
aber keine @code{\layout}-Umgebung vorkommt, wird nur MIDI produziert.
Wenn auch die Notation gewünscht ist, muss zusätzlich die
@code{\layout}-Umgebung vorhanden sein:

@example
\score @{
  @var{...music...}
  \midi @{ @}
  \layout @{ @}
@}
@end example

Tonhöhen, Rhythmen, Überbindungen, Dynamik und Tempoänderungen werden
korrekt in das MIDI-Format übersetzt.  Dynamikzeichen, Crescendo und
Decrescendo werden in den MIDI-Lautstärkekanal übertragen.  Dynamikzeichen
werden in einen bestimmten Lautstärkenwert übersetzt, Crescendo und
Decrescendo erreichen einen Übergang zwischen Lautstärkewerten.
Die Wirkung von Dynamikzeichen kann auch aus der MIDI-Datei entfernt
werden.  Siehe hierzu @ref{Der MIDI-Block}.

Das Anfangstempo und spätere Tempoänderungen können mit dem
@code{\tempo}-Befehl innerhalb der Notation notiert werden.  Er
bewirkt Tempoänderungen auch in der MIDI-Datei.  Der Befehl setzt
gleichzeitig auch eine Tempobezeichnung in die Noten, welches aber
auch unterdrückt werden kann, siehe @ref{Metronomangabe}.  Eine
andere Möglichkeit, ein eigenes MIDI-Tempo anzugeben, wird weiter
unten gezeigt, siehe @ref{Der MIDI-Block}.

Aufgrund einiger Einschränkungen auf Windows ist auf Windows-Systemen
die Standarddateierweiterung von MIDI-Dateien @code{.mid}. Andere
Betriebssysteme verwenden weiterhin @code{.midi}. Wenn eine
andere Endung erwünscht ist, kann man die folgende Zeile auf oberster
Ebene der Quelldatei, vor Beginn eines @code{\book}, @code{\bookpart}
oder @code{\score}-Blocks einfügen:

@example
#(ly:set-option 'midi-extension "midi")
@end example

Diese Codezeile setzt die Dateiendung auf @code{.midi}.

Als Alternative kann man diese Option auch als Kommandozeilenparameter
übergeben:

@example
lilypond … -dmidi-extension=midi lilyDatei.ly
@end example

@unnumberedsubsubsec Instrumentenbezeichnungen

@cindex Instrumentbezeichnungen

@funindex Staff.midiInstrument

Das MIDI-Instrument, mit dem ein bestimmtes System wiedergegeben
werden soll, wird durch die @code{Staff.midiInstrument}-Eigenschaft
bestimmt, die auf eine Instrumentenbezeichnung gesetzt werden muss.
Die Bezeichnungen sind aufgelistet in @ref{MIDI-Instrumente} und müssen
in der dort definierten Schreibweise notiert werden.

@example
\new Staff @{
  \set Staff.midiInstrument = "glockenspiel"
  @var{...Noten...}
@}
@end example

@example
\new Staff \with @{midiInstrument = "cello"@} @{
  @var{...Noten...}
@}
@end example

Wenn die Schreibweise nicht genau einem definierten Instrument aus
der Liste entspricht, wird ein Piano-Klang benutzt (@code{"acoustic grand"}).

@snippets

@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/changing-midi-output-to-one-channel-per-voice.ly}

@knownissues

Veränderungen der MIDI-Lautstärke sind nur effektiv, wenn sie zu Beginn
einer Note angefordert werden, sodass die Lautstärke während einer Notendauer
nicht geändert werden kann.

Nicht alle MIDI-Spieler können Tempoänderungen richtig wiedergeben.
Spieler, die hierzu in der Lage sind, sind unter Anderen MS Windows Media
Player und @uref{http://@/timidity@/.sourceforge@/.net/,timidity}.


@node Der MIDI-Block
@subsection Der MIDI-Block
@translationof MIDI block

@cindex MIDI-Umgebung

Eine @code{\midi}-Umgebung muss innerhalb von einer @code{\score}-Umgebung
vorkommen, wenn MIDI-Ausgabe gewünscht ist.  Sie entspricht der
@code{\layout}-Umgebung, aber ist etwas einfacher aufgebaut.  Oft wird
die MIDI-Umgebung einfach leer gelassen, aber hier können auch
Kontexte umgeändert werden, neue Kontexte definiert werden oder
neue Werte definiert werden.  Das folgende Beispiel etwa definiert
das MIDI-Tempo, ohne dass in der Partitur eine Metronombezeichnung
gesetzt wird:

@example
\score @{
  @var{...Noten...}
  \midi @{
    \tempo 4 = 72
  @}
@}
@end example

Hier wird das Tempo auf 72 Viertelnoten pro Minute definiert.  @code{\tempo}
ist eigentlich ein Musikbefehl, der die Eigenschaften während der Interpretation
der Musik einstellt: im Kontext von Ausgabedefinitionen wie etwa einem
@code{\midi}-Kontext werden sie neu interpretiert, als ob es sich um
Kontextmodifikatoren handelte.

@cindex MIDI-Kontextdefinitionen

Kontextdefinitionen des @code{\midi}-Kontextes entsprechen
der Syntax, wie sie in der @code{\layout}-Umgebung benutzt
wird.  Klangübersetzungsmodule werden @code{performer}
genannt.  Die Kontexte für die MIDI-Ausgabe sind in der
Datei @file{../ly/performer-init.ly} definiert, siehe
@rlearning{Mehr Information}.  Um beispielsweise
die Auswirkung von Dynamikzeichen aus der MIDI-Ausgabe zu
entfernen, müssen folgende Zeilen eingefügt werden:

@example
\midi @{
  ...
  \context @{
    \Voice
    \remove Dynamic_performer
  @}
@}
@end example

Eine MIDI-Ausgabe wird nur erstellt, wenn die @code{\midi}-Umgebung
in eine Partiturumgebung eingefügt wird, die mit dem Befehl
@code{\score} beginnt.

@example
\score @{
  @{ @dots{}Noten@dots{} @}
  \midi @{ @}
@}
@end example


@node Was geht in die MIDI-Ausgabe
@subsection Was geht in die MIDI-Ausgabe
@translationof What goes into the MIDI output?


@unnumberedsubsubsec In MIDI unterstützt

@cindex Tonhöhen in MIDI
@cindex MIDI, Tonhöhen
@cindex Vierteltöne in MIDI
@cindex MIDI, Vierteltöne
@cindex Mikrotöne in MIDI
@cindex MIDI, Mikrotöne
@cindex Akkordsymbole in MIDI
@cindex MIDI, Akkordsymbole
@cindex Rhythmen in MIDI
@cindex MIDI, Rhythmen
@cindex Artikuliere-Skript
@cindex MIDI, Artikuliere-Skript
@cindex MIDI, Artikulationen
@cindex Triller in MIDI
@cindex Verzierungen in MIDI
@cindex Rallantando in MIDI
@cindex Accelerando in MIDI

Die folgenden Notationselemente werden in die MIDI-Ausgabe aufgenommen:

@itemize
@item Tonhöhen
@item Mikrotöne (siehe @ref{Versetzungszeichen}. Für die Ausgabe wird ein
Spieler benötigt, der Tonhöhen verändern kann.)
@item Akkorde, die als Symbole notiert werden
@item Rhythmen, die als Dauern notiert sind, inklusive N-tolen
@item Tremolo, das ohne @q{@code{:}[@var{Zahl}]} notiert ist
@item Überbindungen
@item Dynamikzeichen
@item Crescendi, decrescendi zu mehreren Noten
@item Tempoänderungen, die mit einer Tempo-Bezeichnung eingegeben werden
@item Gesangstext
@end itemize

Durch Einsatz vom @ref{Artikuliere-Skript} können noch einige Elemente
zu der Liste hinzugefügt werden:

@itemize
@item Artikulationen (Bögen, Staccato usw.)
@item Triller usw.
@item Rallentando und accelerando
@end itemize


@unnumberedsubsubsec In MIDI nicht unterstützt

Folgende Notationselemente werden nicht in die MIDI-Ausgabe einbezogen,
außer am setzt das @ref{Artikuliere-Skript} ein:

@itemize
@item Rhythmus, der als Anmerkung notiert wird, bspw. Swing
@item Tempoveränderungen, die als Anmerkung ohne Tempobezeichnung notiert werden
@item Staccato und andere Artikulationen und Ornamente
@item Legato- und Phrasierungsbögen
@item Crescendi, decrescendi zu einer einzelnen Note
@item Tremolo, notiert mit @q{@code{:}[@var{number}]}
@item Bezifferter Bass
@item Akkorde mit Mikrotönen
@end itemize


@node Wiederholungen im MIDI
@subsection Wiederholungen im MIDI
@translationof Repeats in MIDI

@cindex Wiederholungen in MIDI
@cindex MIDI und Wiederholungen

@funindex \unfoldRepeats

Mit einigen Veränderungen im Notentext können alle Wiederholungstypen
auch in der MIDI-Ausgabe wiedergegeben werden.  Das wird erreicht, indem
die @code{\unfoldRepeats}-Funktion eingesetzt wird.  Diese Funktion
verändert alle Wiederholungen in ausgeschriebene Noten.

@lilypond[quote,verbatim]
\unfoldRepeats {
  \repeat tremolo 8 { c'32 e' }
  \repeat percent 2 { c''8 d'' }
  \repeat volta 2 { c'4 d' e' f' }
  \alternative {
    { g' a' a' g' }
    { f' e' d' c' }
  }
}
\bar "|."
@end lilypond

In Parituren mit mehreren Stimmen funktioniert das Ausschreiben der
Wiederholungen im MIDI nur richtig, wenn @emph{jede} Stimme vollständig
notierte Wiederholungsanweisungen enthält.

Wenn eine Partitur mit diesem @code{\unfoldRepeats}-Befehl erstellt
wird, ist er notwendig,
zwei @code{\score}-Umgebungen einzurichten: in der einen werden die
Wiederholungen ausgeschrieben und nur eine MIDI-Ausgabe produziert,
in der anderen werden die Wiederholungen notiert und als Partitur
gesetzt.  Das Beispiel gibt einen Hinweis, wie eine derartige Datei
aussehen kann:

@example
\score @{
  @var{..music..}
  \layout @{ .. @}
@}
\score @{
  \unfoldRepeats @var{..music..}
  \midi @{ .. @}
@}
@end example


@node MIDI-Lautstärke kontrollieren
@subsection MIDI-Lautstärke kontrollieren
@translationof Controlling MIDI dynamics

Dynamik in der MIDI-Ausgabe wird durch den Dynamic_performer
erstellt, welcher sich in einem @code{Voice}-Kontext befindet.
Es ist möglich, sowohl die generelle Lautstärke einer MIDI-Datei
als auch relative Lautstärken von Dynamikanweisungen und auch
relative Lautstärke von einzelnen Instrumenten einzustellen.


@unnumberedsubsubsec Dynamik-Zeichen

Dynamikanweisungen werden als ein bestimmter Bruch der insgesamt
zur Verfügung stehenden MIDI-Lautstärke notiert.  Die Standardbrüche
reichen von 0,25 für @notation{ppppp} bis hin zu 0,95 für
@notation{fffff}.  Diese Anweisung befinden sich in der Datei
@file{../scm/midi.scm}, siehe auch @rlearning{Mehr Information}.
Diese Brüche können nach Belieben geändert oder erweitert werden, indem
eine Funktion erstellt wird, die ein Dynamikzeichen als Argument
nimmt und den erforderlichen Bruch ausgibt; schließlich muss noch
@code{Score.dynamicAbsoluteVolumeFunction} auf diese Funktion
gesetzt werden.

Beispielhaft soll gezeigt werden, wie man eine @notation{Rinforzando}-Dynamik,
@code{\rfz}, auch in die MIDI-Ausgabe übernehmen kann.  Gleiches gilt
für neue, selbstdefinierte Dynamikzeichen, die in den Standarddefinitionen
nicht enthalten sind.  Die Scheme-Funktion, die hier definiert wird,
setzt den Bruch von 0,9 für eine rfz-Anweisung und ruft andernfalls die
Standardanweisungen auf:

@lilypond[verbatim,quote]
#(define (myDynamics dynamic)
    (if (equal? dynamic "rfz")
      0.9
      (default-dynamic-absolute-volume dynamic)))

\score {
  \new Staff {
    \set Staff.midiInstrument = "cello"
    \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
    \new Voice {
      \relative {
        a'4\pp b c-\rfz
      }
    }
  }
  \layout {}
  \midi {}
}
@end lilypond

Alternativ, insbesondere wenn die gesamte Tabelle der MIDI-Lautstärken
umdefiniert werden soll, ist es besser, die
@notation{default-dynamic-absolute-volume}-Prozedur in der Datei
@file{../scm/midi.scm} und die hiermit verknüpfte Tabelle als Modell
zu benutzen.  Das letzte Beispiel dieses Abschnittes zeigt, wie das
gemacht werden kann.


@unnumberedsubsubsec MIDI-Lautstärke

Die generellen Mindest- und Höchstwerte für die Lautstärke der MIDI-Datei
wird kontrolliert, indem die Eigenschaften @code{midiMinimumVolume}
und @code{midiMaximumVolume} auf der @code{Score}-Ebene gesetzt
werden.  Diese Eigenschaften haben nur Einfluss auf Dynamikzeichen, sodass
ein Dynamikzeichen direkt an den Anfang der Partitur gestellt werden muss,
wenn diese Einstellung von Anfang an Wirkung zeigen soll.  Der Bruch,
der dann den einzelnen Dynamikzeichen entspricht, wird mit der
Formel

@example
midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * Bruch
@end example

@noindent
errechnet.  Im folgenden Beispiel wird die generelle MIDI-Lautstärke
auf den Bereich zwischen 0.2 und 0.5 eingeschränkt.

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \key g \major
      \time 2/2
      \set Staff.midiInstrument = "flute"
      \new Voice \relative {
        r2 g''\mp g fis~
        4 g8 fis e2~
        4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = "clarinet"
      \new Voice \relative {
        b'1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout {}
  \midi {
    \tempo 2 = 72
    \context {
      \Score
      midiMinimumVolume = #0.2
      midiMaximumVolume = #0.5
    }
  }
}
@end lilypond


@unnumberedsubsubsec Verschiedene Instrumente angleichen (i)

Wenn die Mindest- und Höchstwerte für die MIDI-Lautstärke
innerhalb eines @code{Staff}-Kontextes gesetzt werden,
kann damit die relative Lautstärke einzelner Instrumente kontrolliert
werden.  Damit kann man die Qualität der MIDI-Datei
merklich verbessern.

In diesem Beispiel wird die Lautstärke der Klarinette relativ
zur Lautstärke der Flöte verringert.  In jeder Stimme muss
eine Dynamikanweisung für die erste Note gesetzt werden, damit
diese Einstellung korrekt funktioniert.

@lilypond[verbatim,quote]
\score {
  <<
    \new Staff {
      \key g \major
      \time 2/2
      \set Staff.midiInstrument = "flute"
      \set Staff.midiMinimumVolume = #0.7
      \set Staff.midiMaximumVolume = #0.9
      \new Voice \relative {
        r2 g''\mp g fis~
        4 g8 fis e2~
        4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = "clarinet"
      \set Staff.midiMinimumVolume = #0.3
      \set Staff.midiMaximumVolume = #0.6
      \new Voice \relative {
        b'1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout {}
  \midi {
    \tempo 2 = 72
  }
}
@end lilypond


@unnumberedsubsubsec Verschiedene Instrumente angleichen (ii)

Wenn Mindest- und Höchstwerte für die Lautstärke der MIDI-Datei
nicht vorgegeben werden, nimmt LilyPond standardmäßig einige
Anpassungen für die Lautstärken bestimmter Instrumente vor.
Diese Instrumente und ihre entsprechende Veränderung lassen
sich aus der Tabelle @notation{instrument-equalizer-alist}
in der Datei @file{../scm/midi.scm} entnehmen.

Dieser grundlegende Equalizer kann ersetzt werden, indem die
Funktion @code{instrumentEqualizer} im @code{Score}-Kontext auf
eine neue Scheme-Funktion gesetzt wird, die MIDI-Instrumentbezeichnungen
als einziges Argument akzeptiert und ein Zahlenpaar ausgibt, das
den Höchst- und Mindestwert für die Lautstärke des entsprechenden
Instruments darstellt.  Die Ersetzung der Standardfunktion wird
auf gleiche Weise vorgenommen, wie es schon für die
@code{dynamicAbsoluteVolumeFunction} zu Beginn dieses Abschnittes
gezeigt wurde.  Der Standard-Equalizer,
@notation{default-instrument-equalizer} in der Datei
@file{../scm/midi.scm} zeigt, wie solche eine Funktion erstellt werden
kann.

Das folgende Beispiel definiert für die Flöte und Klarinette relative
Lautstärkewerte, die denen des vorigen Beispiels entsprechen.

@lilypond[verbatim,quote]
#(define my-instrument-equalizer-alist '())

#(set! my-instrument-equalizer-alist
  (append
    '(
      ("flute" . (0.7 . 0.9))
      ("clarinet" . (0.3 . 0.6)))
    my-instrument-equalizer-alist))

#(define (my-instrument-equalizer s)
  (let ((entry (assoc s my-instrument-equalizer-alist)))
    (if entry
      (cdr entry))))

\score {
  <<
    \new Staff {
      \key g \major
      \time 2/2
      \set Score.instrumentEqualizer = #my-instrument-equalizer
      \set Staff.midiInstrument = "flute"
      \new Voice \relative {
        r2 g''\mp g fis~
        4 g8 fis e2~
        4 d8 cis d2
      }
    }
    \new Staff {
      \key g \major
      \set Staff.midiInstrument = "clarinet"
      \new Voice \relative {
        b'1\p a2. b8 a
        g2. fis8 e
        fis2 r
      }
    }
  >>
  \layout { }
  \midi {
    \tempo 2 = 72
  }
}
@end lilypond



@node Schlagzeug in MIDI
@subsection Schlagzeug in MIDI
@translationof Percussion in MIDI

Schlagzeuginstrumente werden üblicherweise in einem @code{DrumStaff}-Kontext
notiert.  Aus diese Weise werden sie korrekt in den MIDI-Kanal@tie{}10
ausgegeben.  Eine Schlagzeuge mit diskreten Tonhöhen, wie Xylophon,
Marima, Vibraphone, Pauken usw. werden wie @qq{normale} Instrumente
in einem @code{Staff}-Kontext notiert.  Nur so lässt sich auch hier
eine richtige MIDI-Ausgabe erreichen.

Einige Instrumente, die keine diskreten Tonhöhen haben, können nicht
über den MIDI-Kanal@tie{}10 erreicht werden und müssen deshalb in
einem normalen @code{Staff}-Kontext mit passenden normalen Tonhöhen
notiert werden.  Es handelt sich
um @code{melodic tom, taiko drum, synth drum} u. A.

Viele Schlagzeuginstrumente sind nicht in den MIDI-Standard aufgenommen,
z. B. Kastagnetten.  Die einfachste Methode, derartige Instrumente
zu ersetzen, ist, einen Klang auszuwählen, der ihnen halbwegs ähnlich
kommt.


@knownissues

Weil der MIDI-Standard keine Peitschenschläge kennt, wird ein
Schlagstock (sidestick) für diesen Zweck eingesetzt.


@node Artikuliere-Skript
@subsection Artikuliere-Skript
@translationof The Articulate script

Eine realistischere MIDI-Ausgabe ist möglich, wenn man das
Artikuliere-Skript einsetzt.  Es versucht, Artikulationen
(Bögen, Staccato) mit einzubeziehen, indem Noten mit
sequentieller Musik von passender Verlängerung oder Verkürzung
mit entprechenden Skips ersetzt werden.  Es versucht auch,
Triller usw. klingen zu lassen und rallantando und
accelerando wahrzunehmen.

Um das Artikuliere-Skript einzusetzen, muss oben in der
Eingabedatei

@example
\include "articulate.ly"
@end example

@noindent
eingefügt werden.  Im @code{\score}-Abschnitt schreibt man

@example
\unfoldRepeats \articulate <<
	der Rest der Partitur...
>>
@end example

Wenn die Eingabedatei auf diese Art verändert wurd, wird die
Notenausgabe stark verändert, aber die MIDI-Ausgabe produziert
ein besseres Ergebnis.

Wenn auch nicht unbedingt notwendig, damit das Artikuliere-Skript
funktioniert, bietet es sich an, @code{\unfoldRepeats} wie im
Beispiel oben zu verwenden, weil dadurch Abkürzungen wie etwa
Triller ausgeführt werden.

@knownissues

Articulate verkürzt Akkorde und manche Musik (besonders Orgelmusik)
kann schlechter klingen.



@node Musikalische Information extrahieren
@section Musikalische Information extrahieren
@translationof Extracting musical information

Neben graphischer Ausgabe und MIDI kann LilyPond auch die musikalische
Information als Text anzeigen:

@menu
* LilyPond-Notation anzeigen::
* Musikalische Scheme-Ausdrücke anzeigen::
* Musikalische Ereignisse in einer Datei speichern::
@end menu

@node LilyPond-Notation anzeigen
@subsection LilyPond-Notation anzeigen
@translationof Displaying LilyPond notation

@funindex \displayLilyMusic

Mit der musikalischen Funktion @code{\displayLilyMusic} kann
man einen musikalischen Ausdruck anzeigen.  Um die Ausgabe zu
sehen, wird LilyPond üblicherweise auf der Kommandozeile
aufgerufen.  Beispielsweise

@example
@{
  \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
@}
@end example

@noindent
zeigt an:

@example
@{ a,4 cis e fis g @}
@end example

Standardmäßig gibt LilyPond diese Nachrichten auf die Kommandozeile
aus, zusammen mit all den anderen LilyPond-Nachrichten über die
Kompilation.  Um die Nachrichten zu speichern, kann man die Ausgabe
in eine Datei umleiten:

@example
lilypond file.ly >display.txt
@end example

@funindex \void

LilyPond zeit nicht nur die musikalischen Ausdrücke an, sondern
interpretiert sie auch (weil @code{\displayLilyMusic} sie an das
Programm zurückgibt, zusätzlich zur Anzeige).  Das ist sehr
praktisch, denn man kann einfach @code{\displayLilyMusic}
in vorhandene Noten einfügen, um Informationen darüber zu erhalten.
Wenn Sie nicht wollen, dass LilyPond die angezeigten
musikalischen Ausdrücke auch interpretiert, muss @code{\void}
eingesetzt werden, damit der Ausdruck für die Interpretation ignoriert wird:

@example
@{
  \void \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
@}
@end example


@node Musikalische Scheme-Ausdrücke anzeigen
@subsection Musikalische Scheme-Ausdrücke anzeigen
@translationof Displaying scheme music expressions

Siehe @rextend{Musikalische Funktionen darstellen}.


@node Musikalische Ereignisse in einer Datei speichern
@subsection Musikalische Ereignisse in einer Datei speichern
@translationof Saving music events to a file

Musikereignisse können in einer Datei Notensystem für Notensystem
gespeichert werden, indem eine Datei in die Paritur eingefügt
wird:

@example
\include "event-listener.ly"
@end example

Das erstellt Dateien mit der Bezeichnung @file{DATEINAME-SYSTEMNAME.notes} oder
@file{DATEINAME-unnamed-staff.notes} für jedes Notensystem.
Wenn mehrere Systeme ohne Bezeichnung auftreten, werden die
Ereignisse aller Notensysteme zusammen in der selben Datei
gemischt.  Die Ausgabe sieht folgendermaßen aus:

@example
0.000   note     57       4   p-c 2 12
0.000   dynamic  f
0.250   note     62       4   p-c 7 12
0.500   note     66       8   p-c 9 12
0.625   note     69       8   p-c 14 12
0.750   rest     4
0.750   breathe
@end example

Die Syntax ist eine durch Tabulatoren getrennte Zeile mit zwei
festen Zellen, gefolgt von optionalen Parametern.

@example
@var{time}  @var{type}  @var{...params...}
@end example

Diese Information kann einfach ein ein anderes Programm wie
etwa ein Python-Skript eingelsen werden und kann nützlich für
Forscher sein, die musikalische Analyse- oder Wiedergabeexperimente
mit LilyPond machen wollen.

@knownissues

Nicht alle musikalischen Ereignisse werden von
@file{event-listener.ly} unterstützt.  Es handelt sich eher um ein
gut gemachtes @qq{proof of concept}.  Wenn Ereignisse, die Sie
brauchen, nicht in enthalten sind, können Sie @file{event-listener.ly} 
in Ihr LilyPond-Verzeichnis kopieren und die Datei verändern,
sodass sie die benötigte Information ausgibt.
