1 @c -*- coding: utf-8; mode: texinfo; -*-
4 Translation of GIT committish: a463d80d4be008ce05b12de86fc21f2b7c1c120f
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 * Musikalische Funktionen::
26 * Textbeschriftungsfunktionen::
27 * Kontexte für Programmierer::
28 * Callback-Funktionen::
29 * Scheme-Code innerhalb LilyPonds::
30 * Schwierige Korrekturen::
34 @node Musikalische Funktionen
35 @section Musikalische Funktionen
36 @translationof Music functions
38 Dieser Abschnitt behandelt die Erstellung von musikalischen Funktionen
39 innerhalb von LilyPond. @emph{Musikalische Funktionen} sind Scheme-Prozeduren,
40 die musikalische Ausdrücke automatisch erstellen können und dadurch die
41 Eingabedatei maßgeblich vereinfachen können.
44 * Syntax der musikalischen Funktionen::
45 * Einfache Ersetzungsfunktionen::
46 * Mittlere Ersetzungsfunktionen::
47 * Mathematik in Funktionen::
48 * Funktionen ohne Argumente::
52 @node Syntax der musikalischen Funktionen
53 @subsection Syntax der musikalischen Funktionen
54 @translationof Music function syntax
56 Die allgemeine Form von musikalischen Funktionen ist:
60 #(define-music-function
61 (parser location @var{Arg1} @var{Arg2} @dots{})
62 (@var{Typ1?} @var{Typ2?} @dots{})
69 @multitable @columnfractions .33 .66
71 @tab das @var{n}te Argument
74 @tab ein Scheme-Typenprädikat (engl. type predicate), für welches
75 @code{@var{ArgN}} @code{#t} ausgeben muss
77 @item @var{...Noten...}
78 @tab ein musikalischer Ausdruck, optional in Scheme geschrieben, mit allem
79 LilyPond-Code in Raute/geschweifte Klammer eingeschlossen
80 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}). Innerhalb der LilyPond-Codeumgebungen
81 wird @code{$} eingesetzt, um auf Funktionsargumente zu verweisen (etwa
82 @samp{$Arg1}), oder ein neuer Scheme-Ausdruck muss begonnen werden,
83 der die Funktionsargumente enthält (etwa @w{@samp{$(cons Arg1 Arg2)}}).
87 Eine Liste der möglichen Typenprädikate findet sich in
88 @ruser{Vordefinierte Typenprädikate}. Durch den Benutzer definierte
89 Typenprädikate sind auch erlaubt.
94 @ruser{Vordefinierte Typenprädikate}.
97 @file{lily/music-scheme.cc},
102 @node Einfache Ersetzungsfunktionen
103 @subsection Einfache Ersetzungsfunktionen
104 @translationof Simple substitution functions
106 Einfache Ersetzungsfunktionen sind musikalische Funktionen, deren
107 musikalische Ausgabe-Funktion im LilyPond-Format geschrieben ist
108 und Funktionsargumente in der Ausgabefunktion enthält. Sie werden
109 beschrieben in @ruser{Beispiele der Ersetzungsfunktionen}
112 @node Mittlere Ersetzungsfunktionen
113 @subsection Mittlere Ersetzungsfunktionen
114 @translationof Intermediate substitution functions
116 Mittlere Ersetzungsfunktionen setzen sich aus einer Mischung von
117 Scheme-Code und LilyPond-Code in der musikalischen Ausgabe-Funktion
120 Einige @code{\override}-Befehle benötigen ein Zahlenpaar
121 (als @code{cons}-Zelle in Scheme bezeichnet).
123 Das Paar kann direkt an die musikalische Funktion
124 mit der Variable @code{pair?} weitergeleitet werden:
128 #(define-music-function
129 (parser location beg-end)
132 \once \override Beam #'positions = $beg-end
136 \manualBeam #'(3 . 6) c8 d e f
140 Anstelle dessen können auch die Zahlen, aus denen das Paar besteht,
141 einzeln als eigenständige Argumente weitergeleitet und der
142 Scheme-Code, der das Paar erstellt, in die musikalische Funktion
145 @lilypond[quote,verbatim,ragged-right]
147 #(define-music-function
148 (parser location beg end)
151 \once \override Beam #'positions = $(cons beg end)
155 \manualBeam #3 #6 c8 d e f
160 @node Mathematik in Funktionen
161 @subsection Mathematik in Funktionen
162 @translationof Mathematics in functions
164 Musikalische Funktionen können neben einfachen Ersetzungen
165 auch Scheme-Programmcode enthalten:
167 @lilypond[quote,verbatim,ragged-right]
169 #(define-music-function
170 (parser location mag)
173 \override Stem #'length = $(* 7.0 mag)
174 \override NoteHead #'font-size =
175 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
179 \revert Stem #'length
180 \revert NoteHead #'font-size
185 \AltOn #1.5 c c \AltOff c2
190 Dieses Beispiel kann auch umformuliert werden, um musikalische Ausdrücke
193 @lilypond[quote,verbatim,ragged-right]
195 #(define-music-function
196 (parser location mag music)
199 \override Stem #'length = $(* 7.0 mag)
200 \override NoteHead #'font-size =
201 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
203 \revert Stem #'length
204 \revert NoteHead #'font-size
208 c2 \withAlt #0.5 { c4 c }
209 \withAlt #1.5 { c c } c2
214 @node Funktionen ohne Argumente
215 @subsection Funktionen ohne Argumente
216 @translationof Functions without arguments
218 In den meisten Fällen sollten Funktionen ohne Argumente mit einer
219 Variable notiert werden:
222 dolce = \markup@{ \italic \bold dolce @}
225 In einigen wenigen Fällen kann es aber auch sinnvoll sein, eine
226 musikalische Funktion ohne Argumente zu erstellen:
230 #(define-music-function
233 (if (eq? #t (ly:get-option 'display-bar-numbers))
234 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
238 Damit auch wirklich Taktzahlen angezeigt werden, wo die
239 Funktion eingesetzt wurde, muss @command{lilypond} mit
243 lilypond -d display-bar-numbers Dateiname.ly
251 @node Leere Funktionen
252 @subsection Leere Funktionen
253 @translationof Void functions
255 Eine musikalische Funktion muss einen musikalischen Ausdruck
256 ausgeben, aber in manchen Fällen müssen Funktionen erstellt werden,
257 die keine Noten enthalten (wie etwa eine Funktion, mit der
258 man @qq{Point and Click} ausschalten kann). Um das vornehmen zu
259 können, wird ein @code{leere}r musikalischer Ausdruck ausgegeben.
261 Das ist der Grund, warum die Form, die ausgegeben wird,
262 @w{@code{(make-music @dots{})}} heißt. Wird die Eigenschaft
263 @code{'void} (engl. für @qq{leer}) auf @code{#t} gesetzt, wird der
264 Parser angewiesen, den ausgegebenen musikalischen Ausdruck zu ignorieren.
265 Der maßgebliche Teil der @code{'void}-Funktion ist also die Verarbeitung,
266 die die Funktion vornimmt, nicht der musikalische Ausdruck, der ausgegeben
271 #(define-music-function
274 (ly:set-option 'point-and-click #f)
275 (make-music 'SequentialMusic 'void #t))
277 \noPointAndClick % Point and Click ausschalten
282 @node Textbeschriftungsfunktionen
283 @section Textbeschriftungsfunktionen
284 @translationof Markup functions
286 Textbeschriftungselemente sind als besondere Scheme-Funktionen
287 definiert, die ein @code{Stencil}-Objekt erstellen, dem eine Anzahl
288 an Argumenten übergeben wird.
291 * Beschriftungskonstruktionen in Scheme::
292 * Wie Beschriftungen intern funktionieren::
293 * Neue Definitionen von Beschriftungsbefehlen::
294 * Neue Definitionen von Beschriftungslistenbefehlen::
298 @node Beschriftungskonstruktionen in Scheme
299 @subsection Beschriftungskonstruktionen in Scheme
300 @translationof Markup construction in Scheme
302 @cindex Textbeschriftungsbefehle, definieren
303 @cindex Textbeschriftung, eigene Befehle
304 @cindex eigene Befehle, Textbeschriftung
305 @cindex markup, eigene Befehle
306 @cindex Befehle definieren, Textbeschriftung
308 Das @code{markup}-(Textbeschriftungs)Makro erstellt Textbeschriftungs-Ausdrücke
309 in Scheme, wobei eine LilyPond-artige Syntax benutzt wird. Beispielsweise
313 (markup #:column (#:line (#:bold #:italic "hello" #:raise 0.4 "world")
314 #:larger #:line ("foo" "bar" "baz")))
321 \markup \column @{ \line @{ \bold \italic "hello" \raise #0.4 "world" @}
322 \larger \line @{ foo bar baz @} @}
326 Dieses Beispiel zeigt die hauptsächlichen Übersetzungsregeln
327 zwischen normaler Textbeschriftungssyntax von LilyPond und der
328 Textbeschriftungssyntax in Scheme.
331 @multitable @columnfractions .3 .3
332 @item @b{LilyPond} @tab @b{Scheme}
333 @item @code{\markup Text1} @tab @code{(markup Text1)}
334 @item @code{\markup @{ Text1 Text2 ... @}} @tab
335 @code{(markup Text1 Text2 ... )}
336 @item @code{\Beschriftungsbefehl} @tab @code{#:Beschriftungsbefehl}
337 @item @code{\Variable} @tab @code{Variable}
338 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
339 @item @code{Zeichenkette} @tab @code{"Zeichenkette"}
340 @item @code{#scheme-Arg} @tab @code{scheme-Arg}
344 Die gesamte Scheme-Sprache ist innerhalb des @code{markup}-Makros
345 zugänglich. Man kann also beispielsweise Funktionen innerhalb
346 eines @code{markup} aufrufen, um Zeichenketten zu manipulieren.
347 Das ist nützlich, wenn neue Beschriftungsbefehle definiert werden
349 @ref{Neue Definitionen von Beschriftungsbefehlen}).
354 Das Beschriftungslistenargument von Befehlen wie @code{#:line},
355 @code{#:center} und @code{#:column} kann keine Variable oder
356 das Resultat eines Funktionsaufrufen sein.
359 (markup #:line (Funktion-die-Textbeschriftung-ausgibt))
363 ist ungültig. Man sollte anstatt dessen die Funktionen
364 @code{make-line-markup}, @code{make-center-markup} oder
365 @code{make-column-markup} benutzen:
368 (markup (make-line-markup (Funktion-die-Textbeschriftung-ausgibt)))
372 @node Wie Beschriftungen intern funktionieren
373 @subsection Wie Beschriftungen intern funktionieren
374 @translationof How markups work internally
376 In einer Textbeschriftung wie
379 \raise #0.5 "Textbeispiel"
383 ist @code{\raise} unter der Haube durch die @code{raise-markup}-Funktion
384 repräsentiert. Der Beschriftungsausdruck wird gespeichert als
387 (list raise-markup 0.5 (list simple-markup "Textbeispiel"))
390 Wenn die Beschriftung in druckbare Objekte (Stencils) umgewandelt ist,
391 wir die @code{raise-markup}-Funktion folgendermaßen aufgerufen:
396 @var{Liste der Eigenschafts-alists}
398 @var{die "Textbeispiel"-Beschriftung})
401 Die @code{raise-markup}-Funktion erstellt zunächst den Stencil für die
402 @code{Textbeispiel}-Beschriftung und verschiebt dann diesen Stencil
403 um 0.5 Notenlinienzwischenräume nach oben. Das ist ein einfaches
404 Beispiel. Weitere, kompliziertere Beispiele finden sich nachfolgend
405 in diesem Abschnitt und in der Datei
406 @file{scm/define-markup-commands.scm}.
409 @node Neue Definitionen von Beschriftungsbefehlen
410 @subsection Neue Definitionen von Beschriftungsbefehlen
411 @translationof New markup command definition
413 Dieser Abschnitt behandelt die Definition von neuen Textbeschriftungsbefehlen.
416 * Syntax der Definition von Textbeschriftungsbefehlen::
417 * Über Eigenschaften::
418 * Ein vollständiges Bespiel::
419 * Eingebaute Befehle anpassen::
422 @node Syntax der Definition von Textbeschriftungsbefehlen
423 @unnumberedsubsubsec Syntax der Definition von Textbeschriftungsbefehlen
424 @translationof Markup command definition syntax
426 Neue Textbeschriftungsbefehle können mit dem
427 @code{define-markup-command}-Scheme-Makro definiert werden.
430 (define-markup-command (@var{befehl-bezeichnung} @var{layout} @var{props} @var{Arg1} @var{Arg2} ...)
431 (@var{Arg1-typ?} @var{Arg2-typ?} ...)
432 [ #:properties ((@var{Eigenschaft1} @var{Standard-Wert1})
440 @item @var{befehl-bezeichnung}
441 die Bezeichnung des Befehls
444 die @q{layout}-Definition
447 eine Liste an assoziativen Listen, in der alle aktiven Eigenschaften enthalten sind
450 das @var{i}te Befehlsargument
452 @item @var{argi-type?}
453 eine Eigenschaft für das @var{i}te Argument
456 Wenn der Befehl Eigenschaften des @code{props}-Arguments benutzt,
457 kann das @code{#:properties}-Schlüsselwort benutzt werden um zu
458 bestimmen, welche Eigenschaften mit welchen Standard-Werten benutzt
461 Argumente werden nach ihrem Typ unterschieden:
464 @item eine Textbeschriftung entspricht einem Typenprädikat @code{markup?};
465 @item eine Textbeschriftungsliste entspricht einem Typenprädikat
467 @item jedes andere Scheme-Objekt entspricht Typenprädikaten wie etwa
468 @code{list?}, @code{number?}, @code{boolean?}, usw.
471 Es gibt keine Einschränkung in der Reihenfolge der Argumente (nach
472 den Standard-Argumenten @code{layout} und @code{props}). Textbeschriftungsfunktionen,
473 die als letztes Argument eine Textbeschriftung haben, haben die
474 Besonderheit, dass sie auf Textbeschriftungslisten angewendet werden
475 können, und das Resultat ist eine Textbeschriftungsliste, in der
476 die Textbeschriftungsfuktion (mit den angegebenen Argumenten am Anfang)
477 auf jedes Element der originalen Textbeschriftungsliste angewendet
480 Da das Wiederholen der Argumente am Anfang bei der Anwendung einer
481 Textbeschriftungsfunktion auf eine Textbeschriftungsliste for allem
482 für Scheme-Argumente sparsam ist, kann man Leistungseinbußen vermeiden,
483 indem man nur Scheme-Argumente für die Argumente am Anfang einsetzt,
484 wenn es sich um Textbeschriftungsfunktionen handelt, die eine Textbeschriftung
485 als letztes Argument haben.
488 @node Über Eigenschaften
489 @unnumberedsubsubsec Über Eigenschaften
490 @translationof On properties
492 Die @code{layout}- und @code{props}-Argumente der Textbeschriftungsbefehle
493 bringen einen Kontext für die Interpretation der Beschriftung:
494 Schriftgröße, Zeilenlänge usw.
496 Das @code{layout}-Argument greift auf Eigenschaften zu, die in der
497 @code{paper}-Umgebung definiert werden, indem man die @code{ly:output-def-lookup}-Funktion
498 benutzt. Beispielsweise liest man die Zeilenlänge (die gleiche, die auch in
499 Partituren benutzt wird) aus mit:
502 (ly:output-def-lookup layout 'line-width)
505 Das @code{props}-Argument stellt einige Eigenschaften für die Textbeschriftungsbefehle
506 zur Verfügung. Beispielsweise wenn der Überschrifttext einer
507 @code{book}-Umgebung interpretiert wird, werden alle Variablen, die
508 in der @code{\header}-Umgebung definiert werden, automatisch zu @code{props}
509 hinzugefügt, sodass die Beschriftung auf Titel, Komponist usw. der
510 @code{book}-Umgebung zugreifen kann. Das ist auch eine Möglichkeit, das
511 Verhalten eines Beschriftungsbefehls zu konfigurieren: Wenn etwa ein
512 Befehl die Schriftgröße während der Verarbeitung einsetzt, wird die
513 Schriftgröße aus den @code{props} ausgelesen und nicht mit einem eigenen
514 @code{font-size}-Argument definiert. Beim Aufruf des Beschriftungsbefehls
515 kann der Wert der Schriftgröße geändert werden, womit sich auch das Verhalten
516 des Befehls verändert. Benutzen Sie das @code{#:properties}-Schlüsselwort
517 von @code{define-markup-command} um zu definieren, welche Eigenschaften aus den
518 @code{props}-Argumenten ausgelesen werden sollen.
520 Das Beispiel im nächsten Abschnitt illustriert, wie man auf Eigenschaften
521 in einem Beschriftungsbefehl zugreifen und sie verändern kann.
524 @node Ein vollständiges Bespiel
525 @unnumberedsubsubsec Ein vollständiges Bespiel
526 @translationof A complete example
528 Das folgende Beispiel definiert einen Beschriftungsbefehl, der einen
529 doppelten Kasten um einen Text zeichnet.
531 Zuerst wollen wir ein annäherndes Ergebnis mit Textbeschriftungen definieren.
532 Nach Stöbern in @ruser{Textbeschriftungsbefehle} finden wir den Befehl
535 @lilypond[quote,verbatim,ragged-right]
536 \markup \box \box HELLO
539 Wir wollen aber etwas mehr Abstand (engl. padding) zwischen dem Text und dem Kasten.
540 Nach der Dokumentation von @code{\box} hat der Befehl eine
541 @code{box-padding}-Eigenschaft, die den Standardwert von 0.2 hat. Die
542 Dokumentation zeit auch, wir man den Wert verändert:
544 @lilypond[quote,verbatim,ragged-right]
545 \markup \box \override #'(box-padding . 0.6) \box A
548 Auch der Abstand zwischen den zwei Kästen ist uns zu klein und soll auch
551 @lilypond[quote,verbatim,ragged-right]
552 \markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
555 Diese lange Textbeschriftung immer wieder schreiben zu müssen, ist
556 anstrengend. Hier kömmt ein Textbeschriftungsbefehl ins Spiel. Wir
557 schreiben uns alle einen @code{double-box}-Beschriftungsbefehl, der
558 ein Argument annimmt (den Text). Er zeichnet zwei Kästen mit genügend Abstand:
561 #(define-markup-command (double-box layout props text) (markup?)
562 "Draw a double box around text."
563 (interpret-markup layout props
564 (markup #:override '(box-padding . 0.4) #:box
565 #:override '(box-padding . 0.6) #:box text)))
568 @code{text} ist die Bezeichnung des Arguments dieses Befehls,
569 und @code{markup?} ist seine Art: hiermit wird der Befehl als
570 Beschriftungsbefehl identifiziert. Die @code{interpret-markup}-Funktion
571 wird in den meisten Beschriftungsbefehlen benutzt: sie erstellt einen
572 Stencil, wobei @code{layout}, @code{props} und eine Beschriftung benutzt
573 werden. In unserem Fall wird diese Beschriftung durch das
574 @code{markup}-Scheme-Makro erstellt, siehe auche @ref{Beschriftungskonstruktionen in Scheme}.
575 Die Transformation des @code{\markup}-Ausdrucks in einen
576 Scheme-Beschriftungsausdruck geschieht durch umschreiben des LilyPond-Codes
579 Der neue Befehl kann wie folgt benutzt werden:
582 \markup \double-box A
585 Es wäre schön, den @code{double-box}-Befehl noch konfigurierbar zu gestalten:
586 in unserem Fall sind die Werte von @code{box-padding} direkt definiert und
587 können nicht mehr vom Benutzer verändert werden. Es wäre auch besser, wenn
588 der Abstand zwischen den beiden Kästen vom Abstand zwischen dem inneren Kasten
589 und dem Text unterschieden werden könnte. Eine neue Eigenschaft muss also
590 definiert werden: @code{inter-box-padding} für den Abstand zwischen den Kästen.
591 @code{box-padding} wird für den inneren Abstand benutzt. Der neue Befehl wird
595 #(define-markup-command (double-box layout props text) (markup?)
596 #:properties ((inter-box-padding 0.4)
598 "Draw a double box around text."
599 (interpret-markup layout props
600 (markup #:override `(box-padding . ,inter-box-padding) #:box
601 #:override `(box-padding . ,box-padding) #:box text)))
604 In diesem Code wird das @code{#:properties}-Schlüsselwort benutzt, sodass
605 die Eigenschaften @code{inter-box-padding} und @code{box-padding} aus dem
606 @code{props}-Argument ausgelesen werden, und Standardwerte werden gegeben,
607 falls die Eigenschaften nicht definiert sein sollten.
609 Dann werden diese Werte benutzt, um die @code{box-padding}-Eigenschaft
610 zu verändert, die von beiden @code{\box}-Befehlen benutzt wird. Beachten
611 Sie Akzent und das Komma des @code{\override}-Arguments: hiermit kann man
612 einen Variablenwert in einen wörtlichen Ausdruck überführen.
614 Jetzt kann der Befehl in Beschriftungen benutzt werden und der Abstand
615 der Kästen kann angepasst werden:
617 @lilypond[quote,verbatim,ragged-right]
618 #(define-markup-command (double-box layout props text) (markup?)
619 #:properties ((inter-box-padding 0.4)
621 "Draw a double box around text."
622 (interpret-markup layout props
623 (markup #:override `(box-padding . ,inter-box-padding) #:box
624 #:override `(box-padding . ,box-padding) #:box text)))
626 \markup \double-box A
627 \markup \override #'(inter-box-padding . 0.8) \double-box A
628 \markup \override #'(box-padding . 1.0) \double-box A
631 @node Eingebaute Befehle anpassen
632 @unnumberedsubsubsec Eingebaute Befehle anpassen
633 @translationof Adapting builtin commands
635 Ein guter Weg, einen neuen Beschriftungsbefehl zu schreiben, ist es, als Vorbild
636 einen existierenden zu nehmen. Die meisten Beschriftungsbefehle, die
637 LilyPond mitbringt, finden sich in der Datei
638 @file{scm/define-markup-commands.scm}.
640 Man könnte beispielsweise den Befehl @code{\draw-line}, der eine Linie
641 zeichnet, anpassen, sodass er eine Doppellinie zeichnet. Der
642 Befehl @code{\draw-line} ist wie folgend definiert (Dokumentation entfernt):
645 (define-markup-command (draw-line layout props dest)
648 #:properties ((thickness 1))
650 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
654 (make-line-stencil th 0 0 x y)))
657 Um einen neuen Befehl, der auf einem existierenden basiert, zu definieren,
658 wird die Befehlsdefinition kopiert und die Bezeichnung des Befehls
659 geändert. Das @code{#:category}-Schlagwort kann entfernt werden,
660 weil es nur zur Erstellung der LilyPond-Dokumentation eingesetzt wird
661 und keine Bedeutung für selbstdefinierte Befehle hat.
664 (define-markup-command (draw-double-line layout props dest)
666 #:properties ((thickness 1))
668 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
672 (make-line-stencil th 0 0 x y)))
675 Dann braucht man eine Eigenschaft, um den Abstand zwischen den zwei
676 Linien zu definieren, als @code{line-gap} bezeichnet und etwa mit
677 dem Standardwert 0.6:
680 (define-markup-command (draw-double-line layout props dest)
682 #:properties ((thickness 1)
688 Schließlich wird der Code, der die zwei Linien zeichnet, hinzugefügt.
689 Zwei Aufrufe an @code{make-line-stencil} werden benutzt, um beide Linien
690 zu zeichnen, und die beiden sich daraus ergebenden Stencils werden mit
691 @code{ly:stencil-add} kombiniert:
693 @lilypond[quote,verbatim,ragged-right]
694 #(define-markup-command (my-draw-line layout props dest)
696 #:properties ((thickness 1)
699 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
704 (x (cond ((= dx 0) w)
706 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
707 (y (* (if (< (* dx dy) 0) 1 -1)
710 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
711 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
712 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
714 \markup \my-draw-line #'(4 . 3)
715 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
720 @node Neue Definitionen von Beschriftungslistenbefehlen
721 @subsection Neue Definitionen von Beschriftungslistenbefehlen
722 @translationof New markup list command definition
724 Beschriftungslistenbefehle können mit dem Scheme-Makro
725 @code{define-markup-list-command} definiert werden, welches
726 sich ähnlich verhält wie das
727 @code{define-markup-command}-Makro, das schon beschrieben
728 wurde in @ref{Neue Definitionen von Beschriftungsbefehlen}. Ein Unterschied
729 ist, dass bei diesem Listen-Makro eine ganze Liste an
730 Stencils ausgegeben wird.
732 Im folgenden Beispiel wird ein @code{\paragraph}-Beschriftungslistenbefehl
733 definiert, welcher eine Liste von Zeilen im Blocksatz ausgibt, von
734 denen die erste Zeile eingerückt ist. Der Einzug wird aus dem
735 @code{props}-Argument entnommen.
738 #(define-markup-list-command (paragraph layout props args) (markup-list?)
739 (let ((indent (chain-assoc-get 'par-indent props 2)))
740 (interpret-markup-list layout props
741 (make-justified-lines-markup-list (cons (make-hspace-markup indent)
745 Neben den üblichen @code{layout} und @code{props}-Argumenten nimmt der
746 @code{paragraph}-Beschriftungslistenbefehl als Argument eine Beschriftungsliste,
747 die @code{args} genannt wird. Das Prädikat für Beschriftungslisten ist
750 Zuerst errechnet die Funktion die Breite des Einzugs, eine Eigenschaft
751 mit der Bezeichnung @code{par-indent} anhand der Eigenschaftsliste
752 @code{props}. Wenn die Eigenschaft nicht gefunden wird, ist der
753 Standardwert @code{2}. Danach wird eine Liste von Zeilen im Blocksatz
754 erstellt, wobei die @code{make-justified-lines-markup-list}-Funktion
755 eingesetzt wird, die verwandt ist mit dem eingebauten
756 @code{\justified-lines}-Beschriftungslistenbefehl. Horizontaler
757 Platz wird zu Beginn eingefügt mit der @code{make-hspace-markup}-Funktion.
758 Zuletzt wird die Beschriftungsliste ausgewertet durch die
759 @code{interpret-markup-list}-Funktion.
761 Dieser neue Beschriftungslistenbefehl kann wie folgt benutzt werden:
766 Die Kunst des Notensatzes wird auch als \italic @{Notenstich@} bezeichnet. Dieser
767 Begriff stammt aus dem traditionellen Notendruck. Noch bis vor etwa
768 20 Jahren wurden Noten erstellt, indem man sie in eine Zink- oder
769 Zinnplatte schnitt oder mit Stempeln schlug.
771 \override-lines #'(par-indent . 4) \paragraph @{
772 Diese Platte wurde dann mit Druckerschwärze versehen, so dass sie
773 in den geschnittenen und gestempelten Vertiefungen blieb. Diese
774 Vertiefungen schwärzten dann ein auf die Platte gelegtes Papier.
775 Das Gravieren wurde vollständig von Hand erledigt.
782 @node Kontexte für Programmierer
783 @section Kontexte für Programmierer
784 @translationof Contexts for programmers
787 * Kontextauswertung::
788 * Eine Funktion auf alle Layout-Objekte anwenden::
791 @node Kontextauswertung
792 @subsection Kontextauswertung
793 @translationof Context evaluation
795 @cindex Aufrufen von Code während der Interpretation
796 @cindex On-the-fly Code ausführen
798 @funindex \applyContext
800 Kontexte können während ihrer Interpretation mit Scheme-Code
801 modifiziert werden. Die Syntax hierfür ist
804 \applyContext @var{function}
807 @var{function} sollte eine Scheme-Funktion sein, die ein
808 einziges Argument braucht, welches der Kontext ist, auf den
809 sie ausgeführt werden soll. Der folgende Code schreibt
810 die aktuelle Taktzahl in die Standardausgabe
811 während der Kompilation.
816 (format #t "\nWe were called in barnumber ~a.\n"
817 (ly:context-property x 'currentBarNumber)))
822 @node Eine Funktion auf alle Layout-Objekte anwenden
823 @subsection Eine Funktion auf alle Layout-Objekte anwenden
824 @translationof Running a function on all layout objects
827 @cindex Aufruf von Code für Layoutobjekte
829 @funindex \applyOutput
831 Der vielfältigste Weg, ein Objekt zu beeinflussen, ist
832 @code{\applyOutput}. Das funktioniert, indem ein musikalisches
833 Ereignis in den angegebenen Kontext eingefügt wird
834 (@rinternals{ApplyOutputEvent}). Die Syntax lautet:
837 \applyOutput @var{Kontext} @var{proc}
841 wobei @var{proc} eine Scheme-Funktion ist, die drei Argumente
844 Während der Interpretation wird die Funktion @code{@var{proc}} für
845 jedes Layoutobjekt aufgerufen, dass im Kontext @code{@var{Kontext}}
846 vorgefunden wird, und zwar mit folgenden Argumenten:
849 @item dem Layoutobjekt
850 @item dem Kontext, in dem das Objekt erstellt wurde
851 @item dem Kontext, in welchem @code{\applyOutput} bearbeitet wird.
854 Zusätzlich findet sich der Grund für das Layoutobjekt, etwa
855 der musikalische Ausdruck oder das Objekt, das für seine Erstellung
856 verantwortlich war, in der Objekteigenschaft @code{cause}.
857 Für einen Notenkopf beispielsweise ist das ein
858 @rinternals{NoteHead}-Ereignis, und für einen Notenhals ist es
859 ein @rinternals{Stem}-Objekt.
861 Hier ist eine Funktion, die mit @code{\applyOutput} benutzt
862 werden kann; sie macht Notenköpfe auf und neben der Mittellinie unsichtbar:
864 @lilypond[quote,verbatim,ragged-right]
865 #(define (blanker grob grob-origin context)
866 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
867 (< (abs (ly:grob-property grob 'staff-position)) 2))
868 (set! (ly:grob-property grob 'transparent) #t)))
871 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
876 @node Callback-Funktionen
877 @section Callback-Funktionen
878 @translationof Callback functions
880 Eigenschaften (wie Dicke (@code{thickness}), Richtung (@code{direction})
881 usw.) können mit @code{\override} auf feste Werte gesetzt werden, etwa:
884 \override Stem #'thickness = #2.0
887 Eigenschaften können auch auf eine Scheme-Prozedur gesetzt werden:
889 @lilypond[fragment,verbatim,quote,relative=2]
890 \override Stem #'thickness = #(lambda (grob)
891 (if (= UP (ly:grob-property grob 'direction))
898 In diesem Fall wird die Prozedur ausgeführt, sobald der Wert der
899 Eigenschaft während das Formatierungsprozesses angefordert wird.
901 Der größte Teil der Satzmaschinierie funktioniert mit derartigen
902 Callbacks. Eigenschaften, die üblicherweise Callbacks
903 benutzen, sind u. A.:
907 Die Druckfunktion, die eine Ausgabe des Symbols hervorruft
909 Die Funktion, die die horizontale Position setzt
911 Die Funktion, die die Breite eines Objekts errechnet
914 Die Funktionen brauchen immer ein einziges Argument, das der
917 Wenn Funktionen mit mehreren Argumenten aufgerufen werden müssen,
918 kann der aktuelle Grob mit einer Grob-Einschließung
919 eingefügt werden. Hier eine Einstellung aus
920 @code{AccidentalSuggestion}:
924 ,(ly:make-simple-closure
926 ,(ly:make-simple-closure
927 (list ly:self-alignment-interface::centered-on-x-parent))
928 ,(ly:make-simple-closure
929 (list ly:self-alignment-interface::x-aligned-on-self)))))
933 In diesem Beispiel werden sowohl @code{ly:self-alignment-interface::x-aligned-on-self}
934 als auch @code{ly:self-alignment-interface::centered-on-x-parent}
935 mit dem Grob als Argument aufgerufen. Die Resultate werden mit der
936 @code{+}-Funktion addiert. Um sicherzugehen, dass die Addition
937 richtig ausgeführt wird, wird das ganze Konstrukt in
938 @code{ly:make-simple-closure} eingeschlossen.
940 In der Tat ist die Benutzung einer einzelnen Funktion als
941 Eigenschaftswert äquivalent zu
944 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
948 Das innere @code{ly:make-simple-closure} stellt den Grob als Argument
949 für @var{proc} zur Verfügung, das äußere stellt sicher, dass das
950 Resultat der Funktion ausgegeben wird und nicht das
951 @code{simple-closure}-Objekt.
953 Aus dem Callback heraus kann man eine Beschriftung am einfachsten mit
954 @code{grob-interpret-markup} auswerten. Beispielsweise:
957 mein-callback = #(lambda (grob)
958 (grob-interpret-markup grob (markup "foo")))
966 @node Scheme-Code innerhalb LilyPonds
967 @section Scheme-Code innerhalb LilyPonds
968 @translationof Inline Scheme code
970 Der hauptsächliche Nachteil von @code{\tweak} ist seine
971 syntaktische Inflexibilität. Folgender Code beispielsweise
972 ergibt einen Syntaxfehler:
975 F = \tweak #'font-size #-3 -\flageolet
983 Anders gesagt verhält sich @code{\tweak} nicht wie eine Artikulation
984 und kann auch nicht deren Syntax verwenden: man kann es nicht
985 mit @code{^} oder @code{_} anfügen.
987 Durch die Verwendung von Scheme kann dieses Problem umgangen werden.
988 Der Weg zum Resultat wird gezeigt in
989 @ref{Artikulationszeichen zu Noten hinzufügen (Beispiel)}, insbesondere
990 wie @code{\displayMusic} benutzt wird, hilft hier weiter.
993 F = #(let ((m (make-music 'ArticulationEvent
994 'articulation-type "flageolet")))
995 (set! (ly:music-property m 'tweaks)
997 (ly:music-property m 'tweaks)))
1006 In diesem Beispiel werden die @code{tweaks}-Eigenschaften
1007 des Flageolet-Objekts @code{m} (mit @code{make-music} erstellt)
1008 werden mit @code{ly:music-property} ausgelesen, ein neues
1009 Schlüssel-Wert-Paar, um die Schriftgröße zu ändern, wird
1010 der Eigenschaftenliste mithilfe der @code{acons}-Schemefunktion
1011 vorangestellt, und das Resultat wird schließlich mit
1012 @code{set!} zurückgeschrieben. Das letzte Element des
1013 @code{let}-Blocks ist der Wiedergabewert, @code{m}.
1017 @node Schwierige Korrekturen
1018 @section Schwierige Korrekturen
1019 @translationof Difficult tweaks
1021 Hier finden sich einige Klassen an schwierigeren Anpassungen.
1026 Ein Typ der schwierigen Anpassungen ist die Erscheinung von
1027 Strecker-Objekten wie Binde- oder Legatobögen. Zunächst wird
1028 nur eins dieser Objekte erstellt, und sie können mit dem
1029 normalen Mechanismus verändert werden. In einigen Fällen
1030 reichen die Strecker jedoch über Zeilenumbrüche. Wenn das
1031 geschieht, werden diese Objekte geklont. Ein eigenes
1032 Objekt wird für jedes System erstellt, in dem es sich befindet.
1033 Sie sind Klone des originalen Objektes und erben alle
1034 Eigenschaften, auch @code{\override}-Befehle.
1036 Anders gesagt wirkt sich ein @code{\override} immer auf alle
1037 Stücke eines geteilten Streckers aus. Um nur einen Teil eines
1038 Streckers bei einem Zeilenumbruch zu verändern, ist es notwendig,
1039 in den Formatierungsprozess einzugreifen. Das Callback
1040 @code{after-line-breaking} enthält die Schemefunktion, die
1041 aufgerufen wird, nachdem Zeilenumbrüche errechnet worden sind
1042 und die Layout-Objekte über die unterschiedlichen Systeme verteilt
1045 Im folgenden Beispiel wird die Funktion
1046 @code{my-callback} definiert. Diese Funktion
1050 bestimmt, ob das Objekt durch Zeilenumbrüche geteilt ist,
1052 wenn ja, ruft sie alle geteilten Objekte auf,
1054 testet, ob es sich um das letzte der geteilten Objekte handelt,
1056 wenn ja, wird @code{extra-offset} gesetzt.
1059 Diese Funktion muss in @rinternals{Tie} (Bindebogen) installiert
1060 werden, damit der letzte Teil eines gebrochenen Bindebogens
1061 neu ausgerichtet wird.
1063 @lilypond[quote,verbatim,ragged-right]
1064 #(define (my-callback grob)
1066 ; have we been split?
1067 (orig (ly:grob-original grob))
1069 ; if yes, get the split pieces (our siblings)
1070 (siblings (if (ly:grob? orig)
1071 (ly:spanner-broken-into orig) '() )))
1073 (if (and (>= (length siblings) 2)
1074 (eq? (car (last-pair siblings)) grob))
1075 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1078 \override Tie #'after-line-breaking =
1085 Wenn man diesen Trick anwendet, sollte das neue @code{after-line-breaking}
1086 auch das alte @code{after-line-breaking}-Callback aufrufen,
1087 wenn es vorhanden ist. Wenn diese Funktion etwa mit
1088 @code{Hairpin} (Crescendo-Klammer) eingesetzt wird, sollte auch
1089 @code{ly:spanner::kill-zero-spanned-time} aufgerufen werden.
1093 Manche Objekte können aus technischen Gründen nicht mit @code{\override}
1094 verändert werden. Beispiele hiervon sind @code{NonMusicalPaperColumn}
1095 und @code{PaperColumn}. Sie können mit der
1096 @code{\overrideProperty}-Funktion geändert werden, die ähnlich wie
1097 @code{\once \override} funktioniert, aber eine andere Syntax einsetzt.
1101 #"Score.NonMusicalPaperColumn" % Grob-Bezeichnung
1102 #'line-break-system-details % Eigenschaftsbezeichnung
1103 #'((next-padding . 20)) % Wert
1106 Es sollte angemerkt werden, dass @code{\override}, wenn man es auf
1107 @code{NonMusicalPaperColumn} und @code{PaperColumn} anwendet, immer noch
1108 innerhalb der @code{\context}-Umgebung funktioniert.
1114 @node LilyPond Scheme-Schnittstellen
1115 @chapter LilyPond Scheme-Schnittstellen
1116 @translationof LilyPond Scheme interfaces
1118 Dieses Kapitel behandelt die verschiedenen Werkzeuge, die LilyPond als
1119 Hilfe für Scheme-Programmierer zur Verfügung stellt, um Information in
1120 den Musik-Stream zu senden und aus ihm herauszubekommen.
1122 TODO: was gehört hier eigentlich hin?