emacs-27 bf09106: Improve documentation of 'sort-subr'

[Eli Zaretskii]

branch: emacs-27
commit bf09106256f9212d3162a4335c18fd2ef876066d
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of 'sort-subr'
    
    * doc/lispref/text.texi (Sorting): Clarify the meaning and use of
    PREDICATE argument to 'sort-subr'.  (Bug#41706)
---
 doc/lispref/text.texi | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a14867e..0bbb0aa 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -2028,8 +2028,15 @@ non-@code{nil} value.
 @end enumerate
 
 The argument @var{predicate} is the function to use to compare keys.
-If keys are numbers, it defaults to @code{<}; otherwise it defaults to
-@code{string<}.
+It is called with two arguments, the keys to compare, and should
+return non-@code{nil} if the first key should come before the second
+in the sorting order.  What exactly are the key arguments depends on
+what @var{startkeyfun} and @var{endkeyfun} return.  If @var{predicate}
+is omitted or @code{nil}, it defaults to @code{<} if the keys are
+numbers, to @code{compare-buffer-substrings} if the keys are cons
+cells (whose @code{car} and @code{cdr} are start and end buffer
+positions of the key), and to @code{string<} otherwise (with keys
+assumed to be strings).
 
 As an example of @code{sort-subr}, here is the complete function
 definition for @code{sort-lines}: