doc: explain dot position of variable in predicate.

* txr.1: Explain that the dot position of a variable in a
predicate pattern corresponds to the usual application
syntax. Add an example of this from the test case file.

1 files changed, 23 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index d00ca2d8..ae62ba3e 100644
--- a/txr.1
+++ b/txr.1
@@ -40784,6 +40784,25 @@ and is processed accordingly. Similarly,
 is equivalent to
 .codn "@(@y (dwim f @x))" .
 
+The dot position of
+.meta avar
+in the predicate syntax denotes function application. So that is to say, the
+pattern predicate form
+.code "(f . @a)"
+where
+.code @a
+is in the dotted position invokes the function
+.code f
+as if by evaluation of the form
+.code "(f . x)"
+where
+.code x
+is hidden temporary variable holding the object corresponding to the pattern.
+The form
+.code "(f . x)"
+is a standard \*(TL notation with the same meaning as
+.codn "(apply (fun f) x)" .
+
 .TP* Examples:
 
 .verb
@@ -40804,6 +40823,10 @@ is equivalent to
   (let ((h #H(() (a 1) (b 2))))
     (when-match @(@y [h @x]) 'a (list x y)))
   -> (a 1)
+
+  ;; apply (1 2 3) to < using dot position
+  (when-match @(@x (< . @sym)) '(1 2 3) (list x sym))
+ - > (t (1 2 3))
 .brev
 
 .coNP Macros @ when-match and @ if-match