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

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 73709@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Fri, 11 Oct 2024 02:23:09 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > Apart from that: if it is hard or not practical to describe what the
> > > function returns in every case, we can instead try to describe major
> > > use cases.
> >
> > That'd mean a lot of text to write to describe what should be clear
> > enough, at least as far as Emacs is concerned.  I don't think it's our
> > job to describe how the various filesystems work.
> 
> This is not what I suggested.  My suggestion was to tell something like
> "For example, this function is used to check whether a file should be
> restored from an auto-safe file, or needs to be recompiled".  This is
> possible without describing how filesystems work, or how quantum
> chromodynamics work.

I'm okay with adding examples that people think might be useful, if
all we do is mention them without going into details too much.  To me,
the 2 examples you mention sound almost trivial, but I nevertheless
won't object to add some short text with such examples, if they help
someone better understand the purpose of the function.

> > Very well, but please remember your opinions in this matter, because
> > if someone comes up asking for more details about "last modification
> > times" (perhaps even Drew himself, e.g. because someone asked some
> > question on SE), I will defer to you and Stefan to deal with the
> > fallout.
> 
> When you say "[...] should be clear enough": are you sure that the
> misinterpretation as "file creation time" only can happen to me and to
> Drew - because we are exceptionally stupid Emacs users?

There's nothing stupid about that.  Moreover, in some subtle
situations this will be the exact meaning of "file newer".  My point
is different: that Lisp programmers should not think about this in
terms of file attributes returned by the 'stat' system call, but as a
higher-level abstraction.

> If not: do you have any better idea?

Better idea about what?

> And: Sure can you ask for my help, but, with all respect, please not in
> such a way, Eli.

Sigh.  Why do you have to interpret what I write in the worst possible
way?  It's possible that my dry humor is sometimes too dry, but
there's nothing other than dry humor in what I wrote above.  I'd
expect everyone here would recognize that by now, but I guess not...