X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Fscheme-tutorial.itely;h=e561b1106586de3ba7a8e31061198b4e93b46ded;hb=b97565a9af1c13369ac7e7e9ea80c2638dbc0e51;hp=64f1ff6e18b03d84b3ad6a1bf52fae2cb458bb26;hpb=09765889e9d9dfaa3160c82cbad095d34d97f9cd;p=lilypond.git

diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely
index 64f1ff6e18..e561b11065 100644
--- a/Documentation/user/scheme-tutorial.itely
+++ b/Documentation/user/scheme-tutorial.itely
@@ -1,4 +1,13 @@
+@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
@@ -17,7 +26,25 @@ 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
+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 @ref{Other sources of information}).  Alternatively, Windows
+users may simply chose @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.
 
@@ -61,7 +88,7 @@ respectively.
 
 
 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 to LilyPond are
 
 @example
 ##t ##f
@@ -72,6 +99,35 @@ 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.
 
@@ -144,14 +200,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
@@ -201,4 +257,81 @@ respectively,
 @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]
+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
+
+
+
+