Bring doc up-to-date with draft POSIX

* Makefile, date.1, newctime.3, newtzset.3, theory.html:
Don’t say settings like TZ='EST5EDT' are “nonstandard and obsolete”,
as draft POSIX says they use implementation-defined DST rules.
Clarify and strengthen the wording of the description of the
now-obsolete POSIXRULES macro and posixrules file, the latter of
which is still commonly installed even though it does not work.
Improve doc for TZDEFRULESTRING.  Give Morocco instead of
Iran as an example of unusual DST, as Iran no longer observes DST.

6 files changed, 30 insertions, 26 deletions

diff --git a/Makefile b/Makefile
index 5ebd5d2..95b5448 100644
--- a/Makefile
+++ b/Makefile
@@ -35,22 +35,14 @@ DATAFORM=		main
 
 LOCALTIME=	Factory
 
-# The POSIXRULES macro controls interpretation of nonstandard and obsolete
-# POSIX-like TZ settings like TZ='EET-2EEST' that lack DST transition rules.
-# Such a setting uses the rules in a template file to determine
-# "spring forward" and "fall back" days and times; the environment
-# variable itself specifies UT offsets of standard and daylight saving time.
-#
+# The POSIXRULES macro controls interpretation of POSIX-like TZ
+# settings like TZ='EET-2EEST' that lack DST transition rules.
 # If POSIXRULES is '-', no template is installed; this is the default.
-#
 # Any other value for POSIXRULES is obsolete and should not be relied on, as:
 # * It does not work correctly in popular implementations such as GNU/Linux.
 # * It does not work even in tzcode, except for historical timestamps
 #   that precede the last explicit transition in the POSIXRULES file.
 #   Hence it typically does not work for current and future timestamps.
-# In short, software should avoid ruleless settings like TZ='EET-2EEST'
-# and so should not depend on the value of POSIXRULES.
-#
 # If, despite the above, you want a template for handling these settings,
 # you can change the line below (after finding the timezone you want in the
 # one of the $(TDATA) source files, or adding it to a source file).
@@ -63,7 +55,7 @@ LOCALTIME=	Factory
 POSIXRULES=	-
 
 # Also see TZDEFRULESTRING below, which takes effect only
-# if the time zone files cannot be accessed.
+# if POSIXRULES is '-' or if the template file cannot be accessed.
 
 
 # Installation locations.
@@ -258,7 +250,12 @@ LDLIBS=
 #  -DTZ_DOMAINDIR=\"/path\" to use "/path" for gettext directory;
 #	the default is system-supplied, typically "/usr/lib/locale"
 #  -DTZDEFRULESTRING=\",date/time,date/time\" to default to the specified
-#	DST transitions if the time zone files cannot be accessed
+#	DST transitions for POSIX-style TZ strings lacking them,
+#	in the usual case where POSIXRULES is '-'.  If not specified,
+#	TZDEFRULESTRING defaults to US rules for future DST transitions.
+#	This mishandles some past timestamps, as US DST rules have changed.
+#	It also mishandles settings like TZ='EET-2EEST' for eastern Europe,
+#	as Europe and US DST rules differ.
 #  -DUNINIT_TRAP if reading uninitialized storage can cause problems
 #	other than simply getting garbage data
 #  -DUSE_LTZ=0 to build zdump with the system time zone library
diff --git a/date.1 b/date.1
index 043e568..8670ff1 100644
--- a/date.1
+++ b/date.1
@@ -156,7 +156,8 @@ hexadecimal (leading 0x), preceded by an optional sign.
 .br
 /usr/share/zoneinfo	timezone information directory
 .br
-/usr/share/zoneinfo/posixrules	used with POSIX-style TZ's
+/usr/share/zoneinfo/posixrules	default DST rules (obsolete,
+	and can cause bugs if present)
 .br
 /usr/share/zoneinfo/GMT	for UTC leap seconds
 .sp
diff --git a/newctime.3 b/newctime.3
index 2790c81..0860151 100644
--- a/newctime.3
+++ b/newctime.3
@@ -296,7 +296,8 @@ continue to exist in this form in future releases of this code.
 .br
 /usr/share/zoneinfo/localtime	local timezone file
 .br
-/usr/share/zoneinfo/posixrules	used with POSIX-style TZ's
+/usr/share/zoneinfo/posixrules	default DST rules (obsolete,
+	and can cause bugs if present)
 .br
 /usr/share/zoneinfo/GMT	for UTC leap seconds
 .sp
diff --git a/newtzset.3 b/newtzset.3
index 1e75acf..086152a 100644
--- a/newtzset.3
+++ b/newtzset.3
@@ -333,7 +333,8 @@ from the rest of the specification.
 .br
 /usr/share/zoneinfo/localtime	local timezone file
 .br
-/usr/share/zoneinfo/posixrules	used with POSIX-style TZ
+/usr/share/zoneinfo/posixrules	default DST rules (obsolete,
+	and can cause bugs if present)
 .br
 /usr/share/zoneinfo/GMT	for UTC leap seconds
 .sp
diff --git a/theory.html b/theory.html
index 0470600..7870a91 100644
--- a/theory.html
+++ b/theory.html
@@ -878,7 +878,7 @@ an older <code>zic</code>.
     is error-prone in practice.
     Also, POSIX <code>TZ</code> strings cannot deal with daylight
     saving time rules not based on the Gregorian calendar (as in
-    Iran), or with situations where more than two time zone
+    Morocco), or with situations where more than two time zone
     abbreviations or <abbr>UT</abbr> offsets are used in an area.
     </p>
 
@@ -914,8 +914,8 @@ an older <code>zic</code>.
       <dt><var>date</var>[<code>/</code><var>time</var>]<code>,</code><var>date</var>[<code>/</code><var>time</var>]</dt><dd>
 	specifies the beginning and end of <abbr>DST</abbr>.
 	If this is absent, the system supplies its own ruleset
-	for <abbr>DST</abbr>, and its rules can differ from year to year;
-	typically <abbr>US</abbr> <abbr>DST</abbr> rules are used.
+	for <abbr>DST</abbr>, typically	current <abbr>US</abbr>
+	<abbr>DST</abbr> rules.
       </dd>
       <dt><var>time</var></dt><dd>
 	takes the form
@@ -975,10 +975,11 @@ an older <code>zic</code>.
     Traditionally the current <abbr>US</abbr> <abbr>DST</abbr> rules
     were used to interpret such values, but this meant that the
     <abbr>US</abbr> <abbr>DST</abbr> rules were compiled into each
-    program that did time conversion. This meant that when
+    time conversion package, and when
     <abbr>US</abbr> time conversion rules changed (as in the United
-    States in 1987), all programs that did time conversion had to be
-    recompiled to ensure proper results.
+    States in 1987 and again in 2007), all packages that
+    interpreted <code>TZ</code> values had to be updated
+    to ensure proper results.
   </li>
   <li>
     The <code>TZ</code> environment variable is process-global, which
diff --git a/zic.8 b/zic.8
index 019a289..06cf07b 100644
--- a/zic.8
+++ b/zic.8
@@ -121,7 +121,10 @@ will act as if the input contained a link line of the form
 .ti +.5i
 Link	\fItimezone\fP		posixrules
 .sp
-This feature is obsolete and poorly supported.
+Unless
+.I timezone is
+.q "\*-" ,
+this option is obsolete and poorly supported.
 Among other things it should not be used for timestamps after the year 2037,
 and it should not be combined with
 .B "\*-b slim"
@@ -242,10 +245,10 @@ for
 .PP
 The output file does not contain all the information about the
 long-term future of a timezone, because the future cannot be summarized as
-an extended POSIX TZ string.  For example, as of 2019 this problem
-occurs for Iran's daylight-saving rules for the predicted future, as
-these rules are based on the Iranian calendar, which cannot be
-represented.
+an extended POSIX TZ string.  For example, as of 2023 this problem
+occurs for Morocco's daylight-saving rules, as these rules are based
+on predictions for when Ramadan will be observed, something that
+an extended POSIX TZ string cannot represent.
 .PP
 The output contains data that may not be handled properly by client
 code designed for older