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

[Glenn Morris <rgm@gnu.org>]

Eli Zaretskii wrote:

> Indeed.  But this issue does exist, and is real.  See, for example:
>
>   http://archives.miloush.net/michkap/archive/2005/10/17/481600.html
>
> (CompareString is what we use on MS-Windows to implement
> string-collate-equalp and string-collate-lessp.)

But no-one using Emacs will reason in this way.
"I want to compare if two files are the same.
I don't know about file-equal-p, so I will just do a string comparison
of the filenames.
I know that the MS Windows function to compare strings is CompareString.
Therefore I will see which Emacs function uses that.
Ah, it is string-collate-equalp.
Therefore I will use string-collate-equalp to compare two file names.
I won't use the more obvious string-equal, nor will I read the
documentation of string-collate-equalp, which makes it obvious that this
is wrong."


And suppose I have two strings, and want to know if they are equal,
respecting my locale's convention about characters that are not
literally identical, but have the same meaning. I should use
string-collate-equalp for this. This is true whether the strings
represent the names of elephants in a zoo, or files on a disk.