doc do

[Kevin Ryde]

        * scheme-control.texi (while do): Expand and clarify `do', in
        particular note iteration binds fresh locations, rather than values
        "stored".


 - 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.  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 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)