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

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Stefan Kangas <stefankangas@gmail.com>,  73709@debbugs.gnu.org,
>   drew.adams@oracle.com
> Date: Fri, 11 Oct 2024 02:41:40 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > IOW, the addition I just made per your request breaks the (useful,
> > IMO) abstraction we had.
> 
> If you had an abstraction it should be possible to describe it.

It _was_ described.  "Newer" is a simple word that everyone should
understand.  If "newer" is still not enough understood, we should have
discussed how to make it more clear without leaking the abstraction.

> This is actually what I wanted.  The problem with what we had was
> that people who did not yet know the abstraction could read
> something different than intended.

No, the request was explicitly to add specific technical details about
how we implement the abstraction.  Which is what we have now, and I
think it's a step in the wrong direction.

> > For what good reasons?
> 
> One reason was that I had misunderstood the docstring and that this may
> happen to others.  I really would like to know why that doesn't count as
> a reason.

Because the request was to address the misunderstanding by exposing
the details of the implementation.  Once we start talking about file
creation time vs file modification time (and don't forget file
last-access time), we are not clarifying the abstraction, we are
leaking the details of the implementation.

Maybe I was mistaken in my interpretation of the request, but then
please re-read the thread and point me to the part where the request
was something other than explicitly mention the file's mtime in the
doc string and the manual.