awk macro: fix: rebind *stdout* in broader scope.

* share/txr/stdlib/awk.tl (sys:awk-state loop): Do not
bind *stdout* around the call to the main record-processing
function.
(awk): Re-bind *stdout* around all of the user code,
just after the run-time awk state object is constructed.

* txr.1: Correct the lies written about :output.

2 files changed, 44 insertions, 13 deletions

diff --git a/share/txr/stdlib/awk.tl b/share/txr/stdlib/awk.tl
index 3c92286a..bb1dec1e 100644
--- a/share/txr/stdlib/awk.tl
+++ b/share/txr/stdlib/awk.tl
@@ -94,8 +94,7 @@
             (inc aws.file-rec-num)
             aws.(rec-to-f)
             (block :awk-rec
-              (let ((*stdout* aws.output))
-                [func aws]))))
+              [func aws])))
         (when end-file-func
           [end-file-func aws])))))
 
@@ -200,6 +199,7 @@
                                   ,*(if awc.inputs ^(inputs (list ,*awc.inputs)))
                                   ,*(if awc.output ^(output ,awc.output))
                                   rng-n (macro-time (qref ,awc nranges))))
+                    (*stdout* (qref ,aws-sym output))
                     ,*(if awc.begin-file-actions
                         ^((,awk-begf-fun (lambda (,aws-sym)
                             ,*awc.begin-file-actions))))
diff --git a/txr.1 b/txr.1
index 62f61fdf..2d8e181d 100644
--- a/txr.1
+++ b/txr.1
@@ -37152,7 +37152,7 @@ with special semantics:
 .codn :name ,
 .codn :let ,
 .codn :inputs ,
-.codn :outputs ,
+.codn :output ,
 .codn :begin ,
 .codn :end ,
 .code :begin-file
@@ -37299,15 +37299,43 @@ of a file to open for writing.
 
 If the
 .code :output
-clause is omitted, then the
+clause is omitted, then the current value of the
 .code *stdout*
-stream is used as the output.
-
-The output serves the destination for the local
-.code prn
-macro established by the
+stream is used: the value which that special
+variable has on entry into the code generated by the
 .code awk
 macro.
+
+The
+.code :output
+clause has the effect of creating a local binding for the
+.code *stdout*
+special variable within the dynamic scope of the
+.code awk
+macro. This new value of
+.code *stdout*
+is visible to all forms within the macro.
+If a
+.code :let
+clause is present, it establishes bindings
+in a scope which is nested within the scope established
+by
+.codn :output .
+Therefore,
+.metn init-form -s
+in the
+.code :let
+may refer to the new value of
+.code *stdout*
+established by
+.codn :output .
+Furthermore,
+.code :let
+can rebind
+.codn *stdout* ,
+causing the definition provided by
+.code :output
+to be shadowed.
 .meIP (:begin << form *)
 All
 .code :begin
@@ -37727,12 +37755,15 @@ macro prints lines.
 The awk macro
 .code prn
 performs output into the
-.code awk
-macro's output stream, which may be elected using the
+.code *stdout*
+stream. The
 .code :output
-clause.
+clause affects the destination by rebinding
+.codn *stdout* .
 
-If called with no arguments, it prints
+If called with no arguments,
+.code prn
+prints
 .code rec
 followed by
 .codn ors .