master f167bd0230d: Update doc for North American time zone changes

branch: master
commit f167bd0230d81c7001d3cdbcbc56203d3a5240f0
Author: Paul Eggert <[email protected]>
Commit: Paul Eggert <[email protected]>

    Update doc for North American time zone changes
    
    This year British Columbia and Alberta moved one time zone east,
    discarding daylight saving time, and it’s possible that more of North
    America will follow suit.  Adjust doc strings and manual to be
    more robust in the presence of these changes.
---
 doc/emacs/calendar.texi                     |  6 +++---
 doc/misc/calc.texi                          |  4 +++-
 lisp/calc/calc-forms.el                     |  5 ++++-
 lisp/calendar/cal-dst.el                    |  4 ++--
 lisp/calendar/icalendar-recur.el            | 15 +++++++++------
 lisp/calendar/parse-time.el                 |  8 +++++++-
 lisp/timezone.el                            |  4 ++--
 test/lisp/calendar/icalendar-recur-tests.el |  3 ++-
 8 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi
index a9ac654cdca..5593c64f546 100644
--- a/doc/emacs/calendar.texi
+++ b/doc/emacs/calendar.texi
@@ -660,9 +660,9 @@ if these values are not what you want (or if the operating system does
 not supply them), you must set them yourself.  Here is an example:
 
 @example
-(setq calendar-time-zone -360)
-(setq calendar-standard-time-zone-name "CST")
-(setq calendar-daylight-time-zone-name "CDT")
+(setq calendar-time-zone (* 12 60))
+(setq calendar-standard-time-zone-name "NZST")
+(setq calendar-daylight-time-zone-name "NZDT")
 @end example
 
 @noindent
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index a626ee09f8e..72690e8d286 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -17373,6 +17373,8 @@ For example @samp{tzone(PST) = tzone(8)} and @samp{tzone(pdt) = tzone(7)}
 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,
+the @samp{PST}- and @samp{MST-}related names have disagreed with
+time in western Canada since 2026,
 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,
@@ -17397,7 +17399,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
-circa-2022 US Pacific Time look like this:
+circa-2025 US Pacific Time look like this:
 
 @smallexample
 @group
diff --git a/lisp/calc/calc-forms.el b/lisp/calc/calc-forms.el
index adb2d932a9a..d6ff7e953f5 100644
--- a/lisp/calc/calc-forms.el
+++ b/lisp/calc/calc-forms.el
@@ -1474,7 +1474,10 @@ This is measured in the integer number of days from December 31,
     ( "PGT" 8 "PST" "PDT" ) ( "PST" 8 0 ) ( "PDT" 8 -1 )  ; Pacific
     ( "YGT" 9 "YST" "YDT" ) ( "YST" 9 0 ) ( "YDT" 9 -1 )  ; Yukon
     )
-  "No doc yet.  See calc manual for now.")
+  "No doc yet.  See calc manual for now.
+This variable is obsolete and new software should not rely on its
+contents.  Its abbreviations like \"PST\" have their circa 1970 meanings
+even if timekeeping has changed since then.")
 
 (defvar var-TimeZone nil)
 
diff --git a/lisp/calendar/cal-dst.el b/lisp/calendar/cal-dst.el
index 7681059f592..8285bbb09fb 100644
--- a/lisp/calendar/cal-dst.el
+++ b/lisp/calendar/cal-dst.el
@@ -356,7 +356,7 @@ If the locale never uses daylight saving time, set this to 0."
         "-0000")
     (or (nth 2 calendar-current-time-zone-cache) "UTC"))
   "Abbreviated name of standard time zone at `calendar-location-name'.
-For example, \"-0500\" or \"EST\" in New York City."
+For example, \"+1200\" or \"NZST\" in New Zealand."
   :type 'string
   :version "28.1"
   :set-after '(calendar-time-zone-style))
@@ -369,7 +369,7 @@ For example, \"-0500\" or \"EST\" in New York City."
         "-0000")
     (or (nth 3 calendar-current-time-zone-cache) "UTC"))
   "Abbreviated name of daylight saving time zone at `calendar-location-name'.
-For example, \"-0400\" or \"EDT\" in New York City."
+For example, \"+1300\" or \"NZDT\" in New Zealand."
   :type 'string
   :version "28.1"
   :set-after '(calendar-time-zone-style))
diff --git a/lisp/calendar/icalendar-recur.el b/lisp/calendar/icalendar-recur.el
index fbbfb209ca7..9bf55d4ba8b 100644
--- a/lisp/calendar/icalendar-recur.el
+++ b/lisp/calendar/icalendar-recur.el
@@ -1543,12 +1543,15 @@ UTC offsets local to that time zone."
 ;; time described occurs more than once (when changing from daylight to
 ;; standard time), the DATE-TIME value refers to the first occurrence of
 ;; the referenced time.  Thus, TZID=America/New_York:20071104T013000
-;; indicates November 4, 2007 at 1:30 A.M.  EDT (UTC-04:00).  If the
+;; indicates November 4, 2007 at 1:30 A.M. EDT (UTC-04:00).  If the
 ;; local time described does not occur (when changing from standard to
 ;; daylight time), the DATE-TIME value is interpreted using the UTC
 ;; offset before the gap in local times.  Thus,
 ;; TZID=America/New_York:20070311T023000 indicates March 11, 2007 at
-;; 3:30 A.M.  EDT (UTC-04:00), one hour after 1:30 A.M.  EST (UTC-05:00)."
+;; 3:30 A.M. EDT (UTC-04:00), one hour after 1:30 A.M. EST (UTC-05:00)."
+;; This quote from RFC 5545 is based on New York's 2007 timekeeping practice;
+;; although that practice may change in the future, the example is still
+;; valid for 2007.
 
 ;; TODO: verify that these functions are correct for time zones other
 ;; than US Eastern.
@@ -1641,10 +1644,10 @@ OBS-ONSET, or a range of local times that occur twice (see
 `icalendar-recur-nonexistent-date-time-p' and
 `icalendar-recur-date-time-occurs-twice-p'), it needs to be interpreted
 with the UTC offset in effect prior to the OBS-ONSET of OBSERVANCE (see
-RFC5545 Section 3.3.5).  So e.g. at the switch from Standard to Daylight
-in US Eastern, 2:30AM EST (a nonexistent time) becomes 3:30AM EDT, and
-at the switch from Daylight to Standard, 1:30AM (which occurs twice)
-becomes 1:30AM EDT, the first occurrence."
+RFC5545 Section 3.3.5).  So, for example, at the switch from standard to
+daylight in New Zealand, 2:30AM NZST (a nonexistent time) becomes 3:30AM NZDT,
+and at the switch from daylight to standard, 2:30AM (which occurs twice)
+becomes 1:30AM NZDT, the first occurrence."
   (ical:with-component observance
       ((ical:tzoffsetfrom :value offset-from)
        (ical:tzoffsetto :value offset-to))
diff --git a/lisp/calendar/parse-time.el b/lisp/calendar/parse-time.el
index 21e0e2d569d..16eab83433d 100644
--- a/lisp/calendar/parse-time.el
+++ b/lisp/calendar/parse-time.el
@@ -95,7 +95,11 @@ letters, digits, plus or minus signs or colons."
 			      ("mst" ,(* -7 3600)) ("mdt" ,(* -6 3600) t)
 			      ("cst" ,(* -6 3600)) ("cdt" ,(* -5 3600) t)
 			      ("est" ,(* -5 3600)) ("edt" ,(* -4 3600) t))
-  "(zoneinfo seconds-off daylight-savings-time-p)")
+  "List of some RFC 822 (or later) alphabetic time zones.
+
+Each entry is in the form (ABBR UTC-OFFSET DAYLIGHT-SAVING-TIME-P).
+As specified in the RFCs, a time zone abbreviation like \"PST\" retains
+its circa 1970 meaning even if legislation changes Pacific time.")
 
 (defvar parse-time-rules
   `(((6) parse-time-weekdays)
@@ -163,6 +167,8 @@ affect the returned value of date and time, they only affect the
 last two members of the returned value.  This function simply
 parses the textual representation of date and time into separate
 numerical values, and doesn't care whether the time is local or UTC.
+Also, alphabetic time zone abbreviations like \"PST\" have their
+circa 1970 meanings, even if current usage differs.
 
 See `decode-time' for the meaning of FORM."
   (condition-case ()
diff --git a/lisp/timezone.el b/lisp/timezone.el
index 63f58a477b0..643e974ece0 100644
--- a/lisp/timezone.el
+++ b/lisp/timezone.el
@@ -52,8 +52,8 @@
     ("GMT-10" . -1000) ("GMT-11" . -1100) ("GMT-12" . -1200))
   "Time differentials of timezone from GMT in +-HHMM form.
 This list is obsolescent, and is present only for backwards compatibility,
-because time zone names are ambiguous in practice.
-Use `current-time-zone' instead.")
+because time zone names are ambiguous in practice; for example, abbreviations
+like \"PST\" can change meaning with time.  Use `current-time-zone' instead.")
 
 (defvar timezone-months-assoc
   '(("JAN" .  1)("FEB" .  2)("MAR" .  3)
diff --git a/test/lisp/calendar/icalendar-recur-tests.el b/test/lisp/calendar/icalendar-recur-tests.el
index 199d6c4aa25..77e6f89744f 100644
--- a/test/lisp/calendar/icalendar-recur-tests.el
+++ b/test/lisp/calendar/icalendar-recur-tests.el
@@ -83,7 +83,8 @@ TZNAME:EST
 END:STANDARD
 END:VTIMEZONE
 ")
-"`icalendar-vtimezone' representing America/New_York (Eastern) time.")
+"`icalendar-vtimezone' representing America/New_York (Eastern) time
+from 1967 to at least 2026.")
 
 (defconst ict:est-latest
   (ical:with-component ict:tz-eastern