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

[Óscar Fuentes]

Eli Zaretskii <eliz@gnu.org> writes:

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

This implies that the user knows about string comparisons with collation
but he is a complete ignoramus about file systems. A bit unrealistic.

Anyway, saying "don't use this for comparing file names" is cryptic.
Mentioning file-equal-p would be helpful if you insist on mentioning
file names on the docstring of string-collate-equalp.

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

I think that Glenn is saying that you can compare file names for other
purposes than knowing if they name the same file.

Maybe the user wishes to find a file with a given name, modulo
collation. Search for "tu.txt" and find "tú.txt".