X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fscheme-tutorial.itely;h=5ced0b1a84be807fd2a5497d12f7553ba9501cd3;hb=2afe63ce18d7c2754e84078a722cff416d74fe10;hp=bc3c2b325015e0e9446c31d59f4a401d5468fd03;hpb=fb90bcfab9e7d98b572dcac3f8b80d82282b3ae4;p=lilypond.git

diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely
index bc3c2b3250..5ced0b1a84 100644
--- 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.51"
 
 @node Scheme tutorial
 @appendix Scheme tutorial
 
-@cindex @code{#}
+@funindex #
 @cindex Scheme
 @cindex GUILE
 @cindex Scheme, in-line code
@@ -12,118 +21,123 @@
 @cindex LISP
 
 LilyPond uses the Scheme programming language, both as part of the
-input syntax, and as internal mechanism to glue together modules of
-the program. 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}.}
+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}.
 
 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
+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}.
-@cindex @code{##t}
-@cindex @code{##f}
+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). 
+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{\\}
+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 in LilyPond are
+mark @code{#}.  So, the previous examples translated in LilyPond are
 
 @example
-  ##t ##f 
-  #1 #-1.5
-  #"this is a string"
-  #"this
-  is
-  a string"
+##t ##f
+#1 #-1.5
+#"this is a string"
+#"this
+is
+a string"
 @end example
 
 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 2 is written as @code{(+ 1 2)} rather than the
-traditional 1+2.
+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 
+#(+ 1 2)
+  @result{} #3
 @end lisp
 
 The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
-is @code{3}.  Calculations may be nested; the result of a function may
+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
+#(+ 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  
+@code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
+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 (* twelve))
+#(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
+number or a string.  It is entered as
 
 @example
-  #'twentyFour
+#'twentyFour
 @end example
 
-@cindex @code{#'symbol}
+@funindex #'symbol
 @cindex quoting in Scheme
 
-The quote mark @code{'} prevents Scheme interpreter from substituting
-@code{24} for the @code{twentyFour}. Instead, we get the name
+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
@@ -131,55 +145,58 @@ tweaks involve assigning (Scheme) values to internal variables, for
 example
 
 @example
-  \override Stem #'thickness = #2.6
+\override Stem #'thickness = #2.6
 @end example
 
-This instruction adjusts the appearance of stems. The value @code{2.6}
-is put into a 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
+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 ``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
+(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,
+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 
+\override TextScript #'extra-offset = #'(1 . 2)
+@end example
 
 This assigns the pair (1, 2) to the @code{extra-offset} property of the
-TextScript object. This moves the object 1 staff space to the right,
-and 2 spaces up.
+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)
+#'(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,
+a quote.  For example,
+
 @example
-  #'(1 2 3)
-  #'(1 2 "string" #f)
+#'(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 2). Normally lists are interpreted as calculations, and the Scheme
-interpreter substitutes the outcome of the calculation. To enter a
-list, we stop evaluation. This is done by quoting the list with a
+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
@@ -187,8 +204,85 @@ 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))
+#'(stem . head)
+#'(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
+
+
+
+
+