bug#73709: 29.4; Doc of `file-newer-than-file-p'

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Drew Adams <drew.adams@oracle.com>,
>   "73709@debbugs.gnu.org" <73709@debbugs.gnu.org>
> Date: Wed, 09 Oct 2024 02:45:44 +0200
> 
> Drew Adams via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" <bug-gnu-emacs@gnu.org> writes:
> 
> > It's not about any implementation details.  It's about
> > what's meant here by "newer".  And the answer is that
> > it's about the recentness of the last modification.
> 
> It's not obvious that the time that a file existed is not meant.
> Creation time is what came to my mind, and I find the actual meaning a
> bit surprising.  Maybe I even didn't use this function where I should
> have and reinvented the thing because of a wrong expectation.  So a +1
> from me for trying to make it clearer.

Are you sure this is a good idea?  If the user who reads the doc
string doesn't know the meaning of "the file is newer", how can we be
sure she knows the meaning of "file's last modification time"?  What
is "last modification"? does changing the file's mode bits constitute
"modification"? does renaming the file or moving it to another
directory constitute "modification"? what is the meaning of "last
modification time" of a directory? etc. etc. -- do we have now to
explain all of that in our documentation?  And if we don't explain
that, what exactly did we gain? replacement of one allegedly unclear
term by another?