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

[Eli Zaretskii <eliz@gnu.org>]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: drew.adams@oracle.com,  73709@debbugs.gnu.org
> Date: Wed, 16 Oct 2024 06:11:41 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > "Last saved" assumes the file is edited, but this function doesn't
> > care whether a file has been edited.  "Last written to" might be
> > better.
> 
> Ok - "last written" then.
> 
> > But the problem for which I find no good solution is that there are
> > ways to make the filesystem lie to us about when was file last written
> > to: use set-file-times in Emacs or the 'touch' shell command or
> > anything similar.
> 
> Sure.  But I thought we want to explain the abstraction?  So, if you
> don't want to lie, why not say "in general this means the times when the
> files were last written" or so?  As you said we _don't_ want to go to
> the level of implementation and file system specific details - so why
> discuss them at all?  There are always details a short description
> doesn't cover ("newer" also didn't cover them).
> 
> Of course you can add that "details depend on capabilities and features
> of the used file system and the chosen implementation (Tramp)".  We do
> say similar things in other docstrings, too.

Two issues:

  . "last written to" is incorrect if that time stamp was modified by
    set-file-times and similar methods
  . the interpretation of mtime to mean "newer" (per the function's
    name) is problematic/incorrect when a file is copied with the
    KEEP-TIME argument of copy-file (and similar facilities of other
    commands, like 'cp')

I'm asking whether we care about these subtleties.  E.g., someone
might claim that the second issue above means that
file-newer-than-file-p has a bug.

The current doc string says simply that last-modification times are
compared, and I wonder if that is not better left alone.