+@c -*- coding: utf-8; mode: texinfo; -*-
+
+@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
+@chapter Scheme tutorial
+
+@funindex #
+@cindex Scheme
+@cindex GUILE
+@cindex Scheme, in-line code
+@cindex accessing Scheme
+@cindex evaluating Scheme
+@cindex LISP
+
+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. If you want to know more about Scheme, see
+@uref{http://@/www@/.schemers@/.org}.
+
+LilyPond uses the GNU Guile implementation of Scheme, which is
+based on the Scheme @qq{R5RS} standard. If you are learning Scheme
+to use with LilyPond, working with a different implementation (or
+referring to a different standard) is not recommended. Information
+on guile can be found at @uref{http://www.gnu.org/software/guile/}.
+The @qq{R5RS} Scheme standard is located at
+@uref{http://www.schemers.org/Documents/Standards/R5RS/}.
+
+The LilyPond installation also includes the Guile implementation of
+Scheme. On most systems you can experiment in a Scheme sandbox by
+opening a terminal window and typing @q{guile}. On some systems,
+notably Windows, you may need to set the environment variable
+@code{GUILE_LOAD_PATH} to the directory @code{../usr/shr/guile/1.8}
+in the LilyPond installation (for the full path to this directory
+see @rlearning{Other sources of information}). Alternatively, Windows
+users may simply choose @q{Run} from the Start menu and enter
+@q{guile}.
+
+The most basic concept in a language is data typing: numbers, character
+strings, lists, etc. Here is a list of data types that are relevant to
+LilyPond input.
+
+@table @asis
+@item Booleans
+Boolean values are True or False. The Scheme for True is @code{#t}
+and False is @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).
+
+@item Strings
+Strings are enclosed in double quotes,
+
+@example
+"this is a string"
+@end example
+
+Strings may span several lines
+
+@example
+"this
+is
+a string"
+@end example
+
+Quotation marks and newlines can also be added with so-called escape
+sequences. The string @code{a said "b"} is entered as
+
+@example
+"a said \"b\""
+@end example
+
+Newlines and backslashes are escaped with @code{\n} and @code{\\}
+respectively.
+@end table
+
+
+In a music file, snippets of Scheme code are introduced with the hash
+mark @code{#}. So, the previous examples translated to LilyPond are
+
+@example
+##t ##f
+#1 #-1.5
+#"this is a string"
+#"this
+is
+a string"
+@end example
+
+Note that LilyPond comments (@code{%} and @code{%@{ %@}}) cannot
+be used within Scheme code. Comments in Guile Scheme are entered
+as follows:
+
+@example
+; this is a single-line comment
+
+#!
+ This a (non-nestable) Guile-style block comment
+ But these are rarely used by Schemers and never in
+ LilyPond source code
+!#
+@end example
+
+Multiple consecutive scheme expressions in a music file can be
+combined using the @code{begin} operator. This permits the number
+of hash marks to be reduced to one.
+
+@example
+#(begin
+ (define foo 0)
+ (define bar 1))
+@end example
+
+If @code{#} is followed by an opening bracket, @code{(}, as in
+the example above, the parser will remain in Scheme mode until
+a matching closing bracket, @code{)}, is found, so further
+@code{#} symbols to introduce a Scheme section are not required.
+
+For the rest of this section, we will assume that the data is entered
+in a music file, so we add @code{#}s everywhere.
+
+Scheme can be used to do calculations. It uses @emph{prefix}
+syntax. Adding 1 and@tie{}2 is written as @code{(+ 1 2)} rather than the
+traditional @math{1+2}.
+
+@lisp
+#(+ 1 2)
+ @result{} #3
+@end lisp
+
+The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
+is@tie{}@code{3}. Calculations may be nested; the result of a function may
+be used for another calculation.
+
+@lisp
+#(+ 1 (* 3 4))
+ @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
+
+@example
+twelve = #12
+@end example
+
+@noindent
+variables can also be used in expressions, here
+
+@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))
+@end example
+
+The @emph{name} of a variable is also an expression, similar to a
+number or a string. It is entered as
+
+@example
+#'twentyFour
+@end example
+
+@funindex #'symbol
+@cindex quoting in Scheme
+
+The quote mark @code{'} prevents the Scheme interpreter from substituting
+@code{24} for the @code{twentyFour}. Instead, we get the name
+@code{twentyFour}.
+
+This syntax will be used very frequently, since many of the layout
+tweaks involve assigning (Scheme) values to internal variables, for
+example
+
+@example
+\override Stem #'thickness = #2.6
+@end example
+
+This instruction adjusts the appearance of stems. The value @code{2.6}
+is put into the @code{thickness} variable of a @code{Stem}
+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 @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. 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
+pair@footnote{In Scheme terminology, the pair is called @code{cons},
+and its two elements are called @code{car} and @code{cdr} respectively.}
+is entered as @code{(first . second)} and, like symbols, they must be quoted,
+
+@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
+this command moves the object 1 staff space to the right, and 2 spaces up.
+
+The two elements of a pair may be arbitrary values, for example
+
+@example
+#'(1 . 2)
+#'(#t . #f)
+#'("blah-blah" . 3.14159265)
+@end example
+
+A list is entered by enclosing its elements in parentheses, and adding
+a quote. For example,
+
+@example
+#'(1 2 3)
+#'(1 2 "string" #f)
+@end example
+
+We have been using lists all along. A calculation, like @code{(+ 1 2)}
+is also a list (containing the symbol @code{+} and the numbers 1
+and@tie{}2). Normally lists are interpreted as calculations, and the
+Scheme interpreter substitutes the outcome of the calculation. To enter a
+list, we stop the evaluation. This is done by quoting the list with a
+quote @code{'} symbol. So, for calculations do not use a quote.
+
+Inside a quoted list or pair, there is no need to quote anymore. The
+following is a pair of symbols, a list of symbols and a list of lists
+respectively,
+
+@example
+#'(stem . head)
+#'(staff clef key-signature)
+#'((1) (2))
+@end example
+
+
+@menu
+* Tweaking with Scheme::
+@end menu
+
+@node Tweaking with Scheme
+@section 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]
+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
+
+
+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
+
+
+
+
+