Re: [PATCH] find.1: avoid misunderstanding of `-prtinf %Ak` description

Bernhard Voelker <[email protected]> Wed, 7 Oct 2020 00:36:56 +0200

Newsgroups	gmane.comp.gnu.findutils.patches,gmane.comp.gnu.findutils.bugs
Message-ID	<[email protected]>

Hi Kamil,

On 2020-10-06 17:10, Kamil Dudka wrote:
> * find/find.1 (-printf): Make it clear that strftime() format
> description in this man page is incomplete and refer to the
> strftime() documentation instead.
> 
> Suggested in https://bugzilla.redhat.com/1882695
> ---
>  find/find.1 | 5 ++---
>  1 file changed, 2 insertions(+), 3 deletions(-)
> 
> diff --git a/find/find.1 b/find/find.1
> index ee7c6842..0bc882b3 100644
> --- a/find/find.1
> +++ b/find/find.1
> @@ -1420,9 +1420,8 @@ File's last access time in the format returned by the C `ctime' function.
>  File's last access time in the format specified by
>  .IR k ,
>  which is either `@' or a directive for the C `strftime' function.
> -The possible values for \fIk\fR are listed below;
> -some of them might not be available on all systems,
> -due to differences in `strftime' between systems.
> +Below is an excerpt of possible values for \fIk\fR.  For full list
> +please refer to documentation of `strftime'.
>  .RS
>  .IP @
>  seconds since Jan.\& 1, 1970, 00:00 GMT, with fractional part.

Thanks for the patch.

I prefer to keep the sentence that the supported list of conversion
specifiers may vary among different systems.

Reading the original bug report, I found it useful to add the 'F'
conversion specifier - yielding the IMO quite useful 'yyyy-dd-mm'
date format.

Finally, I added similar clarification to the Texinfo manual.

May I push the attached in your name?

Thanks & have a nice day,
Berny

0001-doc-avoid-misunderstanding-of-printf-Ak-description.patch (text/x-patch, 3.4 KB)

From efa455493063270406f3c206d62032a475e52c47 Mon Sep 17 00:00:00 2001
From: Kamil Dudka <[email protected]>
Date: Tue, 6 Oct 2020 17:10:08 +0200
Subject: [PATCH] doc: avoid misunderstanding of '-printf %Ak' description

* find/find.1 (-printf): Make it clear that the list of conversion
specification characters of '%Ak' is incomplete; refer to the
strftime() documentation.  While at it, document the F conversion
character which yields 'yyyy-mm-dd'.
* doc/find.texi (Time Formats): Likewise.
* NEWS: Mention the improvement.

Suggested in https://bugzilla.redhat.com/1882695
---
 NEWS          |  4 ++++
 doc/find.texi | 11 +++++++----
 find/find.1   |  9 ++++++---
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/NEWS b/NEWS
index aa6083dc..1ec2ab4f 100644
--- a/NEWS
+++ b/NEWS
@@ -16,6 +16,10 @@ find -used works again.  This predicate was not working properly since adding
 the support for sub-second timestamp resolution for various predicates in
 FINDUTILS_4_3_3-1 back in 2007.
 
+The documentation of 'find -printf %Ak' has been improved: it now refers to the
+strftime(3) documentation for a complete list of supported conversion
+specifiers, and documents the 'F' conversion specifier ('yyyy-mm-dd').
+
 #59083: 'find -D exec' now diagnoses all -exec, -execdir, -ok and -okdir runs
 including the call arguments and the exit code of the launched process.
 
diff --git a/doc/find.texi b/doc/find.texi
index ce63ca52..0d7c8ae8 100644
--- a/doc/find.texi
+++ b/doc/find.texi
@@ -2063,10 +2063,11 @@ behaviour, because other directives may be added in the future.
 @node Time Formats
 @subsection Time Formats
 
-Below are the formats for the directives @samp{%A}, @samp{%C}, and
-@samp{%T}, which print the file's timestamps.  Some of these formats
-might not be available on all systems, due to differences in the C
-@code{strftime} function between systems.
+Below is an incomplete list of formats for the directives @samp{%A}, @samp{%C},
+and @samp{%T}, which print the file's timestamps.
+Please refer to the documentation of @code{strftime} for the full list.
+Some of these formats might not be available on all systems, due to differences
+in the implementation of the C @code{strftime} function.
 
 @menu
 * Time Components::
@@ -2162,6 +2163,8 @@ locale's date and time in ctime format (Sat Nov 04 12:02:33 EST
 seconds field.
 @item D
 date (mm/dd/yy)
+@item F
+date (yyyy-mm-dd)
 @item x
 locale's date representation (mm/dd/yy)
 @item +
diff --git a/find/find.1 b/find/find.1
index ee7c6842..27ec62cd 100644
--- a/find/find.1
+++ b/find/find.1
@@ -1420,9 +1420,10 @@ File's last access time in the format returned by the C `ctime' function.
 File's last access time in the format specified by
 .IR k ,
 which is either `@' or a directive for the C `strftime' function.
-The possible values for \fIk\fR are listed below;
-some of them might not be available on all systems,
-due to differences in `strftime' between systems.
+The following shows an incomplete list of possible values for \fIk\fR.
+Please refer to the documentation of `strftime' for the full list.
+Some of the conversion specification characters might not be available on all systems,
+due to differences in the implementation of the `strftime' library function.
 .RS
 .IP @
 seconds since Jan.\& 1, 1970, 00:00 GMT, with fractional part.
@@ -1476,6 +1477,8 @@ in the seconds field.
 day of month (01..31)
 .IP D
 date (mm/dd/yy)
+.IP F
+date (yyyy-mm-dd)
 .IP h
 same as b
 .IP j
-- 
2.28.0