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

[Eli Zaretskii]

> From: oscarfv@telefonica.net (Óscar Fuentes)
> Date: Wed, 06 Jul 2016 00:05:57 +0200
> 
> The mentioned docstring ends with
> 
>      Do _not_ use this function to compare file names for equality, only
>      for sorting them.
> 
> which makes no sense to me. First of all, what's so special about file
> names to mention them here?

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.

> 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.  In any case, the important part
here is not to use this function for file-name comparison.