Doc-de: updates and adding snippet translation to notation manual

[lilypond.git] / Documentation / de / notation / changing-defaults.itely

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

@ignore
    Translation of GIT committish: fc1ca638e0b5f66858b9b7a073ceefc1eccb3ed2

    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.15.20"

@c Translators: Till Paala

@node Standardeinstellungen verändern
@chapter Standardeinstellungen verändern
@translationof Changing defaults

Das Ziel von LilyPonds Design ist es, von sich aus gut gesetzte Noten
zu produzieren.  Es kann aber trotzdem vorkommen, dass Sie diesen
Standardsatz ändern wollen.  Das Layout kann mithilfe einer recht
großen Anzahl von @qq{Schaltern und Knöpfen} kontrolliert werden.
Sie werden als @qq{Eigenschaften} (engl. properties)  bezeichnet.
Eine kurze Einführung und Übung, wie man auf diese Eigenschaften
zugreifen kann und sie verändern kann, findet sich im Handbuch
zum Lernen, siehe @rlearning{Die Ausgabe verändern}.  Das Kapitel
sollte zuerst gelesen werden.  In diesem Kapitel werden die gleichen
Themen behandelt, aber der Schwerpunkt liegt eher auf einer technischen
Darstellung.

@cindex Referenz der Interna
@cindex Internals Reference

Die definitive Beschreibung der unterschiedlichen Einstellmöglichenkeiten
findet sich in einem eigenen Dokument: @rinternalsnamed{Top,der Referenz
der Interna}.  Diese Referenz zeigt alle Variablen, Funktionen und Optionen,
die in LilyPond möglich sind.  Es existiert als ein HTML-Dokumente, das
sich
@c leave the @uref as one long line.
@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
aber auch lokal in das LilyPond-Dokumentationspaket integriert lesen lässt.

Intern benutzt LilyPond Scheme (ein LISP-Dialekt), um eine Infrastruktur
zur Verfügung zu stellen.  Wenn Layoutentscheidungen verändert werden
sollen, müssen auf die programminternen Prozesse zugegriffen werden,
wozu Scheme-Code benötigt wird.  Scheme-Abschnitte werden in einer
LilyPond-Quelldatei mit einer Raute@tie{}@code{#} begonnen.@footnote{@rextend{Scheme-Übung} enthält eine kurze Übung, wie
man Zahlen, Listen, Zeichenketten und Symbole in Scheme notiert.}


@menu
* Interpretationskontexte::
* Die Referenz der Programminterna erklärt::
* Eigenschaften verändern::
* Nützliche Konzepte und Eigenschaften::
* Fortgeschrittene Optimierungen::
* Musikfunktionen benutzen::
@end menu


@node Interpretationskontexte
@section Interpretationskontexte
@translationof Interpretation contexts

Dieser Abschnitt erklärt, was Kontexte sind und wie man sie
verändern kann.

@menu
* Was sind Kontexte?::
* Kontexte erstellen::
* Kontexte am Leben halten::
* Umgebungs-Plugins verändern::
* Die Standardeinstellungen von Kontexten ändern::
* Neue Kontexte definieren::
* Reihenfolge des Kontextlayouts::
@end menu


@seealso
Handbuch zum Lernen:
@rlearning{Kontexte und Engraver}.

Installierte Dateien:
@file{ly/engraver-init.ly},
@file{ly/performer-init.ly}.

Schnipsel:
@rlsr{Contexts and engravers}.

Referenz der Interna:
@rinternals{Contexts},
@rinternals{Engravers and Performers}.


@node Was sind Kontexte?
@subsection Was sind Kontexte?
@translationof Contexts explained

Kontexte sind hierarchisch geordnet:

@menu
* Score -- der Vater aller Kontexte::
* Oberste Kontexte -- Container für Systeme::
* Mittlere Kontexte -- Systeme::
* Unterste Kontexte -- Stimmen::
@end menu

@node Score -- der Vater aller Kontexte
@unnumberedsubsubsec Score -- der Vater aller Kontexte
@translationof Score - the master of all contexts

@code{Score} (Partitur) ist der höchste Notationskontext.  Kein anderer Kontext
kann einen @code{Score}-Kontext enthalten.  Im Normalfall kümmert
sich der @code{Score}-Kontext um die Verwaltung der Taktarten und sorgt
dafür, dass Elemente wie Schlüssel und Taktart- oder Tonartbezeichnungen
über die Systeme hinweg aneinander ausgerichtet sind.

Ein @code{Score}-Kontext wird eingerichtet, wenn eine
@code{\score @{@dots{}@}} oder @code{\layout @{@dots{}@}}-Umgebung
interpretiert wird.

@node Oberste Kontexte -- Container für Systeme
@unnumberedsubsubsec Oberste Kontexte -- Container für Systeme
@translationof Top-level contexts - staff containers

@c Remark for German translation
Diese Kontexte fassen Systeme zu Gruppen zusammen und werden darum hier
als Systemgruppen bezeichnet (engl. staffgroup).

@strong{@emph{StaffGroup}}

Gruppiert Systeme und fügt eine eckige Klammer auf der linken Seite
hinzu.  Die Taktstriche der enthaltenen Systeme werden vertikal
miteinander verbunden. @code{StaffGroup} besteht nur aus einer Ansammlung
von Systemen mit einer eckigen Klammer zu Beginn der Zeile und
durchgezogenen Taktstriche.

@strong{@emph{ChoirStaff}}

Entspricht @code{StaffGroup}, außer dass die Taktstriche der enthaltenen
Systeme nicht vertikal miteinander verbunden sind.

@strong{@emph{GrandStaff}}

Gruppiert Systeme mit einer geschweiften Klammer zur Linken.  Die
Taktlinien der enthaltenen Systeme werden vertikal verbunden.

@strong{@emph{PianoStaff}}

Entspricht @code{GrandStaff}, hat aber zusätzlich Unterstützung für
Instrumentenbezeichnungen zu Beginn jeder Systemgruppe.


@node Mittlere Kontexte -- Systeme
@unnumberedsubsubsec Mittlere Kontexte -- Systeme
@translationof Intermediate-level contexts - staves

Diese Kontexte stellen verschiedene Arten einzelner Notationssysteme
(engl. staff) dar.

@strong{@emph{Staff}}

Kümmert sich um Schlüssel, Taktstriche, Tonarten und Versetzungszeichen.
Er kann @code{Voice}-Kontexte enthalten.

@strong{@emph{RhythmicStaff}}

Entspricht @code{Staff}, aber dient zur Notation von Rhythmen: Tonhöhen
werden ignoriert und die Noten auf einer einzigen Linie ausgegeben.

@strong{@emph{TabStaff}}

Ein Kontext um Tabulaturen zu erstellen.  Die Standardeinstellung ist
eine Gitarrentabulatur mit sechs Notenlinien.

@strong{@emph{DrumStaff}}

Ein Kontext zur Notation von Perkussion.  Er kann
@code{DrumVoice}-Kontexte enthalten.

@strong{@emph{VaticanaStaff}}

Entspricht @code{Staff}, aber eignet sich besonders zum Notensatz des
Gregorianischen Chorals.

@strong{@emph{MensuralStaff}}

Entspricht @code{Staff}, aber eignet sich zum Notensatz von Noten in
der Mensuralnotation.


@node Unterste Kontexte -- Stimmen
@unnumberedsubsubsec Unterste Kontexte -- Stimmen
@translationof Bottom-level contexts - voices

Stimmen-(@code{Voice}-Kontexte initialisieren bestimmte Eigenschaften
und laden bestimmte Engraver.  Weil es sich bei Stimmen um die
untersten Kontexte handelt, können sie keine weiteren Kontexte enthalten.

@strong{@emph{Voice}}

Entspricht einer Stimme auf einem Notensystem.  Der Kontext kümmert sich
um die Umsetzung von Noten, Dynamikzeichen, Hälsen, Balken, diversen Texten,
Bögen und Pausen.  Wenn mehr als eine Stimme pro System benötigt wird,
muss dieser Kontext explizit initialisiert werden.

@strong{@emph{VaticanaVoice}}

Entspricht @code{Voice}, aber eignet sich besonders zum Notensatz
des Gregorianischen Chorals.

@strong{@emph{MensuralVoice}}

Entspricht @code{Voice}, aber mit Änderungen, um Mensuralnotation
setzen zu können.

@strong{@emph{Lyrics}}

Entspricht einer Stimme mit Gesangstext.  Kümmert sich um den Satz
des Gesangstextes auf einer Zeile.

@strong{@emph{DrumVoice}}

Der Stimmenkontext in einem Perkussionssystem.

@strong{@emph{FiguredBass}}

Der Kontext, in dem Generalbassziffern (@code{BassFigure}-Objekte)
gesetzt werden, die in der @code{\figuremode}-Umgebung
notiert werden.

@strong{@emph{TabVoice}}

Dieser Stimmenkontext wird in einer Tabulatur (@code{TabStaff}-Kontext)
benutzt.  Er wird normalerweise implizit erstellt.

@strong{@emph{CueVoice}}

Ein Stimmenkontext, der Noten in reduzierter Größe ausgibt und
vor allem dazu da ist, Stichnoten zu setzen.  Siehe auch
@ref{Stichnoten formatieren}.  Wird normalerweise implizit erstellt,
wenn Stichnoten gesetzt werden.


@strong{@emph{ChordNames}}

Ausgabe von Akkordsymbolen.


@node Kontexte erstellen
@subsection Kontexte erstellen
@translationof Creating contexts

In Partituren mit einer Stimme und einem System werden die Kontexte
normalerweise automatisch erstellt.  In komplizierteren Partituren
muss man sie aber direkt erstellen.  Es gibt drei Möglichkeiten,
Kontexte zu erstellen:

@funindex \new
@funindex \context
@funindex new
@funindex context

@cindex neue Kontexte
@cindex Kontexte erstellen
@cindex eigene Kontexte erstellen

@itemize

@item
Der einfachste Befehl ist @code{\new}.  Er wird zusammen mit dem
Kontextnamen vor einem musikalischen Ausdruck eingesetzt, etwa

@example
\new @var{Kontext} @var{musik. Ausdruck}
@end example

@noindent
wobei @var{Kontext} eine Kontextbezeichnung (wie @code{Staff} oder
@code{Voice}) ist.  Dieser Befehl erstellt einen neuen Kontext und
beginnt mit der Auswertung von @var{musik. Ausdruck} innerhalb
dieses Kontextes.

Eine praktische Anwendung von @code{\new} ist eine Partitur mit vielen
Systemen.  Jede Stimme wird auf einem eigenen System notiert, das
mit @code{\new Staff} begonnen wird.

@lilypond[quote,verbatim,relative=2,ragged-right]
<<
  \new Staff { c4 c }
  \new Staff { d4 d }
>>
@end lilypond

Der @code{\new}-Befehl kann den Kontext auch benennen:

@example
\new @var{Kontext} = @var{ID} @var{musik. Ausdruck}
@end example

Dieser vom Benutzer definierte Name wird aber auch nur wirklich
benutzt, wenn nicht vorher schon der gleiche Name definiert worden
ist.

@item
Ähnlich dem @code{\new}-Befehl wird auch mit dem @code{\context}-Befehl
ein musikalischer Ausdruck in einen Kontext umgeleitet.  Diesem
Kontext wird ein expliziter Name zugewiesen.  Die Syntax lautet:

@example
\context @var{Kontext} = @var{ID} @var{musik. Ausdruck}
@end example

Diese Art von Befehl sucht nach einem existierenden Kontext vom Typus
@var{Kontext} mit der Bezeichnung @var{ID}.  Wenn ein derartiger
Kontext nicht existiert, wird ein neuer Kontext mit der entsprechenden
Bezeichnung erstellt.  Das ist nützlich, wenn auf den Kontext später
zurückverwiesen werden soll.  Um etwa Gesangstext zu einer Melodie
hinzuzufügen, wird die Melodie in einem bezeichneten Kontext
notiert:

@example
\context Voice = "@b{Tenor}" @var{musik. Ausdruck}
@end example

@noindent
sodass der Text an den Noten ausgerichtet werden kann:

@example
\new Lyrics \lyricsto "@b{Tenor}" @var{Gesangstext}
@end example


Eine andere Möglichkeit für bezeichnete Kontexte ist es, zwei
unterschiedliche musikalische Ausdrücke in einen Kontext zu
verschmelzen.  Im nächsten Beispiel werden Artikulationszeichen
und Noten getrennt notiert:

@example
Noten = @{ c4 c4 @}
Artik = @{ s4-. s4-> @}
@end example

@noindent
Dann werden sie kombiniert, indem sie dem selben @code{Voice}-Kontext
zugewiesen werden:

@example
<<
  \new Staff \context Voice = "A" \Noten
  \context Voice = "A" \Artik
>>
@end example

@lilypond[quote,ragged-right]
music = { c4 c4 }
arts = { s4-. s4-> }
\relative c'' <<
  \new Staff \context Voice = "A" \music
  \context Voice = "A" \arts
>>
@end lilypond

Durch diesen Mechanismus ist es möglich eine Urtextausgabe zu
erstellen, mit der optionalen Möglichkeit, bestimmte zusätzliche
Artikulationszeichen zu den gleichen Noten hinzuzufügen und so
eine editierte Ausgabe zu erhalten.

@cindex Kontexte erstellen

@item
Der dritte Befehl, um Kontexte zu erstellen, ist:

@example
\context @var{Kontext} @var{musik. Ausdruck}
@end example

@noindent
Dies entspricht dem @code{\context} mit @code{= @var{ID}}, aber hier
wird ein beliebiger Kontext des Typs @var{Kontext} gesucht und der
musikalische Ausdruck darin ausgewertet, unabhängig von der Bezeichnung,
die dem Kontext gegeben wurde.

Diese Variante wird bei musikalischen Ausdrücken benutzt, die auf
verschiedenen Ebenen interpretiert werden können.  Beispielsweise
der @code{\applyOutput}-Befehl (siehe
@rextend{Eine Funktion auf alle Layout-Objekte anwenden}).  Ohne einen
expliziten @code{\context} wird die Ausgabe normalerweise einem
@code{Voice}-Kontext zugewiesen:

@example
\applyOutput #'@var{Kontext} #@var{Funktion}   % auf Voice anwenden
@end example

Damit aber die Funktion auf @code{Score}- oder @code{Staff}-Ebene
interpretiert wird, muss folgende Form benutzt werden:

@example
\applyOutput #'Score #@var{Funktion}
\applyOutput #'Staff #@var{Funktion}
@end example

@end itemize



@node Kontexte am Leben halten
@subsection Kontexte am Leben halten
@translationof Keeping contexts alive

@cindex Kontexte, am Leben erhalten
@cindex Kontexte, Lebensdauer

Kontexte werden normalerweise am ersten musikalischen Moment
beendet, an dem sie nichts mehr zu tun haben.  Ein
@code{Voice}-Kontext stirbt also sofort, wenn keine Ereignisse
mehr auftreten, @code{Staff}-Kontexte sobald alle in ihnen
enthaltenen @code{Voice}-Kontexte keine Ereignisse mehr aufweisen
usw.  Das kann Schwierigkeiten ergeben, wenn auf frühere
Kontexte verwiesen werden soll, die in der Zwischenzeit schon
gestorben sind, beispielsweise wenn man Systemwechsel mit
@code{\change}-Befehlen vornimmt, wenn Gesangstext einer
Stimme mit dem @code{\lyricsto}-Befehl zugewiesen wird oder
wenn weitere musikalische Ereignisse zu einem früheren Kontext
hinzugefügt werden sollen.

Es gibt eine Ausnahme dieser Regel: genau ein @code{Voice}-Kontext
innerhalb eines @code{Staff}-Kontextes oder in einer
@code{<<...>>}-Konstruktion bleibt immer erhalten bis zum Ende
des @code{Staff}-Kontextes oder der @code{<<...>>}-Konstruktion, der ihn einschließt, auch wenn es Abschnitte gibt, in der er nichts zu
tun hat.  Der Kontext, der erhalten bleibt ist immer der erste,
der in der ersten enthaltenden @code{@{...@}}-Konstruktion
angetroffen wird, wobei @code{<<...>>}-Konstruktionen ignoriert
werden.

Jeder Kontext kann am Leben gehalten werden, indem man sicherstellt
dass er zu jedem musikalischen Moment etwas zu tun hat.
@code{Staff}-Kontexte werden am Leben gehalten, indem man sicherstellt,
dass eine der enthaltenen Stimmen am Leben bleibt.  Eine Möglichkeit,
das zu erreichen, ist es, unsichtbare Pause zu jeder Stimme
hinzuzufügen, die am Leben gehalten werden soll.  Wenn mehrere
Stimmen sporadisch benutzt werden sollen, ist es am sichersten,
sie alle am Leben zu halten und sich nicht auf die Ausnahmeregel
zu verlassen, die im vorigen Abschnitt dargestellt wurde.

Im folgenden Beispiel werden sowohl Stimme A als auch B auf diese
Weise für die gesamte Dauer des Stückes am Leben gehalten.

@lilypond[quote,verbatim]
musicA = \relative c'' { d4 d d d }
musicB = \relative c'' { g4 g g g }
keepVoicesAlive = {
  <<
    \new Voice = "A" { s1*5 }  % Keep Voice "A" alive for 5 bars
    \new Voice = "B" { s1*5 }  % Keep Voice "B" alive for 5 bars
  >>
}

music = {
  \context Voice = "A" {
    \voiceOneStyle
    \musicA
  }
  \context Voice = "B" {
    \voiceTwoStyle
    \musicB
  }
  \context Voice = "A" { \musicA }
  \context Voice = "B" { \musicB }
  \context Voice = "A" { \musicA }
}

\score {
  \new Staff <<
    \keepVoicesAlive
    \music
  >>
}
@end lilypond

@cindex Gesangstext, an einer sporadischen Melodie ausrichten

Das nächste Beispiel zeigt eine Melodie, die zeitweise unterbrochen
wird und wie man den entsprechenden Gesangstext mit ihr verknüpfen
kann, indem man die Stimme am Leben hält.  In wirklichen Situationen
würden Begleitung und Melodie natürlich aus mehreren Abschnitten bestehen.

@lilypond[quote,verbatim]
melody = \relative c'' { a4 a a a }
accompaniment = \relative c' { d4 d d d }
words = \lyricmode { These words fol -- low the mel -- o -- dy }
\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne
          s1*4  % Keep Voice "melody" alive for 4 bars
        }
        {
          \new Voice = "accompaniment" {
            \voiceTwo
            \accompaniment
          }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
          \context Voice = "accompaniment" { \accompaniment }
          <<
            \context Voice = "melody" { \melody }
            \context Voice = "accompaniment" { \accompaniment }
          >>
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = #"music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond

Eine Alternative, die in manchen Umständen besser geeignet sein kann,
ist es, einfach unsichtbare Pausen einzufügen, um die Melodie
mit der Begleitung passend auszurichten:

@lilypond[quote,verbatim]
melody = \relative c'' {
  s1  % skip a bar
  a4 a a a
  s1  % skip a bar
  a4 a a a
}
accompaniment = \relative c' {
  d4 d d d
  d4 d d d
  d4 d d d
  d4 d d d
}
words = \lyricmode { These words fol -- low the mel -- o -- dy }

\score {
  <<
    \new Staff = "music" {
      <<
        \new Voice = "melody" {
          \voiceOne
          \melody
        }
        \new Voice = "accompaniment" {
          \voiceTwo
          \accompaniment
        }
      >>
    }
    \new Lyrics \with { alignAboveContext = #"music" }
    \lyricsto "melody" { \words }
  >>
}
@end lilypond



@node Umgebungs-Plugins verändern
@subsection Umgebungs-Plugins verändern
@translationof Modifying context plug-ins

Notationskontexte (wie @code{Score} oder @code{Staff}) speichern
nicht nur Eigenschaften, sie enthalten auch Plugins (@qq{engraver}
genannt), die die einzelnen Notationselemente erstellen.  Ein
@code{Voice}-Kontext enthält beispielsweise einen
@code{Note_heads_engraver}, der die Notenköpfe erstellt, und ein
@code{Staff}-Kontext einen @code{Key_signature_engraver}, der die
Vorzeichen erstellt.

Eine vollständige Erklärung jedes Plugins findet sich in
@ifhtml
@rinternals{Engravers and Performers}.
@end ifhtml
@ifnothtml
Referenz der Interna: @expansion{} Translation @expansion{} Engravers.
@end ifnothtml
Alle Kontexte sind erklärt in
@ifhtml
@rinternals{Contexts},
@end ifhtml
@ifnothtml
Referenz der Interna: @expansion{} Translation @expansion{} Context,
@end ifnothtml
wobei die in diesem Kontext vorkommenden Engraver aufgelistet sind.

Es kann teilweise nötig sein, diese Engraver umzupositionieren.  Das
geschieht, indem man einen neuen Kontext mit @code{\new} oder
@code{\context} beginnt und ihn dann verändert:

@funindex \with
@funindex with

@example
\new @var{context} \with @{
  \consists @dots{}
  \consists @dots{}
  \remove @dots{}
  \remove @dots{}
  @emph{etc.}
@}
@{
  @emph{..Noten..}
@}
@end example

@noindent
@dots{} steht hier für die Bezeichnung des Engravers.  @code{\consists}
fügt einen Engraver hinzu und @code{\remove} entfernt ihn.
Es folgt ein einfaches Beispiel, in dem der
@code{Time_signature_engraver} (Engraver für den Takt) und der
@code{Clef_engraver} (Engraver für den Schlüssel) aus dem
@code{Staff}-Kontext entfernt werden:

@lilypond[quote,relative=1,verbatim]
<<
  \new Staff {
    f2 g
  }
  \new Staff \with {
     \remove "Time_signature_engraver"
     \remove "Clef_engraver"
  } {
    f2 g2
  }
>>
@end lilypond

Das zweite Notensystem enthält keine Taktangabe und keinen Notenschlüssel.
Das ist eine recht brutale Methode, Objekte zu verstecken, weil es sich
auf das gesamte System auswirkt.  Diese Methode beeinflusst auch die
Platzaufteilung, was erwünscht sein kann.  Vielfältigere Methoden,
mit denen Objekte unsichtbar gemacht werden können, finden sich in
@rlearning{Sichtbarkeit und Farbe von Objekten}.

Das nächste Beispiel zeigt eine Anwendung in der Praxis.  Taktstriche
und Taktart werden normalerweise in einer Partitur synchronisiert.  Das
geschieht durch @code{Timing_translator} und @code{Default_bar_line_engraver}.
Diese Plugins sorgen sich um die Verwaltung der Taktzeiten und die
Stelle innerhalb des Taktes, zu dem eine Note erscheint usw.  Indem
man diese Engraver aus dem @code{Score}-Kontext in den @code{Staff}-Kontext
verschiebt, kann eine Partitur erstellt werden, in welcher
jedes System eine unterschiedliche Taktart hat:

@cindex polymetrische Partitur
@cindex Taktarten, mehrere in Partitur
@cindex Taktarten, unterschiedliche per System

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff \with {
      \consists "Timing_translator"
      \consists "Default_bar_line_engraver"
    } {
        \time 3/4
        c4 c c c c c
    }
  \new Staff \with {
    \consists "Timing_translator"
    \consists "Default_bar_line_engraver"
  } {
      \time 2/4
      c4 c c c c c
  }
>>
\layout {
  \context {
    \Score
    \remove "Timing_translator"
    \remove "Default_bar_line_engraver"
    }
  }
}
@end lilypond

@knownissues

Normalerweise spielt es keine Rolle, in welcher Reihenfolge
Engraver angegeben werden, aber in einigen Spezialfällen
ist die Reihenfolge sehr wichtig.  Das kann beispielsweise
vorkommen, wenn ein Engraver eine Eigenschaft erstellt und
ein anderer von ihr liest, oder ein Engraver erstellt ein
Grob und ein anderer wertet es aus.  Die Reihenfolge, in der
Engraver angegeben werden, ist die Reihenfolge, in der sie
aufgerufen werden, um ihre Tätigkeiten auszuführen.

Folgende Reihenfolgen müssen beachtet werden: der
@code{Bar_engraver} muss normalerweise zuerst kommen, und
der @code{New_fingering_engraver} muss vor dem
@code{Script_column_engraver} kommen.  Es gibt möglicherweise weitere
Abhängigkeiten von der Reihenfolge geben.


@node Die Standardeinstellungen von Kontexten ändern
@subsection Die Standardeinstellungen von Kontexten ändern
@translationof Changing context default settings

Die Kontexteinstellungen, die standardmäßig in
@code{Score}, @code{Staff} und @code{Voice}-Kontexten
benutzt werden, können in einer @code{\layout}-Umgebung
eingestellt werden, wie das folgende Beispiel zeigt.  Die
@code{\layout}-Umgebung sollte innerhalb der
@code{\score}-Umgebung gesetzt werden, auf die sie sich
auswirken soll, aber außerhalb von Notation.

Auch muss der @code{\set}-Befehl und der Kontext weggelassen
werden, wenn die Einstellungen für den Kontext auf diese Weise
vorgenommen werden:

@lilypond[quote,verbatim]
\score {
  \relative c'' {
    a4^"Really small, thicker stems, no time signature" a a a
    a a a a
  }
  \layout {
    \context {
      \Staff
      fontSize = #-4
      \override Stem #'thickness = #4.0
      \remove "Time_signature_engraver"
    }
  }
}
@end lilypond

Hier zeigt der @code{\Staff}-Befehl an, dass die folgenden Einstellungen
sich auf alle Systeme in dieser Partitur erstrecken sollen.

Veränderungen können auch für den @code{Score}- oder alle
@code{Voice}-Kontexte auf gleiche Weise vorgenommen werden.

Kontextänderungen können in eine Variable geschrieben werden und dann
einer @code{\context}-Definition zu gewiesen werden, indem man der
Veränderung ein @code{\with} voranstellt:

@lilypond[quote,verbatim]
blubb = \with {
  fontSize = #-4
  \override Stem #'thickness = #4.0
  \remove "Time_signature_engraver"
}

bla = \with {
  fontSize = #3
  \override Stem #'thickness = #-2.0
}

melody = \relative c'' {
  a4 a a a |
  a4 a a a |
}

\score {
  <<
    \new Staff <<
      \melody
      s1*0^"Small, thicker stems, no time signature"
    >>
    \new Staff \bla <<
      \melody
      s1*0^"Different"
    >>
  >>
  \layout {
    \context {
      \Staff
      \blubb
    }
  }
}
@end lilypond

 @c TODO: add \with in here.
 

@node Neue Kontexte definieren
@subsection Neue Kontexte definieren
@translationof Defining new contexts

@cindex Kontexte, neue definieren
@cindex Engraver, in Kontexte einfügen

@funindex \alias
@funindex alias
@funindex \name
@funindex name
@funindex \type
@funindex type
@funindex \consists
@funindex consists
@funindex \accepts
@funindex accepts
@funindex \denies
@funindex denies

Bestimme Kontexte, wie @code{Staff} oder @code{Voice}, werden
erstellt, indem man sie mit einer Musikumgebung aufruft.  Es ist
aber auch möglich, eigene neue Kontexte zu definieren, in denen
dann unterschiedliche Engraver benutzt werden.

Das folgende Beispiel zeigt, wie man etwa @code{Voice}-Kontexte
von Grund auf neu bauen kann.  Ein derartiger Kontext ähnelt
@code{Voice}, es werden aber nur zentrierte Schrägstriche als
Notenköpfe ausgegeben.  Das kann benutzt werden, um Improvisation
in Jazzmusik anzuzeigen.

@c KEEP LY
@lilypond[quote,ragged-right]
\layout { \context {
  \name ImproVoice
  \type "Engraver_group"
  \consists "Note_heads_engraver"
  \consists "Rhythmic_column_engraver"
  \consists "Text_engraver"
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead #'style = #'slash
  \override Stem #'transparent = ##t
  \override Flag #'transparent = ##t
  \alias Voice
}
\context { \Staff
  \accepts "ImproVoice"
}}

\relative c'' {
  a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
   c4 c^"ausziehen" c_"während des Spiels :)" c }
  a1
}
@end lilypond

Diese Einstellungen werden innerhalb der @code{\context}-Umgebung
innerhalb der @code{\layout}-Umgebung definiert:

@example
\layout @{
  \context @{
    @dots{}
  @}
@}
@end example

Der Beispielcode des folgenden Abschnittest muss anstelle der Punkte
im vorigen Beispiel eingesetzt werden.

Zuerst ist es nötig eine Bezeichnung für den neuen Kontext zu
definieren:

@example
\name ImproVoice
@end example

Weil dieser neue Kontext ähnlich wie @code{Voice} ist, sollen die Befehle,
die in @code{Voice}-Kontexten funktionieren, auch
in dem neuen Kontext funktionieren.  Das wird erreicht, indem der
Kontext als Alias @code{Voice} erhält:

@example
\alias Voice
@end example

Der Kontext gibt Noten und Text aus, darum müssen wir die Engraver
hinzufügen, die für diese Aktionen zuständig sind:

@example
\consists Note_heads_engraver
\consists Text_engraver
@end example

@noindent
aber die Noten sollen nur auf der mittleren Linie ausgegeben werden:

@example
\consists Pitch_squash_engraver
squashedPosition = #0
@end example

Der @code{Pitch_squash_engraver} verändert Notenköpfe (die vom
@code{Note_heads_engraver} erstellt werden) und setzt ihre vertikale
Position auf den Wert von @code{squashedPosition}, in diesem Fall ist
das die Mittellinie.

Die Noten sehen wie ein Querstrich aus und haben keine Hälse:

@example
\override NoteHead #'style = #'slash
\override Stem #'transparent = ##t
\override Flag #'transparent = ##t
@end example

Alle diese Engraver müssen zusammenarbeiten, und das wird erreicht mit
einem zusätzlichen Plugin, das mit dem Befehl @code{\type} gekennzeichnet
werden muss.  Dieser Typ solle immer @code{Engraver_group} lauten:

@example
\type "Engraver_group"
@end example

Alles zusammen haben wir folgende Einstellungen:

@example
\context @{
  \name ImproVoice
  \type "Engraver_group"
  \consists "Note_heads_engraver"
  \consists "Text_engraver"
  \consists Pitch_squash_engraver
  squashedPosition = #0
  \override NoteHead #'style = #'slash
  \override Stem #'transparent = ##t
  \override Flag #'transparent = ##t
  \alias Voice
@}
@end example

@funindex \accepts
@funindex accepts

Kontexte sind hierarchisch.  Wie wollen, dass @code{ImproVoice}
sich als Unterkontext von @code{Staff} erkennt, wie eine normale
Stimme.  Darum wird die Definition von @code{Staff} mit dem
@code{\accepts}-Befehl verändert:

@example
\context @{
  \Staff
  \accepts ImproVoice
@}
@end example

@funindex \denies
@funindex denies

Das Gegenteil von @code{\accepts} ist @code{\denies} (verbietet), was
manchmal gebraucht werden kann, wenn schon existierende Kontext-Definitionen
wieder benutzt werden sollen.

Beide Definitionen müssen in die @code{\layout}-Umgebung geschrieben
werden:

@example
\layout @{
  \context @{
    \name ImproVoice
    @dots{}
  @}
  \context @{
    \Staff
    \accepts "ImproVoice"
  @}
@}
@end example

Jetzt kann die Notation zu Beginn des Abschnitts folgendermaßen
notiert werden:

@example
\relative c'' @{
  a4 d8 bes8
  \new ImproVoice @{
    c4^"ad lib" c
    c4 c^"ausziehen"
    c c_"während des Spielens :)"
  @}
  a1
@}
@end example


@node Reihenfolge des Kontextlayouts
@subsection Reihenfolge des Kontextlayouts
@translationof Context layout order

@cindex Kontext, Layoutreihenfolge
@funindex \accepts
@funindex \denies

Kontexte werden in einer Systemgruppe normalerweise von oben nach
unten positioniert in der Reihenfolge, wie sie in der Quelldatei
auftreten.  Wenn Kontext verschachtelt ewrden, enthält der äußere
Kontexte geschachtelte innere Kontexte, wie in der Quelldatei
angegeben, vorausgesetzt, die inneren Kontexte befinden sich auch
in der @qq{accepts}-Liste.  Geschachtelte Kontexte, die nicht
in dieser @qq{accepts}-Liste enthalten sind, werden unterhalb
des äußeren Kontextes neu positioniert, anstatt innerhalb von ihm
gesetzt zu werden.

Die @qq{accepts}-Liste eines Kontextes kann mit dem Befehlen
@code{\accepts} und @code{\denies} verändert werden.  @code{\accepts} 
fügt einen Kontext zur @qq{accepts}-Liste, und @code{\denies}
entfernt einen Kontext aus der Liste.  Akkordbezeichnungen sollen
beispielsweise normalerweise nicht innerhalb eines @code{Staff}-Kontextes
geschachtelt werden, sodass der @code{ChordNames}-Kontext nicht
automatisch in der @qq{accepts}-Liste des @code{Staff}-Kontextes
geführt ist.  Wenn er aber benötigt wird, kann er hinzugefügt werden:

@lilypond[verbatim,quote]
\score {
  \new Staff {
    c' d' e' f'
    \chords { d1:m7 b1:min7.5- }
  }
}
@end lilypond

@lilypond[verbatim,quote]
\score {
  \new Staff {
    c' d' e' f'
    \chords { d1:m7 b1:min7.5- }
  }
  \layout {
    \context {
      \Staff
      \accepts "ChordNames"
    }
  }
}
@end lilypond

@code{\denies} wird vorrangig eingesetzt, wenn ein neuer Kontext
basierend auf einem existierenden erstellt wird, aber sein 
Schachtelungsverhalten sich unterscheidet.  Der
@code{VaticanaStaff}-Kontext beispielsweise basiert auf dem
@code{Staff}-Kontext, hat aber den @code{VaticanaVoice}-Kontext
anstellt des @code{Voice}-Kontexts in seiner @qq{accepts}-Liste.

Zur Erinnerung: ein Kontext wird automatisch erstellt, wenn ein
Befehl auftritt, der in den aktuellen Kontexten nicht enthalten
sein kann.  Dass kann zu unerwarteten neuen Systemgruppen oder Partituren
führen.

@seealso
Handbuch zur Benutzung:
@rprogram{Ein zusätzliches System erscheint}.

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


@node Die Referenz der Programminterna erklärt
@section Die Referenz der Programminterna erklärt
@translationof Explaining the Internals Reference

@menu
* Zurechtfinden in der Programmreferenz::
* Layout-Schnittstellen::
* Die Grob-Eigenschaften::
* Benennungskonventionen::
@end menu


@node Zurechtfinden in der Programmreferenz
@subsection Zurechtfinden in der Programmreferenz
@translationof Navigating the program reference

Arbeit mit der Referenz der Interna soll hier an
einigen Beispiel illustriert werden.  Die Referenz
der Interna existiert nur auf Englisch,
darum sind auch die Beispiele dieses Abschnittes nicht
übersetzt.

Folgende Aufgabe wird bearbeitet:  Der Fingersatz aus dem Beispiel
unten soll verändert werden:

@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond

In der Dokumentation über Fingersatz (in
@ref{Fingersatzanweisungen}) gibt es folgenden Abschnitt:

@quotation
@strong{Siehe auch:}

Referenz der Interna: @rinternals{Fingering}.

@end quotation

@c all ignored text just left out

@ifnothtml
Die Referenz der Interna gibt es als HTML-Dokument.  Sie sollten sie als
HTML-Dokument lesen, entweder online oder indem Sie die HTML-Dokumentation
herunterladen.  Dieser Abschnitt ist sehr viel schwieriger zu verstehen,
wenn Sie die PDF-Version verwenden.
@end ifnothtml

Gehen Sie über diesen Link zum Abschnitt @rinternals{Fingering}.
Oben auf der Seite findet sich:

@quotation
Fingering objects are created by: @rinternals{Fingering_engraver} and
@rinternals{New_fingering_engraver}.
@end quotation

Indem Sie die Links in der Referenz der Interna folgen, können Sie
verfolgen, wie LilyPond intern arbeitet:

@itemize

@item @rinternals{Fingering}:
@rinternals{Fingering} objects are created by:
@rinternals{Fingering_engraver}

@item @rinternals{Fingering_engraver}:
Music types accepted: @rinternals{fingering-event}

@item @rinternals{fingering-event}:
Music event type @code{fingering-event} is in Music expressions named
@rinternals{FingeringEvent}
@end itemize

@c translation of the above
Fingersatz-Objekte werden also durch den @code{Fingering_engraver}
erstellt, welcher folgende Musikereignistypen akzeptiert:
@code{fingering-event}.  Ein Musikereignis vom Typ
@code{fingering-event} ist ein musikalischer Ausdruck mit der
Bezeichnung @rinternals{FingeringEvent}.

Dieser Pfad geht genau die entgegengesetzte Richtung von LilyPonds
Wirkungsweise: er beginnt bei der graphischen Ausgabe und
arbeitet sich voran zur Eingabe.  Man könnte auch mit einem
Eingabe-Ereignis starten und dann die Links zurückverfolgen,
bis man zum Ausgabe-Objekt gelangt.


Die Referenz der Interna kann auch wie ein normales Dokument
durchsucht werden.  Sie enthält Kapitel über
@ifhtml
@rinternals{Music definitions},
@end ifhtml
@ifnothtml
@code{Music definitions},
@end ifnothtml
über @rinternals{Translation} und @rinternals{Backend}.  Jedes
Kapitel listet alle die Definitionen und Eigenschaften auf,
die benutzt und verändert werden können.


@node Layout-Schnittstellen
@subsection Layout-Schnittstellen
@translationof Layout interfaces

@cindex Layout-Schnittstelle
@cindex Schnittstelle, Layout-
@cindex Grob

Die HTML-Seite, die im vorigen Abschnitt betrachtet wurde,
beschreibt ein Layoutobjekt mit der Bezeichnung
@code{Fingering}.  Ein derartiges Objekt ist ein Symbol
in der Partitur.  Es hat Eigenschaften, die bestimmte
Zahlen speichern (wie etwa Dicke und Richtung), aber auch
Weiser auf verwandte Objekte.  Ein Layoutobjekt wird auch
als @qq{Grob} bezeichnet, die Abkürzung für @emph{Gr}aphisches
@emph{Ob}jekt.  Mehr Information zu Grobs findet sich in
@rinternals{grob-interface}.

Die Seite zu @code{Fingering} enthält Definitionen für das
@code{Fingering}-Objekt.  Auf der Seite steht etwa:

@quotation
@code{padding} (dimension, in staff space):

@code{0.5}
@end quotation

@noindent
was bedeutet, dass der Abstand zu anderen Objekten mindestens
0.5 Notenlinienabstände beträgt.

Jedes Layoutobjekt kann mehrere Funktionen sowohl als typographisches
als auch als Notationselement einnehmen.  Das Fingersatzobjekt
beispielsweise hat folgende Aspekte:

@itemize
@item
Seine Größe ist unabhängig von der horizontalen Platzaufteilung,
anders als etwa bei Legatobögen.

@item
Es handelt sich um Text, normalerweise sehr kurz.

@item
Dieser Text wird durch ein Glyph einer Schriftart gesetzt,
anders als bei Legatobögen.

@item
Der Mittelpunkt des Symbols sollte horizontal mit dem
Mittelpunkt des Notenkopfes ausgerichtet werden.

@item
Vertikal wird das Objekt neben die Note und das Notensystem
gesetzt.

@item
Die vertikale Position wird auch mit anderen Textelementen
abgeglichen.

@end itemize

Jeder dieser Aspekte findet sich in sogenannten Schnittstellen
(engl. interface), die auf der @rinternals{Fingering}-Seite
unten aufgelistet sind:

@quotation
This object supports the following interfaces:
@rinternals{item-interface},
@rinternals{self-alignment-interface},
@rinternals{side-position-interface}, @rinternals{text-interface},
@rinternals{text-script-interface}, @rinternals{font-interface},
@rinternals{finger-interface}, and @rinternals{grob-interface}.
@end quotation

Ein Klick auf einen der Links öffnet die Seite der entsprechenden
Schnittstelle.  Jede Schnittstelle hat eine Anzahl von Eigenschaften.
Einige sind nicht vom Benutzer zu beeinflussen (@qq{interne
Eigenschaften}), andere aber können verändert werden.

Es wurde immer von einem @code{Fingering}-Objekt gesprochen, aber
eigentlich handelt es sich nicht um sehr viel.  Die Initialisierungsdatei
@file{scm/define-grobs.scm} zeigt den Inhalt dieses @qq{Objekts}
(zu Information, wo diese Dateien sich finden siehe
@rlearning{Mehr Information}):

@example
(Fingering
  . ((padding . 0.5)
     (avoid-slur . around)
     (slur-padding . 0.2)
     (staff-padding . 0.5)
     (self-alignment-X . 0)
     (self-alignment-Y . 0)
     (script-priority . 100)
     (stencil . ,ly:text-interface::print)
     (direction . ,ly:script-interface::calc-direction)
     (font-encoding . fetaText)
     (font-size . -5)           ; don't overlap when next to heads.
     (meta . ((class . Item)
     (interfaces . (finger-interface
                    font-interface
                    text-script-interface
                    text-interface
                    side-position-interface
                    self-alignment-interface
                    item-interface))))))
@end example

@noindent
Wie man sehen kann, ist das Fingersatzobjekt nichts anderes als
eine Ansammlung von Variablen, und die Internetseite der
Referenz der Interna ist direkt aus diesen Anweisungen generiert.


@node Die Grob-Eigenschaften
@subsection Die Grob-Eigenschaften
@translationof Determining the grob property

Die Position der @b{2} aus dem Beispiel unten soll also geändert werden:

@lilypond[quote,relative=2,verbatim]
c-2
\stemUp
f
@end lilypond

Weil die @b{2} vertikal an der zugehörigen Note ausgerichtet ist,
müssen wir uns mit der Schnittstelle auseinander setzen, die diese
Positionierung veranlasst.  Das ist hier @code{side-position-interface}.
Auf der Seite für diese Schnittstelle heißt es:

@quotation
@code{side-position-interface}

Position a victim object (this one) next to other objects (the
support).  The property @code{direction} signifies where to put the
victim object relative to the support (left or right, up or down?)
@end quotation

@cindex Verschiebung

@noindent
Darunter wird die Variable @code{padding} (Verschiebung) beschrieben:

@quotation
@table @code
@item padding
(dimension, in staff space)

Add this much extra space between objects that are next to each other.
@end table
@end quotation

Indem man den Wert von @code{padding} erhöht, kann die Fingersatzanweisung
weiter weg von der Note gesetzt werden.  Dieser Befehl beispielsweise
fügt drei Notenlinienzwischenräume zwischen die Zahl und den Notenkopf:

@example
\once \override Voice.Fingering #'padding = #3
@end example

Wenn dieser Befehl in den Quelltext eingefügt wird, bevor der
Fingersatz notiert ist, erhält man folgendes:

@lilypond[quote,relative=2,verbatim]
\once \override Voice.Fingering #'padding = #3
c-2
\stemUp
f
@end lilypond

In diesem Fall muss die Veränderung speziell für den @code{Voice}-Kontext
definiert werden.  Das kann auch aus der Referenz der Interna entnommen
werden, da die Seite des @rinternals{Fingering_engraver} schreibt:

@quotation
Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
@end quotation


@node Benennungskonventionen
@subsection Benennungskonventionen
@translationof Naming conventions

Die Bezeichnungen für Funktionen, Variablen, Engraver und Objekte
folgen bestimmten Regeln:

@itemize

@item
    Scheme-Funktionen: kleinbuchstaben-mit-bindestrichen

@item
    Scheme-Funktionen: ly:plus-scheme-stil

@item
    Musikalische Ereignisse, Musikklassen und Musikeigenschaften: wie-scheme-funktionen

@item
    Grob-Schnittstellen: scheme-stil

@item
    backend-Eigenschaften: scheme-stil (aber X und Y)

@item
    Kontexte: Großbuchstabe, oder GroßbuchstabeZwischenWörtern (CamelCase)

@item
    Kontext-Eigenschaften: kleinbuchstabeMitFolgendenGroßbuchstaben

@item
    Engraver:  Großbuchstabe_gefolgt_von_kleinbuchstaben_mit_unterstrichen
@end itemize

@c todos left out


@node Eigenschaften verändern
@section Eigenschaften verändern
@translationof Modifying properties

@menu
* Grundlagen zum Verändern von Eigenschaften::
* Der set-Befehl::
* Der override-Befehl::
* Der tweak-Befehl::
* set versus override::
* Alisten verändern::
@end menu


@node Grundlagen zum Verändern von Eigenschaften
@subsection Grundlagen zum Verändern von Eigenschaften
@translationof Overview of modifying properties

Jeder Kontext ist verantwortlich für die Erstellung bestimmter
graphischer Objekte.  Die Einstellungen für diese Objekte werden
auch in dem Kontext gespeichert.  Wenn man diese Einstellungen
verändert, kann die Erscheinung der Objekte geändert werden.

Es gibt zwei unterschiedliche Eigenschaftenarten, die in Kontexten
gespeichert werden: Kontexteigenschaften und Grob-Eigenschaften.
Kontexteigenschaften sind Eigenschaften, die sich auf den gesamten Kontext
beziehen und seine Darstellung beinflussen.  Grob-Eigenschaften dagegen
wirken sich nur auf bestimmte graphische Objekte aus, die in einem
Kontext dargestellt werden.

Die @code{\set}- und @code{\unset}-Befehle werden benutzt, um die Werte
von Kontexteigenschaften zu ändern.  Die Befehle @code{\override} und
@code{\revert} hingegen verändern die Werte von Grob-Eigenschaften.

@ignore
Die Syntax hierzu lautet:

@example
\override @var{Kontext}.@var{Bezeichnung} #'@var{Eigenschaft} = #@var{Wert}
@end example


@var{Bezeichnung} ist die Bezeichnung eines graphischen Objekts,
wie @code{Stem} (Hals) oder @code{NoteHead} (Notenkopf), und
@var{Eigenschaft} ist eine interne Variable des Formatierungssystems
(eine @qq{Grob-Eigenschaft} oder @qq{Layout-Eigenschaft}).  Diese
Eigenschaft ist ein Symbol, muss also mit einem Anführungsstrich
versehen werden.  Wie die Felder @var{Bezeichnung}, @var{Eigenschaft}
und @var{Wert} richtig gefüllt werden, zeigt der Abschnitt
@ref{Eigenschaften verändern}.  Hier wird nur die Funktionalität des
Befehls betrachtet.

Der Befehl

@verbatim
\override Staff.Stem #'thickness = #4.0
@end verbatim

@noindent
bewirkt, dass der Notenhals dicker gesetzt wird (Standard ist
1.3, die Dicke der Notenlinie entspricht dem Wert 1).  Da der
Befehl den Kontext @code{Staff} angibt, wirkt er sich nur auf
das gerade aktuelle Notensystem aus.  Andere Systeme behalten
ihr normales Aussehen.  Hier ein Beispiel mit diesem Befehl:

@lilypond[quote,verbatim,relative=2]
c4
\override Staff.Stem #'thickness = #4.0
c4
c4
c4
@end lilypond

Der @code{\override}-Befehl verändert die Definitionen von
@code{Stem} (Hals) innerhalb des aktuellen @code{Staff}
(Notensystems).  Nachdem der Befehl gelesen wurde, werden
alle Hälse dicker gesetzt.

Wie auch bei dem @code{\set}-Befehl kann auch hier der
Kontext ausgelassen werden, wobei dann immer implizit der
@code{Voice}-Kontext angenommen wird.  Mit einem zusätzlichen
@code{\once} wirkt sich die Änderung nur einmal aus:

@lilypond[quote,verbatim,relative=2]
c4
\once \override Stem #'thickness = #4.0
c4
c4
@end lilypond

Der @code{\override}-Befehl muss geschrieben sein, bevor das Objekt
begonnen wird.  Wenn also ein @emph{Strecker}-Objekt wie etwa
ein Bogen verändert werden soll, muss der @code{\override}-Befehl
schon geschrieben werden, bevor das Objekt begonnen wird.  In dem
folgenden Beispiel

@lilypond[quote,verbatim,relative=2]
\override Slur #'thickness = #3.0
c8[( c
\override Beam #'beam-thickness = #0.6
c8 c])
@end lilypond

@noindent
ist der Bogen dicker, der Balken aber nicht.  Das liegt daran, dass der Befehl
zum Ändern des @code{Beam}-Objekts erst gesetzt wurde, nachdem der Balken
schon begonnen hat.

Der @code{\revert}-Befehl macht alle Änderungen rückgängig, die mit einem
@code{\override}-Befehl vorgenommen worden sind, dabei werden allerdings
nur Einstellungen betroffen, die sich im gleichen Kontext befinden.  Der
@code{\revert}-Befehl des folgenden Beispiels bewirkt also gar nichts,
weil er für den falschen Kontext gefordert wird.

@example
\override Voice.Stem #'thickness = #4.0
\revert Staff.Stem #'thickness
@end example

Einige veränderbare Optionen werden als Untereigenschaften (engl.
subproperties) bezeichnet und befinden sich innerhalb von den
normalen Eigenschaften.  Wenn man sie verändern will, nimmt der
Befehl folgende Form an:

@c leave this as a long long
@example
\override @var{Kontext}.@var{Bezeichnung} #'@var{Eigenschaft} #'@var{Untereigenschaft} = #@var{Wert}
@end example

@noindent
wie beispielsweise

@example
\override Stem #'(details beamed-lengths) = #'(4 4 3)
@end example
@end ignore

@seealso
Referenz der Interna:
@rinternals{OverrideProperty},
@rinternals{RevertProperty},
@rinternals{PropertySet},
@rinternals{Backend},
@rinternals{All layout objects}.


@knownissues

Das Back-end ist nicht sehr streng bei der Überprüfung
der Typen von Objekteigenschaften.  Auf sich selbst verweisende
Bezüge in Scheme-Werten der Eigenschaften können Verzögerung
oder einen Absturz des Programms hervorrufen.



@node Der set-Befehl
@subsection Der @code{@bs{}set}-Befehl
@translationof The set command

@cindex Eigenschaften
@cindex Verändern von Eigenschaften

@funindex \set
@funindex set

Jeder Kontext kann unterschiedliche @emph{Eigenschaften} besitzen,
Variablen, die in diesem Kontext definiert sind.  Sie können
während der Interpretation des Kontextes verändert werden.  Hierzu
wird der @code{\set}-Befehl eingesetzt:

@example
\set @var{Kontext}.@var{Eigenschaft} = #@var{Wert}
@end example

@var{Wert} ist ein Scheme-Objekt, weshalb ihm@tie{}@code{#} vorangestellt
werden muss.

Kontexteigenschaften werden üblicherweise mit @code{kleinGroßbuchstabe}
benannt.  Sie kontrollieren vor allem die Übersetzung von Musik in
Notation, wie etwa @code{localKeySignature}, welche bestimmt, wann
ein Taktstrich gesetzt werden muss.  Kontexteigenschaften können
ihren Wert mit der Zeit ändern, während eine Notationsdatei interpretiert
wird.  Ein gutes Beispiel dafür ist @code{measurePosition}, was die
Position der Noten im Takt angibt.  Kontexteigenschaften werden mit dem
@code{\set}-Befehl verändert.

Mehrtaktpausen etwa können in einen Takt zusammengefasst werden, wenn die
Kontexteigenschaft @code{skipBars} (Takte überspringen) auf @code{#t}
(wahr) gesetzt wird:

@lilypond[quote,verbatim,relative=2]
R1*2
\set Score.skipBars = ##t
R1*2
@end lilypond

Wenn das @var{Kontext}-Argument ausgelassen wird, bezieht sich
der Befehl auf den gerade aktiven unterstmöglichen Kontext,
üblicherweise @code{ChordNames}, @code{Voice} oder
@code{Lyrics}.

@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##f
<<
  {
    e8 e e e
    \set autoBeaming = ##t
    e8 e e e
  } \\ {
    c8 c c c c8 c c c
  }
>>
@end lilypond

Die Änderung wird zur Laufzeit während der Musik interpretiert, sodass
diese Einstellung sich nur auf die zweite Gruppe von Achteln auswirkt.

Dabei gilt zu beachten, dass der unterste Kontext nicht immer die
Eigenschaft enthält, die verändert werden soll.  Wenn man
beispielsweise @code{skipBars} aus dem oberen Beispiel
ohne Angabe des Kontextes zu verändern sucht, hat der Befehl
keine Auswirkung, weil er sich auf den @code{Voice}-Kontext
bezieht, die Eigenschaft sich aber im @code{Score}-Kontext
befindet:

@lilypond[quote,verbatim,relative=2]
R1*2
\set skipBars = ##t
R1*2
@end lilypond

Kontexte sind hierarchisch angeordnet.  Wenn ein übergeordneter
Kontext angegeben wird, etwa @code{Staff}, dann beziehen sich
die Änderungen auf alle Stimmen (@code{Voice}), die in diesem
Kontext enthalten sind.

@funindex \unset
@funindex unset

Es gibt auch einen @code{\unset}-Befehl:

@example
\unset @var{Kontext}.@var{Eigenschaft}
@end example

@noindent
der bewirkt, dass die vorgenommenen Definitionen für @var{Eigenschaft}
entfernt werden.  Dieser Befehl macht nur Einstellungen im richtigen
Kontext rückgängig.  Wenn also im @code{Staff}-Kontext die
Bebalkung ausgeschaltet wird:

@lilypond[quote,verbatim,relative=2]
\set Score.autoBeaming = ##t
<<
  {
    \unset autoBeaming
    e8 e e e
    \unset Score.autoBeaming
    e8 e e e
  } \\ {
    c8 c c c c8 c c c
  }
>>
@end lilypond

Wie für @code{\set} muss das @var{Kontext}-Argument für den untersten
Kontext nicht mitangegeben werden.  Die zwei Versionen

@example
\set Voice.autoBeaming = ##t
\set autoBeaming = ##t
@end example

verhalten sich gleich, wenn die gegenwärtige Basis der
@code{Voice}-Kontext ist.

@funindex \once
@funindex once

Einstellungen, die nur einmal vorgenommen werden sollen, können
mit @code{\once} notiert werden, etwa:

@lilypond[quote,verbatim,relative=2]
c4
\once \set fontSize = #4.7
c4
c4
@end lilypond

Eine vollständige Beschreibung aller vorhandenen Kontexteigenschaften
findet sich in der Referenz der Interna, siehe
@ifhtml
@rinternals{Tunable context properties}.
@end ifhtml
@ifnothtml
@qq{Translation @expansion{} Tunable context properties}.
@end ifnothtml

@seealso

Internals Reference:

@rinternals{Tunable context properties}.



@node Der override-Befehl
@subsection Der @code{\\override}-Befehl
@translationof The override command

@cindex Grob-Eigenschaften
@cindex Eigenschaften von Grob
@cindex graphische Objekte, Eigenschaften

@funindex \override
@funindex override

Es gibt eine besondere Art von Kontexteigenschaft: die Grob-Beschreibung.
Grob-Beschreibungen werden mit @code{GroßGroßbuchstabe} benannt.  Sie
enthalten @qq{Standardeinstellungen} für ein bestimmtes Grob als eine
assoziative Liste.  Siehe @file{scm/define-grobs.scm} für die
Einstellungen aller Grob-Beschreibungen.  Grob-Beschreibungen werden
mit @code{\override} verändert.

@code{\override} ist eigentlich eine Kurzform, der Befehl

@example
\override @var{Kontext}.@var{GrobBezeichnung} #'@var{Eigenschaft} = #@var{Wert}
@end example

ist äquivalent zu

@example
\set @var{Kontext}.@var{GrobBezeichnung}  =
  #(cons (cons '@var{Eigenschaft} @var{Wert})
         <vorheriger Wert von @var{Kontext}.@var{GrobBezeichnung}>)
@end example

Der Wert von @code{Kontext}.@code{GrobBezeichnung} (die assoz. Liste @qq{alist}) wird benutzt um die Eigenschaften von individuellen Grobs
zu initialisieren.  Grobs haben Eigenschaften, die im Scheme-Stil mit
@code{bindestrich-wörtern} benannt sind.  Diese Werte der Grob-Eigenschaften
verändern sich während des Notensetzens:  LilyPonds Notensatz heißt im
Grunde, die Eigenschaften mit Callback-Fuktionen auszurechnen.

Beispielsweise kann die Dicke eines Notenhalses verändert werden, indem
man die @code{thickness}-Eigenschaft des @code{Stem}-Objekts verändert:

@lilypond[quote, verbatim, relative=2]
c4 c
\override Voice.Stem #'thickness = #3.0
c4 c
@end lilypond

Wenn kein Kontext angegeben wird, wird der tiefste aktuelle Kontext
benutzt:

@lilypond[quote, verbatim, relative=2]
{ \override Staff.Stem #'thickness = #3.0
  <<
    {
      e4 e
      \override Stem #'thickness = #0.5
      e4 e
    } \\ {
      c4 c c c
    }
  >>
}
@end lilypond

@cindex rückgängig machen von Kontextveränderungen
@cindex Kontextveränderungen rückgängig machen
@cindex override rückgängig machen
@cindex \override rückgängig machen

@funindex \revert
@funindex revert

Die Auswirkungen von @code{\override} können mit @code{\revert} wieder
rückgängig gemacht werden:

@lilypond[quote, verbatim, relative=2]
c4
\override Voice.Stem #'thickness = #3.0
c4 c
\revert Voice.Stem #'thickness
c4
@end lilypond

Die Auswirkungen von @code{\override} und @code{\revert} wirken sich auf alle
Grobs im entsprechenden Kontext aber der Stelle aus, an der sie gesetzt werden:

@lilypond[quote, verbatim, relative=2]
{
  <<
    {
      e4
      \override Staff.Stem #'thickness = #3.0
      e4 e e
    } \\ {
      c4 c c
      \revert Staff.Stem #'thickness
      c4
    }
  >>
}
@end lilypond

@cindex Veränderung von Kontexten nur einmal
@cindex Einmal verändern von Kontexten
@cindex Kontexte, einmal verändern
@cindex \override, nur einmal

@funindex \once
@funindex once

@code{\once} kann zusammen mit @code{\override} benutzt werden,
um nur den aktuellen Zeitwert zu verändern:

@lilypond[quote, verbatim, relative=2]
{
  <<
    {
      \override Stem #'thickness = #3.0
      e4 e e e
    } \\ {
      c4
      \once \override Stem #'thickness = #3.0
      c4 c c
    }
  >>
}
@end lilypond


@ignore
@cindex Referenz der Interna
@cindex Grafische Objekte, Finden
@cindex Finden von graphischen Objekten
@cindex Beschreibung von graphischen Objekten
@cindex Grafische Objekte, Beschreibung
@cindex Grob, Beschreibung
@cindex Veränderungen der Einstellungen
@cindex Einstellungen verändern

@funindex override
@funindex \override

Viele Eigenschaften können unabhängig von der Art der Daten, die
sie enthalten, ausgeschaltet werden, indem man sie als @qq{falsch}
(@code{#f}) definiert.  Dadurch wird diese Eigenschaft von LilyPond
ignoriert.  Das ist insbesondere nützlich, wenn man Grob-Eigenschaften
ausschalten will, die Probleme verursachen.
@end ignore


@seealso

Referenz der Interna:
@rinternals{Backend}.


@node Der tweak-Befehl
@subsection Der @code{\\tweak}-Befehl
@translationof The tweak command

@funindex \tweak
@funindex tweak

@cindex Optimieren

Wenn man Grob-Eigenschaften mit @code{\override} verändert, verändern sich
alle fraglichen Objekte zu dem gegebenen musikalischen Moment.  Manchmal
will man allerdings nur ein Grob verändern, anstatt allen Grobs des
aktuellen Kontextes.  Das kann mit dem @code{\tweak}-Befehl erreicht
werden, mit dem man Optimierungen vornehmen kann:

@example
\tweak #'@code{grob-eigenschaft} #@code{Wert}
@end example

Der @code{\tweak}-Befehl wirkt sich auf das Objekt aus, dass direkt auf
@code{Wert} folgt.

@ignore
In einigen Fällen ist es möglich, mit einem abgekürzten Befehl
graphische Objekte zu verändern.  Wenn Objekte direkt von einem
Element des Quelltextes erstellt werden, kann der @code{\tweak}-Befehl
eingesetzt werden:

@lilypond[relative=2,verbatim]
< c
  \tweak #'color #red
  d
  g
  \tweak #'duration-log #1
  a
> 4
-\tweak #'padding #8
-^
@end lilypond

@cindex Akkord, eine Note verändern

Die hauptsächliche Benutzung von @code{\tweak} ist dann, wenn
man nur ein Element von einer Ansammlung an Elementen verändern
will, die alle zum gleichen musikalischen Moment beginnen.  Das
kann eine Noten in einem Akkord sein, oder eine von mehreren
Triolenklammern, die zur gleichen Zeit beginnen.

Eine Einleitung der Syntax für den @code{\tweak}Befehl findet
sich in @rlearning{Optimierungsmethoden}.

Der @code{\tweak}-Befehl verändert die Eigenschaft des folgenden
Objekts direkt, ohne dass die Bezeichnung des Objekts (Grobs) oder
des Kontextes angegeben werden muss.  Damit das funktioniert, muss
das Objekt direkt auf den @code{\tweak}-Befehl folgen, auf das
er sich auswirken soll.  Das ist in manchen Fällen nicht gegeben,
da viele Objekte durch LilyPond automatisch eingesetzt werden.
Wenn etwa eine Note interpretiert wird, die nicht Teil eines
Akkords ist, fügt LilyPond implizit einen @code{ChordEvent}
vor die Note ein, sodass der @code{\tweak}-Befehl von der
Note getrennt wird.  Wenn aber Akkord-Klammern um die Note
und den @code{\tweak}-Befehl gesetzt werden, folgt der
@code{ChordEvent} auf den @code{\tweak}-Befehl und befindet
sich deshalb direkt vor der Note, auf die er einwirken soll,
sodass die Veränderung funktioniert.

An einem Beispiel demonstriert:  Das funktioniert:


@lilypond[relative=2,verbatim,quote]
<\tweak #'color #red c>4
@end lilypond

@noindent
und das nicht:

@lilypond[relative=2,verbatim,quote]
\tweak #'color #red c4
@end lilypond

@end ignore

Eine Einleitung der Syntax und Benutzungen des @code{\tweak}-(Optimierungs)-Befehls findet sich in @rlearning{Optimierungsmethoden}.

Wenn mehrere gleichartige Elemente zum gleichen musikalischen
Moment auftreten, kann der @code{\override}-Befehl nicht
benutzt werden, um nur einen von ihnen zu verändern: hier braucht
man den @code{\tweak}-Befehl.  Elemente, die mehrfach zum
gleichen musikalischen Moment auftreten können sind unter Anderem:

@c TODO expand to include any further uses of \tweak
@itemize
@item Notenköpfe von Noten innerhalb eines Akkordes
@item Artikulationszeichen an einer einzelnen Note
@item Bindebögen zwischen Noten eines Akkordes
@item Llammern für rhythmische Verhältnisse (wie Triolen), die zur gleichen Zeit beginnen
@end itemize

@c TODO add examples of these

@cindex Akkord, eine Noten verändern

In diesem Beispiel wird die Farbe eines Notenkopfes und die Art eines
anderen Notenkopfes innerhalb eines Akkordes verändert:

@lilypond[relative=2,verbatim,quote]
< c
  \tweak #'color #red
  d
  g
  \tweak #'duration-log #1
  a
> 4
@end lilypond

@code{\tweak} kann auch benutzt werden, um Bögen zu verändern:

@lilypond[verbatim,quote,relative=1]
c-\tweak #'thickness #5 ( d e f)
@end lilypond

Damit der @code{\tweak}-Befehl funktioniert, muss er direkt vor dem
Objekt stehen, auf das er sich bezieht.  Manchmal kommt es vor, dass
LilyPond während der Kompilierung der Datei zusätzliche Elemente
einfügt, die dann zwischen der Optimierung und dem Objekt stehen.
Noten, auch einzlene Noten, werden beispielsweise intern von LilyPond
immer wie Akkorde behandelt, sodass auch ein @code{\tweak}-Befehl
für eine einzelne Note innerhalb von Akkordzeichen notiert werden
muss:

@lilypond[relative=2,verbatim,quote]
\tweak #'color #red c4
<\tweak #'color #red c>4
@end lilypond

Der @code{\tweak}-Befehl kann @emph{nicht} eingesetzt werden, um
Elemente zu verändern, die sich nicht direkt im Notentext befinden.
Insbesondere Hälse, Balken oder Versetzungszeichen lassen sich nicht
beeinflussen, weil diese später durch den Notenkopf erstellt werden
und nicht direkt durch
den Quelltext.  @code{\tweak} kann auch nicht verwendet werden,
um Schlüssel oder Taktarten zu verändern, denn sie werden von
dem @code{\tweak}-Befehl während der Interpretation durch
automatisches Einfügen von zusätzlichen Kontextelementen getrennt.

Mehrere @code{\tweak}-Befehle können vor ein Notationselement
gesetzt werden und alle werden interpretiert:

@lilypond[verbatim,quote,relative=1]
c
-\tweak #'style #'dashed-line
-\tweak #'dash-fraction #0.2
-\tweak #'thickness #3
-\tweak #'color #red
 \glissando
f'
@end lilypond

Der Strom der musikalischen Ereignisse (engl. music stream), der aus
dem Quelltext erstellt wird, und zu dem auch die automatisch eingefügten
Elemente gehören, kann betrachtet werden, siehe
@rextend{Musikalische Funktionen darstellen}.  Das kann nützlich sein,
wenn man herausfinden will, was mit dem @code{\tweak}-Befehl
verändert werden kann.

@seealso
Handbuch zum Lernen:
@rlearning{Optimierungsmethoden}.

Erweitern:
@rextend{Musikalische Funktionen darstellen}.

@knownissues

@cindex tweak-Befehl in einer Variable
@cindex Variable, tweak-Befehl benutzen
@cindex Optimierung innerhalb einer Variable

Der @code{\tweak}-Befehl kann nicht innerhalb von einer Variable eingesetzt werden.

@cindex tweaks-Befehl in Gesangstext
@cindex lyrics und tweak-Befehl
@cindex Gesangstext und tweak-Befehl

Der @code{\tweak}-Befehl kann nicht innerhalb von @code{\lyricmode} eingesetzt werden.

@cindex Kontrollpunkte und tweak
@cindex tweak und Kontrollpunkte

Der @code{\tweak}-Befehl kann nicht benutzt werden, um die Kontrollpunkte
eines von mehreren Bindebögen eines Akkorden zu verändern. Anstelle dessen
wird der erste Bogen verändert, der in der Eingabedatei auftritt.


@node set versus override
@subsection @code{\\set} versus @code{\\override}
@translationof set versus override

@c TODO: überflüssig?

@ignore
Es wurden zwei unterschiedliche Methoden vorgestellt, mit denen
Eigenschaften verändert werden können: @code{\set} und
@code{\override}.  Im Grunde genommen gibt es auch zwei
unterschiedliche Arten von Eigenschaften.

Kontexte können Eigenschaften haben, deren Bezeichnungen
üblicherweise dem Schema @code{kleinGroß} folgen.  Derartige
Eigenschaften sind vor allen Dingen für die Übersetzung der
Musik in Notation zuständig, beispielsweise @code{localKeySignature}
(um zu bestimmen, ob Versetzungszeichen ausgegeben werden
müssen), @code{measurePosition} (um zu bestimmen, ob eine
Taktlinie gesetzt werden muss).  Kontexteigenschaften können
ihren Wert verändern, während ein Musikstück ausgewertet wird;
@code{measurePosition} (Taktposition) ist ein gutes Beispiel
hierfür.  Kontexteigenschaften werden mit dem Befehl @code{\set}
verändert.

Dann gibt es einen Spezialtyp der Kontexeigenschaften: die
Elementbeschreibung.  Diese Eigenschaften werden mit
@code{GroßGroß} benannt (beginnen also auch mit einem
Großbuchstaben).  Sie beinhalten die Standardeinstellungen
für die besagten graphischen Objekte in Form einer
Assosiationsliste.  Siehe auch die Datei @file{scm/define-grobs.scm}
für ein Beispiel zu diesen Einstellungen.  Elementbeschreibungen
können mit dem Befehl @code{\override} verändert werden.

@code{\override} ist eigentlich eine Abkürzung:

@example
\override @var{Kontext}.@var{Bezeichnung} #'@var{Eigenschaft} = #@var{Wert}
@end example

@noindent
entspricht mehr oder weniger:

@c  leave this long line -gp
@example
\set @var{Kontext}.@var{Bezeichnung} #'@var{Eigenschaft} = #(cons (cons '@var{Eigenschaft} @var{Wert}) <voriger Wert von @var{Kontext})
@end example

Der Wert von @code{context} (die @qq{alist}) wird benutzt, um
die Eigenschaften von einzelnen Grobs zu initiieren.  Grobs haben
auch Eigenschaften, die im Scheme-Stil benannt werden, also
@code{wort-mit-bindestrich}.  Die Werte der Grob-Eigenschaften
ändern sich während des Formatierungsprozesses: Formatierung
läuft im Prinzip darauf hinaus, Eigenschaften zu errechnen, indem
Callback-Funktionen eingesetzt werden.

@code{fontSize} ist eine besondere Eigenschaft: sie entspricht
@code{\override ... #'font-size} für alle möglichen Objekte.
Weil es sich hier um eine globale Änderung handelt, wurde
die spezielle Form (die mit @code{\set} verändert wird) erstellt.
@end ignore


@node Alisten verändern
@subsection Alisten verändern
@translationof Modifying alists

Einige vom Benutzer einstellbare Eigenschaften sind intern als
@emph{alists} (Assoziative Listen) dargestellt, die Paare von
Schlüsseln und Werten speichern.  Die Struktur einer Aliste ist:

@example
'((@var{Schlüssel1} . @var{Wert1})
  (@var{Schlüssel2} . @var{Wert2})
  (@var{Schlüssel3} . @var{Wert3})
  @dots{})
@end example

Wenn eine Aliste eine Grob-Eigenschaft oder eine Variable der
@code{\paper}-Umgebung ist, können ihre Schlüssel einzeln verändert
werden, ohne andere Schlüssel zu beeinflussen.

Um beispielsweise den Freiraum zwischen benachbarten Systemen
in einer Systemgruppe zu verkleinern, kann man die
@code{staff-staff-spacing}-Eigenschaft des
+@code{StaffGrouper}-Grobs benutzen.  Die Eigenschaft ist eine
Aliste mit vier Schlüsseln: : @code{basic-distance} (Grund-Abstand),
@code{minimum-distance} (minimaler Abstand), @code{padding} (Verschiebung)
und @code{stretchability} (Dehnbarkeit).  Die Standardwerte dieser
Eigenschaft finden sich im Abschnitt @qq{Backend} der Referenz der
Interna (siehe @rinternals{StaffGrouper}):

@example
'((basic-distance . 9)
  (minimum-distance . 7)
  (padding . 1)
  (stretchability . 5))
@end example

Eine Möglichkeit, die Systemen dichter zueinander zu zwingen,
ist es, der Wert des  @code{basic-distance}-Schlüssels (@code{9}) zu
verändern, sodass der den gleichen Wert wie
@code{minimum-distance} (@code{7}) hat.  Um einen einzelnen
Schlüssel zu verändern, wird ein geschachtelter Aufruf benutzt:

@lilypond[quote,verbatim]
% default space between staves
\new PianoStaff <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>

% reduced space between staves
\new PianoStaff \with {
  % this is the nested declaration
  \override StaffGrouper #'staff-staff-spacing #'basic-distance = #7
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

Wenn man diese Art des geschachtelten Aufrufs einsetzt, wird der
spezifische Schlüssel (@code{basic-distance} im obigen Beispiel) verändert,
ohne dass sich andere Wert für die gleiche Eigenschaft ändern würden.

Nun sollen die Systeme so dicht wie möglich gesetzt werden, ohne das
Überlappungen vorkommen.  Die einfachste Möglichkeit, das zu tun, wäre
es, alle vier Wert auf 0 zu setzen.  Man muss jedoch nicht vier
Werte definieren, sondern die Eigenschaft
kann mit einem Aufruf als Aliste vollständig verändert werden:

@lilypond[quote,verbatim]
\new PianoStaff \with {
  \override StaffGrouper #'staff-staff-spacing =
    #'((basic-distance . 0)
       (minimum-distance . 0)
       (padding . 0)
       (stretchability . 0))
} <<
  \new Staff { \clef treble c''1 }
  \new Staff { \clef bass   c1   }
>>
@end lilypond

Dabei sollte beachtet werden, dass alle Schlüssel, die bei dieser
Weise des Aufrufs nicht explizit aufgelistet sind, auf den Standardwert
gesetzt werden, den sie hätten, wenn sie nicht definiert werden.
Im Falle von @code{staff-staff-spacing} würden alle nicht genannten
Schlüsselwerte auf 0 gesetzt (außer @code{stretchability}, welche immer
den Wert von @code{space} hat, wenn sie nicht definiert ist).  Somit sind
folgende Aufrufe äquivalent:

@example
\override StaffGrouper #'staff-staff-spacing =
  #'((basic-distance . 7))

\override StaffGrouper #'staff-staff-spacing =
  #'((basic-distance . 7)
     (minimum-distance . 0)
     (padding . 0)
     (stretchability . 7))
@end example

Eine möglicherweise ungewollte Konsequenz hiervon ist, dass alle
Standardwerte, die etwa in einer Initialisierungsdatei
zu Beginn einer LilyPond-Partitur geladen werden, nach dem Aufruf
rückgängig gemacht werden.  Im obigen Beispiel werden die
initialisierten Standardwerte für @code{padding} und @code{minimum-distance}
(definiert in @file{scm/define-grobs.scm}) auf den Standard zurückgesetzt,
den sie uninitialisiert hätten (0 in beiden Fällen).  Wenn eine Eigenschaft oder
Variable in Form einer Aliste (jeder Größe) definiert wird, werden
immer alle Schlüsselwerte auf den uninitialisierten Zustand zurückgesetzt.
Es ist also sicherer, geschachtelte Aufrufe zu benutzen, wenn man nicht
bewusst alle Werte zurücksetzen will.

@warning{Geschachtelte Aufrufe funktionieren nicht mit
Kontexteigenschaften (wie etwa @code{beamExceptions}, @code{keySignature},
@code{timeSignatureSettings}, usw.)  Diese Eigenschaften können
nur verändert werden, indem man sie vollständig als Alisten umdefiniert.}


@node Nützliche Konzepte und Eigenschaften
@section Nützliche Konzepte und Eigenschaften
@translationof Useful concepts and properties

@menu
* Eingabe-Modi::
* Richtung und Platzierung::
* Abstände und Maße::
* Eigenschaften des Staff-Symbols::
* Strecker::
* Sichtbarkeit von Objekten::
* Linienstile::
* Drehen von Objekten::
@end menu


@node Eingabe-Modi
@subsection Eingabe-Modi
@translationof Input modes

Die Art, wie die Notation einer Eingabedatei interpretiert
wird, hängt vom aktuellen Eingabemodus ab.

@strong{Chord (Akkordmodus)}

Man erreicht ihn durch den Befehl @code{\chordmode}.  Hierdurch
wird die Eingabe entsprechend der Syntax der Akkordnotation
interpretiert, siehe @ref{Notation von Akkorden}.  Akkorde werden als
Noten auf einem System dargestellt.

Der Akkordmodus wird auch mit dem Befehl @code{\chords} initiiert.
Dadurch wird gleichzeitig ein neuer @code{ChordNames}-Kontext
erstellt, die Eingabe entsprechend der Syntax der Akkordnotation
interpretiert und als Akkordbezeichnungen in einem
@code{ChordNames}-Kontext dargestellt. Siehe @ref{Akkordbezeichnungen drucken}.

@strong{Drum (Schlagzeugmodus)}

Man erreicht ihn mit dem Befehl @code{\drummode}.  Die Eingabe
wird entsprechend der Syntax der Schlagzeugnotation interpretiert,
siehe @ref{Grundlagen der Schlagzeugnotation}.

Der Schlagzeugmodus wird auch mit dem Befehl @code{\drums} aktiviert.
Dadurch wird gleichzeitig ein neuer @code{DrumStaff}-Kontext
erstellt, die Eingabe entsprechend der Syntax der Schlagzeugnotation
interpretiert und als Schlagzeugsymbole auf einem Schlagzeugsystem
dargestellt.  Siehe @ref{Grundlagen der Schlagzeugnotation}.

@strong{Figure (Ziffernmodus)}

Man erreicht ihn mit dem Befehl @code{\figuremode}.  Die Eingabe
wird entsprechend der Syntax für Generalbass interpretiert, siehe
@ref{Eingabe des Generalbass'}.

Der Ziffernmodus wird auch mit dem Befehl @code{\figures} aktiviert.
Dadurch wird gleichzeitig ein neuer @code{FiguredBass}-Kontext
erstellt, die Eingabe entsprechend der Syntax für Generalbass
interpretiert und als Generalbassziffern im @code{FiguredBass}-Kontext
dargestellt.  Siehe @ref{Grundlagen des Bezifferten Basses}.

@strong{Fret/tab (Griffsymbol-/Tabulaturmodus)}

Es gibt keinen besonderen Eingabemodus für Griffsymbole und
Tabulaturen.

Um Tabulaturen zu erstellen, werden Noten oder Akkorde im
Notenmodus notiert und dann in einem @code{TabStaff}-Kontext
interpretiert, siehe
@ref{Standardtabulaturen}.

Um Griffsymbole oberhalb eines Notensystems zu erstellen, gibt
es zwei Möglichkeiten.  Man kann den @code{FretBoards}-Kontext
einsetzen (siehe @ref{Automatische Bund-Diagramme}) oder sie können
als Beschriftung über den Noten eingefügt werden, indem man
den @code{\fret-diagram}-Befehl einsetzt (siehe
@ref{Bund-Diagramm-Beschriftung}).

@strong{Lyrics (Gesangstextmodus)}

Man erreicht ihn mit dem Befehl @code{\lyricmode}.  Die Eingabe
wird entsprechend der Syntax für Silben eines Gesangstextes
interpretiert, wobei optional Dauern und verknüpfte
Gesangstextveränderer möglich  sind, siehe @ref{Notation von Gesang}.

Der Gesangstextmodus wird auch durch den Befehl @code{\addlyrics}
aktiviert.  Dadurch wird auch ein neuer @code{Lyrics}-Kontext
erstellt und ein impliziter @code{\lyricsto}-Befehl, der den
nachfolgenden Gesangstext mit der vorhergehenden Musik verknüpft.

@strong{Markup (Textbeschriftungsmodus)}

Man erreicht ihn mit dem Befehl @code{\markup}.  Die Eingabe wird
entsprechend der Syntax für Textbeschriftung interpretiert, siehe
@ref{Textbeschriftungsbefehle}.

@c silly work-around for texinfo broken-ness
@c (@strong{Note...} causes a spurious cross-reference in Info)
@b{Note (Notenmodus)}

Das ist der Standardmodus.  Er kann auch mit dem Befehl
@code{\notemode} gefordert werden.  Die Eingabe wird als Tonhöhen,
Dauern, Beschriftung usw. interpretiert und als musikalische
Notation auf einem Notensystem gesetzt.

Es ist normalerweise nicht nötig, den Notenmodus extra anzugeben,
aber es kann in bestimmten Situationen durchaus nützlich sein,
etwa wenn man in einem Gesangstext-, Akkord- oder einem anderen
Modus arbeitet aber ein Zeichen braucht, das nur im Notenmodus
benutzt werden kann.

Um etwa Dynamikzeichen vor die Nummern von unterschiedlichen
Strophen zu setzen, muss man den Notenmodus betreten:

@lilypond[verbatim,relative=2,quote]
{ c4 c4 c4 c4 }
\addlyrics {
  \notemode{ \set stanza = \markup{ \dynamic f 1. } }
  To be sung loudly
}
\addlyrics {
  \notemode{ \set stanza = \markup{ \dynamic p 2. } }
  To be sung quietly
}
@end lilypond


@node Richtung und Platzierung
@subsection Richtung und Platzierung
@translationof Direction and placement

Die Platzierung und Richtung von Objekten ist im Notensatz oft durch eine
enge Auswahl begrenzt: Notenhälse beispielsweise können entweder nach
oben oder nach unten zeigen, Gesangstext, Dynamikzeichen und andere
Ausdrucksbezeichnungen können über oder unter dem System gesetzt werden,
Text kann rechts, links oder mittig ausgerichtet werden usw.  Die meisten
dieser Entscheidungen können LilyPond direkt überlassen werden; in
einigen Fällen kann es allerdings nötig sein, eine bestimmte Richtung
oder eine Position zu erzwingen.

@strong{Richtungseinstellung von Artikulationszeichen}

Standardmäßig sind bestimmte Objekte immer nach oben oder unten ausgerichtet,
wie Dynamikzeichen oder Fermaten, während andere Objekte zwischen
oben und unten wechseln, was vor allem von der Richtung der Notenhälse
abhängt und etwa Bögen und Akzente betrifft.

Die Standardeinstellungen können verändert werden, indem dem
Artikulationszeichen ein Ausrichtungsmarkierer vorangeht.  Drei
derartige Ausrichtungsmarkierer sind vorhanden:  @code{^} (bedeutet @qq{nach oben}), @code{_}
(bedeutet @qq{nach unten}) bzw. @code{-} (bedeutet @qq{Standardrichtung}
benutzen) normalerweise weggelassen werden.  In diesem Fall wird
@code{-} angenommen.  Eine Richtungsanweisung ist jedoch
@strong{immer} erforderlich vor

@itemize
@item @code{\tweak}-Befehlen
@item @code{\markup}-(Textbeschriftungs-)Befehlen
@item @code{\tag}-Befehlen
@item Textbeschriftungen in reiner Textform, wie etwa @code{-"string"}
@item Fingersatzanweisungen: @w{@code{-1}}
@item Abkürzungen von Artikulationen, wie @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
@end itemize

Ausrichtungsmarkierer haben nur eine Auswirkung auf die nächste Note:

@lilypond[verbatim,quote,relative=2]
c2( c)
c2_( c)
c2( c)
c2^( c)
@end lilypond


@strong{Die @code{direction}-(Richtungs-)Eigenschaft}

Die Position oder Richtung vieler Layoutobjekte wird von der
@code{direction}-Eigenschaft kontrolliert.

Der Wert der @code{direction}-Eigenschaft kann auf den Wert
@code{1} gesetzt werden, was gleichbedeutend mit @qq{nach oben}
bzw. @qq{oberhalb} ist, oder auf den Wert @w{@code{-1}}, was
@qq{nach unten} bzw. @qq{unterhalb} bedeutet.  Die Symbole
@code{UP} und @code{DOWN} können anstelle von @code{1}
und @w{@code{-1}} benutzt werden.  Die Standardausrichtung kann
angegeben werden, indem @code{direction} auf den Wert
@code{0} oder @code{CENTER} gesetzt wird.  In vielen Fällen
bestehen auch vordefinierte Befehle, mit denen die Ausrichtung
bestimmt werden kann.  Sie haben die Form

@noindent
@code{\xxxUp}, @code{xxxDown}, @code{xxxNeutral}

@noindent
wobei @code{xxxNeutral} bedeutet: @qq{Benutze die
Standardausrichtung}.  Siehe auch
@rlearning{within-staff (Objekte innerhalb des Notensystems)}.

In wenigen Fällen, von denen Arpeggio das einzige häufiger
vorkommende Beispiel darstellt, entscheidet der Wert von
@code{direction}, ob das Objekt auf der rechten oder linken
Seite das Ursprungsobjektes ausgegeben wird.  In diesem Fall
bedeutet @w{@code{-1}} oder @code{LEFT} @qq{auf der linken Seite}
und @code{1} oder @code{RIGHT} @qq{auf der rechten Seite}.  @code{0}
oder @code{CENTER} bedeutet @qq{benutze Standardausrichtung}.

@c ignore left out
Diese Ausrichtungsanzeigen wirken sich auf alle Noten aus, bis sie
rückgängig gemacht werden:

@lilypond[verbatim,quote,relative=2]
c2( c)
\slurDown
c2( c)
c2( c)
\slurNeutral
c2( c)
@end lilypond


@node Abstände und Maße
@subsection Abstände und Maße
@translationof Distances and measurements

@cindex Abstände, absolut
@cindex Abstände, skaliert

@funindex \mm
@funindex \cm
@funindex \in
@funindex \pt

In LilyPond gibt es zwei Arten von Abständen: absolute und
skalierte.

Absolute Abstände werden benutzt, um Ränder, Einzüge und andere
Einzelheiten des Seitenlayouts zu bestimmen.  Sie sind in den
Standardeinstellungen in Millimetern definiert.  Abstände können
auch in anderen Einheiten definiert werden, indem folgende
Befehle auf die Zahl folgen: @code{\mm}, @code{\cm},
@code{\in}@tie{}(Zoll=2,54 cm) und @code{\pt}@tie{}(Punkte, 1/72.27
eines Zolls).  Abstände des Seitenlayouts können auch in
skalierbaren Einheiten (siehe folgenden Absatz) definiert
werden, indem man den Befehl @code{\staff-space} an die
Zahl hängt.  Das Seitenlayout ist genauer beschrieben in
@ref{Seitenlayout}.

Skalierbare Abstände werden immer in Einheiten von
Notenlinienabständen angegeben, oder seltener in halben
Notenlinienabständen.  Ein Notenlinienabstand ist der
Abstand zwischen zwei benachbarten Linien eines Notensystems.
Der Standardwert dieser Einheit kann global geändert werden,
indem man die globale Notensystemgröße ändert, oder sie
kann lokal geändert werden, indem man die Eigenschaft
@code{staff-space} des @code{StaffSymbol}-Objekts mit
@code{\override} verändert.  Skalierte Abstände verändern
sich automatisch entsprechend, wenn der Notenlinienabstand
entweder global oder lokal verändert wird, aber Schriftarten
verändern ihre Größe nur, wenn der Notenlinienabstand
global verändert wird.  Mit dem globalen Notenlinienabstand
kann man also auf einfach Art und Weise die gesamte Größe
einer Partitur verändern.  Zu Methoden, wie der globale
Notenlinienabstand verändert werden kann, siehe
@ref{Die Notensystemgröße einstellen}.

@funindex magstep

Wenn nur eine ein Abschnitt einer Partitur in einer anderen
Größe erscheinen soll, etwa ein Ossia-Abschnitt in einer
Fußnote, kann die globale Notensystemgröße nicht einfach
geändert werden, weil sich diese Änderung auf die gesamte Partitur
auswirken würde.  In derartigen Fällen muss die Größenänderung
vorgenommen werden, indem man sowohl die
@code{staff-space}-Eigenschaft von @code{StaffSymbol} als auch
die Größe der Schriftarten verändert.  Eine Scheme-Funktion,
@code{magstep}, kann von einer Schriftartveränderung zu der
entsprechenden Veränderung in @code{staff-space} (Notenlinienabständen)
konvertieren.  Zu einer Erklärung und Beispielen zu ihrer
Verwendung siehe @rlearning{Länge und Dicke von Objekten}.


@seealso
Handbuch zum Lernen:
@rlearning{Länge und Dicke von Objekten}.

Notationsreferenz:
@ref{Seitenlayout},
@ref{Die Notensystemgröße einstellen}.


@node Eigenschaften des Staff-Symbols
@subsection Eigenschaften des Staff-Symbols
@translationof Staff symbol properties

@cindex Anpassen von staff symbol
@cindex Notensystem, anpassen
@cindex Veränderung des Notensystems

Die vertikale Position der Notenlinien und die Anzahl der
Notenlinien kann gleichzeitig definiert werden.  Wie das
folgende Beispiel zeigt, werden Notenpositionen nicht
durch die Position der Notenlinien verändert:

@warning{Die @code{'line-positions}-Eigenschaft
verändert die @code{'line-count}-Eigenschaft.  Die
Anzahl der Notenlinien wird implizit definiert durch
die Anzahl der Elemente in der Liste der Werte von
@code{'line-positions}.}

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
}
{ a4 e' f b | d1 }
@end lilypond

Die Breite eines Notensystems kann verändert werden.  Die Einheit
ist in Notenlinienabständen.  Die Abstände von Objekten
in diesem Notensystem wird durch diese Einstellung nicht
beeinflusst.

@lilypond[verbatim,quote,relative=1]
\new Staff \with {
  \override StaffSymbol #'width = #23
}
{ a4 e' f b | d1 }
@end lilypond


@node Strecker
@subsection Strecker
@translationof Spanners

Viele Objekte der Musiknotation erstrecken sich über mehrere
Objekte oder gar mehrere Takte.  Beispiele hierfür sind etwa
Bögen, Balken, Triolenklammern, Volta-Klamern in Wiederholungen,
Crescendo, Triller und Glissando.  Derartige Objekte werden
als @qq{Strecker} bezeichnet.  Sie haben spezielle Eigenschaften,
mit welchen ihre Eigenschaften und ihr Verhalten beeinflusst
werden kann.  Einige dieser Eigenschaften gelten für alle
Strecker, andere beschränken sich auf eine Untergruppe der
Strecker.

Alle Strecker unterstützen das @code{spanner-interface}
(Strecker-Schnittstelle).
Ein paar, insbesondere die, die zwischen zwei Objekten eine
gerade Linie ziehen, unterstützen auch das
@code{line-spanner-interface} (Strecker-Linienschnittstelle).


@unnumberedsubsubsec Das @code{spanner-interface} benutzen

Diese Schnittstelle stellt zwei Eigenschaften zur Verfügung,
die sich auf mehrere Strecker auswirken:

@strong{@i{Die @code{minimum-length}-Eigenschaft}}

Die Mindestlänge eines Streckers wird durch die
@code{minimum-length}-Eigenschaft definiert.  Wenn diese
Eigenschaft vergrößert wird, muss in den meisten Fällen
auch der Abstand der Noten zwischen den zwei Endpunkten
eines Streckers verändert werden.  Eine Veränderung dieser
Eigenschaft hat jedoch auf die meisten Strecker keine Auswirkung,
weil ihre Länge aus anderen Berechnungen hervorgeht.
Einige Beispiele, wo die Eigenschaft benutzt wird, sind
unten dargestellt.

@lilypond[verbatim,quote,relative=2]
a~a
a
% increase the length of the tie
-\tweak #'minimum-length #5
~a
@end lilypond

@lilypond[verbatim,quote,relative=2]
a1
\compressFullBarRests
R1*23
% increase the length of the rest bar
\once \override MultiMeasureRest #'minimum-length = #20
R1*23
a1
@end lilypond

@lilypond[verbatim,quote,relative=2]
a \< a a a \!
% increase the length of the hairpin
\override Hairpin #'minimum-length = #20
a \< a a a \!
@end lilypond

Diese Veränderung kann auch eingesetzt werden, um die Länge
von Legato- und Phrasierungsbögen zu verändern:

@lilypond[verbatim,quote,relative=2]
a( a)
a
-\tweak #'minimum-length #5
( a)

a\( a\)
a
-\tweak #'minimum-length #5
\( a\)
@end lilypond

Im Falle einiger Layoutobjekte wirkt sich die
@code{minimum-length}-Eigenschaft erst dann aus, wenn die
@code{set-spacing-rods}-Prozedur explizit aufgerufen wird.
Um das zu tun, sollte die @code{springs-and-rods}-Eigenschaft
auf @code{ly:spanner::set-spacing-rods} gesetzt werden.  Die
Mindestlänge eines Glissandos etwa wird erst aktiv, wenn
die @code{springs-and-rods}-Eigenschaft gesetzt ist:

@lilypond[verbatim,quote,relative=1]
% default
e \glissando c'

% not effective alone
\once \override Glissando #'minimum-length = #20
e, \glissando c'

% effective only when both overrides are present
\once \override Glissando #'minimum-length = #20
\once \override Glissando #'springs-and-rods = #ly:spanner::set-spacing-rods
e, \glissando c'
@end lilypond

Das gilt auch für das @code{Beam}-(Balken-)Objekt:

@lilypond[verbatim,quote,relative=1]
% not effective alone
\once \override Beam #'minimum-length = #20
e8 e e e

% effective only when both overrides are present
\once \override Beam #'minimum-length = #20
\once \override Beam #'springs-and-rods = #ly:spanner::set-spacing-rods
e8 e e e
@end lilypond

@strong{@i{Die @code{to-barline}-Eigenschaft}}

Die zweite nützliche Eigenschaft des @code{spanner-interface} ist
@code{to-barline} (bis zum Taktstrich).  In den Standardeinstellungen
ist diese Eigenschaft auf @qq{wahr} gesetzt, was bedeutet, dass
ein Strecker, etwa eine Crescendo-Klammer, der an der ersten Noten
eines Taktes beendet wird, sich nur bis zum vorhergehenden
Taktstrich erstreckt.  Wenn die Eigenschaft auf @qq{falsch} gesetzt
wird, erstrecken sich die Strecker entsprechend über die Taktlinie
hinüber und enden erst an der entsprechenden Note:

@lilypond[verbatim,quote,relative=2]
a \< a a a a \! a a a \break
\override Hairpin #'to-barline = ##f
a \< a a a a \! a a a
@end lilypond

Diese Eigenschaft wirkt sich nicht auf alle Strecker aus.  Im Falle
von Legato- oder Phrasierungsbögen etwa hat diese Eigenschaft
keinen Effekt.  Das gilt auch für alle anderen Streckern, bei
denen es nicht sinnvoll währe, sie an einer Taktlinie abzuschließen.


@unnumberedsubsubsec Das @code{line-spanner-interface} benutzen

Objekte, die das @code{line-spanner-interface} unterstützen,
sind unter Anderem:

@itemize
@item @code{DynamicTextSpanner}
@item @code{Glissando}
@item @code{TextSpanner}
@item @code{TrillSpanner}
@item @code{VoiceFollower}
@end itemize

Die Routine, die das Setzen der Matrizen dieser Strecker
hervorruft, ist @code{ly:line-interface::print}.  Diese
Routine bestimmt die exakte Position der zwei Endpunkte
und zeichnet eine Linie zwischen ihnen, in dem erforderlichen
Stil.  Die Position der zwei Endpunkte des Streckers wird
in Echtzeit errechnet, aber es ist möglich, ihre
Y-Koordinaten zu verändern.  Die Eigenschaften, die angegeben
werden müssen, sind zwei Ebenen in der Objekthierarchie
tiefer angeordnet, aber die Syntax des @code{\override}-Befehls
ist ziemlich einfach:

@lilypond[relative=2,quote,verbatim]
e2 \glissando b
\once \override Glissando #'(bound-details left Y) = #3
\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando b
@end lilypond

Die Einheiten für die @code{Y}-Eigenschaft werden in
Notenlinienabständen angegeben, wobei die Mittellinie des
Notensystems die Null darstellt.  Für das Glissando ist
der Wert von @code{Y} am entsprechenden X-Koordinatenpunkt
entsprechend dem Mittelpunkt des Notenkopfes, wenn die
Linie bis in die Noten hinein weitergeführt werden würde.

Wenn @code{Y} nicht gesetzt wird, wird der Wert aus der
vertikalen Position des entsprechenden Anknüpfpunkts des
Streckers errechnet.

Im Fall eines Zeilenumbruchs werden die Werte der Endpunkte
in den Unterlisten @code{left-broken} bzw. @code{right-broken}
von @code{bound-details} abgelegt.  Zum Beispiel:

@lilypond[relative=2,ragged-right,verbatim,quote]
\override Glissando #'breakable = ##t
\override Glissando #'(bound-details right-broken Y) = #-3
c1 \glissando \break
f1
@end lilypond

Eine Anzahl weitere Eigenschaft der @code{left}- und
@code{right}-Unterlisten der @code{bound-details}-Eigenschaft
kann auf gleiche Weise wie  @code{Y} verändert werden:

@table @code
@item Y
Hiermit wird der Y-Koordinationspunkt des Endpunktes in
Notenlinienabständen vom Mittelpunkt des Notensystems
ausgehend angegeben.  Der Endpunkt ist normalerweise
der Mittelpunkt des Elternobjektes, sodass Glissandos
vertikal auf den Mittelpunkt eines Notenkopfes weist.

Für horizontale Strecker, wie Textstrecker und Trillerstrecker
ist sein Wert mit 0 definiert.

@item attach-dir
Das entscheidet, wo die Linie auf der X-Achse beginnt und endet,
relativ zum Elternobjekt.  Ein Wert @w{@code{-1}} (oder
@code{LEFT}) lässt die Linie an der linken Seite der Noten
beginnen/enden, mit der sie verknüpft ist.

@item X
Das ist der absolute X-Koordinatenpunkt des Endpunktes.  Der
Wert wird normalerweise in Echtzeit errechnet, und ihn zu
verändern ist normalerweise nicht nützlich.

@item stencil
Linienstrecker können Symbole am Ende oder zu Anfang des
Streckers haben, die in dieser Untereigenschaft definiert
werden.  Die Eigenschaft ist für interne Benutzung, es
wird empfohlen, die Eigenschaft @code{text} zu benutzen.

@item text
Das ist eine Textbeschriftung, die ausgewertet wird und die
@code{stencil}-Eigenschaft überschreibt.  Sie wird eingesetzt,
um @i{cresc.}, @i{tr} oder andere Texte an horizontale
Strecker zu setzen.

@lilypond[quote,ragged-right,relative=2,verbatim]
\override TextSpanner #'(bound-details left text)
   = \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond

@item stencil-align-dir-y
@item stencil-offset
Wenn keine dieser beiden Eigenschaften gesetzt wird, wird
die Matrize (engl. stencil) einfach am Endpunkt des Streckers,
auf seiner Mittellinie (wie durch @code{X} und @code{Y}
definiert) zentriert, ausgegeben.  Wenn entweder
@code{stencil-align-dir-y} oder @code{stencil-offset}
gesetzt werden, wird das Symbol am Rand vertikal entsprechend
des Endpunktes der Linie verschoben:

@lilypond[relative=1,quote,verbatim]
\override TextSpanner
  #'(bound-details left stencil-align-dir-y) = #-2
\override TextSpanner
  #'(bound-details right stencil-align-dir-y) = #UP

\override TextSpanner
  #'(bound-details left text) = #"ggg"
\override TextSpanner
  #'(bound-details right text) = #"hhh"
c4^\startTextSpan c c c \stopTextSpan
@end lilypond

Dabei sollte beachtet werden, dass negative Werte das Objekt
nach @emph{oben} verschieben, anders als man erwarten könnte,
weil der Wert @w{@code{-1}} oder @code{DOWN} bedeutet, dass
die @emph{Unterkante} des Textes mit der Streckerlinie
ausgerichtet wird.  Ein Wert @code{1} oder @code{UP}
richtet die Oberkante des Textes mit der Streckerlinie aus.

@item arrow
Wenn diese Untereigenschaft auf @code{#t} gesetzt wird,
wird ein Pfeilkopf am Ende der Linie erstellt.

@item padding
Diese Eigenschaft kontrolliert den Abstand zwischen
dem angegebenen Endpunkt der Linie und dem wirklichen Ende.
Ohne Füllung (engl. padding) würde ein Glissando in der
Mitte eines Notenkopfes beginnen und enden.

@end table

Die musikalische Funktion @code{\endSpanners} beschließt
den Strecker, der an der direkt folgenden Note beginnt,
bevor er eigentlich zu ende wäre.  Er wird exakt nach
einer Note beendet, oder am nächsten Taktstrich, wenn
@code{to-barline} auf wahr gesetzt ist und eine Taktlinie
vor der nächsten Note erscheint.

@lilypond[verbatim,quote,ragged-right,relative=2]
\endSpanners
c2 \startTextSpan c2 c2
\endSpanners
c2 \< c2 c2
@end lilypond

Wenn man @code{\endSpanners} benutzt, ist es nicht
nötig, den Befehl \startTextSpan mit \stopTextSpan
zu beenden, und es ist auch nicht nötig, Crescendo-Klammern
mit @code{\!} zu beenden.


@seealso
Referenz der Interna:
@rinternals{TextSpanner},
@rinternals{Glissando},
@rinternals{VoiceFollower},
@rinternals{TrillSpanner},
@rinternals{line-spanner-interface}.


@node Sichtbarkeit von Objekten
@subsection Sichtbarkeit von Objekten
@translationof Visibility of objects

@cindex Objekte, Sichtbarkeit
@cindex Grobs, Sichtbarkeit
@cindex Sichtbarkeit von Objekten

Die Sichtbarkeit von Layout-Objekten kann auf vier Arten
kontrolliert werden: Ihre Matrizen (engl stencil) können
entfernt werden, sie können unsichtbar gemacht werden,
sie können weiß eingefärbt werden und ihre
@code{break-visibility}-Eigenschaft kann verändert werden.
Die ersten drei Möglichkeiten beziehen sich auf alle
Layout-Objekte, die letzte nur auf einige wenige, nämlich
die @emph{zerteilbaren} Objekte.  Das Handbuch zum Lernen
führt in alle vier Möglichkeiten ein, siehe
@rlearning{Sichtbarkeit und Farbe von Objekten}.

Es gibt auch einige weitere Techniken, die sich nur auf
bestimmte Layout-Objekte beziehen.  Sie werden im letzten
Abschnitt behandelt.

@menu
* Einen stencil entfernen::
* Objekten unsichtbar machen::
* Objekte weiß malen::
* break-visibility (unsichtbar machen) benutzen::
* Besonderheiten::
@end menu


@node Einen stencil entfernen
@unnumberedsubsubsec Einen @code{stencil} entfernen
@translationof Removing the stencil

@cindex stencil, entfernen
@cindex Matrize, entfernen
@cindex Stempel (stencil), entfernen
@cindex Entfernen eines Stencil

Jedes Layout-Objekt hat eine Matrizen-(stencil)-Eigenschaft.
Sie ist normalerweise definiert als die Funktion, die das
entsprechende Objekt zeichnet.  Wenn die Eigenschaft mit
@code{\override} auf @code{#f} gesetzt wird, wird keine
Funktion aufgerufen und also auch kein Objekt gezeichnet.
Das Standardverhalten kann mit dem Befehl @code{\revert}
wieder hergestellt werden.

@lilypond[quote,verbatim,relative=1]
a1 a
\override Score.BarLine #'stencil = ##f
a a
\revert Score.BarLine #'stencil
a a a
@end lilypond


@node Objekten unsichtbar machen
@unnumberedsubsubsec Objekten unsichtbar machen
@translationof Making objects transparent

@cindex transparent, Objekte
@cindex unsichtbar, Objekte
@cindex durchsichtig, Objekte

Jedes Layout-Objekt hat eine Durchsichtigkeits-Eigenschaft
(@code{'transparent}),
die normalerweise auf den Wert @code{#f} gesetzt ist.  Wenn
sie auf @code{#t} gesetzt wird, nimmt das Objekt immer noch
den entsprechenden Platz ein, ist aber unsichtbar.

@lilypond[quote,verbatim,relative=2]
a4 a
\once \override NoteHead #'transparent = ##t
a a
@end lilypond


@node Objekte weiß malen
@unnumberedsubsubsec Objekte weiß malen
@translationof Painting objects white

@cindex Objekte, einfärben
@cindex Färben von Objekten
@cindex Einfärben von Objekten
@cindex Ebenen (layer)
@cindex layer (Ebenen)
@cindex Druckreihenfolge
@cindex Objekte verändern
@cindex verändern von Objekten
@cindex Grobs, verändern

Alle Layout-Objekte haben eine Farb-(color)-Eigenschaft, die
normalerweise schwarz (@code{black}) definiert ist.  Wenn
sie nach weiß (@code{white}) verändert wird, kann man das
Objekt nicht mehr vom weißen Hintergrund unterscheiden.
Wenn das Objekt jedoch andere Objekte überschneidet, wird
die Farbe der Überschneidungen von der Reihenfolge entschieden,
in welcher die Objekte gesetzt werden.  Es kann also vorkommen,
dass man die Umrisse des weißen Objektes erahnen kann, wie
in diesem Beispiel:

@lilypond[quote,verbatim,relative=2]
\override Staff.Clef #'color = #white
a1
@end lilypond

Das kann man vermeiden, indem man die Satzreihenfolge der Objekte
verändert.  Alle Layout-Objekte haben eine @code{layer}-Eigenschaft,
die auf eine ganze Zahl gesetzt sein muss.  Objekte mit der
niedrigsten Zahl in der @code{layer}-Eigenschaft werden zuerst
gesetzt, dann die nächsten Objekte in ansteigender Ordnung.  Objekte
mit höheren Werten überschneiden also Objekte mit niedrigeren
Werten.  Die meisten Objekte bekommen den Wert @code{1} zugewiesen,
einige wenige Objekte, unter die auch @code{StaffSymbol} (die
Notenlinien) gehört, jedoch den Wert @code{0}.  Die Reihenfolge,
in der Objekte mit demselben Wert gesetzt werden, ist nicht
definiert.

Im oberen Beispiel wird der weiße Schlüssel, der einen Wert von
@code{1} für @code{layer} hat, nach den Notenlinien gesetzt
(die einen Wert von @code{0} für @code{layer} haben) und
überschneidet sie also.  Um das zu ändern, muss dem @code{Clef}-Objekt
(Notenschlüssel) ein niedrigerer Wert, etwa @w{@code{-1}}, gegeben
werden, sodass es früher gesetzt wird:

@lilypond[quote,verbatim,relative=2]
\override Staff.Clef #'color = #white
\override Staff.Clef #'layer = #-1
a1
@end lilypond


@node break-visibility (unsichtbar machen) benutzen
@unnumberedsubsubsec @code{break-visibility} (unsichtbar machen) benutzen
@translationof Using break-visibility

@funindex break-visibility

@cindex break-visibility

Die meisten Layout-Objekte werden nur einmal gesetzt, aber
einige, wie Taktstriche, Schlüssel, Taktartbezeichnung und
Tonartvorzeichen, müssen mehrmals gesetzt werden, wenn
die Zeile gewechselt wird: einmal am Ende des oberen Systems
und ein zweites Mal zu Beginn des nächsten Systems.
Derartige Objekte werden als @emph{trennbar} bezeichnet
und haben eine Eigenschaft, die @code{break-visibility}-Eigenschaft,
mit der ihre Sichtbarkeit an allen drei Positionen, an denen
sie auftreten können, kontrolliert werden kann: zu Beginn
einer Zeile, innerhalb einer Zeile, wenn sie verändert werden,
und am Ende einer Zeile, wenn die Änderung hier stattfindet.

Die Taktart wird beispielsweise standardmäßig nur zu Beginn des
ersten Systems gesetzt, aber an anderen Stellen nur, wenn sie
sich ändert.  Wenn diese Änderung am Ende eines Systems auftritt,
wird die neue Taktart am Ende des aktuellen Systems als auch
zu Beginn des nächsten Systems gesetzt.

Dieses Verhalten wird von der @code{break-visibility}-Eigenschaft
kontrolliert, die erklärt wird in
@c Leave this ref on a newline - formats incorrectly otherwise -td
@rlearning{Sichtbarkeit und Farbe von Objekten}.  Die Eigenschaft
braucht einen Vektor von drei Booleschen Werten, die in ihrer
Reihenfolge bestimmte, ob das Objekt a) zu Ende der Zeile,
b) innerhalb einer Zeile oder c) zu Beginn einer Zeile gesetzt
wird.  Oder, genauer gesagt, vor einem Zeilenumbruch, an Stellen,
wo kein Zeilenumbruch auftritt oder nach einem Zeilenumbruch.

Die acht möglichen Kombinationen können auch durch vordefinierte
Funktionen bestimmt werden, welche in der Datei @file{scm/output-lib.scm}
definiert sind.  Die letzten drei Spalten der folgenden Tabelle
zeigen an, ob das Layout-Objekt an einer bestimmten Position
sichtbar sein wird oder nicht:

@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {ja} {ja} {ja}
@headitem Funktion                   @tab Vektor                  @tab Vor @tab kein    @tab Nach
@headitem Form                       @tab Form                    @tab Umbruch  @tab Umbruch    @tab Umbruch

@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab ja    @tab ja      @tab ja
@item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab nein  @tab nein       @tab ja
@item @code{center-visible}          @tab @code{'#(#f #t #f)}     @tab nein    @tab ja      @tab nein
@item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab ja   @tab nein       @tab nein
@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab ja    @tab ja       @tab nein
@item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab ja    @tab nein       @tab ja
@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab nein     @tab ja     @tab ja
@item @code{all-invisible}           @tab @code{'#(#f #f #f)}     @tab nein   @tab nein       @tab nein
@end multitable

Die Standardeinstellungen von @code{break-visibility} hängen vom
Layout-Objekt ab.  Die folgende Tabelle zeigt alle wichtigen Layout-Objekte,
die mit @code{break-visibility} verändert werden können und die
jeweiligen Standardeinstellungen der Eigenschaft:

@multitable @columnfractions .3 .3 .4

@headitem Layout-Objekt   @tab Normaler Kontext  @tab Standardeinstellung

@c omit Ambitus as it appears not to be affected by break-visibility -td
@c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
@item @code{BarLine} (Taktstrich)            @tab @code{Score}          @tab calculated
@item @code{BarNumber} (Taktzahl)          @tab @code{Score}          @tab @code{begin-of-line-visible}
@c omit the following item until it can be explained -td
@c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
@item @code{BreathingSign} (Atemzeichen)       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@item @code{Clef}  (Schlüssel)              @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
@item @code{DoublePercentRepeat} (Doppel-Prozent-Wiederholung @tab @code{Voice}          @tab @code{begin-of-line-invisible}
@c omit KeyCancellation until it can be explained -td
@c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
@item @code{KeySignature} (Tonart)       @tab @code{Staff}          @tab @code{begin-of-line-visible}
@c omit LeftEdge until it can be explained -td
@c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
@item @code{OctavateEight} (Oktavierungs-Acht)      @tab @code{Staff}          @tab @code{begin-of-line-visible}
@item @code{RehearsalMark} (Übungszeichen)      @tab @code{Score}          @tab @code{end-of-line-invisible}
@item @code{TimeSignature} (Taktart)      @tab @code{Staff}          @tab @code{all-visible}

@end multitable

Das Beispiel unten zeigt die Verwendung der Vektor-Form um die
Sichtbarkeit von Taktlinien zu bestimmten:

@lilypond[quote,verbatim,relative=1,ragged-right]
f4 g a b
f4 g a b
% Remove bar line at the end of the current line
\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
\break
f4 g a b
f4 g a b
@end lilypond

Obwohl alle drei Bestandteile des Vektors, mit denen
@code{break-visibility} definiert wird, vorhanden sein
müssen, haben nicht alle eine Auswirkung auf jedes
Layout-Objekt, und einige Kombinationen können sogar
Fehler hervorrufen.  Es gelten die folgenden Einschränkungen:

@itemize @bullet
@item
Taktstriche können nicht zu Beginn einer Zeile gesetzt werden.

@item
Eine Taktzahl kann nicht zu Beginn der ersten Zeile gesetzt
werden, außer wenn er nicht 1 ist.

@item
Schlüssel -- siehe unten.

@item
Doppel-Prozent-Wiederholungen werden entweder alle ausgegeben
oder alle unterdrückt.  Mit @code{begin-of-line-invisible} werden
sie ausgegeben, mit @code{all-invisible} unterdrückt.

@item
Tonart -- siehe unten.

@item
Oktavierungs-Acht -- siehe unten.

@end itemize


@node Besonderheiten
@unnumberedsubsubsec Besonderheiten
@translationof Special considerations

@strong{@emph{Sichtbarkeit nach expliziten Änderungen}}

@cindex Tonart, Sichtbarkeit nach expliziter Änderung
@cindex Schlüssel, Sichtbarkeit nach expliziter Änderung

@funindex explicitKeySignatureVisibility
@funindex explicitClefVisibility

Die @code{break-visibility}-Eigenschaft kontrolliert die Sichtbarkeit
von Tonarten und Schlüsseländerungen nur zu Beginn einer Zeile,
d.h. nach einem Zeilenumbruch.  Sie hat keinen Einfluss auf die
Sichtbarkeit von Tonarten bzw. Schlüsseln, die nach einer
expliziten Tonart- oder Schlüsseländerung in oder am Ende einer
Zeile angezeigt werden.  Im nächsten Beispiel ist die Tonartangabe
nach dem expliziten Wechsel zu B-Dur immer noch sichtbar, obwohl
@code{all-invisible} eingesetzt wurde:

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
% Try to remove all key signatures
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b
\break
f4 g a b
f4 g a b
@end lilypond

Die Sichtbarkeit derartiger expliziter Tonart- und Schlüsseländerungen
wird von den @code{explicitKeySignatureVisibility}- und
@code{explicitClefVisibility}-Eigenschaften kontrolliert.  Sie
entsprechen der @code{break-visibility}-Eigenschaft und beide
brauchen drei Boolesche Werte bzw. die oben aufgelisteten vordefinierten
Funktionen als Argument, genau wie @code{break-visibility}.
Beide sind Eigenschaft des @code{Staff}-Kontextes, nicht der
Layout-Objekte selber, weshalb sie mit dem Befehl @code{\set}
eingesetzt werden.  Beide sind standardmäßig auf die Funktion
@code{all-visible} gesetzt.  Diese Eigenschaften kontrollieren nur
die Sichtbarkeit von Tonarten bzw. Schlüssel, die von expliziten
Änderungen herrühren, und haben keinen Einfluss auf Tonarten und
Schlüssel zu Beginn einer Zeile -- um diese zu beeinflussen, muss
@code{break-visibility} benutzt werden.

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

@strong{@emph{Sichtbarkeit von erinnernden Versetzungszeichen}}

Um erinnernde Versetzungszeichen zu entfernen, die nach einer
expliziten Tonartänderung auftreten, muss die @code{Staff}-Eigenschaft
@code{printKeyCancellation} auf @code{#f} gesetzt werden:

@lilypond[quote,verbatim,relative=1,ragged-right]
\key g \major
f4 g a b
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.printKeyCancellation = ##f
\override Staff.KeySignature #'break-visibility = #all-invisible
\key bes \major
f4 g a b \break
f4 g a b
f4 g a b
@end lilypond

Mit diesen Veränderungen bleiben nur noch die Versetzungszeichen
vor den Noten übrig um den Wechsel der Tonart anzuzeigen.

@strong{@emph{Automatische Takte}}

@funindex automaticBars

@cindex Taktstriche, unterdrücken

Ein Sonderfall sind die automatischen Taktstriche, die mit der
Eigenschaft @code{automaticBars} im @code{Score}-Kontext
ausgeschaltet werden können.  Wenn sie auf @code{#f} gesetzt
ist, werden Taktstrich nicht automatisch ausgegeben sondern
müssen explizit mit dem @code{\bar}-Befehl eingegeben werden.
Anders als bei dem @code{\cadenzaOn}-Befehl werden die Takte
allerdings immer noch gezählt.  Takterstellung wird später
wieder mit diesem Zahl aufgenommen, wenn die Eigenschaft
wieder auf @code{#t} gesetzt wird.  Wenn sie den Wert @code{#f}
hat, können Zeilenumbrüche nur an expliziten @code{\bar}-Befehlen
auftreten.

@c TODO Add example

@strong{@emph{Oktavierte Schlüssel}}

@cindex oktavierte Schlüssel, Sichtbarkeit
@cindex Sichtbarkeit von oktavierten Schlüsseln
@cindex Schlüssel, Sichtbarkeit der Oktavierung

Das kleine Oktavierungssymbol von oktavierten Notenschlüsseln
wird durch das @code{OctavateEight}-Layout-Objekt erstellt.
Seine Sichtbarkeit wird automatisch vom @code{Clef}-Objekt
geerbt, sodass Veränderungen von @code{break-visibility}
des @code{OctavateEight}-Layout-Objekts nicht auch noch
für unsichtbare Schlüssel zusätzlich vorgenommen werden müssen.

Bei expliziten Schlüsseländerungn kontrolliert die
@code{explicitClefVisibility}-Eigenschaft wohl das
Schlüsselsymbol als auch das damit verknüpfte Oktavierungssymbol.

@seealso
Handbuch zum Lernen:
@rlearning{Sichtbarkeit und Farbe von Objekten}


@node Linienstile
@subsection Linienstile
@translationof Line styles

Einige Aufführungsanweisungen (z. B. @i{rallentando} und
@i{accelerando} oder Triller werden als Text gesetzt und
möglicherweise über mehrere Takte mit Linien fortgeführt,
die teilweise gestrichelt oder gewellt sind.

Alle benutzen die gleichen Routinen wie das Glissando,
um Text und Linien zu produzieren, weshalb auch eine
Veränderungen der Erscheinung auf gleiche Weise vonstatten
geht.  Die Ausgabe erfolgt durch einen Strecker (engl. spanner), und
die Routine, die ihn setzt, heißt @code{ly:line-interface::print}.
Diese Routine bestimmt die exakte Position von zwei
@i{Strecker-Punkten} und zeichnet eine Linie zwischen sie
im gewünschten Linienstil.

Hier einige Beispiele, welche Linienstile möglich sind
und wie sie verändert werden können:

@lilypond[relative=2,ragged-right,verbatim,quote]
d2 \glissando d'2
\once \override Glissando #'style = #'dashed-line
d,2 \glissando d'2
\override Glissando #'style = #'dotted-line
d,2 \glissando d'2
\override Glissando #'style = #'zigzag
d,2 \glissando d'2
\override Glissando #'style = #'trill
d,2 \glissando d'2
@end lilypond

Die Position der Endpunkte des Streckers werden in
Realzeit für jedes graphische Objekt errechnet, aber
es ist möglich, sie manuell vorzugeben:

@c TODO Complete
@lilypond[relative=2,ragged-right,verbatim,quote]
e2 \glissando f
\once \override Glissando #'(bound-details right Y) = #-2
e2 \glissando f
@end lilypond

Der Wert von @code{Y} wird für den rechten Endpunkt auf
@w{@code{-2}} gesetzt.  Die linke Seite kann ähnlich angepasst
werden, indem man @code{left} anstelle von @code{right} angibt.

Wenn @code{Y} nicht gesetzt ist, wird der Wert ausgehend von
der vertikalen Position der linken und rechten Anbindepunkte
des Streckers errechnet.

Andere Anpassungen der Strecker sind auch möglich, für Einzelheiten
siehe @ref{Strecker}.


@node Drehen von Objekten
@subsection Drehen von Objekten
@translationof Rotating objects

Layout-Objekte und Textbeschriftungselemente können zu einem
beliebigen Winkel um einen beliebigen Punkt herum gedreht
werden, aber die Methode, mit der die Änderung vorgenommen
werden muss, unterscheidet sich je nach Objekt.

@menu
* Drehen von Layout-Objekten::
* Textbeschriftung drehen::
@end menu

@node Drehen von Layout-Objekten
@unnumberedsubsubsec Drehen von Layout-Objekten
@translationof Rotating layout objects

@cindex Drehen von Objekten
@cindex Objekte, Drehen

Alle Layout-Objekte, die das @code{grob-interface} unterstützen,
können gedreht werden, indem man ihre @code{rotation}-Eigenschaft
einstellt.  Sie erhält eine Liste mit drei Einträgen: den
Winkel der Drehung gegen den Uhrzeiger sowie die X- und
Y-Koordinaten des Punktes relativ zum Referenzpunkt des Objekts,
um welchen herum die Drehung stattfinden soll.  Der Winkel
der Drehung wird in Grad angegeben, die Koordinaten in
Notenlinienzwischenräumen.

Der Winkel der Drehung und die Koordinaten des Drehpunktes müssen
durch Ausprobieren herausgefunden werden.

@cindex Crescendoklammern, gedreht
@cindex gedrehte Crescendoklammern
@cindex schräge Crescendoklammern
@cindex Klammern, Crescendo, schräg

Es gibt nur wenige Situationen, in welchen die Drehung eines
Layout-Objektes sinnvoll ist.  Das folgende Beispiel zeigt
eine sinnvolle Anwendung:

@lilypond[quote,verbatim,relative=1]
g4\< e' d' f\!
\override Hairpin #'rotation = #'(20 -1 0)
g,,4\< e' d' f\!
@end lilypond


@node Textbeschriftung drehen
@unnumberedsubsubsec Textbeschriftung drehen
@translationof Rotating markup

Jede Textbeschriftung kann gedreht werden, indem vor die Anweisung
der Befehl @code{\rotate} gesetzt wird.  Der Befehl hat zwei
Argumente:  Den Winkel der Drehung in Grad gegen den Uhrzeiger und
der Text, der gedreht dargestllt werden soll.  Die Ausdehnung des
Textes wird nicht gedreht, sie erhält ihren Wert von den Extrempunkten
der x- und y-Koordinaten des gedrehten Textes.  Im folgenden
Beispiel wird die @code{outside-staff-priority}-Eigenschaft auf
@code{#f} gesetzt, damit automatische Zusammenstöße nicht verhindert
werden, wodurch andernfalls einige der Texte zu hoch geschoben werden
würden.

@lilypond[quote,verbatim,relative=1]
\override TextScript #'outside-staff-priority = ##f
g4^\markup { \rotate #30 "a G" }
b^\markup { \rotate #30 "a B" }
des^\markup { \rotate #30 "a D-Flat" }
fis^\markup { \rotate #30 "an F-Sharp" }
@end lilypond


@node Fortgeschrittene Optimierungen
@section Fortgeschrittene Optimierungen
@translationof Advanced tweaks

Dieser Abschnitt behandelt verschiedene Möglichkeiten, das
Aussehen des Notenbildes zu polieren.

@menu
* Objekte ausrichten::
* Vertikale Gruppierung der grafischen Objekte („grob“s)::
* stencils verändern::
* Formen verändern::
* Reine und unreine Container::
@end menu


@seealso
Handbuch zum Lernen:
@rlearning{Die Ausgabe verändern},
@rlearning{Mehr Information}.

Notationsreferenz:
@ref{Die Referenz der Programminterna erklärt},
@ref{Eigenschaften verändern},

Installierte Dateien:
@file{scm/define-grobs.scm}.

Schnipsel:
@rlsr{Tweaks and overrides}.

Erweitern:
@rextend{Schnittstellen für Programmierer}.

Referenz der Interna:
@rinternals{All layout objects}.


@node Objekte ausrichten
@subsection Objekte ausrichten
@translationof Aligning objects

Graphische Objekte, die das @code{self-alignment-interface} und/obder
das @code{side-position-interface} unterstützen, können an einem
vorher gesetzten Objekt auf verschiedene Weise ausgerichtet werden.
Eine Liste derartiger Objekte findet sich in
@rinternals{self-alignment-interface} und @rinternals{side-position-interface}.

Alle graphischen Objekte haben einen Referenzpunkt, eine horizontale
Ausdehnung und eine vertikale Ausdehnung.  Die horizontale Ausdehnung ist
ein Zahlenpaar, mit dem die Verschiebung der rechten und linken Ecken
ausgehend vom Referenzpunkt angegeben werden, wobei Verschiebungen
nach links mit negativen Zahlen notiert werden.  Die vertikale Ausdehnung
ist ein Zahlenpaar, das die Verschiebung der unteren und oberen
Ränder vom Referenzpunkt ausgehend angibt, wobei Verschiebungen nach
unten mit negativen Zahlen notiert werden.

Die Position eines Objektes auf dem Notensystem wird mit Werten
von @code{X-offset} und @code{Y-offset} angegeben.  Der Wert von
@code{X-offset} gibt die Verschiebung von der X-Koordinate des
Referenzpunkts des Elternobjektes an, der Wert von @code{Y-offset}
die Verschiebung ausgehend von der Mittellinie des Notensystemes.
Die Werte von @code{X-offset} und @code{Y-offset} können direkt
bestimmt werden oder durch Prozeduren errechnet werden, sodass
eine Ausrichtung mit dem Elternobjekt erreicht werden kann.

@warning{Viele Objekte brauchen besondere Überlegungen zu ihrer
Position, weshalb in manchen Fällen manuell gesetzte Werte von
@code{X-offset} oder @code{Y-offset} ignoriert oder verändert
werden können, obwohl das Objekt das
@code{self-alignment-interface} unterstützt.  Wenn man @code{X-offset}
oder @code{Y-offset} auf einen festen Wert setzt, wird die entsprechende
@code{self-alignment}-Eigenschaft ignoriert.}

Ein Versetzungszeichen beispielsweise kann vertikal durch Veränderung
von @code{Y-offset} verschoben werden, aber Änderungen von
@code{X-offset} haben keine Auswirkung.

Übungszeichen können an trennbaren Objekten (wie Taktstrichen,
Schlüsseln, Taktarten und Tonartvorzeichen) ausgerichtet werden.
In @code{break-aligned-interface} finden sich besondere Eigenschaften,
mit denen Übungszeichen an derartigen Objekten ausgerichtet werden können.

@seealso

Notationshandbuch:
@ref{Benutzung des break-alignable-interface}.

Erweitern:
@rextend{Callback functions}.


@menu
* X-offset und Y-offset direkt setzen::
* Das side-position-interface benutzen::
* Das self-alignment-interface benutzen::
* Benutzung des break-alignable-interface::
@end menu

@node X-offset und Y-offset direkt setzen
@unnumberedsubsubsec @code{X-offset} und @code{Y-offset} direkt setzen
@translationof Setting X-offset and Y-offset directly

Numerische Werte können den @code{X-offset}- und @code{Y-offset}-Eigenschaften
vieler Objekte zugewiesen werden.  Das folgende Beispiel zeigt
drei Noten mit der Standardposition von Fingersatzanweisungen
und die Positionen, wenn @code{X-offset} und @code{Y-offset}
verändert werden.

@lilypond[verbatim,quote,relative=2]
a-3
a
-\tweak #'X-offset #0
-\tweak #'Y-offset #0
-3
a
-\tweak #'X-offset #-1
-\tweak #'Y-offset #1
-3
@end lilypond



@node Das side-position-interface benutzen
@unnumberedsubsubsec Das @code{side-position-interface} benutzen
@translationof Using the side-position-interface

Ein Objekt, das die @code{side-position-interface}-Schnittstelle
unterstützt, kann neben sein Elternobjekt gesetzt werden,
sodass zwei definierte Enden der Objekte sich berühren.
Das Objekt kann über, unter, rechts oder links vom
Ursprungsobjekt positioniert werden.  Das Ursprungsobjekt
kann nicht definiert werden: es ergibt sich aus der Reihenfolge
der Objekte in der Eingabe.  Die meisten Objekte haben
einen Notenkopf als Ursprung assoziiert.

Die Werte von @code{side-axis} und @code{direction} bestimmen,
wo das Objekt platziert werden soll, wie in der Tabelle
zu sehen:

@c TODO add an example of each to the table

@multitable @columnfractions .3 .3 .3
@headitem @code{side-axis}-  @tab @code{direction}-  @tab
@headitem Eigenschaft          @tab Eigenschaft          @tab Platzierung

@item     @code{0}          @tab @code{-1}         @tab links
@item     @code{0}          @tab @code{1}          @tab rechts
@item     @code{1}          @tab @code{-1}         @tab unten
@item     @code{1}          @tab @code{1}          @tab oben

@end multitable

Wenn @code{side-axis} gleich @code{0} ist, sollte @code{X-offset}
auf die Prozedur @code{ly:side-position-interface::x-aligned-side}
gesetzt werden.  Diese Prozedur errechnet den richtigen Wert für
@code{X-offset}, sodass das Objekt auf der rechten oder linken
Seite des Ursprungs angeordnet wird, entsprechend dem Wert
der @code{direction}-Eigenschaft.

Wenn @code{side-axis} gleich @code{1} ist, sollte @code{Y-offset}
auf die Prozedur @code{ly:side-position-interface::y-aligned-side}
gesetzt werden.  Diese Prozedur errechnet den richtigen Wert für
@code{Y-offset}, sodass das Objekt über oder unter dem Ursprungsobjekt
angeordnet wird, entsprechend dem Wert der @code{direction}-Eigenschaft.




@node Das self-alignment-interface benutzen
@unnumberedsubsubsec Das @code{self-alignment-interface} benutzen
@translationof Using the self-alignment-interface

@emph{Selbstausrichtende Objekte horizontal}

Die horizontale Ausrichtung eines Objektes, das die
@code{self-alignment-interface}-(Selbstausrichtungs)-Schnittstelle
unterstützt, wird durch den Wert von @code{self-alignment-X}
kontrolliert, vorausgesetzt die Eigenschaft @code{X-offset} des
Objektes ist auf @code{ly:self-alignment-interface::x-aligned-on-self}
gesetzt.  @code{self-alignment-X} kann eine beliebige reale
Zahl zugewiesen werden, in Einheiten der Hälfte der
X-Gesamtausdehnung des Objekts.  Negative Werte verschieben
das Objekt nach rechts, positive nach links.  Ein Wert von
@code{0} zentriert das Objekt auf dem Referenzpunkt des
Ursprungs, ein Wert von @w{@code{-1}} richtet die linke Ecke des
Objekts am Referenzpunkt des Ursprungsobjektes aus, ein
Wert von @code{1} richtet die rechte Ecke des Objektes am
Referenzpunkt des Ursprungsobjektes aus.  Die Symbole
@code{LEFT}, @code{CENTER} und @code{RIGHT} können anstelle
von @w{@code{-1}}, @code{0} und @code{1} eingesetzt werden.

Normalerweise würde der @code{\override}-Befehl benutzt werden, um
die Werte von @code{self-alignment-X} zu verändern, aber der
@code{\tweak}-Befehl kann benutzen, um verschiedene Anmerkungen
an einer einzigen Note auszurichten:

@lilypond[quote,verbatim,relative=1]
a'
-\tweak #'self-alignment-X #-1
^"left-aligned"
-\tweak #'self-alignment-X #0
^"center-aligned"
-\tweak #'self-alignment-X #RIGHT
^"right-aligned"
-\tweak #'self-alignment-X #-2.5
^"aligned further to the right"
@end lilypond


@emph{Objekte vertikal automatisch ausrichten}

Objekte können auf ähnliche Weise auch vertikal aneinander
ausgerichtet werden, wenn ihre @code{Y-offset}-Eigenschaft
auf @code{ly:self-alignment-interface::y-aligned-on-self}
gesetzt ist.  Oft greifen jedoch auch andere Mechanismen
bei der vertikalen Ausrichtung ein:  Der Wert von
@code{Y-offset} ist nur eine der Variablen, die für die
Berechnung benutzt werden.  Darum ist es kompliziert, den
Wert für einige Objekte richtig anzupassen.  Die Einheiten
sind Halbe der vertikalen Ausdehnung des Objektes, welche
normalerweise recht klein ist, sodass ziemlich große Werte
erforderlich sein können.  Der Wert @w{@code{-1}} richtet die
untere Kante des Objekts am Referenzpunkt des Ursprungsobjektes
aus, der Wert @code{0} richtet die Mitte des Objekts am
Referenzpunkt des Ursprungsobjektes aus und der Wert @code{1}
richtet die Oberkante des Objektes am Referenzpunkt des
Ursprungsobjektes aus.  Die Symbole @code{DOWN}, @code{CENTER}
und @code{UP} können anstelle von @w{@code{-1}}, @code{0}
und @code{1} benutzt werden.

@emph{Automatische Ausrichtung in beide Richtungen}

Indem sowohl @code{X-offset} als auch @code{Y-offset} eingestellt
werden, kann ein Objekt gleichzeitig in beiden Richtungen ausgerichtet
werden.

Das folgende Beispiel zeigt, wie man eine Fingersatzanweisung so
ausrichtet, dass sie nah am Notenkopf bleibt.

@lilypond[quote,verbatim,relative=2]
a
-\tweak #'self-alignment-X #0.5  % move horizontally left
-\tweak #'Y-offset #ly:self-alignment-interface::y-aligned-on-self
-\tweak #'self-alignment-Y #-1  % move vertically up
-3  % third finger
@end lilypond




@node Benutzung des break-alignable-interface
@unnumberedsubsubsec Benutzung des @code{break-alignable-interface}
@translationof Using the break-alignable-interface

@cindex Ausrichtung an Objekten

@funindex break-align-symbols

Übungszeichen und Taktzahlen können an Notationsobjekten (ausschließlich
Taktstriche) ausgerichtet werden.  Zu diesen Objekten gehören
@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
@code{key-signature} und @code{time-signature}.

Standardmäßig werden Übungszeichen und Taktzahlen horizontal
über dem Objekt zentriert:

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be centered above the Clef
\override Score.RehearsalMark #'break-align-symbols = #'(clef)
\key a \major
\clef treble
\mark "↓"
e1
% The RehearsalMark will be centered above the TimeSignature
\override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
\key a \major
\clef treble
\time 3/4
\mark "↓"
e2.
% The rehearsal mark will be centered above the Breath Mark
\override Score.RehearsalMark #'break-align-symbols = #'(breathing-sign)
\key a \major
\clef treble
\time 4/4
e1
\breathe
\mark "↓"
@end lilypond

Eine Liste von möglichen Objekten zur Ausrichtung kann definiert
werden.  Wenn eins dieser Objekte an der aktuellen Stelle unsichtbar
ist (etwa durch Einstellung von @code{break-visibility} oder die
expliziten Sichtbarkeitseinstellungen von Taktart und Vorzeichen),
werden Übungszeichen und Taktzahlen an dem ersten Objekt in der
Liste ausgerichtet, dass sichtbar ist.  Wenn keine Objekte in der
Liste sichtbar sind, wird das Objekt am Taktstrich ausgerichtet.
Wenn der Taktstrich unsichtbar ist, wird das Objekt an der Stelle
ausgerichtet, an der sich der Taktstrich befinden würde.

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be centered above the Key Signature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e1
% The RehearsalMark will be centered above the Clef
\set Staff.explicitKeySignatureVisibility = #all-invisible
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
\key a \major
\clef bass
\mark "↓"
gis,,1
% The rehearsal mark will be centered above the Bar Line
\set Staff.explicitKeySignatureVisibility = #all-invisible
\set Staff.explicitClefVisibility = #all-invisible
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
\key a \major
\clef treble
\mark "↓"
e''1

@end lilypond

Die Ausrichtung des Übungszeichen relativ zum Notationsobjekt kann
verändert werden, wie das nächste Beispiel zeigt.  In einer Partitur
mit vielen Systemen würde man diese Einstellung für alle Systeme
vornehmen.

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be centered above the KeySignature
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\key a \major
\clef treble
\time 4/4
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the KeySignature
\once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
\mark "↓"
\key a \major
e1
% The RehearsalMark will be aligned with the right edge of the KeySignature
\once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
\key a \major
\mark "↓"
e1
@end lilypond

Das Übungszeichen kann auch nach rechts oder links um einen beliebigen Wert
verschoben werden.  Die Einheiten sind in Notenlinienzwischenräumen:

@lilypond[verbatim,quote,relative=1]
% The RehearsalMark will be aligned with the left edge of the KeySignature
% and then shifted right by 3.5 staff-spaces
\override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
\once \override Score.KeySignature #'break-align-anchor = #3.5
\key a \major
\mark "↓"
e1
% The RehearsalMark will be aligned with the left edge of the KeySignature
% and then shifted left by 2 staff-spaces
\once \override Score.KeySignature #'break-align-anchor = #-2
\key a \major
\mark "↓"
e1
@end lilypond



@node Vertikale Gruppierung der grafischen Objekte („grob“s)
@subsection Vertikale Gruppierung der grafischen Objekte („grob“s)
@translationof Vertical grouping of grobs

Die graphischen Objekte @code{VerticalAlignment} und
@code{VerticalAxisGroup} funktionieren zusammen.
@code{VerticalAxisGroup} gruppiert unterschiedliche Objekte
wie Notensysteme, Gesangstext usw. zusammen.
@code{VerticalAlignment} richtet die unterschiedlichen
Objektgruppen dann aneinander aus.  Es gibt normalerweise
nur ein @code{VerticalAlignment} in einer Partitur, aber
jedes Notensystem, Gesangstext usw. hat eine eigene
@code{VerticalAxisGroup}.


@node stencils verändern
@subsection stencils verändern
@translationof Modifying stencils

Alle Layout-Objekte haben eine @code{stencil}-(Stempel-)Eigenschaft,
die ein Teil von @code{grob-interface} ist.  Diese Eigenschaft
ist normalerweise als eine Funktion definiert, die auf das jeweilige
Objekt angepasst ist und das Symbol erstellt, dass dann im Druckbild
erscheint.  Beispielsweise die Standardeinstellung für die
@code{stencil}-Eigenschaft von @code{MultiMeasureRest}
(Ganztaktpausenobjekt) ist @code{ly:multi-measure-rest::print}.

Das Standardsymbol für jedes Objekt kann ersetzt werden, indem man
die @code{stencil}-Eigenschaft verändert, sodass sie auf eine
andere, speziell geschriebene Prozedur verweist.  Das erfordert
einen hohen Grad an Kenntnis der LilyPond-Interna, aber es gibt
einen einfacheren Weg, mit dem man oft vergleichbarere Ergebnisse
erzielen kann.

Dieser Weg besteht darin, die @code{stencil}-Eigenschaft auf die
Prozedur zu verweisen, die Text ausgibt: @code{ly:text-interface::print}
und eine @code{text}-Eigenschaft zu dem Objekt hinzuzufügen,
in welcher dann die Textbeschriftung definiert wird, mit der
das entsprechende Symbol dargestellt wird.  Aufgrund der
Flexibilität der Textbeschriftung ist hier sehr viel möglich.
Siehe zu Details insbesondere
@ref{Graphische Notation innerhalb einer Textbeschriftung}.

Das folgende Beispiel zeigt diese Methode, indem das Symbol
der Notenköpfe in ein Kreuz innerhalb eines Kreises umgewandelt
wird.

@lilypond[verbatim,quote]
XinO = {
  \once \override NoteHead  #'stencil = #ly:text-interface::print
  \once \override NoteHead #'text = \markup {
    \combine
      \halign #-0.7 \draw-circle #0.85 #0.2 ##f
      \musicglyph #"noteheads.s2cross"
  }
}
\relative c'' {
  a a \XinO a a
}
@end lilypond

Alle Schriftzeichen in der feta-Schriftart können
mit dem @code{\musicglyph}-Befehl erreicht werden.
Siehe auch @ref{Die Feta-Schriftart}.

@seealso
Notationsreferenz:
@ref{Graphische Notation innerhalb einer Textbeschriftung},
@ref{Text formatieren},
@ref{Textbeschriftungsbefehle},
@ref{Die Feta-Schriftart}.



@node Formen verändern
@subsection Formen verändern
@translationof Modifying shapes

@menu
* Bögen verändern::
@end menu

@node Bögen verändern
@unnumberedsubsubsec Bögen verändern
@translationof Modifying ties and slurs

@cindex Bögen, verändern
@cindex Bindebögen, verändern
@cindex Legatobögen, verändern
@cindex Bézier-Kurven
@cindex Kontrollpunkte, Bézier-Kurven

Binde-, Legato- und Phrasierungsbögen werden als Bézierkurven
dritter Ordnung gezeichnet.  Wenn die Form eines automatischen
Bogens nicht optimal ist, kann sie manuell verändert werdne,
indem man die vier erforderlichen Kontrollpunkte angibt.

Bézierkurven dritter Ordnung (auch als quadratische Bézierkurven
bezeichnet) werden durch vier Kontrollpunkte definiert.  Der
erste und vierte Kontrollpunkt geben Beginn und Ende der Kurve
an.  Die zwei Punkte dazwischen werden benutzt, um die Form
der Kurve zu bestimmen.  Im Internet gibt es Animationen,
die illustrieren, wie eine derartige Kurve gezeichnet wird,
aber die folgende Beschreibung kann hilfreich sein.  Die
Kurve beginnt am ersten Kontrollpunkt in Richtung des zweiten,
wobei sie sich schrittweise krümmt um zum dritten Kontrollpunkt
zu gelangen, von wo aus sie sich weiter zum vierten Punkt hin
krümmt.  Die Form der Kurve wird vollständig von den vier
Punkten definiert.

Hier ein Beispiel eines Falles, in dem der Bogen nicht optimal
erscheint, und wo auch @code{\tieDown} das Problem nicht
lösen würde.

@lilypond[verbatim,quote,relative=1]
<<
  { e1~ e }
\\
  { r4 <g c,> <g c,> <g c,> }
>>
@end lilypond

Eine Möglichkeit, diesen Bogen zu verbessern, ist es, seine
Kontrollpunkte manuell zu verändern:

Die Koordinaten von Bézierkontrollpunkten werden in
Notenlinienzwischenräumen angegeben.  Die X-Achse
ist relativ zum Referenzpunkt der Note, an die der Bogen
angefügt wird, und die Y-Achse relativ zur Mittellinie
des Notensystems.  Die Koordinaten werden als eine Liste
von vier Paaren an realen Dezimalzahlen eingegeben.  Eine
Möglichkeit ist es, die Koordinaten der zwei Endpunkte
zu schätzen und dann die zwei Zwischenpunkte zu erraten.
Die optimalen Werte können nur durch Ausprobieren gefunden
werden.

Es lohnt sich daran zu denken, dass eine symmetrische Kurve
symmetrische Kontrollpunkte benötigt, und dass Bézierkurven
die nützliche Eigenschaft haben, dass eine Transformation
der Kurve wie eine Übersetzung, Drehung oder Skalierung
der Kurve erreicht werden kann, indem man die gleiche
Skalierung auf die Kontrollpunkte anwendet.

In dem obigen Beispiel geben folgende Werte einen
zufriedenstellenden Bogen -- Achtung: der Befehl muss direkt
vor dem Beginn der Note gesetzt werden, an die der (Binde-)Bogen angehängt
wird.

@lilypond[verbatim,quote,relative=1]
<<
  {
  \once \override Tie
    #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
  e1~ e1
  }
\\
  { r4 <g c,> <g c,> <g c,>  }
>>
@end lilypond

@knownissues

Es ist nicht möglich, die Form von Bögen anhand ihrer
@code{control-points}-Eigenschaft zu verändern, wenn
mehrere Binde- oder Legatobögen zum gleichen musikalischen Moment
auftreten, nicht einmal mit dem @code{\tweak}-Befehl.  Die Eigenschaft
@code{tie-configuration} von @code{TieColumn} kann jedoch verändert
werden, sodass Startlinie und Richtung wie benötigt platziert werden.

@seealso
Referenz der Interna:
@rinternals{TieColumn}.


@cindex Scheme, reine Container
@cindex Scheme, unreine Container
@cindex reine Container, Scheme
@cindex unreine Container, Scheme
@cindex horizontale Platzierung, verändern

@node Reine und unreine Container
@subsection Reine und unreine Container
@translationof Unpure-pure containers

Unreine und reine Container (engl. unpure/pure containers) sind
nützlich, wenn man die Berechnungen der Platzierungen für die
@emph{Y-Achse} verändern will, insbesondere für @code{Y-offset}
und @code{Y-extent}.  Mit diesen Containern kann die Veränderung
durch eine Scheme-Funktion anstelle einer direkten Zahl oder eines
Paares vorgenommen werden.

Für bestimmte Grobs basiert die Eigenschaft @code{Y-extent} auf
der @code{stencil}-Eigenschaft.  Wenn diese mit @code{\override}
verändert werden soll, braucht man eine zusätzliche Veränderung
von @code{Y-extent} mit einem unreinen-reinen Container.  Wenn eine
Funktion @code{Y-offset} und/oder @code{Y-extent} verändert, wird
angenommen, dass dadurch Zeilenumbruchsberechnungen zu früh während
der Kompilation aufgerufen werden.  Die Funktion wird also überhaupt
nicht ausgewertet (und gibt also normalerweise den Wert @samp{0} oder
@samp{'(0 . 0)} zurück), wodurch sich Zusammenstöße ergeben können.
Eine @qq{saubere} Funktion beeinflusst keine Eigeschaften, Objekte
oder Grob-Suizide, weshalb ihre Werte, die sich auf @code{Y-axis}
beziehen, richtig berechnet werden.

Es gibt zuzeit etwa 30 Funktionen, die schon als @qq{sauber} erachtet
werden, und unsaubere-saubere Container sind eine Möglichkeit, auch
Funktionen, die sich nicht auf dieser Liste befinden, als @qq{sauber}
zu markieren.  Die @qq{saubere} Funktion wird ausgewertet, @emph{bevor}
Seitenumbruch stattfindet, sodass die horizontale Platzierung
@qq{rechtzeitig} stattfindet.  Die @qq{unsaubere} Funktion wird dann
@emph{nach} dem Seitenumbruch ausgewertet.

@warning{Da es schwierig ist, immer sicher zu sein, welche Funktionen sich
auf dieser Liste befinden, wird empfohlen, dass die selbsterstellten
@qq{sauberen} Funktionen nicht die Grobs @code{Beam} oder @code{VerticalAlignment}
einsetzen.}

Ein unsauberer-sauberer Container wird wie folgend erstellt:

@code{(ly:make-unpure-pure-container f0 f1)}

wobei @code{f0} eine Fuktion ist, die @var{n} Arguments braucht
(@var{n >= 1}) und deren erstes Argument immer der Grob sein muss.
Das ist die Funktion, die das eigentliche Resultat ausgibt.  @var{f1}
ist die Funktion, die als @qq{sauber} bezeichnet wird, und braucht @var{n + 2}
Argumente.  Wiederum muss das erste Argument immer der Grob sein, aber
das erste und zweite Argument sind @qq{Beginn-} und @qq{Endeargumente}.



@var{start} (Beginn) und @var{end} (Ende) sind absichtlich
nur Platzhalter, die nur für die Strecker gelten (etwa @code{Hairpin} oder
@code{Beam}), die unterschiedliche Höhenberechnungen je nach beginnender und
endender Note ausgeben können.

Der Rest sind andere Argumente für die erste Funktion (es können auch
Null sein, wenn @var{n = 1}).

Die Ergebnisse der zweiten Funktion werden als Näherungswert des benötigten
Wertes benutzt, welche dann von der ersten Funktion eingesetzt wird,
um den wirklichen Wert auszugeben, mit dem dann sehr viel später im
Layoutprozess die Platzierung justiert werden soll.

@lilypond[verbatim,quote,ragged-right]
#(define (square-line-circle-space grob)
(let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
      (notename (ly:pitch-notename pitch)))
 (if (= 0 (modulo notename 2))
     (make-circle-stencil 0.5 0.0 #t)
     (make-filled-box-stencil '(0 . 1.0)
                              '(-0.5 . 0.5)))))

squareLineCircleSpace = {
  \override NoteHead #'stencil = #square-line-circle-space
}

smartSquareLineCircleSpace = {
  \squareLineCircleSpace
  \override NoteHead #'Y-extent =
   #(ly:make-unpure-pure-container
      ly:grob::stencil-height
      (lambda (grob start end) (ly:grob::stencil-height grob)))
}

\new Voice \with { \remove "Stem_engraver" }
\relative c'' {
  \squareLineCircleSpace
  cis4 ces cisis c
  \smartSquareLineCircleSpace
  cis4 ces cisis c
}
@end lilypond

Im ersten Takt weiß die Layoutmaschine ohne den unsauberen-sauberen
Container nicht die Breite des Notenkopfes und lässt ihn deshalb mit
den Versetzungszeichen zusammenstoßen.  Im zweiten Takt, mit
unreinen-reinen Containern, weiß die Layoutmaschine die Breite
des Notenkopfes und vermeidet den Zusammenstoßf, indem die Zeile
entsprechend verlängert wird.

Normalerweise können für eine einfache Berechnungen fast identische
Funktionen für den @qq{unsauberen} und @qq{sauberen} Teil benutzt
werden, indem nur die Zahl der Argumente und die Reichweite der
Funktion verändert wird.

@warning{Wenn eine Funktion als @qq{sauber} bezeichnet ist und das aber
nicht ist, können unerwartete Ergebnisse auftreten.}


@node Musikfunktionen benutzen
@section Musikfunktionen benutzen
@translationof Using music functions

@c TODO -- add @seealso, etc. to these subsections

Wenn Optimierungen von unterschiedlichen musikalischen Ausdrücken
wiederverwendet werden sollen, bietet es sich oft an, den
@qq{Optimierungsanteil} einer @emph{musikalischen Funktion} zu
erstellen.  In diesem Abschnitt sollen nur @emph{Ersetzungen}
erklärt werden, wo es darum geht, eine Variable mit einem Stück
LilyPond-Code zu ersetzen.  Andere komplexere Funktionen werden
beschrieben in @rextend{Musikalische Funktionen}.

@menu
* Syntax der Ersetzungsfunktion::
* Beispiele der Ersetzungsfunktionen::
@end menu

@node Syntax der Ersetzungsfunktion
@subsection Syntax der Ersetzungsfunktion
@translationof Substitution function syntax

Es ist einfach eine Funktion zu erstellen, die eine Variable
in LilyPond-Code umwandelt.  Die generelle Form dieser
Funktionen ist:

@example
Funktion =
#(define-music-function
     (parser location @var{Arg1} @var{Arg2} @dots{})
     (@var{Typ1?} @var{Typ2?} @dots{})
   #@{
     @var{@dots{}Noten@dots{}}
   #@})
@end example

@noindent
wobei

@multitable @columnfractions .33 .66
@item @code{@var{ArgN}}
@tab @var{n}tes Argument

@item @code{@var{TypN?}}
@tab ein Scheme @emph{Typenprädikat}, für das @code{@var{ArgN}}
den Wert @code{#t} ausgibt.

@item @code{@var{@dots{}Noten@dots{}}}
@tab normale LilyPond-Eingabe, wobei @code{$} (wenn nur LilyPond-Konstruktionen
erlaubt sind) oder @code{#} (um es als Scheme-Wert oder Argument einer
musikalischen Funktionen einzusetzen) benutzt wird, um
Argumente zu referenzieren (etwa @samp{$Arg1}).
@end multitable

Die @code{parser} und @code{location}-Argumente sind zwingend und
werden in einigen fortgeschrittenen Situationen benutzt, wie sie
im @qq{Erweitern}-Handbuch beschrieben werden (siehe
@rextend{Musikalische Funktionen}).  In Ersetzungsfunktionen
gehen Sie einfach sicher, dass sie die beiden Wörter auch mit
aufnehmen.

Die Liste der Typenprädikate ist auch notwendig.  Einige der
häufigsten Typenprädikate, die in musikalischen Funktionen
benutzt werden, sind:

@example
boolean?
cheap-list?  @emph{(benutze anstelle von }@q{list?}@emph{ für schnelleres Kompilieren)}
ly:duration?
ly:music?
ly:pitch?
markup?
number?
pair?
string?
symbol?
@end example

@noindent
Eine Liste aller Typprädikate findet sich unter
@ref{Vordefinierte Typprädikate}.  Eigene Typprädikate
sind auch erlaubt.


@seealso

Notationsreferenz:
@ref{Vordefinierte Typprädikate}.

Erweitern:
@rextend{Musikalische Funktionen}.

Installierte Dateien:
@file{lily/music-scheme.cc},
@file{scm/c++.scm},
@file{scm/lily.scm}.


@node Beispiele der Ersetzungsfunktionen
@subsection Beispiele der Ersetzungsfunktionen
@translationof Substitution function examples

Dieser Abschnitt zeigt einige Beispiele von Ersetzungsfunktionen.
Sie sind nicht vollständig, sondern sollen einige der
Möglichkeiten von einfachen Ersetzungsfunktionen aufzeigen.

Im ersten Beispiel wird eine Funktione definiert, die
das Verschieben von @code{TextScript} erleichtert:

@lilypond[quote,verbatim,ragged-right]
padText =
#(define-music-function
     (parser location padding)
     (number?)
   #{
     \once \override TextScript #'padding = #padding
   #})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond

Neben Zahlen können auch musikalische Ausdrücke wie Noten
als Argumente für musikalische Funktionen eingesetzt werden:

@c TODO: use a better example (the music argument is redundant).

@lilypond[quote,verbatim,ragged-right]
custosNote =
#(define-music-function
     (parser location note)
     (ly:music?)
   #{
     \once \override Voice.NoteHead #'stencil =
       #ly:text-interface::print
     \once \override Voice.NoteHead #'text =
       \markup \musicglyph #"custodes.mensural.u0"
     \once \override Voice.Stem #'stencil = ##f
     $note
   #})

\relative c' { c4 d e f \custosNote g }
@end lilypond

Ersetzungsfunktionen mit mehrfachen Argumenten können definiert
werden:

@lilypond[quote,verbatim,ragged-right]
tempoPadded =
#(define-music-function
     (parser location padding tempotext)
     (number? string?)
   #{
     \once \override Score.MetronomeMark #'padding = #padding
     \tempo \markup { \bold #tempotext }
   #})

\relative c'' {
  \tempo \markup { "Low tempo" }
  c4 d e f g1
  \tempoPadded #4.0 #"High tempo"
  g4 f e d c1
}
@end lilypond