date: reinstate the --iso-8601 (-I) option

We deprecated and undocumented the --iso-8601 (-I) option mostly
because date could not parse that particular format.  Now that
it can, it's time to restore the documentation.
* src/date.c (usage): Document it.
* doc/coreutils.texi (Options for date): Reinstate documentation.
Reported by Hubert Depesz Lubaczewski in http://bugs.gnu.org/7444.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 7b37f60..9233194 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -14262,6 +14262,34 @@ input.  This is useful when you have many dates to process, because the
 system overhead of starting up the @command{date} executable many times can
 be considerable.
 
+@item -I[@var{timespec}]
+@itemx --iso-8601[=@var{timespec}]
+@opindex -I[@var{timespec}]
+@opindex --iso-8601[=@var{timespec}]
+Display the date using the @acronym{ISO} 8601 format, @samp{%Y-%m-%d}.
+
+The argument @var{timespec} specifies the number of additional
+terms of the time to include.  It can be one of the following:
+@table @samp
+@item auto
+Print just the date.  This is the default if @var{timespec} is omitted.
+
+@item hours
+Append the hour of the day to the date.
+
+@item minutes
+Append the hours and minutes.
+
+@item seconds
+Append the hours, minutes and seconds.
+
+@item ns
+Append the hours, minutes, seconds and nanoseconds.
+@end table
+
+If showing any time terms, then include the time zone using the format
+@samp{%z}.
+
 @item -r @var{file}
 @itemx --reference=@var{file}
 @opindex -r

diff --git a/src/date.c b/src/date.c
index 755736a..288804a 100644 (file)
--- a/src/date.c
+++ b/src/date.c
@@ -87,7 +87,7 @@ static struct option const long_options[] =
 {
   {"date", required_argument, NULL, 'd'},
   {"file", required_argument, NULL, 'f'},
-  {"iso-8601", optional_argument, NULL, 'I'}, /* Deprecated.  */
+  {"iso-8601", optional_argument, NULL, 'I'},
   {"reference", required_argument, NULL, 'r'},
   {"rfc-822", no_argument, NULL, 'R'},
   {"rfc-2822", no_argument, NULL, 'R'},
@@ -131,6 +131,10 @@ Display the current time in the given FORMAT, or set the system date.\n\
 \n\
   -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\
 "), stdout);
       fputs (_("\
   -r, --reference=FILE      display the last modification time of FILE\n\