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

@ignore
    Translation of GIT committish: 5131c3292d30cabdf08839daa02a006e4d3c96c5

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node Scheme tutorial
@appendix Scheme tutorial

@funindex #
@cindex Scheme
@cindex GUILE
@cindex Scheme, in einer LilyPond-Datei
@cindex LISP

LilyPond verwendet die Scheme-Programmiersprache sowohl als Teil 
der Eingabesyntax als auch als internen Mechanismus, um Programmmodule 
zusammenzufügen.  Dieser Abschnitt ist ein sehr kurzer Überblick über 
die Dateneingabe mit Scheme.  Wenn Sie mehr über Scheme wissen wollen,
gehen Sie zu @uref{http://@/www@/.schemers@/.org}.

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.

@table @asis
@item Boolesche Variablen
Werte einer Booleschen Variable sind Wahr oder Falsch. Die Scheme-Entsprechung
für Wahr ist @code{#t} und für Falsch @code{#f}.
@funindex ##t
@funindex ##f

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

@item Zeichenketten
Zeichenketten werden in doppelte Anführungszeichen gesetzt:

@example
"Das ist eine Zeichenkette"
@end example

Zeichenketten können über mehrere Zeilen reichen:

@example
"Das
ist
eine 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:

@example
"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:

@example
##t ##f
#1 #-1.5
#"Das ist eine Zeichenkette"
#"Das
ist
eine Zeichenkette"
@end example

Für den Rest dieses Abschnitts nehmen wir an, dass die Daten immer in 
einer LilyPond-Datei stehen, darum wird immer die Raute verwendet.

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
#(+ 1 2)
  @result{} #3
@end lisp

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.

@lisp
#(+ 1 (* 3 4))
  @result{} #(+ 1 12)
  @result{} #13
@end lisp

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:

@example
zwoefl = #12
@end example

@noindent
kann man sie in Ausdrücken weiterverwenden:

@example
vierundzwanzig = #(* 2 zwoelf)
@end example

@noindent
Die 24 wird in der Variablen @code{vierundzwanzig} gespeichert.
Die gleiche Zuweisung kann auch vollständig in Scheme geschrieben 
werden:

@example
#(define vierundzwanzig (* 2 zwoelf))
@end example

Der @emph{Name} einer Variable ist auch ein Ausdruck, genauso wie 
eine Zahl oder eine Zeichenkette. Er wird wie folgt eingegeben:

@example
#'vierundzwanzig
@end example

@funindex #'symbol
@cindex Zitieren in Scheme

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

@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. 
@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, 
die für interne Objekte zuständig sind, werden hier die ersteren 
@qq{Bezeichner} genannt, die letzteren dagegen @qq{Eigenschaften}.
Das Hals-Objekt hat also eine @code{thickness}-Eigenschaft, während 
@code{vierundzwanzig} ein Bezeichner 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:

@example
\override TextScript #'extra-offset = #'(1 . 2)
@end example

Hierdurch wird das Paar (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

@example
#'(1 . 2)
#'(#t . #f)
#'("blah-blah" . 3.14159265)
@end example

Eine Liste wird eingegeben, indem die Elemente der Liste in Klammern 
geschrieben werden, mit einem Apostroph davor. Beispielsweise:

@example
#'(1 2 3)
#'(1 2 "string" #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.

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:

@example
#'(stem . head)
#'(staff clef key-signature)
#'((1) (2))
@end example



@menu
* Tweaking with Scheme::
@end menu

@node Tweaking with Scheme
@appendixsec Tweaking with Scheme

Wir haben gesehen wie LilyPond-Eingabe massiv beeinflusst
werden kann, indem Befehle wie etwa
@code{\override TextScript #'extra-offset = ( 1 . -1)}
benutzt werden.  Aber es wurde gezeigt, dass Scheme noch
mächtiger ist.  Eine bessere Erklärung findet sich in der@ref{Scheme tutorial} und in
@ruser{Interfaces for programmers}.

Scheme kann auch in einfachen @code{\override}-Befehlen
benutzt werden:

TODO Find a simple example
@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?)
#{
  \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
@end ignore

Es kann auch benutzt werden, um Befehle zu erstellen:

@c Check this is a valid example with skylining
@c It is - 'padding still works

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

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

Sogar ganze Musikausdrücke können eingefügt werden:

@lilypond[quote,verbatim,ragged-right]
pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
#{
  $x e8 a b $y b a e
#})

\relative c''{
  \pattern c8 c8\f
  \pattern {d16 dis} { ais16-> b\p }
}
@end lilypond