cat-str/join/join-with: allow nested sequences

The measure/allocate/catenate functions which underlie
the cat-str implementation are streamlined, simplifying
the code. At the same time, they handle nested sequences
of string/character items.

* lib.c (struct cat_str): New member, seen_one. This flips
from 0 to 1 after the first item has been seen in the
cat_str_measure pass or cat_str_append pass. Each item
other than the first is preceded by a separator.
(cat_str_measure, cat_str_append): The more_p argument
is dropped. We account for the separator with the help
of the new seen_one flag, which allows us to easily
recurse over items that are sequences.
(cat_str_alloc): Reset the seen_one flag in preparation
for the cat_str_append pass.
(cat_str, vscat, scat2, scat3, join_with): Simplified.

* tests/015/split.tl: New tests.

* txr.1: Redocumented.

1 files changed, 30 insertions, 34 deletions

diff --git a/txr.1 b/txr.1
index 2342276d..ef53c99a 100644
--- a/txr.1
+++ b/txr.1
@@ -25644,12 +25644,17 @@ functions combine items into a single string, which is returned.
 
 Every
 .meta item
-argument must be a character or string object. The same is true of the
+argument must be a character, string or else a possibly empty
+sequence of items. This rule applies recursively.
+
+If a
 .meta sep
-argument, if present.
+argument is present, it must be a character or string.
+
 The
 .meta item-seq
-argument must be a sequence of any mixture of characters or strings.
+argument must be a sequence of any mixture of items which are
+characters, strings or sequences of items.
 Note that this means that if
 .meta item-seq
 is a character string, it is a valid argument, since it is a sequence
@@ -25662,47 +25667,38 @@ is empty, or no
 arguments are present, then all three functions return an
 empty string.
 
-The
+All three functions operate on an abstract sequence of character and string
+items, produced by a left-to-right recursive traversal of their
+.meta item-seq
+or
+.meta item
+arguments.
+
+Under the
+.code join-with
+function, as well as the
 .code cat-str
-function receives the items as a single list. If the
+function a
 .meta sep
-argument is present, the items are catenated together such that
+argument is given to it,
+the items are catenated together such that
 .meta sep
-is interposed between them. If
-.meta item-seq
-contains
+is interposed between them. If there are
 .I n
-items, then
+character or string items, then
 .I "n - 1"
 copies of
 .meta sep
-occur in the resulting string.
+occur in the resulting string, which is returned.
 
-If
-.meta sep
-is absent, then
-.code cat-str
-catenates the items together directly, without any separator.
-
-Copies of the items appear in the resulting string in the same
-order as the items appear in
-.metn item-seq .
-
-The
-.code join-with
-function receives the items as arguments rather than a single
-.meta item-seq
-arguments. The arguments are joined into a single character string
-in order, with
-.meta sep
-interposed between them.
-
-The
+Under the
 .code join
-function takes no
+function, or
+.code cat-str
+function invoked without a
 .meta sep
-argument. It joins all of its argument items into a single
-string, in order.
+argument, the items are catenated together directly, without any separator.
+The resulting string is returned.
 
 .coNP Function @ split-str
 .synb