doc: clarify that ftw takes a list or path.

* txr.1: Make it clearer that ftw operates on a list; that
fact was too buried in the documentation.

1 files changed, 46 insertions, 50 deletions

diff --git a/txr.1 b/txr.1
index ee97aaf7..98d474a8 100644
--- a/txr.1
+++ b/txr.1
@@ -53567,7 +53567,7 @@ et cetera.
 
 .coNP Function @ ftw
 .synb
-.mets (ftw < path < callback-func >> [ flags <> [ nopenfd ]])
+.mets (ftw < path-or-list < callback-func >> [ flags <> [ nopenfd ]])
 .mets >> [ callback-func < path < type < stat-struct < level << base ]
 .syne
 .desc
@@ -53588,17 +53588,54 @@ defaults to zero, and
 .meta nopenfd
 defaults to 20.
 
-Also note that, unlike in the C function, multiple
-paths may be processed by passing a list
-for the
-.meta path
-argument.
+The
+.meta path-or-list
+argument may be a string specifying the top-level path name that
+.code ftw
+shall visit. Or else,
+.meta path-or-list
+may be a list. If it is a list, then
+.code ftw
+recursively invokes itself over each of the elements, taking
+that element as the
+.meta path-or-name
+argument of the recursive call, passing down all other argument
+values as-is.
+The traversal stops when any recursive invocation of
+.code ftw
+returns a value other than
+.code t
+or
+.codn nil ,
+and that value is returned. If
+.code t
+or
+.code nil
+is returned, the traversal continues with the
+application of
+.code ftw
+to the next list element, if any.
+If the list is completely traversed, and some recursive
+invocations of
+.code ftw
+return
+.codn t ,
+then the return value is
+.codn t .
+If all recursive invocations return
+.code nil
+then
+.code nil
+is returned.
+If the list is empty,
+.code t
+is returned.
 
 The
 .code nftw
 function walks the filesystem, as directed by the
-.meta path
-string and
+.meta path-or-list
+argument and
 .meta flags
 bitmask arguments.
 
@@ -53623,7 +53660,7 @@ stops the traversal.  (Non-integer return values behave like
 The
 .meta path
 argument of the callback function gives the path of the
-visited filesystem object. 
+visited filesystem object.
 
 The
 .meta type
@@ -53676,47 +53713,6 @@ is terminated by a return value from
 .metn callback-func ,
 then that value is returned. Such a value is always a nonzero integer.
 
-If the
-.meta path
-passed to
-.code ftw
-is a list, then all of the paths contained in that
-list are walked, as if by recursive application of
-.code ftw
-to each element of the list taken as the
-.meta path
-argument, the other argument values being the same.
-The traversal stops when any recursive
-invocation of
-.code ftw
-returns a value other than
-.code t
-or
-.codn nil ,
-and that value is returned. If
-.code t
-or
-.code nil
-is returned, the traversal continues with the
-application of
-.code ftw
-to the next list element, if any.
-If the list is completely traversed, and some recursive
-invocations of
-.code ftw
-return
-.codn t ,
-then the return value is
-.codn t .
-If all recursive invocations return
-.code nil
-then
-.code nil
-is returned.
-If the list is empty,
-.code t
-is returned.
-
 The
 .meta callback-func
 may terminate the traversal by a nonlocal exit, such as by throwing