Re: minor proposed changed to guile doc

[Kevin Ryde]

first last <address@hidden> writes:
>
> I propose that the following section replace the
> current documentation for the DO function.  It
> essentially replaces "test" with "terminate" and
> "expr" with "result". 

I revised `do' per below in the cvs head, perhaps it's clearer.


 -- syntax: do ((variable init [step]) ...) (test [expr ...]) body ...
     Bind VARIABLEs and evaluate BODY until TEST is true.  The return
     value is the last EXPR after TEST, if given.  A simple example
     will illustrate the basic form,

          (do ((i 1 (1+ i)))
              ((> i 4))
            (display i))
          -| 1234

     Or with two variables and a final return value,

          (do ((i 1 (1+ i))
               (p 3 (* 3 p)))
              ((> i 4)
               p)
            (format #t "3**~s is ~s\n" i p))
          -|
          3**1 is 3
          3**2 is 9
          3**3 is 27
          3**4 is 81
          =>
          789

     The VARIABLE bindings are established like a `let', in that the
     expressions are all evaluated and then all bindings made.  When
     iterating, the optional STEP expressions are evaluated with the
     previous bindings in scope, then new bindings all made.

     The TEST expression is a termination condition.  Looping stops
     when the TEST is true.  It's evaluated before running the BODY
     each time, so if it's true the first time then BODY is not run at
     all.

     The optional EXPRs after the TEST are evaluated at the end of
     looping, with the final VARIABLE bindings available.  The last
     EXPR gives the return value, or if there are no EXPRs the return
     value is unspecified.

     Each iteration establishes bindings to fresh locations for the
     VARIABLEs, like a new `let' for each iteration.  This is done for
     VARIABLEs without STEP expressions too.  The following illustrates
     this, showing how a new `i' is captured by the `lambda' in each
     iteration (*note The Concept of Closure: About Closure.).

          (define lst '())
          (do ((i 1 (1+ i)))
              ((> i 4))
            (set! lst (cons (lambda () i) lst)))
          (map (lambda (proc) (proc)) lst)
          =>
          (4 3 2 1)