Subject: Re: bug#20203: add example to date man page
From: Pádraig Brady <[email-masked]>
To: 積丹尼 Dan Jacobson <[email-masked]>, [email-masked]
Date: Thu, 26 Mar 2015 00:58:56 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

On 25/03/15 23:58, 積丹尼 Dan Jacobson wrote:
> Please change
> 
>        -I[TIMESPEC], --iso-8601[=TIMESPEC]
>               output date/time in ISO 8601 format.  TIMESPEC='date'  for  date
>               only  (the  default), 'hours', 'minutes', 'seconds', or 'ns' for
>               date and time to the indicated precision.
> 
> to
>         -I[TIMESPEC], --iso-8601[=TIMESPEC]
>               output date/time in ISO 8601 format.  TIMESPEC='date'  for  date
>               only  (2015-03-26, the  default), 'hours', 'minutes', 'seconds', or 'ns' for
>               date and time to the indicated precision.

Probably not worth doing on its own, but I noticed other
improvements that could be made to these option descriptions,
which the attached should fix up.

cheers,
Pádraig.

From a5dc4b8d697e7a50bec123113950ab3f5700705a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Thu, 26 Mar 2015 00:47:28 +0000
Subject: [PATCH] doc: clarify the date standard output formats

* src/date.c (usage): Use FMT rather than TIMESPEC as the parameter,
since it's simpler to understand and can be better aligned.
Give an example for the --iso-8601 output format.
Adjust the example used for the 3 standard formats to
be unambiguous to day/mon ordering and use of leading zeros in the time.
Reorder the options descriptions slightly, so that the
3 standards options are together.
Fixes http://bugs.gnu.org/20203
---
 src/date.c | 38 ++++++++++++++++++++++----------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/src/date.c b/src/date.c
index 65fd0fc..3df7522 100644
--- a/src/date.c
+++ b/src/date.c
@@ -132,26 +132,32 @@ Display the current time in the given FORMAT, or set the system date.\n\
       emit_mandatory_arg_note ();
 
       fputs (_("\
-  -d, --date=STRING         display time described by STRING, not 'now'\n\
-  -f, --file=DATEFILE       like --date once for each line of DATEFILE\n\
-  -I[TIMESPEC], --iso-8601[=TIMESPEC]  output date/time in ISO 8601 format.\n\
-                            TIMESPEC='date' for date only (the default),\n\
-                            'hours', 'minutes', 'seconds', or 'ns' for date\n\
-                            and time to the indicated precision.\n\
+  -d, --date=STRING          display time described by STRING, not 'now'\n\
+  -f, --file=DATEFILE        like --date; once for each line of DATEFILE\n\
 "), stdout);
       fputs (_("\
-  -r, --reference=FILE      display the last modification time of FILE\n\
-  -R, --rfc-2822            output date and time in RFC 2822 format.\n\
-                            Example: Mon, 07 Aug 2006 12:34:56 -0600\n\
+  -I[FMT], --iso-8601[=FMT]  output date/time in ISO 8601 format.\n\
+                             FMT='date' for date only (the default),\n\
+                             'hours', 'minutes', 'seconds', or 'ns' for date\n\
+                             and time to the indicated precision.\n\
+                             Example: 2006-08-14T02:34:56-0600\n\
 "), stdout);
       fputs (_("\
-      --rfc-3339=TIMESPEC   output date and time in RFC 3339 format.\n\
-                            TIMESPEC='date', 'seconds', or 'ns' for\n\
-                            date and time to the indicated precision.\n\
-                            Date and time components are separated by\n\
-                            a single space: 2006-08-07 12:34:56-06:00\n\
-  -s, --set=STRING          set time described by STRING\n\
-  -u, --utc, --universal    print or set Coordinated Universal Time (UTC)\n\
+  -R, --rfc-2822             output date and time in RFC 2822 format.\n\
+                             Example: Mon, 14 Aug 2006 02:34:56 -0600\n\
+"), stdout);
+      fputs (_("\
+      --rfc-3339=FMT         output date/time in RFC 3339 format.\n\
+                             FMT='date', 'seconds', or 'ns' for\n\
+                             date and time to the indicated precision.\n\
+                             Example: 2006-08-14 02:34:56-06:00\n\
+"), stdout);
+      fputs (_("\
+  -r, --reference=FILE       display the last modification time of FILE\n\
+"), stdout);
+      fputs (_("\
+  -s, --set=STRING           set time described by STRING\n\
+  -u, --utc, --universal     print or set Coordinated Universal Time (UTC)\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
-- 
2.1.0