@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
- Translation of GIT committish: 3d7ffa1f82bb44673134b28becf7898482fe7316
+ Translation of GIT committish: 144cd434d02e6d90b2fb738eeee99119a7c5e1d2
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
Fortgeschrittene Anpassungen können mithilfe der Programmiersprache
Scheme vorgenommen werden. Wenn Sie Scheme nicht kennen, gibt
es eine grundlegende Einleitung in LilyPonds
-@rlearning{Scheme-Übung}.
+@ref{Scheme-Übung}.
@menu
* Musikalische Funktionen::
-* Schnittstelle für Programmierer::
-* Komplizierte Funktionen erstellen::
-* Programmierungsschnittstelle für Textbeschriftungen::
+* Textbeschriftungsfunktionen::
* Kontexte für Programmierer::
-* Scheme-Vorgänge als Eigenschaften::
-* Scheme-Code anstelle von \tweak verwenden::
+* Callback-Funktionen::
+* Scheme-Code innerhalb LilyPonds::
* Schwierige Korrekturen::
@end menu
@translationof Music functions
Dieser Abschnitt behandelt die Erstellung von musikalischen Funktionen
-innerhalb von LilyPond.
+innerhalb von LilyPond. @emph{Musikalische Funktionen} sind Scheme-Prozeduren,
+die musikalische Ausdrücke automatisch erstellen können und dadurch die
+Eingabedatei maßgeblich vereinfachen können.
@menu
-* Überblick über musikalische Funktionen::
+* Syntax der musikalischen Funktionen::
* Einfache Ersetzungsfunktionen::
-* Paarige Ersetzungsfunktionen::
+* Mittlere Ersetzungsfunktionen::
* Mathematik in Funktionen::
-* Leere Funktionen::
* Funktionen ohne Argumente::
-* Überblick über vorhandene musikalische Funktionen::
+* Leere Funktionen::
@end menu
-@node Überblick über musikalische Funktionen
-@subsection Überblick über musikalische Funktionen
-@translationof Overview of music functions
+@node Syntax der musikalischen Funktionen
+@subsection Syntax der musikalischen Funktionen
+@translationof Music function syntax
-Es ist einfach, eine Funktion zu erstellen, die Variablen
-im LilyPond-Code ersetzt. Die allgemeine Form derartiger
-Funktionen ist
+Die allgemeine Form von musikalischen Funktionen ist:
@example
function =
-#(define-music-function (parser location @var{var1} @var{var2}...@var{vari}... )
- (@var{var1-type?} @var{var2-type?}...@var{vari-type?}...)
- #@{
- @emph{...Noten...}
- #@})
+#(define-music-function
+ (parser location @var{Arg1} @var{Arg2} @dots{})
+ (@var{Typ1?} @var{Typ2?} @dots{})
+ @var{Noten})
@end example
@noindent
wobei
@multitable @columnfractions .33 .66
-@item @var{vari} @tab die @var{i}te Variable
-@item @var{vari-type?} @tab die Art der @var{i}ten Variable
-@item @var{...Noten...} @tab normaler LilyPond-Code, in dem Variablen
-wie @code{#$var1} usw. benutzt werden.
-@end multitable
+@item @var{ArgN}
+@tab das @var{n}te Argument
-Die folgenden Eingabetypen können als Variablen in einer musikalischen
-Funktion benutzt werden. Diese Liste ist nicht vollständig -- siehe
-auch andere Dokumentationen über Scheme für weitere Variablenarten.
+@item @var{TypN?}
+@tab ein Scheme-Typenprädikat (engl. type predicate), für welches
+@code{@var{ArgN}} @code{#t} ausgeben muss
+
+@item @var{...Noten...}
+@tab ein musikalischer Ausdruck, optional in Scheme geschrieben, mit allem
+LilyPond-Code in Raute/geschweifte Klammer eingeschlossen
+(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}). Innerhalb der LilyPond-Codeumgebungen
+wird @code{$} eingesetzt, um auf Funktionsargumente zu verweisen (etwa
+@samp{$Arg1}), oder ein neuer Scheme-Ausdruck muss begonnen werden,
+der die Funktionsargumente enthält (etwa @w{@samp{$(cons Arg1 Arg2)}}).
-@multitable @columnfractions .33 .66
-@headitem Eingabetyp @tab @var{vari-type?}-Notation
-@item Ganzzahl @tab @code{integer?}
-@item Float (Dezimalzahl) @tab @code{number?}
-@item Zeichenkette @tab @code{string?}
-@item Textbeschriftung @tab @code{markup?}
-@item Musikalischer Ausdruck @tab @code{ly:music?}
-@item Ein Variablenpaar @tab @code{pair?}
@end multitable
-Die Argumente @code{parser} und @code{location} sind zwingend erforderlich
-und werden in einigen fortgeschrittenen Situationen eingesetzt. Das
-Argument @code{parser} wird benutzt, um auf den Wert einer weiteren
-LilyPond-Variable zuzugreifen. Das Argument @code{location} wird
-benutzt, um den @qq{Ursprung} des musikalischen Ausdrucks zu definieren, der von
-der musikalischen Funktion erzeugt wird. Das hilft, wenn ein
-Syntaxfehler auftaucht: in solchen Fällen kann LilyPond mitteilen,
-an welcher Stelle in der Eingabedatei sich der Fehler befindet.
+Eine Liste der möglichen Typenprädikate findet sich in
+@ruser{Vordefinierte Typenprädikate}. Durch den Benutzer definierte
+Typenprädikate sind auch erlaubt.
+@seealso
-@node Einfache Ersetzungsfunktionen
-@subsection Einfache Ersetzungsfunktionen
-@translationof Simple substitution functions
+Notationsreferenz:
+@ruser{Vordefinierte Typenprädikate}.
-Hier ist ein einfaches Beispiel:
+Installierte Dateien:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
-@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
-Musikalische Ausdrücke können auch ersetzt werden:
-
-@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
- #})
-
-{ c' d' e' f' \custosNote g' }
-@end lilypond
-
-Mehrere Variablen können benutzt werden:
+@node Einfache Ersetzungsfunktionen
+@subsection Einfache Ersetzungsfunktionen
+@translationof Simple substitution functions
-@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 }
-#})
+Einfache Ersetzungsfunktionen sind musikalische Funktionen, deren
+musikalische Ausgabe-Funktion im LilyPond-Format geschrieben ist
+und Funktionsargumente in der Ausgabefunktion enthält. Sie werden
+beschrieben in @ruser{Beispiele der Ersetzungsfunktionen}
-\relative c'' {
- \tempo \markup { "Low tempo" }
- c4 d e f g1
- \tempoPadded #4.0 #"High tempo"
- g4 f e d c1
-}
-@end lilypond
+@node Mittlere Ersetzungsfunktionen
+@subsection Mittlere Ersetzungsfunktionen
+@translationof Intermediate substitution functions
-@node Paarige Ersetzungsfunktionen
-@subsection Paarige Ersetzungsfunktionen
-@translationof Paired substitution functions
+Mittlere Ersetzungsfunktionen setzen sich aus einer Mischung von
+Scheme-Code und LilyPond-Code in der musikalischen Ausgabe-Funktion
+zusammen.
Einige @code{\override}-Befehle benötigen ein Zahlenpaar
-(als @code{cons}-Zelle in Scheme bezeichnet). Um beide Zahlen
-einer Funktion zuzuweisen, kann entweder die Variable @code{pair?}
-benutzt werden oder die @code{cons} in die musikalische Funktion
-eingefügt werden.
+(als @code{cons}-Zelle in Scheme bezeichnet).
+
+Das Paar kann direkt an die musikalische Funktion
+mit der Variable @code{pair?} weitergeleitet werden:
-@quotation
@example
manualBeam =
-#(define-music-function (parser location beg-end)
- (pair?)
-#@{
- \once \override Beam #'positions = #$beg-end
-#@})
-
-\relative @{
+#(define-music-function
+ (parser location beg-end)
+ (pair?)
+ #@{
+ \once \override Beam #'positions = $beg-end
+ #@})
+
+\relative c' @{
\manualBeam #'(3 . 6) c8 d e f
@}
@end example
-@end quotation
-@noindent
-oder
+Anstelle dessen können auch die Zahlen, aus denen das Paar besteht,
+einzeln als eigenständige Argumente weitergeleitet und der
+Scheme-Code, der das Paar erstellt, in die musikalische Funktion
+augenommen werden:
@lilypond[quote,verbatim,ragged-right]
manualBeam =
-#(define-music-function (parser location beg end)
- (number? number?)
-#{
- \once \override Beam #'positions = #(cons $beg $end)
-#})
-
-\relative {
+#(define-music-function
+ (parser location beg end)
+ (number? number?)
+ #{
+ \once \override Beam #'positions = $(cons beg end)
+ #})
+
+\relative c' {
\manualBeam #3 #6 c8 d e f
}
@end lilypond
auch Scheme-Programmcode enthalten:
@lilypond[quote,verbatim,ragged-right]
-AltOn = #(define-music-function (parser location mag) (number?)
- #{ \override Stem #'length = #$(* 7.0 mag)
+AltOn =
+#(define-music-function
+ (parser location mag)
+ (number?)
+ #{
+ \override Stem #'length = $(* 7.0 mag)
\override NoteHead #'font-size =
- #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
+ $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
+ #})
AltOff = {
\revert Stem #'length
\revert NoteHead #'font-size
}
-{ c'2 \AltOn #0.5 c'4 c'
- \AltOn #1.5 c' c' \AltOff c'2 }
+\relative c' {
+ c2 \AltOn #0.5 c4 c
+ \AltOn #1.5 c c \AltOff c2
+}
@end lilypond
@noindent
zu integrieren:
@lilypond[quote,verbatim,ragged-right]
-withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
- #{ \override Stem #'length = #$(* 7.0 mag)
+withAlt =
+#(define-music-function
+ (parser location mag music)
+ (number? ly:music?)
+ #{
+ \override Stem #'length = $(* 7.0 mag)
\override NoteHead #'font-size =
- #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
+ $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
$music
\revert Stem #'length
- \revert NoteHead #'font-size #})
+ \revert NoteHead #'font-size
+ #})
-{ c'2 \withAlt #0.5 {c'4 c'}
- \withAlt #1.5 {c' c'} c'2 }
+\relative c' {
+ c2 \withAlt #0.5 { c4 c }
+ \withAlt #1.5 { c c } c2
+}
@end lilypond
-@node Leere Funktionen
-@subsection Leere Funktionen
-@translationof Void functions
-
-Eine musikalische Funktion muss einen musikalischen Ausdruck
-ausgeben, aber in manchen Fällen müssen Funktionen erstellt werden,
-die keine Notation enthalten (wie etwa eine Funktion, mit der
-man @qq{Point and Click} ausschalten kann). Um das vornehmen zu
-können, wird ein @code{leere}r musikalischer Ausdruck ausgegeben.
-
-Das ist der Grund, warum die Form, die ausgegeben wird,
-@code{(make-music ...)} heißt. Wird die Eigenschaft
-@code{'void} (engl. für @qq{leer}) auf @code{#t} gesetzt, wird der
-Parser angewiesen, den ausgegebenen musikalischen Ausdruck zu ignorieren.
-Der maßgebliche Teil der @code{'void}-Funktion ist also die Verarbeitung,
-die die Funktion vornimmt, nicht der musikalische Ausdruck, der ausgegeben
-wird.
-
-@example
-noPointAndClick =
-#(define-music-function (parser location) ()
- (ly:set-option 'point-and-click #f)
- (make-music 'SequentialMusic 'void #t))
-...
-\noPointAndClick % disable point and click
-@end example
-
-
@node Funktionen ohne Argumente
@subsection Funktionen ohne Argumente
@translationof Functions without arguments
@example
displayBarNum =
-#(define-music-function (parser location) ()
+#(define-music-function
+ (parser location)
+ ()
(if (eq? #t (ly:get-option 'display-bar-numbers))
#@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
#@{#@}))
aufgerufen werden.
-@node Überblick über vorhandene musikalische Funktionen
-@subsection Überblick über vorhandene musikalische Funktionen
-@translationof Overview of available music functions
-
-@c fixme ; this should be move somewhere else?
-Die folgenden Befehle sind musikalische Funktionen:
-
-@include identifiers.tely
-
-
-
-@node Schnittstelle für Programmierer
-@section Schnittstelle für Programmierer
-@translationof Programmer interfaces
-
-Dieser Abschnitt zeigt, wie LilyPond und
-Scheme gemischt werden können.
-
-@menu
-* Eingabevariablen und Scheme::
-* Interne Repräsentation der Musik::
-@end menu
-
-
-@node Eingabevariablen und Scheme
-@subsection Eingabevariablen und Scheme
-@translationof Input variables and Scheme
-
-Das Eingabeformat unterstützt die Notation von Variablen: im
-folgenden Beispiel wird ein musikalischer Ausdruck einer Variable
-mit der Bezeichnung @code{traLaLa} zugewiesen:
-
-@example
-traLaLa = @{ c'4 d'4 @}
-@end example
-
-Der Geltungsbereich von Variablen ist beschränkt: im folgenden
-Beispiel enthält die @code{\layout}-Umgebung auch eine
-@code{traLaLa}-vVariable, die unabhängig von der äußeren
-@code{\traLaLa}-Variable ist:
-
-@example
-traLaLa = @{ c'4 d'4 @}
-\layout @{ traLaLa = 1.0 @}
-@end example
-
-Grundsätzlich ist jede Eingabedatei ein Geltungsbereich, und
-alle @code{\header}-, @code{\midi}- und @code{\layout}-Umgebungen
-sind Geltungsbereiche, die unterhalb des globalen Geltungsbereiches
-angeordnet sind.
-
-Sowohl Variablen als auch Geltungsbereiche sind in Form des
-GUILE-Modulsystems implementiert. Ein anonymes Scheme-Modul
-wird an jeden Geltungsbereich angehängt. Eine Zuweisung der Form
-
-@example
-traLaLa = @{ c'4 d'4 @}
-@end example
-
-@noindent
-wird intern in die Scheme-Definition
-
-@example
-(define traLaLa @var{Scheme-Wert von `@code{... }'})
-@end example
-@noindent
-umgewandelt.
-
-Das bedeutet, dass Eingabe- und Scheme-Variablen frei vermischt
-werden können. Im nächsten Beispiel wird ein Notenfragment in
-der Variable @code{traLaLa} gespeichert und mithilfe von Scheme
-dupliziert. Das Ergebnis wird in eine @code{\score}-Umgebung
-mit der zweiten Variable @code{twice} integriert:
-
-@lilypond[verbatim]
-traLaLa = { c'4 d'4 }
-
-%% dummy action to deal with parser lookahead
-#(display "this needs to be here, sorry!")
-
-#(define newLa (map ly:music-deep-copy
- (list traLaLa traLaLa)))
-#(define twice
- (make-sequential-music newLa))
-
-{ \twice }
-@end lilypond
-
-In diesem Beispiel geschieht die Zuweisung, nachdem der Parser
-festgestellt hat, dass nichts interessantes mehr nach
-@code{traLaLa = @{ ... @}} vorkommt. Ohne die Pseudovariable
-in dem Beispiel würde die @code{newLa}-Definition ausgeführt
-werden, bevor @code{traLaLa} definiert ist, was zu einem
-Syntax-Fehler führen würde.
-
-Das obige Beispiel zeigt, wie man musikalische Ausdrücke
-von der Eingabe in den Scheme-Interpretierer @qq{exportieren}
-kann. Es geht auch in die andere Richtung. Indem man einen
-Scheme-Wert in die Funktion @code{ly:export} einpackt, wird
-der Scheme-Wert interpretiert als ob er in LilyPond-Syntax
-notiert worden wäre. Anstatt @code{\twice} zu definieren,
-hätte man also auch schreiben können:
+@node Leere Funktionen
+@subsection Leere Funktionen
+@translationof Void functions
-@example
-...
-@{ #(ly:export (make-sequential-music (list newLa))) @}
-@end example
+Eine musikalische Funktion muss einen musikalischen Ausdruck
+ausgeben, aber in manchen Fällen müssen Funktionen erstellt werden,
+die keine Noten enthalten (wie etwa eine Funktion, mit der
+man @qq{Point and Click} ausschalten kann). Um das vornehmen zu
+können, wird ein @code{leere}r musikalischer Ausdruck ausgegeben.
-Scheme-Code wird sofort ausgewertet, wenn der Parser darauf
-stößt. Um Scheme-Code in einem Makro zu definieren (das dann
-erst später aufgerufen werden soll), müssen leere Funktionen
-benutzt werden (siehe @ref{Leere Funktionen}) oder das Folgende:
+Das ist der Grund, warum die Form, die ausgegeben wird,
+@w{@code{(make-music @dots{})}} heißt. Wird die Eigenschaft
+@code{'void} (engl. für @qq{leer}) auf @code{#t} gesetzt, wird der
+Parser angewiesen, den ausgegebenen musikalischen Ausdruck zu ignorieren.
+Der maßgebliche Teil der @code{'void}-Funktion ist also die Verarbeitung,
+die die Funktion vornimmt, nicht der musikalische Ausdruck, der ausgegeben
+wird.
@example
-#(define (nopc)
- (ly:set-option 'point-and-click #f))
-
+noPointAndClick =
+#(define-music-function
+ (parser location)
+ ()
+ (ly:set-option 'point-and-click #f)
+ (make-music 'SequentialMusic 'void #t))
...
-#(nopc)
-@{ c'4 @}
-@end example
-
-@knownissues
-
-Scheme- und LilyPond-Variablen können im LilyPond-Modus mit der
-@code{--safe}-Option nicht vermischt werden.
-
-
-@node Interne Repräsentation der Musik
-@subsection Interne Repräsentation der Musik
-@translationof Internal music representation
-
-Wenn ein musikalischer Ausdruck ausgewertet wird, wird er in eine
-Anzahl von musikalischen Scheme-Objekten konvertiert. Die Eigenschaft, die ein
-musikalisches Objekt definiert, ist, dass es Zeit einnimmt. Zeit ist
-eine rationale Zahl, die die Länge eines Stückes in ganzen Noten
-misst.
-
-Ein musikalisches Objekt hat drei Typusarten:
-@itemize
-@item
-musikalische Bezeichnung: Jeder musikalische Ausdruck hat eine Bezeichnung.
-Eine Note beispielsweise führt zu einem @rinternals{NoteEvent} und
-@code{\simultaneous} führt zu @rinternals{SimultaneousMusic}. Eine Liste
-aller möglichen Ausdrücke findet sich in der Referenz der Interna, unter
-@rinternals{Music expressions}.
-
-@item
-@q{Typ} oder Schnittstelle: Jede musikalische Bezeichnung hat mehrere
-@qq{Typen} oder Schnittstellten, beispielsweise ist eine Note ein
-@code{event}, ober sie ist auch ein @code{note-event}, ein
-@code{rhythmic-event} und ein @code{melodic-event}. Alle diese
-Notationsklassen finden sich in der Referenz der Interna unter
-@rinternals{Music classes}.
-
-@item
-C++-Objekt: Jedes musikalische Objekt wird von einem Objekt der
-C++-Klasse @code{Music} repräsentiert.
-@end itemize
-
-Die eigentlich Information eines musikalischen Ausdrucks ist in
-Eigenschaften gespeichert. Ein @rinternals{NoteEvent} hat zum
-Beispiel @code{pitch}- und @code{duration}-Eigenschaften, die
-die Tonhöhe und die Dauer dieser Note speichern. Eine Liste aller
-verfügbaren Eigenschaften findet sich in der Referenz der Interna unter
-@rinternals{Music properties}.
-
-Ein zusammengesetzter musikalischer Ausdruck ist ein musikalisches
-Objekt, das andere Objekte in seinen Eigenschaften enthält. Eine Liste
-der Objekte kann in der @code{elements}-Eigenschaft eines
-musikalischen Objektes gespeichert werden, oder ein einziges
-@qq{Kind}-Objekt in der @code{element}-Eigenschaft. Sa hat etwa
-@rinternals{SequentialMusic} seine @qq{Kinder} in @code{elements},
-und @rinternals{GraceMusic} hat sein einziges Argument in
-@code{element}. Der Hauptteil einer Wiederholung wird in der
-@code{element}-Eigenschaft von @rinternals{RepeatedMusic} gespeichert,
-und die Alternativen in @code{elements}.
-
-
-
-@node Komplizierte Funktionen erstellen
-@section Komplizierte Funktionen erstellen
-@translationof Building complicated functions
-
-Dieser Abschnitt zeigt, wie man Information zusammensucht,
-um komplizierte musikalische Funktionen zu erstellen.
-
-@menu
-* Musikalische Funktionen darstellen::
-* Eigenschaften von Musikobjekten::
-* Verdoppelung einer Note mit Bindebögen (Beispiel)::
-* Artikulationszeichen zu Noten hinzufügen (Beispiel)::
-@end menu
-
-
-@node Musikalische Funktionen darstellen
-@subsection Musikalische Funktionen darstellen
-@translationof Displaying music expressions
-
-@cindex interne Speicherung
-@cindex Musikausdrücke anzeigen
-@cindex Anzeigen von Musikausdrücken
-
-@funindex displayMusic
-@funindex \displayMusic
-
-Wenn man eine musikalische Funktion erstellt, ist es oft
-hilfreich sich anzuschauen, wie musikalische Funktionen
-intern gespeichert werden. Das kann mit der Funktion
-@code{\displayMusic} erreicht werden:
-
-@example
-@{
- \displayMusic @{ c'4\f @}
-@}
-@end example
-
-@noindent
-zeigt:
-
-@example
-(make-music
- 'SequentialMusic
- 'elements
- (list (make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch 0 0 0))
- (make-music
- 'AbsoluteDynamicEvent
- 'text
- "f")))))
-@end example
-
-Normalerweise gibt LilyPond diese Ausgabe auf der Konsole mit
-allen anderen Nachrichten aus. Um die wichtigen Nachrichten
-in einer Datei zu speichern, kann die Ausgabe in eine Datei
-umgeleitet werden:
-
-@example
-lilypond file.ly >display.txt
-@end example
-
-Mit etwas Umformatierung ist die gleiche Information sehr viel
-einfacher zu lesen:
-
-@example
-(make-music 'SequentialMusic
- 'elements (list (make-music 'EventChord
- 'elements (list (make-music 'NoteEvent
- 'duration (ly:make-duration 2 0 1 1)
- 'pitch (ly:make-pitch 0 0 0))
- (make-music 'AbsoluteDynamicEvent
- 'text "f")))))
-@end example
-
-Eine musikalische @code{@{ ... @}}-Sequenz hat die Bezeichnung
-@code{SequentialMusic} und ihre inneren Ausdrücke werden als
-Liste in seiner @code{'elements}-Eigenschaft gespeichert. Eine
-Note ist als als ein @code{EventChord}-Ausdruck dargestellt,
-der ein @code{NoteEvent}-Objekt (welches Dauer und
-Tonhöhe speichert) und zusätzliche Information enthält (in
-diesem Fall ein @code{AbsoluteDynamicEvent} mit einer
-@code{"f"}-Text-Eigenschaft.
-
-
-@node Eigenschaften von Musikobjekten
-@subsection Eigenschaften von Musikobjekten
-@translationof Music properties
-
-Das @code{NoteEvent}-Objekt ist das erste Objekt der
-@code{'elements}-Eigenschaft von @code{someNote}.
-
-@example
-someNote = c'
-\displayMusic \someNote
-===>
-(make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch 0 0 0))))
-@end example
-
-Die @code{display-scheme-music}-Funktion ist die Funktion, die von
-@code{\displayMusic} eingesetzt wird, um die Scheme-Repräsentation
-eines musikalischen Ausdrucks anzuzeigen.
-
-@example
-#(display-scheme-music (first (ly:music-property someNote 'elements)))
-===>
-(make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch 0 0 0))
-@end example
-
-Danach wird die Tonhöhe der Note von der @code{'pitch}-Eigenschaft
-des @code{NoteEvent}-Objektes gelesen:
-
-@example
-#(display-scheme-music
- (ly:music-property (first (ly:music-property someNote 'elements))
- 'pitch))
-===>
-(ly:make-pitch 0 0 0)
-@end example
-
-Die Tonhöhe einer Note kann geändert werden, indem man diese
-@code{'pitch}-Eigenschaft umdefiniert:
-
-@funindex \displayLilyMusic
-@funindex displayLilyMusic
-
-@example
-#(set! (ly:music-property (first (ly:music-property someNote 'elements))
- 'pitch)
- (ly:make-pitch 0 1 0)) ;; Die Tonhöhen auf d' verändern.
-\displayLilyMusic \someNote
-===>
-d'
-@end example
-
-
-@node Verdoppelung einer Note mit Bindebögen (Beispiel)
-@subsection Verdoppelung einer Note mit Bindebögen (Beispiel)
-@translationof Doubling a note with slurs (example)
-
-In diesem Abschnitt soll gezeigt, werden, wie man eine
-Funktion erstellt, die eine Eingabe wie @code{a}
-nach @code{a( a)} umdefiniert. Dazu wird zuerst die
-interne Repräsentation der Musik betrachtet, die
-das Endergebnis darstellt:
-
-@example
-\displayMusic@{ a'( a') @}
-===>
-(make-music
- 'SequentialMusic
- 'elements
- (list (make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch 0 5 0))
- (make-music
- 'SlurEvent
- 'span-direction
- -1)))
- (make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch 0 5 0))
- (make-music
- 'SlurEvent
- 'span-direction
- 1)))))
-@end example
-
-Eine schlechte Nachricht ist, dass die
-@code{SlurEvent}-Ausdrücke @qq{innerhalb}
-der Noten (bzw. innerhalb der
-@code{EventChord}-Ausdrücke) hinzugefügt werden müssen.
-
-Jetzt folgt eine Betrachtung der Eingabe:
-
-@example
-(make-music
- 'SequentialMusic
- 'elements
- (list (make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch 0 5 0))))))
-@end example
-
-In der gewünschten Funktion muss also dieser Ausdruck
-kopiert werden (sodass zwei Noten vorhanden sind, die
-eine Sequenz bilden), dann müssen @code{SlurEvent}
-zu der @code{'elements}-Eigenschaft jeder Noten hinzugefügt
-werden, und schließlich muss eine @code{SequentialMusic}
-mit den beiden @code{EventChords} erstellt werden.
-
-@example
-doubleSlur = #(define-music-function (parser location note) (ly:music?)
- "Return: @{ note ( note ) @}.
- `note' is supposed to be an EventChord."
- (let ((note2 (ly:music-deep-copy note)))
- (set! (ly:music-property note 'elements)
- (cons (make-music 'SlurEvent 'span-direction -1)
- (ly:music-property note 'elements)))
- (set! (ly:music-property note2 'elements)
- (cons (make-music 'SlurEvent 'span-direction 1)
- (ly:music-property note2 'elements)))
- (make-music 'SequentialMusic 'elements (list note note2))))
+\noPointAndClick % Point and Click ausschalten
@end example
-@node Artikulationszeichen zu Noten hinzufügen (Beispiel)
-@subsection Artikulationszeichen zu Noten hinzufügen (Beispiel)
-@translationof Adding articulation to notes (example)
-
-Am einfachsten können Artikulationszeichen zu Noten
-hinzugefügt werden, indem man zwei musikalische Funktionen
-in einen Kontext einfügt, wie erklärt in
-@ref{Kontexte erstellen}. Hier soll jetzt eine musikalische
-Funktion entwickelt werden, die das vornimmt.
-
-Eine @code{$variable} innerhalb von @code{#@{...#@}} ist das
-gleiche wie die normale Befehlsform @code{\variable} in
-üblicher LilyPond-Notation. Es ist bekannt dass
-
-@example
-@{ \music -. -> @}
-@end example
-
-@noindent
-in LilyPond nicht funktioniert. Das Problem könnte vermieden
-werden, indem das Artikulationszeichen an eine Pseudonote
-gehängt wird:
-
-@example
-@{ << \music s1*0-.-> @}
-@end example
-
-@noindent
-aber in diesem Beispiel soll gezeigt werden, wie man das in
-Scheme vornimmt. Zunächst wird die Eingabe und die gewünschte
-Ausgabe examiniert:
-
-@example
-% Eingabe
-\displayMusic c4
-===>
-(make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch -1 0 0))))
-=====
-% gewünschte Ausgabe
-\displayMusic c4->
-===>
-(make-music
- 'EventChord
- 'elements
- (list (make-music
- 'NoteEvent
- 'duration
- (ly:make-duration 2 0 1 1)
- 'pitch
- (ly:make-pitch -1 0 0))
- (make-music
- 'ArticulationEvent
- 'articulation-type
- "marcato")))
-@end example
-
-Dabei ist zu sehen, dass eine Note (@code{c4}) als @code{EventChord}
-repräsentiert ist, mit einem @code{NoteEvent}-Ausdruck in ihrer
-Elementenliste. Um eine Marcato-Artikulation hinzuzufügen, muss
-ein @code{ArticulationEvent}-Ausdruck zu der Elementeigenschaft
-des @code{EventChord}-Ausdrucks hinzugefügt werden.
-Um diese Funktion zu bauen, wird folgendermaßen begonnen:
-
-@example
-(define (add-marcato event-chord)
- "Add a marcato ArticulationEvent to the elements of `event-chord',
- which is supposed to be an EventChord expression."
- (let ((result-event-chord (ly:music-deep-copy event-chord)))
- (set! (ly:music-property result-event-chord 'elements)
- (cons (make-music 'ArticulationEvent
- 'articulation-type "marcato")
- (ly:music-property result-event-chord 'elements)))
- result-event-chord))
-@end example
-
-Die erste Zeile definiert eine Funktion in Scheme: Die Bezeichnung
-der Funktion ist @code{add-marcato} und sie hat eine Variable
-mit der Bezeichnung @code{event-chord}. In Scheme geht der Typ
-einer Variable oft direkt aus der Bezeichnung hervor (das ist auch
-eine gute Methode für andere Programmiersprachen).
-
-@example
-"Add a marcato..."
-@end example
-
-@noindent
-ist eine (englische) Beschreibung, was diese Funktion tut. Sie ist
-nicht unbedingt notwendig, aber genauso wie klare Variablen-Bezeichnungen
-ist auch das eine gute Methode.
-
-@example
-(let ((result-event-chord (ly:music-deep-copy event-chord)))
-@end example
-
-@code{let} wird benutzt, um die lokalen Variablen zu definieren. Hier
-wird eine lokale Variable benutzt: @code{result-event-chord}. Sie erhält
-den Wert @code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy}
-ist eine LilyPond-spezifische Funktion, die wie alle Funktionen mit dem
-Präfix @code{ly:} versehen ist. Sie wird benutzt, um eine Kopie eines
-musikalischen Ausdrucks anzufertigen. Hier wird @code{event-chord}
-(der Parameter der Funktion) kopiert. Die Funktion soll ja nur ein
-Artikulationszeichen an einen @code{EventChord} gehängt werden, deshalb ist es besser,
-den @code{EventChord}, der als Argument gegeben wurde, nicht zu
-verändern, weil er woanders benutzt werden könnte.
-
-Jetzt gibt es @code{result-event-chord}, wobei es sich um einen
-@code{NoteEventChord}-Ausdruck handelt, welcher gleichzeitig eine Kopie
-von @code{event-chord} ist. Das Makro wird seiner Eigenschaftsliste
-hinzugefügt:
-
-@example
-(set! place new-value)
-@end example
-
-Was in diesem Fall @qq{gesetzt} werden soll (@qq{place}) ist die
-@q{elements}-Eigenschaft des @code{result-event-chord}-Ausdrucks.
-
-@example
-(ly:music-property result-event-chord 'elements)
-@end example
-
-@code{ly:music-property} ist die Funktion, mit der musikalische
-Eigenschaften erreicht werden können (die @code{'elements},
-@code{'duration}, @code{'pitch} usw., die in der Ausgabe von
-@code{\displayMusic} weiter oben angezeigt werden). Der neue
-Wert ist, was ehemals die Elementeigenschaft war, mit einem
-zusätzlichen Element: dem @code{ArticulationEvent}-Ausdruck,
-der aus der Ausgabe von
-@code{\displayMusic} kopiert werden kann:
-
-@example
-(cons (make-music 'ArticulationEvent
- 'articulation-type "marcato")
- (ly:music-property result-event-chord 'elements))
-@end example
-
-@code{cons} wird benutzt, um ein Element zu einer Liste hinzuzufügen,
-ohne dass die originale Liste verändert wird. Das ist es, was die
-Funktion tun soll: die gleiche Liste, aber mit dem neuen
-@code{ArticulationEvent}-Ausdruck. Die Reihenfolge innerhalb
-der Elementeeigenschaft ist hier nicht relevant.
-
-Wenn schließlich die Marcato-Artikulation zu der entsprechenden
-@code{elements}-Eigenschaft hinzugefügt ist, kann
-@code{result-event-chord} ausgegeben werden, darum die letzte Zeile
-der Funktion.
-
-Jetzt wird die @code{add-marcato}-Funktion in eine musikalische
-Funktion umgewandelt:
-
-@example
-addMarcato = #(define-music-function (parser location event-chord)
- (ly:music?)
- "Add a marcato ArticulationEvent to the elements of `event-chord',
- which is supposed to be an EventChord expression."
- (let ((result-event-chord (ly:music-deep-copy event-chord)))
- (set! (ly:music-property result-event-chord 'elements)
- (cons (make-music 'ArticulationEvent
- 'articulation-type "marcato")
- (ly:music-property result-event-chord 'elements)))
- result-event-chord))
-@end example
-
-Eine Überprüfung, dass die Funktion richtig arbeitet, geschieht
-folgendermaßen:
-
-@example
-\displayMusic \addMarcato c4
-@end example
-
-
-@node Programmierungsschnittstelle für Textbeschriftungen
-@section Programmierungsschnittstelle für Textbeschriftungen
-@translationof Markup programmer interface
+@node Textbeschriftungsfunktionen
+@section Textbeschriftungsfunktionen
+@translationof Markup functions
Textbeschriftungselemente sind als besondere Scheme-Funktionen
-definiert, die ein Stencil-Objekt erstellen, dem eine Anzahl
+definiert, die ein @code{Stencil}-Objekt erstellen, dem eine Anzahl
an Argumenten übergeben wird.
@menu
* Beschriftungskonstruktionen in Scheme::
* Wie Beschriftungen intern funktionieren::
* Neue Definitionen von Beschriftungsbefehlen::
-* Neue Definitionen von Beschriftungsbefehlen für Listen::
+* Neue Definitionen von Beschriftungslistenbefehlen::
@end menu
@item @code{\markup Text1} @tab @code{(markup Text1)}
@item @code{\markup @{ Text1 Text2 ... @}} @tab
@code{(markup Text1 Text2 ... )}
-@item @code{\Befehl} @tab @code{#:Befehl}
+@item @code{\Beschriftungsbefehl} @tab @code{#:Beschriftungsbefehl}
@item @code{\Variable} @tab @code{Variable}
@item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
@item @code{Zeichenkette} @tab @code{"Zeichenkette"}
-@item @code{#scheme-arg} @tab @code{scheme-arg}
+@item @code{#scheme-Arg} @tab @code{scheme-Arg}
@end multitable
@end quotation
@subsection Neue Definitionen von Beschriftungsbefehlen
@translationof New markup command definition
+Dieser Abschnitt behandelt die Definition von neuen Textbeschriftungsbefehlen.
+
+@menu
+* Syntax der Definition von Textbeschriftungsbefehlen::
+* Über Eigenschaften::
+* Ein vollständiges Bespiel::
+* Eingebaute Befehle anpassen::
+@end menu
+
+@node Syntax der Definition von Textbeschriftungsbefehlen
+@unnumberedsubsubsec Syntax der Definition von Textbeschriftungsbefehlen
+@translationof Markup command definition syntax
+
Neue Textbeschriftungsbefehle können mit dem
@code{define-markup-command}-Scheme-Makro definiert werden.
@lisp
-(define-markup-command (@var{befehl-bezeichnung} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
- (@var{arg1-type?} @var{arg2-type?} ...)
+(define-markup-command (@var{befehl-bezeichnung} @var{layout} @var{props} @var{Arg1} @var{Arg2} ...)
+ (@var{Arg1-typ?} @var{Arg2-typ?} ...)
+ [ #:properties ((@var{Eigenschaft1} @var{Standard-Wert1})
+ ...) ]
..Befehlkörper..)
@end lisp
Die Argumente sind:
@table @var
-@item argi
-@var{i}te Befehlsargument
-@item argi-type?
-eine Eigenschaft für das @var{i}te Argument
-@item layout
+@item @var{befehl-bezeichnung}
+die Bezeichnung des Befehls
+
+@item @var{layout}
die @q{layout}-Definition
+
@item props
-eine Liste an alists, in der alle aktiven Eigenschaften enthalten sind
+eine Liste an assoziativen Listen, in der alle aktiven Eigenschaften enthalten sind
+
+@item @var{argi}
+das @var{i}te Befehlsargument
+
+@item @var{argi-type?}
+eine Eigenschaft für das @var{i}te Argument
@end table
-Als einfaches Beispiel soll gezeigt werden, wie man einen
-@code{\smallcaps}-Befehl hinzufügen kann, der die Kapitälchen
-für die Schriftzeichen auswählt. Normalerweise würde man Kapitälchen
-folgendermaßen auswählen:
+Wenn der Befehl Eigenschaften des @code{props}-Arguments benutzt,
+kann das @code{#:properties}-Schlüsselwort benutzt werden um zu
+bestimmen, welche Eigenschaften mit welchen Standard-Werten benutzt
+werden.
-@example
-\markup @{ \override #'(font-shape . caps) Text-in-Kapitälchen @}
-@end example
+Argumente werden nach ihrem Typ unterschieden:
-@noindent
-Damit wird die Kapitälchenschriftart ausgewählt, indem die
-@code{font-shape}-Eigenschaft auf @code{#'caps} gesetzt wird,
-während @code{Text-in-caps} interpretiert wird.
+@itemize
+@item eine Textbeschriftung entspricht einem Typenprädikat @code{markup?};
+@item eine Textbeschriftungsliste entspricht einem Typenprädikat
+@code{markup-list?};
+@item jedes andere Scheme-Objekt entspricht Typenprädikaten wie etwa
+@code{list?}, @code{number?}, @code{boolean?}, usw.
+@end itemize
-Damit diese Funktion als @code{\smallcaps}-Befehl zur Verfügung
-gestellt werden kann, muss eine Funktion mit @code{define-markup-command}
-definiert werden. Der Befehl braucht ein Argument vom Typ @code{markup}.
-Darum sollte der Beginn der Funktion lauten:
+Es gibt keine Einschränkung in der Reihenfolge der Argumente (nach
+den Standard-Argumenten @code{layout} und @code{props}). Textbeschriftungsfunktionen,
+die als letztes Argument eine Textbeschriftung haben, haben die
+Besonderheit, dass sie auf Textbeschriftungslisten angewendet werden
+können, und das Resultat ist eine Textbeschriftungsliste, in der
+die Textbeschriftungsfuktion (mit den angegebenen Argumenten am Anfang)
+auf jedes Element der originalen Textbeschriftungsliste angewendet
+wurde.
-@example
-(define-markup-command (smallcaps layout props argument) (markup?)
-@end example
+Da das Wiederholen der Argumente am Anfang bei der Anwendung einer
+Textbeschriftungsfunktion auf eine Textbeschriftungsliste for allem
+für Scheme-Argumente sparsam ist, kann man Leistungseinbußen vermeiden,
+indem man nur Scheme-Argumente für die Argumente am Anfang einsetzt,
+wenn es sich um Textbeschriftungsfunktionen handelt, die eine Textbeschriftung
+als letztes Argument haben.
-@noindent
-Was jetzt folgt, ist der eigentliche Inhalt des Befehls: das
-@code{argument} soll als Beschriftung (markup) interpretiert werden,
-also:
+@node Über Eigenschaften
+@unnumberedsubsubsec Über Eigenschaften
+@translationof On properties
-@example
-(interpret-markup layout @dots{} argument)
-@end example
+Die @code{layout}- und @code{props}-Argumente der Textbeschriftungsbefehle
+bringen einen Kontext für die Interpretation der Beschriftung:
+Schriftgröße, Zeilenlänge usw.
-@noindent
-Diese Interpretation sollte @code{'(font-shape . caps)} zu den
-aktiven Eigenschaften hinzufügen, weshalb wir das Folgende anstelle
-der @dots{} in dem Beispiel einfügen:
+Das @code{layout}-Argument greift auf Eigenschaften zu, die in der
+@code{paper}-Umgebung definiert werden, indem man die @code{ly:output-def-lookup}-Funktion
+benutzt. Beispielsweise liest man die Zeilenlänge (die gleiche, die auch in
+Partituren benutzt wird) aus mit:
@example
-(cons (list '(font-shape . caps) ) props)
+(ly:output-def-lookup layout 'line-width)
@end example
-@noindent
-Die Variable @code{props} ist eine Liste an alists, und mit @code{cons}
-wird ihr eine zusätzliche Einstellung hinzugefügt.
+Das @code{props}-Argument stellt einige Eigenschaften für die Textbeschriftungsbefehle
+zur Verfügung. Beispielsweise wenn der Überschrifttext einer
+@code{book}-Umgebung interpretiert wird, werden alle Variablen, die
+in der @code{\header}-Umgebung definiert werden, automatisch zu @code{props}
+hinzugefügt, sodass die Beschriftung auf Titel, Komponist usw. der
+@code{book}-Umgebung zugreifen kann. Das ist auch eine Möglichkeit, das
+Verhalten eines Beschriftungsbefehls zu konfigurieren: Wenn etwa ein
+Befehl die Schriftgröße während der Verarbeitung einsetzt, wird die
+Schriftgröße aus den @code{props} ausgelesen und nicht mit einem eigenen
+@code{font-size}-Argument definiert. Beim Aufruf des Beschriftungsbefehls
+kann der Wert der Schriftgröße geändert werden, womit sich auch das Verhalten
+des Befehls verändert. Benutzen Sie das @code{#:properties}-Schlüsselwort
+von @code{define-markup-command} um zu definieren, welche Eigenschaften aus den
+@code{props}-Argumenten ausgelesen werden sollen.
-Man könnte sich auch vorstellen, dass ein Rezitativ einer Oper
-gesetzt werden soll, und ein Befehl wäre sehr bequem, mit dem
-man die Namen der Charaktere auf eine eigene Art darstellen könnte.
-Namen sollen in Kapitälchen gesetzt werden und etwas nach links und
-oben verschoben werden. Man kann also einen @code{\character}-Befehl
-definieren, der die nötige Verschiebung berücksichtigt und
-den neuen @code{\smallcaps}-Befehl einsetzt:
+Das Beispiel im nächsten Abschnitt illustriert, wie man auf Eigenschaften
+in einem Beschriftungsbefehl zugreifen und sie verändern kann.
-@example
-#(define-markup-command (character layout props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
+
+@node Ein vollständiges Bespiel
+@unnumberedsubsubsec Ein vollständiges Bespiel
+@translationof A complete example
+
+Das folgende Beispiel definiert einen Beschriftungsbefehl, der einen
+doppelten Kasten um einen Text zeichnet.
+
+Zuerst wollen wir ein annäherndes Ergebnis mit Textbeschriftungen definieren.
+Nach Stöbern in @ruser{Textbeschriftungsbefehle} finden wir den Befehl
+@code{\box}:
+
+@lilypond[quote,verbatim,ragged-right]
+\markup \box \box HELLO
+@end lilypond
+
+Wir wollen aber etwas mehr Abstand (engl. padding) zwischen dem Text und dem Kasten.
+Nach der Dokumentation von @code{\box} hat der Befehl eine
+@code{box-padding}-Eigenschaft, die den Standardwert von 0.2 hat. Die
+Dokumentation zeit auch, wir man den Wert verändert:
+
+@lilypond[quote,verbatim,ragged-right]
+\markup \box \override #'(box-padding . 0.6) \box A
+@end lilypond
+
+Auch der Abstand zwischen den zwei Kästen ist uns zu klein und soll auch
+vergrößert werden:
+
+@lilypond[quote,verbatim,ragged-right]
+\markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
+@end lilypond
+
+Diese lange Textbeschriftung immer wieder schreiben zu müssen, ist
+anstrengend. Hier kömmt ein Textbeschriftungsbefehl ins Spiel. Wir
+schreiben uns alle einen @code{double-box}-Beschriftungsbefehl, der
+ein Argument annimmt (den Text). Er zeichnet zwei Kästen mit genügend Abstand:
+
+@lisp
+#(define-markup-command (double-box layout props text) (markup?)
+ "Draw a double box around text."
(interpret-markup layout props
- (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
-@end example
+ (markup #:override '(box-padding . 0.4) #:box
+ #:override '(box-padding . 0.6) #:box text)))
+@end lisp
-Hier ist eine Komplikation, die erklärt werden muss: Text über oder
-unter dem Notensystem wird vertikal verschoben um in einem bestimmten
-Abstand von dem System und den Noten zu sein (das wird als @qq{padding}
-bezeichnet). Um sicherzugehen, dass dieser Mechanismus nicht die
-vertikale Verschiebung von @code{#:translate} annulliert, wird
-die leere Zeichenkette (@code{#:hspace 0}) vor den zu verschiebenden
-Text gesetzt. Das @code{#:hspace 0} wird jetzt also über die Noten
-gesetzt und @code{name} dann relativ zu der leeren Zeichenkette
-verschoben. Im Endeffekt wird der Text nach links oben verschoben.
+@code{text} ist die Bezeichnung des Arguments dieses Befehls,
+und @code{markup?} ist seine Art: hiermit wird der Befehl als
+Beschriftungsbefehl identifiziert. Die @code{interpret-markup}-Funktion
+wird in den meisten Beschriftungsbefehlen benutzt: sie erstellt einen
+Stencil, wobei @code{layout}, @code{props} und eine Beschriftung benutzt
+werden. In unserem Fall wird diese Beschriftung durch das
+@code{markup}-Scheme-Makro erstellt, siehe auche @ref{Beschriftungskonstruktionen in Scheme}.
+Die Transformation des @code{\markup}-Ausdrucks in einen
+Scheme-Beschriftungsausdruck geschieht durch umschreiben des LilyPond-Codes
+in Scheme-Code.
-Das Resultat sieht folgendermaßen aus:
+Der neue Befehl kann wie folgt benutzt werden:
@example
-@{
- c''^\markup \character #"Cleopatra"
- e'^\markup \character #"Giulio Cesare"
-@}
+\markup \double-box A
@end example
-@lilypond[quote,ragged-right]
-#(define-markup-command (smallcaps layout props str) (string?)
- "Print the string argument in small caps. Syntax: \\smallcaps #\"string\""
+Es wäre schön, den @code{double-box}-Befehl noch konfigurierbar zu gestalten:
+in unserem Fall sind die Werte von @code{box-padding} direkt definiert und
+können nicht mehr vom Benutzer verändert werden. Es wäre auch besser, wenn
+der Abstand zwischen den beiden Kästen vom Abstand zwischen dem inneren Kasten
+und dem Text unterschieden werden könnte. Eine neue Eigenschaft muss also
+definiert werden: @code{inter-box-padding} für den Abstand zwischen den Kästen.
+@code{box-padding} wird für den inneren Abstand benutzt. Der neue Befehl wird
+so definiert:
+
+@lisp
+#(define-markup-command (double-box layout props text) (markup?)
+ #:properties ((inter-box-padding 0.4)
+ (box-padding 0.6))
+ "Draw a double box around text."
(interpret-markup layout props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-
-#(define-markup-command (character layout props name) (string?)
- "Print the character name in small caps, translated to the left and
- top. Syntax: \\character #\"name\""
+ (markup #:override `(box-padding . ,inter-box-padding) #:box
+ #:override `(box-padding . ,box-padding) #:box text)))
+@end lisp
+
+In diesem Code wird das @code{#:properties}-Schlüsselwort benutzt, sodass
+die Eigenschaften @code{inter-box-padding} und @code{box-padding} aus dem
+@code{props}-Argument ausgelesen werden, und Standardwerte werden gegeben,
+falls die Eigenschaften nicht definiert sein sollten.
+
+Dann werden diese Werte benutzt, um die @code{box-padding}-Eigenschaft
+zu verändert, die von beiden @code{\box}-Befehlen benutzt wird. Beachten
+Sie Akzent und das Komma des @code{\override}-Arguments: hiermit kann man
+einen Variablenwert in einen wörtlichen Ausdruck überführen.
+
+Jetzt kann der Befehl in Beschriftungen benutzt werden und der Abstand
+der Kästen kann angepasst werden:
+
+@lilypond[quote,verbatim,ragged-right]
+#(define-markup-command (double-box layout props text) (markup?)
+ #:properties ((inter-box-padding 0.4)
+ (box-padding 0.6))
+ "Draw a double box around text."
(interpret-markup layout props
- (markup #:hspace 0 #:translate (cons -3 1) #:smallcaps name)))
+ (markup #:override `(box-padding . ,inter-box-padding) #:box
+ #:override `(box-padding . ,box-padding) #:box text)))
-{
- c''^\markup \character #"Cleopatra" c'' c'' c''
- e'^\markup \character #"Giulio Cesare" e' e' e'
-}
+\markup \double-box A
+\markup \override #'(inter-box-padding . 0.8) \double-box A
+\markup \override #'(box-padding . 1.0) \double-box A
@end lilypond
-In diesen Befehlen wurden Kapitälchen eingesetzt, aber es kann
-vorkommen, dass die Schriftart keine Kapitälchen zur Verfügung
-stellt. In diesem Fall können die Kapitälchen nachempfunden
-werden, indem man Großbuchstaben setzt, deren Anfangsbuchstabe
-etwas größer gesetzt wird:
+@node Eingebaute Befehle anpassen
+@unnumberedsubsubsec Eingebaute Befehle anpassen
+@translationof Adapting builtin commands
-@example
-#(define-markup-command (smallcaps layout props str) (string?)
- "Print the string argument in small caps."
- (interpret-markup layout props
- (make-line-markup
- (map (lambda (s)
- (if (= (string-length s) 0)
- s
- (markup #:large (string-upcase (substring s 0 1))
- #:translate (cons -0.6 0)
- #:tiny (string-upcase (substring s 1)))))
- (string-split str #\Space)))))
-@end example
+Ein guter Weg, einen neuen Beschriftungsbefehl zu schreiben, ist es, als Vorbild
+einen existierenden zu nehmen. Die meisten Beschriftungsbefehle, die
+LilyPond mitbringt, finden sich in der Datei
+@file{scm/@/define@/-markup@/-commands@/.scm}.
-Der @code{smallcaps}-Befehl spaltet die Argumente zuerst in
-Einzelstücke auf, die von Leerzeichen getrennt sind
-(@code{(string-split str #\Space)}); für jedes Einzelstück
-wird dann eine Beschriftung aufgebaut, deren erster Buchstabe
-vergrößert wird und als Versalbuchstabe gesetzt wird
-(@code{#:large (string-upcase (substring s 0 1))}), und eine
-zweite Versalbuchstaben gesetzt werden
-(@code{#:tiny (string-upcase (substring s 1))}). Wenn
-LilyPond ein Leerzeichen zwischen Beschriftungen einer Zeile
-entdeckt, wird die zweite Beschriftung nach links verschoben
-(@code{#:translate (cons -0.6 0) ...}). Dann werden die
-Beschriftungen für jedes Einzelstück in eine Zeile gesetzt
-@code{(make-line-markup ...)}. Schließlich wird die resultierende
-Beschriftung an die @code{interpret-markup}-Funktion zusammen
-mit den Argumenten @code{layout} und @code{props} weitergereicht.
-
-Achtung: ist gibt keinen internen Befehl @code{\smallCaps}, der
-benutzt werden kann, um Text in Kapitälchen zu setzen. Siehe auch
-@ref{Text markup commands}.
+Man könnte beispielsweise den Befehl @code{\draw-line}, der eine Linie
+zeichnet, anpassen, sodass er eine Doppellinie zeichnet. Der
+Befehl @code{\draw-line} ist wie folgend definiert (Dokumentation entfernt):
-@knownissues
+@lisp
+(define-markup-command (draw-line layout props dest)
+ (number-pair?)
+ #:category graphic
+ #:properties ((thickness 1))
+ "..documentation.."
+ (let ((th (* (ly:output-def-lookup layout 'line-thickness)
+ thickness))
+ (x (car dest))
+ (y (cdr dest)))
+ (make-line-stencil th 0 0 x y)))
+@end lisp
-Im Moment sind die möglichen Kombinationen von Argumenten (nach den
-Standardargumenten @var{layout} und @var{props}), die mit
-@code{define-markup-command} definiert werden, wie folgt
-limitiert:
-
-@table @asis
-@item (kein Argument)
-@itemx @var{list}
-@itemx @var{markup}
-@itemx @var{markup markup}
-@itemx @var{scm}
-@itemx @var{scm markup}
-@itemx @var{scm scm}
-@itemx @var{scm scm markup}
-@itemx @var{scm scm markup markup}
-@itemx @var{scm markup markup}
-@itemx @var{scm scm scm}
-@end table
+Um einen neuen Befehl, der auf einem existierenden basiert, zu definieren,
+wird die Befehlsdefinition kopiert und die Bezeichnung des Befehls
+geändert. Das @code{#:category}-Schlagwort kann entfernt werden,
+weil es nur zur Erstellung der LilyPond-Dokumentation eingesetzt wird
+und keine Bedeutung für selbstdefinierte Befehle hat.
-@noindent
-Hier stellt @var{scm} native Scheme-Datentypen dar wie
-@q{number} oder @q{string}.
+@lisp
+(define-markup-command (draw-double-line layout props dest)
+ (number-pair?)
+ #:properties ((thickness 1))
+ "..documentation.."
+ (let ((th (* (ly:output-def-lookup layout 'line-thickness)
+ thickness))
+ (x (car dest))
+ (y (cdr dest)))
+ (make-line-stencil th 0 0 x y)))
+@end lisp
-Es ist beispielsweise nicht möglich, einen Beschriftungsbefehl
-@code{foo} mit vier Argumenten in folgender Weise zu nutzen:
+Dann braucht man eine Eigenschaft, um den Abstand zwischen den zwei
+Linien zu definieren, als @code{line-gap} bezeichnet und etwa mit
+dem Standardwert 0.6:
-@example
-#(define-markup-command (foo layout props
- num1 str1 num2 str2)
- (number? string? number? string?)
- ...)
-@end example
+@lisp
+(define-markup-command (draw-double-line layout props dest)
+ (number-pair?)
+ #:properties ((thickness 1)
+ (line-gap 0.6))
+ "..documentation.."
+ ...
+@end lisp
-@noindent
-Wenn es folgendermaßen eingesetzt wird:
+Schließlich wird der Code, der die zwei Linien zeichnet, hinzugefügt.
+Zwei Aufrufe an @code{make-line-stencil} werden benutzt, um beide Linien
+zu zeichnen, und die beiden sich daraus ergebenden Stencils werden mit
+@code{ly:stencil-add} kombiniert:
-@example
-\markup \foo #1 #"bar" #2 #"baz"
-@end example
+@lilypond[quote,verbatim,ragged-right]
+#(define-markup-command (my-draw-line layout props dest)
+ (number-pair?)
+ #:properties ((thickness 1)
+ (line-gap 0.6))
+ "..documentation.."
+ (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
+ thickness))
+ (dx (car dest))
+ (dy (cdr dest))
+ (w (/ line-gap 2.0))
+ (x (cond ((= dx 0) w)
+ ((= dy 0) 0)
+ (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
+ (y (* (if (< (* dx dy) 0) 1 -1)
+ (cond ((= dy 0) w)
+ ((= dx 0) 0)
+ (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
+ (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
+ (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
+
+\markup \my-draw-line #'(4 . 3)
+\markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
+@end lilypond
-@cindex Scheme signature
-@cindex Signatur, Scheme
-@noindent
-beschwert sich @command{lilypond}, dass @code{foo} wegen einer unbekannten
-Scheme Signatur nicht analysiert werden kann.
-@node Neue Definitionen von Beschriftungsbefehlen für Listen
-@subsection Neue Definitionen von Beschriftungsbefehlen für Listen
+@node Neue Definitionen von Beschriftungslistenbefehlen
+@subsection Neue Definitionen von Beschriftungslistenbefehlen
@translationof New markup list command definition
Beschriftungslistenbefehle können mit dem Scheme-Makro
args)))))
@end example
-Neben den üblichen @code{layout} und @code{props}-Argumenten, nimmt der
+Neben den üblichen @code{layout} und @code{props}-Argumenten nimmt der
@code{paragraph}-Beschriftungslistenbefehl als Argument eine Beschriftungsliste,
die @code{args} genannt wird. Das Prädikat für Beschriftungslisten ist
@code{markup-list?}.
@funindex \applyOutput
Der vielfältigste Weg, ein Objekt zu beeinflussen, ist
-@code{\applyOutput}. Die Syntax lautet:
+@code{\applyOutput}. Das funktioniert, indem ein musikalisches
+Ereignis in den angegebenen Kontext eingefügt wird
+(@rinternals{ApplyOutputEvent}). Die Syntax lautet:
@example
\applyOutput @var{Kontext} @var{proc}
wobei @var{proc} eine Scheme-Funktion ist, die drei Argumente
benötigt.
-Während der Interpretation wird die Funktion @var{proc} für
-jedes Layoutobjekt aufgerufen, dass im Kontext @var{Kontext}
+Während der Interpretation wird die Funktion @code{@var{proc}} für
+jedes Layoutobjekt aufgerufen, dass im Kontext @code{@var{Kontext}}
vorgefunden wird, und zwar mit folgenden Argumenten:
@itemize
der musikalische Ausdruck oder das Objekt, das für seine Erstellung
verantwortlich war, in der Objekteigenschaft @code{cause}.
Für einen Notenkopf beispielsweise ist das ein
-@rinternals{NoteHead}-Ereignis, und für einen Notenhals
-(ein @rinternals{Stem}-Objekt) ist es ein @rinternals{NoteHead}-Objekt.
+@rinternals{NoteHead}-Ereignis, und für einen Notenhals ist es
+ein @rinternals{Stem}-Objekt.
Hier ist eine Funktion, die mit @code{\applyOutput} benutzt
-werden kann; sie macht Notenköpfe auf der Mittellinie unsichtbar:
+werden kann; sie macht Notenköpfe auf und neben der Mittellinie unsichtbar:
@lilypond[quote,verbatim,ragged-right]
#(define (blanker grob grob-origin context)
(if (and (memq 'note-head-interface (ly:grob-interfaces grob))
- (eq? (ly:grob-property grob 'staff-position) 0))
+ (< (abs (ly:grob-property grob 'staff-position)) 2))
(set! (ly:grob-property grob 'transparent) #t)))
-\relative {
- e4 g8 \applyOutput #'Voice #blanker b d2
+\relative c' {
+ a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
}
@end lilypond
-@node Scheme-Vorgänge als Eigenschaften
-@section Scheme-Vorgänge als Eigenschaften
-@translationof Scheme procedures as properties
+@node Callback-Funktionen
+@section Callback-Funktionen
+@translationof Callback functions
-Eigenschaften (wie Dicke, Richtung usw.) können mit
-@code{\override} auf feste Werte gesetzt werden, etwa:
+Eigenschaften (wie Dicke (@code{thickness}), Richtung (@code{direction})
+usw.) können mit @code{\override} auf feste Werte gesetzt werden, etwa:
@example
\override Stem #'thickness = #2.0
Resultat der Funktion ausgegeben wird und nicht das
@code{simple-closure}-Objekt.
+Aus dem Callback heraus kann man eine Beschriftung am einfachsten mit
+@code{grob-interpret-markup} auswerten. Beispielsweise:
+
+@example
+mein-callback = #(lambda (grob)
+ (grob-interpret-markup grob (markup "foo")))
+@end example
+
+
+
+
+
-@node Scheme-Code anstelle von \tweak verwenden
-@section Scheme-Code anstelle von @code{ weak} verwenden
-@translationof Using Scheme code instead of \tweak
+@node Scheme-Code innerhalb LilyPonds
+@section Scheme-Code innerhalb LilyPonds
+@translationof Inline Scheme code
Der hauptsächliche Nachteil von @code{\tweak} ist seine
syntaktische Inflexibilität. Folgender Code beispielsweise
@end itemize
Diese Funktion muss in @rinternals{Tie} (Bindebogen) installiert
-werden, und der letzte Teil eines gebrochenen Bindebogens wird
-nach oben verschoben.
+werden, damit der letzte Teil eines gebrochenen Bindebogens
+neu ausgerichtet wird.
@lilypond[quote,verbatim,ragged-right]
#(define (my-callback grob)
auch das alte @code{after-line-breaking}-Callback aufrufen,
wenn es vorhanden ist. Wenn diese Funktion etwa mit
@code{Hairpin} (Crescendo-Klammer) eingesetzt wird, sollte auch
-@code{ly:hairpin::after-line-breaking} aufgerufen werden.
+@code{ly:spanner::kill-zero-spanned-time} aufgerufen werden.
@item
innerhalb der @code{\context}-Umgebung funktioniert.
@end itemize
+
+
+
+@node LilyPond Scheme-Schnittstellen
+@chapter LilyPond Scheme-Schnittstellen
+@translationof LilyPond Scheme interfaces
+
+Dieses Kapitel behandelt die verschiedenen Werkzeuge, die LilyPond als
+Hilfe für Scheme-Programmierer zur Verfügung stellt, um Information in
+den Musik-Stream zu senden und aus ihm herauszubekommen.
+
+TODO: was gehört hier eigentlich hin?
@c -*- coding: utf-8; mode: texinfo; documentlanguage: de -*-
@ignore
- Translation of GIT committish: 3d7aec6a2b5f3910f8d5a43e58cb5c741d3fcc77
+ Translation of GIT committish: 144cd434d02e6d90b2fb738eeee99119a7c5e1d2
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
@c \version "2.12.0"
@node Scheme-Übung
-@appendix Scheme-Übung
+@chapter Scheme-Übung
@translationof Scheme tutorial
@funindex #
@cindex GUILE
@cindex Scheme, in einer LilyPond-Datei
@cindex LISP
+@cindex Auswertung von Scheme-Code
LilyPond verwendet die Scheme-Programmiersprache sowohl als Teil
der Eingabesyntax als auch als internen Mechanismus, um Programmmodule
@qq{R5RS}-Standard von Scheme befindet sich unter der Adresse
@uref{http://www.schemers.org/Documents/Standards/R5RS/}.
+
+@menu
+* Einleitung in Scheme::
+* Scheme in LilyPond::
+* Komplizierte Funktionen erstellen::
+@end menu
+
+@node Einleitung in Scheme
+@section Einleitung in Scheme
+@translationof Introduction to Scheme
+
+Wir wollen mit einer Einführung in Scheme beginnen. Für diese kurze Einfürung
+soll der GUILE-Interpreter genommen werden, um zu erforschen, wie die Sprache
+funktioniert. Nach besserer Bekanntschaft mit Scheme soll gezeigt werden, wie
+die Sprache in LilyPond-Dateien eingefügt werden kann.
+
+@menu
+* Scheme-Sandkasten::
+* Scheme-Variablen::
+* Einfache Scheme-Datentypen::
+* Zusammengesetzte Scheme-Datentypen::
+* Berechnungen in Scheme::
+* Scheme-Prozeduren::
+* Scheme-Konditionale::
+@end menu
+
+@node Scheme-Sandkasten
+@subsection Scheme-Sandkasten
+@translationof Scheme sandbox
+
Die LilyPond-Installation enthält gleichzeitig auch die
Guile-Implementation von Scheme. Auf den meisten Systemen kann
man in einer Scheme-sandbox experimentieren, indem man ein
einigen Systemen, insbesondere unter Windows, muss man evtl.
die Umgebungsvariable @code{GUILE_LOAD_PATH} auf das Verzeichnis
@code{../usr/shr/guile/1.8} innerhalb des LilyPond-Installationsverzeichnisses
-setzen (der vollständige Pfad ist erklärt in @ref{Other sources of information}).
+setzen (der vollständige Pfad ist erklärt in @rlearning{Mehr Information}).
Alternativ können Windows-Benutzer auch einfach @qq{Ausführen} im
Startmenü wählen und @code{guile} schreiben.
+Wenn guile einmal läuft, erhält man die Eingabeaufforderung von guile:
+
+@lisp
+guile>
+@end lisp
+
+Man kann Scheme-Ausdrucke hier eingeben und mit Scheme experimentieren.
+
+
+@node Scheme-Variablen
+@subsection Scheme-Variablen
+@translationof Scheme variables
+
+Scheme-Variablen können jedlichen gültigen Scheme-Wert erhalten, auch
+Scheme-Prozeduren.
+
+Scheme-Variablen werden mit @code{define} definiert:
+
+@lisp
+guile> (define a 2)
+guile>
+@end lisp
+
+Scheme-Variablen können an der Guile-Eingabeaufforderung ausgewertet werden,
+indem man einfach die Variable eintippt.
+
+@lisp
+guile> a
+2
+guile>
+@end lisp
+
+Scheme-Variablen können auf dem Bildschirm ausgegeben werden, indem man
+@code{display} zum Anzeigen benutzt:
+
+@lisp
+guile> (display a)
+2guile>
+@end lisp
+
+Sowohl der Wert @code{2} als auch die Eingabeaufforderung @code{guile}
+werden auf der gleichen Zeile ausgegeben. Das kann man vermeiden, indem
+man eine @code{newline}-Prozedur für eine Leerzeile aufruft oder das
+Zeichen für eine neue Zeile anzeigen lässt:
+
+@lisp
+guile> (display a)(newline)
+2
+guile> (display a)(display "\n")
+2
+guile>
+@end lisp
+
+Wenn eine Variable einmal erstellt wurde, kann ihr Wert durch @code{set!}
+verändert werden:
+
+@lisp
+guile> (set! a 12345)
+guile> a
+12345
+guile>
+@end lisp
+
+@node Einfache Scheme-Datentypen
+@subsection Einfache Scheme-Datentypen
+@translationof Scheme simple data types
+
Das Grundlegendste an einer Sprache sind Daten: Zahlen, Zeichen,
Zeichenketten, Listen usw. Hier ist eine Liste der Datentypen, die für
LilyPond-Eingabedateien relevant sind.
@item Zahlen
Zahlen werden wie üblich eingegeben, @code{1} ist die (ganze)
-Zahl Eins, während @code{-1.5} ist eine Gleitkommazahl (also
-eine nicht-ganze).
+Zahl Eins, während @code{-1.5} eine Gleitkommazahl (also
+eine nicht-ganze) ist.
@item Zeichenketten
Zeichenketten werden in doppelte Anführungszeichen gesetzt:
eine Zeichenkette"
@end example
+@noindent
+und die Zeichen für eine neue Zeile am Ende jeder Zeile werden auch
+in die Zeichenkette aufgenommen.
+
+Zeichen für eine neue Zeile können auch hinzugefügt werden, indem man
+@code{\n} in die Zeichenkette aufnimmt.
+
+@example
+"das\nist eine\nmehrzeilige Zeichenkette"
+@end example
+
Anführungszeichen und neue Zeilen können auch mit sogenannten
Fluchtsequenzen eingefügt werden. Die Zeichenkette
@code{a sagt "b"} wird wie folgt eingegeben:
"a sagt \"b\""
@end example
-Neue Zeilen und Backslashe werden mit @code{\n} bzw. @code{\\}
-eingegeben.
@end table
-In einer Notationsdatei werden kleine Scheme-Abschnitte mit der
-Raute (@code{#}) eingeleitet. Die vorigen Beispiele heißen also in
-LilyPond:
+Weitere zusätzliche Scheme-Datentypen, die hier nicht besprochen wurden,
+finden sich in einer vollständigen Liste der Scheme-Datentypen in der
+Guile-Referenzanleitung:
+@uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
+
+
+@node Zusammengesetzte Scheme-Datentypen
+@subsection Zusammengesetzte Scheme-Datentypen
+@translationof Scheme compound data types
+
+Es gibt auch zusammengesetzte Datentypen in Scheme. Die Datentypen, die in
+LilyPond häufig benutzt werden, beinhalten Paare, Listen, assoziative Listen
+und Hash-Tabellen.
+
+@subheading Paare (pair)
+
+Der wichtigeste zusammengesetzte Datentyp in Scheme ist ein Paar (@code{pair}).
+Wie aus dem Namen schon hervorgeht, besteht ein Paar aus zwei zusammengeschweißten
+Werten. Die Prozedur um ein Paar zu erstellen ist @code{cons}.
+
+@lisp
+guile> (cons 4 5)
+(4 . 5)
+guile>
+@end lisp
+
+Das Paar wird dargestellt als zwei Elemente, von Klammern umgeben
+und durch Leerzeichen und einen Punkt (@code{.}) getrennt. Der Punkt ist
+@emph{kein} Dezimalpunkt, sondern markiert die Gruppe als Paar.
+
+Paare können auch wörtlich eingegeben werden, indem man ihnen voraus ein
+einfaches Anführungszeichen (@code{'} setzt.
+
+@lisp
+guile> '(4 . 5)
+(4 . 5)
+guile>
+@end lisp
+
+Beide Elemente eines Paares können beliebige gültige Scheme-Werte sein:
+
+@lisp
+guile> (cons #t #f)
+(#t . #f)
+guile> '("blah-blah" . 3.1415926535)
+("blah-blah" . 3.1415926535)
+guile>
+@end lisp
+
+Das erste Element eines Paares kann mit der Prozedur @code{car},
+das zweite mit der Prozedur @code{cdr} angesprochen werden.
+
+@lisp
+guile> (define mypair (cons 123 "hello there")
+... )
+guile> (car mypair)
+123
+guile> (cdr mypair)
+"hello there"
+guile>
+@end lisp
+
+@noindent
+
+Achtung: @code{cdr} wird ausgeprochen wie "kudd-err", nach Sussman und
+Abelson, siehe
+@uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
+
+@subheading Listen (list)
+
+Ein sehr häufiger Datentyp in Scheme ist die Liste (@emph{list}). Formal
+gesehen wird eine Liste entweder als leere Liste definiert
+(repräsentiert als @code{'()}), oder als ein Paar, dessen @code{cdr}
+eine Liste ist.
+
+Es gibt viele Arten, Listen zu erstellen. Die vielleicht häufigste Methode
+ist die @code{list}-Prozedur:
+
+@lisp
+guile> (list 1 2 3 "abc" 17.5)
+(1 2 3 "abc" 17.5)
+@end lisp
+
+Wie man sehen kann, wird eine Liste dargestellt in Form der einzelnen
+Elemente, getrennt durch ein Leerzeichen und als Gruppe in Klammern eingeschlossen.
+Anders als bei einem Paar, befindet sich kein Punkt zwischen den Elementen.
+
+Eine Liste kann auch als wörtliche Liste notiert werden, indem man die
+enthaltenen Elemente in Klammern einschließt und ein einfaches Anführungszeichen
+voranschreibt:
+
+@lisp
+guile> '(17 23 "foo" "bar" "bazzle")
+(17 23 "foo" "bar" "bazzle")
+@end lisp
+
+Listen haben eine zentrale Stellung in Scheme. Scheme wird als Dialekt
+von Lisp angesehen, und das Wort @qq{lisp} steht für @qq{List Processing}.
+Scheme-Ausdrücke sind immer Listen.
+
+@subheading Assoziative Listen (alist)
+
+Eine besonderer Listentyp ist die @emph{assoziative Liste} oder @emph{alist}.
+Eine Alist wird benutzt, um Daten zum einfachen Abrufen zu speichern.
+
+Alisten sind Listen, deren Elemente als Paare kommen. Der @code{car}-Teil
+jedes Elements wird als @emph{Schlüssel} (key) bezeichnet, der
+@code{cdr}-Teil jedes Elements wird @emph{Wert} (value) genannt.
+Die Scheme-Prozedur @code{assoc} wird benutzt, um einen Eintrag aus einer
+Aliste aufzurufen, und mit @code{cdr} wird sein Wert abgefragt:
+
+@lisp
+guile> (define my-alist '((1 . "A") (2 . "B") (3 . "C")))
+guile> my-alist
+((1 . "A") (2 . "B") (3 . "C"))
+guile> (assoc 2 my-alist)
+(2 . "B")
+guile> (cdr (assoc 2 my-alist))
+"B"
+guile>
+@end lisp
+
+Alisten werden sehr viel in LilyPond genutzt, um Eigenschaften und
+andere Daten zu speichern.
+
+@subheading Hash-Tabellen (hash table)
+
+Eine Datenstruktur, die ab und zu in LilyPond eingesetzt wird.
+Eine Hash-Tabelle ähnelt einem Array, aber die Indexe des Arrays
+können beliebige Scheme-Werte sein, nicht nur Integre.
+
+Hash-Tabellen sind effizienter als Alisten, wenn man viele Daten
+speichern will und die Daten sich oft ändern.
+
+Die Syntax, mit der Hash-Tabellen erstellt werden, ist etwas komplex,
+aber man kann Beispiele hierzu im LilyPond-Quellcode finden.
+
+@lisp
+guile> (define h (make-hash-table 10))
+guile> h
+#<hash-table 0/31>
+guile> (hashq-set! h 'key1 "val1")
+"val1"
+guile> (hashq-set! h 'key2 "val2")
+"val2"
+guile> (hashq-set! h 3 "val3")
+"val3"
+@end lisp
+
+Werte werden aus den Hash-Tabellen mit @code{hashq-ref} ausgelesen.
+
+@lisp
+guile> (hashq-ref h 3)
+"val3"
+guile> (hashq-ref h 'key2)
+"val2"
+guile>
+@end lisp
+
+Schlüssel und Werte werden als Paar mit @code{hashq-get-handle} ausgelesen.
+Das ist die beste Art, weil hier @code{#f} ausgegeben wird, wenn ein
+Schlüssel nicht gefunden werden kann.
+
+@lisp
+guile> (hashq-get-handle h 'key1)
+(key1 . "val1")
+guile> (hashq-get-handle h 'frob)
+#f
+guile>
+@end lisp
+
+
+@node Berechnungen in Scheme
+@subsection Berechnungen in Scheme
+@translationof Calculations in Scheme
+
+@ignore
+We have been using lists all along. A calculation, like @code{(+ 1 2)}
+is also a list (containing the symbol @code{+} and the numbers 1
+and@tie{}2). Normally lists are interpreted as calculations, and the
+Scheme interpreter substitutes the outcome of the calculation. To enter a
+list, we stop the evaluation. This is done by quoting the list with a
+quote @code{'} symbol. So, for calculations do not use a quote.
+
+Inside a quoted list or pair, there is no need to quote anymore. The
+following is a pair of symbols, a list of symbols and a list of lists
+respectively,
@example
-##t ##f
-#1 #-1.5
-#"Das ist eine Zeichenkette"
-#"Das
-ist
-eine Zeichenkette"
+#'(stem . head)
+#'(staff clef key-signature)
+#'((1) (2))
+@end example
+@end ignore
+
+Scheme kann verwendet werden, um Berechnungen durchzuführen. Es
+verwendet eine @emph{Präfix}-Syntax. Um 1 und@tie{}2 zu addieren, muss
+man @code{(+ 1 2)} schreiben, und nicht @math{1+2}, wie in traditioneller
+Mathematik.
+
+@lisp
+guile> (+ 1 2)
+3
+@end lisp
+
+Berechnungen können geschachtelt werden und das Ergebnis einer Berechnung
+kann für eine neue Berechnung eingesetzt werden.
+
+@lisp
+guile> (+ 1 (* 3 4))
+13
+@end lisp
+
+Diese Berechnungen sind Beispiele von Auswertungen. Ein Ausdruck
+wie @code{(* 3 4)} wird durch seinen Wert @code{12} ersetzt.
+
+Scheme-Berechnungen können zwischen Integren und Nich-Integren
+unterscheiden. Integre Berechnungen sind exakt, während Nicht-Integre
+nach den passenden Genauigkeitseinschränkungen berechnet werden:
+
+@lisp
+guile> (/ 7 3)
+7/3
+guile> (/ 7.0 3.0)
+2.33333333333333
+@end lisp
+
+Wenn der Scheme-Berechner einen Ausdruck antrifft, der eine Liste darstellt,
+wird das erste Element der Liste als Prozedur behandelt, die mit
+Argumenten des Restes der Liste ausgewertet werden. Darum sind alle
+Operatoren in Scheme vorangestellt.
+
+Wenn das erste Element eines Scheme-Ausdrucks, der eine Liste darstellt,
+@emph{kein} Operator oder keine Prozedur ist, gibt es einen Fehler:
+
+@lisp
+guile> (1 2 3)
+
+Backtrace:
+In current input:
+ 52: 0* [1 2 3]
+
+<unnamed port>:52:1: In expression (1 2 3):
+<unnamed port>:52:1: Wrong type to apply: 1
+ABORT: (misc-error)
+guile>
+@end lisp
+
+Hier kann man sehen, dass Scheme versucht hat, 1 als einen Operator oder
+eine Prozedur zu behandeln, was aber nicht möglich war. Darum der Fehler
+"Wrong type to apply: 1".
+
+Wenn man also eine Liste erstellen will, braucht man also einen Listen-Operator
+oder man muss die Liste als wörtliches Zitat schreiben, sodass Scheme sie
+nicht auszuwerten versucht.
+
+@lisp
+guile> (list 1 2 3)
+(1 2 3)
+guile> '(1 2 3)
+(1 2 3)
+guile>
+@end lisp
+
+Dieser Fehler kann durchaus vorkommen, wenn man Scheme unter LilyPond
+einsetzt.
+
+@ignore
+The same assignment can be done in completely in Scheme as well,
+
+@example
+#(define twentyFour (* 2 twelve))
+@end example
+
+@c this next section is confusing -- need to rewrite
+
+The @emph{name} of a variable is also an expression, similar to a
+number or a string. It is entered as
+
+@example
+#'twentyFour
+@end example
+
+@funindex #'symbol
+@cindex quoting in Scheme
+
+The quote mark @code{'} prevents the Scheme interpreter from substituting
+@code{24} for the @code{twentyFour}. Instead, we get the name
+@code{twentyFour}.
+@end ignore
+
+
+@node Scheme-Prozeduren
+@subsection Scheme-Prozeduren
+@translationof Scheme procedures
+
+Scheme-Prozeduren sind ausführbare Scheme-Ausdrücke, die einen
+Wert ausgeben, der das Resultat ihrer Ausführung darstellt. Sie können
+auch Variablen verändern, die außerhalb dieser Prozedur definiert wurden.
+
+@subheading Prozeduren definieren
+
+Prozeduren werden in Scheme mit @code{define} definiert:
+
+@example
+(define (function-name arg1 arg2 ... argn)
+ scheme-expression-that-gives-a-return-value)
+@end example
+
+Beispielsweise könnte man eine Prozedur definieren, die den Durchschnitt
+berechnet:
+
+@lisp
+guile> (define (average x y) (/ (+ x y) 2))
+guile> average
+#<procedure average (x y)>
+@end lisp
+
+Wenn die Prozedur einmal definiert ist, wird sie aufgerufen indem man
+die Prozedur und die Argumente in eine Liste schreibt. Man könnte also den
+Durchschnitt von 3 und 12 berechnen:
+
+@lisp
+guile> (average 3 12)
+15/2
+@end lisp
+
+@subheading Prädikate
+
+Scheme-Prozeduren, die Boolsche Werte ausgeben, werden oft als Prädikate
+(predicate) bezeichnet. Es herrscht die Übereinkunft, Prädikat-Bezeichnungen
+mit einem Fragezeichen abzuschließen:
+
+@lisp
+guile> (define (less-than-ten? x) (< x 10))
+guile> (less-than-ten? 9)
+#t
+guile> (less-than-ten? 15)
+#f
+@end lisp
+
+@subheading Wiedergabe-Werte
+
+Scheme-Prozeduren geben immer einen Wiedergabe-Wert (return value) aus, welcher
+der Wert des letzten Ausdrucks ist, der in der Prozedur ausgeführt wurde. Der
+Wiedergabewert kann ein beliebiger gültiger Scheme-Wert sein, auch eine
+komplexe Datenstruktur oder eine Prozedur.
+
+Manchmal würden Benutzer gerne mehrere Scheme-Ausdrucke in einer Prozedur haben.
+Es gibt zwei Arten, wie merhere Ausdrücke kombiniert werden können. Die erste
+Art ist die @code{begin}-Prozedur, der es ermöglicht, dass mehrere Ausdrücke
+ausgewertet werden und den Wert des letzten Ausdrucks wiedergibt.
+
+@lisp
+guile> (begin (+ 1 2) (- 5 8) (* 2 2))
+4
+@end lisp
+
+Die andere Art, mehrere Ausdrücke zu kombinieren, ist eine @code{let}-Umgebung.
+In dieser Umgebung wird eine Serie von Verbindungen erstellt, und dann wird eine
+Sequenz von Ausdrücken ausgewertet, die diese Bindungen einschließen können.
+Der Wiedergabewert der let-Umgebung ist der Wiedergabewert der letzten Aussage
+in der let-Umgebung:
+
+@lisp
+guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
+... (+ (* x y) (/ z x)))
+508
+@end lisp
+
+
+@node Scheme-Konditionale
+@subsection Scheme-Konditionale
+@translationof Scheme conditionals
+
+@subheading if
+
+Scheme hat eine @code{if}-Prozedur:
+
+@example
+(if test-expression true-expression false-expression)
+@end example
+
+@var{test-expression} ist ein Ausdruck, der einen Booleschen
+Wert zurück gibt. Wenn @var{test-expression} den Wert @code{#t}
+ausgibt, gibt die if-Prozedur den Wert von @var{true-expression} aus,
+in allen anderen Fällen den Wert von @var{false-expression}.
+
+@lisp
+guile> (define a 3)
+guile> (define b 5)
+guile> (if (> a b) "a is greater than b" "a is not greater than b")
+"a is not greater than b"
+@end lisp
+
+@subheading cond
+
+Eine andere konditionale Prozedur in Scheme ist
+@code{cond}:
+
+@example
+(cond (test-expression-1 result-expression-sequence-1)
+ (test-expression-2 result-expression-sequence-2)
+ ...
+ (test-expression-n result-expression-sequence-n))
+@end example
+
+Beispielsweise:
+
+@lisp
+guile> (define a 6)
+guile> (define b 8)
+guile> (cond ((< a b) "a is less than b")
+... ((= a b) "a equals b")
+... ((> a b) "a is greater than b"))
+"a is less than b"
+@end lisp
+
+
+
+@node Scheme in LilyPond
+@section Scheme in LilyPond
+@translationof Scheme in LilyPond
+
+@menu
+* LilyPond Scheme-Syntax::
+* LilyPond-Variablen::
+* Eingabe-Variablen und Scheme::
+* Objekteigenschaften::
+* Zusammengesetzte LilyPond-Variablen::
+* Interne musikalische Repräsentation::
+@end menu
+
+@node LilyPond Scheme-Syntax
+@subsection LilyPond Scheme-Syntax
+@translationof LilyPond Scheme syntax
+
+Der Guile-Auswerter ist ein Teil von LilyPond, sodass Scheme also auch in
+normale LilyPond-Eingabedateien eingefügt werden kann. Das Rautenzeichen
+(@code{#}) wird benutzt, um dem LilyPond-Parser mitzuteilen, dass der nächste
+Wert ein Scheme-Wert ist.
+
+Wenn der Parser eine Raute sieht, wird der Eingabe-Code an den Guile-Auswerter
+weitergereicht, der den Scheme-Ausdruck auswertet. Der Auswerter behandelt
+die Eingabe so lange, bis er zum Ende eines Scheme-Ausdrucks kommt.
+
+Scheme-Prozeduren können in LilyPond-Eingabedateien definiert werden:
+
+@example
+#(define (average a b c) (/ (+ a b c) 3))
@end example
LilyPond-Kommentare (@code{%} oder @code{%@{ %@}}) können innerhalb
selten benutzt und nie im Quellcode
von LilyPond
!#
-+@end example
+@end example
+
+Für den Rest dieses Abschnitts soll angenommen werden, dass die Daten in
+einer LilyPond-Eingabedatei notiert werden sollen, sodass immer @code{#}
+vor die Scheme-Ausdrücke gestellt wird.
-Mehrere aufeinander folgende Scheme-Ausdrücke in einer Notationsdatei
-können kombiniert werden, wenn man @code{begin} einsetzt. Das
-erlaubt es, die Anzahl an Rauten auf eins zu begrenzen.
+Alle Scheme-Ausdrücke auf oberster Ebene in einer LilyPond-Eingabedatei
+können in einen einzigen Scheme-Ausdruck zusammengefasst werden mit
+@code{begin}:
@example
#(begin
(define bar 1))
@end example
-Wenn @code{#} von einer öffnenden Klammer, @code{(}, gefolgt wird, wie
-in dem Beispiel oben, bleibt der Parser im Scheme-Modus bis eine
-passende schließende Klammer, @code{)}, gefunden wird, sodass keine
-weiteren @code{#}-Zeichen benötigt werden, um einen Scheme-Abschnitt
-anzuzeigen.
-Für den Rest dieses Abschnitts nehmen wir an, dass die Daten immer in
-einer LilyPond-Datei stehen, darum wird immer die Raute verwendet.
+@node LilyPond-Variablen
+@subsection LilyPond-Variablen
+@translationof LilyPond variables
-Scheme kann verwendet werden, um Berechnungen durchzuführen. Es
-verwendet eine @emph{Präfix}-Syntax. Um 1 und@tie{}2 zu addieren, muss
-man @code{(+ 1 2)} schreiben, und nicht @math{1+2}, wie in traditioneller
-Mathematik.
+LilyPond-Variablen werden intern als Scheme-Variablen gespeichert. Darum
+ist
-@lisp
-#(+ 1 2)
- @result{} #3
-@end lisp
+@example
+Zwoelf = 12
+@end example
-Der Pfeil @result{} zeigt an, dass das Ergebnis der Auswertung von
-@code{(+ 1 2)} @code{3}@tie{}ist. Berechnungen können geschachtelt
-werden und das Ergebnis einer Berechnung kann für eine neue
-Berechnung eingesetzt werden.
+@noindent
+das Gleiche wie
-@lisp
-#(+ 1 (* 3 4))
- @result{} #(+ 1 12)
- @result{} #13
-@end lisp
+@example
+#(define Zwoelf 12)
+@end example
-Diese Berechnungen sind Beispiele von Auswertungen. Ein Ausdruck
-wie @code{(* 3 4)} wird durch seinen Wert @code{12} ersetzt. Ähnlich
-verhält es sich mit Variablen. Nachdem eine Variable definiert ist:
+Das bedeutet, dass Scheme-Ausdrücke auf LilyPond-Variablen zugreifen können.
+Man könnte also schreiben:
@example
-zwoelf = #12
+Vierundzwanzig = #(* 2 Zwoelf)
@end example
@noindent
-kann man sie in Ausdrücken weiterverwenden:
+was zur Folge hätte, dass die Zahl 24 in der LilyPond (und Scheme-)Variablen
+@code{Vierundzwanzig} gespeichert wird.
+
+
+@node Eingabe-Variablen und Scheme
+@subsection Eingabe-Variablen und Scheme
+@translationof Input variables and Scheme
+
+Das Eingabeformat unterstützt die Notation von Variablen: Im folgenden
+Beispiel wird ein musikalischer Ausdruck einer Variablen mit der
+Bezeichnung @code{traLaLa} zugewiesen:
@example
-vierundzwanzig = #(* 2 zwoelf)
+traLaLa = @{ c'4 d'4 @}
+@end example
+
+Variablen haben beschränkte Geltungsbereiche: im unten stehenden Beispiel
+enthält auch die @code{\layout}-Umgebung eine @code{traLaLa}-Variable,
+die sich aber von der @code{traLaLa}-Variable auf oberster Ebene unterscheidet:
+
+@example
+traLaLa = @{ c'4 d'4 @}
+\layout @{ traLaLa = 1.0 @}
+@end example
+
+Jede Eingabedatei ist solch ein Gültigkeitsbereich, und alle
+@code{\header}-, @code{\midi}- und @code{\layout}-Umgebungen
+sind Gültigkeitsbereiche, die in diesen obersten Gültigkeitsbereich
+eingebettet sind.
+
+Sowohl Variablen als auch Gültigkeitsbereiche sind im Guile Modulsystem
+eingebaut. Ein anonymes Scheme-Modul wird jedem Gültigkeitsbereich
+angehängt. Eine Zuweisen in der Form von
+
+@example
+traLaLa = @{ c'4 d'4 @}
+@end example
+
+@noindent
+wird intern in die Scheme-Definition
+
+@example
+(define traLaLa @var{Scheme-Wert von `@code{... }'})
@end example
@noindent
-Die 24 wird in der Variablen @code{vierundzwanzig} gespeichert.
-Die gleiche Zuweisung kann auch vollständig in Scheme geschrieben
-werden:
+konvertiert.
+
+Das bedeutet, dass LilyPond-Variablen und Scheme-Variablen frei gemischt
+werden können. Im folgenden Beispiel wird ein Notenfragment in der
+Variable @code{traLaLa} gespeichert und mit Scheme dupliziert. Das
+Resultat wird in eine @code{\score}-Umgebung mit einer weiteren
+Variable @code{twice} importiert:
+
+@lilypond[verbatim]
+traLaLa = { c'4 d'4 }
+
+%% dummy action to deal with parser lookahead
+#(display "this needs to be here, sorry!")
+
+#(define newLa (map ly:music-deep-copy
+ (list traLaLa traLaLa)))
+#(define twice
+ (make-sequential-music newLa))
+
+{ \twice }
+@end lilypond
+
+In diesem Beispiel geschieht die Zuweisung, nachdem der Parser sichergestellt
+hat, dass nichts interessantes mehr nach @code{traLaLa = @{ ... @}} passiert.
+Ohne die Dummy-Aussage in dem Beispiel würde die @code{newLa}-Definition ausgeführt,
+bevor @code{traLaLa} definiert ist, was einen Syntax-Fehler hervorrufen würde.
+
+Das Beispiel zeigt, wie man musikalische Ausdrücke aus der Eingabe in den
+Scheme-Auswerter @qq{exportieren} kann. Es geht auch andersherum. Indem
+man Scheme-Werten in die Funktion @code{ly:export} einschließt, wird ein
+Scheme-Wert interpretiert, als ob er in LilyPond-Syntax eingeben wäre.
+Anstatt @code{\twice} zu definieren, könne man also auch schreiben:
@example
-#(define vierundzwanzig (* 2 zwoelf))
+...
+@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example
-Der @emph{Name} einer Variable ist auch ein Ausdruck, genauso wie
-eine Zahl oder eine Zeichenkette. Er wird wie folgt eingegeben:
+Scheme-Code wird sofort interpretiert, wenn der Parser darauf stößt. Um
+Scheme-Code als Makro zu definieren (das später aufgerufen werden soll),
+muss man @ref{Leere Funktionen} benutzen oder
@example
-#'vierundzwanzig
+#(define (nopc)
+ (ly:set-option 'point-and-click #f))
+
+...
+#(nopc)
+@{ c'4 @}
@end example
-@funindex #'symbol
-@cindex Zitieren in Scheme
+@knownissues
+
+Scheme- und LilyPond-Variablen können nicht gemischt werden, wenn man die
+@code{--safe}-Option benutzt.
-Das Apostroph @code{'} verhindert, dass bei der Scheme-Auswertung
- @code{vierundzwanzig} durch @code{24} ersetzt wird. Anstatt dessen erhalten
- wir die Bezeichnung @code{vierundzwanzig}.
-Diese Syntax wird sehr oft verwendet, weil es manche
-Einstellungsveränderungen erfordern, dass Scheme-Werte einer
-internen Variable zugewiesen werden, wie etwa
+@node Objekteigenschaften
+@subsection Objekteigenschaften
+@translationof Object properties
+
+Objekteigenschaften werden in LilyPond in Form von Alisten-Ketten
+gespeichert, also als Listen von Alisten. Eigenschaften werden
+geändert, indem man Werte an den Anfang der Eigenschaftsliste
+hinzufügt. Eigenschaften werden gelesen, indem Werte aus der
+Aliste gelesen werden.
+
+Ein neuer Wert für eine Eigenschaft kann gesetzt werden, indem man
+der Alist einen Wert mit Schlüssel und dem Wert zuweist. Die
+LilyPond-Syntax hierfür ist:
@example
\override Stem #'thickness = #2.6
@end example
-Diese Anweisung verändert die Erscheinung der Notenhälse. Der Wert
-@code{2.6} wird der Variable @code{thickness} (Dicke) eines
-@code{Stem}-(Hals)-Objektes gleichgesetzt.
+Diese Anweisung verändert die Erscheinung der Notenhälse. Der Alist-Eintrag
+@code{'(thickness . 2.6)} wird zu der Eigenschaftsliste eines
+@code{Stem}-(Hals-)Objektes hinzugefügt.
@code{thickness} wird relativ zu den Notenlinien errechnet, in diesem
Fall sind die Hälse also 2,6 mal so dick wie die Notenlinien. Dadurch
werden Hälse fast zweimal so dick dargestellt, wie sie normalerweise sind.
Um zwischen Variablen zu unterscheiden, die in den Quelldateien direkt
-definiert werden (wie @code{vierundzwanzig} weiter oben), und zwischen denen,
+definiert werden (wie @code{Vierundzwanzig} weiter oben), und zwischen denen,
die für interne Objekte zuständig sind, werden hier die ersteren
-@qq{Bezeichner} genannt, die letzteren dagegen @qq{Eigenschaften}.
+@qq{Variablen} genannt, die letzteren dagegen @qq{Eigenschaften}.
Das Hals-Objekt hat also eine @code{thickness}-Eigenschaft, während
-@code{vierundzwanzig} ein Bezeichner ist.
+@code{Vierundzwanzig} eine Variable ist.
@cindex Eigenschaften versus Bezeichner
@cindex Bezeichner versus Eigenschaften
-Sowohl zweidimensionale Abstände (X- und Y-Koordinaten) als auch
-Größen von Objekten (Intervalle mit linker und rechter Begrenzung) werden
-als @code{pairs} (Paare) eingegeben. Ein Paar@footnote{In der
-Scheme-Terminologie wird ein Paar @code{cons} genannt und seine
-zwei Elemente @code{car} und @code{cdr}.} wird als @code{(erster . zweiter)}
-eingegeben und sie müssen mit dem Apostroph eingeleitet werden, genauso
-wie Symbole:
+
+@node Zusammengesetzte LilyPond-Variablen
+@subsection Zusammengesetzte LilyPond-Variablen
+@translationof LilyPond compound variables
+
+@subheading Abstände (offset)
+
+
+
+Zweidimensionale Abstände (X- und Y-Koordinaten) werden
+als @code{pairs} (Paare) gespeichert. Der @code{car}-Wert des
+Abstands ist die X-Koordinate und der @code{cdr}-Wert die
+Y-Koordinate.
@example
\override TextScript #'extra-offset = #'(1 . 2)
@end example
-Hierdurch wird das Paar (1, 2) mit der Eigenschaft @code{extra-offset}
+Hierdurch wird das Paar @code{(1 . 2)} mit der Eigenschaft @code{extra-offset}
des TextScript-Objektes verknüpft. Diese Zahlen werden in
Systembreiten gemessen, so dass der Befehl das Objekt eine Systembreite
nach rechts verschiebt und zwei Breiten nach oben.
-Die zwei Elemente eines Paares können von beliebigem Inhalt sein, etwa
+Prozeduren, um mit Abständen zu arbeiten, finden sich in @file{scm/lily-library.scm}.
+
+@subheading Bereiche (extend)
+
+Paare werden auch benutzt, um Intervalle zu speichern, die einen Zahlenbereich
+vom Minimum (dem @code{car}) bis zum Maximum (dem @code{cdr}) darstellen.
+Intervalle werden benutzt, um die X- und Y-Ausdehnung von druckbaren
+Objekten zu speichern. Bei X-Ausdehnungen ist @code{car} die linke
+X-Koordinate und @code{cdr} die rechte X-Koordinate. Für Y-Ausdehnungen
+ist @code{car} die untere Koordinate und @code{cdr} die obere Koordinate.
+
+Prozeduren, um mit Intervallen zu arbeiten, finden sich in
+@file{scm/lily-library.scm}. Diese Prozeduren sollten benutzt, wenn es möglich
+ist, um den Code konsistent zu halten.
+
+@subheading Eigenschafts-Alisten (property alist)
+
+Eine Eigenschafts-Aliste ist eine LilyPond-Datenstruktur, die eine Aliste
+darstellt, deren Schlüssel Eigenschaften sind und deren Werte
+Scheme-Ausdrücke sind, die den erwünschen Wert der Eigenschaft ausgeben.
+
+LilyPond-Eigenschaften sind Scheme-Symbole, wie etwa @code{'thickness}
+(Dicke).
+
+@subheading Alisten-Ketten (alist chains)
+
+Eine Alisten-Kette ist eine Liste, die Eigenschafts-Alisten enthält.
+
+Die Menge aller Eigenschaften, die sich auf einen Grob auswirken, wird
+typischerweise in einer Alisten-Kette gespeichert. Um den Wert einer
+bestimmten Eigenschaft zu finden, die ein Grob haben soll, wird jede
+Liste in der Kette nach einander durchsucht, wobei nach einem Eintrag
+geschaut wird, der den Eigenschaftsschlüssel enthält. Der erste
+gefundene Alisten-Eintrag wird benutzt und dessen Wert ist der
+Wert der Eigenschaft.
+
+Die Scheme-Prozedur @code{chain-assoc-get} wird normalerweise benutzt,
+um Grob-Eigenschaftenwerte zu erhalten.
+
+
+@node Interne musikalische Repräsentation
+@subsection Interne musikalische Repräsentation
+@translationof Internal music representation
+
+Intern werden Noten als Scheme-Liste dargestellt. Die Liste enthält
+verschiedene Elemente, die die Druckausgabe beeinflussen. Parsen
+nennt man den Prozess, der die Noten aus der LilyPond-Repräsentation
+in die interne Scheme-Repräsentation überführt.
+
+Wenn ein musikalischer Ausdruck geparst wird, wird er in eine Gruppe
+von Scheme-Musikobjekten konvertiert. Die definierende Eigenschaft
+eines Musikobjektes ist, dass es Zeit einnimmt. Die Zeit, die
+ein Objekt braucht, wird Dauer (engl. @emph{duration}) genannt.
+Dauern werden in rationalen Zahlen ausgedrückt, die die Länge des
+Musikobjekts in Ganzen Noten angeben.
+
+Ein Musikobjekt hat drei Typen:
+
+@itemize
+@item
+Musikbezeichnung (music name): Jeder Musikausdruck hat eine Bezeichnung. Eine
+Note beispielsweise erzeugt ein @rinternals{NoteEvent} und @code{\simultaneous}
+produziert @rinternals{SimultaneousMusic}. Eine Liste aller möglichen
+Ausdrücke findet sich in der Referenz der Interna, unter
+@rinternals{Music expressions}.
+
+@item
+Typ (type) oder Schnittstelle (interface): Jede Musikbezeichnung hat mehrere
+Typen oder Schnittstellen, beispielsweise eine Note ist ein Ereignis (@code{event}),
+aber auch ein Notenereignis (@code{note-event}), ein rhythmisches Ereignis
+(@code{rhythmic-event}) und ein Melodieereignis (@code{melodic-event}).
+Alle Musikklassen sind in der Referenz der Interna aufgelistet, unter
+@rinternals{Music classes}.
+
+@item
+C++-Objekt: Jedes Musikobjekt ist durch ein Objekt der C++-Klasse @code{Music}
+repräsentiert.
+@end itemize
+
+Die eigentliche Information eines musikalischen Ausdrucks wird in Eigenschaften
+gespeichert. Ein @rinternals{NoteEvent} beispielsweise hat die Eigenschaften
+Tonhöhe (@code{pitch}) und Dauer (@code{duration}), die die Dauer und die
+Tonhöhe der Note speichern. Eine Liste aller möglichen Eigenschaften findet
+sich in der Referenz der Interna, unter
+@rinternals{Music properties}.
+
+Ein zusammengesetzter musikalischer Ausdruck ist ein Musikobjekt, das andere
+Musikobjekte als Eigenschaften enthält. Eine Liste an Objekten kann in der
+@code{elements}-Eigenschaft eines Musikobjekts bzw. ein einziges
+Ableger-Musikelement in der @code{element}-Eigenschaft gespeichert werden.
+@rinternals{SequentialMusic} beispielsweise hat sein einziges Argument in
+@code{element}. Der Körper einer Wiederholung wird in der @code{element}-Eigenschaft
+von @rinternals{RepeatedMusic} gespeichert, und die alternativen Endungen
+in @code{elements}.
+
+
+@node Komplizierte Funktionen erstellen
+@section Komplizierte Funktionen erstellen
+@translationof Building complicated functions
+
+Dieser Abschnitt zeigt, wie man Information zusammensucht,
+um komplizierte musikalische Funktionen zu erstellen.
+
+@menu
+* Musikalische Funktionen darstellen::
+* Eigenschaften von Musikobjekten::
+* Verdoppelung einer Note mit Bindebögen (Beispiel)::
+* Artikulationszeichen zu Noten hinzufügen (Beispiel)::
+@end menu
+
+
+@node Musikalische Funktionen darstellen
+@subsection Musikalische Funktionen darstellen
+@translationof Displaying music expressions
+
+@cindex interne Speicherung
+@cindex Musikausdrücke anzeigen
+@cindex Anzeigen von Musikausdrücken
+
+@funindex displayMusic
+@funindex \displayMusic
+
+Wenn man eine musikalische Funktion erstellt, ist es oft
+hilfreich sich anzuschauen, wie musikalische Funktionen
+intern gespeichert werden. Das kann mit der Funktion
+@code{\displayMusic} erreicht werden:
@example
-#'(1 . 2)
-#'(#t . #f)
-#'("blah-blah" . 3.14159265)
+@{
+ \displayMusic @{ c'4\f @}
+@}
@end example
-Eine Liste wird eingegeben, indem die Elemente der Liste in Klammern
-geschrieben werden, mit einem Apostroph davor. Beispielsweise:
+@noindent
+zeigt:
@example
-#'(1 2 3)
-#'(1 2 "string" #f)
+(make-music
+ 'SequentialMusic
+ 'elements
+ (list (make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 0 0))
+ (make-music
+ 'AbsoluteDynamicEvent
+ 'text
+ "f")))))
@end example
-Die ganze Zeit wurde hier schon Listen benutzt. Eine Berechnung,
-wie @code{(+ 1 2)}, ist auch eine Liste (welche das Symbol @code{+}
-und die Nummern 1 und@tie{}2 enthält. Normalerweise werden Listen
-als Berechnungen interpretiert und der Scheme-Interpreter ersetzt
-die Liste mit dem Ergebnis der Berechnung. Um eine Liste an sich
-einzugeben, muss die Auswertung angehalten werden. Das geschieht,
-indem der Liste ein Apostroph vorangestellt wird. Für Berechnungen
-kann man also den Apostroph nicht verwenden.
+Normalerweise gibt LilyPond diese Ausgabe auf der Konsole mit
+allen anderen Nachrichten aus. Um die wichtigen Nachrichten
+in einer Datei zu speichern, kann die Ausgabe in eine Datei
+umgeleitet werden:
+
+@example
+lilypond file.ly >display.txt
+@end example
-Innerhalb einer zitierten Liste (also mit Apostroph) muss man keine
-Anführungszeichen mehr setzen. Im Folgenden ein Symbolpaar, eine
-Symbolliste und eine Liste von Listen:
+Mit etwas Umformatierung ist die gleiche Information sehr viel
+einfacher zu lesen:
@example
-#'(stem . head)
-#'(staff clef key-signature)
-#'((1) (2))
+(make-music 'SequentialMusic
+ 'elements (list (make-music 'EventChord
+ 'elements (list (make-music 'NoteEvent
+ 'duration (ly:make-duration 2 0 1 1)
+ 'pitch (ly:make-pitch 0 0 0))
+ (make-music 'AbsoluteDynamicEvent
+ 'text "f")))))
+@end example
+
+Eine musikalische @code{@{ ... @}}-Sequenz hat die Bezeichnung
+@code{SequentialMusic} und ihre inneren Ausdrücke werden als
+Liste in seiner @code{'elements}-Eigenschaft gespeichert. Eine
+Note ist als als ein @code{EventChord}-Ausdruck dargestellt,
+der ein @code{NoteEvent}-Objekt (welches Dauer und
+Tonhöhe speichert) und zusätzliche Information enthält (in
+diesem Fall ein @code{AbsoluteDynamicEvent} mit einer
+@code{"f"}-Text-Eigenschaft.
+
+
+@node Eigenschaften von Musikobjekten
+@subsection Eigenschaften von Musikobjekten
+@translationof Music properties
+
+Das @code{NoteEvent}-Objekt ist das erste Objekt der
+@code{'elements}-Eigenschaft von @code{someNote}.
+
+@example
+someNote = c'
+\displayMusic \someNote
+===>
+(make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 0 0))))
+@end example
+
+Die @code{display-scheme-music}-Funktion ist die Funktion, die von
+@code{\displayMusic} eingesetzt wird, um die Scheme-Repräsentation
+eines musikalischen Ausdrucks anzuzeigen.
+
+@example
+#(display-scheme-music (first (ly:music-property someNote 'elements)))
+===>
+(make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 0 0))
+@end example
+
+Danach wird die Tonhöhe der Note von der @code{'pitch}-Eigenschaft
+des @code{NoteEvent}-Objektes gelesen:
+
+@example
+#(display-scheme-music
+ (ly:music-property (first (ly:music-property someNote 'elements))
+ 'pitch))
+===>
+(ly:make-pitch 0 0 0)
@end example
+Die Tonhöhe einer Note kann geändert werden, indem man diese
+@code{'pitch}-Eigenschaft umdefiniert:
+
+@funindex \displayLilyMusic
+@funindex displayLilyMusic
+
+@example
+#(set! (ly:music-property (first (ly:music-property someNote 'elements))
+ 'pitch)
+ (ly:make-pitch 0 1 0)) ;; Die Tonhöhen auf d' verändern.
+\displayLilyMusic \someNote
+===>
+d'
+@end example
+
+
+@node Verdoppelung einer Note mit Bindebögen (Beispiel)
+@subsection Verdoppelung einer Note mit Bindebögen (Beispiel)
+@translationof Doubling a note with slurs (example)
+
+In diesem Abschnitt soll gezeigt, werden, wie man eine
+Funktion erstellt, die eine Eingabe wie @code{a}
+nach @code{a( a)} umdefiniert. Dazu wird zuerst die
+interne Repräsentation der Musik betrachtet, die
+das Endergebnis darstellt:
+
+@example
+\displayMusic@{ a'( a') @}
+===>
+(make-music
+ 'SequentialMusic
+ 'elements
+ (list (make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 5 0))
+ (make-music
+ 'SlurEvent
+ 'span-direction
+ -1)))
+ (make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 5 0))
+ (make-music
+ 'SlurEvent
+ 'span-direction
+ 1)))))
+@end example
+
+Eine schlechte Nachricht ist, dass die
+@code{SlurEvent}-Ausdrücke @qq{innerhalb}
+der Noten (bzw. innerhalb der
+@code{EventChord}-Ausdrücke) hinzugefügt werden müssen.
+
+Jetzt folgt eine Betrachtung der Eingabe:
+
+@example
+(make-music
+ 'SequentialMusic
+ 'elements
+ (list (make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch 0 5 0))))))
+@end example
+
+In der gewünschten Funktion muss also dieser Ausdruck
+kopiert werden (sodass zwei Noten vorhanden sind, die
+eine Sequenz bilden), dann müssen @code{SlurEvent}
+zu der @code{'elements}-Eigenschaft jeder Noten hinzugefügt
+werden, und schließlich muss eine @code{SequentialMusic}
+mit den beiden @code{EventChords} erstellt werden.
+
+@example
+doubleSlur = #(define-music-function (parser location note) (ly:music?)
+ "Return: @{ note ( note ) @}.
+ `note' is supposed to be an EventChord."
+ (let ((note2 (ly:music-deep-copy note)))
+ (set! (ly:music-property note 'elements)
+ (cons (make-music 'SlurEvent 'span-direction -1)
+ (ly:music-property note 'elements)))
+ (set! (ly:music-property note2 'elements)
+ (cons (make-music 'SlurEvent 'span-direction 1)
+ (ly:music-property note2 'elements)))
+ (make-music 'SequentialMusic 'elements (list note note2))))
+@end example
+
+
+@node Artikulationszeichen zu Noten hinzufügen (Beispiel)
+@subsection Artikulationszeichen zu Noten hinzufügen (Beispiel)
+@translationof Adding articulation to notes (example)
+
+Am einfachsten können Artikulationszeichen zu Noten
+hinzugefügt werden, indem man zwei musikalische Funktionen
+in einen Kontext einfügt, wie erklärt in
+@ruser{Kontexte erstellen}. Hier soll jetzt eine musikalische
+Funktion entwickelt werden, die das vornimmt.
+
+Eine @code{$variable} innerhalb von @code{#@{...#@}} ist das
+gleiche wie die normale Befehlsform @code{\variable} in
+üblicher LilyPond-Notation. Es ist bekannt dass
+
+@example
+@{ \music -. -> @}
+@end example
+
+@noindent
+in LilyPond nicht funktioniert. Das Problem könnte vermieden
+werden, indem das Artikulationszeichen an eine Pseudonote
+gehängt wird:
+
+@example
+@{ << \music s1*0-.-> @}
+@end example
+
+@noindent
+aber in diesem Beispiel soll gezeigt werden, wie man das in
+Scheme vornimmt. Zunächst wird die Eingabe und die gewünschte
+Ausgabe examiniert:
+
+@example
+% Eingabe
+\displayMusic c4
+===>
+(make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch -1 0 0))))
+=====
+% gewünschte Ausgabe
+\displayMusic c4->
+===>
+(make-music
+ 'EventChord
+ 'elements
+ (list (make-music
+ 'NoteEvent
+ 'duration
+ (ly:make-duration 2 0 1 1)
+ 'pitch
+ (ly:make-pitch -1 0 0))
+ (make-music
+ 'ArticulationEvent
+ 'articulation-type
+ "marcato")))
+@end example
+Dabei ist zu sehen, dass eine Note (@code{c4}) als @code{EventChord}
+repräsentiert ist, mit einem @code{NoteEvent}-Ausdruck in ihrer
+Elementenliste. Um eine Marcato-Artikulation hinzuzufügen, muss
+ein @code{ArticulationEvent}-Ausdruck zu der Elementeigenschaft
+des @code{EventChord}-Ausdrucks hinzugefügt werden.
+
+Um diese Funktion zu bauen, wird folgendermaßen begonnen:
+
+@example
+(define (add-marcato event-chord)
+ "Add a marcato ArticulationEvent to the elements of `event-chord',
+ which is supposed to be an EventChord expression."
+ (let ((result-event-chord (ly:music-deep-copy event-chord)))
+ (set! (ly:music-property result-event-chord 'elements)
+ (cons (make-music 'ArticulationEvent
+ 'articulation-type "marcato")
+ (ly:music-property result-event-chord 'elements)))
+ result-event-chord))
+@end example
+
+Die erste Zeile definiert eine Funktion in Scheme: Die Bezeichnung
+der Funktion ist @code{add-marcato} und sie hat eine Variable
+mit der Bezeichnung @code{event-chord}. In Scheme geht der Typ
+einer Variable oft direkt aus der Bezeichnung hervor (das ist auch
+eine gute Methode für andere Programmiersprachen).
+
+@example
+"Add a marcato..."
+@end example
+
+@noindent
+ist eine (englische) Beschreibung, was diese Funktion tut. Sie ist
+nicht unbedingt notwendig, aber genauso wie klare Variablen-Bezeichnungen
+ist auch das eine gute Methode.
+
+@example
+(let ((result-event-chord (ly:music-deep-copy event-chord)))
+@end example
+
+@code{let} wird benutzt, um die lokalen Variablen zu definieren. Hier
+wird eine lokale Variable benutzt: @code{result-event-chord}. Sie erhält
+den Wert @code{(ly:music-deep-copy event-chord)}. @code{ly:music-deep-copy}
+ist eine LilyPond-spezifische Funktion, die wie alle Funktionen mit dem
+Präfix @code{ly:} versehen ist. Sie wird benutzt, um eine Kopie eines
+musikalischen Ausdrucks anzufertigen. Hier wird @code{event-chord}
+(der Parameter der Funktion) kopiert. Die Funktion soll ja nur ein
+Artikulationszeichen an einen @code{EventChord} gehängt werden, deshalb ist es besser,
+den @code{EventChord}, der als Argument gegeben wurde, nicht zu
+verändern, weil er woanders benutzt werden könnte.
+
+Jetzt gibt es @code{result-event-chord}, wobei es sich um einen
+@code{NoteEventChord}-Ausdruck handelt, welcher gleichzeitig eine Kopie
+von @code{event-chord} ist. Das Makro wird seiner Eigenschaftsliste
+hinzugefügt:
+
+@example
+(set! place new-value)
+@end example
+
+Was in diesem Fall @qq{gesetzt} werden soll (@qq{place}) ist die
+@q{elements}-Eigenschaft des @code{result-event-chord}-Ausdrucks.
+
+@example
+(ly:music-property result-event-chord 'elements)
+@end example
+
+@code{ly:music-property} ist die Funktion, mit der musikalische
+Eigenschaften erreicht werden können (die @code{'elements},
+@code{'duration}, @code{'pitch} usw., die in der Ausgabe von
+@code{\displayMusic} weiter oben angezeigt werden). Der neue
+Wert ist, was ehemals die Elementeigenschaft war, mit einem
+zusätzlichen Element: dem @code{ArticulationEvent}-Ausdruck,
+der aus der Ausgabe von
+@code{\displayMusic} kopiert werden kann:
+
+@example
+(cons (make-music 'ArticulationEvent
+ 'articulation-type "marcato")
+ (ly:music-property result-event-chord 'elements))
+@end example
+
+@code{cons} wird benutzt, um ein Element zu einer Liste hinzuzufügen,
+ohne dass die originale Liste verändert wird. Das ist es, was die
+Funktion tun soll: die gleiche Liste, aber mit dem neuen
+@code{ArticulationEvent}-Ausdruck. Die Reihenfolge innerhalb
+der Elementeeigenschaft ist hier nicht relevant.
+
+Wenn schließlich die Marcato-Artikulation zu der entsprechenden
+@code{elements}-Eigenschaft hinzugefügt ist, kann
+@code{result-event-chord} ausgegeben werden, darum die letzte Zeile
+der Funktion.
+
+Jetzt wird die @code{add-marcato}-Funktion in eine musikalische
+Funktion umgewandelt:
+
+@example
+addMarcato = #(define-music-function (parser location event-chord)
+ (ly:music?)
+ "Add a marcato ArticulationEvent to the elements of `event-chord',
+ which is supposed to be an EventChord expression."
+ (let ((result-event-chord (ly:music-deep-copy event-chord)))
+ (set! (ly:music-property result-event-chord 'elements)
+ (cons (make-music 'ArticulationEvent
+ 'articulation-type "marcato")
+ (ly:music-property result-event-chord 'elements)))
+ result-event-chord))
+@end example
+
+Eine Überprüfung, dass die Funktion richtig arbeitet, geschieht
+folgendermaßen:
+
+@example
+\displayMusic \addMarcato c4
+@end example
+
+
+
+
+
+
+@ignore
@menu
* Optimierungen mit Scheme::
@end menu
-@node Optimierungen mit Scheme
-@appendixsec Optimierungen mit Scheme
-@translationof Tweaking with Scheme
+@c node Optimierungen mit Scheme
+@c appendixsec Optimierungen mit Scheme
+@c translationof Tweaking with Scheme
Wir haben gesehen wie LilyPond-Eingabe massiv beeinflusst
werden kann, indem Befehle wie etwa
@c This isn't a valid example with skylining
@c It works fine without padText -td
-@ignore
+
@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
#{
c4^"piu mosso" fis a g
}
@end lilypond
-@end ignore
+
Es kann auch benutzt werden, um Befehle zu erstellen:
\pattern {d16 dis} { ais16-> b\p }
}
@end lilypond
-
+@end ignore
projects / lilypond.git / commitdiff