From 1ff1b51eee6bbf3042ee3a572f6e750ad1897590 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Thu, 21 Jan 2021 19:14:23 -0800
Subject: doc: document new check in iter-step.

* txr.1: Document recently introduced check against crossing
over into infinite iteration on the terminator of an improper
list.
---
 txr.1 | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

(limited to 'txr.1')

diff --git a/txr.1 b/txr.1
index e4e224b9..90de24f1 100644
--- a/txr.1
+++ b/txr.1
@@ -34367,7 +34367,42 @@ cell, then
 .code iter-step
 returns the
 .code cdr
-field of that cell.
+field of that cell. That value must itself be a
+.code cons
+or else
+.codn nil ,
+otherwise an error is thrown. This is to prevent iteration
+from wrongly iterating into the non-null terminators of improper
+lists. Without this rule, iteration of a list like
+.code "(1 2 . 3)"
+would reach the
+.code cons
+cell
+.code "(2 . 3)"
+at which point a subsequent
+.code iter-step
+would return the
+.code cdr
+field
+.codn 3 .
+But that value is a valid iterator which will then continue by
+stepping through
+.codn 4 ,
+.code 5
+and so on.
+
+If
+.meta iter
+is a list-like sequence, then
+.code cdr
+is invoked on it and that value is returned.
+The value must also be a list-like sequence, or else
+.codn nil .
+The reasoning for this is the same as for the similar
+restriction imposed in the case when
+.meta iter
+is a
+.codn cons .
 
 If
 .meta iter
-- 
cgit v1.2.3