X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fextending%2Fscheme-tutorial.itely;h=7503306b1fa56f3e8c16b0f6d25b5f5e8d8f28a6;hb=74843362972efd8b7a76419da499c0f5a920663d;hp=65a28c62d272c0cff1d7312901d085e3ec2419d8;hpb=67a345f965d169bc1acd23ff4160914fb2142f38;p=lilypond.git

diff --git a/Documentation/extending/scheme-tutorial.itely b/Documentation/extending/scheme-tutorial.itely
index 65a28c62d2..7503306b1f 100644
--- a/Documentation/extending/scheme-tutorial.itely
+++ b/Documentation/extending/scheme-tutorial.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.6"
+@c \version "2.17.11"
 
 @node Scheme tutorial
 @chapter Scheme tutorial
@@ -258,7 +258,7 @@ Scheme procedures @code{car} and @code{cdr}, respectively.
 
 @lisp
 guile> (define mypair (cons 123 "hello there")
-... )
+@dots{} )
 guile> (car mypair)
 123
 guile> (cdr mypair)
@@ -574,7 +574,7 @@ statement in the let block:
 
 @lisp
 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
-... (+ (* x y) (/ z x)))
+@dots{} (+ (* x y) (/ z x)))
 508
 @end lisp
 
@@ -615,7 +615,7 @@ Another conditional procedure in scheme is @code{cond}:
 @example
 (cond (test-expression-1 result-expression-sequence-1)
       (test-expression-2 result-expression-sequence-2)
-      ...
+      @dots{}
       (test-expression-n result-expression-sequence-n))
 @end example
 
@@ -660,7 +660,7 @@ Now LilyPond's input is structured into tokens and expressions, much
 like human language is structured into words and sentences.  LilyPond
 has a lexer that recognizes tokens (literal numbers, strings, Scheme
 elements, pitches and so on), and a parser that understands the syntax,
-@ruser{LilyPond grammar}.  Once it knows that a particular syntax rule
+@rcontrib{LilyPond grammar}.  Once it knows that a particular syntax rule
 applies, it executes actions associated with it.
 
 The hash mark@tie{}@code{#} method of embedding Scheme is a natural fit
@@ -820,7 +820,7 @@ traLaLa = @{ c'4 d'4 @}
 is internally converted to a Scheme definition:
 
 @example
-(define traLaLa @var{Scheme value of `@code{... }'})
+(define traLaLa @var{Scheme value of `@code{@dots{}}'})
 @end example
 
 This means that LilyPond variables and Scheme variables may be freely
@@ -862,7 +862,7 @@ Instead of defining @code{\twice}, the example above could also have
 been written as
 
 @example
-...
+@dots{}
 $(make-sequential-music newLa)
 @end example
 
@@ -885,7 +885,7 @@ context.  Using those, the last part of the example could have been
 written as
 
 @example
-...
+@dots{}
 @{ #@@newLa @}
 @end example
 
@@ -905,7 +905,7 @@ If you need it to be executed at a later point of time, check out
 #(define (nopc)
   (ly:set-option 'point-and-click #f))
 
-...
+@dots{}
 #(nopc)
 @{ c'4 @}
 @end example
@@ -1127,30 +1127,37 @@ will display
                   'text
                   "f"))
           'duration
-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)
           'pitch
           (ly:make-pitch 0 0 0))))
 @end example
 
 By default, LilyPond will print these messages to the console along
 with all the other messages.  To split up these messages and save
-the results of @code{\display@{STUFF@}}, redirect the output to
-a file.
+the results of @code{\display@{STUFF@}}, you can specify an optional
+output port to use:
 
 @example
-lilypond file.ly >display.txt
+@{
+  \displayMusic #(open-output-file "display.txt") @{ c'4\f @}
+@}
 @end example
 
-With a combined bit of Lilypond and Scheme magic, you can actually
-let Lilypond direct just this output to a file of its own:
-
+This will overwrite a previous output file whenever it is called; if you
+need to write more than one expression, you would use a variable for
+your port and reuse it:
 @example
 @{
-  #(with-output-to-file "display.txt"
-      (lambda () #@{ \displayMusic @{ c'4\f @} #@}))
+  port = #(open-output-file "display.txt")
+  \displayMusic \port @{ c'4\f @}
+  \displayMusic \port @{ d'4 @}
+  #(close-output-port port)
 @}
 @end example
 
+Guile's manual describes ports in detail.  Closing the port is actually
+only necessary if you need to read the file before Lilypond finishes; in
+the first example, we did not bother to do so.
 
 A bit of reformatting makes the above information easier to read:
 
@@ -1162,16 +1169,16 @@ A bit of reformatting makes the above information easier to read:
 			       (make-music 'AbsoluteDynamicEvent
 				 'text
 				 "f"))
-	       'duration (ly:make-duration 2 0 1 1)
+	       'duration (ly:make-duration 2 0 1/1)
 	       'pitch    (ly:make-pitch 0 0 0))))
 @end example
 
-A @code{@{ ... @}} music sequence has the name @code{SequentialMusic},
-and its inner expressions are stored as a list in its @code{'elements}
-property.  A note is represented as a @code{NoteEvent} object (storing
-the duration and pitch properties) with attached information (in this
-case, an @code{AbsoluteDynamicEvent} with a @code{"f"} text property)
-stored in its @code{articulations} property.
+A @code{@{ @dots{} @}} music sequence has the name
+@code{SequentialMusic}, and its inner expressions are stored as a list
+in its @code{'elements} property.  A note is represented as a
+@code{NoteEvent} object (storing the duration and pitch properties) with
+attached information (in this case, an @code{AbsoluteDynamicEvent} with
+a @code{"f"} text property) stored in its @code{articulations} property.
 
 @funindex{\void}
 @code{\displayMusic} returns the music it displays, so it will get
@@ -1194,7 +1201,7 @@ someNote = c'
 (make-music
   'NoteEvent
   'duration
-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)
   'pitch
   (ly:make-pitch 0 0 0))
 @end example
@@ -1212,7 +1219,7 @@ someNote = <c'>
   (list (make-music
           'NoteEvent
           'duration
-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)
           'pitch
           (ly:make-pitch 0 0 0))))
 @end example
@@ -1230,7 +1237,7 @@ expression.
 (make-music
   'NoteEvent
   'duration
-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)
   'pitch
   (ly:make-pitch 0 0 0))
 @end example
@@ -1281,7 +1288,7 @@ representation of the desired result.
                   'span-direction
                   -1))
           'duration
-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)
           'pitch
           (ly:make-pitch 0 5 0))
         (make-music
@@ -1292,7 +1299,7 @@ representation of the desired result.
                   'span-direction
                   1))
           'duration
-          (ly:make-duration 2 0 1 1)
+          (ly:make-duration 2 0 1/1)
           'pitch
           (ly:make-pitch 0 5 0))))
 @end example
@@ -1309,7 +1316,7 @@ Now we examine the input,
 (make-music
   'NoteEvent
   'duration
-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)
   'pitch
   (ly:make-pitch 0 5 0))))
 @end example
@@ -1317,7 +1324,7 @@ Now we examine the input,
 So in our function, we need to clone this expression (so that we have
 two notes to build the sequence), add a @code{SlurEvent} to the
 @code{'articulations} property of each one, and finally make a
-@code{SequentialMusic} with the two @code{EventChords}.  For adding to a
+@code{SequentialMusic} with the two @code{NoteEvent} elements.  For adding to a
 property, it is useful to know that an unset property is read out as
 @code{'()}, the empty list, so no special checks are required before we
 put another element at the front of the @code{articulations} property.
@@ -1341,14 +1348,14 @@ doubleSlur = #(define-music-function (parser location note) (ly:music?)
 @subsection Adding articulation to notes (example)
 
 The easy way to add articulation to notes is to merge two music
-expressions into one context, as explained in @ruser{Creating contexts}.
+expressions into one context.
 However, suppose that we want to write a music function that does this.
 This will have the additional advantage that we can use that music
 function to add an articulation (like a fingering instruction) to a
 single note inside of a chord which is not possible if we just merge
 independent music.
 
-A @code{$variable} inside the @code{#@{...#@}} notation is like
+A @code{$variable} inside the @code{#@{@dots{}#@}} notation is like
 a regular @code{\variable} in classical LilyPond notation.  We
 know that
 
@@ -1375,7 +1382,7 @@ Scheme.  We begin by examining our input and desired output,
 (make-music
   'NoteEvent
   'duration
-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)
   'pitch
   (ly:make-pitch -1 0 0))))
 =====
@@ -1390,7 +1397,7 @@ Scheme.  We begin by examining our input and desired output,
           'articulation-type
           "accent"))
   'duration
-  (ly:make-duration 2 0 1 1)
+  (ly:make-duration 2 0 1/1)
   'pitch
   (ly:make-pitch -1 0 0))
 @end example
@@ -1420,7 +1427,7 @@ from its name.  (this is good practice in other programming languages,
 too!)
 
 @example
-"Add an accent..."
+"Add an accent@dots{}"
 @end example
 
 @noindent