bug#41706: 26.1; sort-subr predicate cannot be set successfully

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 4 Jun 2020 21:05:26 +0200
> From: Marvin Gülker <post+ebugs@guelker.eu>
> Cc: 41706@debbugs.gnu.org
> 
> >To understand how ‘sort-subr’ works, consider the whole accessible
> >portion of the buffer as being divided into disjoint pieces called
> >“sort records”.  The records may or may not be contiguous, but they
> >must not overlap.  A portion of each sort record (perhaps all of
> >it) is designated as the sort key. [...]
> >The argument PREDICATE is the function to use to compare keys.  If
> >keys are numbers, it defaults to ‘<’; otherwise it defaults to
> >string<’.
> 
> No further mention of how to use PREDICATE is made, and the manual 
> continues with reproducing the source code of `sort-lines'. I took that 
> section to mean that the PREDICATE is in the default case `<' and 
> with strings `string<'. From the manual's text it became not clear to me 
> under which condition the keys are not strings, and I assumed they will 
> normally always be strings as buffer substrings are always strings.
> 
> Now I see that the documentation for the `sort-subr' function is a 
> little more specific, but still it doesn't really make clear which kind 
> of "key" is received as arguments in the PREDICATE under which 
> conditions. The call above appearently yields cons cell keys whose CAR 
> and CDR correspond to buffer positions, but the documentation makes me 
> suspect that calling `sort-subr' differently will yield other kinds of 
> keys.
> 
> I would suggest to amend the manual to be more precise about the 
> arguments that PREDICATE receives, and perhaps add an example.

It is hard to be specific about the arguments to PREDICATE, because
they depend on what the other arguments to sort-subr return.  I
augmented the manual to at least have the same information as the doc
string; more detail is only possible if we discuss specific values of
STARTKEYFUN and ENDKEYFUN.

Thanks.