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

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Neither the doc string nor the Elisp manual (node File Attributes) says
what is meant by a file being "newer" than another.  A guess is that
this is about last file modification time, but one could think it's
about file creation time etc.

Please clarify the meaning.


In GNU Emacs 29.4 (build 2, x86_64-w64-mingw32) of 2024-07-05 built on
 AVALON
Windowing system distributor 'Microsoft Corp.', version 10.0.19045
System Description: Microsoft Windows 10 Pro (v10.0.2009.19045.4894)

Configured using:
 'configure --with-modules --without-dbus --with-native-compilation=aot
 --without-compress-install --with-sqlite3 --with-tree-sitter
 CFLAGS=-O2'

Configured features:
ACL GIF GMP GNUTLS HARFBUZZ JPEG JSON LCMS2 LIBXML2 MODULES NATIVE_COMP
NOTIFY W32NOTIFY PDUMPER PNG RSVG SOUND SQLITE3 THREADS TIFF
TOOLKIT_SCROLL_BARS TREE_SITTER WEBP XPM ZLIB

(NATIVE_COMP present but libgccjit not available)

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

[Eli Zaretskii]

tags 73709 notabug wontfix
close 73709
thanks

> Date: Tue, 8 Oct 2024 17:56:44 +0000
> From:  Drew Adams via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> Neither the doc string nor the Elisp manual (node File Attributes) says
> what is meant by a file being "newer" than another.  A guess is that
> this is about last file modification time, but one could think it's
> about file creation time etc.
> 
> Please clarify the meaning.

"Newer" means newer, in its literal meaning.  How this translates into
the file's attributes (if that is not obvious) is implementation
details.

There's no need to and no sense in "clarifying" in our documentation
the meaning of words which are used literally.

Closing.

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> tags 73709 notabug wontfix
> close 73709
> thanks
> 
> > Date: Tue, 8 Oct 2024 17:56:44 +0000
> > From:  Drew Adams via "Bug reports for GNU Emacs,
> >  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> >
> > Neither the doc string nor the Elisp manual (node File Attributes) says
> > what is meant by a file being "newer" than another.  A guess is that
> > this is about last file modification time, but one could think it's
> > about file creation time etc.
> >
> > Please clarify the meaning.
> 
> "Newer" means newer, in its literal meaning.  How this translates into
> the file's attributes (if that is not obvious) is implementation
> details.
> 
> There's no need to and no sense in "clarifying" in our documentation
> the meaning of words which are used literally.
> 
> Closing.

It's not about any implementation details.  It's about
what's meant here by "newer".  And the answer is that
it's about the recentness of the last modification.

What's newer?  That's the question.  Assuming a "literal"
meaning of "newer" doesn't help at all.  What kind of
newness?  Check a thesaurus for "newer"/"new".  E.g.:

  "Having just (or relatively recently) come into
   being or been made or acquired or discovered"

  "Recently created or having started to exist recently"

That's about _creation_, not modification.

You have a 2024 Ferrari, just out of the showroom -
never been touched.  I have a 1998 Toyota, with recent
modifications/repairs.

Which is "newer"?  According to what you feel is obvious,
it's my '98 Toyota that's newer: more recently modified -
more recent last modification.

And besides time of last file modification, there are file
creation time, last access time, and last status-change time.

Please make the minor clarification that lets users know
that this is about last-modification date.  It won't take
much time.

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Drew Adams via "Bug reports for GNU Emacs, the Swiss army knife of text
editors" <bug-gnu-emacs@gnu.org> writes:

> It's not about any implementation details.  It's about
> what's meant here by "newer".  And the answer is that
> it's about the recentness of the last modification.

It's not obvious that the time that a file existed is not meant.
Creation time is what came to my mind, and I find the actual meaning a
bit surprising.  Maybe I even didn't use this function where I should
have and reinvented the thing because of a wrong expectation.  So a +1
from me for trying to make it clearer.

I know already saving files may create a new file and rename the
existing one to a backup name - or keep the file etc.  But anyway, let's
at least say that creation time is not meant, but most of the time, last
file modification.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Eli Zaretskii <eliz@gnu.org>,  Drew Adams <drew.adams@oracle.com>,
>   "73709@debbugs.gnu.org" <73709@debbugs.gnu.org>
> Date: Wed, 09 Oct 2024 02:45:44 +0200
> 
> Drew Adams via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" <bug-gnu-emacs@gnu.org> writes:
> 
> > It's not about any implementation details.  It's about
> > what's meant here by "newer".  And the answer is that
> > it's about the recentness of the last modification.
> 
> It's not obvious that the time that a file existed is not meant.
> Creation time is what came to my mind, and I find the actual meaning a
> bit surprising.  Maybe I even didn't use this function where I should
> have and reinvented the thing because of a wrong expectation.  So a +1
> from me for trying to make it clearer.

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"?  What
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?  And if we don't explain
that, what exactly did we gain? replacement of one allegedly unclear
term by another?

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> > > It's not about any implementation details.  It's about
> > > what's meant here by "newer".  And the answer is that
> > > it's about the recentness of the last modification.
> >
> > It's not obvious that the time that a file existed is not meant.
> > Creation time is what came to my mind, and I find the actual meaning a
> > bit surprising.  Maybe I even didn't use this function where I should
> > have and reinvented the thing because of a wrong expectation.  So a +1
> > from me for trying to make it clearer.
> 
> 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"?  

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

Yes, it could be interpreted to mean a change to file
permissions or other things, rather than a content
change or a change by `touch'.  That's why we have a
complete, rigorous description of attribute
`file-attribute-modification-time'.

If you feel it's needed, you can add a link to that
description/definition.  If you feel linking to that
description is point to the "implementation", and you
don't want to do that, then don't.

> -- do we have now to
> explain all of that in our documentation?

The relevant question is what we need to explain in the
doc string of `file-newer-than-p'.  The rest is already
explained well enough elsewhere in our doc (the manual).

The doc of `file-newer-than-file-p' should be clearer
than just "newer", to give some indication that it's
about the last modification of the file content.  That's
all.  If necessary, it can link to the more precise
explanation.

IOW, you needn't go to the extreme of saying that we
would need to explain everything in the doc of
`file-newer-than-file-p'.  All that's needed for that
doc is something a bit clearer than just saying that
it's about a file's "newness".

> And if we don't explain that, what exactly did we gain?
> replacement of one allegedly unclear term by another?

By another that's less unclear - yes.  It's a matter of
degree.

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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"? [...]

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.

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

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.  For example, checking whether an auto save file has to be
restored, or whether a file has to be recompiled.  Then the user would
probably have an idea about what this is about even without any
background knowledge and implementation details.  At least a
misunderstanding would be less likely.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 73709@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Thu, 10 Oct 2024 01:21:40 +0200
> 
> 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"? [...]
> 
> 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.

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

[Michael Albinus via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

Hi,

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

In the Tramp case, we couldn'tz even be sure that the remote file is
treated there as "file". See for example the Tramp gdrive method, or
think about AWS S3 buckets.

Tramp asks the remote system about whether a file is newer than the
other, and it returns this answer in its file-newer-than-file-p
implementations. On classical filesystems, it is the last modification
time, yes. But we cannot guarantee, because we simply don't know the
details of the remote filesystem.

Best regards, Michael.

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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.


> 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?  If not: do you
have any better idea?

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


Michael.

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

[Eli Zaretskii]

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

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

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

They are trivial but help to avoid the misinterpretation I had.  I agree
that "file modification [time]" is not much better than "new".


> Better idea about what?

About how to prevent a misunderstanding of the doc for people that not

already know the abstraction or intended meaning of "new" here.

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


This is what you wrote:

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

For me this is not funny.  Especially when mentioning Drew who you often
have arguments with.  "Dry, maybe too dry humor" looks like an euphemism
of "sarcasm" to me in this case.  At least like masked anger.  Humor
that is about others can go awry.

But maybe I just did not understand what was funny about that.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 73709@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Sat, 12 Oct 2024 02:31:26 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Better idea about what?
> 
> About how to prevent a misunderstanding of the doc for people that not
> 
> already know the abstraction or intended meaning of "new" here.

I don't, maybe because for me "newer" is clear enough.  But I'm open
to suggestions.

> > > 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...
> 
> 
> This is what you wrote:
> 
> > 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.
> 
> For me this is not funny.  Especially when mentioning Drew who you often
> have arguments with.  "Dry, maybe too dry humor" looks like an euphemism
> of "sarcasm" to me in this case.  At least like masked anger.  Humor
> that is about others can go awry.
> 
> But maybe I just did not understand what was funny about that.

It was supposed to humorously say that you will be the "guilty
parties" for any followup complaints about this.

But even if it was not funny, there's no reason to perceive it as
anything but an unsuccessful joke or even simply unclear wording.  Why
on earth would you assume that I meant to offend or insult?

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

> > But maybe I just did not understand what was funny about that.
>
> It was supposed to humorously say that you will be the "guilty
> parties" for any followup complaints about this.
>
> But even if it was not funny, there's no reason to perceive it as
> anything but an unsuccessful joke or even simply unclear wording.  Why
> on earth would you assume that I meant to offend or insult?

It's not my fault that you being angry and you making jokes is nearly
indistinguishable.

You also don't seem to be able to say "Ok, sorry, this joke didn't work
so well".  The only responsibility seems to lie on the other side.  This
is a bit too simple.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: 73709@debbugs.gnu.org,  drew.adams@oracle.com
> Date: Sun, 13 Oct 2024 00:48:02 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > > But maybe I just did not understand what was funny about that.
> >
> > It was supposed to humorously say that you will be the "guilty
> > parties" for any followup complaints about this.
> >
> > But even if it was not funny, there's no reason to perceive it as
> > anything but an unsuccessful joke or even simply unclear wording.  Why
> > on earth would you assume that I meant to offend or insult?
> 
> It's not my fault that you being angry and you making jokes is nearly
> indistinguishable.
> 
> You also don't seem to be able to say "Ok, sorry, this joke didn't work
> so well".  The only responsibility seems to lie on the other side.  This
> is a bit too simple.

Sigh.

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

1. Doc string suggestion, first line:

"Return t if content of FILE1 is newer than content of FILE2."

Short and clear.  (If you want shorter yet: use "that" instead
of the second "content" - but that's slightly less clear.)

[A better name for it would have been `file-content-newer-p'.
The second "file" in the name isn't needed, as we're clearly
comparing the two args, which are both files.]

2. For the rest of the doc string, consider replacing "the
answer is" with "return" (both places).

3. The argument that "Lisp programmers should not think about
this in terms of file attributes returned by the 'stat' system
call" is misdirected.  No one suggested they should.

Just pointing readers to `file-attribute-modification-time'
doesn't cause them to think that way.  Mentioning it wouldn't
hurt, but help.  It makes clear _exactly_ what's compared.

4. But whether or not `file-attribute-modification-time' is
mentioned isn't important.  The point is that "newer" alone
isn't clear.  It's like "bigger" - mass? volume? height?
width? depth?

It's about WHAT'S newer - just _what_ about the two files is
compared wrt time/newness?  Answer: their _content_ (at a
reasonable approximation).  Not shorter file life, nor a
measure of file metadata, etc.

5. FWIW, "newer" is accurate.  I wasn't sure whether the
test might actually be newer-or-the-same (IOW test, in fact,
whether the content of FILE2 is older).  So I tried passing
the same file as both args, and got nil - "newer" is the
right word.  This might not be obvious to all readers, but
it's easy enough for them to find out as I did.

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "73709@debbugs.gnu.org" <73709@debbugs.gnu.org>
> Date: Sun, 13 Oct 2024 14:51:19 +0000
> 
> 1. Doc string suggestion, first line:
> 
> "Return t if content of FILE1 is newer than content of FILE2."
> 
> Short and clear.

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)?

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> > 1. Doc string suggestion, first line:
> >
> > "Return t if content of FILE1 is newer than content of FILE2."
> >
> > Short and clear.
> 
> 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).

But it's _not_ available even in that doc, is it?

 (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.
                              ^^^^^^^^^^^^^^^
 Doc string of `file-attributes':
 5. Last modification time, likewise.  This is the
    time of the last change to the file's contents.
                                   ^^^^^^^^^^^^^^^

If we don't get into such detail in the doc for
the attribute then we certainly don't need to get
into it in the doc for `file-newer-than-file-p'.

But what's _most_ important here is to say WHAT
thing (aspect/attribute/dimension) it is whose
relative recentness is measured/compared.  Just
"newer" or "more recent" doesn't cut the mustard.

The thing that's measured/compared, as the attribute
doc itself says, is the "file's contents".  Don't
believe me; believe that doc.

As said before, it's a matter of _degree_ of clarity.
The current doc for the predicate isn't clear enough.
It misses what's most important - content changes.

  "IOW, you needn't go to the extreme of saying that
   we would need to explain everything in the doc of
   `file-newer-than-file-p'.  All that's needed for
   that doc is something a bit clearer than just saying
   that it's about a file's "newness".

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.  A false choice.

https://en.wikipedia.org/wiki/False_dilemma

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "michael_heerdegen@web.de" <michael_heerdegen@web.de>,
>         "73709@debbugs.gnu.org" <73709@debbugs.gnu.org>
> 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?

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Good to hear.

How come you haven't mentioned it in this bug thread?

Why not communicate the improvement you propose,
rather than just arguing that this simple doc
string can't possibly make clear all of the complex
details (which no one's suggested is needed to
improve this doc string)?

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

[Eli Zaretskii]

> From: Drew Adams <drew.adams@oracle.com>
> CC: "michael_heerdegen@web.de" <michael_heerdegen@web.de>,
>         "73709@debbugs.gnu.org" <73709@debbugs.gnu.org>
> Date: Sun, 13 Oct 2024 22:23:20 +0000
> 
> > I do?  Then how come I changed the doc string at least twice in the
> > recent days?
> 
> Good to hear.
> 
> How come you haven't mentioned it in this bug thread?

I did, actually.

> Why not communicate the improvement you propose,
> rather than just arguing that this simple doc
> string can't possibly make clear all of the complex
> details (which no one's suggested is needed to
> improve this doc string)?

I did communicate that.

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

> > "Return t if content of FILE1 is newer than content of FILE2."
> >
> > Short and clear.
>
> 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)?

Would it be less problematic to refer to "the time when the file has
been last saved"?  I think this comes close to the actual meaning,
doesn't refer to internals, and also suggest the intended semantics for
the existing use cases (auto-save files, source vs. compiled files,
etc.).


Michael.

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

[Stefan Kangas]

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.

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

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.

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

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

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

Precisely one of my points (for the manual).  It's the
same node where `file-newer-than-file-p' is covered.

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

[Eli Zaretskii]

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

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

> IOW, the addition I just made per your request breaks the (useful,
> IMO) abstraction we had.

If you had an abstraction it should be possible to describe it.  This is
actually what I wanted.  The problem with what we had was that people
who did not yet know the abstraction could read something different than
intended.


> For what good reasons?

One reason was that I had misunderstood the docstring and that this may
happen to others.  I really would like to know why that doesn't count as
a reason.


Michael.

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

[Eli Zaretskii]

> From: Michael Heerdegen <michael_heerdegen@web.de>
> Cc: Stefan Kangas <stefankangas@gmail.com>,  73709@debbugs.gnu.org,
>   drew.adams@oracle.com
> Date: Fri, 11 Oct 2024 02:41:40 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > IOW, the addition I just made per your request breaks the (useful,
> > IMO) abstraction we had.
> 
> If you had an abstraction it should be possible to describe it.

It _was_ described.  "Newer" is a simple word that everyone should
understand.  If "newer" is still not enough understood, we should have
discussed how to make it more clear without leaking the abstraction.

> This is actually what I wanted.  The problem with what we had was
> that people who did not yet know the abstraction could read
> something different than intended.

No, the request was explicitly to add specific technical details about
how we implement the abstraction.  Which is what we have now, and I
think it's a step in the wrong direction.

> > For what good reasons?
> 
> One reason was that I had misunderstood the docstring and that this may
> happen to others.  I really would like to know why that doesn't count as
> a reason.

Because the request was to address the misunderstanding by exposing
the details of the implementation.  Once we start talking about file
creation time vs file modification time (and don't forget file
last-access time), we are not clarifying the abstraction, we are
leaking the details of the implementation.

Maybe I was mistaken in my interpretation of the request, but then
please re-read the thread and point me to the part where the request
was something other than explicitly mention the file's mtime in the
doc string and the manual.

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

[Michael Heerdegen via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

> No, the request was explicitly to add specific technical details about
> how we implement the abstraction.  Which is what we have now, and I
> think it's a step in the wrong direction.

Drew, would it be acceptable for you if we tried to describe the
abstraction without relying on file-system related details?  And how
could that look like?


Michael.

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

[Drew Adams via Bug reports for GNU Emacs, the Swiss army knife of text editors]

> > No, the request was explicitly to add specific technical details about
> > how we implement the abstraction.  Which is what we have now, and I
> > think it's a step in the wrong direction.
> 
> Drew, would it be acceptable for you if we tried to describe the
> abstraction without relying on file-system related details?  And how
> could that look like?

I don't care how you describe the meaning that what's
more recent is the time/date of the last _content_
change.

(Of course, it's a bit more nuanced than that, since
you can `touch' a file without changing its content.
But at a first approximation it's conceptually about
a change in content.)

You don't have to refer to the file attribute that has
that meaning (`file-attribute-modification-time').
What's important is to convey the meaning - that's the
thing (aspect/attribute/dimension) whose relative
recentness is measured/compared.

Do I think it would be a _good_ thing to actually refer
to that attribute by name?  Yes, because it's described
rigorously and carefully (in the same node, no less).
And even if you want to repeat the description, making
the connection with the attribute that has that meaning
helps users - it doesn't hurt them.

That's what I think, but I don't say that's what you
need to do.

If you prefer to describe that meaning without
referring to that attribute (because you think doing
so gets into the "implementation"), go for it.  To me,
that makes Occam gag a bit, but it gets the job done.

"Last modification" by itself doesn't describe it.
"Last content modification" comes close.