Subject: RE: [External] : Re: bug#73709: 29.4; Doc of `file-newer-than-file-p'

From: Drew Adams <[email-masked]>
Date: Sun, 13 Oct 2024 14:51:19 +0000

1. Doc string suggestion, first line:

"Return t if content of FILE1 is newer than content of FILE2."

Short and clear.  (If you want shorter yet: use "that" instead
of the second "content" - but that's slightly less clear.)

[A better name for it would have been `file-content-newer-p'.
The second "file" in the name isn't needed, as we're clearly
comparing the two args, which are both files.]

2. For the rest of the doc string, consider replacing "the
answer is" with "return" (both places).

3. The argument that "Lisp programmers should not think about
this in terms of file attributes returned by the 'stat' system
call" is misdirected.  No one suggested they should.

Just pointing readers to `file-attribute-modification-time'
doesn't cause them to think that way.  Mentioning it wouldn't
hurt, but help.  It makes clear _exactly_ what's compared.

4. But whether or not `file-attribute-modification-time' is
mentioned isn't important.  The point is that "newer" alone
isn't clear.  It's like "bigger" - mass? volume? height?
width? depth?

It's about WHAT'S newer - just _what_ about the two files is
compared wrt time/newness?  Answer: their _content_ (at a
reasonable approximation).  Not shorter file life, nor a
measure of file metadata, etc.

5. FWIW, "newer" is accurate.  I wasn't sure whether the
test might actually be newer-or-the-same (IOW test, in fact,
whether the content of FILE2 is older).  So I tried passing
the same file as both args, and got nil - "newer" is the
right word.  This might not be obvious to all readers, but
it's easy enough for them to find out as I did.