From 9a8da964a294feceda8ff5d5f81ecc4a4937cd02 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Wed, 7 May 2025 20:11:07 -0700
Subject: infix: expose and document finish-infix.

* autoload.c (infix_set_entries): intern finish-infix
in the usr package, and trigger autoload on it.

* txr.1: Documented existence and purpose of finish-infix.
---
 autoload.c |  2 +-
 txr.1      | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/autoload.c b/autoload.c
index c24b3a14..8ebc5db0 100644
--- a/autoload.c
+++ b/autoload.c
@@ -1002,7 +1002,7 @@ static val enum_instantiate(void)
 static val infix_set_entries(val fun)
 {
   val name[] = {
-    lit("parse-infix"), lit("ifx"),
+    lit("parse-infix"), lit("finish-infix"), lit("ifx"),
     nil
   };
   val name_noload[] = {
diff --git a/txr.1 b/txr.1
index 5784d7ac..e8781921 100644
--- a/txr.1
+++ b/txr.1
@@ -55192,6 +55192,11 @@ after which this structure is recognized, and transformed into
 
 which has a completely different, and useful meaning.
 
+The parse is performed by the function
+.codn parse-infix ,
+and the subsequent transformation by the function
+.codn finish-infix .
+
 Note that in this depiction of the transformation, the terms
 .codn d ,
 .code e
@@ -55467,6 +55472,47 @@ it transforms it to
 in order to mark it as an external, non-infix expression that was
 integrated into the output.
 
+.coNP Function @ finish-infix
+.synb
+.mets (finish-infix << expr )
+.syne
+.desc
+The
+.code finish-infix
+traverses the expression
+.code expr
+which is expected to be an object returned by
+.codn parse-infix .
+It performs certain transformations, namely the processing
+described in a preceding section
+.B "Compound Relational Expressions"
+as well as the recognition and removal of annotations, produced by
+.code parse-infix
+of unprocessed compound expressions.
+
+Because
+.code parse-infix
+does not recurse into compound expressions, handling the input as
+a linear sequence of elements, the output of
+.code parse-infix
+may contain unexpanded infix expressions, protected by annotations.
+In that situation, the output of
+.code finish-infix
+also contains unexpanded infix expressions.
+
+Note: the
+.code ifx
+macro makes use of both
+.code parse-infix
+and
+.code finish-infix
+infix to process expressions which are indicated infix processing
+by the infix auto-detection rules. The
+.code ifx
+macro establishes an expansion strategy which will traverse the output of
+.code finish-infix
+to identify and expand nested infix expressions.
+
 .coNP Macro @ ifx
 .synb
 .mets (ifx << form *)
-- 
cgit v1.2.3