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

@c Translators: Till Paala

@part Allgemeine Eingabe und Ausgabe

@node Input structure
@anchor{General Input and output} @c retain old label
@chapter Eingabestruktur

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


@node Structure of a score
@section Struktur einer Partitur

@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{File structure}.)  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{Multiple scores in a book},
@ref{Multiple output files from one input file} und
@ref{File structure}.


@morerefs
Handbuch zum Lernen:
@rlearningnamed{Working on input files, Arbeiten an Eingabe-Dateien},
@rlearningnamed{Music expressions explained, Musikalische Ausdrücke erklärt},
@rlearningnamed{Score is a (single) compound musical expression, Score ist ein (einziger) zusammengesetzter musikalischer Ausdruck}.

Notationsreferenz:
@ref{Multiple scores in a book},
@ref{Multiple output files from one input file} und
@ref{File structure}.


@node Multiple scores in a book
@section Mehrere Partituren in einem Buch

@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 Multiple output files from one input file
@section Mehrere Ausgabedateien aus einer Eingabedatei

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{File structure}.

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 Output file names
@section Dateinamen der Ausgabedateien

@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 File structure
@section Die Dateistruktur

@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{The layout block}.

@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:
@rlearningnamed{How LilyPond input files work, Wie eine LilyPond-Eingabe-Datei funktioniert}.

Notationsreferenz:
@ref{The layout block}.


@node Titles and headers
@chapter Titel

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


@need 1500
@node Creating titles headers and footers
@section Titel, Kopf- und Fußzeilen erstellen


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

@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{File structure},
@ref{Custom layout for title blocks}.


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

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{Custom layout for title blocks}.

@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:
@rlearningnamed{How LilyPond input files work, Wie eine LilyPond-Eingabe-Datei funktioniert},

Notationsreferenz:
@ref{File structure},
@ref{Custom layout for title blocks}.

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


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

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


@need 1500
@node Custom headers footers and titles
@section Eigene Kopf- und Fußzeilen sowie Titel

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


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

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{Formatting text}.


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

@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{Default layout of book and score title blocks}.

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{Title blocks explained}.

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{Title blocks explained}.


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

@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{Title blocks explained},
@ref{Default layout of book and score title blocks}.

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


@node Creating footnotes
@section Fußnoten erstellen

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


@node Footnotes overview
@subsection Übersicht über Fußnoten

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 Automatic footnotes
@subsection Automatische Fußnoten

@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 Manual footnotes
@subsection Manuelle Fußnoten

@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:
@rlearningnamed{Objects and interfaces, Objekte und Schnittstellen}.

Notationsreferenz:
@ref{Balloon help},
@ref{Page layout},
@ref{Text marks},
@ref{Text scripts},
@ref{Titles and headers}.

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 Reference to page numbers
@section Verweis auf die Seitenzahlen

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.

Falls die Größe des finalen Textes sich von der des Platzhalters unterscheidet,
kann es sinnvoll sein, die horizontale Ausrichtung gegenüber dem Platzhalter
mit der Eigenschaft @code{x-align} festzulegen.
Standardmäßig erfolgt die Ausrichtung rechtsbündig mit dem Platzhalter.

@lilypond[quote,verbatim]
\markup {
  \box
    \page-ref #'foo "???" "?" " rechtsbündig (Standard)"
}
\markup {
  \box
    \override #`(x-align . ,LEFT)
    \page-ref #'foo "???" "?" " linksbündig"
}
\markup {
  \box
    \override #'(x-align . -2.5)
    \page-ref #'foo "???" "?" " links außerhalb"
}
@end lilypond

Im Beispiel ist der Platzhalter @samp{???} größer als der eingesetzte Text @samp{?}, der genommen wird,
weil die Marke @code{#'foo} nicht existiert. @code{x-align} kann mit beliebigen Zahlen
eingestellt werden oder die bekannten Symbole @code{LEFT}, @code{CENTER} oder @code{RIGHT} annehmen,
welche die Ausrichtung linksbündig, zentriert oder rechtsbündig gegenüber dem Platzhalter vornehmen.

@predefined
@funindex \label
@funindex \page-ref

@code{\label},
@code{\page-ref}.
@endpredefined


@node Table of contents
@section Inhaltsverzeichnis

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}.

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

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


@need 1500
@node Working with input files
@chapter Arbeiten an Eingabe-Dateien


@node Including LilyPond files
@section LilyPond-Dateien einfügen

@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{Different editions from one source}.

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 @rlearningnamed{Other sources of information, 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 @rlearningnamed{Other sources of information, 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
@rlearningnamed{Scores and parts, Partituren und Stimmen}.

@morerefs
Handbuch zum Lernen:
@rlearningnamed{Other sources of information, Mehr Information},
@rlearningnamed{Scores and parts, 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 Different editions from one source
@section Verschiedene Editionen aus einer Quelldatei

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.


@node Using variables
@subsection Variablen benutzen

@cindex Variablen, Benutzung

Wenn Notenabschnitt in Variablen definiert werden, können sie
an unterschiedlichen Stellen in der Partitur eingesetzt werden,
siehe auch @rlearningnamed{Organizing pieces with variables, 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{Automatic part combining}.
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{Including LilyPond files}.


@node Using tags
@subsection Marken benutzen

@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

@example
\keepWithTag #'@var{Bezeichnung}
@end example

@noindent
oder

@example
\keepWithTag #'(@var{Bezeichnung1} @var{Bezeichnung2}@dots{})
@end example

  @tab Unmarkierte Noten und Noten, die mit einer der angegebenen Bezeichnung
  markiert sind, werden gesetzt, Noten mit einer anderen Marke werden nicht angezeigt.

@item
Markierte Noten mit vorgesetztem

@example
\removeWithTag #'@var{Bezeichnung}
@end example

@noindent
oder

@example
\removeWithTag #'(@var{Bezeichnung1} @var{Bezeichnung2}@dots{})
@end example

  @tab Unmarkierte Noten und Noten, die mit keiner der angegebenen Bezeichnungen
  markiert sind, werden gesetzt, Noten, die mit einer der Bezeichnungen markiert sind,
  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 oder eine Liste von Symbolen sein
(wie etwa @code{#'score} oder @code{#'(violineI violineII)}),
gefolgt von einem musikalischen Ausdruck.
Nur wenn die Symbole gültige LilyPond-Bezeichner sind
(nur Buchstaben, keine Zahlen, Unter- oder Bindestriche),
die nicht mit Noten verwechselt werden können,
kann @code{#'} als Kurzschreibweise weggelassen werden.
Eine Liste von Symbolen kann ein Komma als Trenner nutzen,
d.h. @code{\tag #'(violineI violineII)} kann auch als
@code{\tag violineI,violineII} geschrieben werden.
Das gleiche gilt für @code{\keepWithTag} und @code{\removeWithTag}.
Die Tag-Befehle sind musikalische Funktionen und können damit nicht
zum Filtern von Objekten benutzt werden, die kein musikalischer
Ausdruck sind, also sowas wie @code{\book}- oder @code{\score}-Blöcke.
Es gibt jedoch auch Befehle für Tags in @code{\markup}-Umgebungen.

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.
Alternativ kann auch ein einziger @code{\removeWithTag}-Befehl mit
einer Liste von Marken benutzt werden.

@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 }
}
\new Voice {
  \removeWithTag #'B
  \removeWithTag #'C
  \music
  \removeWithTag #'(B 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.
Ein einzelner @code{\keepWithTag}-Befehl mit mehreren Marken entfernt
nur diejenigen markierten Abschnitte, die nur andere Marken als die
angegebenen enthalten.

In folgendem Beispiel

@lilypond[verbatim,quote]
music = \relative c'' {
  \tag #'violinI { a4 a a a }
  \tag #'violinII { b4 b b b }
  \tag #'viola { c4 c c c }
  \tag #'cello { d4 d d d }
}

\new Staff {
  \keepWithTag #'(violinI violinII)
  \music
}
@end lilypond

@noindent
werden nur die mit @code{\tag} markierten Abchnitte ausgegeben,
die die Bezeichner @var{violinI} und @var{violinII},
aber nicht @var{viola} und @var{cello} benutzen.

@cindex Marke, mehrere, in Gruppen
@funindex \tagGroup

Während @code{\keepWithTag} gut geeignet ist, um mit @emph{einer} Art
von Alternativen umzugehen, führt das Entfernen von @emph{andersartigen}
Marken zu Problemen, bei Nutzung für verschiedene Zwecke.
In diesem Fall können Marken gruppiert werden:

@example
\tagGroup #'(violinI violinII viola cello)
@end example

@noindent
Verschiedene Marken können somit zu einer Gruppe zusammengefasst werden.
Allerdings kann eine einzelne Marke nur in einer Gruppe sein.

Die Nutzung von

@example
\keepWithTag #'violinI @dots{}
@end example

@noindent
entfernt nur markierte Abschnitte mit Marken der gleichen Gruppe,
in der auch @code{violinI} ist, sofern es nicht @code{violinI} selber ist.
Marken anderer Gruppen bleiben unangetastet.

@lilypond[verbatim,quote]
music = \relative {
  \tagGroup #'(violinI violinII)
  \tagGroup #'(viola cello)
  \tag #'violinI { c''4^"violinI" c c c }
  \tag #'violinII { a2 a }
  \tag #'viola { e8 e e2. }
  \tag #'cello { d'2 d4 d }
  \tag #'other { f^"other" f f f }
  R1^"untagged"
}

\new Voice {
  \keepWithTag #'violinI
  \music
}
@end lilypond

Im Beispiel entfernt der @code{\keepWithTag}-Befehl lediglich @code{violinII},
da diese Marke in der selben Gruppe wie @code{violinI} ist.
@code{viola} und @code{cello} bleiben erhalten, weil sie in einer
anderen Gruppe sind und @code{other} bleibt ebenfalls erhalten,
weil diese Marke gar keiner Gruppe zugeordnet ist.

@funindex \tagGroupRef

Es ist möglich, bereits erstellte Taggruppen zu modifizieren.
Um diese referenzieren zu können, existiert eine alternative
Definitionsmöglichkeit mit @code{\tagGroupRef}.  Der Aufruf

@example
tg = \tagGroupRef violinI,violinII
@end example

@noindent
ist im Wesentlichen das gleiche wie

@example
tg = #'(violinI violinII)
\tagGroup \tg
@end example

Bereits erstellte Taggruppen können auf mehrere Arten
verändert werden.

@funindex \resetTagGroups

Um die Auswirkungen von allen @code{\tagGroup}- und
@code{\tagGroupRef}-Befehlen rückgängig zu machen,
lässt sich @code{\resetTagGroups} verwenden.

@lilypond[verbatim,quote]
\tagGroup tagI,tagII

music = \relative {
  \tag tagI { c''4^"tagI" c c c }
  \tag tagII { a2^"tagII" a }
  \tag otherI { d4^"otherI" d d d }
  \tag otherII { f,4^"otherII" g a c }
}

\new Voice {
  \keepWithTag tagI \music
}

\resetTagGroups

\new Voice {
  \keepWithTag tagI \music
}
@end lilypond

@funindex \resetTagGroup

Soll hingegen nur eine einzelne Taggruppe aufgelöst werden,
so ist @code{\resetTagGroup} mit einer Taggruppe zu nutzen.
An dieser Stelle ist die Nutzung von @code{\tagGroupRef}
zur Erstellung der Taggruppe vorteilhaft, um eine Referenz
in Form einer Variablen zu erhalten.

@lilypond[verbatim,quote]
tgI = \tagGroupRef tagI,tagII
tgII = \tagGroupRef otherI,otherII

music = \relative {
  \tag tagI { c''4^"tagI" c c c }
  \tag tagII { a2^"tagII" a }
  \tag otherI { d4^"otherI" d d d }
  \tag otherII { f,4^"otherII" g a c }
  \tag test { c8^"test" a g f e2 }
}

% 'otherI', 'otherII' und 'test' sind nicht in der selben
% Taggruppe wie 'tagI' und werden daher nicht rausgefiltert.
\new Voice {
  \keepWithTag tagI \music
}

\resetTagGroup \tgI

% Jetzt sind nur noch 'otherI' und 'otherII' in einer Taggruppe,
% daher filtert '\keepWithTag tagI' jetzt 'tagII' und 'test' heraus.
\new Voice {
  \keepWithTag tagI \music
}
@end lilypond

@funindex \addToTagGroup
@funindex \removeFromTagGroup

Eine weitere Modifikationsmöglichkeit bieten die Befehle
@code{\addToTagGroup} und @code{\removeFromTagGroup}, die
neue Tags zu bestehenden Taggruppen hinzufügen oder bereits
vorhandene wieder entfernen können.

@lilypond[verbatim,quote]
tgI = \tagGroupRef tagI,tagII
tgII = \tagGroupRef otherI,otherII

music = \relative {
  \tag tagI { c''4^"tagI" c c c }
  \tag tagII { a2^"tagII" a }
  \tag otherI { d4^"otherI" d d d }
  \tag otherII { f,4^"otherII" g a c }
  \tag test { c8^"test" a g f e2 }
}

% 'otherI', 'otherII' und 'test' sind nicht in der gleichen
% Taggruppe wie 'tagI' und bleiben somit ungefiltert.
\new Voice {
  \keepWithTag tagI \music
}

\addToTagGroup \tgI test

% Jetzt sind 'tagI', 'tagII' und 'test' in der gleichen Taggruppe.
% Somit werden 'tagII' und 'test' herausgefiltert.
\new Voice {
  \keepWithTag tagI \music
}

\removeFromTagGroup \tgII otherII
\addToTagGroup \tgI otherII

% Jetzt wird 'otherII' von der Taggruppe 'tgII' entfernt
% und der Taggruppe 'tgI' hinzugefügt.
% Damit ist nur noch 'otherI' in seiner eigenen Gruppe
% und wird damit nicht gefiltert.
\new Voice {
  \keepWithTag tagI \music
}
@end lilypond


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.

@funindex \replaceWithTag

Es ist außerdem möglich, ganze Abschnitte auszutauschen.

@lilypond[verbatim,quote]
music = { c' \tag #'here { d' } e' }

{
  \music
  \replaceWithTag #'here c' \music
}
@end lilypond

Es ist zu beachten, dass dabei der Tag an sich mit ersetzt wird.
Das bedeutet, man kann keine weiteren Ersetzungen oder Filterungen,
die sich auf diesen Tag beziehen, mehr vornehmen.

@lilypond[verbatim,quote]
music = { c' \tag #'here { d' } e' }

{
  \removeWithTag #'here % tut nichts, da der Tag ersetzt wurde
  \replaceWithTag #'here c'
  \music
}
@end lilypond

@funindex \keep-with-tag
@funindex \remove-with-tag
@funindex \push-to-tag
@funindex \append-to-tag
@funindex \replace-with-tag

Der @code{\tag}-Befehl kann auch in @code{\markup}-Umgebungen eingesetzt werden.
Auch die Befehle @code{\keep-with-tag}, @code{\remove-with-tag}, @code{\push-to-tag},
@code{\append-to-tag} und @code{\replace-with-tag} können genutzt werden und
verhalten sich wie ihre Pendants in musikalischen Umgebungen.

@lilypond[verbatim,quote]
test = \markup {
  \tag #'a a
  \tag #'b b
  \tag #'c c
}

\markup { \keep-with-tag #'b \test }
\markup { \remove-with-tag #'b \test }
\markup { \push-to-tag #'c pre \test }
\markup { \append-to-tag #'c post \test }
\markup { \replace-with-tag #'c sub \test }
@end lilypond

Musikalische @code{\keepWithTag}- und @code{\removeWithTag}-Befehle
filtern auch Marken in @code{\markup}-Abschnitten innerhalb des
betroffenen Musikabschnitts.

@lilypond[verbatim,quote]
music = \relative {
  c'4^\markup { \tag #'one first \tag #'two second part } c c c
}

{
  \keepWithTag #'one \music
  \removeWithTag #'one \music
}
@end lilypond

@funindex \pushToTagMarkup
@funindex \appendToTagMarkup
@funindex \replaceWithTagMarkup

Soll an die markierten Stellen in @code{\markup}-Abschnitten von
musikalischen Objekten etwas hinzugefügt werden, kann man
@code{\pushToTag}, @code{\appendToTag} oder @code{\removeWithTag} nicht verwenden,
denn diese fügen nur musikalische Ausdrücke hinzu.
Hierfür wird @code{\pushToTagMarkup}, @code{\appendToTagMarkup} oder
@code{\removeWithTagMarkup} benötigt.

@lilypond[verbatim,quote]
music = \relative {
  c'4^\markup { \tag #'part part } c c c
}

{
  \pushToTagMarkup #'part "great" \music
  \appendToTagMarkup #'part \markup { is also great } \music
  \replaceWithTagMarkup #'part \markup { cool substitution } \music
}
@end lilypond

Die Filterung von Marken wirkt sich umgekehrt auch auf Musik
innerhalb eines @code{\score}-Befehls in einem @code{\markup}-Abschnitt aus.

@lilypond[verbatim,quote]
music = \relative {
  c'2^\markup { \tag #'first first \tag #'second second } c
  \tag #'first { d d }
  \tag #'second { f f }
}

\markup {
  \keep-with-tag #'first \score { \music }
  \remove-with-tag #'first \score { \music }
}
@end lilypond

@funindex \tag-list

Bei der Verwendung von Marken in Markups ist allerdings beim Markieren
von Listen besondere Vorsicht geboten. Während die Filter

@lilypond[verbatim,quote]
\markup {
  \remove-with-tag #'test { a \tag #'test { b c } d }
}
@end lilypond

@noindent
gut funktionieren, gibt es bei den einfügenden Befehlen
@code{\push-to-tag}, @code{\append-to-tag} und
@code{\replace-with-tag} Probleme.

@lilypond[verbatim,quote]
\markup {
  \remove-with-tag #'test { a \tag #'test { b c } d }
}
\markup {
  \push-to-tag #'test "twice" { a \tag #'test { b c } d }
}
\markup {
  \replace-with-tag #'test "twice" { a \tag #'test { b c } d }
}
@end lilypond

Das liegt in diesem Falle daran, dass LilyPond das Konstrukt

@example
\tag #'test @{ b c @}
@end example

@noindent
intern auflöst zu

@example
\tag #'test b
\tag #'test c
@end example

@noindent
und daher den übergebenen Text zweimal einfügt.
Geht es wirklich darum, vor oder nach einer Liste an sich
etwas einzufügen, muss auch die ganze Liste entsprechend
markiert werden. Das geht mit @code{\tag-list}.

@lilypond[verbatim,quote]
\markup {
  \push-to-tag #'test "once" { a \tag-list #'test { b c } d }
}
@end lilypond

@morerefs
Handbuch zum Lernen:
@rlearningnamed{Organizing pieces with variables, Stücke durch Variablen organisieren}.

Notationsreferenz:
@ref{Automatic part combining},
@ref{Including LilyPond files}.

@knownissues
Die Nutzung von @code{\relative} auf musikalische Abschnitte, die
mittels @code{\keepWithTag} oder @code{\removeWithTag} gefiltert wurden,
kann die Oktavlage verändern, da nur die Töne betrachtet werden,
die nach der Filterung noch übrig sind.
Wenn @code{\relative} zuerst angewendet wird, bevor @code{\keepWithTag} oder
@code{\removeWithTag} filtern, kann das Problem vermieden werden, da
@code{\relative} dann auf alle Töne angewendet wird
und die Filterung danach erfolgt.


@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 Using global settings
@subsection Globale Einstellungen benutzen

@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 @rlearningnamed{Style sheets, Formatvorlagen} behandelt.

@morerefs
Handbuch zum Lernen:
@rlearningnamed{Organizing pieces with variables, Stücke durch Variablen organisieren},
@rlearningnamed{Style sheets, Formatvorlagen}.

Notationsreferenz:
@ref{Including LilyPond files}.


@need 1500
@node Special characters
@section Sonderzeichen

@cindex Sonderzeichen
@cindex Nicht-ASCII-Zeichen


@node Text encoding
@subsection Zeichenkodierung


@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 {
  property-defaults.fonts.serif = "Linux Libertine O,serif"
  property-defaults.fonts.sans = "Linux Biolinum O,sans-serif"
  property-defaults.fonts.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
@subsection 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--2026" \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 aliases
@subsection ASCII-Aliase

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{List of special characters}.

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


@need 1500
@node Controlling output
@chapter Ausgabe kontrollieren


@node Extracting fragments of music
@section Notationsfragmente extrahieren

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 @rprogramnamed{Invoking LilyPond, lilypond aufrufen}.


@node Skipping corrected music
@section Korrigierte Musik überspringen


@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 output formats
@section Alternative Ausgabeformate

@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 @rprogramnamed{Basic command-line options for LilyPond, Grundlegende Optionen auf der Kommandozeile für LilyPond}.


@node Replacing the notation font
@section Die Notationsschriftart verändern

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,,}

@subheading 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 @rlearningnamed{Other sources of information, 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:
@rlearningnamed{Other sources of information, 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 output
@chapter MIDI-Ausgabe

@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{The articulate script}
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.


@node Creating MIDI files
@section MIDI-Dateien erstellen

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{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{Metronome marks}.  Eine
andere Möglichkeit, ein eigenes MIDI-Tempo anzugeben, wird weiter
unten gezeigt, siehe @ref{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

@subheading 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 instruments} 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 MIDI block
@section Der 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
@rlearningnamed{Other sources of information, 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 What goes into the MIDI output?
@section Was geht in die MIDI-Ausgabe


@subheading 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{Accidentals}. 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{The articulate script} 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


@subheading In MIDI nicht unterstützt

Folgende Notationselemente werden nicht in die MIDI-Ausgabe einbezogen,
außer am setzt das @ref{The articulate script} 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 Repeats in MIDI
@section Wiederholungen im 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 Controlling MIDI dynamics
@section MIDI-Lautstärke kontrollieren

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.


@subheading 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 @rlearningnamed{Other sources of information, 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.


@subheading 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


@subheading 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


@subheading 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 Percussion in MIDI
@section Schlagzeug 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 The articulate script
@section Artikuliere-Skript

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 Extracting musical information
@chapter Musikalische Information extrahieren

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


@node Displaying LilyPond notation
@section LilyPond-Notation anzeigen

@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 Displaying Scheme music expressions
@section Musikalische Scheme-Ausdrücke anzeigen

Siehe @rextendnamed{Displaying music expressions, Musikalische Funktionen darstellen}.


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

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.
