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

From: Eli Zaretskii <[email-masked]>
Date: Thu, 10 Oct 2024 11:09:57 +0300

> From: Michael Heerdegen <[email-masked]>
> Cc: [email-masked],  [email-masked]
> Date: Thu, 10 Oct 2024 01:21:40 +0200
> 
> Eli Zaretskii <[email-masked]> 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"? [...]
> 
> I had a look what my find(1) man page says about the command line option
> "-newer":
> 
> | Time of the last data modification of the current file is more recent
> | than that of the last data modification of the reference file.

That is not accurate, as I hinted previously.  What constitutes
"file's data" is vague and system-dependent.

> I think something like this is better than saying nothing, and worse
> than telling all details.

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.

> 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.