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

From: Eli Zaretskii <[email-masked]>
Date: Sun, 13 Oct 2024 21:30:31 +0300

> From: Drew Adams <[email-masked]>
> CC: "[email-masked]" <[email-masked]>,
>         "[email-masked]" <[email-masked]>
> Date: Sun, 13 Oct 2024 17:01:04 +0000
> 
> > It's short and clear, but it's inaccurate.  E.g., how to define
> > "content newer" when both files have the same content (like if one of
> > them is a copy of the other)?
> 
> That and other details should be available from
> `file-attribute-modification-time', if important at
> all (which is why it can be good to point to the doc
> of that attribute).

Except that we also have set-file-times, which can make the file seem
as if it was "last modified" at a different time.

>  (elisp) `File Attributes':
>  5. The time of last modification as a list of four integers
>     (as above) ('file-attribute-modification-time').  This
>     is the last time when the file's contents were modified.
>                               ^^^^^^^^^^^^^^^

The problem here is with the term "contents were modified".  It is not
explained, and its naïve interpretation will lead to inaccurate
conclusions, for example when a file was copied.

You can deny the complexity as much as you want, and you can quote
text from documentation as long as you want, but the simple fact is
that the concept of being "newer" is not easy to explain in detail.
Alluding to file's attributes doesn't solve the problem; instead, it
makes it more complicated and harder to explain without going into a
very low level of how filesystems work (and that's even before we
consider the differences in how the different filesystems supported by
Emacs work in this regard).

> You repeat that it's ALL OR NOTHING, claiming both (1)
> the current doc is fine - clear enough and (2) anything
> other than 100% complete information/clarity/details is
> no better.

I do?  Then how come I changed the doc string at least twice in the
recent days?