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

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 9 Oct 2024 23:42:30 +0000
> Cc: 73709@debbugs.gnu.org, drew.adams@oracle.com
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > 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"?
> 
> On GNU/Linux (actually POSIX) systems, we have atime/ctime/mtime.

Actually, modern Posix filesystems have much more than that.

> The word "newer" does not make it clear if we mean ctime or mtime.

Why does it matter?  Emacs Lisp programs should not care about these
details.  Emacs offers APIs that are not direct channels to calling a
Posix system call.  Emacs offers additional abstractions that are
supposed to protect the caller Lisp programs from too much low-level
and system-dependent stuff.  Seeping system-dependent details into our
documentation goes in the opposite direction.

If people want Lisp bindings of system calls, they should use Guile,
not Emacs.

> The phrasing "last modification time" makes it clear that we're talking
> about mtime.  This phrase is already used further down in (info "(elisp)
> File Attributes"), and should be equally good here.

I think you are mistaken, but let's let time judge who is right.

> > 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?
> 
> I don't see a need for the Elisp manual to explain these details.

Neither do I, but for different reasons.

> Users that need to know such things in detail will have to refer to
> other platform-relevant documentation, such as the POSIX standard:
> 
> https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap04.html#tag_04_12

How do we expect someone to write portable Lisp programs based on that
technobabble?

If the call to file-newer-than-file-p does not live up to its contract
in some situation or doesn't fit people's expectations that are based
on the documentation, I expect people to submit bug reports about
their expectations not being met, and demand us to fix the
implementation.  Suppose that on some filesystem FILE1 was created
after FILE2, but file-newer-than-file-p does NOT return t for FILE1.
With the previous doc string people could tell us the function was
broken in that case, whereas with the current "fixed" doc string we
could tell them that since the mtime told us FILE1 was not newer, we
are okay, and this is not a bug.  Does this sound reasonable for
Emacs?  I think not.

IOW, the addition I just made per your request breaks the (useful,
IMO) abstraction we had.  For what good reasons?