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.

1 files changed, 28 insertions, 0 deletions

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 7b37f60e1..92331945b 100644
--- 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