From: Carl Sorensen <c_sorensen@byu.edu>
Date: Sat, 19 Dec 2009 04:22:43 +0000 (-0700)
Subject: Doc -- add structure to Scheme tutorial
X-Git-Tag: release/2.13.10-1~146
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=79cabb95c5d511fb8007355d6c2f5a3bc7d1eaed;p=lilypond.git

Doc -- add structure to Scheme tutorial
---

diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
index 20fe66e381..378c0045b1 100644
--- a/Documentation/extending/scheme-tutorial.itely
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -44,6 +44,31 @@ see @rlearning{Other sources of information}).  Alternatively, Windows
 users may simply choose @q{Run} from the Start menu and enter
 @q{guile}.
 
+@menu
+* Introduction to Scheme::
+* Scheme in LilyPond::
+@end menu
+
+@node Introduction to Scheme
+@section Introduction to Scheme
+
+We begin with an introduction to Scheme.  For this brief introduction,
+we will use the GUILE interpreter to explore how the language works.
+Once we are familiar with Scheme, we will show how the language can
+be integrated in LilyPond files.
+
+
+@menu
+* Scheme simple data types::
+* Scheme compound data types::
+* Calculations in Scheme::
+* Scheme procedures::
+* Scheme conditionals::
+@end menu
+
+@node Scheme simple data types
+@subsection Scheme simple data types
+
 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.
@@ -87,6 +112,134 @@ respectively.
 @end table
 
 
+@node Scheme compound data types
+@subsection Scheme compound data types
+
+@unnumberedsubsubsec Pairs
+
+TODO -- write about pairs
+
+The two elements of a pair may be arbitrary values, for example
+
+@example
+#'(1 . 2)
+#'(#t . #f)
+#'("blah-blah" . 3.14159265)
+@end example
+
+
+@unnumberedsubsubsec Lists
+
+TODO -- write about lists
+
+A list is entered by enclosing its elements in parentheses, and adding
+a quote.  For example,
+
+@example
+#'(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@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
+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))
+@end example
+
+@unnumberedsubsubsec Hash tables
+
+TODO -- write about hash tables
+
+
+@node Calculations in Scheme
+@subsection Calculations in Scheme
+
+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
+@end lisp
+
+The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
+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
+@end lisp
+
+These calculations are examples of evaluations; an expression like
+@code{(* 3 4)} is replaced by its value @code{12}.
+
+The same assignment can be done in completely in Scheme as well,
+
+@example
+#(define twentyFour (* 2 twelve))
+@end example
+
+@c this next section is confusing -- need to rewrite
+
+The @emph{name} of a variable is also an expression, similar to a
+number or a string.  It is entered as
+
+@example
+#'twentyFour
+@end example
+
+@funindex #'symbol
+@cindex quoting in Scheme
+
+The quote mark @code{'} prevents the Scheme interpreter from substituting
+@code{24} for the @code{twentyFour}.  Instead, we get the name
+@code{twentyFour}.
+
+@node Scheme procedures
+@subsection Scheme procedures
+
+@unnumberedsubsubsec Predicates
+
+@unnumberedsubsubsec Return values
+
+TODO -- write about scheme procedures
+
+@node Scheme conditionals
+@subsection Scheme conditionals
+
+@unnumberedsubsubsec if
+
+@unnumberedsubsubsec cond
+
+
+@node Scheme in LilyPond
+@section Scheme in LilyPond
+
+
+@menu
+* LilyPond Scheme syntax::
+* LilyPond variables::
+* Object properties::
+* LilyPond compound variables::
+@end menu
+
+@node LilyPond Scheme syntax
+@subsection LilyPond Scheme syntax
+
 In a music file, snippets of Scheme code are introduced with the hash
 mark @code{#}.  So, the previous examples translated to LilyPond are
 
@@ -123,69 +276,42 @@ of hash marks to be reduced to one.
   (define bar 1))
 @end example
 
-If @code{#} is followed by an opening bracket, @code{(}, as in
+@c todo -- # introduces a scheme *expression*
+@c         need the concept of an expression
+
+If @code{#} is followed by an opening parenthesis, @code{(}, as in
 the example above, the parser will remain in Scheme mode until
-a matching closing bracket, @code{)}, is found, so further
+a matching closing parenthesis, @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.
 
-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
-@end lisp
+@node LilyPond variables
+@subsection LilyPond variables
 
-The arrow @result{} shows that the result of evaluating @code{(+ 1 2)}
-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
-@end lisp
+TODO -- make this read right
 
-These calculations are examples of evaluations; an expression like
-@code{(* 3 4)} is replaced by its value @code{12}.  A similar thing
+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)
+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 (* 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
-
-@example
-#'twentyFour
-@end example
-
-@funindex #'symbol
-@cindex quoting in Scheme
-
-The quote mark @code{'} prevents the Scheme interpreter from substituting
-@code{24} for the @code{twentyFour}.  Instead, we get the name
-@code{twentyFour}.
+@node Object properties
+@subsection Object properties
 
 This syntax will be used very frequently, since many of the layout
 tweaks involve assigning (Scheme) values to internal variables, for
@@ -209,6 +335,15 @@ while @code{twentyFour} is an variable.
 @cindex properties vs. variables
 @cindex variables vs. properties
 
+@c  todo -- here we're getting interesting.  We're now introducing
+@c  LilyPond variable types.  I think this deserves a section all
+@c  its own
+
+@node LilyPond compound variables
+@subsection LilyPond compound variables
+
+@unnumberedsubsubsec Offsets
+
 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
 pair@footnote{In Scheme terminology, the pair is called @code{cons},
@@ -223,40 +358,19 @@ 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 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
+@unnumberedsubsubsec Extents
 
-@example
-#'(1 . 2)
-#'(#t . #f)
-#'("blah-blah" . 3.14159265)
-@end example
+todo -- write something about extents
 
-A list is entered by enclosing its elements in parentheses, and adding
-a quote.  For example,
+@unnumberedsubsubsec Property alists
 
-@example
-#'(1 2 3)
-#'(1 2 "string" #f)
-@end example
+todo -- write something about property alists
 
-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
-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))
-@end example
+@unnumberedsubsubsec Alist chains
 
+todo -- write something about alist chains
 
+@ignore
 @menu
 * Tweaking with Scheme::
 @end menu
@@ -276,6 +390,7 @@ 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
+@end ignore
 
 @ignore
 @lilypond[quote,verbatim,ragged-right]
@@ -294,6 +409,7 @@ padText = #(define-music-function (parser location padding) (number?)
 @end lilypond
 @end ignore
 
+@ignore
 We can use it to create new commands:
 
 @c Check this is a valid example with skylining
@@ -330,8 +446,4 @@ pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
   \pattern {d16 dis} { ais16-> b\p }
 }
 @end lilypond
-
-
-
-
-
+@end ignore