doc: functions apply to arguments not vice versa.

* txr.1: Fix numerous instances of text which uses the wording
that arguments are applied to a function. A few of the changes
repair wording that was entirely botched.

1 files changed, 32 insertions, 27 deletions

diff --git a/txr.1 b/txr.1
index ea96de7b..3e8ff28d 100644
--- a/txr.1
+++ b/txr.1
@@ -14699,8 +14699,8 @@ as well as the related convenience macros
 and
 .codn usl .
 
-If a function is needed which partially applies some arguments
-to the method invoked on a specific object, the
+If a function is needed which partially applies,
+to some arguments, a method invoked on a specific object, the
 .code method
 function or
 .code meth
@@ -14867,11 +14867,11 @@ function invokes
 passing it the given arguments, if any.
 
 .TP* Examples:
-Apply arguments
-.code "1 2"
-to a
+Apply
 .code lambda
-which adds them to produce
+to
+.code "1 2"
+arguments, adding them to produce
 .codn 3 :
 
 .verb
@@ -23368,8 +23368,9 @@ function rather than
 Note: it is permissible for
 .meta item
 objects to specify infinite ranges.
-It is also permissible to apply an infinite argument list to
-.codn rlist .
+It is also permissible to apply
+.code rlist
+to an infinite argument list.
 
 .TP* Examples:
 .verb
@@ -48864,7 +48865,7 @@ found, it returns
 A regex takes one, two, or three arguments. The required
 .meta string
 is always the rightmost argument. This allows for convenient
-partial application of the optional arguments using
+partial application over optional arguments using
 macros in the
 .code op
 family, and macros in which the
@@ -52416,8 +52417,9 @@ and does not contain
 .codn @rest ,
 it is actually a shorthand for
 .codn "(op foo . @rest)" :
-a function which applies all of its arguments to
-.codn foo .
+a function which applies
+.code foo
+to all of its arguments.
 If the body does contain at least one
 .meta @num
 or
@@ -52839,9 +52841,12 @@ macro.  However, instead of returning
 .metn f ,
 directly, it returns a different function
 .metn g ,
-which is a one-argument function  which accepts a list,
-and then applies the list as arguments to
-.metn f .
+which is a one-argument function that accepts a list.
+The list specifies arguments to which
+.meta g
+applies
+.metn f ,
+and then returns the resulting value.
 
 In other words, the following equivalence holds:
 
@@ -52886,8 +52891,8 @@ and
 are related to
 .codn op .
 They produce a one-argument function which works
-as if by applying its arguments to the function generated by do,
-according to the following equivalence:
+as if by applying the function generated by do to its
+its own arguments, according to the following equivalence:
 
 .verb
   (ado form ...) <--> (apf (do form ...))
@@ -53534,9 +53539,9 @@ function returns a one-argument function whose argument conventions
 are similar to those of the
 .code apply
 function: it accepts one or more arguments, the last of which should
-be a list.  When that function is called, it applies these arguments to
+be a list.  When that function is called, it applies
 .meta function
-as if by
+to these arguments to as if by
 .codn apply .
 It then returns whatever
 .meta function
@@ -53558,11 +53563,10 @@ The
 .code ipf
 function is similar to
 .codn apf ,
-except that the argument conventions of the function returned by
+except that the argument conventions and application semantics of the function
+returned by
 .code ipf
 are based on
-.codn iapply ,
-and that function applies arguments as if by
 .code iapply
 rather than
 .codn apply .
@@ -53588,11 +53592,12 @@ macro.
 .desc
 The
 .code callf
-function returns a function which applies its arguments to each
-.metn arg-function ,
-juxtaposing the return values of these calls to form arguments
-which are then passed to
-.metn main-function .
+function returns a function which applies each
+.meta arg-function
+to its arguments, juxtaposing the return values of these calls to form
+arguments to which
+.meta main-function
+is then applied.
 The return value of
 .meta main-function
 is returned.
@@ -55795,7 +55800,7 @@ argument specified, it overrides this default. In that situation,
 the specified mode should permit reading.
 
 These streams are turned
-into a catenated stream as if applied as arguments to
+into a catenated stream as if they were the arguments of a call to
 .codn make-catenated-stream .
 
 The effect is that multiple files appear to be catenated together into a single