Document calc-time-zone abbreviation obsolescence

* doc/misc/calc.texi (Time Zones): Document that alphabetic
time zone abbreviations are obsolescent and in some cases wrong.

1 files changed, 7 insertions, 3 deletions

diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index ef9990c057a..e5bac25cac8 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -17341,8 +17341,12 @@ it can be a variable which is a time zone name in upper- or lower-case.
 For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
 (for Pacific standard and daylight saving times, respectively).
 
-North American and European time zone names are defined as follows;
-note that for each time zone there is one name for standard time,
+North American and European time zone names are defined as follows.
+These names are obsolescent and new code should not rely on them:
+the @samp{YST}-related names have disagreed with time in Yukon since 1973,
+and other names could well become confusing or wrong in the future
+as countries change their time zone rules.
+For each time zone there is one name for standard time,
 another for daylight saving time, and a third for ``generalized'' time
 in which the daylight saving adjustment is computed from context.
 
@@ -17364,7 +17368,7 @@ To define time zone names that do not appear in the above table,
 you must modify the Lisp variable @code{math-tzone-names}.  This
 is a list of lists describing the different time zone names; its
 structure is best explained by an example.  The three entries for
-Pacific Time look like this:
+circa-2022 US Pacific Time look like this:
 
 @smallexample
 @group