bug#8782: date command
James Youngman wrote: On Thu, Jun 2, 2011 at 10:11 AM, Jim Meyering j...@meyering.net wrote: Pádraig Brady wrote: OK how about I put the last 3 or 4 examples from http://www.pixelbeat.org/cmdline.html#dates in an EXAMPLE section in the man page. Good examples. I like the idea. One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. Good idea. That makes it immune to failure in a one hour interval on the day before the spring DST transition.
bug#8782: date command
Jim Meyering wrote: James Youngman wrote: One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. Good idea. That makes it immune to failure in a one hour interval on the day before the spring DST transition. hmm, shouldn't the tomorrow handling be fixed then? -- Berny
bug#8782: date command
Voelker, Bernhard wrote: Jim Meyering wrote: James Youngman wrote: One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. Good idea. That makes it immune to failure in a one hour interval on the day before the spring DST transition. hmm, shouldn't the tomorrow handling be fixed then? Hi Voelker, Fixed how? To retry in that very unusual case? Let's ignore that someone might depend on the current failure, e.g., to locate a DST transition. Note that tomorrow is equivalent to +1 day, aka +24 hours. Upon retry would you use +23 hours or +25 hours? Something else? I don't think it's feasible to change it. This is well documented in the FAQ, and probably in the manual, too.
bug#8782: date command
Jim Meyering wrote: Voelker, Bernhard wrote: Jim Meyering wrote: James Youngman wrote: One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. Good idea. That makes it immune to failure in a one hour interval on the day before the spring DST transition. hmm, shouldn't the tomorrow handling be fixed then? Hi Voelker, Fixed how? To retry in that very unusual case? Let's ignore that someone might depend on the current failure, e.g., to locate a DST transition. that's BAD (tm) usage, IMHO Note that tomorrow is equivalent to +1 day, aka +24 hours. Upon retry would you use +23 hours or +25 hours? Something else? I don't think it's feasible to change it. I admit it's hard. From the user's point of view, there's always a date 24 hours from now on. And the user wants to know what date this would be ... This is well documented in the FAQ, and probably in the manual, too. yes, it is. But as I'm following this ML for ~2 years now, this topic has popped up several times. It seems there's room for improvement. -- Bye, Berny
bug#8782: date command
On 06/03/11 01:52, Voelker, Bernhard wrote: It seems there's room for improvement. Absolutely. All that we need is someone to volunteer to specify exactly how to improve it, and to write the documentation and code. Unfortunately, this won't be trivial.
bug#8782: date command
Voelker, Bernhard wrote: Jim Meyering wrote: Voelker, Bernhard wrote: Jim Meyering wrote: James Youngman wrote: One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. Good idea. That makes it immune to failure in a one hour interval on the day before the spring DST transition. hmm, shouldn't the tomorrow handling be fixed then? Hi Voelker, Fixed how? To retry in that very unusual case? Let's ignore that someone might depend on the current failure, e.g., to locate a DST transition. that's BAD (tm) usage, IMHO Note that tomorrow is equivalent to +1 day, aka +24 hours. Upon retry would you use +23 hours or +25 hours? Something else? I don't think it's feasible to change it. I admit it's hard. From the user's point of view, there's always a date 24 hours from now on. And the user wants to know what date this would be ... We can't change the fact that the spring DST transition introduces a one-hour hole containing invalid times. Whenever we tell date to use a time in such a hole, date must diagnose it as invalid. This is well documented in the FAQ, and probably in the manual, too. yes, it is. But as I'm following this ML for ~2 years now, this topic has popped up several times. It seems there's room for improvement. Making a technical change will be a challenge, to say the least. People are learning that this hole can make date fail. As I see it, education is the way to go.
bug#8782: date command
Jim Meyering wrote: Voelker, Bernhard wrote: Jim Meyering wrote: Voelker, Bernhard wrote: Jim Meyering wrote: James Youngman wrote: One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. Good idea. That makes it immune to failure in a one hour interval on the day before the spring DST transition. hmm, shouldn't the tomorrow handling be fixed then? Hi Voelker, Fixed how? To retry in that very unusual case? Let's ignore that someone might depend on the current failure, e.g., to locate a DST transition. that's BAD (tm) usage, IMHO Note that tomorrow is equivalent to +1 day, aka +24 hours. Upon retry would you use +23 hours or +25 hours? Something else? I don't think it's feasible to change it. I admit it's hard. From the user's point of view, there's always a date 24 hours from now on. And the user wants to know what date this would be ... We can't change the fact that the spring DST transition introduces a one-hour hole containing invalid times. Whenever we tell date to use a time in such a hole, date must diagnose it as invalid. `date` is still a tool, so I feel it should reflect daily life ... I I don't feel I have a 1h gap in spring, do you? ;-)
bug#8782: date command
Voelker, Bernhard wrote: ... We can't change the fact that the spring DST transition introduces a one-hour hole containing invalid times. Whenever we tell date to use a time in such a hole, date must diagnose it as invalid. `date` is still a tool, so I feel it should reflect daily life ... I I don't feel I have a 1h gap in spring, do you? ;-) I do notice it when I have one hour more or less to sleep. I'd say that this tool does reflect daily life. With date you have to be careful about the DST transitions, just as you have to adjust clocks twice a year.
bug#8782: date command
Jim Meyering wrote: Voelker, Bernhard wrote: ... We can't change the fact that the spring DST transition introduces a one-hour hole containing invalid times. Whenever we tell date to use a time in such a hole, date must diagnose it as invalid. `date` is still a tool, so I feel it should reflect daily life ... I I don't feel I have a 1h gap in spring, do you? ;-) I do notice it when I have one hour more or less to sleep. admitted. I'd say that this tool does reflect daily life. With date you have to be careful about the DST transitions, just as you have to adjust clocks twice a year. so in the night where the DST transition takes place, imagine you get up to go to the toilet because you drank to much coffee the evening before ... right in the hour where DST transition happens: isn't there a `date`? Or the other way round: how many hours do you have to left to sleep until 8am? The situation with date sounds like there is an hour once per year when no date exists, but this is not true.
bug#8782: date command
On Friday 03 June 2011, Voelker, Bernhard wrote: so in the night where the DST transition takes place, imagine you get up to go to the toilet because you drank to much coffee the evening before ... right in the hour where DST transition happens: isn't there a `date`? Or the other way round: how many hours do you have to left to sleep until 8am? The situation with date sounds like there is an hour once per year when no date exists, but this is not true. There was no 2011-05-27 02:01:00 in Germany. I am 100% sure nobody in Germany was on toilet on at this time. At this date if you go at 01:59:00 and come back at 03:02:00 then you where 3 minutes on toilet but you was not at 2:01:00 because this time simply does not exist at this day. This works as expected: $ export TZ=Europe/Berlin $ date -d 2011-03-27 02:01:00 date: invalid date `2011-03-27 02:01:00' $ date -d 2011-03-26 02:01:00 tomorrow Sun Mar 27 03:01:00 CEST 2011 cu, Rudi
bug#8782: date command
On 02/06/11 00:39, Jesse Gordon wrote:
On 6/1/2011 4:12 PM, Pádraig Brady wrote:
On 01/06/11 18:11, Rick Stanley wrote:
The date command is very useful. A lot of features and options which I
take advantage of as I need them. Every once in a while I need to use
the command to convert a UNIX Epoch Date to a normal date, so I attempt
to use the command as:
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 don't know why this ('@') is needed, since the date command recognizes
many different date formats without specifying the format. 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 '@'.
Thank you for your time and consideration!
You need the '@' to disambiguate. Consider fir example:
date --date=1243
date --date=@1234
Unfortunately the date input formats are many and varied,
and I don't think it's worth getting specific in the man page.
The man page currently says:
The date string format is more complex than is easily documented
here but is fully described in the info documentation.
So I'll close this as adequately documented.
thanks,
Pádraig.
Jumpin' whale gills!
Well when you put it like that :)
I wish I'd known about the -d @ function! I ended
up writing my own in Perl utility just to convert epochs to dates.
I'm with Rick on this one. Date supports so many different date formats
without any special arbitrary characters designating the format. The
average sys admin just assumes the most simple date format in the world
would also work the same way.
Since -d @1234 is so useful, and since it uncharacteristically requires
an arbitrary prefix code, I think that it would be a very good to put it
in all forms of documentation, even where the dozens of other obvious
uses are not documented.
OK how about I put the last 3 or 4 examples from
http://www.pixelbeat.org/cmdline.html#dates
in an EXAMPLE section in the man page.
There was also a recent report from RMS that
the date input formats wrt TZ were a bit buried.
cheers,
Pádraig.
bug#8782: date command
Pádraig Brady wrote: ... Jumpin' whale gills! Well when you put it like that :) Heh ;-) I had the same reaction. I wish I'd known about the -d @ function! I ended up writing my own in Perl utility just to convert epochs to dates. I'm with Rick on this one. Date supports so many different date formats without any special arbitrary characters designating the format. The average sys admin just assumes the most simple date format in the world would also work the same way. Since -d @1234 is so useful, and since it uncharacteristically requires an arbitrary prefix code, I think that it would be a very good to put it in all forms of documentation, even where the dozens of other obvious uses are not documented. OK how about I put the last 3 or 4 examples from http://www.pixelbeat.org/cmdline.html#dates in an EXAMPLE section in the man page. Good examples. I like the idea.
bug#8782: date command
I'm going with these 3. It's a bit tricky to align --help and man output, but this isn't too bad I think. cheers, Pádraig. From 9a7a5d114388342a86f7dc9ade7f69b70624e3fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draig=20Brady?= p...@draigbrady.com Date: Thu, 2 Jun 2011 13:00:18 +0100 Subject: [PATCH] doc: add examples to date --help * src/date.c (usage): Add examples for TZ handling, and seconds since epoch parsing, neither of which were mentioned in the man page until now. Suggested-by: Rick Stanley rstan...@rsiny.com --- src/date.c | 12 1 files changed, 12 insertions(+), 0 deletions(-) diff --git a/src/date.c b/src/date.c index 61d4818..6439d16 100644 --- a/src/date.c +++ b/src/date.c @@ -236,6 +236,18 @@ then an optional modifier, which is either\n\ E to use the locale's alternate representations if available, or\n\ O to use the locale's alternate numeric symbols if available.\n\ ), stdout); + fputs (_(\ +\n\ +Examples:\n\ +Convert seconds since the epoch (1970-01-01 UTC) to a date\n\ + $ date --date='@2147483647'\n\ +\n\ +Show the time on the west coast of the US (use tzselect(1) to find TZ)\n\ + $ TZ='America/Los_Angeles' date\n\ +\n\ +Show the local time for 9AM next Friday on the west coast of the US\n\ + $ date --date='TZ=\America/Los_Angeles\ 09:00 next Fri'\n\ +), stdout); emit_ancillary_info (); } exit (status); -- 1.7.5.2
bug#8782: date command
Pádraig Brady wrote: I'm going with these 3. It's a bit tricky to align --help and man output, but this isn't too bad I think. Thanks. Subject: [PATCH] doc: add examples to date --help * src/date.c (usage): Add examples for TZ handling, and seconds since epoch parsing, neither of which were mentioned in the man page until now. s/were/was/ Suggested-by: Rick Stanley rstan...@rsiny.com Usually, I prefer to list only names in the commit log, leaving the name-to-email mapping to THANKS.in, since a few contributors have requested that no email address be used or that a different one be substituted. If it's in a vc'd file like THANKS.in we can adjust it. Sometimes I'm impatient or lazy, and put the email address in the log. No big deal either way. --- src/date.c | 12 1 files changed, 12 insertions(+), 0 deletions(-) diff --git a/src/date.c b/src/date.c index 61d4818..6439d16 100644 --- a/src/date.c +++ b/src/date.c @@ -236,6 +236,18 @@ then an optional modifier, which is either\n\ E to use the locale's alternate representations if available, or\n\ O to use the locale's alternate numeric symbols if available.\n\ ), stdout); + fputs (_(\ +\n\ +Examples:\n\ +Convert seconds since the epoch (1970-01-01 UTC) to a date\n\ + $ date --date='@2147483647'\n\ +\n\ +Show the time on the west coast of the US (use tzselect(1) to find TZ)\n\ + $ TZ='America/Los_Angeles' date\n\ +\n\ +Show the local time for 9AM next Friday on the west coast of the US\n\ + $ date --date='TZ=\America/Los_Angeles\ 09:00 next Fri'\n\ +), stdout); emit_ancillary_info (); } exit (status);
bug#8782: date command
On Thu, Jun 2, 2011 at 10:11 AM, Jim Meyering j...@meyering.net wrote: Pádraig Brady wrote: OK how about I put the last 3 or 4 examples from http://www.pixelbeat.org/cmdline.html#dates in an EXAMPLE section in the man page. Good examples. I like the idea. One tweak: use date -d 12:00 +1 day instead of date -d tomorrow in the example. James.
bug#8782: date command
The date command is very useful. A lot of features and options which I
take advantage of as I need them. Every once in a while I need to use
the command to convert a UNIX Epoch Date to a normal date, so I attempt
to use the command as:
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 don't know why this ('@') is needed, since the date command recognizes
many different date formats without specifying the format. 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 '@'.
Thank you for your time and consideration!
Cheers!
Rick
--
RSI (Rick Stanley, Inc.)
(917) 822-7771
www.rsiny.com
Computer Systems Consulting
Linux Open Source Specialists
bug#8782: date command
On 01/06/11 18:11, Rick Stanley wrote:
The date command is very useful. A lot of features and options which I
take advantage of as I need them. Every once in a while I need to use
the command to convert a UNIX Epoch Date to a normal date, so I attempt
to use the command as:
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 don't know why this ('@') is needed, since the date command recognizes
many different date formats without specifying the format. 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 '@'.
Thank you for your time and consideration!
You need the '@' to disambiguate. Consider fir example:
date --date=1243
date --date=@1234
Unfortunately the date input formats are many and varied,
and I don't think it's worth getting specific in the man page.
The man page currently says:
The date string format is more complex than is easily documented
here but is fully described in the info documentation.
So I'll close this as adequately documented.
thanks,
Pádraig.
bug#8782: date command
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
bug#8782: date command
On 6/1/2011 4:12 PM, Pádraig Brady wrote:
On 01/06/11 18:11, Rick Stanley wrote:
The date command is very useful. A lot of features and options which I
take advantage of as I need them. Every once in a while I need to use
the command to convert a UNIX Epoch Date to a normal date, so I attempt
to use the command as:
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 don't know why this ('@') is needed, since the date command recognizes
many different date formats without specifying the format. 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 '@'.
Thank you for your time and consideration!
You need the '@' to disambiguate. Consider fir example:
date --date=1243
date --date=@1234
Unfortunately the date input formats are many and varied,
and I don't think it's worth getting specific in the man page.
The man page currently says:
The date string format is more complex than is easily documented
here but is fully described in the info documentation.
So I'll close this as adequately documented.
thanks,
Pádraig.
Jumpin' whale gills! I wish I'd known about the -d @ function! I
ended up writing my own in Perl utility just to convert epochs to
dates.
I'm with Rick on this one. Date supports so many different date
formats without any special arbitrary characters designating the
format. The average sys admin just assumes the most simple date
format in the world would also work the same way.
Since -d @1234 is so useful, and since it uncharacteristically
requires an arbitrary prefix code, I think that it would be a
very good to put it in all forms of documentation, even where the
dozens of other obvious uses are not documented.
Thanks have a great day,
Jesse Gordon
