[tz] [PATCH 2/3] Replace some zones with links when that doesn't lose non-LMT info.

[Paul Eggert]

Thanks for the review.  I pushed the following patch
into the experimental repository to try to fix (or
at least document) the problems that you noted.

diff --git a/newctime.3 b/newctime.3
index 8528deb..ece8507 100644
--- a/newctime.3
+++ b/newctime.3
@@ -36,8 +36,6 @@ asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time to
 .I Ctime\^
 converts a long integer, pointed to by
 .IR clock ,
-representing the time in seconds since
-00:00:00 UTC, 1970-01-01,
 and returns a pointer to a
 string of the form
 .br
@@ -59,6 +57,17 @@ These unusual formats are designed to make it less likely that older
 software that expects exactly 26 bytes of output will mistakenly output
 misleading values for out-of-range years.
 .PP
+The
+.BI * clock
+time stamp represents the time in seconds since 1970-01-01 00:00:00
+Coordinated Universal Time (UTC).
+The POSIX standard says that time stamps must be nonnegative
+must ignore leap seconds.
+Many implementations extend POSIX by allowing negative time stamps,
+and can therefore represent time stamps that that predate the
+introduction of UTC and are some other flavor of Universal Time (UT).
+Some implementations support leap seconds, in contradiction to POSIX.
+.PP
 .I Localtime\^
 and
 .I gmtime\^
@@ -186,6 +195,7 @@ is non-zero if summer time is in effect.
 is the offset (in seconds) of the time represented
 from UT, with positive values indicating east
 of the Prime Meridian.
+The field's name is derived from Greenwich Mean Time, a precursor of UT.
 .SH FILES
 .ta \w'/usr/local/etc/zoneinfo/posixrules\0\0'u
 /usr/local/etc/zoneinfo	time zone information directory
diff --git a/newstrftime.3 b/newstrftime.3
index 5b0dcdc..d39915c 100644
--- a/newstrftime.3
+++ b/newstrftime.3
@@ -164,7 +164,7 @@ using AM/PM notation.
 is replaced by the second as a decimal number (00-60).
 .TP
 %s
-is replaced by the number of seconds since the Epoch, UT (see mktime(3)).
+is replaced by the number of seconds since the Epoch (see newctime(3)).
 .TP
 %T
 is replaced by the time in the format %H:%M:%S.
@@ -211,7 +211,8 @@ is replaced by the time zone name,
 or by the empty string if this is not determinable.
 .TP
 %z
-is replaced by the offset from UT in the format +HHMM or -HHMM as appropriate,
+is replaced by the offset from the Prime Meridian
+in the format +HHMM or \(miHHMM as appropriate,
 with positive values representing locations east of Greenwich,
 or by the empty string if this is not determinable.
 .TP
diff --git a/newtzset.3 b/newtzset.3
index 8162920..3689e50 100644
--- a/newtzset.3
+++ b/newtzset.3
@@ -27,8 +27,9 @@ If
 .B TZ
 appears in the environment but its value is a null string,
 Universal Time (UT) is used, with the abbreviation "UTC"
-and without leap second
-correction.  If
+and without leap second correction; please see
+.IR newctime (3)
+for more about UT, UTC, and leap seconds.  If
 .B TZ
 appears in the environment and its value is not a null string:
 .IP
diff --git a/zdump.8 b/zdump.8
index af3277d..106361a 100644
--- a/zdump.8
+++ b/zdump.8
@@ -61,6 +61,14 @@ Time discontinuities are found by sampling the results returned by localtime
 at twelve-hour intervals.
 This works in all real-world cases;
 one can construct artificial time zones for which this fails.
+.PP
+In the output, "UT" denotes the value returned by
+.IR gmtime (3),
+which uses UTC for modern time stamps and some other UT flavor for
+time stamps that predate the introduction of UTC.
+No attempt is currently made to have the output use "UTC" for newer
+and "UT" for older time stamps,
+partly because the exact date of the introduction of UTC is problematic.
 .SH "SEE ALSO"
 newctime(3), tzfile(5), zic(8)
 .\" This file is in the public domain, so clarified as of