bug#23902: 25.1.50; Strange warning on string-collate-equalp's docstring

[Michael Heerdegen <michael_heerdegen@web.de>]

Eli Zaretskii <eliz@gnu.org> writes:

> As with any such notes in doc strings, we warn about popular mistakes
> that people make frequently.  Trying to compare file names using this
> function is such a mistake.  Any string that is actually a kind of
> handle to a system object, for which the system itself uses binary
> comparison, will do as an example of such a mistake, but doing that
> with file names is a common enough example to warrant mentioning.

I also have trouble to understand.  How can I compare file names modulo
collate-equality, if not with this function?

> > And then, how one is supposed to use an
> > equality predicate for sorting? (We have string-collate-lessp for that)
>
> A sorting algorithm can have its own ideas what to do when
> string-collate-lessp returns zero.

But we are speaking about the docstring of `string-collate-equal-p'.  It
is not clear here how it (as an equivalence predicate) could be useful
for sorting at all.


Michael.