GNU bug report logs - #73709
29.4; Doc of `file-newer-than-file-p'

Previous Next

Full log

Message #27 received at 73709 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: "73709 <at> debbugs.gnu.org" <73709 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#73709: 29.4; Doc of `file-newer-than-file-p'
Date: Wed, 9 Oct 2024 16:32:20 +0000

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.