Merge commit 'origin' into includes

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

diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely
index 6fa1caa717ceb0f96b64f288f6d0c05a243a88e5..6d8f33e0f8f285083a8a0ac152fd2ee6d222931f 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.12.0"
 
 @node Scheme tutorial
 @appendix Scheme tutorial
 
-@cindex @code{#}
+@funindex #
 @cindex Scheme
 @cindex GUILE
 @cindex Scheme, in-line code
@@ -25,8 +34,8 @@ LilyPond input.
 @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,
@@ -114,7 +123,7 @@ 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
@@ -124,7 +133,7 @@ number or a string.  It is entered as
 #'twentyFour
 @end example
 
-@cindex @code{#'symbol}
+@funindex #'symbol
 @cindex quoting in Scheme
 
 The quote mark @code{'} prevents the Scheme interpreter from substituting
@@ -144,14 +153,14 @@ 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
+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
@@ -199,3 +208,81 @@ respectively,
 #'(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
+
+
+
+
+