1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: e5a609e373eae846857f9a6d70a402a3d42b7d94
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Translators: Till Paala
15 @node Schnittstellen für Programmierer
16 @chapter Schnittstellen für Programmierer
17 @translationof Interfaces for programmers
19 Fortgeschrittene Anpassungen können mithilfe der Programmiersprache
20 Scheme vorgenommen werden. Wenn Sie Scheme nicht kennen, gibt
21 es eine grundlegende Einleitung in LilyPonds
25 * LilyPond-Codeabschnitte::
27 * Musikalische Funktionen::
28 * Ereignisfunktionen::
29 * Textbeschriftungsfunktionen::
30 * Kontexte für Programmierer::
31 * Callback-Funktionen::
32 * Scheme-Code innerhalb LilyPonds::
33 * Schwierige Korrekturen::
37 @node LilyPond-Codeabschnitte
38 @section LilyPond-Codeabschnitte
39 @translationof Lilypond code blocks
41 Codeabschnitte in LilyPond sehen etwa so aus:
44 #@{ @var{Lilypond code} #@}
47 Sie können überall eingesetzt werden, wo man Scheme-Code schreiben
48 kann: der Scheme-Einleser wurde geändert, um LilyPond-Codeabschnitte
49 zu akzeptieren und kann mit eingebetteten Scheme-Ausdrücken umgehen,
50 die mit @code{$} und@w{ }@code{#} beginnen.
52 Er extrahiert den LilyPond-Codeabschnitt und erstellt einen Aufruf
53 zum LilyPond-Parser, welcher während der Prorammausführung zur
54 Interpretation des LilyPond-Codeabschnittes aufgerufen wird. Alle
55 eingebetteten Scheme-Ausdrücke werden in der lokalen Umgebung des
56 LilyPond-Codeabschnittes ausgeführt, sodass man Zugruff auf lokale
57 Variablen und Funktionsparameter zu dem Zeitpunkt hat, an dem
58 der LilyPond-Codeabschnitt geschrieben wird.
60 Ein LilyPond-Codeabschnitt kann jeden Inhalt haben, den man auf
61 der rechten Seite einer Zuweisung einsetzt. Zusätzlich entspricht
62 ein leerer LilyPond-Abschnitt einem gültigen musikalischen Ausdruck,
63 und ein LilyPond-Abschnitt, der mehrere musikalische Ereignisse enthält,
64 wird in einen sequenziellen musikalischen Ausdruck umgewandelt.
67 @node Scheme-Funktionen
68 @section Scheme-Funktionen
69 @translationof Scheme functions
71 @cindex Scheme-Funktionen (LilyPond syntax)
73 @emph{Scheme-Funktionen} sind Scheme-Prozeduren, die Scheme-Ausdrücke
74 aus einer Eingabe erstellen können, die in LilyPond-Syntax geschrieben
75 wurde. Sie können in so gut wie allen Fällen aufgerufen werden, in
76 denen es erlaubt ist, @code{#} zur Angabe eines Wertes in Scheme-Syntax
77 einzusetzen. Während Scheme auch eigene Funktionen besitzt, handelt
78 % dieses kapitel von @emph{syntaktischen} Funktionen, Funktionen, die
79 Argumente in LilyPond-Syntax annehmen.
82 * Definition von Scheme-Funktionen::
83 * Benutzung von Scheme-Funktionen::
84 * Leere Scheme-Funktionen::
87 @node Definition von Scheme-Funktionen
88 @subsection Definition von Scheme-Funktionen
89 @translationof Scheme function definitions
91 @funindex define-scheme-function
93 Die übliche Form zur Definition von Scheme-Funktionen ist:
97 #(define-scheme-function
98 (parser location @var{Arg1} @var{Arg2} @dots{})
99 (@var{Typ1?} @var{Typ2?} @dots{})
106 @multitable @columnfractions .33 .66
108 @tab ganz genau das Wort @code{parser} sein muss, damit LilyPond
109 eine Umgebung (@code{#@{}@dots{}@code{#@}}) mit Zugriff
110 auf den Parser bekommt.
112 @item @code{@var{ArgN}}
113 @tab @var{n}te Argument
115 @item @code{@var{TypN?}}
116 @tab eine Scheme-@emph{Typenprädikat}, für welches @code{@var{argN}}
117 @code{#t} ausgeben muss. Manche dieser Prädikate werden vom Parser
118 besonders erkannt, siehe unten. Es gibt auch eine Spezialform
119 @code{(@emph{predicate?} @emph{default})}, um optionale Argumente
120 anzugeben. Wenn das eigentlich Argument fehlt, während die Funktion
121 aufgerufen wird, wird der Standardwert anstelle eingesetzt. Standardwerte
122 werden bei ihrer Definition evaluiert (gilt auch für
123 LilyPond-Codeabschnitte), so dass man besser einen speziellen Wert
124 schreibt, den man einfach erkennen kann, wenn der Wert während der
125 Ausführung der Position evaluiert weren soll. Wenn man das Prädikat
126 in Klammern setzt, aber kein Standardwert folt, wird @code{#f}
127 als Standard eingesetzt. Standardwerte werden weder bei der Definition
128 noch bei der Ausführung mit @emph{predicate?} verifiziert, sodass
129 man selber verantworlich für funktionsfähige Werte ist. Standardwerte,
130 die musikalische Ausdrücke darstellen, werden kopiert und @code{origin}
131 auf den Parameter @code{location} gesetzt.
133 @item @code{@var{body}}
134 @tab Eine Folge von Scheme-Formeln, die der Reihe nach ausgewertet
135 werden, wobei die letzte als Ausgabewert der Scheme-Funktion eingesetzt
136 wird. Sie kann LilyPond-Codeabschnitte enthalten, eingeschlossen mit
137 Raute-Klammern (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), wie beschrieben
138 in @ref{LilyPond-Codeabschnitte}. Innerhalb von LilyPond-Codeabschnitten
139 wird mit @code{#} auf Funktionsargumente (etwa @samp{#Arg1}) verwiesen
140 oder ein neuer Scheme-Ausdruck mit Funktionsargumenten begonnen
141 (etwa @w{@samp{#(cons Arg1 Arg2)}}). Wo normale Scheme-Ausdrücke mit
142 @code{#} nicht funktionieren, kann man auf direkte Scheme-Ausdrücke
143 zurückgreifen, die mit @code{$} begonnen werden (etwa @samp{$music}).
145 Wenn die Funktion eine musikalische Funktion ausgibt, bekommt sie einen
146 Wert von @code{origin}. zugewiesen.
150 Einige Typenprädikate werden vom Parser besonders behandelt, weil
151 er sonst die Argumente nicht zuverlässig erkennen könnte. Im Moment
152 handelt es sich um @code{ly:pitch?} und @code{ly:duration?}.
154 Die Eignung der Argumente für alle anderen Prädikate wird festgestellt,
155 indem das Prädikat aufgerufen wird, nachdem LilyPond es schon in einen
156 Scheme-Ausdruck umgewandelt hat. Demzufolge kann das Argument in
157 Scheme-Syntax angegeben werden, wenn nötig (beginnend mit @code{#} oder
158 als Result des Aufrufes einer Scheme-Funktion), aber LilyPond
159 konvertiert auch eine Reihe von LilyPond-Strukturen nach Scheme,
160 bevor dann tatsächlich die Prädikate überprüft werden. Bei den
161 letzteren handelt es sich im Moment um music (Noten), postevents,
162 simple strings (einfache Zeichenketten mit oder ohne Anführungszeichen)
163 numbers (Zahlen), markup (Beschriftung) und markup lists
164 (Beschriftungslisten), score (Partitur), book (Buch), bookpart
165 (Buchteil), Kontextdefinitions- und Ausgabedefinitionsumgebungen.
167 Für einige Arten von Ausdrücken (wie die meisten Noten, die nicht
168 in Klammern geschrieben werden) muss LilyPond weiter nach vorne
169 schauen als der Ausdruck selber reicht, um das Ende des Ausdrucks
170 zu bestimmen. Wenn solche Ausdrücke für optionale Argumente mit
171 einbezogen würden, indem ihre Prädikate ausgewählt würden, könnte
172 LilyPond nicht mehr zurückgehen, wenn es feststellt, dass der
173 Ausdruck nicht zu dem Parameter passt. Darum müssen manche Formen
174 von Noten möglicherweise in Klammern eingeschlossen werden, damit
175 LilyPond sie akzeptiert. Es gibt auch einige andere Mehrdeutigkeiten,
176 die LilyPond durch Testen von Prädikatfunktionen eingrenzt:
177 ist etwa @samp{-3} die Anmerkung für einen Fingersatz oder eine
178 negative Zahl? Ist @code{"a" 4} im Gesangskontext eine Zeichenkette
179 gefolgt von einer Zahl oder ein Gesangstextereignis mit der Dauer
180 @code{4}? LilyPond entscheidet, indem es Prädaikate befragt. Das
181 heißt, dass man zu durchlässige Prädikate wie @code{scheme?}
182 vermeiden sollte, wenn man eine bestimmmte Verwendung beabsichtigt
183 und nicht nur eine Funktion für die allgemeine Verwendung schreibt.
185 Eine Liste der möglichen vordefinierten Typenprädikte findet sich in
186 @ruser{Vordefinierte Typenprädikate}.
191 @ruser{Vordefinierte Typenprädikate}.
193 Installierte Dateien:
194 @file{lily/music-scheme.cc},
199 @node Benutzung von Scheme-Funktionen
200 @subsection Benutzung von Scheme-Funktionen
201 @translationof Scheme function usage
203 Scheme-Funktionen können überall aufgerufen werden, wo ein
204 Scheme-Ausdruck beginnend mit @code{#} geschrieben werden kann.
205 Man kann eine Scheme-Funktion aufrufen, indem man ihrer Bezeichnung
206 @code{\} voranstellt und Argumente hinten anfügt. Wenn ein optionales
207 Argumentenprädikat nicht mit einem Argument übereinstimmt, lässt
208 LilyPond dieses und alle folgenden Argumente aus und ersetzt sie
209 durch ihre Standardwerte und @qq{speichert} das Argument, das nicht
210 gepasst hat, bis zum nächsten zwingenden Argument. Da das gespeicherte
211 Argument auch noch irgendwo untergebracht werden muss, werden
212 optionale Argumente nicht wirklich als optional angesehen, es sei denn,
213 sie werden von einem zwingenden Argument gefolgt.
215 Es gibt eine Ausnahme: Wenn man @code{\default} anstelle eines optionalen
216 Arguments schreibt, wird dieses und alle folgenden Argumente ausgelassen
217 und durch ihre Standardwerte ersetzt. Das funktioniert auch, wenn kein
218 zwingendes Argument folgt, weil @code{\default} nicht gespeichert werden
219 muss. Die Befehle @code{mark} und @code{key} benützten diesen Trick,
220 um ihr Standardverhalten zur verfügung zu stellen, wenn sie
221 @code{\default} nachgestellt haben.
223 Abgesehen von Stellen, wo ein Scheme-Wert benötigt ist, gibt es
224 wenige Stellen, wo @code{#}-Ausdrücke zwar für ihre (Neben-)Wirkung
225 akzeptiert und ausgewertet, aber ansonsten ignoriert werden. Meistens
226 handelt es sich dabei um Stellen, wo eine Zuweisung auch in Ordnung
229 Weil es eine schlechte Idee ist, einen Wert auszugeben, der in einigen
230 Kontexten misinterpretiert werden könnte, sollte man Scheme-Funktionen
231 nur in den Fällen benutzen, in welchen sie immer einen sinnvollen
232 Wert ausgeben, und leere Scheme-Funktionen an anderen stellen
233 einsetzen. Siehe auch @pxref{Leere Scheme-Funktionen}.
236 @node Leere Scheme-Funktionen
237 @subsection Leere Scheme-Funktionen
238 @translationof Void scheme functions
240 @funindex define-void-function
243 Manchmal wird eine Prozedur ausgeführt, um eine Aktion zu machen und nicht,
244 um einen Wert auszugeben. Einige Programmiersprachen (wie C oder Scheme)
245 setzen Funktionen für beide Konzepte ein und verwerfen einfach den
246 Rückgabewert (normalerweise, indem einem Ausdruck erlaubt wird, als
247 Aussage zu funktionieren und das Ergebnis ignoriert wird). Das ist
248 klug, aber auch fehleranfällig: die meisten C-Kompilierer haben heutzutage
249 Warnungen für verschiedene nicht-@qq{gültige} Ausdrücke, die verworfen
250 werden. Viele Funktionen, die eine Aktion ausführen, werden von den
251 Scheme-Standards als Funktionen betrachtet, deren Wiedergabewert unspezifiert
252 ist. Der Scheme-Interpreter von LilyPond, Guile, hat den eindeutigen
253 Wert @code{*unspecified*}, der normalerweise (etwa wenn man @code{set!}
254 direkt auf eine Variable anwendet), aber leider nicht konsistent in
255 diesen Fällen ausgegeben wird.
257 Indem man eine LilyPond-Funktion mit @code{define-void-function} definiert,
258 geht man sicher, dass dieser Spezialwert (der einzige Wert, der das
259 Prädikat @code{void?} erfüllt) wiedergegeben wird.
263 #(define-void-function
266 (ly:set-option 'point-and-click #f))
268 \noPointAndClick % Point and Click deaktivieren
271 Wenn man einen Ausdruck nur wegen seiner Nebeneffekte evaluieren will
272 und keinen der möglicherweise ausgegebenen Werte interpretiert haben
273 will, kann man dem Ausdruck @code{\void} voranstellen:
276 \void #(hashq-set! eine-Tabelle ein-Schlüssel ein-Wert)
279 Auf diese Weise kann man sicher sein, dass LilyPond dem ausgegebenen
280 Wert keine Bedeutung zuweist, unabhängig davon, wo er angetroffen wird.
281 Das funktioniert auch für musikalische Funktionen wie @code{\displayMusic}.
284 @node Musikalische Funktionen
285 @section Musikalische Funktionen
286 @translationof Music functions
288 @cindex musikalische Funktionen
290 @emph{Musikalische Funktionen} sind Scheme-Prozeduren,
291 die musikalische Ausdrücke automatisch erstellen können und dadurch die
292 Eingabedatei maßgeblich vereinfachen können.
295 * Definition der musikalischen Funktionen::
296 * Benutzung von musikalischen Funktionen::
297 * Einfache Ersetzungsfunktionen::
298 * Mittlere Ersetzungsfunktionen::
299 * Mathematik in Funktionen::
300 * Funktionen ohne Argumente::
301 * Leere musikalische Funktionen::
305 @node Definition der musikalischen Funktionen
306 @subsection Definition der musikalischen Funktionen
307 @translationof Music function definitions
309 Die allgemeine Form zur Definition musikalischer Funktionen ist:
313 #(define-music-function
314 (parser location @var{Arg1} @var{Arg2} @dots{})
315 (@var{Typ1?} @var{Typ2?} @dots{})
320 analot zu Scheme-Funktionen, siehe @ref{Definition von Scheme-Funktionen}.
321 In der Mehrzahl der Fälle ist @var{body} ein LilyPond-Codeabschnitt (siehe
322 @ref{LilyPond-Codeabschnitte}.
324 Eine Liste der möglichen Typenprädikate findet sich in
325 @ruser{Vordefinierte Typenprädikate}.
330 @ruser{Vordefinierte Typenprädikate}.
332 Installierte Dateien:
333 @file{lily/music-scheme.cc},
338 @node Benutzung von musikalischen Funktionen
339 @subsection Benutzung von musikalischen Funktionen
340 @translationof Music function usage
342 Musikalische Funktionen können zur Zeit an verschiedenen Stellen benützt
343 werden. Abhängig davon, wo sie eingesetzt werden, gibt es Begrenzungen,
344 damit die Funktionen eindeutig interpretiert werden können. Das Resultat,
345 das eine musikalische Funktion wiedergibt, muss mit dem Kontext kompatibel
346 sein, indem sie aufgerufen wird.
350 Auf höchster Ebene in einer musikalischen Funktion. Keine Begrenzungen.
353 Als ein Nach-Ereignis, explizit begonnen mit einem Richtungsindikator
354 (einer von @code{-}, @code{^}, @w{und @code{_}}). Wichtig dabei ist,
355 dass musikalische Funktionen, die das Nachereignis ausgeben, als
356 normale Noten akzeptiert werden. Dabei erhält man ein Resultat, das
357 etwa folgendem entspricht:
363 In diesem Fall kann man keinen @emph{offenen} musikalischen Ausdruck als
364 letztes Argument einsetzen, also ein Argument, das in einem musikalischen
365 Ausdruck schließt, der weitere Nach-Ereignisse akzeptieren kann.
368 Als Element eines Akkordes. Der ausgegebene Ausdruck muss vom Typ
369 @code{rhythmic-event} sein, wahrscheinlich auch @code{NoteEvent}.
374 Die besonderen Regeln für noch nicht abgearbeitete Argumente machen es
375 möglich, polymorphe Funktionen wie @code{\tweak} zu schreiben,
376 die auf unterschiedliche Konstruktionen angewendet werden können.
379 @node Einfache Ersetzungsfunktionen
380 @subsection Einfache Ersetzungsfunktionen
381 @translationof Simple substitution functions
383 Einfache Ersetzungsfunktionen sind musikalische Funktionen, deren
384 musikalische Ausgabe-Funktion im LilyPond-Format geschrieben ist
385 und Funktionsargumente in der Ausgabefunktion enthält. Sie werden
386 beschrieben in @ruser{Beispiele der Ersetzungsfunktionen}
389 @node Mittlere Ersetzungsfunktionen
390 @subsection Mittlere Ersetzungsfunktionen
391 @translationof Intermediate substitution functions
393 Mittlere Ersetzungsfunktionen setzen sich aus einer Mischung von
394 Scheme-Code und LilyPond-Code in der musikalischen Ausgabe-Funktion
397 Einige @code{\override}-Befehle benötigen ein Zahlenpaar
398 (als @code{cons}-Zelle in Scheme bezeichnet).
400 Das Paar kann direkt an die musikalische Funktion
401 mit der Variable @code{pair?} weitergeleitet werden:
405 #(define-music-function
406 (parser location beg-end)
409 \once \override Beam.positions = #beg-end
413 \manualBeam #'(3 . 6) c8 d e f
417 Anstelle dessen können auch die Zahlen, aus denen das Paar besteht,
418 einzeln als eigenständige Argumente weitergeleitet und der
419 Scheme-Code, der das Paar erstellt, in die musikalische Funktion
422 @lilypond[quote,verbatim,ragged-right]
424 #(define-music-function
425 (parser location beg end)
428 \once \override Beam.positions = #(cons beg end)
432 \manualBeam #3 #6 c8 d e f
437 @node Mathematik in Funktionen
438 @subsection Mathematik in Funktionen
439 @translationof Mathematics in functions
441 Musikalische Funktionen können neben einfachen Ersetzungen
442 auch Scheme-Programmcode enthalten:
444 @lilypond[quote,verbatim,ragged-right]
446 #(define-music-function
447 (parser location mag)
450 \override Stem.length = #(* 7.0 mag)
451 \override NoteHead.font-size =
452 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
457 \revert NoteHead.font-size
462 \AltOn #1.5 c c \AltOff c2
467 Dieses Beispiel kann auch umformuliert werden, um musikalische Ausdrücke
470 @lilypond[quote,verbatim,ragged-right]
472 #(define-music-function
473 (parser location mag music)
476 \override Stem.length = #(* 7.0 mag)
477 \override NoteHead.font-size =
478 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
481 \revert NoteHead.font-size
485 c2 \withAlt #0.5 { c4 c }
486 \withAlt #1.5 { c c } c2
491 @node Funktionen ohne Argumente
492 @subsection Funktionen ohne Argumente
493 @translationof Functions without arguments
495 In den meisten Fällen sollten Funktionen ohne Argumente mit einer
496 Variable notiert werden:
499 dolce = \markup@{ \italic \bold dolce @}
502 In einigen wenigen Fällen kann es aber auch sinnvoll sein, eine
503 musikalische Funktion ohne Argumente zu erstellen:
507 #(define-music-function
510 (if (eq? #t (ly:get-option 'display-bar-numbers))
511 #@{ \once \override Score.BarNumber.break-visibility = ##f #@}
515 Damit auch wirklich Taktzahlen angezeigt werden, wo die
516 Funktion eingesetzt wurde, muss @command{lilypond} mit
520 lilypond -d display-bar-numbers Dateiname.ly
527 @node Leere musikalische Funktionen
528 @subsection Leere musikalische Funktionen
529 @translationof Void music functions
531 Eine musikalische Funktion muss einen musikalischen Ausdruck
532 ausgeben. Wenn man eine Funktion nur für ihre Nebeneffekte
533 ausführt, sollte man @code{define-void-function} benützen.
534 Es kann aber auch Fälle geben, in denen man teilweise eine
535 musikalische Funktion erstellen will, teilweise aber nicht
536 (wie im vorherigen Beispiel). Indem man eine leere (@code{void})
537 Funktion mit @code{#@{ #@}} ausgibt, wird das erreicht.
540 @node Ereignisfunktionen
541 @section Ereignisfunktionen
542 @translationof Event functions
544 @funindex define-event-function
545 @cindex Ereignisfunktionen
547 Damit man eine musikalische Funktion anstelle eines Ereignisses benützen
548 kann, muss man ihr einen Richtungsindikator voranstellen. Manchmal
549 entspricht dies jedoch nicht der Syntax der Konstruktionen, die man ersetzen
550 will. Dynamikbefehle beispielsweise werden normalerweise ohne Richtungsangabe
551 angehängt, wie @code{c'\pp}. Das Folgende ist eine Möglichkeit, beliebige
552 Dynamikbefehle zu schreiben:
554 @lilypond[quote,verbatim,ragged-right]
555 dyn=#(define-event-function (parser location arg) (markup?)
556 (make-dynamic-script arg))
557 \relative c' { c\dyn pfsss }
560 Man kann das Gleiche auch mit einer musikalischen Funktion erreichen, aber dann
561 muss man immer einen Richtungsindikator voranstellen, wie @code{@w{c-\dyn pfsss}}.
564 @node Textbeschriftungsfunktionen
565 @section Textbeschriftungsfunktionen
566 @translationof Markup functions
568 Textbeschriftungselemente sind als besondere Scheme-Funktionen
569 definiert, die ein @code{Stencil}-Objekt erstellen, dem eine Anzahl
570 an Argumenten übergeben wird.
573 * Beschriftungskonstruktionen in Scheme::
574 * Wie Beschriftungen intern funktionieren::
575 * Neue Definitionen von Beschriftungsbefehlen::
576 * Neue Definitionen von Beschriftungslistenbefehlen::
580 @node Beschriftungskonstruktionen in Scheme
581 @subsection Beschriftungskonstruktionen in Scheme
582 @translationof Markup construction in Scheme
584 @cindex Textbeschriftungsbefehle, definieren
585 @cindex Textbeschriftung, eigene Befehle
586 @cindex eigene Befehle, Textbeschriftung
587 @cindex markup, eigene Befehle
588 @cindex Befehle definieren, Textbeschriftung
590 Das @code{markup}-(Textbeschriftungs)Makro erstellt Textbeschriftungs-Ausdrücke
591 in Scheme, wobei eine LilyPond-artige Syntax benutzt wird. Beispielsweise
595 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
596 #:larger #:line ("foo" "bar" "baz")))
603 #@{ \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
604 \larger \line @{ foo bar baz @} @} #@}
608 Dieses Beispiel zeigt die hauptsächlichen Übersetzungsregeln
609 zwischen normaler Textbeschriftungssyntax von LilyPond und der
610 Textbeschriftungssyntax in Scheme. Es ist meistens der beste
611 Weg, @code{#@{ @dots{} #@}} zur Eingabe von LilyPond-Syntax zu
612 benützen, aber es soll auch erklärt werden, wie man das
613 @code{markup}-Makro einsetzt, um eine Lösung nur in Scheme zu bekommen.
616 @multitable @columnfractions .3 .3
617 @item @b{LilyPond} @tab @b{Scheme}
618 @item @code{\markup Text1} @tab @code{(markup Text1)}
619 @item @code{\markup @{ Text1 Text2 ... @}} @tab
620 @code{(markup Text1 Text2 ... )}
621 @item @code{\Beschriftungsbefehl} @tab @code{#:Beschriftungsbefehl}
622 @item @code{\Variable} @tab @code{Variable}
623 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
624 @item @code{Zeichenkette} @tab @code{"Zeichenkette"}
625 @item @code{#scheme-Arg} @tab @code{scheme-Arg}
629 Die gesamte Scheme-Sprache ist innerhalb des @code{markup}-Makros
630 zugänglich. Man kann also beispielsweise Funktionen innerhalb
631 eines @code{markup} aufrufen, um Zeichenketten zu manipulieren.
632 Das ist nützlich, wenn neue Beschriftungsbefehle definiert werden
634 @ref{Neue Definitionen von Beschriftungsbefehlen}).
639 Das Beschriftungslistenargument von Befehlen wie @code{#:line},
640 @code{#:center} und @code{#:column} kann keine Variable oder
641 das Resultat eines Funktionsaufrufen sein.
644 (markup #:line (Funktion-die-Textbeschriftung-ausgibt))
648 ist ungültig. Man sollte anstatt dessen die Funktionen
649 @code{make-line-markup}, @code{make-center-markup} oder
650 @code{make-column-markup} benutzen:
653 (markup (make-line-markup (Funktion-die-Textbeschriftung-ausgibt)))
657 @node Wie Beschriftungen intern funktionieren
658 @subsection Wie Beschriftungen intern funktionieren
659 @translationof How markups work internally
661 In einer Textbeschriftung wie
664 \raise #0.5 "Textbeispiel"
668 ist @code{\raise} unter der Haube durch die @code{raise-markup}-Funktion
669 repräsentiert. Der Beschriftungsausdruck wird gespeichert als
672 (list raise-markup 0.5 (list simple-markup "Textbeispiel"))
675 Wenn die Beschriftung in druckbare Objekte (Stencils) umgewandelt ist,
676 wir die @code{raise-markup}-Funktion folgendermaßen aufgerufen:
681 @var{Liste der Eigenschafts-alists}
683 @var{die "Textbeispiel"-Beschriftung})
686 Die @code{raise-markup}-Funktion erstellt zunächst den Stencil für die
687 @code{Textbeispiel}-Beschriftung und verschiebt dann diesen Stencil
688 um 0.5 Notenlinienzwischenräume nach oben. Das ist ein einfaches
689 Beispiel. Weitere, kompliziertere Beispiele finden sich nachfolgend
690 in diesem Abschnitt und in der Datei
691 @file{scm/define-markup-commands.scm}.
694 @node Neue Definitionen von Beschriftungsbefehlen
695 @subsection Neue Definitionen von Beschriftungsbefehlen
696 @translationof New markup command definition
698 Dieser Abschnitt behandelt die Definition von neuen Textbeschriftungsbefehlen.
701 * Syntax der Definition von Textbeschriftungsbefehlen::
702 * Über Eigenschaften::
703 * Ein vollständiges Bespiel::
704 * Eingebaute Befehle anpassen::
707 @node Syntax der Definition von Textbeschriftungsbefehlen
708 @unnumberedsubsubsec Syntax der Definition von Textbeschriftungsbefehlen
709 @translationof Markup command definition syntax
711 Neue Textbeschriftungsbefehle können mit dem
712 @code{define-markup-command}-Scheme-Makro definiert werden.
715 (define-markup-command (@var{befehl-bezeichnung} @var{layout} @var{props} @var{Arg1} @var{Arg2} ...)
716 (@var{Arg1-typ?} @var{Arg2-typ?} ...)
717 [ #:properties ((@var{Eigenschaft1} @var{Standard-Wert1})
725 @item @var{befehl-bezeichnung}
726 die Bezeichnung des Befehls
729 die @q{layout}-Definition
732 eine Liste an assoziativen Listen, in der alle aktiven Eigenschaften enthalten sind
735 das @var{i}te Befehlsargument
737 @item @var{argi-type?}
738 eine Eigenschaft für das @var{i}te Argument
741 Wenn der Befehl Eigenschaften des @code{props}-Arguments benutzt,
742 kann das @code{#:properties}-Schlüsselwort benutzt werden um zu
743 bestimmen, welche Eigenschaften mit welchen Standard-Werten benutzt
746 Argumente werden nach ihrem Typ unterschieden:
749 @item eine Textbeschriftung entspricht einem Typenprädikat @code{markup?};
750 @item eine Textbeschriftungsliste entspricht einem Typenprädikat
752 @item jedes andere Scheme-Objekt entspricht Typenprädikaten wie etwa
753 @code{list?}, @code{number?}, @code{boolean?}, usw.
756 Es gibt keine Einschränkung in der Reihenfolge der Argumente (nach
757 den Standard-Argumenten @code{layout} und @code{props}). Textbeschriftungsfunktionen,
758 die als letztes Argument eine Textbeschriftung haben, haben die
759 Besonderheit, dass sie auf Textbeschriftungslisten angewendet werden
760 können, und das Resultat ist eine Textbeschriftungsliste, in der
761 die Textbeschriftungsfuktion (mit den angegebenen Argumenten am Anfang)
762 auf jedes Element der originalen Textbeschriftungsliste angewendet
765 Da das Wiederholen der Argumente am Anfang bei der Anwendung einer
766 Textbeschriftungsfunktion auf eine Textbeschriftungsliste for allem
767 für Scheme-Argumente sparsam ist, kann man Leistungseinbußen vermeiden,
768 indem man nur Scheme-Argumente für die Argumente am Anfang einsetzt,
769 wenn es sich um Textbeschriftungsfunktionen handelt, die eine Textbeschriftung
770 als letztes Argument haben.
773 @node Über Eigenschaften
774 @unnumberedsubsubsec Über Eigenschaften
775 @translationof On properties
777 Die @code{layout}- und @code{props}-Argumente der Textbeschriftungsbefehle
778 bringen einen Kontext für die Interpretation der Beschriftung:
779 Schriftgröße, Zeilenlänge usw.
781 Das @code{layout}-Argument greift auf Eigenschaften zu, die in der
782 @code{paper}-Umgebung definiert werden, indem man die @code{ly:output-def-lookup}-Funktion
783 benutzt. Beispielsweise liest man die Zeilenlänge (die gleiche, die auch in
784 Partituren benutzt wird) aus mit:
787 (ly:output-def-lookup layout 'line-width)
790 Das @code{props}-Argument stellt einige Eigenschaften für die Textbeschriftungsbefehle
791 zur Verfügung. Beispielsweise wenn der Überschrifttext einer
792 @code{book}-Umgebung interpretiert wird, werden alle Variablen, die
793 in der @code{\header}-Umgebung definiert werden, automatisch zu @code{props}
794 hinzugefügt, sodass die Beschriftung auf Titel, Komponist usw. der
795 @code{book}-Umgebung zugreifen kann. Das ist auch eine Möglichkeit, das
796 Verhalten eines Beschriftungsbefehls zu konfigurieren: Wenn etwa ein
797 Befehl die Schriftgröße während der Verarbeitung einsetzt, wird die
798 Schriftgröße aus den @code{props} ausgelesen und nicht mit einem eigenen
799 @code{font-size}-Argument definiert. Beim Aufruf des Beschriftungsbefehls
800 kann der Wert der Schriftgröße geändert werden, womit sich auch das Verhalten
801 des Befehls verändert. Benutzen Sie das @code{#:properties}-Schlüsselwort
802 von @code{define-markup-command} um zu definieren, welche Eigenschaften aus den
803 @code{props}-Argumenten ausgelesen werden sollen.
805 Das Beispiel im nächsten Abschnitt illustriert, wie man auf Eigenschaften
806 in einem Beschriftungsbefehl zugreifen und sie verändern kann.
809 @node Ein vollständiges Bespiel
810 @unnumberedsubsubsec Ein vollständiges Bespiel
811 @translationof A complete example
813 Das folgende Beispiel definiert einen Beschriftungsbefehl, der einen
814 doppelten Kasten um einen Text zeichnet.
816 Zuerst wollen wir ein annäherndes Ergebnis mit Textbeschriftungen definieren.
817 Nach Stöbern in @ruser{Textbeschriftungsbefehle} finden wir den Befehl
820 @lilypond[quote,verbatim,ragged-right]
821 \markup \box \box HELLO
824 Wir wollen aber etwas mehr Abstand (engl. padding) zwischen dem Text und dem Kasten.
825 Nach der Dokumentation von @code{\box} hat der Befehl eine
826 @code{box-padding}-Eigenschaft, die den Standardwert von 0.2 hat. Die
827 Dokumentation zeit auch, wir man den Wert verändert:
829 @lilypond[quote,verbatim,ragged-right]
830 \markup \box \override #'(box-padding . 0.6) \box A
833 Auch der Abstand zwischen den zwei Kästen ist uns zu klein und soll auch
836 @lilypond[quote,verbatim,ragged-right]
837 \markup \override #'(box-padding . 0.4) \box
838 \override #'(box-padding . 0.6) \box A
841 Diese lange Textbeschriftung immer wieder schreiben zu müssen, ist
842 anstrengend. Hier kömmt ein Textbeschriftungsbefehl ins Spiel. Wir
843 schreiben uns alle einen @code{double-box}-Beschriftungsbefehl, der
844 ein Argument annimmt (den Text). Er zeichnet zwei Kästen mit genügend Abstand:
847 #(define-markup-command (double-box layout props text) (markup?)
848 "Draw a double box around text."
849 (interpret-markup layout props
850 #@{\markup \override #'(box-padding . 0.4) \box
851 \override #'(box-padding . 0.6) \box @{ #text @}#@}))
857 #(define-markup-command (double-box layout props text) (markup?)
858 "Draw a double box around text."
859 (interpret-markup layout props
860 (markup #:override '(box-padding . 0.4) #:box
861 #:override '(box-padding . 0.6) #:box text)))
864 @code{text} ist die Bezeichnung des Arguments dieses Befehls,
865 und @code{markup?} ist seine Art: hiermit wird der Befehl als
866 Beschriftungsbefehl identifiziert. Die @code{interpret-markup}-Funktion
867 wird in den meisten Beschriftungsbefehlen benutzt: sie erstellt einen
868 Stencil, wobei @code{layout}, @code{props} und eine Beschriftung benutzt
869 werden. Im zweiten Fall wird diese Beschriftung durch das
870 @code{markup}-Scheme-Makro erstellt, siehe auche
871 @ref{Beschriftungskonstruktionen in Scheme}.
872 Die Transformation des @code{\markup}-Ausdrucks in einen
873 Scheme-Beschriftungsausdruck geschieht durch Umschreiben des LilyPond-Codes
876 Der neue Befehl kann wie folgt benutzt werden:
879 \markup \double-box A
882 Es wäre schön, den @code{double-box}-Befehl noch konfigurierbar zu gestalten:
883 in unserem Fall sind die Werte von @code{box-padding} direkt definiert und
884 können nicht mehr vom Benutzer verändert werden. Es wäre auch besser, wenn
885 der Abstand zwischen den beiden Kästen vom Abstand zwischen dem inneren Kasten
886 und dem Text unterschieden werden könnte. Eine neue Eigenschaft muss also
887 definiert werden: @code{inter-box-padding} für den Abstand zwischen den Kästen.
888 @code{box-padding} wird für den inneren Abstand benutzt. Der neue Befehl wird
892 #(define-markup-command (double-box layout props text) (markup?)
893 #:properties ((inter-box-padding 0.4)
895 "Draw a double box around text."
896 (interpret-markup layout props
897 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
898 \override #`(box-padding . ,box-padding) \box
902 Wiederum wäre die entsprechende Version mit dem @code{markup}-Makro
906 #(define-markup-command (double-box layout props text) (markup?)
907 #:properties ((inter-box-padding 0.4)
909 "Draw a double box around text."
910 (interpret-markup layout props
911 (markup #:override `(box-padding . ,inter-box-padding) #:box
912 #:override `(box-padding . ,box-padding) #:box text)))
915 In diesem Code wird das @code{#:properties}-Schlüsselwort benutzt, sodass
916 die Eigenschaften @code{inter-box-padding} und @code{box-padding} aus dem
917 @code{props}-Argument ausgelesen werden, und Standardwerte werden gegeben,
918 falls die Eigenschaften nicht definiert sein sollten.
920 Dann werden diese Werte benutzt, um die @code{box-padding}-Eigenschaft
921 zu verändert, die von beiden @code{\box}-Befehlen benutzt wird. Beachten
922 Sie Akzent und das Komma des @code{\override}-Arguments: hiermit kann man
923 einen Variablenwert in einen wörtlichen Ausdruck überführen.
925 Jetzt kann der Befehl in Beschriftungen benutzt werden und der Abstand
926 der Kästen kann angepasst werden:
928 @lilypond[quote,verbatim,ragged-right]
929 #(define-markup-command (double-box layout props text) (markup?)
930 #:properties ((inter-box-padding 0.4)
932 "Draw a double box around text."
933 (interpret-markup layout props
934 #{\markup \override #`(box-padding . ,inter-box-padding) \box
935 \override #`(box-padding . ,box-padding) \box
938 \markup \double-box A
939 \markup \override #'(inter-box-padding . 0.8) \double-box A
940 \markup \override #'(box-padding . 1.0) \double-box A
943 @node Eingebaute Befehle anpassen
944 @unnumberedsubsubsec Eingebaute Befehle anpassen
945 @translationof Adapting builtin commands
947 Ein guter Weg, einen neuen Beschriftungsbefehl zu schreiben, ist es, als Vorbild
948 einen existierenden zu nehmen. Die meisten Beschriftungsbefehle, die
949 LilyPond mitbringt, finden sich in der Datei
950 @file{scm/define-markup-commands.scm}.
952 Man könnte beispielsweise den Befehl @code{\draw-line}, der eine Linie
953 zeichnet, anpassen, sodass er eine Doppellinie zeichnet. Der
954 Befehl @code{\draw-line} ist wie folgend definiert (Dokumentation entfernt):
957 (define-markup-command (draw-line layout props dest)
960 #:properties ((thickness 1))
962 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
966 (make-line-stencil th 0 0 x y)))
969 Um einen neuen Befehl, der auf einem existierenden basiert, zu definieren,
970 wird die Befehlsdefinition kopiert und die Bezeichnung des Befehls
971 geändert. Das @code{#:category}-Schlagwort kann entfernt werden,
972 weil es nur zur Erstellung der LilyPond-Dokumentation eingesetzt wird
973 und keine Bedeutung für selbstdefinierte Befehle hat.
976 (define-markup-command (draw-double-line layout props dest)
978 #:properties ((thickness 1))
980 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
984 (make-line-stencil th 0 0 x y)))
987 Dann braucht man eine Eigenschaft, um den Abstand zwischen den zwei
988 Linien zu definieren, als @code{line-gap} bezeichnet und etwa mit
989 dem Standardwert 0.6:
992 (define-markup-command (draw-double-line layout props dest)
994 #:properties ((thickness 1)
1000 Schließlich wird der Code, der die zwei Linien zeichnet, hinzugefügt.
1001 Zwei Aufrufe an @code{make-line-stencil} werden benutzt, um beide Linien
1002 zu zeichnen, und die beiden sich daraus ergebenden Stencils werden mit
1003 @code{ly:stencil-add} kombiniert:
1005 @lilypond[quote,verbatim,ragged-right]
1006 #(define-markup-command (my-draw-line layout props dest)
1008 #:properties ((thickness 1)
1011 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1015 (w (/ line-gap 2.0))
1016 (x (cond ((= dx 0) w)
1018 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1019 (y (* (if (< (* dx dy) 0) 1 -1)
1022 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1023 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1024 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1026 \markup \my-draw-line #'(4 . 3)
1027 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1032 @node Neue Definitionen von Beschriftungslistenbefehlen
1033 @subsection Neue Definitionen von Beschriftungslistenbefehlen
1034 @translationof New markup list command definition
1036 Beschriftungslistenbefehle können mit dem Scheme-Makro
1037 @code{define-markup-list-command} definiert werden, welches
1038 sich ähnlich verhält wie das
1039 @code{define-markup-command}-Makro, das schon beschrieben
1040 wurde in @ref{Neue Definitionen von Beschriftungsbefehlen}. Ein Unterschied
1041 ist, dass bei diesem Listen-Makro eine ganze Liste an
1042 Stencils ausgegeben wird.
1044 Im folgenden Beispiel wird ein @code{\paragraph}-Beschriftungslistenbefehl
1045 definiert, welcher eine Liste von Zeilen im Blocksatz ausgibt, von
1046 denen die erste Zeile eingerückt ist. Der Einzug wird aus dem
1047 @code{props}-Argument entnommen.
1050 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1051 #:properties ((par-indent 2))
1052 (interpret-markup-list layout props
1053 #@{\markuplist \justified-lines @{ \hspace #par-indent #args @} #@}))
1056 Die Version nur in Scheme ist etwas komplexer:
1059 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1060 #:properties ((par-indent 2))
1061 (interpret-markup-list layout props
1062 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1066 Neben den üblichen @code{layout} und @code{props}-Argumenten nimmt der
1067 @code{paragraph}-Beschriftungslistenbefehl als Argument eine Beschriftungsliste,
1068 die @code{args} genannt wird. Das Prädikat für Beschriftungslisten ist
1069 @code{markup-list?}.
1071 Zuerst errechnet die Funktion die Breite des Einzugs, eine Eigenschaft
1072 mit der Bezeichnung @code{par-indent} anhand der Eigenschaftsliste
1073 @code{props}. Wenn die Eigenschaft nicht gefunden wird, ist der
1074 Standardwert @code{2}. Danach wird eine Liste von Zeilen im Blocksatz
1075 erstellt, wobei der eingebaute @code{\justified-lines}-Beschriftungslistenbefehl
1076 eingesetzt wird, der verwandt ist mit der
1077 @code{make-justified-lines-markup-list}-Funktion. Horizontaler
1078 Platz wird zu Beginn eingefügt mit @code{\hspace} (oder der
1079 @code{make-hspace-markup}-Funktion). Zuletzt wird die Beschriftungsliste
1080 ausgewertet durch die @code{interpret-markup-list}-Funktion.
1082 Dieser neue Beschriftungslistenbefehl kann wie folgt benutzt werden:
1087 Die Kunst des Notensatzes wird auch als \italic @{Notenstich@} bezeichnet. Dieser
1088 Begriff stammt aus dem traditionellen Notendruck. Noch bis vor etwa
1089 20 Jahren wurden Noten erstellt, indem man sie in eine Zink- oder
1090 Zinnplatte schnitt oder mit Stempeln schlug.
1092 \override-lines #'(par-indent . 4) \paragraph @{
1093 Diese Platte wurde dann mit Druckerschwärze versehen, so dass sie
1094 in den geschnittenen und gestempelten Vertiefungen blieb. Diese
1095 Vertiefungen schwärzten dann ein auf die Platte gelegtes Papier.
1096 Das Gravieren wurde vollständig von Hand erledigt.
1102 @node Kontexte für Programmierer
1103 @section Kontexte für Programmierer
1104 @translationof Contexts for programmers
1107 * Kontextauswertung::
1108 * Eine Funktion auf alle Layout-Objekte anwenden::
1111 @node Kontextauswertung
1112 @subsection Kontextauswertung
1113 @translationof Context evaluation
1115 @cindex Aufrufen von Code während der Interpretation
1116 @cindex On-the-fly Code ausführen
1118 @funindex \applyContext
1120 Kontexte können während ihrer Interpretation mit Scheme-Code
1121 modifiziert werden. Die Syntax hierfür ist
1124 \applyContext @var{function}
1127 @var{function} sollte eine Scheme-Funktion sein, die ein
1128 einziges Argument braucht, welches der Kontext ist, auf den
1129 sie ausgeführt werden soll. Der folgende Code schreibt
1130 die aktuelle Taktzahl in die Standardausgabe
1131 während der Kompilation.
1136 (format #t "\nWe were called in barnumber ~a.\n"
1137 (ly:context-property x 'currentBarNumber)))
1142 @node Eine Funktion auf alle Layout-Objekte anwenden
1143 @subsection Eine Funktion auf alle Layout-Objekte anwenden
1144 @translationof Running a function on all layout objects
1147 @cindex Aufruf von Code für Layoutobjekte
1149 @funindex \applyOutput
1151 Der vielfältigste Weg, ein Objekt zu beeinflussen, ist
1152 @code{\applyOutput}. Das funktioniert, indem ein musikalisches
1153 Ereignis in den angegebenen Kontext eingefügt wird
1154 (@rinternals{ApplyOutputEvent}). Die Syntax lautet:
1157 \applyOutput @var{Kontext} @var{proc}
1161 wobei @var{proc} eine Scheme-Funktion ist, die drei Argumente
1164 Während der Interpretation wird die Funktion @code{@var{proc}} für
1165 jedes Layoutobjekt aufgerufen, dass im Kontext @code{@var{Kontext}}
1166 vorgefunden wird, und zwar mit folgenden Argumenten:
1169 @item dem Layoutobjekt
1170 @item dem Kontext, in dem das Objekt erstellt wurde
1171 @item dem Kontext, in welchem @code{\applyOutput} bearbeitet wird.
1174 Zusätzlich findet sich der Grund für das Layoutobjekt, etwa
1175 der musikalische Ausdruck oder das Objekt, das für seine Erstellung
1176 verantwortlich war, in der Objekteigenschaft @code{cause}.
1177 Für einen Notenkopf beispielsweise ist das ein
1178 @rinternals{NoteHead}-Ereignis, und für einen Notenhals ist es
1179 ein @rinternals{Stem}-Objekt.
1181 Hier ist eine Funktion, die mit @code{\applyOutput} benutzt
1182 werden kann; sie macht Notenköpfe auf und neben der Mittellinie unsichtbar:
1184 @lilypond[quote,verbatim,ragged-right]
1185 #(define (blanker grob grob-origin context)
1186 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1187 (< (abs (ly:grob-property grob 'staff-position)) 2))
1188 (set! (ly:grob-property grob 'transparent) #t)))
1191 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1196 @node Callback-Funktionen
1197 @section Callback-Funktionen
1198 @translationof Callback functions
1200 Eigenschaften (wie Dicke (@code{thickness}), Richtung (@code{direction})
1201 usw.) können mit @code{\override} auf feste Werte gesetzt werden, etwa:
1204 \override Stem.thickness = #2.0
1207 Eigenschaften können auch auf eine Scheme-Prozedur gesetzt werden:
1209 @lilypond[fragment,verbatim,quote,relative=2]
1210 \override Stem.thickness = #(lambda (grob)
1211 (if (= UP (ly:grob-property grob 'direction))
1218 In diesem Fall wird die Prozedur ausgeführt, sobald der Wert der
1219 Eigenschaft während das Formatierungsprozesses angefordert wird.
1221 Der größte Teil der Satzmaschinierie funktioniert mit derartigen
1222 Callbacks. Eigenschaften, die üblicherweise Callbacks
1223 benutzen, sind u. A.:
1227 Die Druckfunktion, die eine Ausgabe des Symbols hervorruft
1229 Die Funktion, die die horizontale Position setzt
1231 Die Funktion, die die Breite eines Objekts errechnet
1234 Die Funktionen brauchen immer ein einziges Argument, das der
1237 Wenn Funktionen mit mehreren Argumenten aufgerufen werden müssen,
1238 kann der aktuelle Grob mit einer Grob-Einschließung
1239 eingefügt werden. Hier eine Einstellung aus
1240 @code{AccidentalSuggestion}:
1244 ,(ly:make-simple-closure
1246 ,(ly:make-simple-closure
1247 (list ly:self-alignment-interface::centered-on-x-parent))
1248 ,(ly:make-simple-closure
1249 (list ly:self-alignment-interface::x-aligned-on-self)))))
1253 In diesem Beispiel werden sowohl @code{ly:self-alignment-interface::x-aligned-on-self}
1254 als auch @code{ly:self-alignment-interface::centered-on-x-parent}
1255 mit dem Grob als Argument aufgerufen. Die Resultate werden mit der
1256 @code{+}-Funktion addiert. Um sicherzugehen, dass die Addition
1257 richtig ausgeführt wird, wird das ganze Konstrukt in
1258 @code{ly:make-simple-closure} eingeschlossen.
1260 In der Tat ist die Benutzung einer einzelnen Funktion als
1261 Eigenschaftswert äquivalent zu
1264 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1268 Das innere @code{ly:make-simple-closure} stellt den Grob als Argument
1269 für @var{proc} zur Verfügung, das äußere stellt sicher, dass das
1270 Resultat der Funktion ausgegeben wird und nicht das
1271 @code{simple-closure}-Objekt.
1273 Aus dem Callback heraus kann man eine Beschriftung am einfachsten mit
1274 @code{grob-interpret-markup} auswerten. Beispielsweise:
1277 mein-callback = #(lambda (grob)
1278 (grob-interpret-markup grob (markup "foo")))
1282 @node Scheme-Code innerhalb LilyPonds
1283 @section Scheme-Code innerhalb LilyPonds
1284 @translationof Inline Scheme code
1286 TODO: das Beispiel für diesen Abschnitt ist nicht gut gewähtl:
1289 F = -\tweak font-size #-3 -\flageolet
1291 (beachte @samp{-}, was ein Nachereignis anzeigt) funktioniert
1292 für den geschilderten Zweck sehr gut. Aber bis der Abschnitt
1293 neu geschrieben wird, nehmen wir einfach an, dass wir das nicht
1296 Der hauptsächliche Nachteil von @code{\tweak} ist seine
1297 syntaktische Inflexibilität. Folgender Code beispielsweise
1298 ergibt einen Syntaxfehler:
1301 F = \tweak font-size #-3 -\flageolet
1309 Durch die Verwendung von Scheme kann dieses Problem umgangen werden.
1310 Der Weg zum Resultat wird gezeigt in
1311 @ref{Artikulationszeichen zu Noten hinzufügen (Beispiel)}, insbesondere
1312 wie @code{\displayMusic} benutzt wird, hilft hier weiter.
1315 F = #(let ((m (make-music 'ArticulationEvent
1316 'articulation-type "flageolet")))
1317 (set! (ly:music-property m 'tweaks)
1318 (acons 'font-size -3
1319 (ly:music-property m 'tweaks)))
1328 In diesem Beispiel werden die @code{tweaks}-Eigenschaften
1329 des Flageolet-Objekts @code{m} (mit @code{make-music} erstellt)
1330 werden mit @code{ly:music-property} ausgelesen, ein neues
1331 Schlüssel-Wert-Paar, um die Schriftgröße zu ändern, wird
1332 der Eigenschaftenliste mithilfe der @code{acons}-Schemefunktion
1333 vorangestellt, und das Resultat wird schließlich mit
1334 @code{set!} zurückgeschrieben. Das letzte Element des
1335 @code{let}-Blocks ist der Wiedergabewert, @code{m}.
1339 @node Schwierige Korrekturen
1340 @section Schwierige Korrekturen
1341 @translationof Difficult tweaks
1343 Hier finden sich einige Klassen an schwierigeren Anpassungen.
1348 Ein Typ der schwierigen Anpassungen ist die Erscheinung von
1349 Strecker-Objekten wie Binde- oder Legatobögen. Zunächst wird
1350 nur eins dieser Objekte erstellt, und sie können mit dem
1351 normalen Mechanismus verändert werden. In einigen Fällen
1352 reichen die Strecker jedoch über Zeilenumbrüche. Wenn das
1353 geschieht, werden diese Objekte geklont. Ein eigenes
1354 Objekt wird für jedes System erstellt, in dem es sich befindet.
1355 Sie sind Klone des originalen Objektes und erben alle
1356 Eigenschaften, auch @code{\override}-Befehle.
1358 Anders gesagt wirkt sich ein @code{\override} immer auf alle
1359 Stücke eines geteilten Streckers aus. Um nur einen Teil eines
1360 Streckers bei einem Zeilenumbruch zu verändern, ist es notwendig,
1361 in den Formatierungsprozess einzugreifen. Das Callback
1362 @code{after-line-breaking} enthält die Schemefunktion, die
1363 aufgerufen wird, nachdem Zeilenumbrüche errechnet worden sind
1364 und die Layout-Objekte über die unterschiedlichen Systeme verteilt
1367 Im folgenden Beispiel wird die Funktion
1368 @code{my-callback} definiert. Diese Funktion
1372 bestimmt, ob das Objekt durch Zeilenumbrüche geteilt ist,
1374 wenn ja, ruft sie alle geteilten Objekte auf,
1376 testet, ob es sich um das letzte der geteilten Objekte handelt,
1378 wenn ja, wird @code{extra-offset} gesetzt.
1381 Diese Funktion muss in @rinternals{Tie} (Bindebogen) installiert
1382 werden, damit der letzte Teil eines gebrochenen Bindebogens
1383 neu ausgerichtet wird.
1385 @lilypond[quote,verbatim,ragged-right]
1386 #(define (my-callback grob)
1388 ; have we been split?
1389 (orig (ly:grob-original grob))
1391 ; if yes, get the split pieces (our siblings)
1392 (siblings (if (ly:grob? orig)
1393 (ly:spanner-broken-into orig) '() )))
1395 (if (and (>= (length siblings) 2)
1396 (eq? (car (last-pair siblings)) grob))
1397 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1400 \override Tie.after-line-breaking =
1407 Wenn man diesen Trick anwendet, sollte das neue @code{after-line-breaking}
1408 auch das alte @code{after-line-breaking}-Callback aufrufen,
1409 wenn es vorhanden ist. Wenn diese Funktion etwa mit
1410 @code{Hairpin} (Crescendo-Klammer) eingesetzt wird, sollte auch
1411 @code{ly:spanner::kill-zero-spanned-time} aufgerufen werden.
1415 Manche Objekte können aus technischen Gründen nicht mit @code{\override}
1416 verändert werden. Beispiele hiervon sind @code{NonMusicalPaperColumn}
1417 und @code{PaperColumn}. Sie können mit der
1418 @code{\overrideProperty}-Funktion geändert werden, die ähnlich wie
1419 @code{\once \override} funktioniert, aber eine andere Syntax einsetzt.
1423 Score.NonMusicalPaperColumn % Grob-Bezeichnung
1424 #'line-break-system-details % Eigenschaftsbezeichnung
1425 #'((next-padding . 20)) % Wert
1428 Es sollte angemerkt werden, dass @code{\override}, wenn man es auf
1429 @code{NonMusicalPaperColumn} und @code{PaperColumn} anwendet, immer noch
1430 innerhalb der @code{\context}-Umgebung funktioniert.
1436 @node LilyPond Scheme-Schnittstellen
1437 @chapter LilyPond Scheme-Schnittstellen
1438 @translationof LilyPond Scheme interfaces
1440 Dieses Kapitel behandelt die verschiedenen Werkzeuge, die LilyPond als
1441 Hilfe für Scheme-Programmierer zur Verfügung stellt, um Information in
1442 den Musik-Stream zu senden und aus ihm herauszubekommen.
1444 TODO: was gehört hier eigentlich hin?