bug#8782: date command

[Bob Proulx]

Rick Stanley wrote:
> date -d 1306947372
> Which results in the error message, "date: invalid date `1306947372'".
> 
> Neither 'date --help' or 'man date' shows that the command should have
> been written as:
> 
> date -d @1306947372
> 
> I needed to do a Google search to see what I was doing wrong. (My memory
> is not as good as it used to be!) ;^)

I am sorry that you had such trouble with the date command.  The
documentation for date should be available along with the date
command.  As the man page says:

       The full documentation for date is maintained as a Texinfo
       manual.  If the info and date programs are properly installed
       at your site, the command

              info coreutils 'date invocation'

       should give you access to the complete manual.

If for some reason the manual is not available we can try to debug why
and try to help you get it going for you.

The latest manual is also available on the web.

  http://www.gnu.org/software/coreutils/manual/

Here is the relevant parts for your topic:

  
http://www.gnu.org/software/coreutils/manual/html_node/Date-input-formats.html#Date-input-formats

> I don't know why this ('@') is needed, since the date command recognizes
> many different date formats without specifying the format.

If the @ sign weren't there it would be ambiguous as to what you were
trying to ask for and it could break previous behavior.

How else would it be possible to tell the difference between these two
dates?

  $ date -R -d @20110101
  Fri, 21 Aug 1970 12:08:21 -0600

  $ date -R -d 20110101
  Sat, 01 Jan 2011 00:00:00 -0700

Those are quite different dates!

> For completeness of the help and man page, please add a line
> explaining that when passing a UNIX Epoch Date to the -d option, you
> need to prefix the date with a '@'.

The manual explains the input formats on at least ten different pages
of documentation!  That is very much too long to put in the --help
output of the command.  The --help is good for very terse hints for
when you already know how to use a command but is not well suited for
a user manual.  There just isn't space to describe all of the features
of a program there.  Neither is the man page which is extracted from
the --help output very well suited to it.  This is a bug but one that
was fixed a very long time ago by creating the full manual using a
medium that was designed for it.

Bob