+@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+ 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
-@cindex @code{#}
+@funindex #
@cindex Scheme
@cindex GUILE
@cindex Scheme, in-line code
LilyPond uses the Scheme programming language, both as part of the
input syntax, and as internal mechanism to glue modules of the program
together. This section is a very brief overview of entering data in
-Scheme.@footnote{If you want to know more about Scheme, see
-@uref{http://@/www@/.schemers@/.org}.}
+Scheme. If you want to know more about Scheme, see
+@uref{http://@/www@/.schemers@/.org}.
The most basic thing of a language is data: numbers, character
strings, lists, etc. Here is a list of data types that are relevant to
@item Booleans
Boolean values are True or False. The Scheme for True is @code{#t}
and False is @code{#f}.
-@cindex @code{##t}
-@cindex @code{##f}
+@funindex ##t
+@funindex ##f
@item Numbers
Numbers are entered in the standard fashion,
@code{1} is the (integer) number one, while @code{-1.5} is a
-floating point number (a non-integer number).
+floating point number (a non-integer number).
@item Strings
Strings are enclosed in double quotes,
mark @code{#}. So, the previous examples translated in LilyPond are
@example
-##t ##f
+##t ##f
#1 #-1.5
#"this is a string"
#"this
@lisp
#(+ 1 2)
- @result{} #3
+ @result{} #3
@end lisp
The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
@lisp
#(+ 1 (* 3 4))
- @result{} #(+ 1 12)
+ @result{} #(+ 1 12)
@result{} #13
@end lisp
These calculations are examples of evaluations; an expression like
@code{(* 3 4)} is replaced by its value @code{12}. A similar thing
-happens with variables. After defining a variable
+happens with variables. After defining a variable
@example
-twelve = #12
+twelve = #12
@end example
@noindent
variables can also be used in expressions, here
@example
-twentyFour = #(* 2 twelve)
-@end example
+twentyFour = #(* 2 twelve)
+@end example
@noindent
the number 24 is stored in the variable @code{twentyFour}.
The same assignment can be done in completely in Scheme as well,
@example
-#(define twentyFour (* 2 twelve)
+#(define twentyFour (* 2 twelve))
@end example
The @emph{name} of a variable is also an expression, similar to a
#'twentyFour
@end example
-@cindex @code{#'symbol}
+@funindex #'symbol
@cindex quoting in Scheme
The quote mark @code{'} prevents the Scheme interpreter from substituting
This instruction adjusts the appearance of stems. The value @code{2.6}
is put into the @code{thickness} variable of a @code{Stem}
-object. This makes stems almost twice as thick as their normal size.
-To distinguish between variables defined in input files (like
+object. @code{thickness} is measured relative to the thickness of
+staff lines, so these stem lines will be @code{2.6} times the
+width of staff lines. This makes stems almost twice as thick as their
+normal size. To distinguish between variables defined in input files (like
@code{twentyFour} in the example above) and variables of internal
-objects, we will call the latter ``properties'' and the former
-``identifiers.'' So, the stem object has a @code{thickness} property,
-while @code{twentyFour} is an identifier.
+objects, we will call the latter @q{properties} and the former
+@q{variables.} So, the stem object has a @code{thickness} property,
+while @code{twentyFour} is an variable.
-@cindex properties vs. identifiers
-@cindex identifiers vs. properties
+@cindex properties vs. variables
+@cindex variables vs. properties
Two-dimensional offsets (X and Y coordinates) as well as object sizes
(intervals with a left and right point) are entered as @code{pairs}. A
is entered as @code{(first . second)} and, like symbols, they must be quoted,
@example
-\override TextScript #'extra-offset = #'(1 . 2)
-@end example
+\override TextScript #'extra-offset = #'(1 . 2)
+@end example
This assigns the pair (1, 2) to the @code{extra-offset} property of the
TextScript object. These numbers are measured in staff-spaces, so
#'(staff clef key-signature)
#'((1) (2))
@end example
+
+
+@menu
+* Tweaking with Scheme::
+@end menu
+
+@node Tweaking with Scheme
+@appendixsec Tweaking with Scheme
+
+We have seen how LilyPond output can be heavily modified using
+commands like
+@code{\override TextScript #'extra-offset = ( 1 . -1)}. But
+we have even more power if we use Scheme. For a full explanation
+of this, see the @ref{Scheme tutorial}, and
+@ruser{Interfaces for programmers}.
+
+We can use Scheme to simply @code{\override} commands,
+
+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
+
+We can use it to create new commands:
+
+@c Check this is a valid example with skylining
+@c It is - 'padding still works
+
+@lilypond[quote,verbatim,ragged-right]
+tempoMark = #(define-music-function (parser location padding marktext)
+ (number? string?)
+#{
+ \once \override Score . RehearsalMark #'padding = $padding
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup { \bold $marktext }
+#})
+
+\relative c'' {
+ c2 e
+ \tempoMark #3.0 #"Allegro"
+ g c
+}
+@end lilypond
+
+Even music expressions can be passed in:
+
+@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
+
+
+
+
+