Re: antidote to date +%s not mentioned

[Jim Meyering]

Dan Jacobson <address@hidden> wrote:
> I know, on the info page that says
>
> `%s'
>      seconds since the epoch, i.e., 1 January 1970 00:00:00 UTC (a GNU
>
> please add a Info-follow-reference right there, to your
>
> Jim> example showing how to do that:
>
> Jim>    * If you're sorting or graphing dated data, your raw date values may
> Jim>      be represented as seconds since the epoch.  But few people can
>
> and, at the top where he starts talking about the antidote to %s,
> maybe put in this example:
>
> $ date
> Sun Jun 15 10:33:43 GMT-8 2003
> $ date -d "1970-01-01     $(date +%s) seconds"
> Sun Jun 15 02:33:43 GMT-8 2003
> $ date -d "1970-01-01 UTC $(date +%s) seconds"
> Sun Jun 15 10:33:43 GMT-8 2003
>
> as I think it gets the point across more directly maybe, about local
> time zones.

Thanks again.
I've made the following changes.

        * coreutils.texi (Time directives) [%s]: Add a cross reference
        to the related examples.
        (Examples of date): Add an @anchor here, along with a few more examples.
        Suggestion from Dan Jacobson.

Personally, I'd really like to be able to assume everyone
uses a Bourne-compatible shell (where the $(...) notation works),
but people using C-shells wouldn't like that.

If you still think something like the above would help,
then please send a patch using examples like these that
limit output to the part (time) that changes:

  date +%T
  date -d "1970-01-01     `date +%s` seconds" +%T
  date -d "1970-01-01 UTC `date +%s` seconds" +%T

Index: coreutils.texi
===================================================================
RCS file: /fetish/cu/doc/coreutils.texi,v
retrieving revision 1.114
diff -u -p -u -p -r1.114 coreutils.texi
--- coreutils.texi      12 Jun 2003 06:59:45 -0000      1.114
+++ coreutils.texi      25 Jun 2003 09:46:16 -0000
@@ -10472,6 +10472,7 @@ GNU extension).
 Note that this value is the number of seconds between the epoch
 and the current date as defined by the localtime system call.
 It isn't changed by the @option{--date} option.
+For examples, @xref{%s-examples}.
 @item %S
 second (address@hidden).  The range is address@hidden, and not address@hidden,
 in order to accommodate the occasional positive leap second.
@@ -10830,6 +10831,7 @@ use @samp{date --rfc}.  I just did and s
 Mon, 25 Mar 1996 23:34:17 -0600
 @end example
 
address@hidden
 @item
 To convert a date string to the number of seconds since the epoch
 (which is 1970-01-01 00:00:00 UTC), use the @option{--date} option with
@@ -10866,6 +10868,17 @@ date --date='2000-01-01 UTC' +%s
 946684800
 @end example
 
+An alternative is to use the @option{--utc} (@option{-u}) option.
+Then you may omit @samp{UTC} from the date string.  Although this
+produces the same result for @samp{%s} and many other format sequences,
+with a time zone offset different from zero, it would give a different
+result for zone-dependent formats like @samp{%z}.
+
address@hidden
+date -u --date=2000-01-01 +%s
+946684800
address@hidden example
+
 To convert such an unwieldy number of seconds back to
 a more readable form, use a command like this:
 
@@ -10873,6 +10886,13 @@ a more readable form, use a command like
 # local time zone used
 date -d '1970-01-01 UTC 946684800 seconds' +"%Y-%m-%d %T %z"
 1999-12-31 19:00:00 -0500
address@hidden smallexample
+
+Often it is better to output UTC-relative date and time:
+
address@hidden
+date -u -d '1970-01-01 946684800 seconds' +"%Y-%m-%d %T %z"
+2000-01-01 00:00:00 +0000
 @end smallexample
 
 @end itemize