From 7eafaa2ef0a32790fb0e5746e4f7d90d4b851217 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Mon, 13 Jun 2022 06:55:06 -0700
Subject: for/for*: stricter syntax check.

* eval.c (me_for): Require at least one argument.
However, we let the init-forms continue to be optional
and document it.

* txr.1: Refer to for and for* as macros, since they have been
since 2016. The omission of the inc-form list is shown
as a second variant of the syntax. This is to avoid misleading
the reader into thinking that the the inc-form list can be
omitted while body forms are present. A spurious paragraph
reiterating that the macros establish an anonymous block is
removed. That extra text was present in the first draft written
in 2011, and maintained since.

* stdlib/doc-syms.tl: Updated.
---
 eval.c             |  2 +-
 stdlib/doc-syms.tl |  4 ++--
 txr.1              | 31 ++++++++++++++++---------------
 3 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/eval.c b/eval.c
index 4053f8eb..7f207de9 100644
--- a/eval.c
+++ b/eval.c
@@ -3215,7 +3215,7 @@ static val me_each(val form, val menv)
 static val me_for(val form, val menv)
 {
   val forsym = first(form);
-  val args = (syn_check(form, forsym, cdr, 0), rest(form));
+  val args = (syn_check(form, forsym, cddr, 0), rest(form));
   val vars = first(args);
   val body = rest(args);
   int oldscope = opt_compat && opt_compat <= 123;
diff --git a/stdlib/doc-syms.tl b/stdlib/doc-syms.tl
index 7b9ab9fa..ba518652 100644
--- a/stdlib/doc-syms.tl
+++ b/stdlib/doc-syms.tl
@@ -797,8 +797,8 @@
       ("fnm-period" "N-0330E15A")
       ("fnmatch" "N-03F8FF75")
       ("fnr" "N-02E33A82")
-      ("for" "N-031372ED")
-      ("for*" "N-031372ED")
+      ("for" "N-01F3471B")
+      ("for*" "N-01F3471B")
       ("force" "N-0307223D")
       ("force-break" "N-03B5FB1D")
       ("forget" "N-02A1EE04")
diff --git a/txr.1 b/txr.1
index 8166d0aa..6950c4a8 100644
--- a/txr.1
+++ b/txr.1
@@ -17615,19 +17615,24 @@ and
  10 is "even"
 .onom
 
-.coNP Operators @ for and @ for*
+.coNP Macros @ for and @ for*
 .synb
 .mets ({for | for*} >> ({ sym | >> ( sym << init-form )}*)
 .mets \ \ \ \ \ \ \ \ \ \ \ \ \  >> ([ test-form << result-form *])
-.mets \ \ \ \ \ \ \ \ \ \ \ \ \  <> ( inc-form *)
+.mets \ \ \ \ \ \ \ \ \ \ \ \ \  <> [( inc-form *)]
 .mets \ \  << body-form *)
+.mets ""
+.mets ({for | for*} >> ({ sym | >> ( sym << init-form )}*)
+.mets \ \ \ \ \ \ \ \ \ \ \ \ \  >> ([ test-form << result-form *]))
+.mets ""
+.mets ({for | for*} >> ({ sym | >> ( sym << init-form )}*))
 .syne
 .desc
-The
+The macros
 .code for
 and
 .code for*
-operators combine variable binding with loop iteration.
+combine variable binding with loop iteration.
 The first argument is a list of variables with optional initializers,
 exactly the same as in the
 .code let
@@ -17644,11 +17649,17 @@ and
 .code let*
 with regard to this list of variables.
 
+The second variant in the above syntax synopsis shows that when
+.metn body-form s
+are absent, then a list of
+.metn inc-form s
+which is empty may be omitted from the syntax.
+
 The
 .code for
 and
 .code for*
-operators execute these steps:
+macros execute these steps:
 .RS
 .IP 1.
 Establish an anonymous block over the entire form, allowing
@@ -17697,16 +17708,6 @@ is evaluated in turn. Then, each
 is evaluated in turn and processing resumes at step 2.
 .RE
 
-.IP
-Furthermore, the
-.code for
-and
-.code for*
-operators establish an anonymous block,
-allowing the
-.code return
-operator to be used to terminate at any point.
-
 .coNP Macros @ doloop and @ doloop*
 .synb
 .mets ({doloop | doloop*}
-- 
cgit v1.2.3