Doc-fr: Learning Manual full update

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

diff --git a/Documentation/user/scheme-tutorial.itely b/Documentation/user/scheme-tutorial.itely
index 6d9d9c3cd44a6cd616711625dc76e4b4bb1b37ce..18f79c2d15bfa021aedd3565c9e8100e91fabaf2 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
 
 
 @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,10 +23,28 @@
 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}.}
-
-The most basic thing of a language is data: numbers, character
+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 @ref{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.
 
 strings, lists, etc.  Here is a list of data types that are relevant to
 LilyPond input.
 


@@ -25,13 +52,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,


@@ -61,10 +88,10 @@ respectively.
 
 
 In a music file, snippets of Scheme code are introduced with the hash
 
 
 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
 
 @example

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

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


@@ -72,6 +99,35 @@ is
 a string"
 @end example
 
 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.
 
 For the rest of this section, we will assume that the data is entered
 in a music file, so we add @code{#}s everywhere.
 


@@ -81,7 +137,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 +146,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 +180,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


@@ -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
 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
 @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


@@ -160,8 +216,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


@@ -199,3 +255,83 @@ 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]
+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
+
+
+
+
+