summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJim Meyering <jim@meyering.net>1997-07-14 14:41:16 +0000
committerJim Meyering <jim@meyering.net>1997-07-14 14:41:16 +0000
commit589e18a1f759698693029f1c3d4beed60deefc6c (patch)
treeb0abcbb015b5bf40217b738fff69cd631d97a99f
parent566451e5be927461def169e7677ce454bb96c45f (diff)
downloadcoreutils-589e18a1f759698693029f1c3d4beed60deefc6c.tar.xz
Tweak new examples based on Karl B.s suggestions.
-rw-r--r--doc/sh-utils.texi39
1 files changed, 21 insertions, 18 deletions
diff --git a/doc/sh-utils.texi b/doc/sh-utils.texi
index 2f626e840..925f0473e 100644
--- a/doc/sh-utils.texi
+++ b/doc/sh-utils.texi
@@ -2454,29 +2454,37 @@ Mon, 25 Mar 1996 23:34:17 -0600
@end example
@item
-To convert a date string to the number of seconds since 1970-01-01 00:00:00,
-use the @samp{--date} option with the @samp{%s} format.
-That can be useful in sorting and graphing data by date.
-The command in the following example prints the number of seconds that
-elapsed between the epoch and the specified date: one second after midnight
-on 1970-01-01.
-But it is important to note that the date string is interpreted relative
-to the local time zone, UTC+2, so it is two hours and one second
-or @samp{7201} seconds after the @code{epoch}.
+To convert a date string to the number of seconds since the epoch
+(which is 1970-01-01 00:00:00 UTC), use the @samp{--date} option with
+the @samp{%s} format. That can be useful in sorting and/or graphing
+and/or comparing data by date. The following command outputs the
+number of the seconds since the epoch for the time one second later
+than the epoch, but in the time zone two hours later, thus a total
+of two hours and one second after the epoch:
@example
-% env TZ=UTC+2 date --date='1970-01-01 00:00:01' +%s
+date --date='1970-01-01 00:00:01 UTC +2 hours' +%s
7201
@end example
+Suppose you had @emph{not} specified time zone information in the example above.
+Then, date would have used your computer's idea of the time zone when
+interpreting the string. Here's what you would get if you were six
+hours later than UTC on that day:
+
+@example
+date --date='1970-01-01 00:00:01' +%s
+21601
+@end example
+
@item
If you're sorting or graphing dated data, your raw date values may be
represented as seconds since the epoch. But few people can look at
the date @samp{946684800} and casually note ``Oh, that's the first second
-of the third millenium.''
+of the year 2000.''
@example
-% env TZ=UTC date --date='2000-01-01' +%s
+date --date='2000-01-01 UTC' +%s
946684800
@end example
@@ -2484,15 +2492,10 @@ To convert such an unwieldy number of seconds back to
a more readable form, use a command like this:
@smallexample
-% env TZ=UTC date -d '1970-01-01 UTC 946684800 sec' +"%Y-%m-%d %T %z"
+date -d '1970-01-01 946684800 sec' +"%Y-%m-%d %T %z"
2000-01-01 00:00:00 +0000
@end smallexample
-Note that in the few preceding examples, the timezone was set to
-a specific value through the @samp{TZ} environment variable.
-If you do not set @samp{TZ}, you must remember that @samp{--date}
-strings are converted relative to the local time zone.
-
@end itemize