Re: Documentation: unclear -newerXY

Hi Mike,

On 3/6/26 21:46, Mike Maxwell wrote:
> I'm sending this as an email because I'm new to this, and
> https://www.gnu.org/software/findutils/ says "there will be occasions
> where you're not sure whether the problem you have is actually a bug, or
> you just want to talk about ideas for improving findutils. Using the
> mailing list is a good way to do that."  (Also because I can't find a
> place/button on https://savannah.gnu.org/bugs/ to actually submit anything.)
> 
> I am not sure what the most recent documentation page for 'find' is, in
> particular for the documentation on the -newerXY argument.  I've found
> half a dozen versions, most of which I find hard to understand or even
> misleading.  First I'll explain what I find confusing, then what I'm
> suggesting as better wording.
> 
> 
> Here's the relevant part of the documentation (some lines removed), as
> found in the man page for v 4.9.0 (on Linux Mint, but I assume the same
> elsewhere):
> ---------
>    -newerXY reference
>         Succeeds if timestamp X of the file being considered is newer
>         than timestamp Y of the file reference. ...
>         a   The access time of the file reference
>         B   The birth time of the file reference
>         c   The inode status change time of reference
>         m   The modification time of the file reference
>         t   reference is interpreted directly as a time
> --------
> When I read this, I (mis-)understand "timestamp Y of the file reference"
> to mean that 'reference' is a filename, and that's the only way to use
> this arg.  Given that misunderstanding I don't understand what
> "reference is interpreted directly as a time" means, i.e. I'm left
> confused by the man page.  Furthermore, the letters all (except t) talk
> about the times "of the file reference", whereas actually they pertain
> to the times of BOTH the file being considered and the reference file.
> 
> 
> Here's a different version of the man page on
> https://www.gnu.org/savannah-checkouts/gnu/findutils/manual/html_node/find_html/Comparing-Timestamps.html,
> also hard to understand:
> --------
>     Test: -newerXY reference
>        Succeeds if timestamp ‘X’ of the file being considered is newer
>        than timestamp ‘Y’ of the file reference.
>        ...
>        ‘t’
>            The reference argument is interpreted as a literal time,
>            rather than the name of a file.
> --------
> This version again uses the confusing "timestamp ‘Y’ of the file
> reference", but the 't' part (particularly the "rather than") helps to
> clarify that.  There is also an example, but the example doesn't
> illustrate the use of 't'.
> 
> 
> Finally, there's the documentation as show on
> https://unix.stackexchange.com/questions/169798/what-does-newermt-mean-in-find-command:
> ---------
> -newerXY reference
>             Compares the timestamp of the current file with reference.
>             The reference argument is normally the name of a file
>             (and one of its timestamps is used for the comparison)
>             but it may also be a string describing an absolute time.
>             ...
>             t   reference is interpreted directly as a time
> ----------
> IMO, this one comes the closest to being understandable, because the
> 'but' is right there in the first paragraph, not (just) down in the
> description of the possible replacements for X and Y.

Thanks for description of why this paragraph might be misinterpreted.

> Putting this all together, here's how I'd suggest this part of the man
> page could read:

Still, I think going back towards the older description might be confusing
as well:

> ---------
> -newerXY reference
>             Compares the timestamp X of the current file with the
>             timestamp Y of the reference. The reference argument is
>             normally the name of a file (and one of its timestamps
______________^^^^^^^^

what is normally?

>             is used for the comparison), but it may also be a string
_______________________________________________^^^^^^^^^^^^^^
I think this is also quite vague.

>             describing an absolute time (see description of 't' below).
>             The letters X and Y must be replaced with any of the
>             following letters:
>             a   The access time of the file
>             B   The birth time of the file
>             c   The inode status change time
>             m   The modification time
>             t   'reference' is interpreted as a time (rather than as
> 
>                 a file name); used for letter Y only

Actually it is a reference file for "Abcm", and a literal timestamp for 't'.
We should try to get this 2 different cases into the documentation, yet IMO
based on the current version which is not too bad but obviously not precise
enough.

> ----------

> An example would be a nice addition, like the two near the top of
> https://collectingwisdom.com/bash-find-files-newer-than/.

Agree.

Have a nice day,
Berny