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

[Eli Zaretskii <eliz@gnu.org>]

> From: Glenn Morris <rgm@gnu.org>
> Cc: oscarfv@telefonica.net (Óscar Fuentes),
>   michael_heerdegen@web.de,  23902@debbugs.gnu.org
> Date: Sat, 09 Jul 2016 13:06:57 -0400
> 
> 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."

No, no one will reason this way.

But they can reason this way instead:

"I want to compare two file names.
Collation is a way to compare strings, for example the man page for
strcoll says the function returns zero if one string is equal to the
other.
And Emacs just learned how to use collation to compare strings, it
has this great new function string-collate-equalp.
Therefore, let's use string-collate-equalp for comparing two file
names."

> 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.

And that is exactly the fallacy that the note warns against.  Because
filesystems don't compare as equal characters that have the same
meaning, they compare bytes in a byte stream that is the file name in
its raw byte form, as recorded on disk.