[tz] [PROPOSED] Document GMT0 and posixrules better

[Paul Eggert]

Document the role of /usr/share/zoneinfo/GMT0.
Also, improve the documentation for /usr/share/zoneinfo/posixrules.
---
 date.1     | 14 +++++---------
 newctime.3 | 16 ++++++----------
 newtzset.3 | 44 +++++++++++++++++++++++++-------------------
 zic.8      | 12 ++++++------
 4 files changed, 42 insertions(+), 44 deletions(-)

diff --git a/date.1 b/date.1
index e8107212..01907bc7 100644
--- a/date.1
+++ b/date.1
@@ -154,15 +154,11 @@ hexadecimal (leading 0x), preceded by an optional sign.
 .br
 /usr/lib/locale/\f2L\fP/LC_TIME	description of time locale \f2L\fP
 .br
-/usr/share/zoneinfo	timezone information directory
+/usr/share/zoneinfo	timezone directory
 .br
-/usr/share/zoneinfo/posixrules	default DST rules (obsolete,
-	and can cause bugs if present)
+/usr/share/zoneinfo/posixrules	default DST rules (obsolete)
 .br
 /usr/share/zoneinfo/GMT	for UTC leap seconds
-.sp
-If
-.B /usr/share/zoneinfo/GMT
-is absent,
-UTC leap seconds are loaded from
-.BR /usr/share/zoneinfo/posixrules .
+.PP
+If /usr/share/zoneinfo/GMT is absent,
+UTC leap seconds are loaded from /usr/share/zoneinfo/GMT0 if present.
diff --git a/newctime.3 b/newctime.3
index 05bb7dea..3b54d4ad 100644
--- a/newctime.3
+++ b/newctime.3
@@ -292,20 +292,16 @@ will
 continue to exist in this form in future releases of this code.
 .SH FILES
 .ta \w'/usr/share/zoneinfo/posixrules\0\0'u
-/usr/share/zoneinfo	timezone information directory
+/etc/localtime	local timezone file
 .br
-/usr/share/zoneinfo/localtime	local timezone file
+/usr/share/zoneinfo	timezone directory
 .br
-/usr/share/zoneinfo/posixrules	default DST rules (obsolete,
-	and can cause bugs if present)
+/usr/share/zoneinfo/posixrules	default DST rules (obsolete)
 .br
 /usr/share/zoneinfo/GMT	for UTC leap seconds
-.sp
-If
-.B /usr/share/zoneinfo/GMT
-is absent,
-UTC leap seconds are loaded from
-.BR /usr/share/zoneinfo/posixrules .
+.PP
+If /usr/share/zoneinfo/GMT is absent,
+UTC leap seconds are loaded from /usr/share/zoneinfo/GMT0 if present.
 .SH SEE ALSO
 getenv(3),
 newstrftime(3),
diff --git a/newtzset.3 b/newtzset.3
index 78b6b6ce..80617cd7 100644
--- a/newtzset.3
+++ b/newtzset.3
@@ -306,21 +306,31 @@ The abbreviations for standard and daylight saving time are
 and
 .q "\*-02".
 .PP
-If no
-.I rule
-is present in
-.BR TZ ,
-the rules specified
-by the
+If
+.B TZ
+specifies daylight saving time but does not specify a
+.IR rule ,
+and the optional
 .BR tzfile (5)-format
 file
 .B posixrules
-in the system time conversion information directory are used, with the
-standard and daylight saving time offsets from UT replaced by those specified by
-the
+is present in the system time conversion information directory, the
+rules in
+.B posixrules
+are used, with the
+.B posixrules
+standard and daylight saving time offsets from UT
+replaced by those specified by the
 .I offset
 values in
 .BR TZ .
+However, the
+.B posixrules
+file is obsolete: if it is present it is only for backward compatibility,
+and it does not work reliably.
+Therefore, applications that specify a
+.B TZ
+string with daylight saving time should specify rules explicitly.
 .PP
 For compatibility with System V Release 3.1, a semicolon
 .RB ( ; )
@@ -329,20 +339,16 @@ may be used to separate the
 from the rest of the specification.
 .SH FILES
 .ta \w'/usr/share/zoneinfo/posixrules\0\0'u
-/usr/share/zoneinfo	timezone information directory
+/etc/localtime	local timezone file
 .br
-/usr/share/zoneinfo/localtime	local timezone file
+/usr/share/zoneinfo	timezone directory
 .br
-/usr/share/zoneinfo/posixrules	default DST rules (obsolete,
-	and can cause bugs if present)
+/usr/share/zoneinfo/posixrules	default DST rules (obsolete)
 .br
 /usr/share/zoneinfo/GMT	for UTC leap seconds
-.sp
-If
-.B /usr/share/zoneinfo/GMT
-is absent,
-UTC leap seconds are loaded from
-.BR /usr/share/zoneinfo/posixrules .
+.PP
+If /usr/share/zoneinfo/GMT is absent,
+UTC leap seconds are loaded from /usr/share/zoneinfo/GMT0 if present.
 .SH SEE ALSO
 getenv(3),
 newctime(3),
diff --git a/zic.8 b/zic.8
index c467efef..6bcef7ae 100644
--- a/zic.8
+++ b/zic.8
@@ -121,6 +121,12 @@ will act as if the input contained a link line of the form
 .ti +.5i
 Link	\fItimezone\fP		posixrules
 .sp
+If
+.I timezone
+is
+.q "\*-"
+(the default), any already-existing link is removed.
+.sp
 Unless
 .I timezone is
 .q "\*-" ,
@@ -131,12 +137,6 @@ and it should not be combined with
 if
 .IR timezone 's
 transitions are at standard time or Universal Time (UT) instead of local time.
-.sp
-If
-.I timezone
-is
-.BR \*- ,
-any already-existing link is removed.
 .TP
 .BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]"
 Limit the applicability of output files
-- 
2.41.0