Merge branch 'master' of ssh://jneem@git.sv.gnu.org/srv/git/lilypond into tmp

[lilypond.git] / Documentation / user / scheme-tutorial.itely

diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely
index bd4372ac0f7bcf419865d9fcfa4f853d74fcffb3..a9b6d65012d8a4d83947664b1d53d6a9e22d264e 100644 (file)
--- a/Documentation/user/scheme-tutorial.itely
+++ b/Documentation/user/scheme-tutorial.itely
@@ -1,9 +1,18 @@
+@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.11.61"

 
 @node Scheme tutorial
 @appendix Scheme tutorial
 
 
 @node Scheme tutorial
 @appendix Scheme tutorial
 

-@cindex @code{#}
+@funindex #

 @cindex Scheme
 @cindex GUILE
 @cindex Scheme, in-line code
 @cindex Scheme
 @cindex GUILE
 @cindex Scheme, in-line code


@@ -14,8 +23,8 @@
 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
 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
 
 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


@@ -25,13 +34,13 @@ LilyPond input.
 @item Booleans
 Boolean values are True or False.  The Scheme for True is @code{#t}
 and False is @code{#f}.
 @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
 
 @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,
 
 @item Strings
 Strings are enclosed in double quotes,


@@ -64,7 +73,7 @@ In a music file, snippets of Scheme code are introduced with the hash
 mark @code{#}.  So, the previous examples translated in LilyPond are
 
 @example
 mark @code{#}.  So, the previous examples translated in LilyPond are
 
 @example

-##t ##f 
+##t ##f

 #1 #-1.5
 #"this is a string"
 #"this
 #1 #-1.5
 #"this is a string"
 #"this


@@ -81,7 +90,7 @@ traditional @math{1+2}.
 
 @lisp
 #(+ 1 2)
 
 @lisp
 #(+ 1 2)

-  @result{} #3 
+  @result{} #3

 @end lisp
 
 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
 @end lisp
 
 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}


@@ -90,31 +99,31 @@ be used for another calculation.
 
 @lisp
 #(+ 1 (* 3 4))
 
 @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
   @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
 
 @example

-twelve = #12 
+twelve = #12

 @end example
 
 @noindent
 variables can also be used in expressions, here
 
 @example
 @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
 
 @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
 @end example
 
 The @emph{name} of a variable is also an expression, similar to a


@@ -124,7 +133,7 @@ number or a string.  It is entered as
 #'twentyFour
 @end example
 
 #'twentyFour
 @end example
 

-@cindex @code{#'symbol}
+@funindex #'symbol

 @cindex quoting in Scheme
 
 The quote mark @code{'} prevents the Scheme interpreter from substituting
 @cindex quoting in Scheme
 
 The quote mark @code{'} prevents the Scheme interpreter from substituting


@@ -141,15 +150,17 @@ example
 
 This instruction adjusts the appearance of stems.  The value @code{2.6}
 is put into the @code{thickness} variable of a @code{Stem}
 
 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
 @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
 
 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


@@ -158,8 +169,8 @@ 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
 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
 
 This assigns the pair (1, 2) to the @code{extra-offset} property of the
 TextScript object.  These numbers are measured in staff-spaces, so


@@ -197,3 +208,81 @@ respectively,
 #'(staff clef key-signature)
 #'((1) (2))
 @end example
 #'(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
+
+
+
+
+