- add an example to date(1) showing how to convert between timezones

- update the description of TZ in date(1) - mention some relevant info
to avoid sending the reader to another page and, when they have to refer
to another page, send them to tzset(3) rather than environ(7)
- update the timezone name used in environ(7), as advised by millert

ok millert

2 files changed, 15 insertions, 7 deletions

diff --git a/bin/date/date.1 b/bin/date/date.1
index ec3ac698d8d..21298329a38 100644
--- a/bin/date/date.1
+++ b/bin/date/date.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: date.1,v 1.67 2016/09/12 17:28:47 jca Exp $
+.\"	$OpenBSD: date.1,v 1.68 2018/10/17 05:49:43 jmc Exp $
 .\"	$NetBSD: date.1,v 1.12 1996/03/12 04:32:37 phil Exp $
 .\"
 .\" Copyright (c) 1980, 1990, 1993
@@ -33,7 +33,7 @@
 .\"
 .\"     @(#)date.1	8.3 (Berkeley) 4/28/95
 .\"
-.Dd $Mdocdate: September 12 2016 $
+.Dd $Mdocdate: October 17 2018 $
 .Dt DATE 1
 .Os
 .Sh NAME
@@ -166,8 +166,10 @@ and leap years are handled automatically.
 .Bl -tag -width Ds
 .It Ev TZ
 The time zone to use when parsing or displaying dates.
-See
-.Xr environ 7
+It is normally specified as a pathname relative to
+.Pa /usr/share/zoneinfo ,
+though see
+.Xr tzset 3
 for more information.
 If this variable is not set, the time zone is determined based on
 .Pa /etc/localtime ,
@@ -204,6 +206,12 @@ Set the time to
 without modifying the date:
 .Pp
 .Dl # date 1432
+.Pp
+If the mailing list server located in California
+is being taken offline at 05.45,
+work out what time it will be locally, here in Tokyo:
+.Pp
+.Dl $ TZ=America/Los_Angeles date -j -z Asia/Tokyo 0545
 .Sh SEE ALSO
 .Xr adjtime 2 ,
 .Xr gettimeofday 2 ,
diff --git a/share/man/man7/environ.7 b/share/man/man7/environ.7
index d9d1670c6d2..538aab8d153 100644
--- a/share/man/man7/environ.7
+++ b/share/man/man7/environ.7
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: environ.7,v 1.19 2015/09/10 18:47:57 schwarze Exp $
+.\"	$OpenBSD: environ.7,v 1.20 2018/10/17 05:49:43 jmc Exp $
 .\"	$NetBSD: environ.7,v 1.4 1995/07/03 19:45:07 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1990, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)environ.7	8.3 (Berkeley) 4/19/94
 .\"
-.Dd $Mdocdate: September 10 2015 $
+.Dd $Mdocdate: October 17 2018 $
 .Dt ENVIRON 7
 .Os
 .Sh NAME
@@ -159,7 +159,7 @@ The time zone to use when displaying dates.
 The normal format is a pathname relative to
 .Pa /usr/share/zoneinfo .
 For example, the command
-.Ic env TZ=US/Pacific date
+.Ic env TZ=America/Los_Angeles date
 displays the current time in California.
 See
 .Xr tzset 3