From c0379ca87158d3ea015cfb88a9968ab460368f83 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Thu, 16 Nov 2017 20:33:37 -0800
Subject: doc: pos-max, find-max: notes about multiple maxima.

* txr.1: mention that the rightmost maximum can be found by
manipulating the comparison function. (Hence, this is why
we don't provide rpos-max and rfind-max).
---
 txr.1 | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/txr.1 b/txr.1
index 26bc2051..4ca6929a 100644
--- a/txr.1
+++ b/txr.1
@@ -26808,6 +26808,23 @@ from
 is passed through this one-argument function, and
 the resulting value is used in its place.
 
+If a sequence contains multiple equivalent maxima,
+whether the position of the leftmost or rightmost such maximum is reported
+depends on whether
+.meta testfun
+compares for strict inequality, or whether it reports true for
+equal arguments also. Under the default
+.metn testfun ,
+which is
+.codn less ,
+the
+.code pos-max
+function will return the position leftmost of a duplicate set of maximum
+elements. To find the rightmost of the maxima, the
+.code lequal
+function can be substituted. Analogous reasoning applies to other
+test functions.
+
 .coNP Function @ mismatch
 .synb
 .mets (mismatch < left-seq < right-seq >> [ testfun <> [ keyfun ]])
@@ -27605,6 +27622,14 @@ To find the entry holding the maximum value, the
 .code cdr
 function can be specified.
 
+If there are multiple equivalent maxima, then under the default
+.metn testfun ,
+that being
+.codn less ,
+the leftmost one is reported. See the notes under
+.code pos-max
+regarding duplicate maxima.
+
 .coNP Functions @, uni @ isec and @ diff
 .synb
 .mets (uni < seq1 < seq2 >> [ testfun <> [ keyfun ]])
-- 
cgit v1.2.3