Merge branch 'master' into feature/igcfeature/igc

92 files changed, 17141 insertions, 1159 deletions

diff --git a/lisp/align.el b/lisp/align.el
index 1f1c8f58009..362d59f2231 100644
--- a/lisp/align.el
+++ b/lisp/align.el
@@ -1407,11 +1407,18 @@ aligner would have dealt with are."
                     (align-region
                      beg end 'entire
                      exclude-rules nil
+                     ;; Use markers for exclusion area bounds so
+                     ;; they remain accurate after subsequent
+                     ;; alignment sections modify the buffer.
                      (lambda (b e mode)
                        (or (and mode (listp mode))
+                           (let ((bm (copy-marker b))
+                                 (em (copy-marker e t)))
+                             (push bm markers)
+                             (push em markers)
                            (setq exclude-areas
-                                 (cons (cons b e)
-                                       exclude-areas)))))
+                                   (cons (cons bm em)
+                                         exclude-areas))))))
                     (setq exclude-areas
                           (nreverse
                            (sort exclude-areas #'car-less-than-car))))
@@ -1458,14 +1465,17 @@ aligner would have dealt with are."
                       (setq same nil)
                       (align--set-marker eol (line-end-position)))
 
-                    ;; remember the beginning position of this rule
-                    ;; match, and save the match-data, since either
-                    ;; the `valid' form, or the code that searches for
-                    ;; section separation, might alter it
-                    (setq rule-beg (match-beginning first)
-                          save-match-data (match-data))
-
-                    (or rule-beg
+                    ;; Remember the beginning position of this rule
+                    ;; match as a marker so it remains accurate after
+                    ;; `align-regions' modifies the buffer for a
+                    ;; previous alignment section.  Also save the
+                    ;; match-data, since either the `valid' form, or
+                    ;; the code that searches for section separation,
+                    ;; might alter it.
+                    (align--set-marker rule-beg (match-beginning first) t)
+                    (setq save-match-data (match-data))
+
+                    (or (marker-position rule-beg)
                         (error "No match for subexpression %s" first))
 
                     ;; unless the `valid' attribute is set, and tells
@@ -1480,6 +1490,18 @@ aligner would have dealt with are."
                       (when (and last-point
                                  (align-new-section-p last-point rule-beg
                                                       thissep))
+                        ;; Convert saved match-data positions to
+                        ;; markers before `align-regions' modifies
+                        ;; the buffer, so the restored match-data
+                        ;; reflects the updated buffer state.
+                        (setq save-match-data
+                              (mapcar (lambda (pos)
+                                        (if (integerp pos)
+                                            (let ((m (copy-marker pos)))
+                                              (push m markers)
+                                              m)
+                                          pos))
+                                      save-match-data))
                         (align-regions regions align-props rule func)
                         (setq regions nil)
                         (setq align-props nil))
diff --git a/lisp/battery.el b/lisp/battery.el
index 05f9c5ecadb..ee3e24b196c 100644
--- a/lisp/battery.el
+++ b/lisp/battery.el
@@ -207,8 +207,14 @@ The full `format-spec' formatting syntax is supported."
   :type '(choice string (const nil)))
 
 (defcustom battery-update-interval 60
-  "Seconds after which the battery status will be updated."
-  :type 'integer)
+  "Seconds after which the battery status will be updated.
+A value of nil means do not poll for battery status changes.
+This can be useful when `battery-status-function' is set to
+`battery-upower' and `battery-upower-subscribe' is non-nil, in
+which case D-Bus automatically signals battery status changes."
+  :version "31.1"
+  :type '(choice (const :tag "Never" nil)
+                 (integer :tag "Number of seconds")))
 
 (defcustom battery-load-low 25
   "Upper bound of low battery load percentage.
@@ -305,8 +311,9 @@ trigger actions based on battery-related events."
         (and (eq battery-status-function #'battery-upower)
              battery-upower-subscribe
              (battery--upower-subscribe))
-        (setq battery-update-timer (run-at-time nil battery-update-interval
-                                                #'battery-update-handler))
+        (when battery-update-interval
+          (setq battery-update-timer (run-at-time nil battery-update-interval
+                                                  #'battery-update-handler)))
         (battery-update))
     (message "Battery status not available")
     (setq display-battery-mode nil)))
@@ -772,17 +779,37 @@ See URL `https://upower.freedesktop.org/docs/Device.html'.")
 (defconst battery-upower-device-path "/org/freedesktop/UPower/devices"
   "D-Bus object providing `battery-upower-device-interface'.")
 
+(defconst battery-upower-display-device-path
+  "/org/freedesktop/UPower/devices/DisplayDevice"
+  "D-Bus object providing a subset of `battery-upower-device-interface'.
+This is a composite device for displaying a digest of overall state.
+In particular, it is not listed by the EnumerateDevices method.")
+
+(defvar battery-upower-subscribe-properties
+  '(;; `battery-upower-path' properties.
+    "OnBattery"
+    ;; `battery-upower-display-device-path' properties.
+    "State" "Percentage" "IsPresent")
+  "List of UPower device properties to listen for.
+Each value is a string property of `battery-upower-path'
+or `battery-upower-display-device-path'.
+A D-Bus signal that any of them changed results in a `battery-update'.")
+
 (defvar battery--upower-signals nil
   "Handles for UPower signal subscriptions.")
 
 (defun battery--upower-signal-handler (&rest _)
   "Update battery status on receiving a UPower D-Bus signal."
-  (timer-event-handler battery-update-timer))
+  (if battery-update-timer
+      (timer-event-handler battery-update-timer)
+    (battery-update-handler)))
 
 (defun battery--upower-props-changed (_interface changed _invalidated)
-  "Update status when system starts/stops running on battery.
+  "Update status when UPower device properties change.
+Respond only to those in `battery-upower-subscribe-properties'.
 Intended as a UPower PropertiesChanged signal handler."
-  (when (assoc "OnBattery" changed)
+  (when (any (lambda (prop) (assoc prop changed))
+             battery-upower-subscribe-properties)
     (battery--upower-signal-handler)))
 
 (defun battery--upower-unsubscribe ()
@@ -792,12 +819,20 @@ Intended as a UPower PropertiesChanged signal handler."
 
 (defun battery--upower-subscribe ()
   "Subscribe to UPower device change signals."
+  ;; Listen for OnBattery changes.
   (push (dbus-register-signal :system battery-upower-service
                               battery-upower-path
                               dbus-interface-properties
                               "PropertiesChanged"
                               #'battery--upower-props-changed)
         battery--upower-signals)
+  ;; Listen for DisplayDevice property changes.
+  (push (dbus-register-signal :system battery-upower-service
+                              battery-upower-display-device-path
+                              dbus-interface-properties
+                              "PropertiesChanged"
+                              #'battery--upower-props-changed)
+        battery--upower-signals)
   (dolist (method '("DeviceAdded" "DeviceRemoved"))
     (push (dbus-register-signal :system battery-upower-service
                                 battery-upower-path
@@ -879,8 +914,10 @@ The following %-sequences are provided:
        ((and (eq type 1) (not (eq line-status 'online)))
         ;; It's a line power device: `online' if currently providing
         ;; power, any other non-nil value if simply present.
-        (setq line-status (if (cdr (assoc "Online" props)) 'online t)))
-       ((and (eq type 2) (cdr (assoc "IsPresent" props)))
+        (setq line-status (or (not (cdr (assoc "Online" props))) 'online)))
+       ((and (eq type 2)
+             (cdr (assoc "PowerSupply" props))
+             (cdr (assoc "IsPresent" props)))
         ;; It's a battery.
         (setq count (1+ count))
         (setq state (battery--upower-state props state))
diff --git a/lisp/calendar/appt.el b/lisp/calendar/appt.el
index d6b8621d26b..df8e28319e5 100644
--- a/lisp/calendar/appt.el
+++ b/lisp/calendar/appt.el
@@ -81,8 +81,7 @@
 (defcustom appt-message-warning-time 12
   "Default time in minutes before an appointment that the warning begins.
 You probably want to make `appt-display-interval' a factor of this."
-  :type 'integer
-  :group 'appt)
+  :type 'integer)
 
 (defcustom appt-warning-time-regexp "warntime \\([0-9]+\\)"
   "Regexp matching a string giving the warning time for an appointment.
@@ -92,13 +91,11 @@ You may want to put this inside a diary comment (see `diary-comment-start').
 For example, to be warned 30 minutes in advance of an appointment:
    2011/06/01 12:00 Do something ## warntime 30"
   :version "24.1"
-  :type 'regexp
-  :group 'appt)
+  :type 'regexp)
 
 (defcustom appt-audible t
   "Non-nil means beep to indicate appointment."
-  :type 'boolean
-  :group 'appt)
+  :type 'boolean)
 
 ;; TODO - add popup.
 (defcustom appt-display-format 'window
@@ -112,7 +109,6 @@ See also `appt-audible' and `appt-display-mode-line'."
           (const :tag "Separate window" window)
           (const :tag "Echo-area" echo)
           (const :tag "No visible display" nil))
-  :group 'appt
   :version "24.1") ; no longer inherit from deleted obsolete variables
 
 (defcustom appt-display-mode-line t
@@ -120,21 +116,18 @@ See also `appt-audible' and `appt-display-mode-line'."
 This is in addition to any other display of appointment messages.
 The mode line updates every minute, independent of the value of
 `appt-display-interval'."
-  :type 'boolean
-  :group 'appt)
+  :type 'boolean)
 
 (defcustom appt-display-duration 10
   "The number of seconds an appointment message is displayed.
 Only relevant if reminders are to be displayed in their own window."
-  :type 'integer
-  :group 'appt)
+  :type 'integer)
 
 (defcustom appt-display-diary t
   "Non-nil displays the diary when the appointment list is first initialized.
 This occurs when this package is first activated, and then at
 midnight when the appointment list updates."
-  :type 'boolean
-  :group 'appt)
+  :type 'boolean)
 
 (defcustom appt-display-interval 3
   "Interval in minutes at which to display appointment reminders.
@@ -146,8 +139,7 @@ a final message displayed precisely when the appointment is due.
 Note that this variable controls the interval at which
 `appt-display-message' is called.  The mode line display (if active)
 always updates every minute."
-  :type 'integer
-  :group 'appt)
+  :type 'integer)
 
 (defcustom appt-disp-window-function #'appt-disp-window
   "Function called to display appointment window.
@@ -156,14 +148,12 @@ It should take three string arguments: the number of minutes till
 the appointment, the current time, and the text of the appointment.
 Each argument may also be a list, if multiple appointments are
 relevant at any one time."
-  :type 'function
-  :group 'appt)
+  :type 'function)
 
 (defcustom appt-delete-window-function #'appt-delete-window
   "Function called to remove appointment window and buffer.
 Only relevant if reminders are being displayed in a window."
-  :type 'function
-  :group 'appt)
+  :type 'function)
 
 (defface appt-notification
   '((t :inherit mode-line-emphasis))
@@ -602,7 +592,7 @@ Any appointments made with `appt-add' are not affected by this function."
                    (not (eq diary-number-of-entries 1))
                    (not (memq (car (last diary-list-entries-hook))
                               '(diary-sort-entries sort-diary-entries)))
-                   (setq entry-list (sort entry-list 'diary-entry-compare)))
+                   (setq entry-list (sort entry-list #'diary-entry-compare)))
               ;; Skip diary entries for dates before today.
               (while (and entry-list
                           (calendar-date-compare
diff --git a/lisp/calendar/cal-bahai.el b/lisp/calendar/cal-bahai.el
index ad0379bb731..8afa4046c4e 100644
--- a/lisp/calendar/cal-bahai.el
+++ b/lisp/calendar/cal-bahai.el
@@ -368,8 +368,7 @@ Reads a year, month and day."
          (month (cdr (assoc
                       (completing-read
                        "Bahá’í calendar month name: "
-                       (mapcar 'list
-                               (append calendar-bahai-month-name-array nil))
+                       (append calendar-bahai-month-name-array nil)
                        nil t)
                       (calendar-make-alist calendar-bahai-month-name-array
                                            1))))
diff --git a/lisp/calendar/cal-china.el b/lisp/calendar/cal-china.el
index af470030499..cadbd6f937f 100644
--- a/lisp/calendar/cal-china.el
+++ b/lisp/calendar/cal-china.el
@@ -65,8 +65,7 @@
   "Minutes difference between local standard time for Chinese calendar and UTC.
 Default is for Beijing.  This is an expression in `year' since it changed at
 1928-01-01 00:00:00 from UT+7:45:40 to UT+8."
-  :type 'sexp
-  :group 'calendar-chinese)
+  :type 'sexp)
 
 ;; It gets eval'd.
 ;;;###autoload
@@ -75,8 +74,7 @@ Default is for Beijing.  This is an expression in `year' since it changed at
 ;; FIXME unused.
 (defcustom calendar-chinese-location-name "Beijing"
   "Name of location used for calculation of Chinese calendar."
-  :type 'string
-  :group 'calendar-chinese)
+  :type 'string)
 
 (defcustom calendar-chinese-daylight-time-offset 0
 ;; The correct value is as follows, but the Chinese calendrical
@@ -84,8 +82,7 @@ Default is for Beijing.  This is an expression in `year' since it changed at
 ;;  60
   "Minutes difference between daylight saving and standard time.
 Default is for no daylight saving time."
-  :type 'integer
-  :group 'calendar-chinese)
+  :type 'integer)
 
 (defcustom calendar-chinese-standard-time-zone-name
   '(if (< year 1928)
@@ -95,13 +92,11 @@ Default is for no daylight saving time."
 This is an expression depending on `year' because it changed
 at 1928-01-01 00:00:00 from `PMT' to `CST'."
   :type 'sexp
-  :risky t
-  :group 'calendar-chinese)
+  :risky t)
 
 (defcustom calendar-chinese-daylight-time-zone-name "CDT"
   "Abbreviated name of daylight saving time zone used for Chinese calendar."
-  :type 'string
-  :group 'calendar-chinese)
+  :type 'string)
 
 (defcustom calendar-chinese-daylight-saving-start nil
 ;; The correct value is as follows, but the Chinese calendrical
@@ -113,8 +108,7 @@ at 1928-01-01 00:00:00 from `PMT' to `CST'."
 Default is for no daylight saving time.  See documentation of
 `calendar-daylight-savings-starts'."
   :type 'sexp
-  :risky t
-  :group 'calendar-chinese)
+  :risky t)
 
 (defcustom calendar-chinese-daylight-saving-end nil
 ;; The correct value is as follows, but the Chinese calendrical
@@ -124,25 +118,21 @@ Default is for no daylight saving time.  See documentation of
 Default is for no daylight saving time.  See documentation of
 `calendar-daylight-savings-ends'."
   :type 'sexp
-  :risky t
-  :group 'calendar-chinese)
+  :risky t)
 
 (defcustom calendar-chinese-daylight-saving-start-time 0
   "Number of minutes after midnight that daylight saving time starts.
 Default is for no daylight saving time."
-  :type 'integer
-  :group 'calendar-chinese)
+  :type 'integer)
 
 (defcustom calendar-chinese-daylight-saving-end-time 0
   "Number of minutes after midnight that daylight saving time ends.
 Default is for no daylight saving time."
-  :type 'integer
-  :group 'calendar-chinese)
+  :type 'integer)
 
 (defcustom calendar-chinese-celestial-stem
   ["Jia" "Yi" "Bing" "Ding" "Wu" "Ji" "Geng" "Xin" "Ren" "Gui"]
   "Prefixes used by `calendar-chinese-sexagesimal-name'."
-  :group 'calendar-chinese
   :type '(vector (string :tag "Jia")
                  (string :tag "Yi")
                  (string :tag "Bing")
@@ -157,7 +147,6 @@ Default is for no daylight saving time."
 (defcustom calendar-chinese-terrestrial-branch
   ["Zi" "Chou" "Yin" "Mao" "Chen" "Si" "Wu" "Wei" "Shen" "You" "Xu" "Hai"]
   "Suffixes used by `calendar-chinese-sexagesimal-name'."
-  :group 'calendar-chinese
   :type '(vector (string :tag "Zi")
                  (string :tag "Chou")
                  (string :tag "Yin")
@@ -188,7 +177,7 @@ The Zodiac signs begin when the sun's longitude is a multiple of 30 degrees."
   (with-suppressed-warnings ((lexical year))
     (defvar year))
   (let* ((year (calendar-extract-year (calendar-gregorian-from-absolute d)))
-         (calendar-time-zone (eval calendar-chinese-time-zone)) ; uses year
+         (calendar-time-zone (eval calendar-chinese-time-zone t)) ; uses year
          (calendar-daylight-time-offset
           calendar-chinese-daylight-time-offset)
          (calendar-standard-time-zone-name
@@ -212,7 +201,7 @@ The Zodiac signs begin when the sun's longitude is a multiple of 30 degrees."
   (with-suppressed-warnings ((lexical year))
     (defvar year))
   (let* ((year (calendar-extract-year (calendar-gregorian-from-absolute d)))
-         (calendar-time-zone (eval calendar-chinese-time-zone))
+         (calendar-time-zone (eval calendar-chinese-time-zone t))
          (calendar-daylight-time-offset
           calendar-chinese-daylight-time-offset)
          (calendar-standard-time-zone-name
diff --git a/lisp/calendar/cal-coptic.el b/lisp/calendar/cal-coptic.el
index 9696a484224..2878c35bb7c 100644
--- a/lisp/calendar/cal-coptic.el
+++ b/lisp/calendar/cal-coptic.el
@@ -148,8 +148,7 @@ Reads a year, month, and day."
          (month (cdr (assoc-string
                       (completing-read
                        (format "%s calendar month name: " calendar-coptic-name)
-                       (mapcar 'list
-                               (append calendar-coptic-month-name-array nil))
+                       (append calendar-coptic-month-name-array nil)
                        nil t)
                       (calendar-make-alist calendar-coptic-month-name-array
                                            1)
diff --git a/lisp/calendar/cal-dst.el b/lisp/calendar/cal-dst.el
index ca95fb59607..7681059f592 100644
--- a/lisp/calendar/cal-dst.el
+++ b/lisp/calendar/cal-dst.el
@@ -46,8 +46,7 @@ current date apply to all years.  This is faster, but not always
 correct, since the dates of daylight saving transitions sometimes
 change."
   :type 'boolean
-  :version "22.1"
-  :group 'calendar-dst)
+  :version "22.1")
 
 ;;;###autoload
 (put 'calendar-daylight-savings-starts 'risky-local-variable t)
@@ -68,8 +67,7 @@ If it starts on the first Sunday in April, you would set it to
       (calendar-nth-named-day 1 0 4 year)
 
 If the locale never uses daylight saving time, set this to nil."
-  :type 'sexp
-  :group 'calendar-dst)
+  :type 'sexp)
 
 ;;;###autoload
 (put 'calendar-daylight-savings-ends 'risky-local-variable t)
@@ -85,8 +83,7 @@ For example, if daylight saving time ends on the last Sunday in October:
       (calendar-nth-named-day -1 0 10 year)
 
 If the locale never uses daylight saving time, set this to nil."
-  :type 'sexp
-  :group 'calendar-dst)
+  :type 'sexp)
 
 ;;; More defcustoms below.
 
@@ -208,10 +205,12 @@ The result has the proper form for `calendar-daylight-savings-starts'."
           ;; we require an absolute date.  The following is for efficiency.
           (setq date (cond ((eq (car rule) #'calendar-nth-named-day)
                             (eval (cons #'calendar-nth-named-absday
-                                        (cdr rule))))
+                                        (cdr rule))
+                                  t))
                            ((eq (car rule) #'calendar-gregorian-from-absolute)
-                            (eval (cadr rule)))
-                           (t (calendar-absolute-from-gregorian (eval rule)))))
+                            (eval (cadr rule) t))
+                           (t (calendar-absolute-from-gregorian
+                               (eval rule t)))))
           (or (equal (current-time-zone
                       (calendar-time-from-absolute date prevday-sec))
                      (current-time-zone
@@ -226,7 +225,7 @@ The result has the proper form for `calendar-daylight-savings-starts'."
     (car candidate-rules)))
 
 ;; TODO it might be better to extract this information directly from
-;; the system timezone database. But cross-platform...?
+;; the system timezone database.  But cross-platform...?
 ;; See thread
 ;; https://lists.gnu.org/r/emacs-pretest-bug/2006-11/msg00060.html
 (defun calendar-dst-find-data (&optional time)
@@ -309,7 +308,9 @@ system knows:
 UTC-DIFF is an integer specifying the number of minutes difference between
     standard time in the current time zone and Coordinated Universal Time
     (Greenwich Mean Time).  A negative value means west of Greenwich.
-DST-OFFSET is an integer giving the daylight saving time offset in minutes.
+DST-OFFSET is an integer giving the daylight saving time offset in minutes
+    relative to UTC-DIFF.  (That is, the total UTC offset during daylight saving
+    time is UTC-DIFF + DST-OFFSET minutes.)
 STD-ZONE is a string giving the name of the time zone when no seasonal time
     adjustment is in effect.
 DST-ZONE is a string giving the name of the time zone when there is a seasonal
@@ -339,15 +340,13 @@ it can't find."
 (defcustom calendar-time-zone (or (car calendar-current-time-zone-cache) -300)
   "Number of minutes difference between local standard time and UTC.
 For example, -300 for New York City, -480 for Los Angeles."
-  :type 'integer
-  :group 'calendar-dst)
+  :type 'integer)
 
 (defcustom calendar-daylight-time-offset
   (or (cadr calendar-current-time-zone-cache) 60)
   "Number of minutes difference between daylight saving and standard time.
 If the locale never uses daylight saving time, set this to 0."
-  :type 'integer
-  :group 'calendar-dst)
+  :type 'integer)
 
 (defcustom calendar-standard-time-zone-name
   (if (eq calendar-time-zone-style 'numeric)
@@ -360,8 +359,7 @@ If the locale never uses daylight saving time, set this to 0."
 For example, \"-0500\" or \"EST\" in New York City."
   :type 'string
   :version "28.1"
-  :set-after '(calendar-time-zone-style)
-  :group 'calendar-dst)
+  :set-after '(calendar-time-zone-style))
 
 (defcustom calendar-daylight-time-zone-name
   (if (eq calendar-time-zone-style 'numeric)
@@ -374,21 +372,18 @@ For example, \"-0500\" or \"EST\" in New York City."
 For example, \"-0400\" or \"EDT\" in New York City."
   :type 'string
   :version "28.1"
-  :set-after '(calendar-time-zone-style)
-  :group 'calendar-dst)
+  :set-after '(calendar-time-zone-style))
 
 (defcustom calendar-daylight-savings-starts-time
   (or (nth 6 calendar-current-time-zone-cache) 120)
   "Number of minutes after midnight that daylight saving time starts."
-  :type 'integer
-  :group 'calendar-dst)
+  :type 'integer)
 
 (defcustom calendar-daylight-savings-ends-time
   (or (nth 7 calendar-current-time-zone-cache)
       calendar-daylight-savings-starts-time)
   "Number of minutes after midnight that daylight saving time ends."
-  :type 'integer
-  :group 'calendar-dst)
+  :type 'integer)
 
 
 (defun calendar-dst-starts (year)
@@ -398,7 +393,7 @@ This function respects the value of `calendar-dst-check-each-year-flag'."
                       (cadr (calendar-dst-find-startend year))
                     (nth 4 calendar-current-time-zone-cache))))
         (calendar-dlet ((year year))
-          (if expr (eval expr))))
+          (if expr (eval expr t))))
       ;; New US rules commencing 2007.  https://www.iana.org/time-zones
       (and (not (zerop calendar-daylight-time-offset))
            (calendar-nth-named-day 2 0 3 year))))
@@ -410,7 +405,7 @@ This function respects the value of `calendar-dst-check-each-year-flag'."
                       (nth 2 (calendar-dst-find-startend year))
                     (nth 5 calendar-current-time-zone-cache))))
         (calendar-dlet ((year year))
-          (if expr (eval expr))))
+          (if expr (eval expr t))))
       ;; New US rules commencing 2007.  https://www.iana.org/time-zones
       (and (not (zerop calendar-daylight-time-offset))
            (calendar-nth-named-day 1 0 11 year))))
@@ -421,8 +416,8 @@ This function respects the value of `calendar-dst-check-each-year-flag'."
 Fractional part of DATE is local standard time of day."
   (calendar-dlet ((year (calendar-extract-year
                           (calendar-gregorian-from-absolute (floor date)))))
-    (let* ((dst-starts-gregorian (eval calendar-daylight-savings-starts))
-           (dst-ends-gregorian (eval calendar-daylight-savings-ends))
+    (let* ((dst-starts-gregorian (eval calendar-daylight-savings-starts t))
+           (dst-ends-gregorian (eval calendar-daylight-savings-ends t))
            (dst-starts (and dst-starts-gregorian
                             (+ (calendar-absolute-from-gregorian
                                 dst-starts-gregorian)
diff --git a/lisp/calendar/cal-french.el b/lisp/calendar/cal-french.el
index 061ab4ebafa..28cb2515a86 100644
--- a/lisp/calendar/cal-french.el
+++ b/lisp/calendar/cal-french.el
@@ -344,7 +344,7 @@ Echo French Revolutionary date unless NOECHO is non-nil."
                      (calendar-absolute-from-gregorian
                       (calendar-current-date)))))))
           (month-list
-           (mapcar 'list
+           (mapcar #'list
                    (append months
                            (if (calendar-french-leap-year-p year)
                                (mapcar #'calendar-french-trim-feast feasts)
diff --git a/lisp/calendar/cal-hebrew.el b/lisp/calendar/cal-hebrew.el
index 213afc1d3ba..714f18999fa 100644
--- a/lisp/calendar/cal-hebrew.el
+++ b/lisp/calendar/cal-hebrew.el
@@ -238,7 +238,7 @@ Reads a year, month, and day."
          (month (cdr (assoc-string
                       (completing-read
                        "Hebrew calendar month name: "
-                       (mapcar 'list (append month-array nil))
+                       (append month-array nil)
                        (if (= year 3761)
                            (lambda (x)
                              (let ((m (cdr
@@ -691,7 +691,7 @@ from the cursor position."
                     (month (cdr (assoc-string
                                  (completing-read
                                   "Month of death (name): "
-                                  (mapcar 'list (append month-array nil))
+                                  (append month-array nil)
                                   nil t)
                                  (calendar-make-alist month-array 1) t)))
                     (last (calendar-last-day-of-month month year))
@@ -1123,6 +1123,7 @@ use when highlighting the day in the calendar."
 
 (declare-function solar-setup "solar" ())
 (declare-function solar-sunrise-sunset "solar" (date))
+(declare-function solar-time-string "solar" (time time-zone))
 (defvar calendar-latitude)
 (defvar calendar-longitude)
 (defvar calendar-time-zone)
@@ -1145,7 +1146,7 @@ use when highlighting the day in the calendar."
         (if sunset
             (cons mark (format
                         "%s Sabbath candle lighting"
-                        (apply 'solar-time-string
+                        (apply #'solar-time-string
                                (cons (- (car sunset)
                                         (/ diary-hebrew-sabbath-candles-minutes
                                            60.0))
diff --git a/lisp/calendar/cal-html.el b/lisp/calendar/cal-html.el
index 06729743243..6e5e42e8f7f 100644
--- a/lisp/calendar/cal-html.el
+++ b/lisp/calendar/cal-html.el
@@ -42,18 +42,15 @@
 
 (defcustom cal-html-directory "~/public_html"
   "Directory for HTML pages generated by cal-html."
-  :type 'string
-  :group 'calendar-html)
+  :type 'string)
 
 (defcustom cal-html-print-day-number-flag nil
   "Non-nil means print the day-of-the-year number in the monthly cal-html page."
-  :type 'boolean
-  :group 'calendar-html)
+  :type 'boolean)
 
 (defcustom cal-html-year-index-cols 3
   "Number of columns in the cal-html yearly index page."
-  :type 'integer
-  :group 'calendar-html)
+  :type 'integer)
 
 (defcustom cal-html-day-abbrev-array calendar-day-abbrev-array
   "Array of seven strings for abbreviated day names (starting with Sunday)."
@@ -64,14 +61,12 @@
                  (string :tag "Wed")
                  (string :tag "Thu")
                  (string :tag "Fri")
-                 (string :tag "Sat"))
-  :group 'calendar-html)
+                 (string :tag "Sat")))
 
 (defcustom cal-html-holidays t
   "If non-nil, include holidays as well as diary entries."
   :version "24.3"
-  :type 'boolean
-  :group 'calendar-html)
+  :type 'boolean)
 
 (defcustom cal-html-css-default
   (concat
@@ -93,8 +88,7 @@
    "</STYLE>\n\n")
   "Default cal-html css style.  You can override this with a \"cal.css\" file."
   :type 'string
-  :version "24.3"                       ; added SPAN.HOLIDAY
-  :group 'calendar-html)
+  :version "24.3")                      ; Added SPAN.HOLIDAY.
 
 ;;; End customizable variables.
 
@@ -317,7 +311,7 @@ There are 12/cols rows of COLS months each."
 Characters are replaced according to `cal-html-html-subst-list'."
   (if (stringp string)
       (replace-regexp-in-string
-       (regexp-opt (mapcar 'car cal-html-html-subst-list))
+       (regexp-opt (mapcar #'car cal-html-html-subst-list))
        (lambda (x)
          (cdr (assoc x cal-html-html-subst-list)))
        string)
diff --git a/lisp/calendar/cal-islam.el b/lisp/calendar/cal-islam.el
index 79cbad2c61a..49da71adac4 100644
--- a/lisp/calendar/cal-islam.el
+++ b/lisp/calendar/cal-islam.el
@@ -154,7 +154,7 @@ Reads a year, month, and day."
          (month (cdr (assoc-string
                       (completing-read
                        "Islamic calendar month name: "
-                       (mapcar 'list (append month-array nil))
+                       (append month-array nil)
                        nil t)
                       (calendar-make-alist month-array 1) t)))
          (last (calendar-islamic-last-day-of-month month year))
diff --git a/lisp/calendar/cal-julian.el b/lisp/calendar/cal-julian.el
index 0977b14b2e6..7597f36b62f 100644
--- a/lisp/calendar/cal-julian.el
+++ b/lisp/calendar/cal-julian.el
@@ -107,7 +107,7 @@ Driven by the variable `calendar-date-display-form'."
           (month (cdr (assoc-string
                        (completing-read
                         "Julian calendar month name: "
-                        (mapcar 'list (append month-array nil))
+                        (append month-array nil)
                         nil t)
                        (calendar-make-alist month-array 1) t)))
           (last
diff --git a/lisp/calendar/cal-mayan.el b/lisp/calendar/cal-mayan.el
index df4ebe873f9..886e92a859d 100644
--- a/lisp/calendar/cal-mayan.el
+++ b/lisp/calendar/cal-mayan.el
@@ -70,7 +70,7 @@ but some use 1137140.  Using 1232041 gives you Spinden's correlation; using
 
 (defun calendar-mayan-long-count-to-string (mayan-long-count)
   "Convert MAYAN-LONG-COUNT into traditional written form."
-  (apply 'format (cons "%s.%s.%s.%s.%s" mayan-long-count)))
+  (apply #'format (cons "%s.%s.%s.%s.%s" mayan-long-count)))
 
 (defun calendar-mayan-string-from-long-count (str)
   "Given STR, a string of format \"%d.%d.%d.%d.%d\", return list of numbers."
@@ -144,7 +144,7 @@ but some use 1137140.  Using 1232041 gives you Spinden's correlation; using
          (haab-month (cdr
                       (assoc-string
                        (completing-read "Haab uinal: "
-                                        (mapcar 'list haab-month-list)
+                                        haab-month-list
                                         nil t)
                        (calendar-make-alist haab-month-list 1) t))))
     (cons haab-day haab-month)))
@@ -160,7 +160,7 @@ but some use 1137140.  Using 1232041 gives you Spinden's correlation; using
          (tzolkin-name (cdr
                         (assoc-string
                          (completing-read "Tzolkin uinal: "
-                                          (mapcar 'list tzolkin-name-list)
+                                          tzolkin-name-list
                                           nil t)
                          (calendar-make-alist tzolkin-name-list 1) t))))
     (cons tzolkin-count tzolkin-name)))
diff --git a/lisp/calendar/cal-menu.el b/lisp/calendar/cal-menu.el
index 68c6abdd8d8..a95c1c882b4 100644
--- a/lisp/calendar/cal-menu.el
+++ b/lisp/calendar/cal-menu.el
@@ -206,7 +206,7 @@ is non-nil."
                       (if holidays
                           (list "--shadow-etched-in" "--shadow-etched-in"))
                       (if diary-entries
-                          (mapcar 'list (apply 'append diary-entries))
+                          (mapcar #'list (apply #'append diary-entries))
                         '("None")))))
     (and selection (call-interactively selection))))
 
diff --git a/lisp/calendar/cal-move.el b/lisp/calendar/cal-move.el
index c96ae182118..f1137dfda5c 100644
--- a/lisp/calendar/cal-move.el
+++ b/lisp/calendar/cal-move.el
@@ -430,11 +430,7 @@ Interactively, prompt for YEAR and DAY number."
                 (calendar-day-number (calendar-current-date))
                 last)))
      (list year day)))
-  (calendar-goto-date
-   (calendar-gregorian-from-absolute
-    (if (< 0 day)
-        (+ -1 day (calendar-absolute-from-gregorian (list 1 1 year)))
-      (+ 1 day (calendar-absolute-from-gregorian (list 12 31 year))))))
+  (calendar-goto-date (calendar-date-from-day-of-year year day))
   (or noecho (calendar-print-day-of-year)))
 
 (provide 'cal-move)
diff --git a/lisp/calendar/cal-persia.el b/lisp/calendar/cal-persia.el
index 9f59a75f952..df0a11160fb 100644
--- a/lisp/calendar/cal-persia.el
+++ b/lisp/calendar/cal-persia.el
@@ -169,8 +169,7 @@ Reads a year, month, and day."
          (month (cdr (assoc
                       (completing-read
                        "Persian calendar month name: "
-                       (mapcar 'list
-                               (append calendar-persian-month-name-array nil))
+                       (append calendar-persian-month-name-array nil)
                        nil t)
                       (calendar-make-alist calendar-persian-month-name-array
                                            1))))
diff --git a/lisp/calendar/cal-tex.el b/lisp/calendar/cal-tex.el
index bf0ff100be3..166aa4658e2 100644
--- a/lisp/calendar/cal-tex.el
+++ b/lisp/calendar/cal-tex.el
@@ -72,26 +72,22 @@
   "The days of the week that are displayed on the portrait monthly calendar.
 Sunday is 0, Monday is 1, and so on.  The default is to print from Sunday to
 Saturday.  For example, (1 3 5) prints only Monday, Wednesday, Friday."
-  :type '(repeat integer)
-  :group 'calendar-tex)
+  :type '(repeat integer))
 
 (defcustom cal-tex-holidays t
   "Non-nil means holidays are printed in the LaTeX calendars that support it.
 Setting this to nil may speed up calendar generation."
-  :type 'boolean
-  :group 'calendar-tex)
+  :type 'boolean)
 
 (defcustom cal-tex-diary nil
   "Non-nil means diary entries are printed in LaTeX calendars that support it.
 Setting this to nil may speed up calendar generation."
-  :type 'boolean
-  :group 'calendar-tex)
+  :type 'boolean)
 
 (defcustom cal-tex-rules nil
   "Non-nil means pages will be ruled in some LaTeX calendar styles.
 At present, this only affects the daily filofax calendar."
-  :type 'boolean
-  :group 'calendar-tex)
+  :type 'boolean)
 
 (defcustom cal-tex-daily-string
   '(let* ((year (calendar-extract-year date))
@@ -112,30 +108,25 @@ days remaining.  As an example, setting this to
     (calendar-hebrew-date-string date)
 
 will put the Hebrew date at the bottom of each day."
-  :type 'sexp
-  :group 'calendar-tex)
+  :type 'sexp)
 
 (defcustom cal-tex-buffer "calendar.tex"
   "The name for the output LaTeX calendar buffer."
-  :type 'string
-  :group 'calendar-tex)
+  :type 'string)
 
 (defcustom cal-tex-24 nil
   "Non-nil means use a 24 hour clock in the daily calendar."
-  :type 'boolean
-  :group 'calendar-tex)
+  :type 'boolean)
 
 (defcustom cal-tex-daily-start 8
   "The first hour of the daily LaTeX calendar page.
 At present, this only affects `cal-tex-cursor-day'."
-  :type 'integer
-  :group 'calendar-tex)
+  :type 'integer)
 
 (defcustom cal-tex-daily-end 20
   "The last hour of the daily LaTeX calendar page.
 At present, this only affects `cal-tex-cursor-day'."
-  :type 'integer
-  :group 'calendar-tex)
+  :type 'integer)
 
 (defcustom cal-tex-preamble-extra nil
   "A string giving extra LaTeX commands to insert in the calendar preamble.
@@ -144,7 +135,6 @@ For example, to include extra packages:
   :type '(choice (const nil)
                  ;; An example to help people format things in custom.
                  (string :value "\\usepackage{foo}\n\\usepackage{bar}\n"))
-  :group 'calendar-tex
   :version "22.1")
 
 (defcustom cal-tex-hook nil
@@ -153,28 +143,23 @@ You can use this to do post-processing on the buffer.  For example, to change
 characters with diacritical marks to their LaTeX equivalents, use
     (add-hook \\='cal-tex-hook
               (lambda () (iso-iso2tex (point-min) (point-max))))"
-  :type 'hook
-  :group 'calendar-tex)
+  :type 'hook)
 
 (defcustom cal-tex-year-hook nil
   "List of functions called after a LaTeX year calendar buffer is generated."
-  :type 'hook
-  :group 'calendar-tex)
+  :type 'hook)
 
 (defcustom cal-tex-month-hook nil
   "List of functions called after a LaTeX month calendar buffer is generated."
-  :type 'hook
-  :group 'calendar-tex)
+  :type 'hook)
 
 (defcustom cal-tex-week-hook nil
   "List of functions called after a LaTeX week calendar buffer is generated."
-  :type 'hook
-  :group 'calendar-tex)
+  :type 'hook)
 
 (defcustom cal-tex-daily-hook nil
   "List of functions called after a LaTeX daily calendar buffer is generated."
-  :type 'hook
-  :group 'calendar-tex)
+  :type 'hook)
 
 ;;;
 ;;; Definitions for LaTeX code
@@ -1227,7 +1212,7 @@ shown are hard-coded to 8-12, 13-17."
         (cal-tex-arg (number-to-string (calendar-extract-day date)))
         (cal-tex-arg (cal-tex-latexify-list diary-list date))
         (cal-tex-arg (cal-tex-latexify-list holidays date))
-        (cal-tex-arg (eval cal-tex-daily-string))
+        (cal-tex-arg (eval cal-tex-daily-string t))
         (insert "%\n")
         (setq date (cal-tex-incr-date date)))
       (dotimes (_jdummy 2)
@@ -1236,7 +1221,7 @@ shown are hard-coded to 8-12, 13-17."
         (cal-tex-arg (number-to-string (calendar-extract-day date)))
         (cal-tex-arg (cal-tex-latexify-list diary-list date))
         (cal-tex-arg (cal-tex-latexify-list holidays date))
-        (cal-tex-arg (eval cal-tex-daily-string))
+        (cal-tex-arg (eval cal-tex-daily-string t))
         (insert "%\n")
         (setq date (cal-tex-incr-date date)))
       (unless (= i (1- n))
diff --git a/lisp/calendar/calendar.el b/lisp/calendar/calendar.el
index 42fc210c1e1..2e90d6e4639 100644
--- a/lisp/calendar/calendar.el
+++ b/lisp/calendar/calendar.el
@@ -871,7 +871,15 @@ current word of the diary entry, so in no case can the pattern match more than
 a portion of the first word of the diary entry.
 
 For examples of three common styles, see `diary-american-date-forms',
-`diary-european-date-forms', and `diary-iso-date-forms'."
+`diary-european-date-forms', and `diary-iso-date-forms'.
+
+If you customize this variable, you should also customize the variable
+`diary-date-insertion-form' to contain a pseudo-pattern which produces
+dates that match one of the forms in this variable. (If
+`diary-date-insertion-form' does not correspond to one of the patterns
+in this variable, then the diary will not recognize such dates,
+including those inserted into the diary from the calendar with
+`diary-insert-entry'.)"
   :type '(repeat (choice (cons :tag "Backup"
                                :value (backup . nil)
                                (const backup)
@@ -895,6 +903,50 @@ For examples of three common styles, see `diary-american-date-forms',
                 (diary))))
   :group 'diary)
 
+(defconst diary-american-date-insertion-form '(month "/" day "/" year)
+  "Pseudo-pattern for American dates in `diary-date-insertion-form'")
+
+(defconst diary-european-date-insertion-form '(day "/" month "/" year)
+  "Pseudo-pattern for European dates in `diary-date-insertion-form'")
+
+(defconst diary-iso-date-insertion-form '(year "/" month "/" day)
+  "Pseudo-pattern for ISO dates in `diary-date-insertion-form'")
+
+(defcustom diary-date-insertion-form
+  (cond ((eq calendar-date-style 'iso) diary-iso-date-insertion-form)
+        ((eq calendar-date-style 'european) diary-european-date-insertion-form)
+        (t diary-american-date-insertion-form))
+  "Pseudo-pattern describing how to format a date for a new diary entry.
+
+A pseudo-pattern is a list of expressions that can include the symbols
+`month', `day', and `year' (all numbers in string form), and `monthname'
+and `dayname' (both alphabetic strings).  For example, a typical American
+form would be
+
+       (month \"/\" day \"/\" (substring year -2))
+
+whereas
+
+       ((format \"%9s, %9s %2s, %4s\" dayname monthname day year))
+
+would give the usual American style in fixed-length fields.
+
+This pattern will be used by `calendar-date-string' (which see) to
+format dates when inserting them with `diary-insert-entry', or when
+importing them from other formats into the diary.
+
+If you customize this variable, you should also customize the variable
+`diary-date-forms' to include a pseudo-pattern which matches dates
+produced by this pattern.  (If there is no corresponding pattern in
+`diary-date-forms', then the diary will not recognize such dates,
+including those inserted into the diary from the calendar with
+`diary-insert-entry'.)"
+  :version "31.1"
+  :type 'sexp
+  :risky t
+  :set-after '(calendar-date-style)
+  :group 'diary)
+
 ;; Next three are provided to aid in setting calendar-date-display-form.
 (defcustom calendar-iso-date-display-form '((format "%s-%.2d-%.2d" year
                                                (string-to-number month)
@@ -1028,7 +1080,9 @@ The valid styles are described in the documentation of `calendar-date-style'."
         calendar-month-header
         (symbol-value (intern-soft (format "calendar-%s-month-header" style)))
         diary-date-forms
-        (symbol-value (intern-soft (format "diary-%s-date-forms" style))))
+        (symbol-value (intern-soft (format "diary-%s-date-forms" style)))
+        diary-date-insertion-form
+        (symbol-value (intern-soft (format "diary-%s-date-insertion-form" style))))
   (calendar-redraw))
 
 (defcustom diary-show-holidays-flag t
@@ -1297,6 +1351,16 @@ return negative results."
               (/ offset-years 400)
               (calendar-day-number '(12 31 -1))))))) ; days in year 1 BC
 
+;; This function is the inverse of `calendar-day-number':
+(defun calendar-date-from-day-of-year (year dayno)
+  "Return the date of the DAYNO-th day in YEAR.
+DAYNO must be an integer between -366 and 366."
+  (calendar-gregorian-from-absolute
+   (+ (if (< dayno 0)
+          (+ 1 dayno (if (calendar-leap-year-p year) 366 365))
+        dayno)
+      (calendar-absolute-from-gregorian (list 12 31 (1- year))))))
+
 ;;;###autoload
 (defun calendar (&optional arg)
   "Display a three-month Gregorian calendar.
@@ -1598,143 +1662,143 @@ Otherwise, use the selected window of EVENT's frame."
                  mark-defun mark-whole-buffer mark-page
                  downcase-region upcase-region kill-region
                  copy-region-as-kill capitalize-region write-region))
-      (define-key map (vector 'remap c) 'calendar-not-implemented))
-    (define-key map "<"     'calendar-scroll-right)
-    (define-key map "\C-x<" 'calendar-scroll-right)
-    (define-key map [S-wheel-up] 'calendar-scroll-right)
-    (define-key map [prior] 'calendar-scroll-right-three-months)
-    (define-key map "\ev"   'calendar-scroll-right-three-months)
-    (define-key map [wheel-up] 'calendar-scroll-right-three-months)
-    (define-key map [M-wheel-up] 'calendar-backward-year)
-    (define-key map ">"     'calendar-scroll-left)
-    (define-key map "\C-x>" 'calendar-scroll-left)
-    (define-key map [S-wheel-down] 'calendar-scroll-left)
-    (define-key map [next]  'calendar-scroll-left-three-months)
-    (define-key map "\C-v"  'calendar-scroll-left-three-months)
-    (define-key map [wheel-down] 'calendar-scroll-left-three-months)
-    (define-key map [M-wheel-down] 'calendar-forward-year)
-    (define-key map "\C-l"  'calendar-recenter)
-    (define-key map "\C-b"  'calendar-backward-day)
-    (define-key map "\C-p"  'calendar-backward-week)
-    (define-key map "\e{"   'calendar-backward-month)
-    (define-key map "{"   'calendar-backward-month)
-    (define-key map "\C-x[" 'calendar-backward-year)
-    (define-key map "[" 'calendar-backward-year)
-    (define-key map "\C-f"  'calendar-forward-day)
-    (define-key map "\C-n"  'calendar-forward-week)
-    (define-key map [left]  'calendar-backward-day)
-    (define-key map [up]    'calendar-backward-week)
-    (define-key map [right] 'calendar-forward-day)
-    (define-key map [down]  'calendar-forward-week)
-    (define-key map "\e}"   'calendar-forward-month)
-    (define-key map "}"   'calendar-forward-month)
-    (define-key map "\C-x]" 'calendar-forward-year)
-    (define-key map "]" 'calendar-forward-year)
-    (define-key map "\C-a"  'calendar-beginning-of-week)
-    (define-key map "\C-e"  'calendar-end-of-week)
-    (define-key map "\ea"   'calendar-beginning-of-month)
-    (define-key map "\ee"   'calendar-end-of-month)
-    (define-key map "\e<"   'calendar-beginning-of-year)
-    (define-key map "\e>"   'calendar-end-of-year)
-    (define-key map "\C-@"  'calendar-set-mark)
+      (define-key map (vector 'remap c) #'calendar-not-implemented))
+    (define-key map "<"     #'calendar-scroll-right)
+    (define-key map "\C-x<" #'calendar-scroll-right)
+    (define-key map [S-wheel-up] #'calendar-scroll-right)
+    (define-key map [prior] #'calendar-scroll-right-three-months)
+    (define-key map "\ev"   #'calendar-scroll-right-three-months)
+    (define-key map [wheel-up] #'calendar-scroll-right-three-months)
+    (define-key map [M-wheel-up] #'calendar-backward-year)
+    (define-key map ">"     #'calendar-scroll-left)
+    (define-key map "\C-x>" #'calendar-scroll-left)
+    (define-key map [S-wheel-down] #'calendar-scroll-left)
+    (define-key map [next]  #'calendar-scroll-left-three-months)
+    (define-key map "\C-v"  #'calendar-scroll-left-three-months)
+    (define-key map [wheel-down] #'calendar-scroll-left-three-months)
+    (define-key map [M-wheel-down] #'calendar-forward-year)
+    (define-key map "\C-l"  #'calendar-recenter)
+    (define-key map "\C-b"  #'calendar-backward-day)
+    (define-key map "\C-p"  #'calendar-backward-week)
+    (define-key map "\e{"   #'calendar-backward-month)
+    (define-key map "{"   #'calendar-backward-month)
+    (define-key map "\C-x[" #'calendar-backward-year)
+    (define-key map "[" #'calendar-backward-year)
+    (define-key map "\C-f"  #'calendar-forward-day)
+    (define-key map "\C-n"  #'calendar-forward-week)
+    (define-key map [left]  #'calendar-backward-day)
+    (define-key map [up]    #'calendar-backward-week)
+    (define-key map [right] #'calendar-forward-day)
+    (define-key map [down]  #'calendar-forward-week)
+    (define-key map "\e}"   #'calendar-forward-month)
+    (define-key map "}"   #'calendar-forward-month)
+    (define-key map "\C-x]" #'calendar-forward-year)
+    (define-key map "]" #'calendar-forward-year)
+    (define-key map "\C-a"  #'calendar-beginning-of-week)
+    (define-key map "\C-e"  #'calendar-end-of-week)
+    (define-key map "\ea"   #'calendar-beginning-of-month)
+    (define-key map "\ee"   #'calendar-end-of-month)
+    (define-key map "\e<"   #'calendar-beginning-of-year)
+    (define-key map "\e>"   #'calendar-end-of-year)
+    (define-key map "\C-@"  #'calendar-set-mark)
     ;; Many people are used to typing C-SPC and getting C-@.
-    (define-key map [?\C-\s] 'calendar-set-mark)
-    (define-key map "\C-x\C-x" 'calendar-exchange-point-and-mark)
-    (define-key map "\e=" 'calendar-count-days-region)
-    (define-key map "gd"  'calendar-goto-date)
-    (define-key map "gD"  'calendar-goto-day-of-year)
-    (define-key map "gj"  'calendar-julian-goto-date)
-    (define-key map "ga"  'calendar-astro-goto-day-number)
-    (define-key map "gh"  'calendar-hebrew-goto-date)
-    (define-key map "gi"  'calendar-islamic-goto-date)
-    (define-key map "gb"  'calendar-bahai-goto-date)
-    (define-key map "gC"  'calendar-chinese-goto-date)
-    (define-key map "gk"  'calendar-coptic-goto-date)
-    (define-key map "ge"  'calendar-ethiopic-goto-date)
-    (define-key map "gp"  'calendar-persian-goto-date)
-    (define-key map "gc"  'calendar-iso-goto-date)
-    (define-key map "gw"  'calendar-iso-goto-week)
-    (define-key map "gf"  'calendar-french-goto-date)
-    (define-key map "gml"  'calendar-mayan-goto-long-count-date)
-    (define-key map "gmpc" 'calendar-mayan-previous-round-date)
-    (define-key map "gmnc" 'calendar-mayan-next-round-date)
-    (define-key map "gmph" 'calendar-mayan-previous-haab-date)
-    (define-key map "gmnh" 'calendar-mayan-next-haab-date)
-    (define-key map "gmpt" 'calendar-mayan-previous-tzolkin-date)
-    (define-key map "gmnt" 'calendar-mayan-next-tzolkin-date)
-    (define-key map "Aa"   'appt-add)
+    (define-key map [?\C-\s] #'calendar-set-mark)
+    (define-key map "\C-x\C-x" #'calendar-exchange-point-and-mark)
+    (define-key map "\e=" #'calendar-count-days-region)
+    (define-key map "gd"  #'calendar-goto-date)
+    (define-key map "gD"  #'calendar-goto-day-of-year)
+    (define-key map "gj"  #'calendar-julian-goto-date)
+    (define-key map "ga"  #'calendar-astro-goto-day-number)
+    (define-key map "gh"  #'calendar-hebrew-goto-date)
+    (define-key map "gi"  #'calendar-islamic-goto-date)
+    (define-key map "gb"  #'calendar-bahai-goto-date)
+    (define-key map "gC"  #'calendar-chinese-goto-date)
+    (define-key map "gk"  #'calendar-coptic-goto-date)
+    (define-key map "ge"  #'calendar-ethiopic-goto-date)
+    (define-key map "gp"  #'calendar-persian-goto-date)
+    (define-key map "gc"  #'calendar-iso-goto-date)
+    (define-key map "gw"  #'calendar-iso-goto-week)
+    (define-key map "gf"  #'calendar-french-goto-date)
+    (define-key map "gml"  #'calendar-mayan-goto-long-count-date)
+    (define-key map "gmpc" #'calendar-mayan-previous-round-date)
+    (define-key map "gmnc" #'calendar-mayan-next-round-date)
+    (define-key map "gmph" #'calendar-mayan-previous-haab-date)
+    (define-key map "gmnh" #'calendar-mayan-next-haab-date)
+    (define-key map "gmpt" #'calendar-mayan-previous-tzolkin-date)
+    (define-key map "gmnt" #'calendar-mayan-next-tzolkin-date)
+    (define-key map "Aa"   #'appt-add)
     (define-key map "Ad"   'appt-delete)
-    (define-key map "S"   'calendar-sunrise-sunset)
-    (define-key map "M"   'calendar-lunar-phases)
-    (define-key map " "   'scroll-other-window)
-    (define-key map [?\S-\ ] 'scroll-other-window-down)
-    (define-key map "\d"  'scroll-other-window-down)
-    (define-key map "\C-c\C-l" 'calendar-redraw)
-    (define-key map "."   'calendar-goto-today)
-    (define-key map "o"   'calendar-other-month)
-    (define-key map "q"   'calendar-exit)
-    (define-key map "a"   'calendar-list-holidays)
-    (define-key map "h"   'calendar-cursor-holidays)
-    (define-key map "x"   'calendar-mark-holidays)
-    (define-key map "u"   'calendar-unmark)
-    (define-key map "m"   'diary-mark-entries)
-    (define-key map "d"   'diary-view-entries)
-    (define-key map "D"   'diary-view-other-diary-entries)
-    (define-key map "s"   'diary-show-all-entries)
-    (define-key map "pd"  'calendar-print-day-of-year)
-    (define-key map "pC"  'calendar-chinese-print-date)
-    (define-key map "pk"  'calendar-coptic-print-date)
-    (define-key map "pe"  'calendar-ethiopic-print-date)
-    (define-key map "pp"  'calendar-persian-print-date)
-    (define-key map "pc"  'calendar-iso-print-date)
-    (define-key map "pj"  'calendar-julian-print-date)
-    (define-key map "pa"  'calendar-astro-print-day-number)
-    (define-key map "ph"  'calendar-hebrew-print-date)
-    (define-key map "pi"  'calendar-islamic-print-date)
-    (define-key map "pb"  'calendar-bahai-print-date)
-    (define-key map "pf"  'calendar-french-print-date)
-    (define-key map "pm"  'calendar-mayan-print-date)
-    (define-key map "po"  'calendar-print-other-dates)
-    (define-key map "id"  'diary-insert-entry)
-    (define-key map "iw"  'diary-insert-weekly-entry)
-    (define-key map "im"  'diary-insert-monthly-entry)
-    (define-key map "iy"  'diary-insert-yearly-entry)
-    (define-key map "ia"  'diary-insert-anniversary-entry)
-    (define-key map "ib"  'diary-insert-block-entry)
-    (define-key map "ic"  'diary-insert-cyclic-entry)
-    (define-key map "ihd" 'diary-hebrew-insert-entry)
-    (define-key map "ihm" 'diary-hebrew-insert-monthly-entry)
-    (define-key map "ihy" 'diary-hebrew-insert-yearly-entry)
-    (define-key map "iid" 'diary-islamic-insert-entry)
-    (define-key map "iim" 'diary-islamic-insert-monthly-entry)
-    (define-key map "iiy" 'diary-islamic-insert-yearly-entry)
-    (define-key map "iBd" 'diary-bahai-insert-entry)
-    (define-key map "iBm" 'diary-bahai-insert-monthly-entry)
-    (define-key map "iBy" 'diary-bahai-insert-yearly-entry)
-    (define-key map "iCd" 'diary-chinese-insert-entry)
-    (define-key map "iCm" 'diary-chinese-insert-monthly-entry)
-    (define-key map "iCy" 'diary-chinese-insert-yearly-entry)
-    (define-key map "iCa" 'diary-chinese-insert-anniversary-entry)
-    (define-key map "?"   'calendar-goto-info-node)
-    (define-key map "Hm" 'cal-html-cursor-month)
-    (define-key map "Hy" 'cal-html-cursor-year)
-    (define-key map "tm" 'cal-tex-cursor-month)
-    (define-key map "tM" 'cal-tex-cursor-month-landscape)
-    (define-key map "td" 'cal-tex-cursor-day)
-    (define-key map "tw1" 'cal-tex-cursor-week)
-    (define-key map "tw2" 'cal-tex-cursor-week2)
-    (define-key map "tw3" 'cal-tex-cursor-week-iso) ; FIXME twi ?
-    (define-key map "tw4" 'cal-tex-cursor-week-monday) ; twm ?
-    (define-key map "twW" 'cal-tex-cursor-week2-summary)
-    (define-key map "tfd" 'cal-tex-cursor-filofax-daily)
-    (define-key map "tfw" 'cal-tex-cursor-filofax-2week)
-    (define-key map "tfW" 'cal-tex-cursor-filofax-week)
-    (define-key map "tfy" 'cal-tex-cursor-filofax-year)
-    (define-key map "ty" 'cal-tex-cursor-year)
-    (define-key map "tY" 'cal-tex-cursor-year-landscape)
-
-    (define-key map [menu-bar edit] 'undefined)
-    (define-key map [menu-bar search] 'undefined)
+    (define-key map "S"   #'calendar-sunrise-sunset)
+    (define-key map "M"   #'calendar-lunar-phases)
+    (define-key map " "   #'scroll-other-window)
+    (define-key map [?\S-\ ] #'scroll-other-window-down)
+    (define-key map "\d"  #'scroll-other-window-down)
+    (define-key map "\C-c\C-l" #'calendar-redraw)
+    (define-key map "."   #'calendar-goto-today)
+    (define-key map "o"   #'calendar-other-month)
+    (define-key map "q"   #'calendar-exit)
+    (define-key map "a"   #'calendar-list-holidays)
+    (define-key map "h"   #'calendar-cursor-holidays)
+    (define-key map "x"   #'calendar-mark-holidays)
+    (define-key map "u"   #'calendar-unmark)
+    (define-key map "m"   #'diary-mark-entries)
+    (define-key map "d"   #'diary-view-entries)
+    (define-key map "D"   #'diary-view-other-diary-entries)
+    (define-key map "s"   #'diary-show-all-entries)
+    (define-key map "pd"  #'calendar-print-day-of-year)
+    (define-key map "pC"  #'calendar-chinese-print-date)
+    (define-key map "pk"  #'calendar-coptic-print-date)
+    (define-key map "pe"  #'calendar-ethiopic-print-date)
+    (define-key map "pp"  #'calendar-persian-print-date)
+    (define-key map "pc"  #'calendar-iso-print-date)
+    (define-key map "pj"  #'calendar-julian-print-date)
+    (define-key map "pa"  #'calendar-astro-print-day-number)
+    (define-key map "ph"  #'calendar-hebrew-print-date)
+    (define-key map "pi"  #'calendar-islamic-print-date)
+    (define-key map "pb"  #'calendar-bahai-print-date)
+    (define-key map "pf"  #'calendar-french-print-date)
+    (define-key map "pm"  #'calendar-mayan-print-date)
+    (define-key map "po"  #'calendar-print-other-dates)
+    (define-key map "id"  #'diary-insert-entry)
+    (define-key map "iw"  #'diary-insert-weekly-entry)
+    (define-key map "im"  #'diary-insert-monthly-entry)
+    (define-key map "iy"  #'diary-insert-yearly-entry)
+    (define-key map "ia"  #'diary-insert-anniversary-entry)
+    (define-key map "ib"  #'diary-insert-block-entry)
+    (define-key map "ic"  #'diary-insert-cyclic-entry)
+    (define-key map "ihd" #'diary-hebrew-insert-entry)
+    (define-key map "ihm" #'diary-hebrew-insert-monthly-entry)
+    (define-key map "ihy" #'diary-hebrew-insert-yearly-entry)
+    (define-key map "iid" #'diary-islamic-insert-entry)
+    (define-key map "iim" #'diary-islamic-insert-monthly-entry)
+    (define-key map "iiy" #'diary-islamic-insert-yearly-entry)
+    (define-key map "iBd" #'diary-bahai-insert-entry)
+    (define-key map "iBm" #'diary-bahai-insert-monthly-entry)
+    (define-key map "iBy" #'diary-bahai-insert-yearly-entry)
+    (define-key map "iCd" #'diary-chinese-insert-entry)
+    (define-key map "iCm" #'diary-chinese-insert-monthly-entry)
+    (define-key map "iCy" #'diary-chinese-insert-yearly-entry)
+    (define-key map "iCa" #'diary-chinese-insert-anniversary-entry)
+    (define-key map "?"   #'calendar-goto-info-node)
+    (define-key map "Hm" #'cal-html-cursor-month)
+    (define-key map "Hy" #'cal-html-cursor-year)
+    (define-key map "tm" #'cal-tex-cursor-month)
+    (define-key map "tM" #'cal-tex-cursor-month-landscape)
+    (define-key map "td" #'cal-tex-cursor-day)
+    (define-key map "tw1" #'cal-tex-cursor-week)
+    (define-key map "tw2" #'cal-tex-cursor-week2)
+    (define-key map "tw3" #'cal-tex-cursor-week-iso) ; FIXME twi ?
+    (define-key map "tw4" #'cal-tex-cursor-week-monday) ; twm ?
+    (define-key map "twW" #'cal-tex-cursor-week2-summary)
+    (define-key map "tfd" #'cal-tex-cursor-filofax-daily)
+    (define-key map "tfw" #'cal-tex-cursor-filofax-2week)
+    (define-key map "tfW" #'cal-tex-cursor-filofax-week)
+    (define-key map "tfy" #'cal-tex-cursor-filofax-year)
+    (define-key map "ty" #'cal-tex-cursor-year)
+    (define-key map "tY" #'cal-tex-cursor-year-landscape)
+
+    (define-key map [menu-bar edit] #'undefined)
+    (define-key map [menu-bar search] #'undefined)
 
     (easy-menu-define nil map nil cal-menu-sunmoon-menu)
     (easy-menu-define nil map nil cal-menu-diary-menu)
diff --git a/lisp/calendar/diary-icalendar.el b/lisp/calendar/diary-icalendar.el
new file mode 100644
index 00000000000..ed8706c50a7
--- /dev/null
+++ b/lisp/calendar/diary-icalendar.el
@@ -0,0 +1,3730 @@
+;;; diary-icalendar.el --- Display iCalendar data in diary  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2025-2026  Free Software Foundation, Inc.
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: January 2025
+;; Keywords: calendar
+;; Human-Keywords: diary, calendar, iCalendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file is a replacement for icalendar.el that uses a new parser
+;; and offers more features.
+
+;;; Code:
+
+(eval-when-compile (require 'cl-lib))
+(eval-when-compile (require 'icalendar-macs))
+(require 'icalendar)
+(require 'icalendar-parser)
+(require 'icalendar-utils)
+(require 'icalendar-recur)
+(require 'icalendar-ast)
+(require 'calendar)
+(require 'cal-dst)
+(require 'diary-lib)
+(require 'skeleton)
+(require 'seq)
+(require 'rx)
+(require 'pp)
+
+;; Customization
+(defgroup diary-icalendar nil
+  "iCalendar import, export, and display in diary."
+  :version "31.1"
+  :group 'diary
+  :prefix 'diary-icalendar)
+
+;;; Import customizations
+(defgroup diary-icalendar-import nil
+  "iCalendar import into diary."
+  :version "31.1"
+  :group 'diary-icalendar
+  :prefix 'diary-icalendar)
+
+(defcustom di:always-import-quietly nil
+  "When non-nil, diary will never ask for confirmations when importing events.
+
+`diary-icalendar-import-file' and `diary-icalendar-import-buffer' both
+accept an optional argument, QUIETLY, which determines whether these
+functions ask for confirmation when importing individual events and
+saving the diary file.  If you set this variable to t, you will never be
+asked to confirm."
+  :version "31.1"
+  :type '(choice (const :tag "Ask for confirmations" nil)
+                 (const :tag "Never ask for confirmations" t)))
+
+(defcustom di:after-mailcap-viewer-hook nil
+  "Hook run after `diary-icalendar-mailcap-viewer'.
+
+The functions in this hook will be run in a temporary buffer after
+formatting the contents of iCalendar data as diary entries in that
+buffer.  You can add functions to this hook if you want, for example, to
+copy these entries somewhere else."
+  :version "31.1"
+  :type '(hook))
+
+(defcustom di:attachment-directory nil
+  "Directory in which to save iCalendar attachments when importing.
+
+If the value is nil, binary attachments encoded in an ATTACH property
+are never saved.  If it is the name of a directory, attachments will be
+saved in per-component subdirectories of this directory, with each
+subdirectory named by the component's UID value."
+  :version "31.1"
+  :type '(choice
+          (const :tag "Do not save attachments" nil)
+          directory))
+
+(defcustom di:time-format "%H:%M"
+  "Format string to use for event times.
+
+The value must be a valid format string for `format-time-string'; see
+its docstring for more information.  The value only needs to format clock
+times, and should format them in a way that will be recognized by
+`diary-time-regexp'.  (Date information is formatted separately at the
+start of the imported entry.)  Examples:
+
+  \"%H:%M\" - 24-hour, 0-padded: 09:00 or 21:00
+  \"%k.%Mh\" - 24-hour, blank-padded: 9.00h or 21.00h
+  \"%I:%M%p\" - 12-hour, 0-padded, with AM/PM: 09:00AM or 09:00PM
+  \"%l.%M%p\" - 12-hour, blank-padded, with AM/PM: 9.00AM or 9.00PM"
+  :version "31.1"
+  :type '(string))
+
+(defcustom di:attendee-format-function #'di:attendee-skeleton
+  "Function to format ATTENDEE properties during diary import.
+
+This should be a function which inserts information about an
+`icalendar-attendee' into the current buffer.  It is convenient to
+express such a function as a skeleton; see `define-skeleton' and
+`skeleton-insert' for more information.
+
+The function will be called with one argument, ATTENDEE, which will be
+an `icalendar-attendee' syntax node.  It should insert information about
+the attendee into the current buffer.  See `icalendar-with-property' for
+a convenient way to bind the data in ATTENDEE.
+
+For convenience when writing this function as a skeleton, the following
+variables will also be (dynamically) bound when the function is called.
+All values will be strings (unless another type is noted), or nil:
+
+`attendee-address' - address, with \"mailto:\" removed
+`attendee-cn' - common name (`icalendar-cnparam')
+`attendee-cutype' - calendar user type (`icalendar-cutypeparam')
+`attendee-role' - role in the event (`icalendar-roleparam')
+`attendee-partstat' - participation status (`icalendar-partstatparam')
+`attendee-rsvp' - whether an RSVP is requested (`icalendar-rsvpparam')"
+  :version "31.1"
+  :type '(radio (function-item di:attendee-skeleton)
+                (function :tag "Other function")))
+
+(defcustom di:skip-addresses-regexp
+  (concat "\\<" (regexp-quote user-mail-address) "\\'")
+  "Regular expression matching addresses to skip when importing.
+
+This regular expression should match calendar addresses (which are
+typically \"mailto:\" URIs) which should be skipped when importing
+ATTENDEE, ORGANIZER, and other iCalendar properties that identify a
+contact.
+
+You can make this match your own email address(es) to prevent them from
+being formatted by `diary-icalendar-attendee-format-function' and
+listed in diary entries."
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:vevent-format-function #'di:vevent-skeleton
+  "Function to format VEVENT components for the diary.
+
+This function is called with one argument VEVENT, an `icalendar-vevent'.
+It should insert formatted data from this event into the current buffer.
+It is convenient to express such a function as a skeleton; see
+`define-skeleton' and `skeleton-insert' for more information.  See
+`icalendar-with-component' for a convenient way to bind the data in
+VEVENT.
+
+For convenience when writing this function as a skeleton, the following
+variables will be (dynamically) bound when the function is called.  All
+values will be strings unless another type is noted, or nil:
+
+`ical-as-alarm' (symbol) - non-nil when the event should be formatted for an
+  alarm notification in advance of the event.  The symbol indicates the
+  type of alarm: `email' means to format the event as the body of an email.
+  (Currently only used for EMAIL alarms; see `diary-icalendar-export-alarms'.)
+`ical-attachments' (list of strings) - URLs or filenames of attachments
+  in the event
+`ical-attendees' (list of strings) - the participants of the event,
+  formatted by `diary-icalendar-attendee-format-function'
+`ical-categories' (list of strings) - categories specified in the event
+`ical-access' - the event's access classification
+`ical-comments' (list of strings) - comments specified in the event
+`ical-description' - the event's description
+`ical-start' - start date and time in a single string.  When importing,
+  includes the date, otherwise just the (local) time.
+`ical-end' - end date and time in a single string.  When importing,
+  includes the date, otherwise just the (local) time.
+`ical-start-to-end' - a single string containing both start and end date and
+  (local) time.  If the event starts and ends on the same day, the date
+  is not repeated.  When importing, dates are included, and the string
+  may contain a diary s-exp; when displaying, the string contains only
+  the times for the displayed date.  If there is no end date, same as
+  `ical-start'.
+`ical-importing' (a boolean) - t if the event should be formatted for import.
+  When nil, the event should be formatted for display rather than import.
+  When importing it is important to include all information from the event
+  that you want to be saved in the diary; when displaying, information like
+  the date (or date-related S-expressions) and UID can be left out.
+`ical-location' - the event's location, or geographical coordinates
+`ical-nonmarking' (a boolean) - if non-nil, the diary entry should be nonmarking
+`ical-organizer' - the event's organizer, formatted by
+  `diary-icalendar-attendee-format-function'
+`ical-priority' (a number) - the event's priority (1 = highest priority,
+  9 = lowest; 0 = undefined)
+`ical-rrule-sexp' - a string containing a diary S-expression for a
+  recurring event.  If this is non-nil, you should normally use it
+  instead of the start-* and end-* variables to form the date of the
+  entry.
+`ical-status' - overall status specified by the organizer (e.g. \"confirmed\")
+`ical-summary' - a summary of the event
+`ical-transparency' - the event's time transparency status, either
+  \"OPAQUE\" (busy) or \"TRANSPARENT\" (free); see `icalendar-transp'
+`ical-uid' - the unique identifier of the event
+`ical-url' - a URL for the event"
+  :version "31.1"
+  :type '(radio (function-item di:vevent-skeleton)
+                (function :tag "Other function")))
+
+(defcustom di:vjournal-format-function #'di:vjournal-skeleton
+  "Function to format VJOURNAL components for the diary.
+
+This function is called with one argument VJOURNAL, an
+`icalendar-vjournal'.  It should insert formatted data from this journal
+entry into the current buffer.  It is convenient to express such a
+function as a skeleton; see `define-skeleton' and `skeleton-insert' for
+more information, and see `diary-icalendar-vjournal-skeleton' for an
+example.  See `icalendar-with-component' for a convenient way to bind
+the data in VJOURNAL.
+
+For convenience when writing this function as a skeleton, the following
+variables will be (dynamically) bound when the function is called.  All
+values will be strings unless another type is noted, or nil:
+
+`ical-attachments' (list of strings) - URLs or filenames of attachments
+  in the journal entry
+`ical-attendees' (list of strings) - the participants of the journal entry,
+  formatted by `diary-icalendar-attendee-format-function'
+`ical-categories' (list of strings) - categories specified in the journal entry
+`ical-access' - the journal entry's access classification
+`ical-comments' (list of strings) - comments specified in the journal entry
+`ical-description' - the journal entry's description(s) as a single
+  string, separated by newlines (more than one description is allowed in
+  VJOURNAL components)
+`ical-start' - start date and time in a single string.  When importing,
+  includes the date, otherwise just the (local) time.
+`ical-importing' (a boolean) - t if the journal entry should be
+  formatted for import.  When nil, the entry should be formatted for
+  display rather than import.  When importing it is important to include
+  all information from the entry that you want to be saved in the diary;
+  when displaying, information like the date (or date-related
+  S-expressions) and UID can be left out.
+`ical-nonmarking' (a boolean) - if non-nil, the diary entry should be nonmarking
+`ical-organizer' - the journal entry's organizer, formatted by
+  `diary-icalendar-attendee-format-function'
+`ical-rrule-sexp' - a string containing a diary S-expression for a recurring
+  journal entry.  If this is non-nil, you should normally use it instead
+  of the start-* variables to form the date of the entry.
+`ical-status' - overall status specified by the organizer (e.g. \"draft\")
+`ical-summary' - a summary of the journal entry
+`ical-uid' - the unique identifier of the journal entry
+`ical-url' - a URL for the journal entry"
+  :version "31.1"
+  :type '(radio (function-item di:vjournal-skeleton)
+                (function :tag "Other function")))
+
+(defcustom di:import-vjournal-as-nonmarking t
+  "Whether to import VJOURNAL components as nonmarking diary entries.
+
+If this variable is non-nil, VJOURNAL components will be imported into
+the diary as \"nonmarking\" entries by prefixing
+`diary-nonmarking-symbol'.  This means they will not cause their date to
+be marked in the calendar when the command `diary-mark-entries' is
+called.  See Info node `(emacs)Displaying the Diary' for more
+information."
+  :version "31.1"
+  :type '(choice (const :tag "Import as nonmarking entries" t)
+                 (const :tag "Import as normal (marking) entries" nil)))
+
+(defcustom di:vtodo-format-function #'di:vtodo-skeleton
+  "Function to format VTODO components for the diary.
+
+This function is called with one argument VTODO, an `icalendar-vtodo'.
+It should insert formatted data from this task into the current buffer.
+It is convenient to express such a function as a skeleton; see
+`define-skeleton' and `skeleton-insert' for more information.  See
+`icalendar-with-component' for a convenient way to bind the data in
+VTODO.
+
+For convenience when writing this function as a skeleton, the following
+variables will be (dynamically) bound when the function is called.  All
+values will be strings unless another type is noted, or nil:
+
+`ical-as-alarm' (symbol) - non-nil when the task should be formatted for
+  an alarm notification in advance of the task.  The symbol indicates
+  the type of alarm: `email' means to format the task as the body of an
+  email.  (Currently only used for EMAIL alarms; see
+  `diary-icalendar-export-alarms'.)
+`ical-attachments' (list of strings) - URLs or filenames of attachments
+  in the task
+`ical-attendees' (list of strings) - the participants of the task,
+  formatted by `diary-icalendar-attendee-format-function'
+`ical-categories' (list of strings) - categories specified in the task
+`ical-access' - the task's access classification
+`ical-comments' (list of strings) - comments specified in the task
+`ical-completed' - when the task was completed, formatted as a local
+  date-time string
+`ical-description' - the task's description
+`ical-start' - start-date and time in a single string.  When importing,
+  includes the date, otherwise just the (local) time
+`ical-start-to-end' - a single string containing both start and due date
+  and time.  If the task starts and ends on the same day, the date is
+  not repeated.  When importing, dates are included, and the string may
+  contain a diary s-exp; when displaying, the string contains only the
+  times for the displayed date.  If there is no end date, same as
+  `ical-start'.
+`ical-due' - due date and time in a single string
+`ical-end' - same as `ical-due'
+`ical-work-time-sexp' - when the task has both a start date and a due date,
+  this is a %%(diary-time-block ...) diary S-expression representing the
+  time from the start date to the due date (only non-nil when
+  importing).  You can use this e.g. to make a separate entry for the
+  task's work time, so that it shows up every day in the diary until it
+  is due.
+`ical-importing' (a boolean) - t if the task should be formatted for import.
+  When nil, the task should be formatted for display rather than import.
+  When importing it is important to include all information from the task
+  that you want to be saved in the diary; when displaying, information like
+  the date (or date-related S-expressions) and UID can be left out.
+`ical-location' - the task's location, or geographical coordinates
+`ical-nonmarking' (a boolean) - if non-nil, the diary entry should be nonmarking
+`ical-organizer' - the task's organizer, formatted by
+  `diary-icalendar-attendee-format-function'
+`ical-percent-complete' (a number between 0 and 100) - the percentage of
+  the task which has already been completed
+`ical-priority' (a number) - the task's priority (1 = highest priority,
+  9 = lowest; 0 = undefined)
+`ical-rrule-sexp' - a string containing a diary S-expression for a
+  recurring task (only non-nil when importing).  When this is non-nil,
+  you should normally use it instead of the start and end variables to
+  form the date of the entry.
+`ical-status' - overall status specified by the organizer (e.g. \"confirmed\")
+`ical-summary' - a summary of the task
+`ical-uid' - the unique identifier of the task
+`ical-url' - a URL for the task"
+  :version "31.1"
+  :type '(radio (function-item di:vjournal-skeleton)
+                (function :tag "Other function")))
+
+(defcustom di:import-predicate #'identity
+  "Predicate to filter iCalendar components before importing.
+
+This function must accept one argument, which will be an
+`icalendar-vevent', `icalendar-vtodo', or `icalendar-vjournal'
+component.  It should return non-nil if this component should be
+formatted for import, or nil if it should be skipped.
+
+The default value will format all the events, todos, and journal entries
+in a given calendar."
+  :version "31.1"
+  :type '(radio (function-item identity)
+                (function :tag "Other predicate")))
+
+;;; Export customization
+(defgroup diary-icalendar-export nil
+  "iCalendar export from diary."
+  :version "31.1"
+  :group 'diary-icalendar
+  :prefix 'diary-icalendar)
+
+(defcustom di:address-regexp
+  (rx line-start
+      (one-or-more space)
+      (zero-or-one ;; property prefix, e.g. "Attendee:" or "Organizer:"
+       (seq (one-or-more word) ":"))
+      (group-n 2 (zero-or-more (not (any "<" "\n"))))
+      "<"
+      (group-n 1 (one-or-more (not (any "@" "\n")))
+                 "@"
+                 (one-or-more (not (any ">" "\n"))))
+      ">")
+  "Regular expression to match calendar user (email) addresses.
+
+The full address should match group 1; \"mailto:\" will be prepended to
+the full address during export, unless it or another URI scheme is
+present.  If there is a match in group 2, it will be used as the
+common name associated with the address (see `icalendar-cnparam').
+
+The default value matches names and addresses on lines like:
+
+  Ms. Baz <baz@foo.com>
+
+as well as on lines like:
+
+  Property: Ms. Baz <baz@foo.com> other data...
+
+Any matching address within a diary entry will be exported as an
+iCalendar ATTENDEE property, unless the line on which it appears is also
+a match for `diary-icalendar-organizer-regexp', in which case it will be
+exported as the ORGANIZER property."
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:description-regexp nil
+  "Regular expression to match description in an entry.
+
+If this is nil, the entire entry (after the date and time specification)
+is used as the description.  Thus, it is only necessary to set this
+variable if you want to export diary entries where the text to be used
+as the description should not include the full entry body.  In that case,
+the description should match group 1 of this regexp."
+  :version "31.1"
+  :type '(radio
+          (const :tag "Use full entry body" nil)
+          (regexp :tag "Regexp")))
+
+(defcustom di:organizer-regexp
+  (rx line-start
+      (one-or-more space)
+      "Organizer:")
+  "Regular expression to match line of an entry specifying the ORGANIZER.
+
+This regular expression need *not* match the name and address of the
+organizer (`diary-icalendar-address-regexp' is responsible for that).
+It only needs to match a line on which the organizer's address appears,
+to distinguish the organizer's address from other addresses."
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:class-regexp
+  (rx line-start
+      (one-or-more space)
+      (or "Class:" ; for backward compatibility
+          "Access:")
+      (zero-or-more space)
+      (group-n 1 (or "public" "private" "confidential")))
+  "Regular expression to match access classification.
+
+The access classification value should be matched by group 1.  The default
+regexp matches access classifications like:
+  Access: C
+or
+  Class: C
+where C can be any of:
+  public
+  private
+  confidential"
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:location-regexp
+  (rx line-start
+      (one-or-more space)
+      "Location:"
+      (zero-or-more space)
+      (group-n 1 (one-or-more not-newline)))
+  "Regular expression to match location of an event.
+
+The location value should be matched by group 1.  The default regexp
+matches lines like:
+
+  Location: Some place"
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:status-regexp
+  (rx line-start
+      (one-or-more space)
+      "Status:"
+      (zero-or-more space)
+      (group-n 1 (or "tentative" "confirmed" "cancelled" "needs-action" "completed"
+                     "in-process" "draft" "final")))
+  "Regular expression to match status of an event.
+
+The status value should be matched by group 1.  The default regexp
+matches statuses on lines like:
+
+  Status: S
+
+where S can be any of:
+
+  tentative
+  confirmed
+  cancelled
+  needs-action
+  completed
+  in-process
+  draft
+  final"
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:summary-regexp nil
+  "Regular expression to match summary in an entry.
+
+If this is nil, the first line of the entry (after the date and time
+specification) is used as the summary.  Thus, it is only necessary to set
+this variable if you want to export diary entries where the text to be
+used as the summary does not appear on the first line of the entry.  In
+that case, the summary should match group 1 of this regexp."
+  :version "31.1"
+  :type '(choice (const nil) regexp))
+
+(defcustom di:todo-regexp nil
+  "Regular expression that identifies an entry as a task (VTODO).
+
+If this is non-nil, any diary entry that matches this regexp will be
+exported as an iCalendar VTODO component (instead of VEVENT), with its
+due date equal to the entry date."
+  :version "31.1"
+  :type '(radio (const :tag "Do not export VTODO tasks" nil)
+                (regexp :tag "Regexp for tasks")))
+
+(defcustom di:uid-regexp
+  (rx line-start
+      (one-or-more space)
+      "UID:"
+      (zero-or-more space)
+      (group-n 1 (one-or-more not-newline)))
+  "Regular expression to match UID of an entry.
+
+The UID value should be matched by group 1.  The default regexp matches
+UIDs on lines like:
+
+  UID: some-unique-identifier"
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:url-regexp
+  (rx line-start
+      (one-or-more space)
+      "URL:"
+      (zero-or-more space)
+      (group-n 1 (eval 'ical:uri)))
+  "Regular expression to match URL of an entry.
+
+The full URL should be matched by group 1.  The default regexp matches
+URLs on lines like:
+
+  URL: http://example.com/foo/bar"
+  :version "31.1"
+  :type '(regexp))
+
+(defcustom di:export-nonmarking-entries t
+  "Whether to export nonmarking diary entries.
+
+If this variable is nil, nonmarking diary entries (those prefixed with
+`diary-nonmarking-symbol') are never exported.  If it is non-nil,
+nonmarking diary entries are exported; see also
+`diary-icalendar-export-nonmarking-as-vjournal' for more control over
+how they are exported."
+  :version "31.1"
+  :type '(choice (const :tag "Export nonmarking entries" t)
+                 (const :tag "Do not export nonmarking entries" nil)))
+
+(defcustom di:export-nonmarking-as-vjournal nil
+  "Whether to export nonmarking diary entries as VJOURNAL components.
+
+If this variable is non-nil, nonmarking diary entries (those prefixed
+with `diary-nonmarking-symbol') will be exported as iCalendar VJOURNAL
+components, rather than VEVENT components.  VJOURNAL components are
+intended to represent notes, documents, or other data associated with a
+date.  External calendar applications may treat VJOURNAL components
+differently than VEVENTs, so consult your application's documentation
+before setting this variable to t.
+
+If this variable is nil, nonmarking entries will be exported as VEVENT
+components which do not take up busy time in the calendar (i.e., with
+the TRANSP property set to \"TRANSPARENT\"; see `icalendar-transp')."
+  :version "31.1"
+  :type '(choice (const :tag "Export nonmarking entries as VEVENT" nil)
+                 (const :tag "Export nonmarking entries as VJOURNAL" t))
+  :link '(url-link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.3"))
+
+(defcustom di:export-alarms
+  nil
+  "Determine whether and how alarms are included in exported diary events.
+
+If this variable is nil, no alarms are created during export.
+If it is non-nil, it should be a list of lists like:
+
+\((TYPE LEAD-TIME [OPTIONS]) ...)
+
+In each inner list, the first element TYPE should be a symbol indicating
+an alarm type to generate: one of \\='audio, \\='display, or \\='email.
+The second element LEAD-TIME should be an integer specifying the amount
+of time before the event, in minutes, when the alarm should be
+triggered.  For audio alarms, there are currently no other
+OPTIONS.
+
+For display and email alarms, the next OPTION is a format string for the
+displayed alarm, or the email subject line.  In this string, \"%t\" will
+be replaced with LEAD-TIME and \"%s\" with the event's summary.
+
+If TYPE is \\='email, the next OPTION should be a list whose members
+specify the email addresses to which email alarms should be sent.  These
+can either be email addresses (as strings), or the symbol
+\\='from-entry, meaning that these addresses should be taken from the
+exported diary entry (see `diary-icalendar-address-regexp')."
+  :version "31.1"
+  :type
+  '(choice (const :tag "Do not include alarms when exporting diary entries" nil)
+           (set :tag "Create alarms of these types"
+                (list :tag "Audio alarms"
+                      (const :tag "Options" audio)
+                      (integer :tag "Advance time (in minutes)"
+                               :value 10)
+                      ;; TODO: specify an audio file to attach?
+                      ;; TODO: other options we could have here and below:
+                      ;; - whether alarm is before event start or end
+                      ;; - repetitions and delays between repetitions
+                      )
+                (list :tag "Display alarms"
+                      (const :tag "Options" display)
+                      (integer :tag "Advance time (minutes)"
+                               :value 10)
+                      (string :tag "Display format"
+                              :value "In %t minutes: %s")
+                      ;; TODO: other options?
+                      )
+                (list :tag "Email alarms"
+                      (const :tag "Options" email)
+                      (integer :tag "Advance time (minutes)"
+                               :value 10)
+                      ;; TODO: other options?
+                      (string :tag "Subject line format"
+                              :value "In %t minutes: %s")
+                      (set
+                       :tag "Attendees"
+                       (const :tag "Parse addresses from entry"
+                              from-entry)
+                       (repeat :tag "Other addresses"
+                               (string :tag "Email address")))))))
+
+(defcustom di:export-sexp-enumeration-days
+  14
+  "Number of days over which an S-expression diary entry is enumerated.
+
+Some S-expression entries cannot be translated to iCalendar format.
+They are therefore enumerated, i.e., explicitly evaluated for a
+certain number of days, and then exported.  The enumeration starts
+on the current day and continues for the number of days given here.
+
+See `icalendar-export-sexp-enumerate-all' for a list of sexp
+entries which by default are NOT enumerated."
+  :version "31.1"
+  :type 'integer)
+
+(defcustom di:export-sexp-enumerate-all
+  nil
+  "Whether all S-expression diary entries are enumerated.
+
+If this variable is non-nil, all S-expression diary entries are
+enumerated for `diary-icalendar-export-sexp-enumeration-days' days
+instead of translating them into an iCalendar equivalent.
+This causes the following S-expression entries to be enumerated
+instead of translated to a recurrence rule:
+ `diary-anniversary'
+ `diary-block'
+ `diary-cyclic'
+ `diary-date'
+ `diary-float'
+ `diary-remind'
+ `diary-rrule'
+ `diary-time-block'
+All other S-expression entries are enumerated in any case."
+  :version "31.1"
+  :type '(choice (const :tag "Export without enumeration when possible" nil)
+                 (const :tag "Always enumerate S-expression entries" t)))
+
+(defcustom di:recurring-start-year
+  (1- (decoded-time-year (decode-time)))
+  "Start year for recurring events.
+
+Set this to a year just before the start of your personal calendar.
+It is needed when exporting certain diary S-expressions to iCalendar
+recurring events, and because some calendar browsers only propagate
+recurring events for several years beyond the start time."
+  :version "31.1"
+  :type 'integer)
+
+(defcustom di:time-zone-export-strategy
+  'local
+  "Strategy to use for exporting clock times in diary files.
+
+The symbol `local' (the default) means to assume that times are in the
+time zone determined by `calendar-current-time-zone'.  The time zone
+information returned by that function will be exported as an iCalendar
+VTIMEZONE component, and clock times in the diary file will be exported
+with a reference to that time zone definition.
+
+On some systems, `calendar-current-time-zone' cannot determine time zone
+information for the local time zone.  In that case, you can set this
+variable to a list in the format returned by that function:
+
+ (UTC-DIFF DST-OFFSET STD-ZONE DST-ZONE
+  DST-STARTS DST-ENDS DST-STARTS-TIME DST-ENDS-TIME)
+
+This list describes the time zone you would like to use for export.  See
+the docstring of `calendar-current-time-zone' for details.  Times in the
+diary file will be exported like with `local' for this time zone.
+
+The other possible values for this variable avoid the need to include
+any time zone information in the exported iCalendar data:
+
+The symbol `to-utc' means to re-encode all exported times to UTC
+time.  In this case, export will assume that times are in Emacs local
+time, and rely on `encode-time' and `decode-time' to convert them to UTC
+times.
+
+The symbol `floating' means to export clock times without any time
+zone identifier, which the iCalendar standard (RFC5545) calls
+\"floating\" times.  RFC5545 specifies that floating times should be
+interpreted as local to whichever time zone the recipient of the
+iCalendar data is currently in (which might be different from your local
+time zone).  You should only use this if that behavior makes sense for
+the events you are exporting."
+  :version "31.1"
+  :type
+  '(radio (const :tag "Use TZ from `calendar-current-time-zone'" local)
+          (const :tag "Convert local times to UTC" to-utc)
+          (const :tag "Use floating times" floating)
+          (sexp :tag "User-provided TZ information"
+                :match icr:-tz-info-sexp-p
+                :type-error
+                "See `calendar-current-time-zone' for format"))
+  :link '(url-link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.5"))
+
+(defcustom di:export-linewise
+  nil
+  "Export entries with multiple lines to distinct events.
+
+If this is non-nil, each line of a diary entry will be exported as a
+separate iCalendar event.
+
+If you write your diary entries in a one-entry-per-day style, with
+multiple events or appointments per day, you can use this variable to
+export these individual events to iCalendar format.  For example, an
+entry like:
+
+2025-05-03
+  9AM Lab meeting
+    Günter to present on new assay
+  Start experiment A
+  12:30-1:30PM Lunch with Phil
+  16:00 Experiment A finishes; move to freezer
+
+will be exported as four events, each on 2025-05-03 but with different
+start times (except for the second event, \"Start experiment A\", which
+has no start time).  An event line can be continued onto subsequent lines
+via additional indentation, as in the first event in this entry.
+
+If this variable is non-nil, each distinct event must begin on a
+continuation line of the entry (below the date); any text on the same
+line as the date is ignored.  A time specification can only appear at
+the beginning of each continuation line of the entry, immediately after
+the leading whitespace.
+
+If this variable is nil, each entry will be exported as exactly one
+event, and only a time specification immediately following the date will
+determine the start and end times for that event.  Thus, in the example
+above, the exported event would have a start date but no start time or
+end time.  The times in the entry would be preserved as text in the
+event description."
+  :version "31.1"
+  :type '(radio (const :tag "Do not export linewise" nil)
+                (const :tag "Export linewise" t)))
+
+(defcustom di:other-properties-parser nil
+  "Function to parse additional iCalendar properties from diary entries.
+
+If you like to keep your diary entries in a particular format, you can
+set this to a function which parses that format to iCalendar properties
+during iCalendar export, so that other calendar applications can use
+them.
+
+The parsing function will be called with the current restriction set to
+the boundaries of a diary entry.  If `diary-icalendar-export-linewise'
+is non-nil, the restriction will correspond to a single event in a
+multi-line diary entry.
+
+The function should accept two arguments, TYPE and PROPERTIES.  TYPE is
+the iCalendar type symbol (one of \\='icalendar-vevent,
+\\='icalendar-vjournal, or \\='icalendar-vtodo) for the component being
+generated for the entry.  PROPERTIES is the list of property nodes that
+`diary-icalendar-parse-entry' has already parsed from the entry and will
+be included in the exported component.
+
+The function should return a list of iCalendar property nodes, which
+(in addition to PROPERTIES) will be incorporated into the
+`icalendar-vevent', `icalendar-vjournal', or `icalendar-vtodo' component
+node created from the current entry.  See the docstrings of those
+symbols for more information on the properties they can contain, and the
+`icalendar-make-property' macro for a simple way to create property
+nodes from values parsed from the entry."
+  :version "31.1"
+  :type '(radio (const :tag "Do not parse additional properties" nil)
+                (function :tag "Parsing function")))
+
+
+;; Utilities for display and import
+
+;;; Error handling
+(define-error 'ical:diary-import-error "Unable to import iCalendar data"
+              'ical:error)
+
+(cl-defun di:signal-import-error (msg &key (diary-buffer (current-buffer))
+                                           (position (point))
+                                           line
+                                           (severity 2))
+  (let ((err-data
+          (list :message msg
+                :buffer diary-buffer
+                :position position
+                :line line
+                :severity severity)))
+    (signal 'ical:diary-import-error err-data)))
+
+;;; Backward compatibility with icalendar.el
+
+;; icalendar.el provided the following customization variables:
+;; `icalendar-import-format'
+;; `icalendar-import-format-class'
+;; `icalendar-import-format-description'
+;; `icalendar-import-format-location'
+;; `icalendar-import-format-organizer'
+;; `icalendar-import-format-summary'
+;; `icalendar-import-format-status'
+;; `icalendar-import-format-url'
+;; `icalendar-import-format-uid'
+;; These were all format strings: `icalendar-import-format' was the
+;; top-level format string, which would potentially incorporate the
+;; formatted output from the others.  This approach to customization
+;; isn't very flexible, though, and doing it right requires a
+;; separate defcustom variable for each iCalendar property.  (The above
+;; list is not nearly exhaustive.) I have abandoned this approach in
+;; what follows in favor of skeleton.el templates, but the following two
+;; functions provide backward compatibility for anyone who had
+;; customized the values of the above variables:
+(defun di:-use-legacy-vars-p ()
+  "Return non-nil if user has set `icalendar-import-format*' variables.
+If any of these variables have non-default values, they will be used by
+`diary-icalendar-import-format-entry' to import events.  This function
+is for backward compatibility; please do not rely on it in new code."
+  (declare (obsolete nil "31.1"))
+  (with-suppressed-warnings
+      ((obsolete ical:import-format
+                 ical:import-format-class
+                 ical:import-format-description
+                 ical:import-format-location
+                 ical:import-format-organizer
+                 ical:import-format-summary
+                 ical:import-format-status
+                 ical:import-format-url
+                 ical:import-format-uid))
+    (or
+     (and (boundp 'ical:import-format)
+          (not (equal ical:import-format
+                      (custom--standard-value 'ical:import-format))))
+     (and (boundp 'ical:import-format-class)
+          (not (equal ical:import-format-class
+                      (custom--standard-value 'ical:import-format-class))))
+     (and (boundp 'ical:import-format-description)
+          (not (equal ical:import-format-description
+                      (custom--standard-value
+                       'ical:import-format-description))))
+     (and (boundp 'ical:import-format-location)
+          (not (equal ical:import-format-location
+                      (custom--standard-value 'ical:import-format-location))))
+     (and (boundp 'ical:import-format-organizer)
+          (not (equal ical:import-format-organizer
+                      (custom--standard-value 'ical:import-format-organizer))))
+     (and (boundp 'ical:import-format-summary)
+          (not (equal ical:import-format-summary
+                      (custom--standard-value 'ical:import-format-summary))))
+     (and (boundp 'ical:import-format-status)
+          (not (equal ical:import-format-status
+                      (custom--standard-value 'ical:import-format-status))))
+     (and (boundp 'ical:import-format-url)
+          (not (equal ical:import-format-url
+                      (custom--standard-value 'ical:import-format-url))))
+     (and (boundp 'ical:import-format-uid)
+          (not (equal ical:import-format-uid
+                      (custom--standard-value 'ical:import-format-uid)))))))
+
+(defun di:-format-vevent-legacy (date class desc location organizer
+                                 summary status url uid)
+  "Format an entry on DATE using the values of obsolete import variables.
+This function is for backward compatibility; please do not rely on it in
+new code."
+  (declare (obsolete nil "31.1"))
+  (with-suppressed-warnings
+      ((obsolete ical:import-format
+                 ical:import-format-class
+                 ical:import-format-description
+                 ical:import-format-location
+                 ical:import-format-organizer
+                 ical:import-format-summary
+                 ical:import-format-status
+                 ical:import-format-url
+                 ical:import-format-uid))
+
+    (insert ical:import-format)
+    (replace-regexp-in-region "%c"
+                              (format ical:import-format-class class)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%d"
+                              (format ical:import-format-description desc)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%l"
+                              (format ical:import-format-location location)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%o"
+                              (format ical:import-format-organizer organizer)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%s"
+                              (format ical:import-format-summary summary)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%t"
+                              (format ical:import-format-status status)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%u"
+                              (format ical:import-format-url url)
+                              (point-min) (point-max))
+    (replace-regexp-in-region "%U"
+                              (format ical:import-format-uid uid)
+                              (point-min) (point-max))
+    (goto-char (point-min))
+    (insert date " ")))
+
+(defun di:-vevent-to-legacy-alist (vevent)
+  "Convert an `icalendar-vevent' to an alist of the kind used by icalendar.el.
+This function is for backward compatibility; please do not rely on it in
+new code."
+  (declare (obsolete nil "31.1"))
+  ;; function values of `icalendar-import-format' expect a list like:
+  ;; ((VEVENT nil
+  ;;   ((PROP1 params val)
+  ;;    (PROP2 params val)
+  ;;    ...)))
+  (let ((vevent-children (ical:ast-node-children vevent))
+        children)
+    (dolist (p vevent-children)
+      (let* ((type (ical:ast-node-type p))
+             (list-sep (get type 'ical:list-sep))
+             (name (intern (car (rassq type ical:property-types))))
+             ;; icalendar.el did not interpret values when parsing, so we
+             ;; convert back to string representation:
+             (value (ical:ast-node-value p))
+             (value-str
+              (or (ical:ast-node-meta-get :original-value p)
+                  (if list-sep
+                      (string-join (mapcar #'ical:default-value-printer value)
+                                   list-sep)
+                    (ical:default-value-printer value))))
+             params)
+        (when (ical:ast-node-children p)
+          (dolist (param (ical:ast-node-children p))
+            (let* ((par-str (ical:print-param-node param))
+                   (split (string-split par-str "[;=]"))
+                   (parname (intern (nth 1 split)))
+                   (parval (nth 2 split)))
+              (push `(,parname nil ,parval) params)))
+          (setq params (nreverse params)))
+        (push `(,name ,params ,value-str) children)))
+    (setq children (nreverse children))
+    ;; Return the legacy alist:
+    `((VEVENT nil ,children))))
+
+;;; Other utilities
+
+(defconst di:entry-regexp
+  (rx line-start
+      (group-n 1 ; first line of entry
+        (or (group-n 2 (regexp diary-nonmarking-symbol))
+            (not (any "\t\n #")))
+        (one-or-more not-newline))
+      (group-n 3 ; continuation lines of entry
+        (zero-or-more "\n" (any space) (zero-or-more not-newline))))
+  "Regular expression to match a full diary entry.
+
+Group 1 matches the first line of the entry.  Group 2 contains
+`diary-nonmarking-symbol', if it was present at the start of the first
+line.  Group 3 contains any continuation lines of the entry.")
+
+;; TODO: move to diary-lib.el?
+(defun di:entry-bounds ()
+  "Return markers (START END) bounding the diary entry around point.
+If point is not in an entry, return nil."
+  (save-excursion
+    (let* ((pt (point))
+           (bound (point-min))
+           (start (make-marker))
+           (end (make-marker)))
+      (when (re-search-backward "^[[:space:]]*$" nil t)
+        (setq bound (match-end 0)))
+      (goto-char pt)
+      (cond ((looking-at di:entry-regexp)
+             (set-marker start (match-beginning 0))
+             (set-marker end (match-end 0)))
+            ((re-search-backward di:entry-regexp bound t)
+             (set-marker start (match-beginning 0))
+             ;; match again forward, to ensure we get the full entry;
+             ;; see `re-search-backward':
+             (goto-char start)
+             (when (looking-at di:entry-regexp)
+               (set-marker end (match-end 0))))
+            (t nil))
+      (when (and (marker-position start) (marker-position end))
+        (list start end)))))
+
+(defun di:find-entry-with-uid (uid &optional diary-filename)
+  "Search DIARY-FILENAME (default: `diary-file') for an entry containing UID.
+
+The UID must occur on a line matching `diary-icalendar-uid-regexp'.  If
+such an entry exists, return markers (START END) bounding it.
+Otherwise, return nil."
+  (let* ((diary-file (or diary-filename diary-file))
+         (diary-buffer (or (find-buffer-visiting diary-file)
+                           (find-file-noselect diary-file))))
+    (with-current-buffer diary-buffer
+      (save-excursion
+        (save-restriction
+          (widen)
+          (goto-char (point-min))
+          (catch 'found
+            (while (re-search-forward di:uid-regexp nil t)
+              (when (equal uid (match-string 1))
+                (throw 'found (di:entry-bounds))))
+            ;; continue search in included files:
+            ;; TODO: is this a good idea?
+            ;; (goto-char (point-min))
+            ;; (while (re-search-forward
+            ;;         (rx line-start (regexp diary-include-string)
+            ;;             ?\" (group-n 1 (one-or-more (not ?\")) ?\"))
+            ;;         nil t)
+            ;;   (let ((entry (di:find-entry-with-uid uid (match-string 1))))
+            ;;     (when entry
+            ;;       (throw 'found entry))))
+            ;; nothing to return:
+            nil))))))
+
+(defun di:y-or-n-or-edit-p (prompt)
+  "Like `y-or-n-p', but with the option to enter a recursive edit.
+Adds a message to current binding of `help-form' explaining how."
+  (let* ((allow-edits-map
+          (let ((map (make-sparse-keymap)))
+            (define-key map [remap edit]
+                        (lambda ()
+                          (interactive)
+                          (save-excursion
+                            (save-window-excursion
+                              (recursive-edit)))))
+            map))
+         (y-or-n-p-map (make-composed-keymap allow-edits-map
+                                             y-or-n-p-map))
+         (help-form
+          (concat (when (stringp help-form) (concat help-form "\n\n"))
+                  ;; FIXME: should use substitute-command-keys here, but
+                  ;; for some reason, even with \<y-or-n-p-map>, it
+                  ;; doesn't find the C-r and C-M-c bindings and only
+                  ;; suggests M-x ...
+                  "Type C-r to enter recursive edit before answering "
+                  "(C-M-c to exit).")))
+    (save-excursion
+      (save-restriction
+        (y-or-n-p prompt)))))
+
+;;; Skeletons
+;;
+;; We use skeleton.el's templating facilities to make formatting of
+;; different iCalendar elements in the diary simple and easy to
+;; customize.  There are default skeletons for each major type of
+;; iCalendar component (`di:vevent-skeleton', `di:vtodo-skeleton',
+;; `di:vjournal-skeleton'), and a corresponding defcustom pointing to
+;; each of these skeletons (`di:vevent-format-function', etc.).
+;; `di:format-entry' calls these skeletons, or user-provided functions,
+;; to format individual components as diary entries.  Since properties
+;; representing people (`icalendar-attendee', `icalendar-organizer') are
+;; important and relatively complex, another skeleton
+;; (`di:attendee-skeleton') takes care of formatting these for the
+;; top-level component skeletons.
+(defun di:attendee-skeleton (attendee)
+  "Default skeleton to format an `icalendar-attendee' for the diary.
+
+Includes any data from the attendee's `icalendar-cnparam' and
+`icalendar-partstatparam', and does not insert any data if its
+`icalendar-cutypeparam' is non-nil and anything other than
+\"INDIVIDUAL\" or \"GROUP\".
+
+The result looks like:
+  <foo@example.com>
+or
+  Baz Foo <foo@example.com>
+or
+  Baz Foo <foo@example.com> (declined)"
+  (ignore attendee) ; we only need the `attendee-' vars below
+  (with-suppressed-warnings ((free-vars attendee-cutype))
+    ;; skip non-human "attendees":
+    (when (or (not attendee-cutype)
+              (equal attendee-cutype "INDIVIDUAL")
+              (equal attendee-cutype "GROUP"))
+      (skeleton-insert
+       '(nil
+         attendee-cn
+         (format " <%s>" attendee-address)
+         (when attendee-partstat
+           (format " (%s)" (downcase attendee-partstat))))))))
+
+(defun di:format-attendee (attendee)
+  "Format ATTENDEE for the diary.
+
+ATTENDEE should be an `icalendar-attendee' or `icalendar-organizer'
+property node.  Returns a string representing an entry for the attendee,
+formatted by `diary-icalendar-attendee-format-function', unless the
+attendee's address matches the regexp in
+`diary-icalendar-skip-addresses-regexp'; in that case, nil is returned."
+  (ical:with-property attendee
+    ((ical:cutypeparam :value cutype)
+     (ical:cnparam :value cn)
+     (ical:roleparam :value role)
+     (ical:partstatparam :value partstat)
+     (ical:rsvpparam :value rsvp))
+    (unless (and di:skip-addresses-regexp
+                 (string-match-p di:skip-addresses-regexp value))
+      (dlet ((attendee-address (ical:strip-mailto value))
+             (attendee-cn (when cn (string-trim cn)))
+             (attendee-cutype cutype)
+             (attende-role role)
+             (attendee-partstat partstat)
+             (attendee-rsvp rsvp))
+        (with-temp-buffer
+          (funcall di:attendee-format-function attendee)
+          (buffer-string))))))
+
+(defun di:vevent-skeleton (vevent)
+  "Default skeleton to format an `icalendar-vevent' for the diary."
+  (ignore vevent)  ; we only need the dynamic `ical-*' variables here
+  (skeleton-insert
+   '(nil
+     (when (or ical-nonmarking (equal ical-transparency "TRANSPARENT"))
+       diary-nonmarking-symbol)
+     (or ical-rrule-sexp ical-start-to-end ical-start) & " "
+     ical-summary "\n"
+     @ ; start of body (for indentation)
+     (when ical-location "Location: ") ical-location
+     & "\n" (when ical-url "URL: ") & ical-url
+     & "\n" (when ical-status "Status: ") & ical-status
+     & "\n" (when ical-organizer "Organizer: ") & ical-organizer
+     & "\n" (di:format-list ical-attendees "Attendee")
+     & "\n" (di:format-list ical-categories "Category" "Categories")
+     & "\n" (di:format-list ical-comments "Comment")
+     & "\n" (di:format-list ical-contacts "Contact")
+     & "\n" (di:format-list ical-attachments "Attachment")
+     & "\n" (when (and ical-importing ical-access) "Access: ") & ical-access
+     & "\n" (when (and ical-importing ical-uid) "UID: ") & ical-uid
+     & "\n" (when ical-description "Description: ") & ical-description
+     & "\n"
+     @ ; end of body
+     (let* ((end (pop skeleton-positions))
+            (start (pop skeleton-positions)))
+       ;; TODO: should diary define a customizable indentation level?
+       ;; For now, we use 1 because that's what icalendar.el chose
+       (indent-code-rigidly start end 1)
+       nil) ; Don't insert return value
+     (when ical-importing "\n"))))
+
+(defun di:vjournal-skeleton (vjournal)
+  "Default skeleton to format an `icalendar-vjournal' for the diary."
+  (ignore vjournal)  ; we only need the dynamic `ical-*' variables here
+  (skeleton-insert
+   '(nil
+     (when (or ical-nonmarking di:import-vjournal-as-nonmarking)
+       diary-nonmarking-symbol)
+     (or ical-rrule-sexp ical-start) & " "
+     ical-summary "\n"
+     @ ; start of body (for indentation)
+     & "\n" (when ical-url "URL: ") & ical-url
+     & "\n" (when ical-status "Status: ") & ical-status
+     & "\n" (when ical-organizer "Organizer: ") & ical-organizer
+     & "\n" (di:format-list ical-attendees "Attendee")
+     & "\n" (di:format-list ical-categories "Category" "Categories")
+     & "\n" (di:format-list ical-comments "Comment")
+     & "\n" (di:format-list ical-contacts "Contact")
+     & "\n" (di:format-list ical-attachments "Attachment")
+     & "\n" (when (and ical-importing ical-access) "Access: ") & ical-access
+     & "\n" (when (and ical-importing ical-uid) "UID: ") & ical-uid
+     ;; In a vjournal, multiple `icalendar-description's are allowed:
+     & "\n" (di:format-list ical-descriptions "Description")
+     & "\n"
+     @ ; end of body
+     (let* ((end (pop skeleton-positions))
+            (start (pop skeleton-positions)))
+       (indent-code-rigidly start end 1)
+       nil) ; Don't insert return value
+     (when ical-importing "\n"))))
+
+(defun di:vtodo-skeleton (vtodo)
+  "Default skeleton to format an `icalendar-vtodo' for the diary."
+  (ignore vtodo)  ; we only need the dynamic `ical-*' variables here
+  (skeleton-insert
+   '(nil
+     (when ical-nonmarking diary-nonmarking-symbol)
+     (or ical-rrule-sexp ical-due) & " "
+     (when ical-due "Due: ") summary
+     (when start (concat " (Start: " ical-start ")"))
+     "\n"
+     @ ; start of body (for indentation)
+     & "\n" (when ical-url "URL: ") & ical-url
+     & "\n" (when ical-status "Status: ") & ical-status
+     & "\n" (when ical-completed "Completed: ") & ical-completed
+     & "\n" (when ical-percent-complete
+              (format "Progress: %d%%" ical-percent-complete))
+     & "\n" (when ical-organizer "Organizer: ") & ical-organizer
+     & "\n" (di:format-list ical-attendees "Attendee")
+     & "\n" (di:format-list ical-categories "Category" "Categories")
+     & "\n" (di:format-list ical-comments "Comment")
+     & "\n" (di:format-list ical-contacts "Contact")
+     & "\n" (di:format-list ical-attachments "Attachment")
+     & "\n" (when (and ical-importing ical-access) "Access: ") & ical-access
+     & "\n" (when (and ical-importing ical-uid) "UID: ") & ical-uid
+     & "\n" (when ical-description "Description: ") & ical-description
+     & "\n"
+     @ ; end of body
+     (let* ((end (pop skeleton-positions))
+            (start (pop skeleton-positions)))
+       (indent-code-rigidly start end 1)
+       nil) ; Don't insert return value
+     (when ical-importing "\n"))))
+
+;;; Further utilities for formatting/importing special kinds of values:
+(defun di:format-geo-coordinates (geo)
+  "Format an `icalendar-geo-coordinates' value as degrees N/S and E/W."
+  (format "%.6f°%s %.6f°%s" ; RFC5545 says we may truncate after 6 decimal places
+          (abs (car geo)) (if (< 0 (car geo)) "N" "S")
+          (abs (cdr geo)) (if (< 0 (cdr geo)) "E" "W")))
+
+(defun di:save-binary-attachment (base64-data dir &optional mimetype)
+  "Decode and save BASE64-DATA to a new file in DIR.
+
+The file will be named based on a unique prefix of BASE64-DATA with an
+extension based on MIMETYPE.  It will be saved in a subdirectory named
+DIR of `diary-icalendar-attachment-directory', which will be created if
+necessary.  Returns the (non-directory part of) the saved filename."
+  (require 'mailcap) ; for `mailcap-mime-type-to-extension'
+  ;; Create the subdirectory for the attachment if necessary:
+  (unless (and (directory-name-p di:attachment-directory)
+               (file-writable-p di:attachment-directory))
+    (di:signal-import-error
+     (format "Cannot write to directory: %s" di:attachment-directory)))
+  (make-directory (file-name-concat di:attachment-directory dir) t)
+  ;; Create a unique filename for the attachment.  Unfortunately RFC5545
+  ;; has no mechanism for suggesting a filename, so we just use a unique
+  ;; prefix of BASE64-DATA, or a random number as a fallback.
+  (let* ((nchars 4)
+         (max-chars (length base64-data))
+         (prefix (substring base64-data 0 nchars))
+         (extn (when mimetype
+                 (concat "." (symbol-name
+                              (mailcap-mime-type-to-extension mimetype)))))
+         (path (file-name-concat di:attachment-directory dir
+                                 (concat prefix extn))))
+    (while (file-exists-p path)
+      (cl-incf nchars)
+      (setq prefix (if (< nchars max-chars)
+                       (substring base64-data 0 nchars)
+                     (number-to-string (random max-chars))))
+      (setq path (file-name-concat di:attachment-directory dir
+                                   (concat prefix extn))))
+    ;; Save the file and return its name:
+    (let ((data (base64-decode-string base64-data))
+          (coding-system-for-write 'no-conversion))
+      (write-region data nil path)
+      (file-name-nondirectory path))))
+
+(defun di:save-attachments-from (attachment-nodes uid)
+  "Save attachments in ATTACHMENT-NODES and return a list of attachments.
+
+If these nodes contain binary data, rather than an URL, save the data to
+a file in `diary-icalendar-attachment-directory' (unless this variable
+is nil).  UID should be the universal ID of the component containing
+ATTACHMENT-NODES; the attachments will be saved in a subdirectory of the
+same name.  The returned list is a list of strings, which are either
+URLs or filenames."
+  (let (entry-attachments)
+    (dolist (node attachment-nodes)
+      (ical:with-property node
+        ((ical:fmttypeparam :value fmttype))
+        (when (and (eq 'ical:binary value-type)
+                   di:attachment-directory)
+          (let ((filename (di:save-binary-attachment value uid fmttype)))
+            (push filename entry-attachments)))
+        (when (eq 'ical:url value-type)
+          (push value entry-attachments))))
+    ;; Return the list of filenames and URLs:
+    entry-attachments))
+
+(defun di:format-list (values &optional title plural-form sep indent)
+  "Smartly format VALUES for the diary.
+
+VALUES should be a list of strings.  nil elements will be ignored, and an
+empty list will return nil.
+
+TITLE is a string to add to the beginning of the list; a colon will be
+appended.  PLURAL-FORM is the plural of TITLE, to be used when VALUES
+contains more than one element (default: TITLE+\"s\").
+
+The strings in VALUES are first joined with SEP (default: \", \"), with
+\"TITLE: \" prepended.  If the result is longer than the current value of
+`fill-column', the values are instead formatted one per line, with the
+title on its own line at the beginning, and the whole list indented
+relative to the title by INDENT spaces (default: 2).  Thus, in the first
+case, the result looks like:
+  TITLE(s): VAL1, VAL2, ...
+and in the second:
+  TITLE(s):
+    VAL1
+    VAL2
+    ..."
+  (when (cdr values)
+    (setq title (when title (or plural-form (concat title "s")))))
+  (unless indent
+    (setq indent 2))
+  ;; Remove nil values and extra whitespace:
+  (setq values (mapcar #'string-trim (delq nil values)))
+  (when values
+    (let ((line (concat
+                 (when title (concat title ": "))
+                 (string-join values (or sep ", ")))))
+      (if (< (length line) fill-column)
+          line
+        ;; Otherwise, one value per line:
+        (with-temp-buffer
+          (insert (string-join values "\n"))
+          (indent-code-rigidly (point-min) (point-max) indent)
+          (goto-char (point-min))
+          (when title
+            (insert title ":\n"))
+          (buffer-string))))))
+
+(defun di:format-time (dt &optional tzname)
+  "Format the `icalendar-date-time' DT for the diary.
+The time is formatted according to `diary-icalendar-time-format', which see.
+TZNAME, if specified, should be a string naming the time zone observance
+in which DT occurs."
+  ;; Diary does not support seconds, so silently truncate:
+  (let ((time (format-time-string di:time-format (encode-time dt))))
+    (if tzname
+        (concat time " " tzname)
+      time)))
+
+(defun di:format-time-as-local (dt &optional original-tzname)
+  "Format the time in `icalendar-date-time' DT for the diary.
+
+DT is translated to the system local time zone if necessary, and the
+original time specification is preserved in parentheses if it was given
+in a different zone.  ORIGINAL-TZNAME, if specified, should be a string
+naming the time zone observance in which DT was originally encoded in
+the iCalendar data."
+  (cl-typecase dt
+    (ical:date "")
+    (ical:date-time
+     (let* ((ts (encode-time dt))
+            (original-offset (decoded-time-zone dt))
+            (local-tz (current-time-zone ts))
+            (local-offset (car local-tz))
+            (local-dt (decode-time ts local-tz))
+            (local-str (di:format-time local-dt)))
+       (if (and original-tzname original-offset
+                (not (= original-offset local-offset)))
+           (format "%s (%s)" local-str (di:format-time dt original-tzname))
+         local-str)))))
+
+(defun di:format-date (dt)
+  "Format the `icalendar-date' or `icalendar-date-time' DT for the diary.
+If DT is a date-time, only the date part is considered.  The date is
+formatted with `calendar-date-string' according to the pattern in
+`diary-date-insertion-form'."
+  (dlet ((calendar-date-display-form diary-date-insertion-form))
+    (cl-typecase dt
+      (ical:date (calendar-date-string dt t t))
+      (ical:date-time (calendar-date-string (ical:date-time-to-date dt) t t)))))
+
+(defun di:format-date/time-as-local (dt &optional original-tzname)
+  "Format the `icalendar-date' or `icalendar-date-time' DT for the diary.
+
+If DT is a plain date, only the date will be formatted.  If DT is a
+date-time, both the date and the time will formatted, after translating
+DT into a date and time into the system local time.
+
+If specified, ORIGINAL-TZNAME should be a string naming the time zone
+observance in which DT was originally encoded in the iCalendar data.  In
+this case, the original clock time in DT will also be added in
+parentheses, with date if necessary.  For example:
+  2025/05/01 09:00 (08:00 GMT)
+or
+  2025/05/01 18:00 (2025/05/02 08:00 JST)"
+  (let ((local-dt (ical:date/time-to-local dt)))
+    (cl-typecase local-dt
+      (ical:date (di:format-date local-dt))
+      (ical:date-time
+       (let ((date (di:format-date local-dt))
+             (time (di:format-time local-dt))
+             (orig-date (di:format-date dt))
+             (orig-time (di:format-time dt original-tzname)))
+         (if original-tzname
+             (format "%s %s (%s)" date time
+                     (if (equal date orig-date)
+                         orig-time
+                       (format "%s %s" orig-date orig-time)))
+           (format "%s %s" date time)))))))
+
+(defun di:format-time-range (start end &optional omit-start-date)
+  "Format a time range for the diary.
+
+START and END should be `icalendar-date-time' values where the date part
+is the same.  (If they are not on the same date, nil is returned; use
+`diary-icalendar-format-time-block-sexp' to make a diary S-exp for this
+range instead.)
+
+The date is only formatted once, and the time is formatted as a range, like:
+  STARTDATE STARTTIME-ENDTIME
+If OMIT-START-DATE is non-nil, STARTDATE will be omitted."
+  (when (equal (ical:date/time-to-date start) (ical:date/time-to-date end))
+    (format "%s%s-%s"
+            (if omit-start-date ""
+              (concat (di:format-date start) " "))
+            (di:format-time-as-local start)
+            (di:format-time-as-local end))))
+
+(defun di:format-block-sexp (start end)
+  "Format a `diary-block' diary S-expression between START and END.
+
+START and END may be `icalendar-date' or `icalendar-date-time'
+values.  If they are date-times, only the date parts will be considered.
+Returns a string like \"%%(diary-block ...)\" with the arguments properly
+ordered for the current value of `calendar-date-style'."
+  (unless (cl-typep start 'ical:date)
+    (setq start (ical:date-time-to-date start)))
+  (unless (cl-typep end 'ical:date)
+    (setq end (ical:date-time-to-date end)))
+  (concat
+   diary-sexp-entry-symbol
+   (apply #'format "(diary-block %d %d %d %d %d %d)"
+          (cl-case calendar-date-style
+            ;; M/D/Y
+            (american (list (calendar-extract-month start)
+                            (calendar-extract-day start)
+                            (calendar-extract-year start)
+                            (calendar-extract-month end)
+                            (calendar-extract-day end)
+                            (calendar-extract-year end)))
+            ;; D/M/Y
+            (european (list (calendar-extract-day start)
+                            (calendar-extract-month start)
+                            (calendar-extract-year start)
+                            (calendar-extract-day end)
+                            (calendar-extract-month end)
+                            (calendar-extract-year end)))
+            ;; Y/M/D
+            (iso      (list (calendar-extract-year start)
+                            (calendar-extract-month start)
+                            (calendar-extract-day start)
+                            (calendar-extract-year end)
+                            (calendar-extract-month end)
+                            (calendar-extract-day end)))))))
+
+(defun di:format-time-block-sexp (start end)
+  "Format a `diary-time-block' diary S-expression for times between START and END."
+  (concat
+   diary-sexp-entry-symbol
+   (format "(diary-time-block :start '%s :end '%s)" start end)))
+
+(defun di:format-rrule-sexp (component)
+  "Format the recurrence rule data in COMPONENT as a diary S-expression.
+
+The returned string looks like \"%%(diary-rrule ...)\", and contains the
+necessary data from COMPONENT for the calendar to compute recurrences of
+the event."
+  (ical:with-component component
+      ((ical:dtstart :value dtstart)
+       (ical:dtend :value dtend)
+       (ical:duration :value duration)
+       (ical:rrule :value rrule)
+       (ical:rdate :all rdate-nodes)
+       (ical:exdate :all exdate-nodes))
+    (unless (or rrule rdate-nodes)
+      (di:signal-import-error "No recurrence data in component"))
+    (let ((exdates
+           (mapcar #'ical:ast-node-value
+                   (apply #'append
+                          (mapcar #'ical:ast-node-value exdate-nodes))))
+          (rdates
+           (mapcar #'ical:ast-node-value
+                   (apply #'append
+                          (mapcar #'ical:ast-node-value rdate-nodes))))
+          ;; N.B. we intentionally *don't* add any clock times to the
+          ;; imported diary entry, since they could conflict with the
+          ;; times generated by the recurrence rule, e.g. if the rule is
+          ;; an 'HOURLY rule.  Instead we always specify the end time
+          ;; (if any) via a duration, and take care of displaying the
+          ;; correct clocks times after computing recurrences during
+          ;; diary display (see `diary-rrule').
+          (dur-value (cond (duration duration)
+                           (dtend (unless (equal dtstart dtend)
+                                    (ical:duration-between dtstart dtend)))
+                           (t nil)))
+          (arg-plist nil))
+
+      (when exdates
+        (setq arg-plist (plist-put arg-plist :exclude `(quote ,exdates))))
+      (when rdates
+        (setq arg-plist (plist-put arg-plist :include `(quote ,rdates))))
+      (when dtstart
+        (setq arg-plist (plist-put arg-plist :start `(quote ,dtstart))))
+      (when dur-value
+        (setq arg-plist (plist-put arg-plist :duration `(quote ,dur-value))))
+      (when rrule
+        ;; TODO: make this prettier to look at?
+        (setq arg-plist (append (list :rule `(quote ,rrule)) arg-plist)))
+      ;; TODO: timezones??
+
+      (setq arg-plist (cons 'diary-rrule arg-plist))
+      (string-trim ; removing trailing \n added by pp
+       (concat diary-sexp-entry-symbol
+               (with-output-to-string (pp arg-plist)))))))
+
+;; This function puts all of the above together to format individual
+;; iCalendar components as diary entries.  The final formatting is done
+;; by the appropriate skeleton command for the component, or by
+;; `di:-format-vevent-legacy' if the legacy format string variables from
+;; icalendar.el are set.
+(defun di:format-entry (component index &optional nonmarking)
+  "Format an iCalendar component for the diary.
+
+COMPONENT should be an `icalendar-vevent', `icalendar-vtodo', or
+`icalendar-vjournal'.  INDEX should be an index into the calendar where
+COMPONENT occurs, as returned by `icalendar-parse-and-index'.
+
+Depending on the type of COMPONENT, the body will be formatted by one of:
+`diary-icalendar-vevent-format-function'
+`diary-icalendar-vtodo-format-function'
+`diary-icalendar-vjournal-format-function'
+which see.
+
+The variable `ical-nonmarking' will be bound to the value of NONMARKING in
+the relevant skeleton command.  If it is non-nil, the user requested the
+entry to be nonmarking.
+
+Returns a string containing the diary entry."
+  (ical:with-component component
+      ((ical:attach :all attach-nodes)
+       (ical:attendee :all attendee-nodes)
+       (ical:categories :all categories-nodes)
+       (ical:class :value access)
+       (ical:comment :all comment-nodes)
+       (ical:completed :value completed-dt)
+       (ical:contact :all contact-nodes)
+       (ical:description :value description)
+       ;; in `icalendar-vjournal', multiple `icalendar-description'
+       ;; nodes are allowed:
+       (ical:description :all description-nodes)
+       (ical:dtend :first dtend-node :value dtend)
+       (ical:dtstart :first dtstart-node :value dtstart)
+       (ical:duration :value duration)
+       (ical:due :first due-node :value due-dt)
+       (ical:geo :value geo)
+       (ical:location :value location)
+       (ical:organizer :first organizer-node  ; for skeleton formatting
+                       :value organizer-addr) ; for legacy formatting
+       (ical:percent-complete :value percent-complete)
+       (ical:priority :value priority)
+       (ical:rrule :value rrule)
+       (ical:rdate :all rdate-nodes)
+       (ical:status :value status)
+       (ical:summary :value summary)
+       (ical:transp :value transp)
+       (ical:uid :value uid)
+       (ical:url :value url))
+    (let* ((is-recurring (or rdate-nodes rrule))
+           (start-tz (when dtstart-node
+                       (ical:with-property dtstart-node
+                         ((ical:tzidparam :value tzid))
+                         (when tzid (ical:index-get index :tzid tzid)))))
+           (start-tzname (when start-tz (icr:tzname-on dtstart start-tz)))
+           (dtstart-local (ical:date/time-to-local dtstart))
+           (due-tz (when due-node
+                     (ical:with-property due-node
+                       ((ical:tzidparam :value tzid))
+                       (when tzid (ical:index-get index :tzid tzid)))))
+           (due-tzname (when due-tz (icr:tzname-on due-dt due-tz)))
+           (dtend
+            (cond (dtend dtend)
+                  ;; DTEND and DUE never occur in the same component,
+                  ;; so we alias dtend to due:
+                  (due-dt due-dt)
+                  (duration
+                   (ical:date/time-add-duration dtstart duration start-tz))))
+           (dtend-local (ical:date/time-to-local dtend))
+           (end-tz
+            (cond (dtend-node
+                   (ical:with-property dtend-node
+                     ((ical:tzidparam :value tzid))
+                     (when tzid (ical:index-get index :tzid tzid))))
+                  (due-node due-tz)
+                  (duration start-tz)))
+           (end-tzname (when end-tz (icr:tzname-on dtend end-tz)))
+           (component-type (ical:ast-node-type component)))
+      (dlet
+          ;; We use "ical-" rather than "icalendar-" as prefix for these
+          ;; vars because (a) it's shorter and (b) to avoid shadowing
+          ;; any library symbols:
+          ((ical-attachments
+            (when attach-nodes
+              (di:save-attachments-from attach-nodes uid)))
+           (ical-attendees (mapcar #'di:format-attendee attendee-nodes))
+           (ical-categories
+            (mapcan
+             (lambda (node)
+               (mapcar #'ical:text-to-string (ical:ast-node-value node)))
+             categories-nodes))
+           (ical-access (when access (downcase access)))
+           (ical-comments
+            (mapcar
+             (lambda (node) (ical:text-to-string (ical:ast-node-value node)))
+             comment-nodes))
+           (ical-contacts
+            (mapcar
+             (lambda (node) (ical:text-to-string (ical:ast-node-value node)))
+             contact-nodes))
+           (ical-completed
+            (when completed-dt (di:format-date/time-as-local completed-dt)))
+           (ical-description
+            (if (eq 'icalendar-vjournal component-type)
+              (mapconcat
+               (lambda (node)
+                 (ical:trimp (ical:text-to-string (ical:ast-node-value node))))
+               description-nodes
+               "\n\n")
+              (ical:trimp description)))
+           (ical-start
+            (when dtstart
+              (if (bound-and-true-p ical-importing)
+                  (di:format-date/time-as-local dtstart start-tzname)
+                (di:format-time-as-local dtstart start-tzname))))
+           (ical-end
+            (when dtend
+              (if (bound-and-true-p ical-importing)
+                  (di:format-date/time-as-local dtend end-tzname)
+                (di:format-time-as-local dtend end-tzname))))
+           (ical-start-to-end
+            (with-suppressed-warnings ((lexical date) (free-vars date))
+              (cond
+               ((not dtstart) nil)
+               ((or (not dtend) (equal dtstart dtend))
+                ;; without a distinct DTEND/DUE, same as start:
+                (if (bound-and-true-p ical-importing)
+                    (di:format-date/time-as-local dtstart start-tzname)
+                  (di:format-time-as-local dtstart start-tzname)))
+               ((and (bound-and-true-p ical-importing)
+                     (cl-typep dtstart 'ical:date)
+                     (cl-typep dtend 'ical:date))
+                ;; Importing two dates:
+                ;; %%(diary-block ...)
+                (di:format-block-sexp
+                 dtstart
+                 ;; DTEND is an exclusive bound, while
+                 ;; diary-block needs an inclusive bound, so
+                 ;; subtract a day:
+                 (ical:date-add dtend :day -1)))
+               ((and (bound-and-true-p ical-importing)
+                     (equal (ical:date/time-to-date dtstart-local)
+                            (ical:date/time-to-date dtend-local)))
+                ;; Importing, start and end times on same day:
+                ;; DATE HH:MM-HH:MM
+                (di:format-time-range dtstart-local dtend-local))
+               ((bound-and-true-p ical-importing)
+                ;; Importing at least one date-time, on different days:
+                ;; %%(diary-time-block :start ... :end ...)
+                (di:format-time-block-sexp dtstart-local dtend-local))
+               ((and (boundp 'date) ; bound when displaying diary
+                     (cl-typep dtstart-local 'ical:date-time)
+                     (cl-typep dtend-local 'ical:date-time)
+                     (equal date (ical:date-time-to-date dtstart-local))
+                     (equal date (ical:date-time-to-date dtend-local)))
+                ;; Displaying, start and end times on the day displayed:
+                ;; HH:MM-HH:MM
+                (di:format-time-range dtstart-local dtend-local t))
+               ((and (boundp 'date) ; bound when displaying diary
+                     (cl-typep dtstart-local 'ical:date-time)
+                     (cl-typep dtend-local 'ical:date-time))
+                ;; Displaying, start and/or end time on other days:
+                ;; HH:MM-HH:MM for just the times on `date'
+                (di:format-time-range
+                 (ical:date/time-max dtstart-local
+                                     (ical:make-date-time
+                                      :year (calendar-extract-year date)
+                                      :month (calendar-extract-month date)
+                                      :day (calendar-extract-day date)
+                                      :hour 0 :minute 0 :second 0
+                                      :zone
+                                      (decoded-time-zone dtstart-local)))
+                 (ical:date/time-min dtend-local
+                                     (ical:make-date-time
+                                      :year (calendar-extract-year date)
+                                      :month (calendar-extract-month date)
+                                      :day (calendar-extract-day date)
+                                      :hour 23 :minute 59 :second 59
+                                      :zone
+                                      (decoded-time-zone dtend-local)))))
+               (t
+                ;; That's all the cases we care about here.
+                nil))))
+           (ical-due
+            (when (eq component-type 'ical:vtodo)
+              (if due-node
+                  (di:format-date/time-as-local due-dt due-tzname)
+                ;; here we use start-tzname because due/dtend is calculated from
+                ;; dtstart, not its own node with a tzid:
+                (di:format-date/time-as-local dtend start-tzname))))
+           (ical-work-time-sexp
+            (when (and dtstart due-dt (bound-and-true-p ical-importing))
+              (di:format-time-block-sexp dtstart-local due-dt)))
+           (ical-importing (bound-and-true-p ical-importing))
+           (ical-location (or (ical:trimp location)
+                              (when geo (di:format-geo-coordinates geo))))
+           (ical-nonmarking nonmarking)
+           (ical-organizer (di:format-attendee organizer-node))
+           (ical-percent-complete percent-complete)
+           (ical-priority priority)
+           (ical-rrule-sexp
+            (when (and is-recurring (bound-and-true-p ical-importing))
+              (di:format-rrule-sexp component)))
+           (ical-status (when status (ical:trimp (downcase status))))
+           (ical-summary (ical:trimp summary))
+           (ical-transparency transp)
+           (ical-uid (ical:trimp uid))
+           (ical-url (ical:trimp url)))
+        (with-temp-buffer
+          (cl-case (ical:ast-node-type component)
+            (ical:vevent
+             (with-suppressed-warnings
+                 ((obsolete ical:import-format
+                            di:-use-legacy-vars-p
+                            di:-vevent-to-legacy-alist
+                            di:-format-vevent-legacy))
+               ;; N.B. icalendar.el *only* imported VEVENT components
+               (if (di:-use-legacy-vars-p)
+                   (if (functionp ical:import-format)
+                       (insert (funcall ical:import-format
+                                        (di:-vevent-to-legacy-alist component)))
+                     (di:-format-vevent-legacy (or ical-rrule-sexp
+                                                   ical-start-to-end
+                                                   ical-start)
+                                               ical-access ical-description
+                                               ical-location organizer-addr
+                                               ical-summary ical-status
+                                               ical-url ical-uid))
+                 (funcall di:vevent-format-function component))))
+            (ical:vtodo (funcall di:vtodo-format-function component))
+            (ical:vjournal (funcall di:vjournal-format-function component)))
+          (buffer-string))))))
+
+
+;; Import to Diary
+;;
+;; `di:import-file' and `di:import-buffer' are the main user commands
+;; for import.  (These replace `icalendar-import-file' and
+;; `icalendar-import-buffer' defined by icalendar.el, which are now
+;; obsolete aliases to these commands.) `di:import-buffer-to-buffer' is
+;; the function underlying these commands; it is the main import
+;; function available for external Lisp code.
+
+;; `di:import-buffer-to-buffer' is the underlying function that formats
+;; a complete `icalendar-vcalendar' as diary entries.  This function runs
+;; `di:post-entry-format-hook' after formatting each component as an
+;; entry, and it runs `di:post-calendar-format-hook' after all entries
+;; have been formatted.  These hooks enable e.g. user review and
+;; confirmation of each imported entry and of the whole imported
+;; calendar.
+(defvar di:post-entry-format-hook nil
+  "Hook run after formatting a single iCalendar component as a diary entry.
+
+The functions in this hook are run by `diary-icalendar-import-buffer-to-buffer'
+\(which see) after each component it formats.  Each function will be
+called in a (narrowed) buffer whose contents represent a single diary
+entry.")
+
+(defvar di:post-calendar-format-hook nil
+  "Hook run after formatting a complete `icalendar-vcalendar' as diary entries.
+
+The functions in this hook are run by `diary-icalendar-import-buffer-to-buffer'
+\(which see) after formatting all the diary entries created from the
+calendar.  Each function will be called in a buffer containing all the
+diary entries.")
+
+(defun di:sort-by-start-ascending (c1 c2)
+  "Sort iCalendar component C1 before C2 if C1 starts strictly before C2.
+Components with no start date/time are sorted after components that do."
+  (let ((c1start (ical:with-property-of c1 'ical:dtstart nil value))
+        (c2start (ical:with-property-of c2 'ical:dtstart nil value)))
+    (cond ((and c1start c2start)
+           (ical:date/time< c1start c2start))
+          ;; order anything with a start before anything without:
+          (c1start t)
+          (c2start nil)
+          ;; otherwise they can stay as-is:
+          (t t))))
+
+(defcustom di:import-comparison-function #'di:sort-by-start-ascending
+  "Comparison function for sorting imported iCalendar components.
+See the :lessp argument of `sort' for more information."
+  :version "31.1"
+  :type '(radio (function-item di:sort-by-start-ascending)
+                (function :tag "Other comparison function")))
+
+(defun di:import-buffer-to-buffer (&optional all-nonmarking)
+  "Format iCalendar data in current buffer as diary entries.
+
+This function parses the first iCalendar VCALENDAR in the current buffer
+and formats its VEVENT, VJOURNAL, and VTODO components as diary entries.
+It returns a new buffer containing those diary entries.  The caller
+should kill this buffer when it is no longer needed.
+
+If ALL-NONMARKING is non-nil, all diary entries will be non-marking.
+
+The list of components to import can be filtered by binding
+`diary-icalendar-import-predicate'.  After each component is formatted as
+a diary entry, `diary-icalendar-post-entry-format-hook' is run in a (narrowed)
+buffer containing that entry.  After all components have been formatted,
+`diary-icalendar-post-calendar-format-hook' is run in the (widened) buffer
+containing all the entries.
+
+The formatting of imported entries depends on a number of
+user-customizable variables, including: `diary-date-forms',
+`calendar-date-style', `calendar-date-display-form' and customizations
+in the `diary-icalendar' group."
+  (unless (ical:contains-vcalendar-p (current-buffer))
+    (di:signal-import-error (format "No VCALENDAR object in buffer %s"
+                                    (buffer-name))))
+  (save-excursion
+    (goto-char (point-min))
+    (let (vcalendar index)
+      (ical:init-error-buffer)
+      (let ((vcal/idx (ical:parse-and-index (current-buffer))))
+        (when vcal/idx
+          (setq vcalendar (car vcal/idx))
+          (setq index (cadr vcal/idx))
+          (let* ((import-buf (generate-new-buffer " *diary-import*"))
+                 (to-import
+                  (sort
+                   (seq-filter
+                    (lambda (c)
+                      (and (or (ical:vevent-component-p c)
+                               (ical:vjournal-component-p c)
+                               (ical:vtodo-component-p c))
+                           (funcall di:import-predicate c)))
+                    (ical:ast-node-children vcalendar))
+                  :lessp di:import-comparison-function
+                  :in-place t))
+                 ;; prevent point from being reset from window-point
+                 ;; when narrowed buffer is displayed for confirmation:
+                 (window-point-insertion-type t)
+                 ;; position at start of each entry:
+                 entry-start)
+
+            (with-current-buffer import-buf
+              (dlet ((ical-importing t)) ; inform skeletons we're importing
+                (dolist (component to-import)
+                  (setq entry-start (point))
+                  (insert (di:format-entry component index all-nonmarking))
+                  (with-restriction entry-start (point)
+                    (save-excursion
+                      (run-hooks 'di:post-entry-format-hook)))
+                  (unless (bolp) (insert "\n"))))
+              (save-excursion
+                (run-hooks 'di:post-calendar-format-hook))
+              import-buf)))))))
+
+;; Internal variables needed by `di:-entry-import'.  They are dynamically
+;; bound in `di:import-buffer'.
+(defvar di:-no-queries nil)
+(defvar di:-entry-count nil)
+
+(defun di:-entry-import ()
+  ;; Adds the formatted entry in the current restriction to the diary,
+  ;; after getting confirmation from the user.
+  ;; Used via `di:post-entry-format-hook' in `di:import-buffer', below.
+  (unless di:-no-queries
+    (display-buffer (current-buffer)))
+  (when (or di:-no-queries
+            (let ((help-form
+                   "Type y to add this entry to the diary, n to skip to next."))
+              (di:y-or-n-or-edit-p "Add this entry to the diary?")))
+    (ical:condition-case err
+       (let* ((uid (save-excursion
+                     (goto-char (point-min))
+                     (when (re-search-forward di:uid-regexp nil t)
+                       (match-string 1))))
+              (other-entry (di:find-entry-with-uid uid))
+              (entry (buffer-string)))
+         (if (and other-entry
+                  (not di:-no-queries)
+                  (y-or-n-p "Replace existing entry with same UID?"))
+             (with-current-buffer (marker-buffer (car other-entry))
+               (replace-region-contents
+                (car other-entry) (cadr other-entry) entry))
+           ;; Otherwise, diary-make-entry inserts the new entry at the end
+           ;; of the main diary file:
+           (diary-make-entry
+            entry
+            nil ; skeleton has already interpreted nonmarking
+            nil ; use dynamic value of `diary-file'
+            t   ; skeleton responsible for final spaces
+            t))  ; no need to show diary file while importing
+         (when other-entry
+           (set-marker (car other-entry) nil)
+           (set-marker (cadr other-entry) nil))
+         (cl-incf di:-entry-count)))))
+
+;;;###autoload
+(defun di:import-buffer (&optional diary-filename quietly all-nonmarking)
+  "Import iCalendar events from current buffer into diary.
+
+This function parses the first iCalendar VCALENDAR in the current buffer
+and imports VEVENT, VJOURNAL, and VTODO components to the diary file
+DIARY-FILENAME (default: `diary-file').
+
+For each entry, you are asked whether to add it to the diary unless
+QUIETLY is non-nil.  After all entries are imported, you are also asked
+if you want to save the diary file unless QUIETLY is non-nil.  When
+called interactively, you are asked if you want to confirm each entry
+individually; answer No to make QUIETLY non-nil.
+
+ALL-NONMARKING determines whether all diary events are created as
+non-marking entries.  When called interactively, you are asked whether
+you want to make all entries non-marking.
+
+The formatting of imported entries in the diary depends on a number of
+user-customizable variables.  Before running this command for the first
+time, you may especially wish to check the values of:
+`diary-file'
+`diary-date-forms'
+`diary-date-insertion-form'
+`calendar-date-style'
+`calendar-date-display-form'
+as well as variables in the customization group `diary-icalendar-import'."
+  (interactive
+   (list (read-file-name "Diary file: "
+                         (when diary-file (file-name-directory diary-file))
+                         (cons diary-file diary-included-files))
+         (or di:always-import-quietly
+             (not (y-or-n-p "Confirm entries individually?")))
+         (y-or-n-p "Make all entries non-marking?")))
+
+  (let* ((diary-file diary-filename) ; dynamically bound for `di:-entry-import',
+         (di:-entry-count 0)         ; see above
+         (di:-no-queries quietly)    ;
+         (di:post-entry-format-hook
+          (append di:post-entry-format-hook (list #'di:-entry-import)))
+         (diary-buffer (or (find-buffer-visiting diary-filename)
+                           (find-file-noselect diary-filename)))
+         import-buffer)
+    (unwind-protect
+        (setq import-buffer (di:import-buffer-to-buffer all-nonmarking))
+      (when (bufferp import-buffer)
+        (kill-buffer import-buffer)))
+    (display-buffer diary-buffer)
+    (when (or quietly
+              (y-or-n-p (format "%d entries imported.  Save diary file?"
+                                di:-entry-count)))
+      (with-current-buffer diary-buffer
+        (goto-char (point-max))
+        (save-buffer)))))
+
+;;;###autoload
+(defun di:import-file (filename &optional diary-filename quietly nonmarking)
+  "Import iCalendar diary entries from FILENAME into DIARY-FILENAME.
+
+This function parses the first iCalendar VCALENDAR in FILENAME and
+imports VEVENT, VJOURNAL, and VTODO components to the diary
+DIARY-FILENAME (default: `diary-file').
+
+For each entry, you are asked whether to add it to the diary unless
+QUIETLY is non-nil.  After all entries are imported, you are also asked
+if you want to save the diary file unless QUIETLY is non-nil.  When
+called interactively, you are asked if you want to confirm each entry
+individually; answer No to make QUIETLY non-nil.
+
+NONMARKING determines whether all diary events are created as
+non-marking entries.  When called interactively, you are asked whether
+you want to make all entries non-marking.
+
+The formatting of imported entries in the diary depends on a number of
+user-customizable variables.  Before running this command for the first
+time, you may especially wish to check the values of:
+`diary-file'
+`diary-date-forms'
+`diary-date-insertion-form'
+`calendar-date-style'
+`calendar-date-display-form'
+as well as variables in the customization group `diary-icalendar-import'."
+  (interactive
+   (list (read-file-name "iCalendar file: " nil nil 'confirm)
+         (read-file-name "Diary file: "
+                         (when diary-file (file-name-directory diary-file))
+                         (cons diary-file diary-included-files))
+         (or di:always-import-quietly
+             (not (y-or-n-p "Confirm entries individually?")))
+         (y-or-n-p "Make all entries non-marking?")))
+  (let ((parse-buf (ical:find-unfolded-buffer-visiting filename)))
+    (unless parse-buf
+      (ical:condition-case err
+        (setq parse-buf
+              (ical:unfolded-buffer-from-file (expand-file-name filename)))))
+    ;; Hand off to `di:import-buffer' for the actual import:
+    (if parse-buf
+        (with-current-buffer parse-buf
+          (di:import-buffer diary-filename quietly nonmarking))
+      ;; If we get here, we weren't able to open the file for parsing:
+      (warn "Unable to open file %s; see %s"
+            filename (buffer-name (ical:error-buffer))))))
+
+;; Some simple support for viewing iCalendar data in MIME message
+;; parts.  Mail readers may want to build their own viewer using the
+;; import functions above, but this is a good starting point:
+(defun di:mailcap-viewer ()
+  "View iCalendar data in the current message part as diary entries.
+
+This function is a suitable viewer for text/calendar parts in MIME
+messages, such as email attachments.  To use this function as a viewer,
+customize the variable `mailcap-user-mime-data' and add an entry
+containing this function for the MIME type \"text/calendar\".
+
+To extend the behavior of this function, see
+`diary-icalendar-after-mailcap-viewer-hook'."
+  (let ((entries-buf (diary-icalendar-import-buffer-to-buffer)))
+    (unwind-protect
+        (progn
+          ;; Since this is already a temporary viewer buffer, we replace
+          ;; its contents with the imported entries, so we can (a) keep
+          ;; the window configuration setup by the calling mailcap code
+          ;; and (b) already kill the import buffer here.
+          (erase-buffer)
+          (insert-buffer-substring entries-buf)
+          (diary-mode)
+          (run-hooks di:after-mailcap-viewer-hook))
+      (kill-buffer entries-buf))))
+
+
+;; Export
+
+;;; Error handling
+(define-error 'ical:diary-export-error "Unable to export diary data" 'ical:error)
+
+(cl-defun di:signal-export-error (msg &key (diary-buffer (current-buffer))
+                                           (position (point))
+                                           line
+                                           (severity 2))
+  (let ((err-data
+          (list :message msg
+                :buffer diary-buffer
+                :position position
+                :line line
+                :severity severity)))
+    (signal 'ical:diary-export-error err-data)))
+
+;;; Export utility functions
+(defun di:parse-attendees-and-organizer ()
+  "Parse `icalendar-attendee' and `icalendar-organizer' nodes from entry.
+
+Searches the entry in the current restriction for addresses matching
+`diary-icalendar-address-regexp'.  If an address is found on a
+line that also matches `diary-icalendar-organizer-regexp', it will be
+parsed as an `icalendar-organizer' node, or otherwise as an
+`icalendar-attendee'.  Returns the list of nodes for all addresses found."
+  (goto-char (point-min))
+  (let (attendees organizer)
+    (while (re-search-forward di:address-regexp nil t)
+      (let ((addr (match-string 1))
+            (cn (match-string 2)))
+        (unless (string-match ":" addr) ; URI scheme already present
+          (setq addr (concat "mailto:" addr)))
+        (when cn
+          (setq cn (ical:trimp cn)))
+        (if (string-match di:organizer-regexp
+                          (buffer-substring (line-beginning-position)
+                                            (line-end-position)))
+            (setq organizer
+                  (ical:make-property ical:organizer addr (ical:cnparam cn)))
+          (push (ical:make-property ical:attendee addr (ical:cnparam cn))
+                attendees))))
+    (if organizer
+        (cons organizer attendees)
+      attendees)))
+
+(defun di:parse-location ()
+  "Parse `icalendar-location' node from entry.
+
+Searches the entry in the current restriction for a location matching
+`diary-icalendar-location-regexp'.  If a location is found, it will be
+parsed as an `icalendar-location' node.  Returns a list containing just
+this node, or nil."
+  (goto-char (point-min))
+  (when (and di:location-regexp
+             (re-search-forward di:location-regexp nil t))
+    (ical:make-property ical:location (ical:trimp (match-string 1)))))
+
+(defun di:parse-class ()
+  "Parse `icalendar-class' node from entry.
+
+Searches the entry in the current restriction for an access
+classification matching `diary-icalendar-class-regexp'.  If a
+classification is found, it will be parsed as an `icalendar-class'
+node.  Return this node, or nil."
+  (goto-char (point-min))
+  (when (and di:class-regexp
+             (re-search-forward di:class-regexp nil t))
+    (ical:make-property ical:class
+        (upcase (string-trim (match-string 1))))))
+
+(defun di:parse-status ()
+  "Parse `icalendar-status' node from entry.
+
+Searches the entry in the current restriction for a status matching
+`diary-icalendar-status-regexp'.  If a status is found, it will be parsed
+as an `icalendar-status' node.  Return this node, or nil."
+  (goto-char (point-min))
+  (when (and di:status-regexp
+             (re-search-forward di:status-regexp nil t))
+    (ical:make-property ical:status
+        (upcase (string-trim (match-string 1))))))
+
+(defun di:parse-url ()
+  "Parse `icalendar-url' node from entry.
+
+Searches the entry in the current restriction for an URL matching
+`diary-icalendar-url-regexp'.  If an URL is found, it will be parsed as an
+`icalendar-url' node.  Return this node, or nil."
+  (goto-char (point-min))
+  (when (and di:url-regexp
+             (re-search-forward di:url-regexp nil t))
+    (ical:make-property ical:url (ical:trimp (match-string 1)))))
+
+(defun di:parse-uid ()
+  "Parse `icalendar-uid' node from entry.
+
+Searches the entry in the current restriction for a UID matching
+`diary-icalendar-uid-regexp'.  If a UID is found, it will be parsed as an
+`icalendar-uid' node.  Return this node, or nil."
+  (goto-char (point-min))
+  (when (and di:uid-regexp
+             (re-search-forward di:uid-regexp nil t))
+    (ical:make-property ical:uid (ical:trimp (match-string 1)))))
+
+(defun di:parse-summary-and-description ()
+  "Parse summary and description nodes from current restriction.
+
+When `diary-icalendar-summary-regexp' or
+`diary-icalendar-description-regexp' are non-nil, and the entry matches
+them, the matches will be used to generate the summary and description.
+
+Otherwise, the first line of the entry (after any nonmarking symbol and
+date and time specification) is used as the summary.  The description is
+the full body of the entry, excluding the nonmarking symbol, date and
+time, but including the summary.
+
+Returns a list containing an `icalendar-summary' node and
+`icalendar-description' node, or nil."
+  (goto-char (point-min))
+  (let (summary description)
+    (when (and di:summary-regexp
+               (re-search-forward di:summary-regexp nil t))
+      (setq summary (match-string 1)))
+    (goto-char (point-min))
+    (when (and di:description-regexp
+               (re-search-forward di:description-regexp nil t))
+      (setq description (match-string 1)))
+    ;; Fall back to using first line and entire entry:
+    (goto-char (point-min))
+    (while (looking-at-p "[[:space:]]")
+      (forward-char))
+    (unless summary
+      (setq summary (buffer-substring (point) (line-end-position))))
+    (unless description
+      (setq description (buffer-substring (point) (point-max))))
+    ;; Remove any indentation on subsequent lines from description:
+    (setq description (replace-regexp-in-string "^[[:space:]]+" "" description))
+
+    (list (ical:make-property ical:summary summary)
+          (ical:make-property ical:description description))))
+
+(defun di:parse-entry-type ()
+  "Return the type symbol for the component type used to export an entry.
+
+Default is `icalendar-vevent'.  If the entry is nonmarking and
+`diary-icalendar-export-nonmarking-as-vjournal' is non-nil,
+`icalendar-vjournal' is returned.  If `diary-icalendar-todo-regexp' is
+non-nil and the entry matches it, `icalendar-vtodo' is returned.
+
+If the entry is nonmarking and `diary-icalendar-export-nonmarking-entries'
+is nil, nil is returned, indicating that the entry should not be
+exported."
+  (let (type)
+    (goto-char (point-min))
+    (unless (and (looking-at-p diary-nonmarking-symbol)
+                 (not di:export-nonmarking-entries))
+      (setq type 'ical:vevent)
+      (when (and (looking-at-p diary-nonmarking-symbol)
+                 di:export-nonmarking-as-vjournal)
+        (setq type 'ical:vjournal))
+      (when (and di:todo-regexp (re-search-forward di:todo-regexp nil t))
+        (setq type 'ical:vtodo)))
+    type))
+
+(defun di:parse-transparency (type)
+  "Return the iCalendar time transparency of an entry.
+
+TYPE should be the type symbol for the component to be exported, as
+returned by `diary-icalendar-parse-entry-type'.  If the entry is
+non-marking (i.e., begins with `diary-nonmarking-symbol'), and it is to
+be exported as an `icalendar-vevent' (according to TYPE), then this
+function returns a list containing the appropriate `icalendar-transp'
+property node to mark the event as transparent, and moves the current
+restriction past the non-marking symbol.  Otherwise it returns nil."
+  (save-excursion
+    (goto-char (point-min))
+    (when (and (eq type 'ical:vevent)
+               (re-search-forward (concat "^" diary-nonmarking-symbol)
+                                  (line-end-position) t))
+      (narrow-to-region (point) (point-max))
+      (list
+       (ical:make-property ical:transp "TRANSPARENT")))))
+
+;; TODO: move to diary-lib?
+(defun di:parse-date-form ()
+  "Parse a date matching `diary-date-forms' on the current line.
+
+If a date is found, moves the current restriction past the end of the
+date and returns a list (MONTH DAY YEAR), where each value is an integer
+or t if the date is generic in that unit.  Otherwise returns nil."
+  (goto-char (point-min))
+  (catch 'date
+    (let (date-regexp backup)
+      (dolist (date-sexp diary-date-forms)
+        (when (eq 'backup (car date-sexp))
+          (setq date-sexp (cdr date-sexp))
+          (setq backup t))
+        (setq date-regexp (di:date-form-to-regexp date-sexp))
+        (when backup (beginning-of-line))
+        (when (let ((case-fold-search t))
+                (re-search-forward date-regexp nil t))
+          (let ((year
+                 (let ((match (match-string 1)))
+                   (if (or (null match) (equal match "*"))
+                       t
+                     (if (and diary-abbreviated-year-flag (length= match 2))
+                         ;; from diary-lib.el:
+                         ;; Add 2-digit year to current century.
+                         ;; If more than 50 years in the future,
+                         ;; assume last century.  If more than 50
+                         ;; years in the past, assume next century.
+                         (let* ((current-y
+                                 (calendar-extract-year (calendar-current-date)))
+                                (y (+ (string-to-number match)
+                                      ;; Current century, eg 2000.
+                                      (* 100 (/ current-y 100))))
+                                (offset (- y current-y)))
+                           (cond ((> offset 50)
+                                  (- y 100))
+                                 ((< offset -50)
+                                  (+ y 100))
+                                 (t y)))
+                       (string-to-number match)))))
+                (month
+                 (let ((month-num (match-string 2))
+                       (month-name (match-string 4)))
+                   (cond ((or (equal month-name "*") (equal month-num "*")) t)
+                         (month-num (string-to-number month-num))
+                         (month-name
+                          (alist-get
+                           (capitalize month-name)
+                           (calendar-make-alist
+                            calendar-month-name-array
+                            1 nil
+                            calendar-month-abbrev-array
+                            (mapcar (lambda (e) (format "%s." e))
+                                    calendar-month-abbrev-array))
+                           nil nil #'equal)))))
+                (day
+                 (let ((day-num (match-string 3))
+                       (day-name (match-string 5)))
+                   (cond
+                    ;; We don't care about the day name here, unless it
+                    ;; is "*", since it won't help us identify a day of
+                    ;; the month.  Weekly entries under a weekday name
+                    ;; are parsed by `di:parse-weekday-name', below.
+                    ((or (equal day-name "*") (equal day-num "*")) t)
+                    (day-num (string-to-number day-num))))))
+            (when (and year month day)
+              (narrow-to-region (match-end 0) (point-max))
+              (throw 'date (list month day year)))))))))
+
+(defun di:date-form-to-regexp (date-sexp)
+  "Convert DATE-SEXP to a regular expression.
+
+DATE-SEXP should be an S-expression in the variables `year', `month',
+`day', `monthname', and `dayname', as found e.g. in `diary-date-forms'.
+The returned regular expression matches dates of this form, including
+generic dates specified with \"*\", and abbreviated and long-form month
+and day names (based on `calendar-month-name-array' and
+`calendar-month-abbrev-array', and similarly for day names).  The match
+groups contain the following data:
+
+Group 1: the 2-4 digit year, or a literal *
+Group 2: the 1-2 digit month number, or a literal *
+Group 3: the 1-2 digit day number, or a literal *
+Group 4: the (long-form or abbreviated) month name, or a literal *
+Group 5: the (long-form or abbreviated) day name, or a literal *"
+  (when (eq 'backup (car date-sexp))
+    (setq date-sexp (cdr date-sexp)))
+  (let ((month-names-regexp
+         (rx
+          (group-n 4
+            (or (regexp (diary-name-pattern calendar-month-name-array
+                                            calendar-month-abbrev-array))
+                "*"))))
+        (day-names-regexp
+         (rx
+          (group-n 5
+            (or (regexp (diary-name-pattern calendar-day-name-array
+                                            calendar-day-abbrev-array))
+                "*"))))
+          date-regexp)
+    (calendar-dlet
+        ((prefix (rx line-start
+                     (zero-or-one (regexp diary-nonmarking-symbol))))
+         (year (rx (group-n 1 (or (** 2 4 digit) "*"))))
+         (month (rx (group-n 2 (or (** 1 2 digit) "*"))))
+         (day (rx (group-n 3 (or (** 1 2 digit) "*"))))
+         (monthname month-names-regexp)
+         (dayname day-names-regexp))
+      (setq date-regexp (apply #'concat (cons prefix (mapcar #'eval date-sexp)))))
+  date-regexp))
+
+(defun di:parse-weekday-name ()
+  "Parse a weekday name on the current line.
+
+The day name must appear in `calendar-day-name-array' or
+`calendar-day-abbrev-array'.  If a day name is found, move the current
+restriction past it, and return a day number between 0 (=Sunday) and
+6 (=Saturday).  Otherwise, return nil."
+  (goto-char (point-min))
+  (let ((day-names-regexp
+         (rx line-start
+             (zero-or-one (regexp diary-nonmarking-symbol))
+             (group-n 1
+               (regexp (diary-name-pattern calendar-day-name-array
+                                           calendar-day-abbrev-array))))))
+    (when (re-search-forward day-names-regexp (line-end-position) t)
+      (let ((day-name (capitalize (match-string 1))))
+        (narrow-to-region (match-end 0) (point-max))
+        (alist-get
+         day-name
+         (calendar-make-alist calendar-day-name-array 0 nil
+                              calendar-day-abbrev-array
+                              (mapcar (lambda (e) (format "%s." e))
+                                      calendar-day-abbrev-array))
+         nil nil #'equal)))))
+
+(defun di:weekday-to-recurrence (weekday)
+  "Convert WEEKDAY to a WEEKLY iCalendar recurrence rule.
+
+WEEKDAY must be an integer between 0 (=Sunday) and 6 (=Saturday).
+Returns a list (START RRULE), with START being an `icalendar-dtstart'
+property and RRULE an `icalendar-rrule'."
+  (let ((dtstart (calendar-nth-named-day 1 weekday 1 di:recurring-start-year))
+        (rrule `((FREQ WEEKLY)
+                 (BYDAY (,weekday)))))
+    (list (ical:make-property ical:dtstart dtstart)
+          (ical:make-property ical:rrule rrule))))
+
+;; TODO: give this value to diary-time-regexp?
+(defconst di:time-regexp
+  (rx-let ((hours (or (seq (any "0-2") (any "0-9"))
+                      (any "0-9")))
+           (minutes (seq (any "0-5") (any "0-9")))
+           (am/pm (seq (any "ap") "m"))) ;; am, pm
+    (rx
+     (group-n 1 ;; START
+       (group-n 11 hours) ;; start hour
+       (or
+        ;; 10:00 or 10h00:
+        (seq (or ":" "h") (group-n 12 minutes) (opt (group-n 13 am/pm)))
+        ;; 10.00h or 10.00am: (a bare "10.00" should not match)
+        (seq "." (group-n 12 minutes) (or (group-n 13 am/pm) "h"))
+        ;; 10am
+        (group-n 13 am/pm)
+        ;; 10h
+        "h"))
+     (zero-or-one
+      (one-or-more "-")
+      (group-n 2 ;; END
+        (group-n 21 hours) ;; end hour
+        (or
+         ;; 10:00 or 10h00:
+         (seq (or ":" "h") (group-n 22 minutes) (opt (group-n 23 am/pm)))
+         ;; 10.00h or 10.00am:
+         (seq "." (group-n 22 minutes) (or "h" (group-n 23 am/pm)))
+         ;; 10am
+         (group-n 23 am/pm)
+         ;; 10h
+         "h")))
+     (one-or-more space)))
+  "Regular expression to match diary appointment times.
+
+Accepted time formats look like e.g.:
+  9AM 9:00 09:00 9h 9h00 9.00am 9.00h
+  9PM 9:00pm 21:00 21h00 21.00pm 21.00h
+  9AM-1PM 09:00-13:00
+
+Group 1 matches the start time:
+  Group 11 matches the hours digits
+  Group 12 matches the minutes digits
+  Group 13 matches an AM/PM specification
+
+Group 2 matches the end time:
+  Group 21 matches the hours digits
+  Group 22 matches the minutes digits
+  Group 23 matches an AM/PM specification")
+
+(defun di:parse-time ()
+  "Parse diary time string in the current restriction.
+
+If a time specification is found, move the current restriction past it,
+and return a list (START END), where START and END are decoded-time
+values containing the hours and minutes slots parsed from the time
+specification.  END may be nil if no end time was specified."
+  (goto-char (point-min))
+  (let ((regexp di:time-regexp)
+        (case-fold-search t))
+    (when di:export-linewise
+      ;; In this case, only look for a time following whitespace,
+      ;; at the beginning of a continuation line of the full entry:
+      (setq regexp (concat "^[[:space:]]+" di:time-regexp)))
+
+    (when (re-search-forward regexp (line-end-position) t)
+      (let* ((start-hh (string-to-number (match-string 11)))
+             (start-am/pm (when (match-string 13)
+                            (upcase (match-string 13))))
+             (start-hours (if (and (equal start-am/pm "PM") (< start-hh 12))
+                              (+ 12 start-hh)
+                            start-hh))
+             (start-minutes (string-to-number (or (match-string 12) "0")))
+             (start
+              (when (and start-hours start-minutes)
+                (make-decoded-time :hour start-hours
+                                   :minute start-minutes
+                                   :second 0)))
+             (end-hh (when (match-string 21)
+                       (string-to-number (match-string 21))))
+             (end-am/pm (when (match-string 23)
+                          (upcase (match-string 23))))
+             (end-hours (if (and end-hh (equal end-am/pm "PM") (< end-hh 12))
+                            (+ 12 end-hh)
+                          end-hh))
+             (end-minutes (when end-hours
+                            (string-to-number (or (match-string 22) "0"))))
+             (end (when (and end-hours end-minutes)
+                    (make-decoded-time :hour end-hours
+                                       :minute end-minutes
+                                       :second 0))))
+        (narrow-to-region (match-end 0) (point-max))
+        ;; Return the times:
+        (list start end)))))
+
+(defun di:convert-time-via-strategy (dt &optional vtimezone)
+  "Reinterpret the local time DT per the time zone export strategy.
+
+The export strategy is determined by
+`diary-icalendar-time-zone-export-strategy', which see.
+
+DT may be an `icalendar-date' or `icalendar-date-time'.  If it is a
+date, it is returned unmodified.  If it is a date-time, depending on the
+strategy and any existing zone information in DT, it will be converted
+to a correct local, UTC, or floating time.  VTIMEZONE should be the
+`icalendar-vtimezone' which defines the local time zone, if the time
+zone export strategy requires it."
+  (cl-typecase dt
+    (ical:date dt)
+    (ical:date-time
+     (cond
+       ((or (eq 'local di:time-zone-export-strategy)
+            (listp di:time-zone-export-strategy))
+        (unless (ical:vtimezone-component-p vtimezone)
+          (di:signal-export-error
+           (format
+            "%s time export strategy requires a time zone definition;\n%s"
+            (if (eq 'local di:time-zone-export-strategy) "`local'" "list-based")
+            (concat
+             "check the value of `diary-icalendar-time-zone-export-strategy'\n"
+             "and the output of `calendar-current-time-zone'"))))
+        (if (decoded-time-zone dt)
+            (icr:tz-decode-time (encode-time dt) vtimezone)
+          (icr:tz-set-zone dt vtimezone :error)))
+       ((eq 'to-utc di:time-zone-export-strategy)
+        (decode-time (encode-time dt) t))
+       ((eq 'floating di:time-zone-export-strategy)
+        (setf (decoded-time-zone dt) nil)
+        dt)))))
+
+(defun di:parse-sexp ()
+  "Parse a diary S-expression at the beginning of the current restriction.
+
+The S-expression must appear at the start of line, immediately after
+`diary-sexp-entry-symbol'.  If an S-expression is found, move the
+current restriction past it, and return the S-expression.  Otherwise,
+return nil."
+  (goto-char (point-min))
+  (let ((regexp (rx line-start
+                    (regexp diary-sexp-entry-symbol))))
+    (when (re-search-forward regexp (line-end-position) t)
+      (let ((sexp (read (current-buffer))))
+        (narrow-to-region (point) (point-max))
+        sexp))))
+
+(defun di:anniversary-sexp-to-recurrence (sexp)
+  "Convert `diary-anniversary' SEXP to `icalendar-dtstart' and `icalendar-rrule'.
+Returns a pair of nodes (START RRULE)."
+  (let* ((d1 (nth 1 sexp))
+         (d2 (nth 2 sexp))
+         (d3 (nth 3 sexp))
+         (dtstart (diary-make-date d1 d2 (or d3 di:recurring-start-year)))
+         (rrule '((FREQ YEARLY))))
+    (list
+     (ical:make-property ical:dtstart dtstart (ical:valuetypeparam 'ical:date))
+     (ical:make-property ical:rrule rrule))))
+
+(defun di:block-sexp-to-recurrence (sexp)
+  "Convert `diary-block' SEXP to `icalendar-dtstart' and `icalendar-rrule' nodes.
+Returns a pair of nodes (START RRULE)."
+  (let* ((dtstart (diary-make-date (nth 1 sexp) (nth 2 sexp) (nth 3 sexp)))
+         (end (diary-make-date (nth 4 sexp) (nth 5 sexp) (nth 6 sexp)))
+         (rrule `((FREQ DAILY)
+                  (UNTIL ,end))))
+    (list (ical:make-property ical:dtstart dtstart
+            (ical:valuetypeparam 'ical:date))
+          (ical:make-property ical:rrule rrule))))
+
+(defun di:time-block-sexp-to-start-end (sexp &optional vtimezone)
+  "Convert `diary-time-block' SEXP to `icalendar-dtstart' and `icalendar-dtend'.
+Returns a pair of nodes (START END).
+
+VTIMEZONE, if specified, should be an `icalendar-vtimezone'.  Times in
+SEXP will be reinterpreted as local to VTIMEZONE, as UTC, or as floating
+times according to `diary-icalendar-time-zone-export-strategy'."
+  (let* ((start (plist-get sexp :start))
+         (dtstart (di:convert-time-via-strategy start vtimezone))
+         (end (plist-get sexp :end))
+         (dtend (di:convert-time-via-strategy end vtimezone))
+         (tzid (ical:with-property-of vtimezone 'ical:tzid)))
+    (list (ical:make-property ical:dtstart dtstart (ical:tzidparam tzid))
+          (ical:make-property ical:dtend dtend (ical:tzidparam tzid)))))
+
+(defun di:cyclic-sexp-to-recurrence (sexp)
+  "Convert `diary-cyclic' SEXP to `icalendar-dtstart' and `icalendar-rrule'.
+Returns a pair of nodes (START RRULE)."
+  (let* ((ndays (nth 1 sexp))
+         (dtstart (diary-make-date (nth 2 sexp) (nth 3 sexp) (nth 4 sexp)))
+         (rrule `((FREQ DAILY)
+                  (INTERVAL ,ndays))))
+    (list
+     (ical:make-property ical:dtstart dtstart (ical:valuetypeparam 'ical:date))
+     (ical:make-property ical:rrule rrule))))
+
+(defun di:float-sexp-to-recurrence (sexp)
+  "Convert `diary-float' SEXP to `icalendar-dtstart' and `icalendar-rrule'.
+Returns a pair of nodes (START RRULE)."
+  (let* ((month-exp (nth 1 sexp))
+         (months (cond ((eq month-exp t) nil) ; don't add a BYMONTH clause
+                       ((integerp month-exp) (list month-exp))
+                       ((and (listp month-exp) (eq 'quote (car month-exp)))
+                        (eval month-exp nil)) ; unquote a literal list of ints
+                       (t month-exp)))
+         (_ (unless (seq-every-p #'integerp months)
+              (di:signal-export-error
+               (format "Malformed month(s) in `diary-float' S-expression:\n%s"
+                       sexp))))
+         (dow (nth 2 sexp))
+         (n (nth 3 sexp))
+         (day (or (nth 4 sexp)
+                  (if (< 0 n) 1
+                    'last))) ; = "last day of the month" for any month
+         ;; Calculate the offset within the month from day, n:
+         (offset
+          (cond ((eq day 'last) n)
+                ((and (< 0 day) (< 0 n))
+                 ;; In this case, to get the offset relative to
+                 ;; the start of the month, we need to add to n
+                 ;; the number of weeks in the month before day:
+                 ;; e.g. if day = 8, n = 2, then we are looking
+                 ;; for the second DOW after the 8th of the
+                 ;; month, which is the 3rd DOW after the 1st of
+                 ;; the month
+                 (+ n (/ (1- day) 7)))
+                ((and (< 0 day) (< n 0) (< day (* 7 (abs n))))
+                 ;; In this case, we need to cross into the
+                 ;; previous month and adjust the offset
+                 ;; accordingly to reflect the correct number of
+                 ;; weeks before the end of the month.
+                 ;; e.g. if day = 15, n = -3, we're looking for the
+                 ;; 3rd DOW before the 15th of the month,
+                 ;; which is the 1st DOW "before" the end of the
+                 ;; previous month (where "before" is inclusive,
+                 ;; e.g offset = -1 will work when DOW is the last
+                 ;; day of the month)
+                 (when months
+                   (setq months
+                         (sort
+                          :in-place t
+                          (mapcar
+                           (lambda (m) (if (eql m 1) 12 (1- m)))
+                           months))))
+                 (+ n (/ (1- day) 7)))))
+         (rrule (delq nil
+                      `((FREQ MONTHLY)
+                        ,(when months
+                           (list 'BYMONTH months))
+                        (BYDAY ((,dow . ,offset))))))
+         (dtstart
+          (calendar-nth-named-day n dow
+                                  (if months (apply #'min months) 1)
+                                  di:recurring-start-year
+                                  (unless (eq day 'last) day))))
+
+    ;; if at this point we have an offset which could put us outside the
+    ;; month boundaries, warn the user that this may not be supported:
+    (when (< 4 (abs offset))
+      (ical:warn
+       (format
+        "`diary-float' with large N=%d may not be supported on other systems" n)))
+
+    (list (ical:make-property ical:dtstart dtstart
+            (ical:valuetypeparam 'ical:date))
+          (ical:make-property ical:rrule rrule))))
+
+(defun di:offset-sexp-to-nodes (sexp)
+  "Convert a `diary-offset' SEXP to a list of property nodes.
+
+SEXP must have the form (diary-offset INNER-SEXP NDAYS).  The conversion
+is only possible for relatively simple cases of INNER-SEXP.  The
+INNER-SEXP is first converted to a list of property nodes (see
+`diary-icalendar-export-sexp'), and then any date, time, period, and
+recurrence rule values in these nodes are adjusted NDAYS forward."
+  (let* ((arg1 (nth 1 sexp))
+         (inner-sexp (if (eq (car arg1) 'quote)
+                         (eval arg1 nil) ; unquote a quoted inner sexp
+                       arg1))
+         (nodes (di:sexp-to-nodes inner-sexp))
+         (ndays (nth 2 sexp)))
+    (dolist (node nodes)
+      (ical:with-property node nil
+       (cl-case (ical:ast-node-type node)
+         ((ical:dtstart ical:dtend)
+          (ical:ast-node-set-value
+           value-node
+           (ical:date/time-add value :day ndays)))
+         (ical:exdate
+          (dolist (val-node value-nodes)
+            (ical:with-node-value val-node nil
+              (ical:ast-node-set-value
+               val-node
+               (ical:date/time-add value :day ndays)))))
+         (ical:rdate
+          (dolist (val-node value-nodes)
+            (ical:ast-node-set-value
+              val-node
+              (ical:with-node-value val-node nil
+               (cl-typecase value
+                (ical:period
+                 (ical:make-period
+                  (ical:date/time-add (ical:period-start value) :day ndays)
+                  :end (when (ical:period--defined-end value)
+                         (ical:date/time-add
+                          (ical:period--defined-end value) :day ndays))
+                  :duration (ical:period-dur-value value)))
+                (t (ical:date/time-add value :day ndays)))))))
+         (ical:rrule
+          (let ((mdays (ical:recur-by* 'BYMONTHDAY value))
+                (ydays (ical:recur-by* 'BYYEARDAY value))
+                (dows (ical:recur-by* 'BYDAY value))
+                (bad-clause
+                 (cond ((ical:recur-by* 'BYSETPOS value) 'BYSETPOS)
+                       ((ical:recur-by* 'BYWEEKNO value) 'BYWEEKNO))))
+            ;; We can't reliably subtract days in the following cases, so bail:
+            (when (< 28 ndays)
+              (di:signal-export-error
+               (format "Cannot export `diary-offset' with large offset %d" ndays)))
+            (when bad-clause
+              (di:signal-export-error
+               (format "Cannot export `diary-offset': inner SEXP %s contains %s"
+                       sexp bad-clause)))
+            (when (seq-some (lambda (md)
+                              (or (and (< 0 md) (< 28 (+ md ndays)))
+                                  (and (< md 0) (< 0 (+ md ndays)))))
+                            mdays)
+              (di:signal-export-error
+               (format "Cannot export `diary-offset': inner SEXP %s contains %s"
+                       inner-sexp
+                       "BYMONTHDAY clause that could cross month bounds")))
+            (when (seq-some (lambda (yd)
+                              (or (and (< 0 yd) (< 365 (+ yd ndays)))
+                                  (and (< yd 0) (< 0 (+ yd ndays)))))
+                            ydays)
+              (di:signal-export-error
+               (format "Cannot export `diary-offset': inner SEXP %s contains %s"
+                       inner-sexp
+                       "BYYEARDAY clause that could cross year bounds")))
+            ;; Adjust the rule's clauses to account for the offset:
+            (when mdays
+              (setf (alist-get 'BYMONTHDAY value)
+                    (list
+                     (mapcar (apply-partially #'+ ndays) mdays))))
+            (when ydays
+              (setf (alist-get 'BYYEARDAY value)
+                    (list
+                     (mapcar (apply-partially #'+ ndays) ydays))))
+            (when dows
+              (setf (alist-get 'BYDAY value)
+                    (list
+                     (mapcar
+                      (lambda (dow)
+                        (if (integerp dow)
+                            (mod (+ dow ndays) 7)
+                          (let* ((wkday (car dow))
+                                 (shifted (+ wkday ndays))
+                                 (new-wkday (mod shifted 7))
+                                 (new-offs
+                                  (cond
+                                   ;; if shifted is not between 0 and 7,
+                                   ;; we moved into another week, so we need
+                                   ;; to modify the offset within the month/year
+                                   ;; by the number of weeks moved:
+                                   ((< 7 shifted)
+                                    (+ (/ shifted 7) (cdr dow)))
+                                   ((< shifted 0)
+                                    (+ -1 (/ shifted 7) (cdr dow)))
+                                   ;; otherwise it stays the same:
+                                   (t (cdr dow)))))
+                            (cons new-wkday new-offs))))
+                      dows)))))))))
+    ;; Return the modified nodes:
+    nodes))
+
+;; Converts a legacy value of `icalendar-export-alarms' to new format of
+;; `diary-icalendar-export-alarms':
+(defun di:-convert-legacy-alarm-options (alarm-options)
+  (declare (obsolete nil "31.1"))
+  (let ((lead-time (car alarm-options))
+        (by-types (cadr alarm-options)))
+    (mapcar
+     (lambda (l)
+       (cl-case (car l)
+         (audio `(audio ,lead-time))
+         (display `(display ,lead-time "%s"))
+         (email `(email ,lead-time "%s" ,(cadr l)))))
+     by-types)))
+
+(defun di:add-valarms (component &optional vtimezone)
+  "Add VALARMs to COMPONENT according to `diary-icalendar-export-alarms'.
+
+COMPONENT should be an `icalendar-vevent' or `icalendar-vtodo'.  The
+generated VALARM components will be added to this node's children.
+VTIMEZONE should define the local timezone; it is required when
+formatting alarms as mail messages.  Returns the modified COMPONENT."
+  (let* ((alarm-options
+         (if (and (bound-and-true-p icalendar-export-alarms)
+                  (null di:export-alarms))
+             ;; For backward compatibility with icalendar.el:
+             (with-suppressed-warnings
+                 ((obsolete ical:export-alarms
+                            di:-convert-legacy-alarm-options))
+               (di:-convert-legacy-alarm-options ical:export-alarms))
+           di:export-alarms))
+         valarms)
+    (dolist (opts alarm-options)
+      (let* ((type (nth 0 opts))
+             (minutes (nth 1 opts)))
+        (cl-case type
+          (audio
+           (push (ical:make-valarm
+                  (ical:action "AUDIO")
+                  (ical:trigger (make-decoded-time :minute (* -1 minutes))))
+                 valarms))
+          (display
+           (ical:with-component component
+             ((ical:summary :value summary)
+              (ical:description :value description))
+             (let* ((displayed-summary
+                     (replace-regexp-in-string
+                      "%t" (number-to-string minutes)
+                      (replace-regexp-in-string
+                       "%s" summary
+                       (nth 2 opts)))))
+               (push (ical:make-valarm
+                      (ical:action "DISPLAY")
+                      (ical:trigger (make-decoded-time :minute (* -1 minutes)))
+                      (ical:summary displayed-summary)
+                      (ical:description description))
+                     valarms))))
+          (email
+           (ical:with-component component
+             ((ical:summary :value summary)
+              (ical:attendee :all entry-attendees))
+             (let* ((subject
+                     (replace-regexp-in-string
+                      "%t" (number-to-string minutes)
+                      (replace-regexp-in-string
+                       "%s" summary
+                       (nth 2 opts))))
+                    (index (ical:index-insert-tz (ical:make-index) vtimezone))
+                    (body
+                     (dlet ((ical-as-alarm 'email))
+                       (di:format-entry component index)))
+                    (addresses (nth 3 opts))
+                    all-attendees)
+               (dolist (address addresses)
+                 (cond
+                  ((eq address 'from-entry)
+                   (setq all-attendees (append entry-attendees all-attendees)))
+                  ((stringp address)
+                   (push (ical:make-property ical:attendee
+                             (concat "mailto:" address))
+                         all-attendees))))
+               (push (ical:make-valarm
+                      (ical:action "EMAIL")
+                      (ical:trigger (make-decoded-time :minute (* -1 minutes)))
+                      (ical:summary subject)
+                      (ical:description body)
+                      (@ all-attendees))
+                     valarms)))))))
+    (apply #'ical:ast-node-adopt-children component valarms)
+    component))
+
+(defun di:rrule-sexp-to-recurrence (sexp &optional vtimezone)
+  "Convert a `diary-rrule' SEXP to iCalendar recurrence rule properties.
+Returns a list containing at least `icalendar-dtstart' and
+`icalendar-rrule' nodes, and zero or more `icalendar-rdate',
+`icalendar-exdate', and `icalendar-duration' nodes.
+
+VTIMEZONE, if specified, should be an `icalendar-vtimezone'.  Times in
+SEXP will be reinterpreted as local to VTIMEZONE, as UTC, or as floating
+times according to `diary-icalendar-time-zone-export-strategy'."
+  (let* ((args (cdr sexp))
+         (start (plist-get args :start))
+         (dtstart (di:convert-time-via-strategy
+                   (if (eq 'quote (car start)) (eval start nil) start)
+                   vtimezone))
+         (rule (plist-get args :rule))
+         (rrule (if (eq 'quote (car rule)) (eval rule nil) rule))
+         (included (plist-get args :include))
+         (rdates (mapcar
+                  (lambda (dt) (di:convert-time-via-strategy dt vtimezone))
+                  (if (eq 'quote (car included)) (eval included nil) included)))
+         (excluded (plist-get args :exclude))
+         (exdates (mapcar
+                   (lambda (dt) (di:convert-time-via-strategy dt vtimezone))
+                   (if (eq 'quote (car excluded)) (eval excluded nil) excluded)))
+         (duration (eval (plist-get args :duration) t))
+         (dur-value
+          (if (eq 'quote (car duration)) (eval duration nil) duration))
+         (tzid
+          (when (cl-typep dtstart 'ical:date-time)
+            (ical:with-property-of vtimezone 'ical:tzid)))
+         nodes)
+    (push (ical:make-property ical:rrule rrule) nodes)
+    (push (ical:make-property ical:dtstart dtstart (ical:tzidparam tzid))
+          nodes)
+    (when rdates
+      (push (ical:make-property ical:rdate rdates (ical:tzidparam tzid))
+            nodes))
+    (when exdates
+      (push (ical:make-property ical:exdate exdates (ical:tzidparam tzid))
+            nodes))
+    (when duration
+      (push (ical:make-property ical:duration dur-value) nodes))
+    nodes))
+
+(defun di:dates-to-recurrence (months days years)
+  "Convert values representing one or more dates to iCalendar recurrences.
+
+MONTHS, DAYS, and YEARS should either be integers, lists of integers, or
+the symbol t.
+
+Returns a pair of nodes (START R), where START is an `icalendar-dtstart'
+node and R is an `icalendar-rrule' node or `icalendar-rdate' node (or
+nil, if MONTHS, DAYS and YEARS are all integers)."
+  (if (and (integerp months) (integerp days) (integerp years))
+      ;; just a regular date, without recurrence data:
+      (list
+       (ical:make-property ical:dtstart (list months days years))
+       nil)
+
+    (when (integerp months) (setq months (list months)))
+    (when (integerp days) (setq days (list days)))
+    (when (integerp years) (setq years (list years)))
+    (let (dtstart freq bymonth bymonthday rdates rdate-type)
+      (cond ((and (eq days t) (eq months t) (eq years t))
+             (setq freq 'DAILY
+                   dtstart (list 1 1 di:recurring-start-year)))
+            ((and (eq months t) (eq years t))
+             (setq freq 'MONTHLY
+                   bymonthday days
+                   dtstart (list 1 (car days) di:recurring-start-year)))
+            ((and (eq years t) (eq days t))
+             (setq freq 'DAILY
+                   bymonth months
+                   dtstart (list (apply #'min months)
+                                 1
+                                 di:recurring-start-year)))
+            ((eq years t)
+             (setq freq 'YEARLY
+                   bymonth months
+                   bymonthday days
+                   dtstart
+                   (list (apply #'min months)
+                         (apply #'min days)
+                         di:recurring-start-year)))
+            ;; The remaining cases are not representable as RRULEs,
+            ;; because there is no BYYEAR clause.  So we generate an RDATE
+            ;; covering each specified date.
+            ((and (eq months t) (eq days t))
+             ;; In this case we represent each of the specified years as a period:
+             (setq rdate-type 'ical:period
+                   rdates
+                   (mapcar
+                    (lambda (y)
+                      (ical:make-period
+                       (ical:make-date-time :year y :month 1 :day 1
+                                            :hour 0 :minute 0 :second 0)
+                       :end
+                       (ical:make-date-time :year (1+ y) :month 1 :day 1
+                                            :hour 0 :minute 0 :second 0)))
+                    years)
+                   dtstart (ical:date-time-to-date
+                            (ical:period-start (car rdates)))))
+            (t
+             ;; Otherwise, represent each date individually:
+             (setq rdate-type 'ical:date
+                   rdates
+                   (mapcan
+                    (lambda (y)
+                      (mapcan
+                       (lambda (m)
+                         (mapcar
+                          (lambda (d) (list m d y))
+                          (if (listp days) days
+                            ;; days = t:
+                            (number-sequence 1 (calendar-last-day-of-month m y)))))
+                       (if (listp months) months
+                         ;; months = t:
+                         (number-sequence 1 12))))
+                    years)
+                   ;; ensure dtstart is the earliest recurrence:
+                   dtstart (apply #'ical:date/time-min rdates)
+                   rdates (seq-remove (apply-partially #'equal dtstart) rdates))))
+
+      ;; Return the pair of nodes (DTSTART RRULE) or (DTSTART RDATE):
+      (let* ((recur-value
+              (delq nil
+                    `((FREQ ,freq)
+                      ,(when bymonth (list 'BYMONTH bymonth))
+                      ,(when bymonthday (list 'BYMONTHDAY bymonthday)))))
+           (rrule-node (when freq (ical:make-property ical:rrule recur-value)))
+           (rdate-node (when rdates
+                         (ical:make-property ical:rdate rdates
+                           (ical:valuetypeparam rdate-type))))
+           (dtstart-node (ical:make-property ical:dtstart dtstart)))
+        (list dtstart-node (or rrule-node rdate-node))))))
+
+(defun di:date-sexp-to-recurrence (sexp)
+  "Convert a `diary-date' SEXP to an `icalendar-rrule' or `icalendar-rdate' node.
+Returns a pair of nodes (START R), where START is an `icalendar-dtstart'
+node and R is the RRULE or RDATE node."
+  (let* ((d1 (nth 1 sexp))
+         (d2 (nth 2 sexp))
+         (d3 (nth 3 sexp))
+         years months days)
+    (cl-case calendar-date-style
+      (iso (setq years (if (integerp d1) (list d1) d1)
+                 months (if (integerp d2) (list d2) d2)
+                 days (if (integerp d3) (list d3) d3)))
+      (american (setq months (if (integerp d1) (list d1) d1)
+                      days (if (integerp d2) (list d2) d2)
+                      years (if (integerp d3) (list d3) d3)))
+      (european (setq days (if (integerp d1) (list d1) d1)
+                      months (if (integerp d2) (list d2) d2)
+                      years (if (integerp d3) (list d3) d3))))
+
+    ;; unquote lists of integers read as quoted lists:
+    (when (and (listp months) (eq 'quote (car months)))
+      (setq months (eval months nil)))
+    (when (and (listp days) (eq 'quote (car days)))
+      (setq days (eval days nil)))
+    (when (and (listp years) (eq 'quote (car years)))
+      (setq years (eval years nil)))
+
+    ;; if at this point we don't have lists of integers or "t", user
+    ;; entered a malformed diary-date sexp:
+    (unless (or (eq months t) (seq-every-p #'integerp months))
+      (di:signal-export-error
+       (format "Malformed months in `diary-date' S-expression:\n%s" sexp)))
+    (unless (or (eq days t) (seq-every-p #'integerp days))
+      (di:signal-export-error
+       (format "Malformed days in `diary-date' S-expression:\n%s" sexp)))
+    (unless (or (eq years t) (seq-every-p #'integerp years))
+      (di:signal-export-error
+       (format "Malformed years in `diary-date' S-expression:\n%s" sexp)))
+
+    (di:dates-to-recurrence months days years)))
+
+(defun di:other-sexp-to-recurrence (sexp)
+  "Convert diary SEXP to `icalendar-rdate' by enumerating its recurrences.
+
+The enumeration starts on the current date and includes recurrences in
+the next `diary-icalendar-export-sexp-enumeration-days' days.  Returns a
+list (START COMMENT RDATE), where START is an `icalendar-dtstart',
+COMMENT is an `icalendar-comment' containing SEXP, and RDATE is an
+`icalendar-rdate' containing the enumerated recurrences.  If there are
+no recurrences, (START COMMENT EXDATE) is returned, where START is the
+current date, and EXDATE is an `icalendar-exdate' excluding that start
+date as a recurrence.  (This is because `icalendar-dtstart' is a required
+property and must be present even if the recurrence set is empty.)"
+  (let* ((today (calendar-absolute-from-gregorian (calendar-current-date)))
+         (end (+ today (1- di:export-sexp-enumeration-days)))
+        dtstart rdates exdates)
+    (dolist (absdate (number-sequence today end))
+      (calendar-dlet ((date (calendar-gregorian-from-absolute absdate)))
+        (when (eval sexp t)
+          (push date rdates))))
+    (if rdates
+        (progn
+          (setq rdates (nreverse rdates))
+          (setq dtstart (car rdates)
+                rdates (cdr rdates)))
+      (ical:warn
+       (format "No recurrences in the next %d days: %s"
+               di:export-sexp-enumeration-days
+               sexp)
+       :severity 0)
+      ;; When there are no recurrences, we still need a DTSTART, but we
+      ;; can exclude it via an EXDATE:
+      (setq dtstart (calendar-current-date)
+            exdates (list dtstart)))
+
+    (append
+     (list
+      (ical:make-property ical:dtstart dtstart
+        (ical:valuetypeparam 'ical:date))
+      ;; TODO: should we maybe use an X-name property for this?
+      (ical:make-property ical:comment (format "%s" sexp)))
+     (if rdates
+         (list
+          (ical:make-property ical:rdate rdates
+            (ical:valuetypeparam 'ical:date)))
+       (list
+        (ical:make-property ical:exdate exdates
+          (ical:valuetypeparam 'ical:date)))))))
+
+(defun di:sexp-to-nodes (sexp &optional vtimezone)
+  "Convert a diary S-expression SEXP to a list of iCalendar property nodes.
+
+The fully supported S-expressions are:
+`diary-anniversary'
+`diary-block'
+`diary-cyclic'
+`diary-date'
+`diary-float'
+`diary-remind'
+`diary-rrule'
+`diary-time-block'
+
+There is partial support for `diary-offset' S-expressions; see
+`diary-icalendar-offset-to-nodes'.
+
+Other S-expressions are only supported via enumeration.  Their
+recurrences are enumerated for
+`diary-icalendar-export-sexp-enumeration-days' starting from the current
+date; see `diary-icalendar-other-sexp-to-recurrence'.  If
+`diary-icalendar-export-sexp-enumerate-all' is non-nil, all
+S-expressions are enumerated rather than converted to recurrence rules.
+
+VTIMEZONE, if specified, should be an `icalendar-vtimezone'.  Times in
+SEXP will be reinterpreted as local to VTIMEZONE, as UTC, or as floating
+times according to `diary-icalendar-time-zone-export-strategy'."
+  (if di:export-sexp-enumerate-all ;; see Bug#7911 for motivation
+      (di:other-sexp-to-recurrence sexp)
+    (cl-case (car sexp)
+      (diary-anniversary (di:anniversary-sexp-to-recurrence sexp))
+      (diary-block (di:block-sexp-to-recurrence sexp))
+      (diary-cyclic (di:cyclic-sexp-to-recurrence sexp))
+      (diary-date (di:date-sexp-to-recurrence sexp))
+      (diary-float (di:float-sexp-to-recurrence sexp))
+      (diary-offset (di:offset-sexp-to-nodes sexp))
+      (diary-rrule (di:rrule-sexp-to-recurrence sexp vtimezone))
+      (diary-time-block (di:time-block-sexp-to-start-end sexp vtimezone))
+      ;; For `diary-remind' we only handle the inner sexp:
+      (diary-remind (di:sexp-to-nodes (nth 1 sexp) vtimezone))
+      (t (di:other-sexp-to-recurrence sexp)))))
+
+;;; Time zone handling during export:
+
+(defun di:current-tz-to-vtimezone (&optional tz tzid start-year)
+  "Convert TZ to an `icalendar-vtimezone'.
+
+See `icalendar-recur-current-tz-to-vtimezone' for arguments' meanings.
+This function wraps that one, but signals `icalendar-diary-export-error'
+instead if TZ cannot be converted."
+  (condition-case _
+      (icr:current-tz-to-vtimezone tz tzid start-year)
+    ((ical:tz-insufficient-data ical:tz-unsupported)
+     (di:signal-export-error
+      (format "Unable to export time zone data: %s.\n%s." tz
+              "Check the value of `diary-icalendar-time-zone-export-strategy'")))))
+
+;;; Parsing complete diary entries:
+
+(defun di:parse-entry-linewise (begin end vtimezone type date-nodes)
+  "Convert the entry between BEGIN and END linewise to iCalendar components.
+
+\"Linewise\" means each line of a diary entry will be exported as a
+distinct event; see `diary-icalendar-export-linewise'.
+Returns a list of component nodes representing the events.
+
+VTIMEZONE must be the `icalendar-vtimezone' in which times in the entry
+appear (or nil).  TYPE and DATE-NODES must contain the iCalendar component
+type and date information parsed from the beginning of the entry which
+apply to all of the events.  These arguments are passed on in recursive
+calls to `diary-icalendar-parse-entry'."
+  (save-restriction
+    (narrow-to-region begin end)
+    (goto-char (point-min))
+    (let ((subentry-regexp
+           ;; match to the end of lines which have indentation equal to
+           ;; or greater than the current one:
+           (rx line-start
+               (group-n 1 (+ space))
+               (* not-newline)
+               (* "\n" (backref 1) (+ space) (* not-newline))))
+          components)
+
+      (while (re-search-forward subentry-regexp end t)
+        (let ((next-pos (1+ (match-end 0))))
+          (setq components
+                (append
+                 (di:parse-entry (match-beginning 0) (match-end 0)
+                                  vtimezone type date-nodes)
+                 components))
+          (goto-char next-pos)))
+      components)))
+
+(defun di:parse-entry (begin end &optional vtimezone type date-nodes)
+  "Convert the entry between BEGIN and END to a list of iCalendar components.
+
+The region between BEGIN and END will be parsed for a date, time,
+summary, description, attendees, and UID.  This information will be
+combined into an `icalendar-vevent' (or `icalendar-vjournal' or
+`icalendar-vtodo', depending on the values of
+`diary-icalendar-export-nonmarking-entries',
+`diary-icalendar-export-nonmarking-as-vjournal' and
+`diary-icalendar-todo-regexp') and that component will be returned
+wrapped in a list.  Returns nil if the entry should not be exported
+according to `diary-icalendar-export-nonmarking-entries'.
+
+If `diary-icalendar-export-linewise' is non-nil, then a top-level call
+to this function will return a list of several such components.  (Thus,
+the function always returns a list of components.)
+
+VTIMEZONE, if specified, should be the `icalendar-vtimezone' in which
+times in the entry appear.  If
+`diary-icalendar-time-zone-export-strategy' is not either \\='to-utc or
+\\='floating, VTIMEZONE must be provided.
+
+DATE-NODES and TYPE should be nil in a top-level call; they are used in
+recursive calls to this function made by
+`diary-icalendar-parse-entry-linewise'."
+  (save-restriction
+    (narrow-to-region begin end)
+    (goto-char (point-min))
+    (let (sexp dateform weekday tzid transparency all-props should-recurse)
+      (setq should-recurse (and di:export-linewise (not date-nodes) (not type)))
+      (when (ical:vtimezone-component-p vtimezone)
+        (setq tzid (ical:with-property-of vtimezone 'ical:tzid)))
+      (unless date-nodes
+        ;; If we don't already have date information, we are in a
+        ;; top-level call and need to collect the date and type
+        ;; information from the start of the entry:
+        (setq type (di:parse-entry-type))
+        ;; N.B. the following four parsing functions successively
+        ;; narrow the current restriction past anything they parse:
+        (setq transparency (di:parse-transparency type))
+        (setq sexp (di:parse-sexp))
+        (setq dateform (di:parse-date-form))
+        (setq weekday (di:parse-weekday-name))
+        (setq date-nodes
+              (append
+               transparency
+               (when sexp (di:sexp-to-nodes sexp vtimezone))
+               (when dateform
+                 (apply #'di:dates-to-recurrence dateform))
+               (when (and weekday (not dateform))
+                 (di:weekday-to-recurrence weekday)))))
+
+      (when type ; nil means entry should not be exported
+        (if should-recurse
+            ;; If we are in a top level call and should export linewise,
+            ;; do that recursively now:
+            (di:parse-entry-linewise (point) end vtimezone type date-nodes)
+
+          ;; Otherwise, we are either in a recursive call with a
+          ;; narrower restriction, or don't need to export linewise.  In
+          ;; both cases, we gather the remaining data from the current
+          ;; restriction and combine everything into a component node:
+          (let* ((times (di:parse-time))
+                 (start-time (when times (car times)))
+                 (end-time (when times (cadr times))))
+            ;; Combine clock time values in the current restriction with
+            ;; date information parsed at the top level.  Doing this here
+            ;; allows us to combine a different time on each line of an
+            ;; entry exported linewise with the date information for the
+            ;; whole entry:
+            (dolist (node date-nodes)
+              (ical:with-property node nil
+                (cond
+                 ((and (ical:dtstart-property-p node)
+                       (eq 'ical:date value-type)
+                       start-time)
+                  (let ((dtstart
+                         (di:convert-time-via-strategy
+                          (ical:date-time-variant
+                           start-time
+                           :year (calendar-extract-year value)
+                           :month (calendar-extract-month value)
+                           :day (calendar-extract-day value))
+                          vtimezone)))
+                    (push (ical:make-property ical:dtstart dtstart
+                            (ical:tzidparam tzid))
+                          all-props)
+                    (when end-time
+                      ;; an end time parsed from a time specification
+                      ;; in the entry is always on the same day as
+                      ;; DTSTART.
+                      (let* ((dtend
+                              (di:convert-time-via-strategy
+                               (ical:date-time-variant
+                                end-time
+                                :year (calendar-extract-year value)
+                                :month (calendar-extract-month value)
+                                :day (calendar-extract-day value))
+                               vtimezone))
+                             (is-recurring
+                              (seq-find
+                               (lambda (n) (or (ical:rrule-property-p n)
+                                               (ical:rdate-property-p n)))
+                               date-nodes)))
+                        (if is-recurring
+                            ;; If the entry is recurring, we interpret
+                            ;; the end time as giving us a duration for all
+                            ;; recurrences:
+                            (progn
+                              (when (seq-find #'ical:duration-property-p
+                                              date-nodes)
+                                (ical:warn
+                                 (concat "Parsed both duration and end time; "
+                                         "ignoring end time specification")
+                                 :buffer (current-buffer)
+                                 :position (point)))
+                              (push (ical:make-property ical:duration
+                                        (ical:duration-between dtstart dtend))
+                                    all-props))
+                          ;; Otherwise we make a normal DTEND:
+                          (push (ical:make-property ical:dtend dtend)
+                                all-props))))))
+
+                 ((and (ical:rdate-property-p node)
+                       start-time
+                       (seq-every-p (apply-partially #'eq 'ical:date)
+                                    value-types))
+                  (let ((rdates
+                         (mapcar
+                          (lambda (dt)
+                            (if end-time
+                                (ical:make-period
+                                 (di:convert-time-via-strategy
+                                  (ical:date-time-variant
+                                   start-time
+                                   :year (calendar-extract-year dt)
+                                   :month (calendar-extract-month dt)
+                                   :day (calendar-extract-day dt))
+                                  vtimezone)
+                                 :end
+                                 (di:convert-time-via-strategy
+                                  (ical:date-time-variant
+                                   end-time
+                                   :year (calendar-extract-year dt)
+                                   :month (calendar-extract-month dt)
+                                   :day (calendar-extract-day dt))
+                                  vtimezone))
+                              (di:convert-time-via-strategy
+                               (ical:date-time-variant
+                                start-time
+                                :year (calendar-extract-year dt)
+                                :month (calendar-extract-month dt)
+                                :day (calendar-extract-day dt))
+                               vtimezone)))
+                          values)))
+                    (push (ical:make-property ical:rdate rdates
+                            (ical:tzidparam tzid))
+                          all-props)))
+
+                   ;; preserve any other node read from date, e.g. RRULE, as is:
+                   (node (push node all-props))))))
+
+          ;; In a VTODO, entry date must become the DUE date; either
+          ;; DTEND becomes DUE, or if there is no DTEND, then DTSTART:
+          (when (eq type 'ical:vtodo)
+            (unless (catch 'found-dtend
+                      (dolist (node all-props)
+                        (when (ical:dtend-property-p node)
+                          (ical:ast-node-set-type node 'ical:due)
+                          (throw 'found-dtend t))))
+              (dolist (node all-props)
+                (when (ical:dtstart-property-p node)
+                  (ical:ast-node-set-type node 'ical:due)))))
+
+          ;; Collect the remaining properties:
+          (setq all-props (append (di:parse-summary-and-description) all-props))
+          (setq all-props (append (di:parse-attendees-and-organizer) all-props))
+          (push (ical:make-property ical:dtstamp (decode-time nil t)) all-props)
+          (let ((class (di:parse-class))
+                (location (di:parse-location))
+                (status (di:parse-status))
+                (url (di:parse-url)))
+            (when class (push class all-props))
+            (when location (push location all-props))
+            (when status (push status all-props))
+            (when url (push url all-props)))
+          (push (or (di:parse-uid)
+                     (ical:make-property ical:uid
+                         (ical:make-uid all-props)))
+                all-props)
+
+          ;; Allow users to add to the properties parsed:
+          (when (functionp di:other-properties-parser)
+            (let ((others (funcall di:other-properties-parser type all-props)))
+              (dolist (p others)
+                (condition-case nil
+                    (push (ical:ast-node-valid-p p)
+                          all-props)
+                  (ical:validation-error
+                   (ical:warn
+                    (format "`%s' returned invalid `%s' property; ignoring"
+                            di:other-properties-parser
+                            (ical:ast-node-type p))
+                    :buffer (current-buffer)
+                    :position (point)))))))
+
+          ;; Construct, validate and return a component of the appropriate type:
+          (let ((component
+                 (ical:ast-node-valid-p
+                  (ical:make-ast-node type nil all-props))))
+
+            ;; Add alarms per `diary-icalendar-export-alarms', except for
+            ;; in VJOURNAL, where alarms are not allowed:
+            ;; TODO: should we also add alarms for `diary-remind' sexps?
+            (when (not (eq type 'ical:vjournal))
+              (di:add-valarms component vtimezone))
+
+            ;; Return the component wrapped in a list (for type consistency):
+            (list component)))))))
+
+;;;###autoload
+(defun di:export-region (begin end filename &optional erase)
+  "Export diary entries between BEGIN and END to iCalendar format in FILENAME.
+
+If FILENAME exists and is not empty, this function asks whether to erase
+its contents first.  If ERASE is non-nil, the contents of FILENAME will
+always be erased without asking.  Otherwise the exported data will be
+appended to the end of FILENAME.
+
+The export depends on a number of user-customizable variables.  Before
+running this command for the first time, you may especially wish to
+check the values of:
+`diary-file'
+`diary-date-forms'
+`calendar-date-style'
+as well as variables in the customization group `diary-icalendar-export'."
+  (interactive (list (region-beginning)
+                     (region-end)
+                     (expand-file-name
+                      (read-file-name "iCalendar file: "))))
+
+  (ical:init-error-buffer)
+  (let (output-buffer local-tz components vcalendar)
+    (when (and (null erase)
+               (file-exists-p filename)
+               (< 0 (file-attribute-size (file-attributes filename)))
+               (y-or-n-p (format "Delete existing contents of %s?" filename)))
+      (setq erase t))
+    (ical:condition-case err
+      (setq output-buffer (find-file-noselect filename)))
+    (when output-buffer
+      (save-excursion
+        (save-restriction
+          (narrow-to-region begin end)
+          (goto-char (point-min))
+          (cond ((eq 'local di:time-zone-export-strategy)
+                 (setq local-tz (di:current-tz-to-vtimezone)))
+                ((listp di:time-zone-export-strategy)
+                 (setq local-tz (di:current-tz-to-vtimezone
+                                 di:time-zone-export-strategy))))
+          (while (re-search-forward di:entry-regexp nil t)
+            (let ((entry-start (match-beginning 0))
+                  (entry-end (match-end 0))
+                  (first-line (match-string 1)))
+              (ical:condition-case err-data
+                 (setq components
+                       (append (di:parse-entry entry-start entry-end local-tz)
+                               components))
+                (ical:export-error
+                 (ical:warn
+                  (concat
+                   (format "Unable to export entry \"%s...\"; skipping" first-line)
+                   "\nError was:\n"
+                   (plist-get err-data :message))
+                  :position entry-start
+                  :buffer (current-buffer))))
+              (goto-char (1+ entry-end))))
+          (setq components (nreverse components))
+          (when local-tz (push local-tz components))
+          (ical:condition-case err-data
+             (setq vcalendar (ical:make-vcalendar (@ components))))
+
+          (when vcalendar
+            (with-current-buffer output-buffer
+              (when erase (erase-buffer))
+              (goto-char (point-max)) ; append, if user chose not to erase
+              (unless (bolp) (insert "\n"))
+              (ical:condition-case err-data
+                 (insert (ical:print-calendar-node vcalendar)))
+              (let ((coding-system-for-write 'utf-8-dos))
+                (save-buffer))))))))
+
+  (message
+   (if (ical:errors-p)
+       (format "iCalendar export completed with errors; see buffer %s"
+               (buffer-name (ical:error-buffer)))
+     "iCalendar export completed successfully.")))
+
+;;;###autoload
+(defun di:export-file (diary-filename filename &optional erase)
+  "Export DIARY-FILENAME to iCalendar format in FILENAME.
+
+The diary entries in DIARY-FILENAME will be exported to iCalendar format
+and the resulting calendar will be saved to FILENAME.
+
+If FILENAME exists and is not empty, this function asks whether to erase
+its contents first.  If ERASE is non-nil, the contents of FILENAME will
+always be erased without asking.  Otherwise the exported data will be
+appended to the end of FILENAME.
+
+The export depends on a number of user-customizable variables.  Before
+running this command for the first time, you may especially wish to
+check the values of:
+`diary-file'
+`diary-date-forms'
+`calendar-date-style'
+as well as variables in the customization group `diary-icalendar-export'."
+  (interactive (list
+                (read-file-name "Diary file: "
+                                (when diary-file (file-name-directory diary-file))
+                                (cons diary-file diary-included-files)
+                                'confirm)
+                (read-file-name "iCalendar file: "
+                                (when diary-file (file-name-directory diary-file))
+                                (when diary-file
+                                  (concat
+                                   (file-name-sans-extension diary-file)
+                                   ".ics")))))
+  (when (and (null erase)
+             (file-exists-p filename)
+             (< 0 (file-attribute-size (file-attributes filename)))
+             (y-or-n-p (format "Delete existing contents of %s?" filename)))
+      (setq erase t))
+  (with-current-buffer (find-file-noselect diary-filename)
+    (di:export-region (point-min) (point-max) filename erase)))
+
+
+;; Display in Diary
+
+;;; Functions implementing diary-icalendar sexps.
+;;; TODO: move these to diary-lib.el?
+
+;; To be called from diary-sexp-entry, where DATE, ENTRY are bound.
+(cl-defun diary-time-block (&key start end)
+  "Diary S-expression for time blocks.
+
+Entry applies if the queried date occurs between START and END,
+inclusive.  START and END may be `icalendar-date' or
+`icalendar-date-time' values."
+  (with-no-warnings (defvar date) (defvar entry))
+  (when (and (ical:date/time<= start date) (ical:date/time<= date end))
+    entry))
+
+;; To be called from diary-sexp-entry, where DATE, ENTRY are bound.
+(cl-defun diary-rrule (&key rule start duration include exclude)
+  "Diary S-expression for iCalendar recurrence rules.
+
+Entry applies if the queried date matches the recurrence rule.
+
+The keyword arguments RULE, START, INCLUDE and EXCLUDE should contain
+the recurrence data from an iCalendar component.  RULE should be an
+`icalendar-recur' value, START an `icalendar-date' or
+`icalendar-date-time', DURATION an `icalendar-dur-value', and INCLUDE
+and EXCLUDE should be lists of `icalendar-date' or `icalendar-date-time'
+values (of the same type as START)."
+  ;; TODO: also support a format that is nicer to read and type by hand.
+  ;; e.g. just letting a rule be specified in a recur-value string like
+  ;;   :rule "FREQ=MONTHLY;BYDAY=1SU"
+  ;; is perhaps already better than the raw Lisp format.  We could at least
+  ;; support specifying the clauses with keywords, e.g.
+  ;;   :freq :monthly :byday '("Sunday" . 1)
+  ;; would be better than the current
+  ;;   :rule '((FREQ MONTHLY) (BYDAY ((0 . 1))))
+  (with-no-warnings (defvar date) (defvar entry))
+  (when (ical:date<= start date)
+    (let* ((vevent (ical:make-vevent
+                    (ical:rrule rule)
+                    (ical:dtstart start)
+                    (ical:rdate include)
+                    (ical:exdate exclude)))
+           (interval (icr:find-interval date start rule)))
+      (cl-typecase start
+        (ical:date
+         (when (member date (icr:recurrences-in-interval interval vevent))
+           entry))
+        (ical:date-time
+         ;; TODO.  If start is a date-time, it was probably imported from
+         ;; an iCalendar file, but in order to calculate recurrences, we
+         ;; really need all the time zone information from that file,
+         ;; not just the rule, start, include and exclude.  But encoding
+         ;; all that tz info in a diary s-exp is cumbersome and ugly and
+         ;; probably not worth the trouble.  Since this is the diary, we
+         ;; assume that all we really care about here is whether there
+         ;; are recurrences on a particular day.  Thus we convert
+         ;; HOURLY/MINUTELY/SECONDLY rules to a DAILY rule, and all
+         ;; values to plain dates.  This keeps things simple (and
+         ;; hopefully quicker) but means that information gets lost.  I
+         ;; hope this can be changed to do things right at some point,
+         ;; but that will require first adding more robust time zone
+         ;; support to the diary somehow -- perhaps via #included
+         ;; iCalendar files?
+         (let* ((date-rule (copy-sequence rule))
+                (start-date (ical:date-time-to-date start))
+                (include-dates (mapcar #'ical:date-time-to-date include))
+                (exclude-dates (mapcar #'ical:date-time-to-date exclude))
+                ;; Preserve the clock times in the entry:
+                (entry-time
+                 (if duration
+                     (di:format-time-range
+                      start
+                      (ical:date/time-add-duration start duration))
+                   (di:format-time-as-local start)))
+                (date-entry (concat entry-time " " entry)))
+           (when (memq (ical:recur-freq date-rule) '(HOURLY MINUTELY SECONDLY))
+             (setf (alist-get 'FREQ date-rule) 'DAILY)
+             (setf (alist-get 'INTERVAL date-rule) 1)
+             (setf (alist-get 'BYHOUR date-rule nil t) nil)
+             (setf (alist-get 'BYMINUTE date-rule nil t) nil)
+             (setf (alist-get 'BYSECOND date-rule nil t) nil))
+           ;; Recurse with the plain date values:
+           (calendar-dlet
+               ((date date)
+                (entry date-entry))
+             (diary-rrule :rule date-rule :start start-date
+                          :include include-dates :exclude exclude-dates))))))))
+
+(defun di:display-entries ()
+  "Display iCalendar data from a file in the diary.
+
+This function allows you to display the data in an iCalendar-formatted
+file in the diary without importing it.  The data is read directly from
+the currently value of `diary-file'.  If this file contains iCalendar
+data, any events, tasks, and journal entries in the file which occur on
+`original-date' and `number' of days after are formatted for display in
+the diary.  (All three of these variables are dynamically bound by the
+diary when this function is called.)
+
+To use this function, add an '#include \"FILE\"' entry in your diary
+file for each iCalendar file you want to display (see
+`diary-include-string').  Then add `diary-include-other-diary-files' to
+`diary-list-entries-hook'.  (Consider also adding `diary-sort-entries' at
+the end of this hook if you want entries to be displayed in order.)
+Finally, add this function to `diary-nongregorian-listing-hook', so that
+it is called once for each included file when the diary is displayed."
+  (with-no-warnings (defvar original-date) ; the start date
+                    (defvar number) ; number of days to generate entries for
+                    (defvar diary-file)) ; dyn. bound to included file name
+  (let ((diary-buffer (or (find-buffer-visiting diary-file)
+                          (find-file-noselect diary-file))))
+    (when (ical:contains-vcalendar-p diary-buffer)
+      (let ((vcal/idx (ical:parse-and-index diary-file)))
+        (when vcal/idx
+          (let* ((index (cadr vcal/idx))
+                 (absstart (calendar-absolute-from-gregorian original-date))
+                 (absend (+ absstart (1- number))))
+
+            (dolist (absdate (number-sequence absstart absend))
+              (let* ((date (calendar-gregorian-from-absolute absdate))
+                     (to-format (ical:index-get index :date date)))
+                (dolist (component to-format)
+                  ;; Format the entry, with a pointer back to its location
+                  ;; in the parsed buffer:
+                  (let ((marker (make-marker)))
+                    (set-marker marker
+                                (ical:ast-node-meta-get :begin component)
+                                (ical:ast-node-meta-get :buffer component))
+                    (diary-add-to-list
+                     date
+                     (di:format-entry component index)
+                     ""
+                     marker)))))))))))
+
+(defun di:marking-dates-of (component index)
+  "Return the dates in COMPONENT that should be marked in the calendar.
+
+INDEX should be a parse tree index containing the time zone definition
+relevant to COMPONENT; see `icalendar-parse-and-index'.  The dates to
+mark are derived from COMPONENT's start and end date and time, and any
+recurrences it has within the year currently displayed by the calendar.
+
+No dates are returned if COMPONENT's `icalendar-transp' property has the
+value \"TRANSPARENT\" (which means the component does not form a block
+of busy time on a schedule), or if COMPONENT is an `icalendar-vjournal'
+and `diary-icalendar-import-vjournal-as-nonmarking' is non-nil."
+  (ical:with-component component
+    ((ical:dtstart :first dtstart-node :value dtstart)
+     (ical:dtend :first dtend-node :value dtend)
+     (ical:due :value due)
+     (ical:duration :value duration)
+     (ical:rdate :first rdate)
+     (ical:rrule :first rrule)
+     (ical:transp :value transparency))
+    (let* ((start-tz (ical:with-param-of dtstart-node 'ical:tzidparam
+                                         (ical:index-get index :tzid value)))
+           (end
+            (cond
+             (dtend dtend)
+             (due due)
+             (duration (ical:date/time-add-duration dtstart duration start-tz))))
+           dates)
+
+      (unless (or (equal transparency "TRANSPARENT")
+                  (and di:import-vjournal-as-nonmarking
+                       (ical:vjournal-component-p component)))
+        ;; Mark the start date(s) for every (marking) entry:
+        (setq dates (if end
+                        (ical:dates-until dtstart end t)
+                      (list (ical:date/time-to-date
+                             (ical:date/time-to-local dtstart)))))
+        ;; Mark the dates for any recurrences in the displayed calendar year:
+        (let ((year (when (boundp 'displayed-year) ; bound by calendar
+                      displayed-year)))
+          (when (and year (or rdate rrule))
+            (let* ((low (list 1 1 year))
+                   (high (list 12 31 year))
+                   (recs (icr:recurrences-in-window-w/end-times
+                          low high component start-tz)))
+              (dolist (rec recs)
+                (setq dates (append (ical:dates-until (car rec) (cadr rec) t)
+                                    dates)))))))
+      dates)))
+
+(defun di:mark-entries ()
+  "Mark calendar dates for iCalendar data from a file.
+
+This function allows you to mark the dates in an iCalendar-formatted
+file in the calendar without importing it.  The data is read directly
+from the current value of `diary-file' (which is dynamically bound by
+the diary when this function is called).
+
+To use this function, add an '#include \"FILE\"' entry in your diary
+file for each iCalendar file you want to display (see
+`diary-include-string').  Then add `diary-mark-included-diary-files' to
+`diary-mark-entries-hook'.  Finally, add this function to
+`diary-nongregorian-marking-hook', so that it is called once for each
+included file when dates are marked in the calendar."
+  (with-no-warnings (defvar diary-file)) ; dyn. bound to included file name
+  (let ((diary-buffer (or (find-buffer-visiting diary-file)
+                          (find-file-noselect diary-file))))
+    (when (ical:contains-vcalendar-p diary-buffer)
+      (let ((vcal/idx (ical:parse-and-index diary-buffer)))
+        (when vcal/idx
+          (let* ((index (cadr vcal/idx))
+                 (vcalendar (car vcal/idx))
+                 (to-mark
+                  (append (ical:ast-node-children-of 'ical:vevent vcalendar)
+                          (ical:ast-node-children-of 'ical:vjournal vcalendar)
+                          (ical:ast-node-children-of 'ical:vtodo vcalendar)))
+                 (all-dates (mapcan (lambda (c) (di:marking-dates-of c index))
+                                    to-mark))
+                 (dates (seq-uniq
+                         (sort all-dates :lessp #'ical:date< :in-place t))))
+
+            (dolist (date dates)
+              (let ((month (calendar-extract-month date))
+                    (year (calendar-extract-year date)))
+                ;; avoid marking outside the displayed months,
+                ;; to speed things up:
+                (with-current-buffer calendar-buffer
+                  (with-suppressed-warnings
+                      ((free-vars displayed-year
+                                  displayed-month))
+                    (when (and (= year displayed-year)
+                               (<= (1- displayed-month) month)
+                               (<= month (1+ displayed-month)))
+                      (calendar-mark-visible-date date))))))))))))
+
+
+
+(provide 'diary-icalendar)
+
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-") ("icr:" . "icalendar-recur-") ("di:" . "diary-icalendar-"))
+;; End:
+;;; diary-icalendar.el ends here
diff --git a/lisp/calendar/diary-lib.el b/lisp/calendar/diary-lib.el
index 36f9b0ef13b..a7ae6532287 100644
--- a/lisp/calendar/diary-lib.el
+++ b/lisp/calendar/diary-lib.el
@@ -38,15 +38,13 @@
 (defcustom diary-include-string "#include"
   "The string indicating inclusion of another file of diary entries.
 See the documentation for the function `diary-include-other-diary-files'."
-  :type 'string
-  :group 'diary)
+  :type 'string)
 
 (defcustom diary-list-include-blanks nil
   "If nil, do not include days with no diary entry in the list of diary entries.
 Such days will then not be shown in the fancy diary buffer, even if they
 are holidays."
-  :type 'boolean
-  :group 'diary)
+  :type 'boolean)
 
 (defface diary-anniversary '((t :inherit font-lock-keyword-face))
   "Face used for anniversaries in the fancy diary display."
@@ -105,29 +103,24 @@ are: `string', `symbol', `int', `tnil', `stringtnil'."
                                (const :value int    :tag "An integer")
                                (const :value tnil   :tag "t or nil")
                                (const :value stringtnil
-                                      :tag "A string, t, or nil"))))
-  :group 'diary)
+                                      :tag "A string, t, or nil")))))
 
 (defcustom diary-glob-file-regexp-prefix "^#"
   "Regular expression prepended to `diary-face-attrs' for file-wide specifiers."
-  :type 'regexp
-  :group 'diary)
+  :type 'regexp)
 
 (defcustom diary-file-name-prefix nil
   "Non-nil means prefix each diary entry with the name of the file defining it."
-  :type 'boolean
-  :group 'diary)
+  :type 'boolean)
 
 (defcustom diary-file-name-prefix-function #'identity
   "The function that will take a diary file name and return the desired prefix."
-  :type 'function
-  :group 'diary)
+  :type 'function)
 
 (defcustom diary-sexp-entry-symbol "%%"
   "The string used to indicate a sexp diary entry in `diary-file'.
 See the documentation for the function `diary-list-sexp-entries'."
-  :type 'string
-  :group 'diary)
+  :type 'string)
 
 (defcustom diary-comment-start nil
   "String marking the start of a comment in the diary, or nil.
@@ -138,24 +131,21 @@ for whatever you like, e.g. for meta-data that packages such as
 can be only one comment on any line.
 See also `diary-comment-end'."
   :version "24.1"
-  :type '(choice (const :tag "No comment" nil) string)
-  :group 'diary)
+  :type '(choice (const :tag "No comment" nil) string))
 
 (defcustom diary-comment-end ""
   "String marking the end of a comment in the diary.
 The empty string means comments finish at the end of a line.
 See also `diary-comment-start'."
   :version "24.1"
-  :type 'string
-  :group 'diary)
+  :type 'string)
 
 (defcustom diary-hook nil
   "Hook run after displaying the diary.
 Used for example by the appointment package - see `appt-activate'.
 The variables `number' and `original-date' are dynamically bound around
 the call."
-  :type 'hook
-  :group 'diary)
+  :type 'hook)
 
 (defcustom diary-display-function #'diary-fancy-display
   "Function used to display the diary.
@@ -171,10 +161,9 @@ holidays), or hard copy output."
                  (const :tag "Basic display" diary-simple-display)
                  (const :tag "No display" ignore)
                  (function :tag "User-specified function"))
-  :initialize 'custom-initialize-default
-  :set 'diary-set-maybe-redraw
-  :version "23.2"                       ; simple->fancy
-  :group 'diary)
+  :initialize #'custom-initialize-default
+  :set #'diary-set-maybe-redraw
+  :version "23.2")                       ; simple->fancy
 
 (defcustom diary-list-entries-hook nil
   "Hook run after diary file is culled for relevant entries.
@@ -201,8 +190,7 @@ So for example, to sort the complete list of diary entries you would
 use the list-entries hook, whereas to process e.g. Islamic entries in
 the main file and all included files, you would use the nongregorian hook."
   :type 'hook
-  :options '(diary-include-other-diary-files diary-sort-entries)
-  :group 'diary)
+  :options '(diary-include-other-diary-files diary-sort-entries))
 
 (defcustom diary-mark-entries-hook nil
   "List of functions called after marking diary entries in the calendar.
@@ -218,8 +206,7 @@ differ only if you are using included diary files.  In that case,
 `displayed-year' and `displayed-month' are dynamically bound when
 this hook is called."
   :type 'hook
-  :options '(diary-mark-included-diary-files)
-  :group 'diary)
+  :options '(diary-mark-included-diary-files))
 
 (defcustom diary-nongregorian-listing-hook nil
   "List of functions called for listing diary file and included files.
@@ -236,8 +223,7 @@ use `diary-list-entries-hook', which runs only for the main diary file."
   :options '(diary-bahai-list-entries
              diary-hebrew-list-entries
              diary-islamic-list-entries
-             diary-chinese-list-entries)
-  :group 'diary)
+             diary-chinese-list-entries))
 
 (defcustom diary-nongregorian-marking-hook nil
   "List of functions called for marking diary file and included files.
@@ -254,8 +240,7 @@ use `diary-mark-entries-hook', which runs only for the main diary file."
   :options '(diary-bahai-mark-entries
              diary-hebrew-mark-entries
              diary-islamic-mark-entries
-             diary-chinese-mark-entries)
-  :group 'diary)
+             diary-chinese-mark-entries))
 
 (defcustom diary-print-entries-hook #'lpr-buffer
   "Run by `diary-print-entries' after preparing a temporary diary buffer.
@@ -264,8 +249,7 @@ diary buffer.  The default just does the printing.  Other uses
 might include, for example, rearranging the lines into order by
 day and time, saving the buffer instead of deleting it, or
 changing the function used to do the printing."
-  :type 'hook
-  :group 'diary)
+  :type 'hook)
 
 (defcustom diary-unknown-time -9999
   "Value returned by `diary-entry-time' when no time is found.
@@ -273,19 +257,16 @@ The default value -9999 causes entries with no recognizable time
 to be placed before those with times; 9999 would place entries
 with no recognizable time after those with times."
   :type 'integer
-  :group 'diary
   :version "20.3")
 
 (defcustom diary-mail-addr
   (or (bound-and-true-p user-mail-address) "")
   "Email address that `diary-mail-entries' will send email to."
-  :group 'diary
   :type  'string
   :version "20.3")
 
 (defcustom diary-mail-days 7
   "Default number of days for `diary-mail-entries' to check."
-  :group 'diary
   :type 'integer
   :version "20.3")
 
@@ -302,8 +283,7 @@ Used by the function `diary-remind', a pseudo-pattern is a list of
 expressions that can involve the keywords `days' (a number), `date'
 \(a list of month, day, year), and `diary-entry' (a string)."
   :type 'sexp
-  :risky t
-  :group 'diary)
+  :risky t)
 
 (defcustom diary-abbreviated-year-flag t
   "Interpret a two-digit year DD in a diary entry as either 19DD or 20DD.
@@ -312,8 +292,7 @@ When the current century is added to a two-digit year, if the result
 is more than 50 years in the future, the previous century is assumed.
 If the result is more than 50 years in the past, the next century is assumed.
 If this variable is nil, years must be written in full."
-  :type 'boolean
-  :group 'diary)
+  :type 'boolean)
 
 (defun diary-outlook-format-1 (body)
   "Return a replace-match template for an element of `diary-outlook-formats'.
@@ -378,8 +357,7 @@ template following the rules above."
                              (string :tag "Template for entry")
                              (function :tag
                                        "Unary function providing template")))
-  :version "22.1"
-  :group 'diary)
+  :version "22.1")
 
 (defvar diary-header-line-flag)
 (defvar diary-header-line-format)
@@ -401,10 +379,9 @@ template following the rules above."
 (defcustom diary-header-line-flag t
   "Non-nil means `diary-simple-display' will show a header line.
 The format of the header is specified by `diary-header-line-format'."
-  :group   'diary
   :type    'boolean
-  :initialize 'custom-initialize-default
-  :set 'diary-set-header
+  :initialize #'custom-initialize-default
+  :set #'diary-set-header
   :version "22.1")
 
 (defvar diary-selective-display nil
@@ -418,11 +395,10 @@ The format of the header is specified by `diary-header-line-format'."
            ?\s (window-width)))
   "Format of the header line displayed by `diary-simple-display'.
 Only used if `diary-header-line-flag' is non-nil."
-  :group 'diary
   :type 'sexp
   :risky t
-  :initialize 'custom-initialize-default
-  :set 'diary-set-header
+  :initialize #'custom-initialize-default
+  :set #'diary-set-header
   :version "23.3")                      ; frame-width -> window-width
 
 ;; The first version of this also checked for diary-selective-display
@@ -480,9 +456,8 @@ of days of diary entries displayed."
                          (integer :tag "Thursday")
                          (integer :tag "Friday")
                          (integer :tag "Saturday")))
-  :initialize 'custom-initialize-default
-  :set 'diary-set-maybe-redraw
-  :group 'diary)
+  :initialize #'custom-initialize-default
+  :set #'diary-set-maybe-redraw)
 
 ;;; More user options in calendar.el, holidays.el.
 
@@ -1443,9 +1418,9 @@ marks.  This is intended to deal with deleted diary entries."
                           (entry entry))
            (if calendar-debug-sexp
                (let ((debug-on-error t))
-                 (eval (car (read-from-string sexp))))
+                 (eval (car (read-from-string sexp)) t))
              (condition-case err
-                 (eval (car (read-from-string sexp)))
+                 (eval (car (read-from-string sexp)) t)
                (error
                 (display-warning
                  'diary
@@ -1671,7 +1646,7 @@ be used instead of a colon (:) to separate the hour and minute parts."
 If you add this function to `diary-list-entries-hook', it should
 be the last item in the hook, in case earlier items add diary
 entries, or change the order."
-  (setq diary-entries-list (sort diary-entries-list 'diary-entry-compare)))
+  (setq diary-entries-list (sort diary-entries-list #'diary-entry-compare)))
 
 
 (defun diary-list-sexp-entries (date)
@@ -2027,7 +2002,7 @@ Entry applies if the date is DAYS days after another diary-sexp SEXP."
     (user-error "Days must be an integer"))
   (let ((date (calendar-gregorian-from-absolute
                (- (calendar-absolute-from-gregorian date) days))))
-    (eval sexp)))
+    (eval sexp t)))
 
 (defun diary-day-of-year ()
   "Day of year and number of days remaining in the year of date diary entry."
@@ -2058,7 +2033,7 @@ calendar."
   (and (integerp days)
        (< days 0)
        (setq days (number-sequence 1 (- days))))
-  (calendar-dlet ((diary-entry (eval sexp)))
+  (calendar-dlet ((diary-entry (eval sexp t)))
     (cond
      ;; Diary entry applies on date.
      ((and diary-entry
@@ -2071,7 +2046,7 @@ calendar."
       ;; Adjust date, and re-evaluate.
       (let ((date (calendar-gregorian-from-absolute
                    (+ (calendar-absolute-from-gregorian date) days))))
-        (when (setq diary-entry (eval sexp))
+        (when (setq diary-entry (eval sexp t))
           ;; Discard any mark portion from diary-anniversary, etc.
           (if (consp diary-entry) (setq diary-entry (cdr diary-entry)))
           (calendar-dlet ((days days))
@@ -2120,8 +2095,9 @@ show the diary buffer."
 Prefix argument ARG makes the entry nonmarking."
   (interactive
    (list current-prefix-arg last-nonmenu-event))
-  (diary-make-entry (calendar-date-string (calendar-cursor-to-date t event) t t)
-                    arg))
+  (calendar-dlet ((calendar-date-display-form diary-date-insertion-form))
+    (diary-make-entry (calendar-date-string (calendar-cursor-to-date t event) t t)
+                      arg)))
 
 ;;;###cal-autoload
 (defun diary-insert-weekly-entry (arg)
@@ -2299,7 +2275,7 @@ full month names."
                                   "")
                        ;; With backup, last item is not part of date.
                        (if (equal (car x) 'backup)
-                           (concat "\\)" (eval (car (reverse x))))
+                           (concat "\\)" (eval (car (reverse x)) t))
                          "\\)"))
                '(1 'diary)))
             diary-date-forms)))
@@ -2318,6 +2294,10 @@ return a font-lock pattern matching array of MONTHS and marking SYMBOL."
   ;; Accepted formats: 10:00 10.00 10h00 10h 10am 10:00am 10.00am
   ;; Use of "." as a separator annoyingly matches numbers, eg "123.45".
   ;; Hence often prefix this with "\\(^\\|\\s-\\)."
+  ;; FIXME: this regexp is too liberal to be used for parsing times from
+  ;; entries by `diary-icalendar-parse-time', hence the existence of
+  ;; `diary-icalendar-time-regexp'.  Can we tighten it up so we don't
+  ;; need both?
   (concat "[0-9]?[0-9]\\([AaPp][mM]\\|\\("
           "[Hh]\\([0-9][0-9]\\)?\\|[:.][0-9][0-9]"
           "\\)\\([AaPp][Mm]\\)?\\)")
diff --git a/lisp/calendar/icalendar-ast.el b/lisp/calendar/icalendar-ast.el
new file mode 100644
index 00000000000..e9c289f16db
--- /dev/null
+++ b/lisp/calendar/icalendar-ast.el
@@ -0,0 +1,957 @@
+;;; icalendar-ast.el --- Syntax trees for iCalendar  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024 Free Software Foundation, Inc.
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: October 2024
+;; Keywords: calendar
+;; Human-Keywords: calendar, iCalendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file defines the abstract syntax tree representation for
+;; iCalendar data.  The AST is based on `org-element-ast' (which see;
+;; that feature will eventually be renamed and moved out of the Org tree
+;; into the main tree).
+
+;; This file contains low-level functions for constructing and
+;; manipulating the AST, most of which are minimal wrappers around the
+;; functions provided by `org-element-ast'.  This low-level API is
+;; primarily used by `icalendar-parser'.  It also contains a higher-level
+;; API for constructing AST nodes in Lisp code.  Finally, it defines
+;; functions for validating AST nodes.
+
+;; There are three main pieces of data in an AST node: its type, its
+;; value, and its child nodes.  Nodes which represent iCalendar
+;; components have no values; they are simply containers for their
+;; children.  Nodes which represent data of the base iCalendar data
+;; types have no children; they are the leaf nodes in the syntax tree.
+;; The main low-level accessors for these data in AST nodes are:
+;;
+;;   `icalendar-ast-node-type'
+;;   `icalendar-ast-node-value'
+;;   `icalendar-ast-node-children'
+;;   `icalendar-ast-node-children-of'
+;;   `icalendar-ast-node-first-child-of'
+
+;; To construct AST nodes in Lisp code, see especially the high-level macros:
+;;
+;;   `icalendar-make-vcalendar'
+;;   `icalendar-make-vtimezone'
+;;   `icalendar-make-vevent'
+;;   `icalendar-make-vtodo'
+;;   `icalendar-make-vjournal'
+;;   `icalendar-make-property'
+;;   `icalendar-make-param'
+;;
+;; These macros wrap the macro `icalendar-make-node-from-templates',
+;; which allows writing iCalendar syntax tree nodes as Lisp templates.
+
+;; Constructing nodes with these macros automatically validates them
+;; with the function `icalendar-ast-node-valid-p', which signals an
+;; `icalendar-validation-error' if the node is not valid acccording to
+;; RFC5545.
+
+
+;;; Code:
+(eval-when-compile (require 'icalendar-macs))
+(require 'icalendar)
+(require 'org-element-ast)
+(require 'cl-lib)
+
+;;; Type symbols and metadata
+
+;; All nodes in the syntax tree have a type symbol as their first element.
+;; We use the following symbol properties (all prefixed with 'icalendar-')
+;; to associate type symbols with various important data about the type:
+;;
+;; is-type - t (marks this symbol as an icalendar type)
+;; is-value, is-param, is-property, or is-component - t
+;;   (specifies what sort of value this type represents)
+;; list-sep - for property and parameters types, a string (typically
+;;   "," or ";") which separates individual printed values, if the
+;;   type allows lists of values.  If this is non-nil, syntax nodes of
+;;   this type should always have a list of values in their VALUE
+;;   field (even if there is only one value)
+;; matcher - a function to match this type.  This function matches the
+;;   regular expression defined under the type's name; it is used to provide
+;;   syntax highlighting in `icalendar-mode'
+;; begin-rx, end-rx - for component-types, an `rx' regular expression which
+;;   matches the BEGIN and END lines that form its boundaries
+;; value-rx - an `rx' regular expression which matches individual values
+;;   of this type, with no consideration for quoting or lists of values.
+;;   (For value types, this is just a synonym for the rx definition
+;;   under the type's symbol)
+;; values-rx - for types that accept lists of values, an `rx' regular
+;;   expression which matches the whole list (including quotes, if required)
+;; full-value-rx - for property and parameter types, an `rx' regular
+;;   expression which matches a valid value expression in group 2, or
+;;   an invalid value in group 3
+;; value-reader - for value types, a function which creates syntax
+;;   nodes of this type given a string representing their value
+;; value-printer - for value types, a function to print individual
+;;   values of this type.  It accepts a value and returns its string
+;;   representation.
+;; default-value - for property and parameter types, a string
+;;   representing a default value for nodes of this type.  This is the
+;;   value assumed when no node of this type is present in the
+;;   relevant part of the syntax tree.
+;; substitute-value - for parameter types, a string representing a value
+;;   which will be substituted at parse times for unrecognized values.
+;;   (This is normally the same as default-value, but differs from it
+;;   in at least one case in RFC5545, thus it is stored separately.)
+;; default-type - for property types which can accept values of multiple
+;;   types, this is the default type when no type for the value is
+;;   specified in the parameters.  Any type of value other than this
+;;   one requires a VALUE=... parameter when the property is read or printed.
+;; other-types - for property types which can accept values of multiple types,
+;;   this is a list of other types that the property can accept.
+;; value-type - for param types, this is the value type which the parameter
+;;   can accept.
+;; child-spec - for property and component types, a plist describing the
+;;   required and optional child nodes.  See `icalendar-define-property' and
+;;   `icalendar-define-component' for details.
+;; other-validator - a function to perform type-specific validation
+;;   for nodes of this type.  If present, this function will be called
+;;   by `icalendar-ast-node-valid-p' during validation.
+;; type-documentation - a string documenting the type.  This documentation is
+;;   printed in the help buffer when `describe-symbol' is called on TYPE.
+;; link - a hyperlink to the documentation of the type in the relevant standard
+
+(defun ical:type-symbol-p (symbol)
+  "Return non-nil if SYMBOL is an iCalendar type symbol.
+
+This function only checks that SYMBOL has been marked as a type;
+it returns t for value types defined by `icalendar-define-type',
+but also e.g. for types defined by `icalendar-define-param' and
+`icalendar-define-property'.  To check that SYMBOL names a value
+type for property or parameter values, see
+`icalendar-value-type-symbol-p' and
+`icalendar-printable-value-type-symbol-p'."
+  (and (symbolp symbol)
+       (get symbol 'ical:is-type)))
+
+(defun ical:value-type-symbol-p (symbol)
+  "Return non-nil if SYMBOL is a type symbol for a value type.
+
+This means that SYMBOL must both satisfy `icalendar-type-symbol-p' and
+have the property `icalendar-is-value'.  It does not require the type to
+be associated with a print name in `icalendar-value-types'; for that see
+`icalendar-printable-value-type-symbol-p'."
+  (and (ical:type-symbol-p symbol)
+       (get symbol 'ical:is-value)))
+
+(defun ical:expects-list-of-values-p (type)
+  "Return non-nil if TYPE expects a list of values.
+
+This is never t for value types or component types.  For property and
+parameter types defined with `icalendar-define-param' and
+`icalendar-define-property', it is true if the :list-sep argument was
+specified in the definition."
+  (and (ical:type-symbol-p type)
+       (get type 'ical:list-sep)))
+
+(defun ical:param-type-symbol-p (type)
+  "Return non-nil if TYPE is a type symbol for an iCalendar parameter."
+  (and (ical:type-symbol-p type)
+       (get type 'ical:is-param)))
+
+(defun ical:property-type-symbol-p (type)
+  "Return non-nil if TYPE is a type symbol for an iCalendar property."
+  (and (ical:type-symbol-p type)
+       (get type 'ical:is-property)))
+
+(defun ical:component-type-symbol-p (type)
+  "Return non-nil if TYPE is a type symbol for an iCalendar component."
+  (and (ical:type-symbol-p type)
+       (get type 'ical:is-component)))
+
+;; TODO: we could define other accessors here for the other metadata
+;; properties, but at the moment I see no advantage to this; they would
+;; all just be long-winded wrappers around `get'.
+
+
+;; The basic, low-level API for the AST, mostly intended for use by
+;; `icalendar-parser'.  These functions are mostly aliases and simple
+;; wrappers around functions provided by `org-element-ast', which does
+;; the heavy lifting.
+(defalias 'ical:ast-node-type #'org-element-type)
+
+(defsubst ical:ast-node-value (node)
+  "Return the value of iCalendar syntax node NODE.
+In component nodes, this is nil.  Otherwise, it is a syntax node
+representing an iCalendar (property or parameter) value."
+  (org-element-property :value node))
+
+(defalias 'ical:ast-node-children #'org-element-contents)
+
+;; TODO: probably don't want &rest form for this
+(defalias 'ical:ast-node-set-children #'org-element-set-contents)
+
+(defalias 'ical:ast-node-adopt-children #'org-element-adopt-elements)
+
+(defalias 'ical:ast-node-meta-get #'org-element-property)
+
+(defalias 'ical:ast-node-meta-set #'org-element-put-property)
+
+(defun ical:ast-node-set-type (node type)
+  "Set the type of iCalendar syntax node NODE to TYPE.
+
+This function is probably not what you want!  It directly modifies the
+type of NODE in-place, which could make the node invalid if its value or
+children do not match the new TYPE.  If you do not know in advance that
+the data in NODE is compatible with the new TYPE, it is better to
+construct a new syntax node."
+  (setcar node type))
+
+(defun ical:ast-node-set-value (node value)
+  "Set the value of iCalendar syntax node NODE to VALUE."
+  (ical:ast-node-meta-set node :value value))
+
+(defun ical:make-ast-node (type props &optional children)
+  "Construct a syntax node of TYPE with meta-properties PROPS and CHILDREN.
+
+This is a low-level constructor.  If you are constructing iCalendar
+syntax nodes directly in Lisp code, consider using one of the
+higher-level macros based on `icalendar-make-node-from-templates'
+instead, which expand to calls to this function but also perform type
+checking and validation.
+
+TYPE should be an iCalendar type symbol.  CHILDREN, if given, should be
+a list of syntax nodes.  In property nodes, these should be the
+parameters of the property.  In component nodes, these should be the
+properties or subcomponents of the component.  CHILDREN should otherwise
+be nil.
+
+PROPS should be a plist with any of the following keywords:
+
+:value - in value nodes, this should be the Elisp value parsed from a
+  property or parameter's value string.  In parameter and property nodes,
+  this should be a value node or list of value nodes.  In component
+  nodes, it should not be present.
+:buffer - buffer from which VALUE was parsed
+:begin - position at which this node begins in BUFFER
+:end - position at which this node ends in BUFFER
+:value-begin - position at which VALUE begins in BUFFER
+:value-end - position at which VALUE ends in BUFFER
+:original-value - a string containing the original, uninterpreted value
+  of the node.  This can differ from (a string represented by) VALUE
+  if e.g. a default VALUE was substituted for an unrecognized but
+  syntactically correct value.
+:original-name - a string containing the original, uninterpreted name
+  of the parameter, property or component this node represents.
+  This can differ from (a string representing) TYPE
+  if e.g. a default TYPE was substituted for an unrecognized but
+  syntactically correct one."
+  ;; automatically mark :value as a "secondary property" for org-element-ast
+  (let ((full-props (if (plist-member props :value)
+                        (plist-put props :secondary (list :value))
+                      props)))
+    (apply #'org-element-create type full-props children)))
+
+(defun ical:ast-node-p (val)
+  "Return non-nil if VAL is an iCalendar syntax node."
+  (and (listp val)
+       (length> val 1)
+       (ical:type-symbol-p (ical:ast-node-type val))
+       (plistp (cadr val))
+       (listp (ical:ast-node-children val))))
+
+(defun ical:param-node-p (node)
+  "Return non-nil if NODE is a syntax node whose type is a parameter type."
+  (and (ical:ast-node-p node)
+       (ical:param-type-symbol-p (ical:ast-node-type node))))
+
+(defun ical:property-node-p (node)
+  "Return non-nil if NODE is a syntax node whose type is a property type."
+  (and (ical:ast-node-p node)
+       (ical:property-type-symbol-p (ical:ast-node-type node))))
+
+(defun ical:component-node-p (node)
+  "Return non-nil if NODE is a syntax node whose type is a component type."
+  (and (ical:ast-node-p node)
+       (ical:component-type-symbol-p (ical:ast-node-type node))))
+
+(defun ical:ast-node-first-child-of (type node)
+  "Return the first child of NODE of type TYPE, or nil."
+  (assq type (ical:ast-node-children node)))
+
+(defun ical:ast-node-children-of (type node)
+  "Return a list of all the children of NODE of type TYPE."
+  (seq-filter (lambda (c) (eq type (ical:ast-node-type c)))
+              (ical:ast-node-children node)))
+
+
+;; A high-level API for constructing iCalendar syntax nodes in Lisp code:
+(defun ical:type-of (value &optional types)
+  "Find the iCalendar type symbol for the type to which VALUE belongs.
+
+TYPES, if specified, should be a list of type symbols to check.
+TYPES defaults to all type symbols listed in `icalendar-value-types'."
+  (require 'icalendar-parser) ; for ical:value-types, ical:list-of-p
+  (declare-function ical:list-of-p "icalendar-parser")
+  (catch 'found
+    (when (ical:ast-node-p value)
+      (throw 'found (ical:ast-node-type value)))
+    ;; FIXME:  the warning here is spurious, given that icalendar-parser
+    ;; is require'd above:
+    (with-suppressed-warnings ((free-vars ical:value-types))
+      (dolist (type (or types (mapcar #'cdr ical:value-types)))
+        (if (ical:expects-list-of-values-p type)
+            (when (ical:list-of-p value type)
+              (throw 'found type))
+          (when (cl-typep value type)
+            (throw 'found type)))))))
+
+;; A more flexible constructor for value nodes which can choose the
+;; correct type from a list.  This helps keep templates succinct and easy
+;; to use in `icalendar-make-node-from-templates', and related macros
+;; below.
+(defun ical:make-value-node-of (type value)
+  "Make an iCalendar syntax node of type TYPE containing VALUE as its value.
+
+TYPE should be a symbol for an iCalendar value type, and VALUE should be
+a value of that type.  If TYPE is the symbol \\='plain-text, VALUE should
+be a string, and in that case VALUE is returned as-is.
+
+TYPE may also be a list of type symbols; in that case, the first type in
+the list which VALUE satisfies is used as the returned node's type.  If
+the list is nil, VALUE will be checked against all types in
+`icalendar-value-types'.
+
+If VALUE is nil, and `icalendar-boolean' is not (in) TYPE, nil is
+returned.  Otherwise, a \\='wrong-type-argument error is signaled if
+VALUE does not satisfy (any type in) TYPE."
+  (require 'icalendar-parser) ; for `icalendar-list-of-p'
+  (cond
+   ((and (null value)
+         (not (if (listp type) (memq 'ical:boolean type)
+                (eq 'ical:boolean type))))
+    ;; Instead of signaling an error, we just return nil in this case.
+    ;; This allows the `ical:make-*' macros higher up the stack to
+    ;; filter out templates that evaluate to nil at run time:
+    nil)
+   ((eq type 'plain-text)
+    (unless (stringp value)
+      (signal 'wrong-type-argument (list 'stringp value)))
+    value)
+   ((symbolp type)
+    (unless (ical:value-type-symbol-p type)
+      (signal 'wrong-type-argument (list 'icalendar-value-type-symbol-p type)))
+    (if (ical:expects-list-of-values-p type)
+        (unless (ical:list-of-p value type)
+          (signal 'wrong-type-argument (list `(list-of ,type) value)))
+      (unless (cl-typep value type)
+        (signal 'wrong-type-argument (list type value)))
+      (ical:make-ast-node type (list :value value))))
+   ((listp type)
+    ;; N.B. nil is allowed; in that case, `ical:type-of' will check all
+    ;; types in `ical:value-types':
+    (let ((the-type (ical:type-of value type)))
+      (if the-type
+          (ical:make-ast-node the-type (list :value value))
+        (signal 'wrong-type-argument
+                (list (if (length> type 1) (cons 'or type) (car type))
+                      value)))))
+   (t (signal 'wrong-type-argument (list '(or symbolp listp) type)))))
+
+(defun ical:-make-param--list (type value-type raw-values)
+  "Make a param node of TYPE with list of values RAW-VALUES of type VALUE-TYPE."
+  (let ((value (if (seq-every-p #'ical:ast-node-p raw-values)
+                   raw-values
+                 (mapcar
+                  (lambda (c)
+                    (ical:make-value-node-of value-type c))
+                  raw-values))))
+    (when value
+      (ical:ast-node-valid-p
+       (ical:make-ast-node
+        type
+        (list :value value))))))
+
+(defun ical:-make-param--nonlist (type value-type raw-value)
+  "Make a param node of TYPE with value RAW-VALUE of type VALUE-TYPE."
+  (let ((value (if (ical:ast-node-p raw-value)
+                   raw-value
+                 (ical:make-value-node-of value-type raw-value))))
+    (when value
+      (ical:ast-node-valid-p
+       (ical:make-ast-node
+        type
+        (list :value value))))))
+
+(defmacro ical:make-param (type value)
+  "Construct an iCalendar parameter node of TYPE with value VALUE.
+
+TYPE should be an iCalendar type symbol satisfying
+`icalendar-param-type-symbol-p'; it should not be quoted.
+
+VALUE should evaluate to a value appropriate for TYPE.  In particular, if
+TYPE expects a list of values (see `icalendar-expects-list-p'), VALUE
+should be such a list.  If necessary, the value(s) in VALUE will be
+wrapped in syntax nodes indicating their type.
+
+For example,
+
+  (icalendar-make-param icalendar-deltoparam
+    (list \"mailto:minionA@example.com\" \"mailto:minionB@example.com\"))
+
+will return an `icalendar-deltoparam' node whose value is a list of
+`icalendar-cal-address' nodes containing the two addresses.
+
+The resulting syntax node is checked for validity by
+`icalendar-ast-node-valid-p' before it is returned."
+  (declare (debug (symbolp form)))
+  ;; TODO: support `ical:otherparam'
+  (unless (ical:param-type-symbol-p type)
+    (error "Not an iCalendar param type: %s" type))
+  (let ((value-type (or (get type 'ical:value-type) 'plain-text)))
+    (if (ical:expects-list-of-values-p type)
+        `(ical:-make-param--list ',type ',value-type ,value)
+      `(ical:-make-param--nonlist ',type ',value-type ,value))))
+
+(defun ical:-make-property--list (type value-types raw-values &optional params)
+  "Make a property node of TYPE with list of values RAW-VALUES.
+VALUE-TYPES should be a list of value types that TYPE accepts.
+PARAMS, if given, should be a list of parameter nodes."
+  (require 'icalendar-parser) ; for `ical:maybe-add-value-param'
+  (declare-function ical:maybe-add-value-param "icalendar-parser")
+
+  (let ((value (if (seq-every-p #'ical:ast-node-p raw-values)
+                   raw-values
+                 (mapcar
+                  (lambda (c) (ical:make-value-node-of value-types c))
+                  raw-values))))
+    (when value
+      (ical:ast-node-valid-p
+       (ical:maybe-add-value-param
+        (ical:make-ast-node type (list :value value) params))))))
+
+(defun ical:-make-property--nonlist (type value-types raw-value &optional params)
+  "Make a property node of TYPE with value RAW-VALUE.
+VALUE-TYPES should be a list of value types that TYPE accepts.
+PARAMS, if given, should be a list of parameter nodes."
+  (require 'icalendar-parser) ; for `ical:maybe-add-value-param'
+  (declare-function ical:maybe-add-value-param "icalendar-parser")
+
+  (let ((value (if (ical:ast-node-p raw-value)
+                   raw-value
+                 (ical:make-value-node-of value-types raw-value))))
+    (when value
+      (ical:ast-node-valid-p
+       (ical:maybe-add-value-param
+        (ical:make-ast-node type (list :value value) params))))))
+
+(defmacro ical:make-property (type value &rest param-templates)
+  "Construct an iCalendar property node of TYPE with value VALUE.
+
+TYPE should be an iCalendar type symbol satisfying
+`icalendar-property-type-symbol-p'; it should not be quoted.
+
+VALUE should evaluate to a value appropriate for TYPE.  In particular,
+if TYPE expects a list of values (see
+`icalendar-expects-list-of-values-p'), VALUE should be such a list.  If
+necessary, the value(s) in VALUE will be wrapped in syntax nodes
+indicating their type.  If VALUE is not of the default value type for
+TYPE, an `icalendar-valuetypeparam' will automatically be added to
+PARAM-TEMPLATES.
+
+Each element of PARAM-TEMPLATES should represent a parameter node; see
+`icalendar-make-node-from-templates' for the format of such templates.
+A template can also have the form (@ L), where L evaluates to a list of
+parameter nodes to be added to the component.
+
+PARAM-TEMPLATES which evaluate to nil are removed when the property node
+is constructed.
+
+For example,
+
+  (icalendar-make-property icalendar-rdate (list \\='(2 1 2025) \\='(3 1 2025)))
+
+will return an `icalendar-rdate' node whose value is a list of
+`icalendar-date' nodes containing the dates above as their values.
+
+The resulting syntax node is checked for validity by
+`icalendar-ast-node-valid-p' before it is returned."
+  ;; TODO: support `ical:other-property', maybe like
+  ;; (ical:other-property "X-NAME" value ...)
+  (declare (debug (symbolp form &rest form))
+           (indent 2))
+  (unless (ical:property-type-symbol-p type)
+    (error "Not an iCalendar property type: %s" type))
+  (let ((value-types (cons (get type 'ical:default-type)
+                           (get type 'ical:other-types)))
+        params-expr children lists-of-children)
+    (dolist (c param-templates)
+      (cond ((and (listp c) (ical:type-symbol-p (car c)))
+             ;; c is a template for a child node, so it should be
+             ;; recursively expanded:
+             (push (cons 'ical:make-node-from-templates c)
+                   children))
+            ((and (listp c) (eq '@ (car c)))
+             ;; c is a template (@ L) where L evaluates to a list of children:
+             (push (cadr c) lists-of-children))
+            (t
+             ;; otherwise, just pass c through as is; this allows
+             ;; interleaving templates with other expressions that
+             ;; evaluate to syntax nodes:
+             (push c children))))
+    (when (or children lists-of-children)
+      (setq params-expr
+            `(seq-filter #'identity
+                         (append (list ,@children) ,@lists-of-children))))
+
+    (if (ical:expects-list-of-values-p type)
+        `(ical:-make-property--list ',type ',value-types ,value ,params-expr)
+      `(ical:-make-property--nonlist ',type ',value-types ,value ,params-expr))))
+
+(defmacro ical:make-component (type &rest templates)
+  "Construct an iCalendar component node of TYPE from TEMPLATES.
+
+TYPE should be an iCalendar type symbol satisfying
+`icalendar-component-type-symbol-p'; it should not be quoted.
+
+Each expression in TEMPLATES should represent a child node of the
+component; see `icalendar-make-node-from-templates' for the format of
+such TEMPLATES.  A template can also have the form (@ L), where L
+evaluates to a list of child nodes to be added to the component.
+
+Any value in TEMPLATES that evaluates to nil will be removed before the
+component node is constructed.
+
+If TYPE is `icalendar-vevent', `icalendar-vtodo', `icalendar-vjournal',
+or `icalendar-vfreebusy', the properties `icalendar-dtstamp' and
+`icalendar-uid' will be automatically provided, if they are absent in
+TEMPLATES.  Likewise, if TYPE is `icalendar-vcalendar', the properties
+`icalendar-prodid', `icalendar-version', and `icalendar-calscale' will
+be automatically provided if absent.
+
+For example,
+
+  (icalendar-make-component icalendar-vevent
+     (icalendar-summary \"Party\")
+     (icalendar-location \"Robot House\")
+     (@ list-of-other-properties))
+
+will return an `icalendar-vevent' node containing the provided
+properties as well as `icalendar-dtstamp' and `icalendar-uid'
+properties.
+
+The resulting syntax node is checked for validity by
+`icalendar-ast-node-valid-p' before it is returned."
+  (declare (debug (symbolp &rest form))
+           (indent 1))
+  ;; TODO: support `ical:other-component', maybe like
+  ;; (ical:other-component (:x-name "X-NAME") templates ...)
+  (unless (ical:component-type-symbol-p type)
+    (error "Not an iCalendar component type: %s" type))
+  ;; Add templates for required properties automatically if we can:
+  (when (memq type '(ical:vevent ical:vtodo ical:vjournal ical:vfreebusy))
+    (unless (assq 'ical:dtstamp templates)
+      (push '(ical:dtstamp (decode-time nil t))
+            templates))
+    (unless (assq 'ical:uid templates)
+      (push `(ical:uid ,(ical:make-uid templates))
+            templates)))
+  (when (eq type 'ical:vcalendar)
+    (unless (assq 'ical:prodid templates)
+      (push `(ical:prodid ,ical:vcalendar-prodid)
+            templates))
+    (unless (assq 'ical:version templates)
+      (push `(ical:version ,ical:vcalendar-version)
+            templates))
+    (unless (assq 'ical:calscale templates)
+      (push '(ical:calscale "GREGORIAN")
+            templates)))
+  (when (null templates)
+    (error "At least one template is required"))
+
+  (let (children lists-of-children)
+    (dolist (c templates)
+      (cond ((and (listp c) (ical:type-symbol-p (car c)))
+             ;; c is a template for a child node, so it should be
+             ;; recursively expanded:
+             (push (cons 'ical:make-node-from-templates c)
+                   children))
+            ((and (listp c) (eq '@ (car c)))
+             ;; c is a template (@ L) where L evaluates to a list of children:
+             (push (cadr c) lists-of-children))
+            (t
+             ;; otherwise, just pass c through as is; this allows
+             ;; interleaving templates with other expressions that
+             ;; evaluate to syntax nodes:
+             (push c children))))
+    (setq children (nreverse children)
+          lists-of-children (nreverse lists-of-children))
+    (when (or children lists-of-children)
+      `(ical:ast-node-valid-p
+        (ical:make-ast-node
+         (quote ,type)
+         nil
+         (seq-filter #'identity
+                     (append (list ,@children) ,@lists-of-children)))))))
+
+;; TODO: allow disabling the validity check??
+(defmacro ical:make-node-from-templates (type &rest templates)
+  "Construct an iCalendar syntax node of TYPE from TEMPLATES.
+
+TYPE should be an iCalendar type symbol; it should not be quoted.  This
+macro (and the derived macros `icalendar-make-vcalendar',
+`icalendar-make-vevent', `icalendar-make-vtodo',
+`icalendar-make-vjournal', `icalendar-make-vfreebusy',
+`icalendar-make-valarm', `icalendar-make-vtimezone',
+`icalendar-make-standard', and `icalendar-make-daylight') makes it easy
+to write iCalendar syntax nodes of TYPE as Lisp code.
+
+Each expression in TEMPLATES represents a child node of the constructed
+node.  It must either evaluate to such a node, or it must have one of
+the following forms:
+
+\(VALUE-TYPE VALUE) - constructs a node of VALUE-TYPE containing the
+  value VALUE.
+
+\(PARAM-TYPE VALUE) - constructs a parameter node of PARAM-TYPE
+  containing the VALUE.
+
+\(PROPERTY-TYPE VALUE [PARAM ...]) - constructs a property node of
+  PROPERTY-TYPE containing the value VALUE and PARAMs as child
+  nodes.  Each PARAM should be a template (PARAM-TYPE VALUE), as above,
+  or any other expression that evaluates to a parameter node.
+
+\(COMPONENT-TYPE CHILD [CHILD ...]) - constructs a component node of
+  COMPONENT-TYPE with CHILDs as child nodes.  Each CHILD should either be
+  a template for a property (as above), a template for a
+  sub-component (of the same form), or any other expression that
+  evaluates to an iCalendar syntax node.
+
+If TYPE is an iCalendar component or property type, a TEMPLATE can also
+have the form (@ L), where L evaluates to a list of child nodes to be
+added to the component or property node.
+
+For example, an iCalendar VEVENT could be written like this:
+
+  (icalendar-make-node-from-templates icalendar-vevent
+    (icalendar-dtstamp (decode-time (current-time) 0))
+    (icalendar-uid \"some-unique-id\")
+    (icalendar-summary \"Party\")
+    (icalendar-location \"Robot House\")
+    (icalendar-organizer \"mailto:bender@mars.edu\")
+    (icalendar-attendee  \"mailto:philip.j.fry@mars.edu\"
+      (icalendar-partstatparam \"ACCEPTED\"))
+    (icalendar-attendee  \"mailto:gunther@mars.edu\"
+      (icalendar-partstatparam \"DECLINED\"))
+    (icalendar-categories (list \"MISCHIEF\" \"DOUBLE SECRET PROBATION\"))
+    (icalendar-dtstart (icalendar-make-date-time :year 3003 :month 3 :day 13
+                                                 :hour 22 :minute 0 :second 0)
+       (icalendar-tzidparam \"Mars/University_Time\")))
+
+Before the constructed node is returned, it is validated by
+`icalendar-ast-node-valid-p'."
+  (declare (debug (symbolp &rest form))
+           (indent 1))
+  (cond
+   ((not (ical:type-symbol-p type))
+    (error "Not an iCalendar type symbol: %s" type))
+   ((ical:value-type-symbol-p type)
+    `(ical:ast-node-valid-p
+      (ical:make-value-node-of (quote ,type) ,(car templates))))
+   ((ical:param-type-symbol-p type)
+    `(ical:make-param ,type ,(car templates)))
+   ((ical:property-type-symbol-p type)
+    `(ical:make-property ,type ,(car templates) ,@(cdr templates)))
+   ((ical:component-type-symbol-p type)
+    `(ical:make-component ,type ,@templates))))
+
+(defmacro ical:make-vcalendar (&rest templates)
+  "Construct an iCalendar VCALENDAR object from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-vcalendar' for the permissible child types.
+
+If TEMPLATES does not contain templates for the `icalendar-prodid' and
+`icalendar-version' properties, they will be automatically added; see
+the variables `icalendar-vcalendar-prodid' and
+`icalendar-vcalendar-version'."
+  `(ical:make-node-from-templates ical:vcalendar ,@templates))
+
+(defmacro ical:make-vevent (&rest templates)
+  "Construct an iCalendar VEVENT node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-vevent' for the permissible child types.
+
+If TEMPLATES does not contain templates for the `icalendar-dtstamp' and
+`icalendar-uid' properties (both required), they will be automatically
+provided."
+  `(ical:make-node-from-templates ical:vevent ,@templates))
+
+(defmacro ical:make-vtodo (&rest templates)
+  "Construct an iCalendar VTODO node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-vtodo' for the permissible child types.
+
+If TEMPLATES does not contain templates for the `icalendar-dtstamp' and
+`icalendar-uid' properties (both required), they will be automatically
+provided."
+  `(ical:make-node-from-templates ical:vtodo ,@templates))
+
+(defmacro ical:make-vjournal (&rest templates)
+  "Construct an iCalendar VJOURNAL node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-vjournal' for the permissible child types.
+
+If TEMPLATES does not contain templates for the `icalendar-dtstamp' and
+`icalendar-uid' properties (both required), they will be automatically
+provided."
+  `(ical:make-node-from-templates ical:vjournal ,@templates))
+
+(defmacro ical:make-vfreebusy (&rest templates)
+  "Construct an iCalendar VFREEBUSY node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-vfreebusy' for the permissible child types.
+
+If TEMPLATES does not contain templates for the `icalendar-dtstamp' and
+`icalendar-uid' properties (both required), they will be automatically
+provided."
+  `(ical:make-node-from-templates ical:vfreebusy ,@templates))
+
+(defmacro ical:make-valarm (&rest templates)
+  "Construct an iCalendar VALARM node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-valarm' for the permissible child types."
+  `(ical:make-node-from-templates ical:valarm ,@templates))
+
+(defmacro ical:make-vtimezone (&rest templates)
+  "Construct an iCalendar VTIMEZONE node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-vtimezone' for the permissible child types."
+  `(ical:make-node-from-templates ical:vtimezone ,@templates))
+
+(defmacro ical:make-standard (&rest templates)
+  "Construct an iCalendar STANDARD node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-standard' for the permissible child types."
+  `(ical:make-node-from-templates ical:standard ,@templates))
+
+(defmacro ical:make-daylight (&rest templates)
+  "Construct an iCalendar DAYLIGHT node from TEMPLATES.
+See `icalendar-make-node-from-templates' for the format of TEMPLATES.
+See `icalendar-daylight' for the permissible child types."
+  `(ical:make-node-from-templates ical:daylight ,@templates))
+
+
+;;; Validation:
+
+;; Errors at the validation stage:
+;; e.g. property/param values did not match, or are of the wrong type,
+;; or required properties not present in a component
+(define-error 'ical:validation-error "Invalid iCalendar data" 'ical:error)
+
+(cl-defun ical:signal-validation-error (msg &key node (severity 2))
+  (signal 'ical:validation-error
+              (list :message msg
+                    :buffer (ical:ast-node-meta-get :buffer node)
+                    :position (ical:ast-node-meta-get :begin node)
+                    :severity severity
+                    :node node)))
+
+(defun ical:ast-node-required-child-p (child parent)
+  "Return non-nil if CHILD is required by PARENT's node type."
+  (let* ((type (ical:ast-node-type parent))
+         (child-spec (get type 'ical:child-spec))
+         (child-type (ical:ast-node-type child)))
+    (or (memq child-type (plist-get child-spec :one))
+        (memq child-type (plist-get child-spec :one-or-more)))))
+
+(defun ical:ast-node-valid-value-p (node)
+  "Validate that NODE's value satisfies the requirements of its type.
+Signals an `icalendar-validation-error' if NODE's value is
+invalid, or returns NODE."
+  (require 'icalendar-parser) ; for ical:printable-value-type-symbol-p
+  (declare-function ical:printable-value-type-symbol-p "icalendar-parser")
+  (let* ((type (ical:ast-node-type node))
+         (value (ical:ast-node-value node))
+         (valtype-param (when (ical:property-type-symbol-p type)
+                          (ical:with-param-of node 'ical:valuetypeparam)))
+         (allowed-types
+          (cond ((ical:printable-value-type-symbol-p valtype-param)
+                 ;; with an explicit `VALUE=sometype' param, this is the
+                 ;; only allowed type:
+                 (list valtype-param))
+                ((and (ical:param-type-symbol-p type)
+                      (get type 'ical:value-type))
+                 (list (get type 'ical:value-type)))
+                ((ical:property-type-symbol-p type)
+                 (cons (get type 'ical:default-type)
+                       (get type 'ical:other-types)))
+                (t nil))))
+    (cond ((ical:value-type-symbol-p type)
+           (unless (cl-typep value type) ; see `ical:define-type'
+             (ical:signal-validation-error
+              (format "Invalid value for `%s' node: %s" type value)
+              :node node))
+           node)
+          ((ical:component-node-p node)
+           ;; component types have no value, so no need to check anything
+           node)
+          ((and (or (ical:param-type-symbol-p type)
+                    (ical:property-type-symbol-p type))
+                (null (get type 'ical:value-type))
+                (stringp value))
+           ;; property and param nodes with no value type are assumed to contain
+           ;; strings which match a value regex:
+           (unless (string-match (rx-to-string (get type 'ical:value-rx)) value)
+             (ical:signal-validation-error
+              (format "Invalid string value for `%s' node: %s" type value)
+              :node node))
+           node)
+          ;; otherwise this is a param or property node which itself
+          ;; should have one or more syntax nodes as a value, so
+          ;; recurse on value(s):
+          ((ical:expects-list-of-values-p type)
+           (unless (listp value)
+             (ical:signal-validation-error
+              (format "Expected list of values for `%s' node" type)
+              :node node))
+           (when allowed-types
+             (dolist (v value)
+               (unless (memq (ical:ast-node-type v) allowed-types)
+                 (ical:signal-validation-error
+                  (format "Value of unexpected type `%s' in `%s' node"
+                          (ical:ast-node-type v) type)
+                  :node node))))
+           (mapc #'ical:ast-node-valid-value-p value)
+           node)
+          (t
+           (unless (ical:ast-node-p value)
+             (ical:signal-validation-error
+              (format "Invalid value for `%s' node: %s" type value)
+              :node node))
+           (when allowed-types
+             (unless (memq (ical:ast-node-type value) allowed-types)
+               (ical:signal-validation-error
+                (format "Value of unexpected type `%s' in `%s' node"
+                        (ical:ast-node-type value) type)
+                :node node)))
+           (ical:ast-node-valid-value-p value)))))
+
+(defun ical:count-children-by-type (node)
+  "Count NODE's children by type.
+Returns an alist mapping type symbols to the number of NODE's children
+of that type."
+  (let ((children (ical:ast-node-children node))
+        (map nil))
+    (dolist (child children map)
+      (let* ((type (ical:ast-node-type child))
+             (n (alist-get type map)))
+        (setf (alist-get type map) (1+ (or n 0)))))))
+
+(defun ical:ast-node-valid-children-p (node)
+  "Validate that NODE's children satisfy its type's :child-spec.
+
+The :child-spec is associated with NODE's type by
+`icalendar-define-component', `icalendar-define-property',
+`icalendar-define-param', or `icalendar-define-type', which see.
+Signals an `icalendar-validation-error' if NODE is invalid, or returns
+NODE.
+
+Note that this function does not check that the children of NODE
+are themselves valid; for that, see `ical:ast-node-valid-p'."
+  (let* ((type (ical:ast-node-type node))
+         (child-spec (get type 'ical:child-spec))
+         (child-counts (ical:count-children-by-type node)))
+
+    (when child-spec
+
+      (dolist (child-type (plist-get child-spec :one))
+        (unless (= 1 (alist-get child-type child-counts 0))
+          (ical:signal-validation-error
+            (format "iCalendar `%s' node must contain exactly one `%s'"
+                    type child-type)
+            :node node)))
+
+      (dolist (child-type (plist-get child-spec :one-or-more))
+        (unless (<= 1 (alist-get child-type child-counts 0))
+          (ical:signal-validation-error
+           (format "iCalendar `%s' node must contain one or more `%s'"
+                   type child-type)
+           :node node)))
+
+      (dolist (child-type (plist-get child-spec :zero-or-one))
+        (unless (<= (alist-get child-type child-counts 0)
+                    1)
+          (ical:signal-validation-error
+           (format "iCalendar `%s' node may contain at most one `%s'"
+                   type child-type)
+           :node node)))
+
+      ;; check that all child nodes are allowed:
+      (unless (plist-get child-spec :allow-others)
+        (let ((allowed-types (append (plist-get child-spec :one)
+                                     (plist-get child-spec :one-or-more)
+                                     (plist-get child-spec :zero-or-one)
+                                     (plist-get child-spec :zero-or-more)))
+              (appearing-types (mapcar #'car child-counts)))
+
+          (dolist (child-type appearing-types)
+            (unless (member child-type allowed-types)
+              (ical:signal-validation-error
+               (format "`%s' may not contain `%s'" type child-type)
+               :node node))))))
+    ;; success:
+    node))
+
+(defun ical:ast-node-valid-p (node &optional recursively)
+  "Check that NODE is a valid iCalendar syntax node.
+By default, the check will only validate NODE itself, but if
+RECURSIVELY is non-nil, it will recursively check all its
+descendants as well.  Signals an `icalendar-validation-error' if
+NODE is invalid, or returns NODE."
+  (unless (ical:ast-node-p node)
+    (ical:signal-validation-error
+     "Not an iCalendar syntax node"
+     :node node))
+
+  (ical:ast-node-valid-value-p node)
+  (ical:ast-node-valid-children-p node)
+
+  (let* ((type (ical:ast-node-type node))
+         (other-validator (get type 'ical:other-validator)))
+
+    (unless (ical:type-symbol-p type)
+      (ical:signal-validation-error
+       (format "Node's type `%s' is not an iCalendar type symbol" type)
+       :node node))
+
+    (when (and other-validator (not (functionp other-validator)))
+      (ical:signal-validation-error
+       (format "Bad validator function `%s' for type `%s'" other-validator type)))
+
+    (when other-validator
+      (funcall other-validator node)))
+
+  (when recursively
+    (dolist (c (ical:ast-node-children node))
+      (ical:ast-node-valid-p c recursively)))
+
+  ;; success:
+  node)
+
+(provide 'icalendar-ast)
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-"))
+;; End:
+;;; icalendar-ast.el ends here
diff --git a/lisp/calendar/icalendar-macs.el b/lisp/calendar/icalendar-macs.el
new file mode 100644
index 00000000000..033fea94527
--- /dev/null
+++ b/lisp/calendar/icalendar-macs.el
@@ -0,0 +1,1134 @@
+;;; icalendar-macs.el --- Macros for iCalendar  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024 Free Software Foundation, Inc.
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: October 2024
+;; Keywords: calendar
+;; Human-Keywords: calendar, iCalendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file defines the macros `ical:define-type', `ical:define-param',
+;; `ical:define-property' and `ical:define-component', used in
+;; icalendar-parser.el to define the particular value types, parameters,
+;; properties and components in the standard as type symbols.
+
+;; TODOs:
+;;   - in the define* macros, :default needs rethinking.
+;;     I had made this a string because otherwise you can't distinguish
+;;     an unspecified default from an explicit "FALSE" for icalendar-boolean
+;;     But this might not be true/might not matter anyway, and it's a pain
+;;     to have to read the default value where you need it.  Probably
+;;     should just change these to be the value as read.
+
+
+;;; Code:
+
+(eval-when-compile (require 'cl-lib))
+
+(declare-function ical:ast-node-p "icalendar-ast")
+(declare-function ical:ast-node-type "icalendar-ast")
+(declare-function ical:ast-node-value "icalendar-ast")
+(declare-function ical:type-symbol-p "icalendar-ast")
+(declare-function ical:value-type-symbol-p "icalendar-ast")
+(declare-function ical:expects-list-of-values-p "icalendar-ast")
+
+;; Some utilities:
+
+(defun ical:format-child-spec (child-spec)
+  "Format CHILD-SPEC as a table for use in symbol documentation."
+  (concat
+   (format "%-30s%6s\n" "Type" "Number")
+   (make-string 36 ?-) "\n"
+   (mapconcat
+    (lambda (type) (format "%-30s%-6s\n" (format "`%s'" type) "1"))
+    (plist-get child-spec :one))
+   (mapconcat
+    (lambda (type) (format "%-30s%-6s\n" (format "`%s'" type) "1+"))
+    (plist-get child-spec :one-or-more))
+   (mapconcat
+    (lambda (type) (format "%-30s%-6s\n" (format "`%s'" type) "0-1"))
+    (plist-get child-spec :zero-or-one))
+   (mapconcat
+    (lambda (type) (format "%-30s%-6s\n" (format "`%s'" type) "0+"))
+    (plist-get child-spec :zero-or-more))))
+
+
+;; Define value types:
+(cl-defmacro ical:define-type (symbolic-name print-name doc specifier matcher
+                               &key link
+                                    (reader #'identity)
+                                    (printer #'identity))
+  "Define an iCalendar value type named SYMBOLIC-NAME.
+
+PRINT-NAME should be the string used to represent this type in
+the value of an `icalendar-valuetypeparam' property parameter, or
+nil if this is not a type that should be specified there.  DOC
+should be a documentation string for the type.  SPECIFIER should
+be a type specifier in the sense of `cl-deftype'.  MATCHER should
+be an RX definition body (see `rx-define'; argument lists are not
+supported).
+
+Before the type is defined with `cl-deftype', a function will be
+defined named `icalendar-match-PRINT-NAME-value'
+\(or `icalendar-match-OTHER-value', if PRINT-NAME is nil, where
+OTHER is derived from SYMBOLIC-NAME by removing any prefix
+\"icalendar-\" and suffix \"value\").  This function takes a
+string argument and matches it against MATCHER.  This function may
+thus occur in SPECIFIER (e.g. in a (satisfies ...) clause).
+
+See the functions `icalendar-read-value-node',
+`icalendar-parse-value-node', and `icalendar-print-value-node' to
+convert values defined with this macro to and from their text
+representation in iCalendar format.
+
+The following keyword arguments are accepted:
+
+:reader - a function to read data of this type.  It will be passed
+  a string matching MATCHER and should return an Elisp data structure.
+  Its name does not need to be quoted.  (default: identity)
+
+:printer - a function to convert an Elisp data structure of this
+  type to a string.  Its name does not need to be quoted.
+  (default: identity)
+
+:link - a string containing a URL for further documentation of this type"
+  (declare (doc-string 2))
+  (let* (;; Related functions:
+         (type-dname (if print-name
+                         (downcase print-name)
+                       (string-trim
+                        (symbol-name symbolic-name)
+                        "icalendar-" "value")))
+         (matcher-name (intern (concat "icalendar-match-" type-dname "-value")))
+         ;; Documentation:
+         (header "It names a value type defined by `icalendar-define-type'.")
+         (matcher-doc (format
+"Strings representing values of this type can be matched with
+`%s'.\n" matcher-name))
+         (reader-doc (format "They can be read with `%s'\n" reader))
+         (printer-doc (format "and printed with `%s'." printer))
+         (full-doc (concat header "\n\n" doc "\n\n"
+                           matcher-doc reader-doc printer-doc "\n\n"
+"A syntax node of this type can be read with
+`icalendar-read-value-node' or parsed with `icalendar-parse-value-node',
+and printed with `icalendar-print-value-node'.")))
+
+    `(progn
+       ;; Type metadata needs to be available at both compile time and
+       ;; run time.  In particular, `ical:value-type-symbol-p' needs to
+       ;; work at compile time.
+       (eval-and-compile
+         (setplist (quote ,symbolic-name)
+                   (list
+                    'ical:is-type t
+                    'ical:is-value t
+                    'ical:matcher (function ,matcher-name)
+                    'ical:value-rx (quote ,symbolic-name)
+                    'ical:value-reader (function ,reader)
+                    'ical:value-printer (function ,printer)
+                    'ical:type-documentation ,full-doc
+                    'ical:link ,link)))
+
+       (rx-define ,symbolic-name
+         ,matcher)
+
+       (defun ,matcher-name (s)
+         ,(format "Match string S against rx `%s'." symbolic-name)
+         (string-match (rx ,symbolic-name) s))
+
+       (cl-deftype ,symbolic-name () ,specifier)
+
+       ;; Store the association between the print name and the type
+       ;; symbol in ical:value-types.  The check against print name
+       ;; here allows us to also define value types that aren't
+       ;; "really" types according to the standard, like
+       ;; `ical:geo-coordinates'.  Only types that have a
+       ;; print-name can be specified in a VALUE parameter.
+       (when ,print-name
+         (push (cons ,print-name (quote ,symbolic-name)) ical:value-types)))))
+
+;; TODO: not sure this is needed.  I've only used it once in the parser.
+(cl-defmacro ical:define-keyword-type (symbolic-name print-name doc matcher
+                                       &key link
+                                            (reader 'intern)
+                                            (printer 'symbol-name))
+  "Like `icalendar-define-type', for types represented by strings.
+String values matching MATCHER are assumed to be type-specific keywords
+that should be interned as symbols when read.  (Thus no type specifier
+is necessary: it is always just \\='symbol.) Their printed
+representation is their symbol name."
+  `(ical:define-type ,symbolic-name ,print-name ,doc
+                     'symbol
+                     ,matcher
+                     :link ,link
+                     :reader ,reader
+                     :printer ,printer))
+
+
+;; Define parameters:
+(cl-defmacro ical:define-param (symbolic-name param-name doc value
+                                &key quoted
+                                     list-sep
+                                     default
+                                     (unrecognized default)
+                                     ((:name-face name-face)
+                                      'ical:parameter-name nondefault-name-face)
+                                     ((:value-face value-face)
+                                      'ical:parameter-value nondefault-value-face)
+                                     ((:warn-face warn-face)
+                                      'ical:warning nondefault-warn-face)
+                                     extra-faces
+                                     link)
+  "Define iCalendar parameter PARAM-NAME under the symbol SYMBOLIC-NAME.
+PARAM-NAME should be the parameter name as it should appear in
+iCalendar data.
+
+VALUE should either be a symbol for a value type defined with
+`icalendar-define-type', or an `rx' regular expression.  If it is
+a type symbol, the regex, reader and printer functions associated
+with that type will be used when parsing and serializing values.
+If it is a regular expression, it is assumed that the values of
+this parameter are strings which match that regular expression.
+
+An `rx' regular expression named SYMBOLIC-NAME which matches the
+parameter is defined:
+  Group 1 of this regex matches PARAM-NAME
+    (or any valid parameter name, if PARAM-NAME is nil).
+  Group 2 matches VALUE, which specifies a correct value
+    for this parameter according to RFC5545.
+  Group 3, if matched, contains any parameter value which does
+    *not* match VALUE, and is incorrect according to the standard.
+
+This regex matches the entire string representing this parameter,
+from \";\" to the end of its value.  Another regular expression
+named `SYMBOLIC-NAME-value' is also defined to match just the
+value part, after \";PARAM-NAME=\", with groups 2 and 3 as above.
+
+A function to match the complete parameter expression called
+`icalendar-match-PARAM-NAME-param' is defined
+\(or `icalendar-match-OTHER-param-value' if PARAM-NAME is nil,
+where OTHER is derived from SYMBOLIC-NAME by removing any prefix
+`icalendar-' and suffix `param').  This function is used
+to provide syntax highlighting in `icalendar-mode'.
+
+See the functions `icalendar-read-param-value',
+`icalendar-parse-param-value', `icalendar-parse-params' and
+`icalendar-print-param-node' to convert parameters defined with
+this macro to and from their text representation in iCalendar
+format.
+
+The following keyword arguments are accepted:
+
+:default - a (string representing the) default value, if the
+  parameter is not specified on a given property.
+
+:unrecognized - a (string representing the) value which must be
+  substituted for values that are not recognized but syntactically
+  correct according to RFC5545.  Unrecognized values must be in match
+  group 5 of the regex determined by VALUE.  An unrecognized value will
+  be preserved in the syntax tree metadata and printed instead of this
+  value when the node is printed.  Defaults to any value specified for
+  :default.
+
+:quoted - non-nil if values of this parameter must always be surrounded
+  by (double-)quotation marks when printed, according to RFC5545.
+
+:list-sep - if the parameter accepts a list of values, this should be a
+  string which separates the values (typically \",\").  If :list-sep is
+  non-nil, the value string will first be split on the separator, then
+  if :quoted is non-nil, the individual values will be unquoted, then
+  each value will be read according to VALUE and collected into a list
+  when parsing.  When printing, the inverse happens: values are quoted
+  if :quoted is non-nil, then joined with :list-sep.  Passing this
+  argument marks SYMBOLIC-NAME as a type that accepts a list of values
+  for `icalendar-expects-list-of-values-p'.
+
+:name-face - a face symbol for highlighting the property name
+  (default: `icalendar-parameter-name')
+
+:value-face - a face symbol for highlighting valid property values
+  (default: `icalendar-parameter-value')
+
+:warn-face - a face symbol for highlighting invalid property values
+  (default: `icalendar-warning')
+
+:extra-faces - a list of the form accepted for HIGHLIGHT in
+  `font-lock-keywords'.  In particular,
+    ((GROUPNUM FACENAME [OVERRIDE [LAXMATCH]]) ...)
+  can be used to apply different faces to different
+  match subgroups.
+
+:link - a string containing a URL for documentation of this parameter.
+  The URL will be provided in the documentation shown by
+  `describe-symbol' for SYMBOLIC-NAME."
+  (declare (doc-string 2))
+  (let* (;; Related function names:
+         (param-dname (if param-name
+                          (downcase param-name)
+                        (string-trim (symbol-name symbolic-name)
+                                     "icalendar-" "param")))
+         (matcher-name (intern (concat "icalendar-match-" param-dname "-param")))
+         (type-predicate-name
+          (intern (concat "icalendar-" param-dname "-param-p")))
+         ;; Value regexes:
+         (qvalue-rx (if quoted `(seq ?\" ,value ?\") value))
+         (values-rx (when list-sep
+                     `(seq ,qvalue-rx (zero-or-more ,list-sep ,qvalue-rx))))
+         (full-value-rx-name
+          (intern (concat (symbol-name symbolic-name) "-value")))
+         ;; Faces:
+         (has-faces (or nondefault-name-face nondefault-value-face
+                        nondefault-warn-face extra-faces))
+         ;; Documentation:
+         (header "It names a parameter type defined by `icalendar-define-param'.")
+         (val-list (if list-sep (concat "VAL1" list-sep "VAL2" list-sep "...")
+                     "VAL"))
+         (s (if list-sep "s" "")) ; to make plurals
+         (val-doc (concat "VAL" s " "
+                          "must be " (unless list-sep "a ") (when quoted "quoted ")
+                          (if (ical:value-type-symbol-p value)
+                              (format "`%s' value%s" (symbol-name value) s)
+                            (format "string%s matching rx `%S'" s value))))
+         (syntax-doc (format "Syntax: %s=%s\n%s"
+                             (or param-name "(NAME)") val-list val-doc))
+         (full-doc (concat header "\n\n" doc "\n\n" syntax-doc)))
+
+    `(progn
+       ;; Type metadata needs to be available at both compile time and
+       ;; run time.  In particular, `ical:value-type-symbol-p' needs to
+       ;; work at compile time.
+       (eval-and-compile
+         (setplist (quote ,symbolic-name)
+                   (list
+                    'ical:is-type t
+                    'ical:is-param t
+                    'ical:matcher (function ,matcher-name)
+                    'ical:default-value ,default
+                    'ical:is-quoted ,quoted
+                    'ical:list-sep ,list-sep
+                    'ical:substitute-value ,unrecognized
+                    'ical:matcher (function ,matcher-name)
+                    'ical:value-type
+                    (when (ical:value-type-symbol-p (quote ,value))
+                      (quote ,value))
+                    'ical:value-rx (quote ,value)
+                    'ical:values-rx (quote ,values-rx)
+                    'ical:full-value-rx (quote ,full-value-rx-name)
+                    'ical:type-documentation ,full-doc
+                    'ical:link ,link)))
+
+       ;; Regex which matches just the value of the parameter:
+       ;; Group 2: correct values of the parameter, and
+       ;; Group 3: incorrect values up to the next parameter
+       (rx-define ,full-value-rx-name
+         (or (group-n 2 ,(or values-rx qvalue-rx))
+             (group-n 3 ical:param-value)))
+
+       ;; Regex which matches the full parameter:
+       ;; Group 1: the parameter name,
+       ;; Group 2: correct values of the parameter, and
+       ;; Group 3: incorrect values up to the next parameter
+       (rx-define ,symbolic-name
+         (seq ";"
+              ;; if the parameter name has no printed form, the best we
+              ;; can do is match ical:param-name:
+              (group-n 1 ,(or param-name 'ical:param-name))
+              "="
+              ,full-value-rx-name))
+
+       ;; CL-type to represent syntax nodes for this parameter:
+       (defun ,type-predicate-name (node)
+         ,(format "Return non-nil if NODE represents a %s parameter." param-name)
+         (and (ical:ast-node-p node)
+              (eq (ical:ast-node-type node) (quote ,symbolic-name))))
+
+       (cl-deftype ,symbolic-name () '(satisfies ,type-predicate-name))
+
+       ;; Matcher for the full param string, for syntax highlighting:
+       (defun ,matcher-name (limit)
+         ,(concat (format "Matcher for %s parameter.\n" param-name)
+                  "(Defined by `icalendar-define-param'.)")
+         (re-search-forward (rx ,symbolic-name) limit t))
+
+       ;; Entry for font-lock-keywords in icalendar-mode:
+       (when ,has-faces
+         ;; Avoid circular load of icalendar-mode.el in
+         ;; icalendar-parser.el (which does not use the *-face
+         ;; keywords), while still allowing external code to add to
+         ;; font-lock-keywords dynamically:
+         (require 'icalendar-mode)
+         (push (quote (,matcher-name
+                       (1 (quote ,name-face) t t)
+                       (2 (quote ,value-face) t t)
+                       (3 (quote ,warn-face) t t)
+                       ,@extra-faces))
+               ical:font-lock-keywords))
+
+       ;; Associate the print name with the type symbol for
+       ;; `ical:parse-params' and `ical:print-param':
+       (when ,param-name
+         (push (cons ,param-name (quote ,symbolic-name)) ical:param-types)))))
+
+
+;; Define properties:
+(cl-defmacro ical:define-property (symbolic-name property-name doc value
+                                   &key default
+                                        (unrecognized default)
+                                        (default-type
+                                         (if (ical:value-type-symbol-p value)
+                                             value
+                                           'ical:text))
+                                        other-types
+                                        list-sep
+                                        child-spec
+                                        other-validator
+                                        ((:name-face name-face)
+                                         'ical:property-name nondefault-name-face)
+                                        ((:value-face value-face)
+                                         'ical:property-value nondefault-value-face)
+                                        ((:warn-face warn-face)
+                                         'ical:warning nondefault-warn-face)
+                                        extra-faces
+                                        link)
+  "Define iCalendar property PROPERTY-NAME under SYMBOLIC-NAME.
+PROPERTY-NAME should be the property name as it should appear in
+iCalendar data.
+
+VALUE should either be a symbol for a value type defined with
+`icalendar-define-type', or an `rx' regular expression.  If it is
+a type symbol, the regex, reader and printer functions associated
+with that type will be used when parsing and serializing the
+property's value.  If it is a regular expression, it is assumed
+that the values are strings of type `icalendar-text' which match
+that regular expression.
+
+An `rx' regular expression named SYMBOLIC-NAME is defined to
+match the property:
+  Group 1 of this regex matches PROPERTY-NAME.
+  Group 2 matches VALUE.
+  Group 3, if matched, contains any property value which does
+   *not* match VALUE, and is incorrect according to the standard.
+  Group 4, if matched, contains the (unparsed) property parameters;
+   its boundaries can be used for parsing these.
+
+This regex matches the entire string representing this property,
+from the beginning of the content line to the end of its value.
+Another regular expression named `SYMBOLIC-NAME-value' is also
+defined to match just the value part, after the separating colon,
+with groups 2 and 3 as above.
+
+A function to match the complete property expression called
+`icalendar-match-PROPERTY-NAME-property' is defined.  This
+function is used to provide syntax highlighting in
+`icalendar-mode'.
+
+See the functions `icalendar-read-property-value',
+`icalendar-parse-property-value', `icalendar-parse-property', and
+`icalendar-print-property-node' to convert properties defined
+with this macro to and from their text representation in
+iCalendar format.
+
+The following keyword arguments are accepted:
+
+:default - a (string representing the) default value, if
+  the property is not specified in a given component.
+
+:unrecognized - a (string representing the) value which must be
+  substituted for values that are not recognized but
+  syntactically correct according to RFC5545.  Unrecognized values
+  must be in match group 5 of the regex determined by VALUE.  An
+  unrecognized value will be preserved in the syntax tree
+  metadata and printed instead of this value when the node is
+  printed.  Defaults to any value specified for :default.
+
+:default-type - a type symbol naming the default type of the
+  property's value.  If the property's value differs from this
+  type, an `icalendar-valuetypeparam' parameter will be added to
+  the property's syntax node and printed when the node is
+  printed.  Default is VALUE if VALUE is a value type symbol,
+  otherwise the type `icalendar-text'.
+
+:other-types - a list of type symbols naming value types other
+  than :default-type.  These represent alternative types for the
+  property's value.  If parsing the property's value under its
+  default type fails, these types will be tried in turn, and only
+  if the property's value matches none of them will an error be
+  signaled.
+
+:list-sep - if the property accepts a list of values, this should
+  be a string which separates the values (typically \",\").  If
+  :list-sep is non-nil, the value string will first be split on
+  the separator, then each value will be read according to VALUE
+  and collected into a list when parsing.  When printing, the
+  inverse happens: values are printed individually and then
+  joined with :list-sep.  Passing this argument marks
+  SYMBOLIC-NAME as a type that accepts a list of values for
+  `icalendar-expects-list-of-values-p'.
+
+:child-spec - a plist mapping the following keywords to lists
+of type symbols:
+  :one           - parameters that must appear exactly once
+  :one-or-more   - parameters that must appear at least once and
+                   may appear more than once
+  :zero-or-one   - parameters that must appear at most once
+  :zero-or-more  - parameters that may appear more than once
+  :allow-others  - if non-nil, other parameters besides those listed in
+                   the above are allowed to appear.  (In this case, a
+                   :zero-or-more clause is redundant.)
+
+:other-validator - a function to perform any additional validation of
+  the component, beyond what `icalendar-ast-node-valid-p' checks.
+  This function should accept one argument, a syntax node.  It
+  should return non-nil if the node is valid, or signal an
+  `icalendar-validation-error' if it is not.  Its name does not
+  need to be quoted.
+
+:name-face - a face symbol for highlighting the property name
+  (default: `icalendar-property-name')
+
+:value-face - a face symbol for highlighting valid property values
+  (default: `icalendar-property-value')
+
+:warn-face - a face symbol for highlighting invalid property values
+  (default: `icalendar-warning')
+
+:extra-faces - a list of the form for HIGHLIGHT in `font-lock-keywords'.
+  In particular, ((GROUPNUM FACENAME [OVERRIDE [LAXMATCH]])...)
+  can be used to apply different faces to different match subgroups.
+
+:link - a string containing a URL for documentation of this property"
+  (declare (doc-string 2))
+  (let* (;; Value RX:
+        (full-value-rx-name
+         (intern (concat (symbol-name symbolic-name) "-property-value")))
+        (values-rx (when list-sep
+                    `(seq ,value (zero-or-more ,list-sep ,value))))
+        ;; Related functions:
+        (property-dname (if property-name
+                            (downcase property-name)
+                          (string-trim (symbol-name symbolic-name)
+                                       "icalendar-" "-property")))
+        (matcher-name
+         (intern (concat "icalendar-match-" property-dname "-property")))
+        (type-predicate-name
+         (intern (concat "icalendar-" property-dname "-property-p")))
+        ;; Faces:
+        (has-faces (or nondefault-name-face nondefault-value-face
+                       nondefault-warn-face extra-faces))
+        ;; Documentation:
+        (header "It names a property type defined by `icalendar-define-property'.")
+        (val-list (if list-sep (concat "VAL1" list-sep "VAL2" list-sep "...")
+                    "VAL"))
+        (default-doc (if default (format "The default value is: \"%s\"\n" default)
+                       ""))
+        (s (if list-sep "s" "")) ; to make plurals
+        (val-doc (concat "VAL" s " "
+                         "must be " (unless list-sep "a ")
+                         (format "value%s of one of the following types:\n" s)
+                         (string-join
+                          (cons
+                           (format "`%s' (default)" default-type)
+                           (mapcar (lambda (type) (format "`%s'" type))
+                                   other-types))
+                          "\n")
+                         default-doc))
+        (name-doc (if property-name "" "NAME must match rx `icalendar-name'"))
+        (syntax-doc (format "Syntax: %s[;PARAM...]:%s\n%s\n%s\n"
+                            (or property-name "NAME") val-list name-doc val-doc))
+        (child-doc
+         (concat
+          "The following parameters are required or allowed\n"
+          "as children in syntax nodes of this type:\n\n"
+          (ical:format-child-spec child-spec)
+          (when (plist-get child-spec :allow-others)
+            "\nOther parameters of any type are also allowed.\n")))
+        (full-doc (concat header "\n\n" doc "\n\n" syntax-doc "\n\n" child-doc)))
+
+    `(progn
+       ;; Type metadata needs to be available at both compile time and
+       ;; run time.  In particular, `ical:value-type-symbol-p' needs to
+       ;; work at compile time.
+       (eval-and-compile
+         (setplist (quote ,symbolic-name)
+                   (list
+                    'ical:is-type t
+                    'ical:is-property t
+                    'ical:matcher (function ,matcher-name)
+                    'ical:default-value ,default
+                    'ical:default-type (quote ,default-type)
+                    'ical:other-types (quote ,other-types)
+                    'ical:list-sep ,list-sep
+                    'ical:substitute-value ,unrecognized
+                    'ical:value-type
+                    (when (ical:value-type-symbol-p (quote ,value))
+                      (quote ,value))
+                    'ical:value-rx (quote ,value)
+                    'ical:values-rx (quote ,values-rx)
+                    'ical:full-value-rx (quote ,full-value-rx-name)
+                    'ical:child-spec (quote ,child-spec)
+                    'ical:other-validator (function ,other-validator)
+                    'ical:type-documentation ,full-doc
+                    'ical:link ,link)))
+
+       ;; Value regex which matches:
+       ;; Group 2: correct values of the property, and
+       ;; Group 3: incorrect values up to end-of-line (for syntax warnings)
+       (rx-define ,full-value-rx-name
+         (or (group-n 2 ,(or values-rx value))
+             (group-n 3 (zero-or-more not-newline))))
+
+       ;; Full property regex which matches:
+       ;; Group 1: the property name,
+       ;; Group 2: correct values of the property, and
+       ;; Group 3: incorrect values up to end-of-line (for syntax warnings)
+       (rx-define ,symbolic-name
+         (seq line-start
+              (group-n 1 ,(or property-name 'ical:name))
+              (group-n 4 (zero-or-more ical:other-param-safe))
+              ":"
+              ,full-value-rx-name
+              line-end))
+
+       ;; Matcher:
+       (defun ,matcher-name (limit)
+         ,(concat (format "Matcher for `%s' property.\n" symbolic-name)
+                  "(Defined by icalendar-define-property.)")
+         (re-search-forward (rx ,symbolic-name) limit t))
+
+       ;; CL-type to represent syntax nodes for this property:
+       (defun ,type-predicate-name (node)
+         ,(format "Return non-nil if NODE represents a %s property." property-name)
+         (and (ical:ast-node-p node)
+              (eq (ical:ast-node-type node) (quote ,symbolic-name))))
+
+       (cl-deftype ,symbolic-name () '(satisfies ,type-predicate-name))
+
+       ;; Associate the print name with the type symbol for
+       ;; `icalendar-parse-property', `icalendar-print-property-node', etc.:
+       (when ,property-name
+         (push (cons ,property-name (quote ,symbolic-name)) ical:property-types))
+
+       ;; Generate an entry for font-lock-keywords in icalendar-mode:
+       (when ,has-faces
+         ;; Avoid circular load of icalendar-mode.el in
+         ;; icalendar-parser.el (which does not use the *-face
+         ;; keywords), while still allowing external code to add to
+         ;; font-lock-keywords dynamically:
+         (require 'icalendar-mode)
+         (push (quote (,matcher-name
+                       (1 (quote ,name-face) t t)
+                       (2 (quote ,value-face) t t)
+                       (3 (quote ,warn-face) t t)
+                       ,@extra-faces))
+               ical:font-lock-keywords)))))
+
+
+;; Define components:
+(cl-defmacro ical:define-component (symbolic-name component-name doc
+                                    &key
+                                    ((:keyword-face keyword-face)
+                                     'ical:keyword nondefault-keyword-face)
+                                    ((:name-face name-face)
+                                     'ical:component-name nondefault-name-face)
+                                    child-spec
+                                    other-validator
+                                    link)
+  "Define iCalendar component COMPONENT-NAME under SYMBOLIC-NAME.
+COMPONENT-NAME should be the name of the component as it should
+appear in iCalendar data.
+
+Regular expressions to match the component boundaries are defined
+named `COMPONENT-NAME-begin' and `COMPONENT-NAME-end' (or
+`OTHER-begin' and `OTHER-end', where `OTHER' is derived from
+SYMBOLIC-NAME by removing any prefix `icalendar-' and suffix
+`-component' if COMPONENT-NAME is nil).
+  Group 1 of these regexes matches the \"BEGIN\" or \"END\"
+    keyword that marks a component boundary.
+  Group 2 matches the component name.
+
+A function to match the component boundaries is defined called
+`icalendar-match-COMPONENT-NAME-component' (or
+`icalendar-match-OTHER-component', with OTHER as above).  This
+function is used to provide syntax highlighting in
+`icalendar-mode'.
+
+The following keyword arguments are accepted:
+
+:child-spec - a plist mapping the following keywords to lists
+of type symbols:
+  :one           - properties or components that must appear exactly once
+  :one-or-more   - properties or components that must appear at least once and
+                   may appear more than once
+  :zero-or-one   - properties or components that must appear at most once
+  :zero-or-more  - properties or components that may appear more than once
+  :allow-others  - if non-nil, other children besides those listed in the above
+                   are allowed to appear.  (In this case, a :zero-or-more
+                   clause is redundant.)
+
+:other-validator - a function to perform any additional validation of
+  the component, beyond what `icalendar-ast-node-valid-p' checks.
+  This function should accept one argument, a syntax node.  It
+  should return non-nil if the node is valid, or signal an
+  `icalendar-validation-error' if it is not.  Its name does not
+  need to be quoted.
+
+:keyword-face - a face symbol for highlighting the BEGIN/END keyword
+  (default: `icalendar-keyword')
+
+:name-face - a face symbol for highlighting the component name
+  (default: `icalendar-component-name')
+
+:link - a string containing a URL for documentation of this component"
+  (declare (doc-string 2))
+  (let* (;; Regexes:
+         (name-rx (or component-name 'ical:name))
+         (component-dname (if component-name
+                              (downcase component-name)
+                            (string-trim (symbol-name symbolic-name)
+                                         "icalendar-" "-component")))
+         (begin-rx-name (intern (concat "icalendar-" component-dname "-begin")))
+         (end-rx-name (intern (concat "icalendar-" component-dname "-end")))
+         ;; Related functions:
+         (matcher-name
+          (intern (concat "icalendar-match-" component-dname "-component")))
+         (type-predicate-name
+          (intern (concat "icalendar-" component-dname "-component-p")))
+         ;; Faces:
+         (has-faces (or nondefault-name-face nondefault-keyword-face))
+         ;; Documentation:
+         (header "It names a component type defined by
+`icalendar-define-component'.")
+         (name-doc (if (not component-name)
+                       "\nNAME must match rx `icalendar-name'"
+                     ""))
+         (syntax-doc (format "Syntax:\nBEGIN:%s\n[contentline ...]\nEND:%1$s%s"
+                             (or component-name "NAME")
+                             name-doc))
+         (child-doc
+          (concat
+           "The following properties and components are required or "
+           "allowed\nas children in syntax nodes of this type:\n\n"
+           (ical:format-child-spec child-spec)
+           (when (plist-get child-spec :allow-others)
+             "\nOther properties and components of any type are also allowed.\n")))
+         (full-doc (concat header "\n\n" doc "\n\n" syntax-doc "\n\n" child-doc)))
+
+    `(progn
+       ;; Type metadata needs to be available at both compile time and
+       ;; run time.  In particular, `ical:value-type-symbol-p' needs to
+       ;; work at compile time.
+       (eval-and-compile
+         (setplist (quote ,symbolic-name)
+                   (list
+                    'ical:is-type t
+                    'ical:is-component t
+                    'ical:matcher (function ,matcher-name)
+                    'ical:begin-rx (quote ,begin-rx-name)
+                    'ical:end-rx (quote ,end-rx-name)
+                    'ical:child-spec (quote ,child-spec)
+                    'ical:other-validator (function ,other-validator)
+                    'ical:type-documentation ,full-doc
+                    'ical:link ,link)))
+
+       ;; Regexes which match:
+       ;; Group 1: BEGIN or END, and
+       ;; Group 2: the component name
+       (rx-define ,begin-rx-name
+         (seq line-start
+              (group-n 1 "BEGIN")
+              ":"
+              (group-n 2 ,name-rx)
+              line-end))
+
+       (rx-define ,end-rx-name
+         (seq line-start
+              (group-n 1  "END")
+              ":"
+              (group-n 2 ,name-rx)
+              line-end))
+
+       (defun ,matcher-name (limit)
+         ,(concat (format "Matcher for %s component boundaries.\n"
+                          (or component-name "unrecognized"))
+                  "(Defined by `icalendar-define-component'.)")
+           (re-search-forward (rx (or ,begin-rx-name ,end-rx-name)) limit t))
+
+       ;; CL-type to represent syntax nodes for this component:
+       (defun ,type-predicate-name (node)
+         ,(format "Return non-nil if NODE represents a %s component."
+                  (or component-name "unrecognized"))
+         (and (ical:ast-node-p node)
+              (eq (ical:ast-node-type node) (quote ,symbolic-name))))
+
+       (cl-deftype ,symbolic-name () '(satisfies ,type-predicate-name))
+
+       ;; Generate an entry for font-lock-keywords in icalendar-mode:
+       (when ,has-faces
+         ;; Avoid circular load of icalendar-mode.el in
+         ;; icalendar-parser.el (which does not use the *-face
+         ;; keywords), while still allowing external code to add to
+         ;; font-lock-keywords dynamically:
+         (require 'icalendar-mode)
+         (push (quote (,matcher-name
+                       (1 (quote ,keyword-face) t t)
+                       (2 (quote ,name-face) t t)))
+               ical:font-lock-keywords))
+
+       ;; Associate the print name with the type symbol for
+       ;; `icalendar-parse-component', `icalendar-print-component' etc.:
+       (when ,component-name
+         (push (cons ,component-name (quote ,symbolic-name))
+               ical:component-types)))))
+
+
+;; Macros for destructuring and binding AST nodes
+
+(defmacro ical:with-node-children (node bindings &rest body)
+  "Execute BODY with BINDINGS to children in NODE.
+NODE should be an iCalendar syntax node representing a component or
+property.
+
+Each binding in BINDINGS should be a list of one of the following forms:
+
+\(TYPE VAR)
+  TYPE should be a type symbol for an iCalendar property or component
+  which can be a child of COMPONENT.  The first child node of TYPE, if
+  any, will be bound to VAR in BODY.
+
+\(TYPE KEY1 VAR1 ...)
+  For each KEY present, the corresponding VAR will be bound as follows:
+   :all - a list of all child nodes of TYPE.  If this keyword is present,
+     none of the others are allowed.
+   :first - the first child node of TYPE
+   :default - the default value, if any, for TYPE
+   :value-node - the value of the node in :first
+   :value-type - the type of the node in :value-node (if it is a node).
+   :value - the value of the node in :value-node, if it is a node,
+     or :value-node itself, if it is not.
+  If TYPE expects a list of values, you should use the following keywords
+  instead of the previous three:
+   :value-nodes - the values of the node in :first
+   :value-types - a list of the types of the nodes in :value-nodes.
+   :values - a list of the values of the nodes in :value-nodes (if they are
+     nodes), or the :value-nodes themselves (if they are not).
+  It is a compile-time error to use the singular keywords with a TYPE that
+  takes multiple values, or the plural keywords with a TYPE that does not."
+  (declare (debug (form form &rest form))
+           (indent 2))
+  ;; Static checks on the bindings prevent various annoying bugs:
+  (dolist (b bindings)
+    (let ((type (car b))
+          (kwargs (cdr b)))
+      (unless (ical:type-symbol-p type)
+        (error "Not an iCalendar type symbol: %s" type))
+      (when (and (plist-member kwargs :all)
+                 (> 2 (length kwargs)))
+        (error ":all may not be combined with other bindings"))
+      (if (ical:expects-list-of-values-p type)
+            (when (or (plist-member kwargs :value-node)
+                      (plist-member kwargs :value-type)
+                      (plist-member kwargs :value))
+              (error "Type `%s' expects a list of values" type))
+        (when (or (plist-member kwargs :value-nodes)
+                  (plist-member kwargs :value-types)
+                  (plist-member kwargs :values))
+              (error "Type `%s' does not expect a list of values" type)))))
+
+  (let ((nd (gensym "icalendar-node")))
+    `(let* ((,nd ,node)
+            ,@(mapcan
+               (lambda (tv)
+                 (let ((type (car tv))
+                       (vars (cdr tv)))
+                   (when (and (symbolp (car vars)) (null (cdr vars)))
+                     ;; the simple (TYPE VAR) case:
+                     (setq vars (list :first (car vars))))
+
+                   (let ((first-var (or (plist-get vars :first)
+                                        (gensym "first")))
+                         (default-var (or (plist-get vars :default)
+                                          (gensym "default")))
+                         (vnode-var (or (plist-get vars :value-node)
+                                        (gensym "value-node")))
+                         (vtype-var (or (plist-get vars :value-type)
+                                        (gensym "value-type")))
+                         (vval-var (or (plist-get vars :value)
+                                       (gensym "value")))
+
+                         (vnodes-var (or (plist-get vars :value-nodes)
+                                         (gensym "value-nodes")))
+                         (vtypes-var (or (plist-get vars :value-types)
+                                         (gensym "value-types")))
+                         (vvals-var (or (plist-get vars :values)
+                                        (gensym "values")))
+
+                         (all-var (or (plist-get vars :all)
+                                      (gensym "all")))
+                         ;; The corresponding vars for :all are mostly
+                         ;; too complicated to be useful, I think, so
+                         ;; not implementing them for now.
+                         ;; TODO: but it *would* be helpful to have an
+                         ;; :all-values clause especially for RDATE and
+                         ;; EXDATE, since they both accept lists, and
+                         ;; can also occur multiple times.
+                         ;; I've found myself needing to write
+                         ;; (mapcar #'ical:ast-node-value
+                         ;;   (apply #'append
+                         ;;     (mapcar #'ical:ast-node-value rdate-nodes))
+                         ;; a bit too often.
+                         )
+                     (delq nil
+                           (list
+                            (when (plist-member vars :all)
+                              `(,all-var (ical:ast-node-children-of
+                                          (quote ,type) ,nd)))
+                            (when (not (plist-member vars :all))
+                              `(,first-var (ical:ast-node-first-child-of
+                                            (quote ,type) ,nd)))
+                            (when (plist-member vars :default)
+                              `(,default-var (get (quote ,type)
+                                                  'ical:default-value)))
+                            ;; Single value:
+                            (when (or (plist-member vars :value-node)
+                                      (plist-member vars :value-type)
+                                      (plist-member vars :value))
+                              `(,vnode-var (when (ical:ast-node-p ,first-var)
+                                             (ical:ast-node-value ,first-var))))
+                            (when (plist-member vars :value-type)
+                              `(,vtype-var
+                                (when ,vnode-var
+                                  (ical:ast-node-type ,vnode-var))))
+                            (when (plist-member vars :value)
+                              `(,vval-var
+                                (when ,vnode-var
+                                  (if (ical:ast-node-p ,vnode-var)
+                                      (ical:ast-node-value ,vnode-var)
+                                    ,vnode-var))))
+
+                            ;; List of values:
+                            (when (or (plist-member vars :value-nodes)
+                                      (plist-member vars :value-types)
+                                      (plist-member vars :values))
+                              `(,vnodes-var
+                                (when (ical:ast-node-p ,first-var)
+                                  (ical:ast-node-value ,first-var))))
+                            (when (plist-member vars :value-types)
+                              `(,vtypes-var
+                                (when ,vnodes-var
+                                  (mapcar #'ical:ast-node-type ,vnodes-var))))
+                            (when (plist-member vars :values)
+                              `(,vvals-var
+                                (when ,vnodes-var
+                                  (if (ical:ast-node-p (car ,vnodes-var))
+                                      (mapcar #'ical:ast-node-value
+                                              ,vnodes-var)
+                                    ,vnodes-var)))))))))
+
+               bindings))
+       ,@body)))
+
+(defalias 'ical:with-component #'ical:with-node-children
+    "Execute BODY with properties of NODE bound as in BINDINGS.
+
+NODE should be an iCalendar syntax node representing an iCalendar
+component: `icalendar-vevent', `icalendar-vtodo', `icalendar-vjournal',
+`icalendar-vtimezone', `icalendar-vfreebusy', `icalendar-standard',
+`icalendar-daylight'.  It may also be an entire `icalendar-vcalendar'.
+
+Each binding in BINDINGS should be a list of one of the following forms:
+
+(TYPE VAR)
+  TYPE should be a type symbol for an iCalendar property or component
+  which can be a child of COMPONENT.  The first child node of TYPE, if
+  any, will be bound to VAR in BODY.
+
+(TYPE KEY1 VAR1 ...)
+  For each KEY present, the corresponding VAR will be bound as follows:
+   :all - a list of all child nodes of TYPE.  If this keyword is present,
+     none of the others are allowed.
+   :default - the default value, if any, for TYPE
+   :first - the first child node of TYPE
+   :value-node - the value (which is itself a node) of the node in :first
+   :value-type - the type of the node in :value-node.
+   :value - the value of the node in :value-node.
+  If TYPE expects a list of values, you should use the following keywords
+  instead of the previous three:
+   :value-nodes - the values (which are themselves nodes) of the node in :first
+   :value-types - a list of the types of the nodes in :value-nodes.
+   :values - a list of the values of the node in :value-node.
+  It is a compile-time error to use the singular keywords with a TYPE that
+  takes multiple values, or the plural keywords with a TYPE that does not.")
+
+(defmacro ical:with-node-value (node &optional bindings &rest body)
+  "Execute BODY with bindings in BINDINGS taken from NODE and its children.
+
+NODE should be an iCalendar syntax node representing a property or
+parameter.  If NODE is not a syntax node, this form evalutes to nil
+without binding the variables in BINDINGS and without executing BODY.
+
+Within BODY, if NODE's value is itself a syntax node, the symbol
+`value-node' will be bound to the syntax node for NODE's value,
+`value-type' will be bound to `value-node's type, and `value' will be
+bound to `value-node's value.
+
+If NODE's value is a list of syntax nodes, then within BODY,
+`value-nodes' will be bound to those value nodes, `value-types' will be
+bound to a list of their types, and `values' will be bound to their
+values.
+
+If NODE's value is not a syntax node, then `value' is instead bound
+directly to NODE's value, and `value-type' and `value-node' are bound to
+nil.
+
+If BODY is nil, it is assumed to be the symbol `value'; thus
+  (icalendar-with-node-value some-node)
+is equivalent to
+  (icalendar-with-node-value some-node nil value)
+
+BINDINGS are passed on to `icalendar-with-node-children' and will be
+available in BODY; see its docstring for their form."
+  (declare (debug (form &optional form &rest form))
+           (indent 2))
+  (let ((vn (gensym "icalendar-node"))
+        (val (gensym "icalendar-value"))
+        (is-list (gensym "is-list")))
+    `(let ((,vn ,node))
+       (when (ical:ast-node-p ,vn)
+         (let* ((,val (ical:ast-node-value ,vn))
+                (value-node (when (ical:ast-node-p ,val) ,val))
+                (value-type (when (ical:ast-node-p value-node)
+                              (ical:ast-node-type value-node)))
+                (value (if (ical:ast-node-p value-node)
+                           (ical:ast-node-value value-node)
+                         ,val))
+                (,is-list (ical:expects-list-of-values-p (ical:ast-node-type ,vn)))
+                (value-nodes (when ,is-list
+                               (seq-filter #'ical:ast-node-p ,val)))
+                (value-types (when ,is-list
+                               (mapcar #'ical:ast-node-type value-nodes)))
+                (values (when ,is-list
+                          (mapcar #'ical:ast-node-value value-nodes))))
+           (ignore value-type ; Silence the byte compiler when
+                   value      ; one of these goes unused
+                   value-types
+                   values)
+           (ical:with-node-children ,vn ,bindings ,@(or body (list 'value))))))))
+
+(defalias 'ical:with-property #'ical:with-node-value
+    "Execute BODY with BINDINGS taken from the value and parameters in NODE.
+
+NODE should be an iCalendar syntax node representing a property.  If NODE
+is not a syntax node, this form evalutes to nil without binding the
+variables in BINDINGS and without executing BODY.
+
+Within BODY, if NODE's value is itself a syntax node, the symbol
+`value-node' will be bound to the syntax node for NODE's value,
+`value-type' will be bound to `value-node's type, and `value' will be
+bound to `value-node's value.
+
+If NODE's value is a list of syntax nodes, then within BODY,
+`value-nodes' will be bound to those value nodes, `value-types' will be
+bound to a list of their types, and `values' will be bound to their
+values.
+
+If NODE's value is not a syntax node, then `value' is bound directly to
+NODE's value, and `value-type' and `value-node' are bound to nil.
+
+BINDINGS are passed on to `icalendar-with-node-children' and will be
+available in BODY; see its docstring for their form.")
+
+(defmacro ical:with-param (parameter &rest body)
+  "Bind the value in PARAMETER and execute BODY.
+
+PARAMETER should be an iCalendar syntax node representing a
+parameter.  If PARAMETER is nil, this form evalutes to nil without
+executing BODY.
+
+Within BODY, if PARAMETER's value is a syntax node, the symbol
+`value-node' will be bound to that syntax node, `value-type' will be
+bound to the value node's type, and `value' will be bound to the value
+node's value.
+
+If PARAMETER's value is not a syntax node, then `value' is bound
+directly to PARAMETER's value, and `value-type' and `value-node' are
+bound to nil."
+  (declare (debug (form &rest form))
+           (indent 1))
+  `(ical:with-node-value ,parameter nil ,@body))
+
+(defmacro ical:with-child-of (node type &optional bindings &rest body)
+  "Like `icalendar-with-node-value', but for the relevant node's parent.
+
+Find the first child node of type TYPE in NODE, bind that
+child node's value and any of its children in BINDINGS and execute BODY
+with these bindings.  If there is no such node, this form evalutes to
+nil without executing BODY.
+
+Within BODY, the symbols `value-node', `value-type', and `value' will be
+bound as in `icalendar-with-node-value'.
+If BODY is nil, it is assumed to be the symbol `value'; thus
+  (icalendar-with-child-of some-node some-type)
+is equivalent to
+  (icalendar-with-child-of some-node some-type nil value)
+
+See `icalendar-with-node-children' for the form of BINDINGS."
+  (declare (debug (form form &optional form &rest form))
+           (indent 3))
+  (let ((child (gensym "icalendar-node")))
+    `(let ((,child (ical:ast-node-first-child-of ,type ,node)))
+       (ical:with-node-value ,child ,bindings ,@body))))
+
+(defalias 'ical:with-property-of #'ical:with-child-of
+  "Like `icalendar-with-property', but for components containing that property.
+
+Find the first property node of type TYPE in NODE and execute BODY.
+
+Within BODY, the symbols `value-node', `value-type', and `value' will be
+bound to the property's value node, type and value as in
+`icalendar-with-node-value'.  If BODY is nil, it is assumed to be the
+symbol `value'; thus
+  (icalendar-with-property-of some-component some-type)
+is equivalent to
+  (icalendar-with-property-of some-component some-type nil value)
+
+BINDINGS can be used to bind the property's parameters; see
+`icalendar-with-node-children' for the form of BINDINGS.")
+
+(defmacro ical:with-param-of (node type &rest body)
+  "Like `icalendar-with-param', but for properties containing that param.
+
+Find the first parameter node of TYPE in NODE and execute BODY.
+
+Within BODY, the symbols `value-node', `value-type', and `value' will be
+bound to the parameter's value node, type and value as in
+`icalendar-with-node-value'.  If BODY is nil, it is assumed to be the
+symbol `value'; thus
+  (icalendar-with-param-of some-property some-type)
+is equivalent to
+  (icalendar-with-param-of some-property some-type nil value)"
+  (declare (debug (form form &rest form))
+           (indent 2))
+  `(ical:with-child-of ,node ,type nil ,@body))
+
+(provide 'icalendar-macs)
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-"))
+;; End:
+;;; icalendar-macs.el ends here
diff --git a/lisp/calendar/icalendar-mode.el b/lisp/calendar/icalendar-mode.el
new file mode 100644
index 00000000000..c68a912d296
--- /dev/null
+++ b/lisp/calendar/icalendar-mode.el
@@ -0,0 +1,611 @@
+;;; icalendar-mode.el --- Major mode for iCalendar format  -*- lexical-binding: t; -*-
+;;;
+
+;; Copyright (C) 2024 Free Software Foundation, Inc.
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: October 2024
+;; Keywords: calendar
+;; Human-Keywords: calendar, iCalendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file defines icalendar-mode, a major mode for iCalendar data.
+;; Its main job is to provide syntax highlighting using the matching
+;; functions created for iCalendar syntax in icalendar-parser.el, and to
+;; perform line unfolding and folding via format conversion.
+
+;; When activated, icalendar-mode unfolds content lines if necessary.
+;; This is because the parsing functions, and thus syntax highlighting,
+;; assume that content lines have already been unfolded.  When a buffer
+;; is saved, icalendar-mode also automatically folds long content if
+;; necessary, as required by RFC5545.
+
+
+;;; Code:
+(require 'icalendar-parser)
+(require 'format)
+
+;; Faces and font lock:
+(defgroup ical:faces
+  '((ical:property-name custom-face)
+    (ical:property-value custom-face)
+    (ical:parameter-name custom-face)
+    (ical:parameter-value custom-face)
+    (ical:component-name custom-face)
+    (ical:keyword custom-face)
+    (ical:binary-data custom-face)
+    (ical:date-time-types custom-face)
+    (ical:numeric-types custom-face)
+    (ical:recurrence-rule custom-face)
+    (ical:warning custom-face)
+    (ical:ignored custom-face))
+  "Faces for `icalendar-mode'."
+  :version "31.1"
+  :group 'icalendar
+  :prefix 'icalendar)
+
+(defface ical:property-name
+  '((default . (:inherit font-lock-keyword-face)))
+  "Face for iCalendar property names.")
+
+(defface ical:property-value
+  '((default . (:inherit default)))
+  "Face for iCalendar property values.")
+
+(defface ical:parameter-name
+  '((default . (:inherit font-lock-property-name-face)))
+  "Face for iCalendar parameter names.")
+
+(defface ical:parameter-value
+  '((default . (:inherit font-lock-property-use-face)))
+  "Face for iCalendar parameter values.")
+
+(defface ical:component-name
+  '((default . (:inherit font-lock-constant-face)))
+  "Face for iCalendar component names.")
+
+(defface ical:keyword
+  '((default . (:inherit font-lock-keyword-face)))
+  "Face for other iCalendar keywords.")
+
+(defface ical:binary-data
+  '((default . (:inherit font-lock-comment-face)))
+  "Face for iCalendar values that represent binary data.")
+
+(defface ical:date-time-types
+  '((default . (:inherit font-lock-type-face)))
+  "Face for iCalendar values that represent time.
+These include dates, date-times, durations, periods, and UTC offsets.")
+
+(defface ical:numeric-types
+  '((default . (:inherit ical:property-value-face)))
+  "Face for iCalendar values that represent integers, floats, and geolocations.")
+
+(defface ical:recurrence-rule
+  '((default . (:inherit font-lock-type-face)))
+  "Face for iCalendar recurrence rule values.")
+
+(defface ical:uri
+  '((default . (:inherit ical:property-value-face :underline t)))
+  "Face for iCalendar values that are URIs (including URLs and mail addresses).")
+
+(defface ical:warning
+  '((default . (:inherit font-lock-warning-face)))
+  "Face for iCalendar syntax errors.")
+
+(defface ical:ignored
+  '((default . (:inherit font-lock-comment-face)))
+  "Face for iCalendar syntax which is parsed but ignored.")
+
+;;; Font lock:
+(defconst ical:params-font-lock-keywords
+  '((ical:match-other-param
+     (1 'font-lock-comment-face t t)
+     (2 'font-lock-comment-face t t)
+     (3 'ical:warning t t))
+    (ical:match-value-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-tzid-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:parameter-value t t)
+     (3 'ical:warning t t))
+    (ical:match-sent-by-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-rsvp-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-role-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-reltype-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-related-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-range-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-partstat-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-member-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-language-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:parameter-value t t)
+     (3 'ical:warning t t))
+    (ical:match-fbtype-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-fmttype-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:parameter-value t t)
+     (3 'ical:warning t t))
+    (ical:match-encoding-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-dir-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-delegated-to-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-delegated-from-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-cutype-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-cn-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:parameter-value t t)
+     (3 'ical:warning t t))
+    (ical:match-altrep-param
+     (1 'ical:parameter-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t)))
+  "Entries for iCalendar property parameters in `font-lock-keywords'.")
+
+(defconst ical:properties-font-lock-keywords
+  '((ical:match-request-status-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-other-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-sequence-property
+     (1 'ical:property-name t t)
+     (2 'ical:numeric-types t t)
+     (3 'ical:warning t t))
+    (ical:match-last-modified-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-dtstamp-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-created-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-trigger-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-repeat-property
+     (1 'ical:property-name t t)
+     (2 'ical:numeric-types t t)
+     (3 'ical:warning t t))
+    (ical:match-action-property
+     (1 'ical:property-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-rrule-property
+     (1 'ical:property-name t t)
+     (2 'ical:recurrence-rule t t)
+     (3 'ical:warning t t))
+    (ical:match-rdate-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-exdate-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-uid-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-url-property
+     (1 'ical:property-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-related-to-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-recurrence-id-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-organizer-property
+     (1 'ical:property-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-contact-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-attendee-property
+     (1 'ical:property-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-tzurl-property
+     (1 'ical:property-name t t)
+     (2 'ical:uri t t)
+     (3 'ical:warning t t))
+    (ical:match-tzoffsetto-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-tzoffsetfrom-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-tzname-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-tzid-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-transp-property
+     (1 'ical:property-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-freebusy-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-duration-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-dtstart-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-due-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-dtend-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-completed-property
+     (1 'ical:property-name t t)
+     (2 'ical:date-time-types t t)
+     (3 'ical:warning t t))
+    (ical:match-summary-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-status-property
+     (1 'ical:property-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-resources-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-priority-property
+     (1 'ical:property-name t t)
+     (2 'ical:numeric-types t t)
+     (3 'ical:warning t t))
+    (ical:match-percent-complete-property
+     (1 'ical:property-name t t)
+     (2 'ical:numeric-types t t)
+     (3 'ical:warning t t))
+    (ical:match-location-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-geo-property
+     (1 'ical:property-name t t)
+     (2 'ical:numeric-types t t)
+     (3 'ical:warning t t))
+    (ical:match-description-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-comment-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-class-property
+     (1 'ical:property-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t))
+    (ical:match-categories-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-attach-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t)
+     (13 'ical:uri t t)
+     (14 'ical:binary-data t t))
+    (ical:match-version-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-prodid-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-method-property
+     (1 'ical:property-name t t)
+     (2 'ical:property-value t t)
+     (3 'ical:warning t t))
+    (ical:match-calscale-property
+     (1 'ical:property-name t t)
+     (2 'ical:keyword t t)
+     (3 'ical:warning t t)))
+  "Entries for iCalendar properties in `font-lock-keywords'.")
+
+(defconst ical:ignored-properties-font-lock-keywords
+  `((,(rx ical:other-property) (1 'ical:ignored keep t)
+                               (2 'ical:ignored keep t)))
+  "Entries for iCalendar ignored properties in `font-lock-keywords'.")
+
+(defconst ical:components-font-lock-keywords
+  '((ical:match-vcalendar-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-other-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-valarm-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-daylight-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-standard-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-vtimezone-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-vfreebusy-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-vjournal-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-vtodo-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t))
+    (ical:match-vevent-component
+     (1 'ical:keyword t t)
+     (2 'ical:component-name t t)))
+  "Entries for iCalendar components in `font-lock-keywords'.")
+
+(defvar ical:font-lock-keywords
+  (append ical:params-font-lock-keywords
+          ical:properties-font-lock-keywords
+          ical:components-font-lock-keywords
+          ical:ignored-properties-font-lock-keywords)
+  "Value of `font-lock-keywords' for `icalendar-mode'.")
+
+
+;; The major mode:
+
+;;; Mode hook
+(defvar ical:mode-hook nil
+  "Hook run when activating `icalendar-mode'.")
+
+;;; Activating the mode for .ics files:
+(add-to-list 'auto-mode-alist '("\\.ics\\'" . icalendar-mode))
+
+;;; Syntax table
+(defvar ical:mode-syntax-table
+    (let ((st (make-syntax-table)))
+      ;; Characters for which the standard syntax table suffices:
+      ;; ; (punctuation): separates some property values, and property parameters
+      ;; " (string): begins and ends string values
+      ;; : (punctuation): separates property name (and parameters) from property
+      ;;                  values
+      ;; , (punctuation): separates values in a list
+      ;; CR, LF (whitespace): content line endings
+      ;; space (whitespace): when at the beginning of a line, continues the
+      ;;                     previous line
+
+      ;; Characters which need to be adjusted from the standard syntax table:
+      ;; = is punctuation, not a symbol constituent:
+      (modify-syntax-entry ?= ".   " st)
+      ;; / is punctuation, not a symbol constituent:
+      (modify-syntax-entry ?/ ".   " st)
+      st)
+    "Syntax table used in `icalendar-mode'.")
+
+;;; Coding systems
+
+;; Provide a hint to the decoding system that iCalendar files use DOS
+;; line endings.  This appears to be the simplest way to ensure that
+;; `find-file' will correctly decode an iCalendar file, since decoding
+;; happens before icalendar-mode starts.
+(add-to-list 'file-coding-system-alist '("\\.ics\\'" . undecided-dos))
+
+;;; Format conversion
+
+;; We use the format conversion infrastructure provided by format.el,
+;; `insert-file-contents', and `write-region' to automatically perform
+;; line unfolding when icalendar-mode starts in a buffer, and line
+;; folding when it is saved to a file.  See Info node `(elisp)Format
+;; Conversion' for more.
+
+(defconst ical:format-definition
+  '(text/calendar "iCalendar format"
+                  nil ; no regexp - icalendar-mode runs decode instead
+                  ical:unfold-region       ; decoding function
+                  ical:folding-annotations ; encoding function
+                  nil ; encoding function does not modify buffer
+                  nil ; no need to activate a minor mode
+                  t)  ; preserve the format when saving
+  "Entry for iCalendar format in `format-alist'.")
+
+(add-to-list 'format-alist ical:format-definition)
+
+(defun ical:-format-decode-buffer ()
+  "Call `format-decode-buffer' with the \\='text/calendar format.
+This function is intended to be run from `icalendar-mode-hook'."
+  (format-decode-buffer 'text/calendar))
+
+(add-hook 'ical:mode-hook #'ical:-format-decode-buffer -90)
+
+(defun ical:-disable-auto-fill ()
+  "Disable `auto-fill-mode' in iCalendar buffers.
+Auto-fill-mode interferes with line folding and syntax highlighting, so
+it is off by default in iCalendar buffers.  This function is intended to
+be run from `icalendar-mode-hook'."
+  (when auto-fill-function
+    (auto-fill-mode -1)))
+
+(add-hook 'ical:mode-hook #'ical:-disable-auto-fill -91)
+
+;;; Commands
+
+(defun ical:switch-to-unfolded-buffer ()
+  "Switch to a new buffer with content lines unfolded.
+The new buffer will contain the same data as the current buffer, but
+with content lines unfolded (before decoding, if possible).
+
+`Folding' means inserting a line break and a single whitespace
+character to continue lines longer than 75 octets; `unfolding'
+means removing the extra whitespace inserted by folding.  The
+iCalendar standard (RFC5545) requires folding lines when
+serializing data to iCalendar format, and unfolding before
+parsing it.  In `icalendar-mode', folded lines may not have proper
+syntax highlighting; this command allows you to view iCalendar
+data with proper syntax highlighting, as the parser sees it.
+
+If the current buffer is visiting a file, this function will
+offer to save the buffer first, and then reload the contents from
+the file, performing unfolding with `icalendar-unfold-undecoded-region'
+before decoding it.  This is the most reliable way to unfold lines.
+
+If it is not visiting a file, it will unfold the new buffer
+with `icalendar-unfold-region'.  This can in some cases have
+undesirable effects (see its docstring), so the original contents
+are preserved unchanged in the current buffer.
+
+In both cases, after switching to the new buffer, this command
+offers to kill the original buffer.
+
+It is recommended to turn off `auto-fill-mode' when viewing an
+unfolded buffer, so that filling does not interfere with syntax
+highlighting.  This function offers to disable `auto-fill-mode' if
+it is enabled in the new buffer; consider using
+`visual-line-mode' instead."
+  (interactive)
+  (when (and buffer-file-name (buffer-modified-p))
+    (when (y-or-n-p (format "Save before reloading from %s?"
+                            (file-name-nondirectory buffer-file-name)))
+      (save-buffer)))
+  (let ((old-buffer (current-buffer))
+        (mmode major-mode)
+        (uf-buffer (if buffer-file-name
+                       (ical:unfolded-buffer-from-file buffer-file-name)
+                     (ical:unfolded-buffer-from-buffer (current-buffer)))))
+    (switch-to-buffer uf-buffer)
+    ;; restart original major mode, in case the new buffer is
+    ;; still in fundamental-mode: TODO: is this necessary?
+    (funcall mmode)
+    (when (y-or-n-p (format "Unfolded buffer is shown.  Kill %s?"
+                            (buffer-name old-buffer)))
+      (kill-buffer old-buffer))
+    (when (and auto-fill-function (y-or-n-p "Disable auto-fill-mode?"))
+      (auto-fill-mode -1))))
+
+;;; Mode definition
+;;;###autoload
+(define-derived-mode icalendar-mode text-mode "iCalendar"
+  "Major mode for viewing and editing iCalendar (RFC5545) data.
+
+This mode provides syntax highlighting for iCalendar components,
+properties, values, and property parameters, and defines a format to
+automatically handle folding and unfolding iCalendar content lines.
+
+`Folding' means inserting whitespace characters to continue long
+lines; `unfolding' means removing the extra whitespace inserted
+by folding.  The iCalendar standard requires folding lines when
+serializing data to iCalendar format, and unfolding before
+parsing it.
+
+Thus icalendar-mode's syntax highlighting is designed to work with
+unfolded lines.  When `icalendar-mode' is activated in a buffer, it will
+automatically unfold lines using a file format conversion, and
+automatically fold lines when saving the buffer to a file; see Info
+node `(elisp)Format Conversion' for more information.  It also disables
+`auto-fill-mode' if it is active, since filling interferes with line
+folding and syntax highlighting.  Consider using `visual-line-mode' in
+`icalendar-mode' instead."
+  :group 'icalendar
+  :syntax-table ical:mode-syntax-table
+  ;; TODO: Keymap?
+  ;; TODO: buffer-local variables?
+  ;; TODO: indent-line-function and indentation variables
+  ;; TODO: mode-specific menu and context menus
+  ;; TODO: eldoc integration
+  ;; TODO: completion of keywords
+  (progn
+    (setq font-lock-defaults '(ical:font-lock-keywords nil t))))
+
+(provide 'icalendar-mode)
+
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-"))
+;; End:
+;;; icalendar-mode.el ends here
diff --git a/lisp/calendar/icalendar-parser.el b/lisp/calendar/icalendar-parser.el
new file mode 100644
index 00000000000..a2ce4b2362f
--- /dev/null
+++ b/lisp/calendar/icalendar-parser.el
@@ -0,0 +1,4887 @@
+;;; icalendar-parser.el --- Parse iCalendar grammar  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024 Free Software Foundation, Inc.
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: October 2024
+;; Keywords: calendar
+;; Human-Keywords: calendar, iCalendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file defines regular expressions, constants and functions that
+;; implement the iCalendar grammar according to RFC5545.
+;;
+;; iCalendar data is grouped into *components*, such as events or
+;; to-do items.  Each component contains one or more *content lines*,
+;; which each contain a *property* name and its *value*, and possibly
+;; also property *parameters* with additional data that affects the
+;; interpretation of the property.
+;;
+;; The macros `ical:define-type', `ical:define-param',
+;; `ical:define-property' and `ical:define-component', defined in
+;; icalendar-macs.el, each create rx-style regular expressions for one
+;; of these categories in the grammar and are used here to define the
+;; particular value types, parameters, properties and components in the
+;; standard as type symbols.  These type symbols store all the metadata
+;; about the relevant types, and are used for type-based dispatch in the
+;; parser and printer functions.  In the abstract syntax tree, each node
+;; contains a type symbol naming its type.  A number of other regular
+;; expressions which encode basic categories of the grammar are also
+;; defined in this file.
+;;
+;; The following functions provide the high-level interface to the parser:
+;;
+;;   `icalendar-parse-and-index'
+;;   `icalendar-parse'
+;;   `icalendar-parse-calendar'
+;;   `icalendar-parse-component'
+;;   `icalendar-parse-property'
+;;   `icalendar-parse-params'
+;;
+;; The format of the abstract syntax tree which these functions create
+;; is documented in icalendar-ast.el.  Nodes in this tree can be
+;; serialized to iCalendar format with the corresponding printer
+;; functions:
+;;
+;;   `icalendar-print-calendar-node'
+;;   `icalendar-print-component-node'
+;;   `icalendar-print-property-node'
+;;   `icalendar-print-params'
+
+;;; Code:
+
+(require 'icalendar)
+(eval-when-compile (require 'icalendar-macs))
+(require 'icalendar-ast)
+(eval-when-compile (require 'cl-lib))
+(require 'subr-x)
+(require 'seq)
+(require 'rx)
+(require 'calendar)
+(require 'time-date)
+(require 'simple)
+(require 'help-mode)
+
+;;; Customization
+(defgroup icalendar-parser nil
+  "iCalendar parsing options."
+  :version "31.1"
+  :group 'icalendar
+  :prefix 'icalendar)
+
+(defcustom ical:parse-strictly nil
+  "When non-nil, iCalendar data will be parsed strictly.
+
+By default, the iCalendar parser accepts certain harmless deviations
+from RFC5545 that are common in real-world data (e.g., unescaped commas
+in text values).  Setting this to t will cause the parser to produce
+errors instead of silently accepting such data."
+  :version "31.1"
+  :type '(choice (const :tag "Ignore minor errors" nil)
+                 (const :tag "Parse strictly" t)))
+
+;;; Functions for folding and unfolding
+;;
+;; According to RFC5545, iCalendar content lines longer than 75 octets
+;; should be *folded* by inserting extra line breaks and leading
+;; whitespace to continue the line.  Such lines must be *unfolded*
+;; before they can be parsed.  Unfolding can only reliably happen
+;; before Emacs decodes a region of text, because decoding potentially
+;; replaces the CR-LF line endings which terminate content lines.
+;; Programs that can control when decoding happens should use the
+;; stricter `ical:unfold-undecoded-region' to unfold text; programs
+;; that must work with decoded data should use the looser
+;; `ical:unfold-region'. `ical:fold-region' will fold content lines
+;; using line breaks appropriate to the buffer's coding system.
+;;
+;; All the parsing-related code belows assumes that lines have
+;; already been unfolded if necessary.
+(defcustom ical:pre-unfolding-hook nil
+  "Hook run before unfolding iCalendar data.
+
+The functions in this hook will be run before the iCalendar data is
+\"unfolded\", i.e., before whitespace introduced for breaking long lines
+is removed (see `icalendar-unfold-region' and
+`icalendar-unfold-undecoded-region').  If you routinely receive
+iCalendar data that is not correctly folded, you can add functions to
+this hook which clean up that data before unfolding is attempted.
+
+Each function should accept zero arguments and should perform its
+operation on the entire current buffer."
+  :version "31.1"
+  :type '(hook)
+  :options '(ical:fix-line-endings))
+
+(defun ical:fix-line-endings ()
+  "Convert all line endings to LF.
+This function is intended to be used from `icalendar-pre-unfolding-hook'
+(which see) to make files with inconsistent line endings parseable."
+  (when ical:parse-strictly
+    (ical:warn
+     (concat "Converting line endings to LF causes parsing "
+             "errors when `icalendar-parse-strictly' is non-nil.")))
+  (goto-char (point-min))
+  (while (re-search-forward "\r\n?" nil t)
+    (replace-match "\n")))
+
+(defun ical:unfold-undecoded-region (start end &optional buffer)
+  "Unfold an undecoded region in BUFFER between START and END.
+If omitted, BUFFER defaults to the current buffer.
+
+\"Unfolding\" means removing the whitespace characters inserted to
+continue lines longer than 75 octets (see `icalendar-fold-region'
+for the folding operation).  RFC5545 specifies these whitespace
+characters to be a CR-LF sequence followed by a single space or
+tab character.  Unfolding can only be done reliably before a
+region is decoded, since decoding potentially replaces CR-LF line
+endings.
+
+When `icalendar-parse-strictly' is non-nil, this function searches
+strictly for CR-LF sequences and will fail if they have already been
+replaced, so it should only be called with a region that has not yet
+been decoded.  Otherwise, it also searches for folds containing
+Unix-style LF line endings, since these are common in real data."
+  (with-current-buffer (or buffer (current-buffer))
+    (let ((modp (buffer-modified-p)))
+      (with-restriction start end
+        (run-hooks 'ical:pre-unfolding-hook)
+        (goto-char (point-min))
+        ;; Testing reveals that a *significant* amount of real-world data
+        ;; does not use CR-LF line endings, even if it is otherwise
+        ;; OK.  So unless we're explicitly parsing strictly, we allow the
+        ;; CR to be missing, as we do in `icalendar-unfold-region':
+        (let ((fold (if ical:parse-strictly (rx (seq "\r\n" (or " " "\t")))
+                      (rx (seq (zero-or-one "\r") "\n" (or " " "\t"))))))
+          (while (re-search-forward fold nil t)
+            (replace-match "" nil nil)))
+        ;; merely unfolding should not mark the buffer as modified;
+        ;; this prevents querying the user before killing it:
+        (set-buffer-modified-p modp)))))
+
+(defun ical:unfold-region (start end &optional buffer)
+  "Unfold region between START and END in BUFFER (default: current buffer).
+
+\"Unfolding\" means removing the whitespace characters inserted to
+continue lines longer than 75 octets (see `icalendar-fold-region'
+for the folding operation).
+
+Returns the new end position after unfolding finishes.  Thus this
+function is a suitable FROM-FN (decoding function) for `format-alist'.
+
+WARNING: Unfolding can only be done reliably before text is
+decoded, since decoding potentially replaces CR-LF line endings.
+Unfolding an already-decoded region could lead to unexpected
+results, such as displaying multibyte characters incorrectly,
+depending on the contents and the coding system used.
+
+This function attempts to do the right thing even if the region
+is already decoded.  If it is still undecoded, it is better to
+call `icalendar-unfold-undecoded-region' directly instead, and
+decode it afterward."
+  ;; TODO: also make this a command so it can be run manually?
+  (with-current-buffer (or buffer (current-buffer))
+    (let ((was-multibyte enable-multibyte-characters)
+          (start-char (position-bytes start))
+          (end-char (position-bytes end))
+          (end-marker (make-marker)))
+      ;; set a marker at the original end position so we can return
+      ;; the updated position later:
+      (set-marker end-marker end)
+      ;; we put the buffer in unibyte mode and later restore its
+      ;; previous state, so that if the buffer was already multibyte,
+      ;; any multibyte characters where line folds broke up their
+      ;; bytes can be reinterpreted:
+      (set-buffer-multibyte nil)
+      (with-restriction start-char end-char
+        (run-hooks 'ical:pre-unfolding-hook)
+        (goto-char (point-min))
+        ;; since we can't be sure that line folds have a leading CR
+        ;; in already-decoded regions, do the best we can:
+        (while (re-search-forward (rx (seq (zero-or-one "\r") "\n"
+                                           (or " " "\t")))
+                                  nil t)
+          (replace-match "" nil nil)))
+      ;; restore previous state, possibly reinterpreting characters:
+      (set-buffer-multibyte was-multibyte)
+      ;; return the new end of the region, for format.el conversion:
+      (marker-position end-marker))))
+
+(defun ical:unfolded-buffer-from-region (start end &optional buffer)
+  "Create a new, unfolded buffer with the same contents as the region.
+
+Copies the buffer contents between START and END (in BUFFER, if
+provided) to a new buffer and performs line unfolding in the new buffer
+with `icalendar-unfold-region'.  That function can in some cases have
+undesirable effects; see its docstring.  If BUFFER is visiting a file, it
+may be better to reload its contents from that file and perform line
+unfolding before decoding; see `icalendar-unfolded-buffer-from-file'.
+Returns the new buffer."
+  (let* ((old-buffer (or buffer (current-buffer)))
+         (contents (with-current-buffer old-buffer
+                     (buffer-substring start end)))
+         (uf-buffer (generate-new-buffer ;; TODO: again, move to modeline?
+                     (concat " *UNFOLDED:" (buffer-name old-buffer)))))
+    (with-current-buffer uf-buffer
+      (insert contents)
+      (ical:unfold-region (point-min) (point-max))
+      ;; ensure we'll use CR-LF line endings on write, even if they weren't
+      ;; in the source data.  The standard also says UTF-8 is the default
+      ;; encoding, so use 'prefer-utf-8-dos when last-coding-system-used
+      ;; is nil.
+      (setq buffer-file-coding-system
+            (if last-coding-system-used
+                (coding-system-change-eol-conversion last-coding-system-used
+                                                     'dos)
+              'prefer-utf-8-dos))
+      ;; inhibit auto-save-mode, which will otherwise create save
+      ;; files containing the unfolded data; these are probably
+      ;; not useful to the user and a nuisance when running tests:
+      (auto-save-mode -1))
+    uf-buffer))
+
+(defun ical:unfolded-buffer-from-buffer (buffer)
+  "Create a new, unfolded buffer with the same contents as BUFFER.
+
+Copies the contents of BUFFER to a new buffer and performs line
+unfolding there with `icalendar-unfold-region'.  That function can in
+some cases have undesirable effects; see its docstring.  If BUFFER is
+visiting a file, it may be better to reload its contents from that file
+and perform line unfolding before decoding; see
+`icalendar-unfolded-buffer-from-file'.  Returns the new buffer."
+  (with-current-buffer buffer
+    (ical:unfolded-buffer-from-region (point-min) (point-max) buffer)))
+
+(defun ical:find-unfolded-buffer-visiting (filename)
+  "Find an existing unfolded buffer visiting FILENAME."
+  ;; FIXME: I was previously using
+  ;;   (find-buffer-visiting filename #'ical:unfolded-p)
+  ;; for this, but found that it would sometimes return nil even when an
+  ;; unfolded buffer already existed for FILENAME, leading to buffers
+  ;; getting unfolded and parsed multiple times.  Hence this kludge.
+  (catch 'unfolded
+    (let ((exp-name (expand-file-name filename)))
+      (dolist (buf (match-buffers "UNFOLDED"))
+        (when (and (equal exp-name (buffer-file-name buf))
+                   (ical:unfolded-p buf))
+          (throw 'unfolded buf))))))
+
+(defun ical:unfolded-buffer-from-file (filename &optional visit beg end)
+    "Return a buffer visiting FILENAME with unfolded lines.
+
+If an unfolded buffer is already visiting FILENAME, return
+it.  Otherwise, create a new buffer with the contents of FILENAME and
+perform line unfolding with `icalendar-unfold-undecoded-region', then
+decode the buffer, setting an appropriate value for
+`buffer-file-coding-system', and return the new buffer.  Optional
+arguments VISIT, BEG, END are as in `insert-file-contents'."
+    (unless (and (file-exists-p filename)
+                 (file-readable-p filename))
+      (error "File cannot be read: %s" filename))
+    (or (ical:find-unfolded-buffer-visiting filename)
+        (let ((uf-buffer
+               (generate-new-buffer
+                (concat " *UNFOLDED:" (file-name-nondirectory filename)))))
+          (with-current-buffer uf-buffer
+            (set-buffer-multibyte nil)
+            (insert-file-contents-literally filename visit beg end t)
+            (ical:unfold-undecoded-region (point-min) (point-max))
+            ;; now proceed with decoding:
+            (set-buffer-multibyte t)
+            (decode-coding-inserted-region (point-min) (point-max) filename)
+            ;; ensure we'll use CR-LF line endings on write, even if they weren't
+            ;; in the source data.  The standard also says UTF-8 is the default
+            ;; encoding, so use 'prefer-utf-8-dos when last-coding-system-used
+            ;; is nil.  FIXME: for some reason, this doesn't seem to run at all!
+            (setq buffer-file-coding-system
+                  (if last-coding-system-used
+                      (coding-system-change-eol-conversion last-coding-system-used
+                                                           'dos)
+                    'prefer-utf-8-dos))
+            ;; restore buffer name after renaming by set-visited-file-name:
+            (let ((bname (buffer-name)))
+              (set-visited-file-name filename t)
+              (rename-buffer bname))
+            ;; merely unfolding should not mark the buffer as modified;
+            ;; this prevents querying the user before killing it:
+            (set-buffer-modified-p nil)
+            ;; inhibit auto-save-mode, which will otherwise create save
+            ;; files containing the unfolded data; these are probably
+            ;; not useful to the user and a nuisance when running tests:
+            (auto-save-mode -1))
+        uf-buffer)))
+
+(defun ical:fold-region (begin end &optional annotate-only use-tabs)
+  "Fold content lines between BEGIN and END when longer than 75 octets.
+
+\"Folding\" means inserting a line break and a single space
+character at the beginning of the new line.  If USE-TABS is
+non-nil, insert a tab character instead of a single space.
+
+RFC5545 specifies that lines longer than 75 *octets* (excluding
+the line-ending CR-LF sequence) must be folded, and allows that
+some implementations might fold lines in the middle of a
+multibyte character.  This function takes care not to do that in a
+buffer where `enable-multibyte-characters' is non-nil, and only
+folds between character boundaries.  If the buffer is in unibyte
+mode, however, and contains undecoded multibyte data, it may fold
+lines in the middle of a multibyte character.
+
+By default, this function modifies the region by inserting line folds.
+If the optional argument ANNOTATE-ONLY is non-nil, it will instead leave
+the buffer unmodified, and return a list of \"annotations\"
+\(POSITION . LINE-FOLD), indicating where line folds in the region should
+be inserted.  This output is suitable for a function in
+`write-region-annotation-functions'; `icalendar-folding-annotations'
+is a wrapper for this function which can be added to that list."
+  ;; TODO: also make this a command so it can be run manually?
+  (let (annotations)
+    (save-excursion
+      (goto-char begin)
+      (when (not (bolp))
+        (let ((inhibit-field-text-motion t))
+          (beginning-of-line)))
+      (let ((bol (point))
+            (eol (make-marker))
+            (reg-end (make-marker))
+            (line-fold (if use-tabs "\n\t" "\n ")))
+        (set-marker reg-end end)
+        (while (< bol reg-end)
+          (let ((inhibit-field-text-motion t))
+            (end-of-line))
+          (set-marker eol (point))
+          (when (< 75 (- (position-bytes (marker-position eol))
+                         (position-bytes bol)))
+            (goto-char
+             ;; the max of 75 excludes the two CR-LF
+             ;; characters we're about to add:
+             (byte-to-position (+ 75 (position-bytes bol))))
+            (if annotate-only
+                (push (cons (point) line-fold) annotations)
+              (insert line-fold))
+            (set-marker eol (point)))
+          (setq bol (goto-char (1+ eol))))))
+    ;; Return annotations, or nil if we modified the buffer directly:
+    (nreverse annotations)))
+
+(defun ical:folding-annotations (start end &optional buffer)
+  "Return a list of annotations for folding lines in the region.
+
+This function is a wrapper for `icalendar-fold-region' that provides the
+interface to be used from `write-region-annotation-functions', which
+see."
+  ;; start may be nil or a string; see `write-region'
+  (if (stringp start)
+      (let ((buf (generate-new-buffer " *icalendar-folded*")))
+        (set-buffer buf)
+        (insert start)
+        (ical:fold-region (point-min) (point-max) t))
+
+    (when (bufferp buffer) (set-buffer buffer))
+    (ical:fold-region (or start (point-min))
+                      (if start end (point-max))
+                      t)))
+
+(defun ical:contains-folded-lines-p (&optional buffer)
+  "Return non-nil if BUFFER contains folded content lines.
+
+BUFFER defaults to the current buffer.  Folded content lines need to be
+unfolded before parsing the buffer or performing syntax
+highlighting.  Returns the position at the end of the first fold, or nil."
+  (with-current-buffer (or buffer (current-buffer))
+    (save-excursion
+      (goto-char (point-min))
+      (re-search-forward (rx (seq line-start (or " " "\t")))
+                         nil t))))
+
+(defun ical:unfolded-p (&optional buffer)
+  "Return non-nil if BUFFER does not contain any folded content lines.
+BUFFER defaults to the current buffer."
+  (not (ical:contains-folded-lines-p buffer)))
+
+(defun ical:contains-unfolded-lines-p (&optional buffer)
+  "Return non-nil if BUFFER contains long content lines that should be folded.
+
+Lines longer than 75 bytes need to folded before saving or transmitting
+the data in BUFFER (default: current buffer).  If BUFFER contains such
+lines, return the position at the beginning of the first line that
+requires folding."
+  (with-current-buffer (or buffer (current-buffer))
+    (save-excursion
+      (goto-char (point-min))
+      (let ((bol (point))
+            (eol (make-marker)))
+        (catch 'unfolded-line
+          (while (< bol (point-max))
+            (let ((inhibit-field-text-motion t))
+              (end-of-line))
+            (set-marker eol (point))
+            ;; the max of 75 excludes the two CR-LF characters
+            ;; after position eol:
+            (when (< 75 (- (position-bytes (marker-position eol))
+                           (position-bytes bol)))
+              (throw 'unfolded-line bol))
+            (setq bol (goto-char (1+ eol))))
+          nil)))))
+
+(defun ical:folded-p (&optional buffer)
+  "Return non-nil if BUFFER contains no content lines that require folding.
+BUFFER defaults to the current buffer."
+  (not (ical:contains-unfolded-lines-p buffer)))
+
+
+;; Parsing-related code starts here.  All the parsing code assumes that
+;; content lines have already been unfolded.
+
+;;;; Error handling:
+
+;; Errors at the parsing stage:
+;; e.g. value does not match expected regex
+(define-error 'ical:parse-error "Could not parse iCalendar data" 'ical:error)
+
+(cl-defun ical:signal-parse-error (msg &key (buffer (current-buffer))
+                                       (position (point))
+                                       (severity 2)
+                                       (line (line-number-at-pos position))
+                                       column restart-at)
+  (signal 'ical:parse-error
+          (list :message msg
+                :line line
+                :column column
+                :severity severity
+                :position position
+                :buffer buffer
+                :restart-at restart-at)))
+
+(defun ical:handle-parse-error (err-data &optional skip-msg err-buffer)
+  (let* ((err-sym (car err-data))
+         (err-plist (cdr err-data))
+         (buf (plist-get err-plist :buffer))
+         (restart-pos (plist-get err-plist :restart-at))
+         (new-msg
+          (concat (plist-get err-plist :message)
+                  "..."
+                  (cond (skip-msg skip-msg)
+                        (restart-pos (format "skipping to %d" restart-pos))
+                        (t "skipping")))))
+    (setq err-plist (plist-put err-plist :message new-msg))
+    (setq err-plist (plist-put err-plist :severity 1))
+    (ical:handle-generic-error (cons err-sym err-plist) err-buffer)
+    (when restart-pos
+      (with-current-buffer buf
+        (goto-char restart-pos)))))
+
+;; Errors at the printing stage:
+;; e.g. default print function doesn't know how to print value
+(define-error 'ical:print-error "Unable to print iCalendar data" 'ical:error)
+
+(cl-defun ical:signal-print-error (msg &key (severity 2) node)
+  (signal 'ical:print-error
+          (list :message msg
+                :node node
+                :buffer (ical:ast-node-meta-get :buffer node)
+                :severity severity
+                :position (ical:ast-node-meta-get :begin node))))
+
+(defun ical:handle-print-error (err-data &optional skip-msg err-buffer)
+  (let* ((err-sym (car err-data))
+         (err-plist (cdr err-data))
+         (new-msg (concat (plist-get err-plist :message)
+                          "..."
+                          (or skip-msg "skipping"))))
+    (setq err-plist (plist-put err-plist :message new-msg))
+    (setq err-plist (plist-put err-plist :severity 1))
+    (ical:handle-generic-error (cons err-sym err-plist) err-buffer))
+  (ical:handle-generic-error err-data err-buffer))
+
+;;;; Some utilities:
+(defun ical:parse-from-string (type s)
+  "Parse string S to an iCalendar syntax node of type TYPE.
+S should not contain folded content lines."
+  ;; TODO: support unfolding?
+  (with-temp-buffer
+    (insert s)
+    (goto-char (point-min))
+    (cond ((ical:component-type-symbol-p type)
+           (ical:parse-component (point-max)))
+          ((ical:property-type-symbol-p type)
+           (ical:parse-property (point-max)))
+          ((ical:param-type-symbol-p type)
+           (unless (looking-at-p ";")
+             (insert ";")
+             (backward-char))
+           (ical:parse-params (point-max)))
+          ((ical:value-type-symbol-p type)
+           (ical:parse-value-node type (point-max)))
+          (t
+           (error "Don't know how to parse type %s" type)))))
+
+(defun ical:parse-one-of (types limit)
+  "Parse a value, from point up to LIMIT, of one of the TYPES.
+
+TYPES should be a list of type symbols.  For each type in TYPES, the
+parser function associated with that type will be called at point.  The
+return value of the first successful parser function is returned.  If
+none of the parser functions are able to parse a value, an
+`icalendar-parse-error' is signaled."
+  (let* ((value nil)
+         (start (point))
+         (type (car types))
+         (parser (get type 'ical:value-parser))
+         (rest (cdr types)))
+    (while (and parser (not value))
+      (condition-case nil
+          (setq value (funcall parser limit))
+        (ical:parse-error
+         ;; value of this type not found, so try again:
+         (goto-char start)
+         (setq type (car rest)
+               rest (cdr rest)
+               parser (get type 'ical:value-parser)))))
+    (unless value
+      (ical:signal-parse-error
+       (format "Unable to parse any of %s between %d and %d" types start limit)
+       :position start))
+    value))
+
+(defun ical:read-list-with (reader string
+                            &optional value-regex separators omit-nulls trim)
+  "Read a list of values from STRING with READER.
+
+READER should be a reader function that accepts a single string argument.
+SEPARATORS, OMIT-NULLS, and TRIM are as in `split-string'.
+SEPARATORS defaults to \"[^\\][,;]\".  TRIM defaults to matching a
+double quote character.
+
+VALUE-REGEX should be a regular expression if READER assumes that
+individual substrings in STRING have previously been matched
+against this regex.  In this case, each value in S is placed in a
+temporary buffer and the match against VALUE-REGEX is performed
+before READER is called."
+  (let* ((wrapped-reader
+           (if (not value-regex)
+               ;; no need for temp buffer:
+               reader
+             ;; match the regex in a temp buffer before calling reader:
+             (lambda (s)
+               (with-temp-buffer
+                 (insert s)
+                 (goto-char (point-min))
+                 (unless (looking-at value-regex)
+                   (ical:signal-parse-error
+                    (format "Expected list of values matching '%s'" value-regex)))
+                 (funcall reader (match-string 0))))))
+         (seps (or separators "[^\\][,;]"))
+         (trm (or trim "\""))
+         (raw-values (split-string string seps omit-nulls trm)))
+
+    (unless (functionp reader)
+      (signal 'ical:parser-error
+              (list (format "`%s' is not a reader function" reader))))
+
+    (mapcar wrapped-reader raw-values)))
+
+(defun ical:read-list-of (type string
+                          &optional separators omit-nulls trim)
+  "Read a list of values of type TYPE from STRING.
+
+TYPE should be a value type symbol.  The reader function
+associated with that type will be called to read the successive
+values in STRING, and the values will be returned as a list of
+syntax nodes.
+
+SEPARATORS, OMIT-NULLS, and TRIM are as in `split-string' and
+will be passed on, if provided, to `icalendar-read-list-with'."
+  (let* ((reader (lambda (s) (ical:read-value-node type s)))
+         (val-regex (rx-to-string (get type 'ical:value-rx))))
+    (ical:read-list-with reader string val-regex
+                         separators omit-nulls trim)))
+
+(defun ical:list-of-p (list type)
+  "Return non-nil if each value in LIST satisfies TYPE.
+TYPE should be a type specifier for `cl-typep'."
+  (seq-every-p (lambda (val) (cl-typep val type)) list))
+
+(defun ical:default-value-printer (val)
+  "Default printer for a *single* property or parameter value.
+
+If VAL is a string, just return it unchanged.
+
+Otherwise, VAL should be a syntax node representing a value.  In
+that case, return the original string value if another was
+substituted at parse time, or look up the printer function for
+the node's type and call it on the value inside the node.
+
+For properties and parameters that only allow a single value,
+this function should be a sufficient value printer.  It is not
+sufficient for those that allow lists of values, or which have
+other special requirements like quoting or escaping."
+  (cond ((stringp val) val)
+        ((and (ical:ast-node-p val)
+              (get (ical:ast-node-type val) 'ical:value-printer))
+         (or (ical:ast-node-meta-get :original-value val)
+             (let* ((stored-value (ical:ast-node-value val))
+                    (type (ical:ast-node-type val))
+                    (printer (get type 'ical:value-printer)))
+               (funcall printer stored-value))))
+        ;; TODO: other cases to make things easy?
+        ;; e.g. symbols print as their names?
+        (t (ical:signal-print-error
+            (format "Don't know how to print value: %s" val)))))
+
+
+;;; Section 3.1: Content lines
+
+;; Regexp constants for parsing:
+
+;; In the following regexps and define-* declarations, because
+;; Emacs does not have named groups, we observe the following
+;; convention so that the regexps can be combined in sensible ways:
+;;
+;; - Groups 1 through 5 are reserved for the highest-level regexes
+;;   created by define-param, define-property and define-component and
+;;   used in the match-* functions.  Group 1 always represents a 'key'
+;;   (e.g. param or property name), group 2 always represents a
+;;   correctly parsed value for that key, and group 3 (if matched) an
+;;   invalid or unknown value.
+;;
+;;   Groups 4 and 5 are reserved for other information in these
+;;   highest-level regexes, such as the parameter string between a
+;;   property name and its value, or unrecognized values allowed by
+;;   the standard and required to be treated like a default value.
+;;
+;; - Groups 6 through 10 are currently unused
+;; - Groups 11 through 20 are reserved for significant sub-expressions
+;;   of individual value expressions, e.g. the number of weeks in a
+;;   duration value.  The various read-* functions rely on these groups
+;;   when converting iCalendar data to Elisp data structures.
+
+(rx-define ical:iana-token
+  (one-or-more (any "A-Za-z0-9" "-")))
+
+(rx-define ical:x-name
+  (seq "X-"
+       (zero-or-one (>= 3 (any "A-Za-z0-9")) "-") ; Vendor ID
+       (one-or-more (any "A-Za-z0-9" "-")))) ; Name
+
+(rx-define ical:name
+  (or ical:iana-token ical:x-name))
+
+(rx-define ical:crlf
+  (seq #x12 #xa))
+
+(rx-define ical:control
+  ;; All the controls except HTAB
+  (any (#x00 . #x08) (#x0A . #x1F) #x7F))
+
+;; TODO: double check that "nonascii" class actually corresponds to
+;; the range in the standard
+(rx-define ical:safe-char
+  ;; Any character except ical:control, ?\", ?\;, ?:, ?,
+  (any #x09 #x20 #x21  (#x23 . #x2B) (#x2D . #x39) (#x3C . #x7E) nonascii))
+
+(rx-define ical:qsafe-char
+  ;; Any character except ical:control and ?\"
+  (any #x09 #x20 #x21 (#x23 . #x7E) nonascii))
+
+(rx-define ical:quoted-string
+  (seq ?\" (zero-or-more ical:qsafe-char) ?\"))
+
+(rx-define ical:paramtext
+  ;; RFC5545 allows *zero* characters here, but that would mean we could
+  ;; have parameters like ;FOO=;BAR="somethingelse", and what would then
+  ;; be the value of FOO?  I see no reason to allow this and it breaks
+  ;; parameter parsing so I have required at least one char here
+  (one-or-more ical:safe-char))
+
+(rx-define ical:param-name
+  (or ical:iana-token ical:x-name))
+
+(rx-define ical:param-value
+  (or ical:paramtext ical:quoted-string))
+
+(rx-define ical:value-char
+  (any #x09 #x20 (#x21 . #x7E) nonascii))
+
+(rx-define ical:value
+  (zero-or-more ical:value-char))
+
+;; some helpers for brevity, not defined in the standard:
+(rx-define ical:comma-list (item-rx)
+  (seq item-rx
+       (zero-or-more (seq ?, item-rx))))
+
+(rx-define ical:semicolon-list (item-rx)
+  (seq item-rx
+       (zero-or-more (seq ?\; item-rx))))
+
+
+;;; Section 3.3: Property Value Data Types
+
+;; Note: These definitions are here (out of order with respect to the
+;; standard) because a few of them are already required for property
+;; parameter definitions (section 3.2) below.
+
+(defvar ical:value-types nil ;; populated by define-type
+  "Alist mapping value type strings to type symbols.
+Value type strings are those which can appear in `icalendar-valuetypeparam'
+parameters and specify the type of a property's value.")
+
+(defun ical:read-value-node (type s)
+  "Read an iCalendar value of type TYPE from string S to a syntax node.
+Returns a syntax node containing the value."
+  (let ((reader (get type 'ical:value-reader)))
+    (ical:make-ast-node type (list :value (funcall reader s)))))
+
+(defun ical:parse-value-node (type limit)
+  "Parse an iCalendar value of type TYPE from point up to LIMIT.
+Returns a syntax node containing the value."
+  (let ((value-regex (rx-to-string (get type 'ical:value-rx))))
+
+    (unless (re-search-forward value-regex limit t)
+      (ical:signal-parse-error
+       (format "No %s value between %d and %d" type (point) limit)))
+
+    (let ((begin (match-beginning 0))
+          (end (match-end 0))
+          (node (ical:read-value-node type (match-string 0))))
+      (ical:ast-node-meta-set node :buffer (current-buffer))
+      (ical:ast-node-meta-set node :begin begin)
+      (ical:ast-node-meta-set node :end end)
+
+      node)))
+
+(defun ical:print-value-node (node)
+  "Serialize an iCalendar syntax NODE containing a value to a string."
+  (let* ((type (ical:ast-node-type node))
+         (value-printer (get type 'ical:value-printer)))
+    (funcall value-printer (ical:ast-node-value node))))
+
+(defun ical:printable-value-type-symbol-p (symbol)
+  "Return non-nil if SYMBOL represents a printable iCalendar value type.
+
+This means that SYMBOL names a type for a property or parameter value
+defined by `icalendar-define-type' which has a print name (mainly for
+use in `icalendar-valuetypeparam' parameters).  That is, SYMBOL must *both*
+satisfy `icalendar-value-type-symbol-p' and be associated with a print
+name in `icalendar-value-types'."
+  (and (ical:value-type-symbol-p symbol)
+       (rassq symbol ical:value-types)))
+
+(defun ical:value-node-p (node)
+  "Return non-nil if NODE is a syntax node whose type is a value type."
+  (and (ical:ast-node-p node)
+       (ical:value-type-symbol-p (ical:ast-node-type node))))
+
+;;;; 3.3.1 Binary
+;; from https://www.rfc-editor.org/rfc/rfc4648#section-4:
+(rx-define ical:base64char
+  (any (?A . ?Z) (?a . ?z) (?0 . ?9) ?+ ?/))
+
+(ical:define-type ical:binary "BINARY"
+   "Type for Binary values.
+
+The parsed and printed representations are the same: a string of characters
+representing base64-encoded data."
+   '(and string (satisfies ical:match-binary-value))
+   (seq (zero-or-more (= 4 ical:base64char))
+        (zero-or-one (or (seq (= 2 ical:base64char) "==")
+                         (seq (= 3 ical:base64char) "="))))
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.1")
+
+;;;; 3.3.2 Boolean
+(defun ical:read-boolean (s)
+  "Read an `icalendar-boolean' value from a string S.
+S should be a match against rx `icalendar-boolean'."
+  (let ((upcased (upcase s)))
+    (cond ((equal upcased "TRUE") t)
+          ((equal upcased "FALSE") nil)
+          (t (ical:signal-parse-error
+              (format "Expected 'TRUE' or 'FALSE'; got %s" s))))))
+
+(defun ical:print-boolean (b)
+  "Serialize an `icalendar-boolean' value B to a string."
+    (if b "TRUE" "FALSE"))
+
+(ical:define-type ical:boolean "BOOLEAN"
+   "Type for Boolean values.
+
+When printed, either the string 'TRUE' or 'FALSE'.
+When read, either t or nil."
+   'boolean
+   (or "TRUE" "FALSE")
+   :reader ical:read-boolean
+   :printer ical:print-boolean
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.2")
+
+;;;; 3.3.3 Calendar User Address
+;; Defined with URI, below
+
+;; Dates and Times:
+
+;;;; 3.3.4 Date
+(cl-deftype ical:numeric-year () '(integer 0 9999))
+(cl-deftype ical:numeric-month () '(integer 1 12))
+(cl-deftype ical:numeric-monthday () '(integer 1 31))
+
+(rx-define ical:year
+  (= 4 digit))
+
+(rx-define ical:month
+  (= 2 digit))
+
+(rx-define ical:mday
+  (= 2 digit))
+
+(defun ical:read-date (s)
+  "Read an `icalendar-date' from a string S.
+S should be a match against rx `icalendar-date'."
+  (let ((year (string-to-number (substring s 0 4)))
+        (month (string-to-number (substring s 4 6)))
+        (day (string-to-number (substring s 6 8))))
+    (list month day year)))
+
+(defun ical:print-date (d)
+  "Serialize an `icalendar-date' to a string."
+  (format "%04d%02d%02d"
+          (calendar-extract-year d)
+          (calendar-extract-month d)
+          (calendar-extract-day d)))
+
+(ical:define-type ical:date "DATE"
+   "Type for Date values.
+
+When printed, a date is a string of digits in YYYYMMDD format.
+
+When read, a date is a list (MONTH DAY YEAR), with the three
+values being integers in the appropriate ranges; see calendar.el
+for functions that work with this representation."
+   '(and (satisfies calendar-date-is-valid-p))
+   (seq ical:year ical:month ical:mday)
+   :reader ical:read-date
+   :printer ical:print-date
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.4")
+
+;;;; 3.3.12 Time
+;; (Defined here so that ical:time RX can be used in ical:date-time)
+(cl-deftype ical:numeric-hour () '(integer 0 23))
+(cl-deftype ical:numeric-minute () '(integer 0 59))
+(cl-deftype ical:numeric-second () '(integer 0 60)) ; 60 represents a leap second
+
+(defun ical:read-time (s)
+  "Read an `icalendar-time' from a string S.
+S should be a match against rx `icalendar-time'."
+  (require 'icalendar-utils) ; for ical:make-date-time; avoids circular require
+  (declare-function ical:make-date-time "icalendar-utils")
+  (let ((hour (string-to-number (substring s 0 2)))
+        (minute (string-to-number (substring s 2 4)))
+        (second (string-to-number (substring s 4 6)))
+        (utcoffset (if (and (length= s 7)
+                            (equal "Z" (substring s 6 7)))
+                       0
+                     ;; unknown/'floating' time zone:
+                     nil)))
+    (ical:make-date-time :second second
+                         :minute minute
+                         :hour hour
+                         :zone utcoffset)))
+
+(defun ical:print-time (time)
+  "Serialize an `icalendar-time' to a string."
+  (format "%02d%02d%02d%s"
+          (decoded-time-hour time)
+          (decoded-time-minute time)
+          (decoded-time-second time)
+          (if (eql 0 (decoded-time-zone time))
+              "Z" "")))
+
+(defun ical:-decoded-time-p (val)
+  "Return non-nil if VAL is a valid decoded *time*.
+This predicate does not check date-related values in VAL;
+for that, see `icalendar--decoded-date-time-p'."
+  (and (listp val)
+       (length= val 9)
+       (cl-typep (decoded-time-second val) 'ical:numeric-second)
+       (cl-typep (decoded-time-minute val) 'ical:numeric-minute)
+       (cl-typep (decoded-time-hour val) 'ical:numeric-hour)
+       (cl-typep (decoded-time-dst val) '(member t nil -1))
+       (cl-typep (decoded-time-zone val) '(or integer null))))
+
+(ical:define-type ical:time "TIME"
+  "Type for Time values.
+
+When printed, a time is a string of six digits HHMMSS, followed
+by the letter 'Z' if it is in UTC.
+
+When read, a time is a decoded time, i.e. a list in the format
+(SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).  See
+`decode-time' for the specifics of the individual values.  When
+read, the DAY, MONTH, YEAR, and DOW fields are nil, and these
+fields and DST are ignored when printed."
+  '(satisfies ical:-decoded-time-p)
+  (seq (= 6 digit) (zero-or-one ?Z))
+  :reader ical:read-time
+  :printer ical:print-time
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.12")
+
+;;;; 3.3.5 Date-Time
+(defun ical:-decoded-date-time-p (val)
+  (and (listp val)
+       (length= val 9)
+       (cl-typep (decoded-time-second val) 'ical:numeric-second)
+       (cl-typep (decoded-time-minute val) 'ical:numeric-minute)
+       (cl-typep (decoded-time-hour val) 'ical:numeric-hour)
+       (cl-typep (decoded-time-day val) 'ical:numeric-monthday)
+       (cl-typep (decoded-time-month val) 'ical:numeric-month)
+       (cl-typep (decoded-time-year val) 'ical:numeric-year)
+       (calendar-date-is-valid-p (list (decoded-time-month val)
+                                       (decoded-time-day val)
+                                       (decoded-time-year val)))
+       ;; FIXME: the weekday slot value should be automatically
+       ;; calculated from month, day, and year, like:
+       ;;   (calendar-day-of-week (list month day year))
+       ;; Although `ical:read-date-time' does this correctly,
+       ;; `make-decoded-time' does not.  Thus we can't use
+       ;; `make-decoded-time' to construct valid `ical:date-time'
+       ;; values unless this check is turned off,
+       ;; which means it's annoying to write tests and anything
+       ;; that uses cl-typecase to dispatch on values created by
+       ;; `make-decoded-time':
+       ;; (cl-typep (decoded-time-weekday val) '(integer 0 6))
+       (cl-typep (decoded-time-dst val) '(member t nil -1))
+       (cl-typep (decoded-time-zone val) '(or integer null))))
+
+(defun ical:read-date-time (s)
+  "Read an `icalendar-date-time' from a string S.
+S should be a match against rx `icalendar-date-time'."
+  (require 'icalendar-utils) ; for ical:make-date-time; avoids circular requires
+  (let ((year (string-to-number (substring s 0 4)))
+        (month (string-to-number (substring s 4 6)))
+        (day (string-to-number (substring s 6 8)))
+        ;; "T" is index 8
+        (hour (string-to-number (substring s 9 11)))
+        (minute (string-to-number (substring s 11 13)))
+        (second (string-to-number (substring s 13 15)))
+        (utcoffset (if (and (length= s 16)
+                            (equal "Z" (substring s 15 16)))
+                       0
+                     ;; unknown/'floating' time zone:
+                     nil)))
+    (ical:make-date-time :second second
+                         :minute minute
+                         :hour hour
+                         :day day
+                         :month month
+                         :year year
+                         :zone utcoffset)))
+
+(defun ical:print-date-time (datetime)
+  "Serialize an `icalendar-date-time' to a string."
+  (format "%04d%02d%02dT%02d%02d%02d%s"
+          (decoded-time-year datetime)
+          (decoded-time-month datetime)
+          (decoded-time-day datetime)
+          (decoded-time-hour datetime)
+          (decoded-time-minute datetime)
+          (decoded-time-second datetime)
+          (if (ical:date-time-is-utc-p datetime)
+              "Z" "")))
+
+(defun ical:date-time-is-utc-p (datetime)
+  "Return non-nil if DATETIME is in UTC time."
+  (let ((offset (decoded-time-zone datetime)))
+    (and offset (= 0 offset))))
+
+(ical:define-type ical:date-time "DATE-TIME"
+   "Type for Date-Time values.
+
+When printed, a date-time is a string of digits like:
+  YYYYMMDDTHHMMSS
+where the 'T' is literal, and separates the date string from the
+time string.
+
+When read, a date-time is a decoded time, i.e. a list in the format
+(SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).  See
+`decode-time' for the specifics of the individual values."
+   '(satisfies ical:-decoded-date-time-p)
+  (seq ical:date ?T ical:time)
+  :reader ical:read-date-time
+  :printer ical:print-date-time
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.5")
+
+;;;; 3.3.6 Duration
+(rx-define ical:dur-second
+  (seq (group-n 19 (one-or-more digit)) ?S))
+
+(rx-define ical:dur-minute
+  (seq (group-n 18 (one-or-more digit)) ?M (zero-or-one ical:dur-second)))
+
+(rx-define ical:dur-hour
+  (seq (group-n 17 (one-or-more digit)) ?H (zero-or-one ical:dur-minute)))
+
+(rx-define ical:dur-day
+  (seq (group-n 16 (one-or-more digit)) ?D))
+
+(rx-define ical:dur-week
+  (seq (group-n 15 (one-or-more digit)) ?W))
+
+(rx-define ical:dur-time
+  (seq ?T (or ical:dur-hour ical:dur-minute ical:dur-second)))
+
+(rx-define ical:dur-date
+  (seq ical:dur-day (zero-or-one ical:dur-time)))
+
+(defun ical:read-dur-value (s)
+  "Read an `icalendar-dur-value' from a string S.
+S should be a match against rx `icalendar-dur-value'."
+  ;; TODO: this smells like a design flaw.  Silence the byte compiler for now.
+  (ignore s)
+  (let ((sign (if (equal (match-string 20) "-") -1 1)))
+    (if (match-string 15)
+        ;; dur-value specified in weeks, so just return an integer:
+        (* sign (string-to-number (match-string 15)))
+      ;; otherwise, make a time delta from the other units:
+      (let* ((days (match-string 16))
+             (ndays (* sign (if days (string-to-number days) 0)))
+             (hours (match-string 17))
+             (nhours (* sign (if hours (string-to-number hours) 0)))
+             (minutes (match-string 18))
+             (nminutes (* sign (if minutes (string-to-number minutes) 0)))
+             (seconds (match-string 19))
+             (nseconds (* sign (if seconds (string-to-number seconds) 0))))
+        (make-decoded-time :second nseconds :minute nminutes :hour nhours
+                           :day ndays)))))
+
+(defun ical:print-dur-value (dur)
+  "Serialize an `icalendar-dur-value' to a string."
+  (if (integerp dur)
+      ;; dur-value specified in weeks can only contain weeks:
+      (format "%sP%dW" (if (< dur 0) "-" "") (abs dur))
+    ;; otherwise, show all the time units present:
+    (let* ((days+- (or (decoded-time-day dur) 0))
+           (hours+- (or (decoded-time-hour dur) 0))
+           (minutes+- (or (decoded-time-minute dur) 0))
+           (seconds+- (or (decoded-time-second dur) 0))
+           ;; deal with the possibility of mixed positive and negative values
+           ;; in a time delta list:
+           (sum (+ seconds+-
+                   (* 60 minutes+-)
+                   (* 60 60 hours+-)
+                   (* 60 60 24 days+-)))
+           (abssum (abs sum))
+           (days (/ abssum (* 60 60 24)))
+           (sumnodays (mod abssum (* 60 60 24)))
+           (hours (/ sumnodays (* 60 60)))
+           (sumnohours (mod sumnodays (* 60 60)))
+           (minutes (/ sumnohours 60))
+           (seconds (mod sumnohours 60))
+           (sign (when (< sum 0) "-"))
+           (time-sep (unless (and (zerop hours) (zerop minutes) (zerop seconds))
+                       "T")))
+      (concat sign
+              "P"
+              (unless (zerop days) (format "%dD" days))
+              time-sep
+              (unless (zerop hours) (format "%dH" hours))
+              (unless (zerop minutes) (format "%dM" minutes))
+              (unless (zerop seconds) (format "%dS" seconds))))))
+
+(defun ical:-time-delta-p (val)
+  (and (listp val)
+       (length= val 9)
+       (let ((seconds (decoded-time-second val))
+             (minutes (decoded-time-minute val))
+             (hours (decoded-time-hour val))
+             (days (decoded-time-day val))) ; other values in list are ignored
+         (or (and (integerp seconds) (not (zerop seconds)))
+             (and (integerp minutes) (not (zerop minutes)))
+             (and (integerp hours) (not (zerop hours)))
+             (and (integerp days) (not (zerop days)))))))
+
+(ical:define-type ical:dur-value "DURATION"
+  "Type for Duration values.
+
+When printed, a duration is a string containing:
+  - possibly a +/- sign
+  - the letter 'P'
+  - one or more sequences of digits followed by a letter representing a unit
+    of time: 'W' for weeks, 'D' for days, etc.  Units smaller than a day are
+    separated from days by the letter 'T'.  If a duration is specified in weeks,
+    other units of time are not allowed.
+
+For example, a duration of 15 days, 5 hours, and 20 seconds would be printed:
+   P15DT5H0M20S
+and a duration of 7 weeks would be printed:
+   P7W
+
+When read, a duration is either an integer, in which case it
+represents a number of weeks, or a decoded time, in which case it
+must represent a time delta in the sense of `decoded-time-add'.
+Note that, in the time delta representation, units of time longer
+than a day are not supported and will be ignored if present.
+
+This type is named `icalendar-dur-value' rather than
+`icalendar-duration' for consistency with the text of RFC5545 and
+so that its name does not collide with the symbol for the
+`DURATION' property."
+  '(or integer (satisfies ical:-time-delta-p))
+  ;; Group 15: weeks
+  ;; Group 16: days
+  ;; Group 17: hours
+  ;; Group 18: minutes
+  ;; Group 19: seconds
+  ;; Group 20: sign
+  (seq
+   (group-n 20 (zero-or-one (or ?+ ?-)))
+   ?P
+   (or ical:dur-date ical:dur-time ical:dur-week))
+  :reader ical:read-dur-value
+  :printer ical:print-dur-value
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.6")
+
+
+;;;; 3.3.7 Float
+(ical:define-type ical:float "FLOAT"
+   "Type for Float values.
+
+When printed, possibly a sign + or -, followed by a sequence of digits,
+and possibly a decimal.  When read, an Elisp float value."
+   '(float * *)
+   (seq
+    (zero-or-one (or ?+ ?-))
+    (one-or-more digit)
+    (zero-or-one (seq ?. (one-or-more digit))))
+   :reader string-to-number
+   :printer number-to-string
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.7")
+
+;;;; 3.3.8 Integer
+(ical:define-type ical:integer "INTEGER"
+   "Type for Integer values.
+
+When printed, possibly a sign + or -, followed by a sequence of digits.
+When read, an Elisp integer value between -2147483648 and 2147483647."
+   '(integer -2147483648 2147483647)
+   (seq
+    (zero-or-one (or ?+ ?-))
+    (one-or-more digit))
+   :reader string-to-number
+   :printer number-to-string
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.8")
+
+;;;; 3.3.9 Period
+(defsubst ical:period-start (period)
+  "Return the `icalendar-date-time' which marks the start of PERIOD."
+  (car period))
+
+(defsubst ical:period--defined-end (period)
+  "Return the `icalendar-date-time' which marks the end of PERIOD, or nil."
+  (cadr period))
+
+(defsubst ical:period-dur-value (period)
+  "Return the `icalendar-dur-value' which gives the length of PERIOD, or nil."
+  (caddr period))
+
+(defun ical:period-end (period &optional vtimezone)
+  "Return the `icalendar-date-time' which marks the end of PERIOD.
+If the end is not explicitly specified, it will be computed from the
+period's start and duration.  VTIMEZONE, if given, should be the
+`icalendar-vtimezone' in which to compute the end time."
+  (require 'icalendar-utils) ; for date/time-add-duration; avoids circular import
+  (declare-function ical:date/time-add-duration "icalendar-utils")
+  (or (ical:period--defined-end period)
+      ;; compute end from duration and cache it:
+      (setf (cadr period)
+            (ical:date/time-add-duration
+             (ical:period-start period)
+             (ical:period-dur-value period)
+             vtimezone))))
+
+(defun ical:period-p (val)
+  (and (listp val)
+       (length= val 3)
+       (cl-typep (ical:period-start val) 'ical:date-time)
+       (cl-typep (ical:period-end val) '(or null ical:date-time))
+       (cl-typep (ical:period-dur-value val) '(or null ical:dur-value))))
+
+(cl-defun ical:make-period (start &key end duration)
+  "Make an `icalendar-period' value.
+
+START and END (if given) should be `icalendar-date-time' values.
+DURATION, if given, should be an `icalendar-dur-value'.  It is an error
+to pass both END and DURATION, or neither."
+  (when (and end duration)
+    (signal 'wrong-type-argument (list end duration)))
+  (unless (or end duration)
+    (signal 'wrong-type-argument (list end duration)))
+  (list start end duration))
+
+(defun ical:read-period (s)
+  "Read an `icalendar-period' from a string S.
+S should have been matched against rx `icalendar-period'."
+  ;; TODO: this smells like a design flaw.  Silence the byte compiler for now.
+  (ignore s)
+  (let ((start (ical:read-date-time (match-string 11)))
+        (end (when (match-string 12) (ical:read-date-time (match-string 12))))
+        (dur (when (match-string 13) (ical:read-dur-value (match-string 13)))))
+    (ical:make-period start :end end :duration dur)))
+
+(defun ical:print-period (per)
+  "Serialize an `icalendar-period' to a string."
+  (let ((start (ical:period-start per))
+        (end (ical:period-end per))
+        (dur (ical:period-dur-value per)))
+    (concat (ical:print-date-time start)
+            "/"
+            (if dur
+                (ical:print-dur-value dur)
+              (ical:print-date-time end)))))
+
+(ical:define-type ical:period "PERIOD"
+   "Type for Period values.
+
+A period of time is specified as a starting date-time together
+with either an explicit date-time as its end, or a duration which
+gives its length and implicitly marks its end.
+
+When printed, the starting date-time is separated from the end or
+duration by a / character.
+
+When read, a period is represented as a list (START END DUR), where
+START is an `icalendar-date-time', END is either an
+`icalendar-date-time' or nil, and DUR is either an `icalendar-dur-value'
+or nil.  See the functions `icalendar-make-period',
+`icalendar-period-start', `icalendar-period-end', and
+`icalendar-period-dur-value' to work with period values."
+  '(satisfies ical:period-p)
+  (seq (group-n 11 ical:date-time)
+       "/"
+       (or (group-n 12 ical:date-time)
+           (group-n 13 ical:dur-value)))
+  :reader ical:read-period
+  :printer ical:print-period
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.9")
+
+;;;; 3.3.10 Recurrence rules:
+(rx-define ical:freq
+   (or "SECONDLY" "MINUTELY" "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "YEARLY"))
+
+(rx-define ical:weekday
+   (or "SU" "MO" "TU" "WE" "TH" "FR" "SA"))
+
+(rx-define ical:ordwk
+  (** 1 2 digit)) ; 1 to 53
+
+(rx-define ical:weekdaynum
+  ;; Group 19: Week num, if present
+  ;; Group 20: week day abbreviation
+   (seq (zero-or-one
+         (group-n 19 (seq (zero-or-one (or ?+ ?-))
+                          ical:ordwk)))
+        (group-n 20 ical:weekday)))
+
+(rx-define ical:weeknum
+  (seq (zero-or-one (or ?+ ?-))
+       ical:ordwk))
+
+(rx-define ical:monthdaynum
+  (seq (zero-or-one (or ?+ ?-))
+       (** 1 2 digit))) ; 1 to 31
+
+(rx-define ical:monthnum
+  (seq (zero-or-one (or ?+ ?-))
+       (** 1 2 digit))) ; 1 to 12
+
+(rx-define ical:yeardaynum
+  (seq (zero-or-one (or ?+ ?-))
+       (** 1 3 digit))) ; 1 to 366
+
+(defconst ical:weekday-numbers
+  '(("SU" . 0)
+    ("MO" . 1)
+    ("TU" . 2)
+    ("WE" . 3)
+    ("TH" . 4)
+    ("FR" . 5)
+    ("SA" . 6))
+  "Alist mapping two-letter weekday abbreviations to numbers 0 to 6.
+Weekday abbreviations in recurrence rule parts are translated to
+and from numbers for compatibility with calendar-* and
+decoded-time-* functions.")
+
+(defun ical:read-weekdaynum (s)
+  "Read a weekday abbreviation to a number.
+If the abbreviation is preceded by an offset, read a dotted
+pair (WEEKDAY . OFFSET).  Thus \"SU\" becomes 0, \"-1SU\"
+becomes (0 . -1), etc.  S should have been matched against
+`icalendar-weekdaynum'."
+  ;; TODO: this smells like a design flaw.  Silence the byte compiler for now.
+  (ignore s)
+  (let ((dayno (cdr (assoc (match-string 20) ical:weekday-numbers)))
+        (weekno (match-string 19)))
+    (if weekno
+        (cons dayno (string-to-number weekno))
+      dayno)))
+
+(defun ical:print-weekdaynum (val)
+  "Serialize a number or dotted pair VAL to a string.
+The result is in the format required for a BYDAY recurrence rule clause.
+See `icalendar-read-weekdaynum' for the format of VAL."
+  (if (consp val)
+      (let* ((dayno (car val))
+             (day (car (rassq dayno ical:weekday-numbers)))
+             (offset (cdr val)))
+        (concat (number-to-string offset) day))
+    ;; number alone just stands for a day:
+    (car (rassq val ical:weekday-numbers))))
+
+(defun ical:read-recur-rule-part (s)
+  "Read an `icalendar-recur-rule-part' from string S.
+S should have been matched against `icalendar-recur-rule-part'.
+The return value is a list (KEYWORD VALUE), where VALUE may
+itself be a list, depending on the values allowed by KEYWORD."
+  ;; TODO: this smells like a design flaw.  Silence the byte compiler for now.
+  (ignore s)
+  (let ((keyword (intern (upcase (match-string 11))))
+        (values (match-string 12)))
+    (list keyword
+      (cl-case keyword
+        (FREQ (intern (upcase values)))
+        (UNTIL (if (length> values 8)
+                   (ical:read-date-time values)
+                 (ical:read-date values)))
+        ((COUNT INTERVAL)
+         (string-to-number values))
+        ((BYSECOND BYMINUTE BYHOUR BYMONTHDAY BYYEARDAY BYWEEKNO BYMONTH BYSETPOS)
+         (ical:read-list-with #'string-to-number values nil ","))
+        (BYDAY
+         (ical:read-list-with #'ical:read-weekdaynum values
+                              (rx ical:weekdaynum) ","))
+        (WKST (cdr (assoc values ical:weekday-numbers)))))))
+
+(defun ical:print-recur-rule-part (part)
+  "Serialize recur rule part PART to a string."
+  (let ((keyword (car part))
+        (values (cadr part))
+        values-str)
+    (cl-case keyword
+      (FREQ (setq values-str (symbol-name values)))
+      (UNTIL (setq values-str (cl-typecase values
+                                (ical:date-time (ical:print-date-time values))
+                                (ical:date (ical:print-date values)))))
+      ((COUNT INTERVAL)
+       (setq values-str (number-to-string values)))
+      ((BYSECOND BYMINUTE BYHOUR BYMONTHDAY BYYEARDAY BYWEEKNO BYMONTH BYSETPOS)
+       (setq values-str (string-join (mapcar #'number-to-string values)
+                                     ",")))
+      (BYDAY
+       (setq values-str (string-join (mapcar #'ical:print-weekdaynum values)
+                                     ",")))
+      (WKST (setq values-str (car (rassq values ical:weekday-numbers)))))
+
+    (concat (symbol-name keyword) "=" values-str)))
+
+(rx-define ical:recur-rule-part
+  ;; Group 11: keyword
+  ;; Group 12: value(s)
+  (or (seq (group-n 11 "FREQ") "=" (group-n 12 ical:freq))
+      (seq (group-n 11 "UNTIL") "=" (group-n 12 (or ical:date-time ical:date)))
+      (seq (group-n 11 "COUNT") "=" (group-n 12 (one-or-more digit)))
+      (seq (group-n 11 "INTERVAL") "=" (group-n 12 (one-or-more digit)))
+      (seq (group-n 11 "BYSECOND") "=" (group-n 12 ; 0 to 60
+                                         (ical:comma-list (** 1 2 digit))))
+      (seq (group-n 11 "BYMINUTE") "=" (group-n 12 ; 0 to 59
+                                         (ical:comma-list (** 1 2 digit))))
+      (seq (group-n 11 "BYHOUR") "=" (group-n 12 ; 0 to 23
+                                       (ical:comma-list (** 1 2 digit)))) ; 0 to 23
+      (seq (group-n 11 "BYDAY") "=" (group-n 12 ; weeknum? daynum, e.g. SU or 34SU
+                                      (ical:comma-list ical:weekdaynum)))
+      (seq (group-n 11 "BYMONTHDAY") "=" (group-n 12
+                                           (ical:comma-list ical:monthdaynum)))
+      (seq (group-n 11 "BYYEARDAY") "=" (group-n 12
+                                          (ical:comma-list ical:yeardaynum)))
+      (seq (group-n 11 "BYWEEKNO") "=" (group-n 12 (ical:comma-list ical:weeknum)))
+      (seq (group-n 11 "BYMONTH") "=" (group-n 12 (ical:comma-list ical:monthnum)))
+      (seq (group-n 11 "BYSETPOS") "=" (group-n 12
+                                         (ical:comma-list ical:yeardaynum)))
+      (seq (group-n 11 "WKST") "=" (group-n 12 ical:weekday))))
+
+(defun ical:read-recur (s)
+  "Read a recurrence rule value from string S.
+S should be a match against rx `icalendar-recur'."
+  ;; TODO: let's switch to keywords and a plist, so we can more easily
+  ;; write these clauses also in diary sexp entries without so many parens
+  (ical:read-list-with #'ical:read-recur-rule-part s (rx ical:recur-rule-part) ";"))
+
+(defun ical:print-recur (val)
+  "Serialize a recurrence rule value VAL to a string."
+  ;; RFC5545 sec. 3.3.10: "to ensure backward compatibility with
+  ;; applications that pre-date this revision of iCalendar the
+  ;; FREQ rule part MUST be the first rule part specified in a
+  ;; RECUR value."
+  (string-join
+   (cons
+    (ical:print-recur-rule-part (assq 'FREQ val))
+    (mapcar #'ical:print-recur-rule-part
+            (seq-filter (lambda (part) (not (eq 'FREQ (car part))))
+                        val)))
+   ";"))
+
+(defconst ical:-recur-value-types
+  ;; `list-of' is not a cl-type specifier, just a symbol here; it is
+  ;; handled specially when checking types in `ical:recur-value-p':
+  '(FREQ (member YEARLY MONTHLY WEEKLY DAILY HOURLY MINUTELY SECONDLY)
+    UNTIL (or ical:date-time ical:date)
+    COUNT (integer 1 *)
+    INTERVAL (integer 1 *)
+    BYSECOND (list-of (integer 0 60))
+    BYMINUTE (list-of (integer 0 59))
+    BYHOUR (list-of (integer 0 23))
+    BYDAY (list-of (or (integer 0 6) (satisfies ical:dayno-offset-p)))
+    BYMONTHDAY (list-of (or (integer -31 -1) (integer 1 31)))
+    BYYEARDAY (list-of (or (integer -366 -1) (integer 1 366)))
+    BYWEEKNO (list-of (or (integer -53 -1) (integer 1 53)))
+    BYMONTH (list-of (integer 1 12)) ; unlike the others, months cannot be negative
+    BYSETPOS (list-of (or (integer -366 -1) (integer 1 366)))
+    WKST (integer 0 6))
+  "Plist mapping `icalendar-recur' keywords to type specifiers.")
+
+(defun ical:dayno-offset-p (val)
+  "Return non-nil if VAL is a pair (DAYNO . OFFSET).
+DAYNO must be in [0..6] and OFFSET in [-53..53], excluding 0."
+  (and (consp val)
+       (cl-typep (car val) '(integer 0 6))
+       (cl-typep (cdr val) '(or (integer -53 -1) (integer 1 53)))))
+
+(defun ical:recur-value-p (vals)
+  "Return non-nil if VALS is an iCalendar recurrence rule value."
+  (and (listp vals)
+       ;; FREQ is always required:
+       (assq 'FREQ vals)
+       ;; COUNT and UNTIL are mutually exclusive if present:
+       (not (and (assq 'COUNT vals) (assq 'UNTIL vals)))
+       ;; If BYSETPOS is present, another BYXXX clause must be too:
+       (or (not (assq 'BYSETPOS vals))
+           (assq 'BYMONTH vals)
+           (assq 'BYWEEKNO vals)
+           (assq 'BYYEARDAY vals)
+           (assq 'BYMONTHDAY vals)
+           (assq 'BYDAY vals)
+           (assq 'BYHOUR vals)
+           (assq 'BYMINUTE vals)
+           (assq 'BYSECOND vals))
+       (let ((freq (ical:recur-freq vals))
+             (byday (ical:recur-by* 'BYDAY vals))
+             (byweekno (ical:recur-by* 'BYWEEKNO vals))
+             (bymonthday (ical:recur-by* 'BYMONTHDAY vals))
+             (byyearday (ical:recur-by* 'BYYEARDAY vals)))
+         (and
+          ;; "The BYDAY rule part MUST NOT be specified with a numeric
+          ;; value when the FREQ rule part is not set to MONTHLY or
+          ;; YEARLY."
+          (or (not (consp (car byday)))
+              (memq freq '(MONTHLY YEARLY)))
+          ;; "The BYDAY rule part MUST NOT be specified with a numeric
+          ;; value with the FREQ rule part set to YEARLY when the
+          ;; BYWEEKNO rule part is specified." This also covers:
+          ;; "[The BYWEEKNO] rule part MUST NOT be used when the FREQ
+          ;; rule part is set to anything other than YEARLY."
+          (or (not byweekno)
+              (and (eq freq 'YEARLY)
+                   (not (consp (car byday)))))
+          ;; "The BYMONTHDAY rule part MUST NOT be specified when the
+          ;; FREQ rule part is set to WEEKLY."
+          (not (and bymonthday (eq freq 'WEEKLY)))
+          ;; "The BYYEARDAY rule part MUST NOT be specified when the
+          ;; FREQ rule part is set to DAILY, WEEKLY, or MONTHLY."
+          (not (and byyearday (memq freq '(DAILY WEEKLY MONTHLY))))))
+       ;; check types of all rule parts:
+       (seq-every-p
+        (lambda (kv)
+          (when (consp kv)
+            (let* ((keyword (car kv))
+                   (val (cadr kv))
+                   (type (plist-get ical:-recur-value-types keyword)))
+              (and keyword val type
+                   (if (and (consp type)
+                            (eq (car type) 'list-of))
+                       (ical:list-of-p val (cadr type))
+                     (cl-typep val type))))))
+         vals)))
+
+(ical:define-type ical:recur "RECUR"
+  "Type for Recurrence Rule values.
+
+When printed, a recurrence rule value looks like
+  KEY1=VAL1;KEY2=VAL2;...
+where the VALs may themselves be lists or have other syntactic
+structure; see RFC5545 sec. 3.3.10 for all the details.
+
+The KEYs and their associated value types when read are as follows.
+The first is required:
+  '(FREQ (member YEARLY MONTHLY WEEKLY DAILY HOURLY MINUTELY SECONDLY)
+These two are mutually exclusive; at most one may appear:
+    UNTIL (or icalendar-date-time icalendar-date)
+    COUNT (integer 1 *)
+All others are optional:
+    INTERVAL (integer 1 *)
+    BYSECOND (list-of (integer 0 60))
+    BYMINUTE (list-of (integer 0 59))
+    BYHOUR (list-of (integer 0 23))
+    BYDAY (list-of (or (integer 0 6) ; day of week
+                       (pair (integer 0 6)  ; (day of week . offset)
+                             (integer -53 53))) ; except 0
+    BYMONTHDAY (list-of (integer -31 31))  ; except 0
+    BYYEARDAY (list-of (integer -366 366)) ; except 0
+    BYWEEKNO (list-of (integer -53 53))    ; except 0
+    BYMONTH (list-of (integer 1 12))       ; months cannot be negative
+    BYSETPOS (list-of (integer -366 366))  ; except 0
+    WKST (integer 0 6))
+
+When read, these KEYs and their associated VALs are gathered into
+an alist.
+
+In general, the VALs consist of integers or lists of integers.
+Abbreviations for weekday names are translated into integers
+0 (=Sunday) through 6 (=Saturday), for compatibility with
+calendar.el and decoded-time-* functions.
+
+Some examples:
+
+1) Printed: FREQ=DAILY;COUNT=10;INTERVAL=2
+   Meaning: 10 occurrences that occur every other day
+   Read: ((FREQ DAILY)
+          (COUNT 10)
+          (INTERVAL 2))
+
+2) Printed: FREQ=YEARLY;UNTIL=20000131T140000Z;BYMONTH=1;BYDAY=SU,MO,TU,WE,TH,FR,SA
+   Meaning: Every day in January of every year until 2000/01/31 at 14:00 UTC
+   Read: ((FREQ YEARLY)
+          (UNTIL (0 0 14 31 1 2000 1 -1 0))
+          (BYMONTH (1))
+          (BYDAY (0 1 2 3 4 5 6)))
+
+3) Printed: FREQ=MONTHLY;BYDAY=MO,TU,WE,TH,FR;BYSETPOS=-2
+   Meaning: Every month on the second-to-last weekday of the month
+   Read: ((FREQ MONTHLY)
+          (BYDAY (1 2 3 4 5))
+          (BYSETPOS (-2)))
+
+Notice that singleton values are still wrapped in a list when the
+KEY accepts a list of values, but not when the KEY always has a
+single (e.g. integer) value."
+  '(satisfies ical:recur-value-p)
+  (ical:semicolon-list ical:recur-rule-part)
+  :reader ical:read-recur
+  :printer ical:print-recur
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.10")
+
+(defun ical:recur-freq (recur-value)
+  "Return the frequency in RECUR-VALUE."
+  (car (alist-get 'FREQ recur-value)))
+
+(defun ical:recur-interval-size (recur-value)
+  "Return the interval size in RECUR-VALUE, or the default of 1."
+  (or (car (alist-get 'INTERVAL recur-value)) 1))
+
+(defun ical:recur-until (recur-value)
+  "Return the UNTIL date(-time) in RECUR-VALUE."
+  (car (alist-get 'UNTIL recur-value)))
+
+(defun ical:recur-count (recur-value)
+  "Return the COUNT in RECUR-VALUE."
+  (car (alist-get 'COUNT recur-value)))
+
+(defun ical:recur-weekstart (recur-value)
+  "Return the weekday which starts the work week in RECUR-VALUE.
+If no starting weekday is specified in RECUR-VALUE, returns the default,
+1 (= Monday)."
+  (or (car (alist-get 'WKST recur-value)) 1))
+
+(defun ical:recur-by* (byunit recur-value)
+  "Return the values in the BYUNIT clause in RECUR-VALUE.
+BYUNIT should be a symbol: \\='BYMONTH, \\='BYDAY, etc.
+See `icalendar-recur' for all the possible BYUNIT values."
+  (car (alist-get byunit recur-value)))
+
+;;;; 3.3.11 Text
+(rx-define ical:escaped-char
+   (seq ?\\ (or ?\\ ?\; ?, ?N ?n)))
+
+(rx-define ical:text-safe-char
+  ;; "Any character except CONTROLs not needed by the current character
+  ;; set, DQUOTE, ";", ":", "\", "," "
+  (any #x09 #x20 #x21 ; htab, space, and "!"
+       (#x23 . #x2B) (#x2D . #x39) ; "#".."9" skipping #x2C=","
+       (#x3C . #x5B) (#x5D . #x7E) ; "<".."~" skipping #x5C="\"
+       nonascii))
+
+(defun ical:text-region-p (val)
+  "Return t if VAL represents a region of text."
+  (and (listp val)
+       (markerp (car val))
+       (not (null (marker-buffer (car val))))
+       (markerp (cdr val))))
+
+(defun ical:make-text-region (&optional buffer begin end)
+  "Return an object that represents a region of text.
+The region is taken from BUFFER between BEGIN and END.  BUFFER defaults
+to the current buffer, and BEGIN and END default to point and mark in
+BUFFER."
+  (let ((buf (or buffer (current-buffer)))
+        (b (make-marker))
+        (e (make-marker)))
+    (with-current-buffer buf
+      (set-marker b (or begin (region-beginning)) buf)
+      (set-marker e (or end (region-end)))
+      (cons b e))))
+
+(defsubst ical:text-region-begin (r)
+  "Return the marker at the beginning of the text region R."
+  (car r))
+
+(defsubst ical:text-region-end (r)
+  "Return the marker at the end of the text region R."
+  (cdr r))
+
+(defun ical:unescape-text-in-region (begin end)
+ "Unescape the text between BEGIN and END.
+Unescaping replaces literal '\\n' and '\\N' with newline, and removes
+backslashes that escape commas, semicolons, and backslashes."
+ (with-restriction begin end
+   (save-excursion
+    (replace-string-in-region "\\N" "\n" (point-min) (point-max))
+    (replace-string-in-region "\\n" "\n" (point-min) (point-max))
+    (replace-string-in-region "\\," "," (point-min) (point-max))
+    (replace-string-in-region "\\;" ";" (point-min) (point-max)))
+    (replace-string-in-region (concat "\\" "\\") "\\" (point-min) (point-max))))
+
+(defun ical:unescape-text-string (s)
+ "Unescape the text in string S.
+Unescaping replaces literal '\\n' and '\\N' with newline, and removes
+backslashes that escape commas, semicolons, and backslashes."
+  (with-temp-buffer
+    (insert s)
+    (ical:unescape-text-in-region (point-min) (point-max))
+    (buffer-string)))
+
+(defun ical:escape-text-in-region (begin end)
+  "Escape the text between BEGIN and END in the current buffer.
+Escaping replaces newlines with literal '\\n', and escapes commas,
+semicolons and backslashes with a backslash."
+ (with-restriction begin end
+  (save-excursion
+    ;; replace backslashes first, so the ones introduced when
+    ;; escaping other characters don't end up double-escaped:
+    (replace-string-in-region "\\" (concat "\\" "\\") (point-min) (point-max))
+    (replace-string-in-region "\n" "\\n" (point-min) (point-max))
+    (replace-string-in-region "," "\\," (point-min) (point-max))
+    (replace-string-in-region ";" "\\;" (point-min) (point-max)))))
+
+(defun ical:escape-text-string (s)
+  "Escape the text in string S.
+Escaping replaces newlines with literal '\\n', and escapes commas,
+semicolons and backslashes with a backslash."
+  (with-temp-buffer
+    (insert s)
+    (ical:escape-text-in-region (point-min) (point-max))
+    (buffer-string)))
+
+(defun ical:read-text (s)
+  "Read an `icalendar-text' value from a string S.
+S should be a match against rx `icalendar-text'."
+  (ical:unescape-text-string s))
+
+(defun ical:print-text (val)
+  "Serialize an iCalendar text value.
+VAL may be a string or text region (see `icalendar-make-text-region').
+The text will be escaped before printing.  If VAL is a region, the text
+it contains will not be modified; it is copied before escaping."
+  (if (stringp val)
+      (ical:escape-text-string val)
+    ;; val is a region, so copy and escape its contents:
+    (let* ((beg (ical:text-region-begin val))
+           (buf (marker-buffer beg))
+           (end (ical:text-region-end val)))
+      (with-temp-buffer
+        (insert-buffer-substring buf (marker-position beg) (marker-position end))
+        (ical:escape-text-in-region (point-min) (point-max))
+        (buffer-string)))))
+
+(defun ical:text-to-string (node)
+  "Return the value of an `icalendar-text' NODE as a string.
+The returned string is *not* escaped.  For that, see `icalendar-print-text'."
+  (ical:with-node-value node nil
+    (if (stringp value) value
+      ;; Otherwise the value is a text region:
+      (let* ((beg (ical:text-region-begin value))
+             (buf (marker-buffer beg))
+             (end (ical:text-region-end value)))
+        (with-current-buffer buf
+          (buffer-substring (marker-position beg) (marker-position end)))))))
+
+;; TODO: would it be useful to add a third representation, namely a
+;; function or thunk?  So that e.g. Org can pre-process its own syntax
+;; and return a plain text string to use in the description?
+(ical:define-type ical:text "TEXT"
+   "Type for Text values.
+
+Text values can be represented in Elisp in two ways: as strings,
+or as buffer regions.  For values which aren't expected to change,
+such as property values in a text/calendar email attachment, use
+strings.  For values which are user-editable and might change
+between parsing and serializing to iCalendar format, use a
+region.  In that case, a text value contains two markers BEGIN and
+END which mark the bounds of the region.  See
+`icalendar-make-text-region' to create such values, and
+`icalendar-text-region-begin' and `icalendar-text-region-end' to
+access the markers.
+
+Certain characters in text values are required to be escaped by
+the iCalendar standard.  These characters should NOT be
+pre-escaped when inserting them into the parse tree.  Instead,
+`icalendar-print-text' takes care of escaping text values, and
+`icalendar-read-text' takes care of unescaping them, when parsing and
+printing iCalendar data."
+  '(or string (satisfies ical:text-region-p))
+  (zero-or-more (or ical:text-safe-char ?: ?\" ical:escaped-char))
+  :reader ical:read-text
+  :printer ical:print-text
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.11")
+
+;; 3.3.12 Time - Defined above
+
+;;;; 3.3.13 URI
+;; see https://www.rfc-editor.org/rfc/rfc3986#section-3
+(rx-define ical:uri-with-scheme
+  ;; Group 11: URI scheme; see icalendar-uri-schemes.el
+  ;; Group 12: rest of URI after ":"
+  ;; This regex mostly just scans for all characters allowed by RFC3986,
+  ;; except we make an effort to parse the scheme, because otherwise the
+  ;; regex is either too permissive (ical:binary, in particular, matches
+  ;; a subset of the characters allowed in a URI) or too complicated to
+  ;; be useful.
+  ;; TODO: use url-parse.el to parse to struct?
+  (seq (group-n 11 (any "a-zA-Z") (zero-or-more (any ?- ?+ ?. "A-Za-z0-9")))
+       ":"
+       (group-n 12
+         (one-or-more
+          (any "A-Za-z0-9" ?- ?. ?_ ?~             ; unreserved chars
+               ?: ?/ ?? ?# ?\[ ?\] ?@              ; gen-delims
+               ?! ?$ ?& ?' ?\( ?\) ?* ?+ ?, ?\; ?= ; sub-delims
+               ?%)))))                             ; for %-encoding
+
+(ical:define-type ical:uri "URI"
+   "Type for URI values.
+
+The parsed and printed representations are the same: a URI string."
+   '(satisfies ical:match-uri-value)
+   ical:uri-with-scheme
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.13")
+
+;;;; 3.3.3 Calendar User Address
+(ical:define-type ical:cal-address "CAL-ADDRESS"
+   "Type for Calendar User Address values.
+
+The parsed and printed representations are the same: a URI string.
+Typically, this should be a \"mailto:\" URI.
+
+RFC5545 says: \"*When used to address an Internet email transport
+  address* for a calendar user, the value MUST be a mailto URI,
+  as defined by [RFC2368]\"
+
+Since it is unclear whether there are Calendar User Address values
+which are not used to address email, this type does not enforce the use
+of the mailto: scheme, but be prepared for problems if you create
+values of this type with any other scheme."
+   '(and string (satisfies ical:match-cal-address-value))
+   ical:uri-with-scheme
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.3")
+
+;;;; 3.3.14 UTC Offset
+(defun ical:read-utc-offset (s)
+  "Read a UTC offset from a string.
+S should be a match against rx `icalendar-utc-offset'"
+  (let ((sign (if (equal (substring s 0 1) "-") -1 1))
+        (nhours (string-to-number (substring s 1 3)))
+        (nminutes (string-to-number (substring s 3 5)))
+        (nseconds (if (length= s 7)
+                      (string-to-number (substring s 5 7))
+                    0)))
+    (* sign (+ nseconds (* 60 nminutes) (* 60 60 nhours)))))
+
+(defun ical:print-utc-offset (utcoff)
+  "Serialize a UTC offset to a string."
+  (let* ((sign (if (< utcoff 0) "-" "+"))
+         (absoff (abs utcoff))
+         (nhours (/ absoff (* 60 60)))
+         (no-hours (mod absoff (* 60 60)))
+         (nminutes (/ no-hours 60))
+         (nseconds (mod no-hours 60)))
+    (if (zerop nseconds)
+        (format "%s%02d%02d" sign nhours nminutes)
+      (format "%s%02d%02d%02d" sign nhours nminutes nseconds))))
+
+(ical:define-type ical:utc-offset "UTC-OFFSET"
+  "Type for UTC Offset values.
+
+When printed, a sign followed by a string of digits, like +HHMM
+or -HHMMSS.  When read, an integer representing the number of
+seconds offset from UTC.  This representation is for compatibility
+with `decode-time' and related functions."
+  '(integer -999999 999999)
+  (seq (or ?+ ?-) ; + is not optional for positive values!
+       (= 4 digit) ; HHMM
+       (zero-or-one (= 2 digit))) ; SS
+  :reader ical:read-utc-offset
+  :printer ical:print-utc-offset
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.3.14")
+
+
+;;; Section 3.2: Property Parameters
+
+(defvar ical:param-types nil ;; populated by ical:define-param
+  "Alist mapping printed parameter names to type symbols.")
+
+(defun ical:maybe-quote-param-value (s &optional always)
+  "Add quotes around param value string S if required.
+If ALWAYS is non-nil, add quotes to S regardless of its contents."
+  (if (or always
+          (not (string-match (rx ical:paramtext) s))
+          (< (match-end 0) (length s)))
+      (concat "\"" s "\"")
+    s))
+
+(defun ical:read-param-value (type s)
+  "Read a value for a parameter of type TYPE from a string S.
+S should have already been matched against the regex for TYPE and
+the match data should be available to this function.  Returns a
+syntax node of type TYPE containing the read value.
+
+If TYPE accepts a list of values, S will be split on the list
+separator for TYPE and read individually."
+  (let* ((value-type (get type 'ical:value-type)) ; if nil, value is just a string
+         (value-regex (when (get type 'ical:value-rx)
+                         (rx-to-string (get type 'ical:value-rx))))
+         (list-sep (get type 'ical:list-sep))
+         (substitute-val (get type 'ical:substitute-value))
+         (unrecognized-val (match-string 5)) ; see :unrecognized in define-param
+         (raw-val (if unrecognized-val substitute-val s))
+         (one-val-reader (if (ical:value-type-symbol-p value-type)
+                             (lambda (s) (ical:read-value-node value-type s))
+                           #'identity)) ; value is just a string
+         ;; values may be quoted even if :quoted does not require it,
+         ;; so they need to be stripped of quotes. read-list-with does
+         ;; this by default; in the single value case, use string-trim
+         (read-val (if list-sep
+                       (ical:read-list-with one-val-reader raw-val
+                                            value-regex list-sep)
+                     (funcall one-val-reader
+                              (string-trim raw-val "\"" "\"")))))
+    (ical:make-ast-node type
+                        (list :value read-val
+                              :original-value unrecognized-val))))
+
+(defun ical:parse-param-value (type limit)
+  "Parse the value for a parameter of type TYPE from point up to LIMIT.
+TYPE should be a type symbol for an iCalendar parameter type.
+This function expects point to be at the start of the value
+string, after the parameter name and the equals sign.  Returns a
+syntax node representing the parameter."
+  (let ((full-value-regex (rx-to-string (get type 'ical:full-value-rx))))
+    ;; By far the most common invalid data seem to be text values that
+    ;; contain unescaped characters (e.g. commas in addresses).  These
+    ;; are harmless as long as the parameter accepts arbitrary text and
+    ;; does not expect a list of values.  The only such parameter
+    ;; defined in RFC5545 is `ical:cnparam', so we treat this as a
+    ;; special case and loosen the official regexp to accept anything up
+    ;; to the start of the next param or property value:
+    (when (and (eq type 'ical:cnparam)
+               (not ical:parse-strictly))
+      (setq full-value-regex
+            (rx (group-n 2 (or ical:quoted-string
+                               (zero-or-more (not (any ?: ?\;))))))))
+
+    (unless (re-search-forward full-value-regex limit t)
+      (ical:signal-parse-error
+       (format "Unable to parse `%s' value between %d and %d"
+               type (point) limit)))
+    (when (match-string 3)
+      (ical:signal-parse-error
+       (format "Invalid value for `%s' parameter: %s" type (match-string 3))))
+
+    (let ((value-begin (match-beginning 2))
+          (value-end (match-end 2))
+          (node (ical:read-param-value type (match-string 2))))
+      (ical:ast-node-meta-set node :buffer (current-buffer))
+      ;; :begin must be set by parse-params
+      (ical:ast-node-meta-set node :value-begin value-begin)
+      (ical:ast-node-meta-set node :value-end value-end)
+      (ical:ast-node-meta-set node :end value-end)
+
+      node)))
+
+(defun ical:parse-params (limit)
+  "Parse the parameter string of the current property, up to LIMIT.
+Point should be at the \";\" at the start of the first parameter.
+Returns a list of parameters, which may be nil if none are present.
+After parsing, point is at the end of the parameter string and the
+start of the property value string."
+  (let (params param-node)
+    (rx-let ((ical:param-start (seq ";" (group-n 1 ical:param-name) "=")))
+      (while (re-search-forward (rx ical:param-start) limit t)
+        (when-let* ((begin (match-beginning 1))
+                    (param-name (match-string 1))
+                    (param-type (alist-get (upcase param-name)
+                                           ical:param-types
+                                           'ical:otherparam
+                                            nil #'equal)))
+          (condition-case err
+              (setq param-node (ical:parse-param-value param-type limit))
+            (ical:parse-error
+             (ical:handle-parse-error err (format "Skipping bad %s parameter"
+                                                  param-name))
+             (setq param-node nil)))
+          (when param-node
+            (ical:ast-node-meta-set param-node :begin begin)
+            ;; store the original param name if we didn't recognize it:
+            (when (eq param-type 'ical:otherparam)
+              (ical:ast-node-meta-set param-node :original-name param-name))
+            (push param-node params))))
+    (nreverse params))))
+
+(defun ical:print-param-node (node)
+  "Serialize a parameter syntax node NODE to a string.
+NODE should be a syntax node whose type is an iCalendar
+parameter type."
+  (let* ((param-type (ical:ast-node-type node))
+         (param-name (car (rassq param-type ical:param-types)))
+         (name-str (or param-name
+                       ;; set by parse-params for unrecognized params:
+                       (ical:ast-node-meta-get :original-name node))))
+
+    (unless (and name-str (stringp name-str) (not (equal name-str "")))
+      (ical:signal-print-error "No printable parameter name" :node node))
+
+    (let* ((list-sep (get param-type 'ical:list-sep))
+           (val/s (ical:ast-node-value node))
+           (vals (if (and list-sep (listp val/s))
+                     val/s
+                   (list val/s)))
+           ;; any ical:print-error here propagates:
+           (printed (mapcar #'ical:default-value-printer vals))
+           ;; add quotes to each value as needed, even if :quoted
+           ;; does not require it:
+           (must-quote (get param-type 'ical:is-quoted))
+           (quoted (mapcar
+                    (lambda (v) (ical:maybe-quote-param-value v must-quote))
+                    printed))
+           (val-str (or (ical:ast-node-meta-get :original-value node)
+                        (string-join quoted list-sep)
+                        quoted)))
+
+      (unless (and (stringp val-str) (not (equal val-str "")))
+        (ical:signal-print-error "Unable to print parameter value" :node node))
+
+      (format ";%s=%s" name-str val-str))))
+
+(defun ical:print-params (param-nodes)
+  "Print the property parameter nodes in PARAM-NODES.
+Returns the printed parameter list as a string."
+  (let (param-strs)
+    (dolist (node param-nodes)
+      (condition-case err
+          (push (ical:print-param-node node) param-strs)
+        (ical:print-error
+         (ical:handle-print-error err))))
+    (apply #'concat (nreverse param-strs))))
+
+;; Parameter definitions in RFC5545:
+
+(ical:define-param ical:altrepparam "ALTREP"
+  "Alternate text representation (URI)"
+  ical:uri
+  :quoted t
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.1")
+
+(ical:define-param ical:cnparam "CN"
+  "Common Name"
+  ical:param-value
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.2")
+
+(ical:define-param ical:cutypeparam "CUTYPE"
+  "Calendar User Type"
+  (or "INDIVIDUAL"
+      "GROUP"
+      "RESOURCE"
+      "ROOM"
+      "UNKNOWN"
+      (group-n 5
+        (or ical:x-name ical:iana-token)))
+  :default "INDIVIDUAL"
+  ;; "Applications MUST treat x-name and iana-token values they
+  ;; don't recognize the same way as they would the UNKNOWN
+  ;; value":
+  :unrecognized "UNKNOWN"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.3")
+
+(ical:define-param ical:delfromparam "DELEGATED-FROM"
+  "Delegators.
+
+This is a comma-separated list of quoted `icalendar-cal-address' URIs,
+typically specified on the `icalendar-attendee' property.  The users in
+this list have delegated their participation to the user which is
+the value of the property."
+  ical:cal-address
+  :quoted t
+  :list-sep ","
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.4")
+
+(ical:define-param ical:deltoparam "DELEGATED-TO"
+  "Delegatees.
+
+This is a comma-separated list of quoted `icalendar-cal-address' URIs,
+typically specified on the `icalendar-attendee' property.  The users in
+this list have been delegated to participate by the user which is
+the value of the property."
+  ical:cal-address
+  :quoted t
+  :list-sep ","
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.5")
+
+(ical:define-param ical:dirparam "DIR"
+  "Directory Entry Reference.
+
+This parameter may be specified on properties with a
+`icalendar-cal-address' value type.  It is a quoted URI which specifies
+a reference to a directory entry associated with the calendar
+user which is the value of the property."
+   ical:uri
+   :quoted t
+   :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.6")
+
+(ical:define-param ical:encodingparam "ENCODING"
+  "Inline Encoding, either \"8BIT\" (text, default) or \"BASE64\" (binary).
+
+If \"BASE64\", the property value is base64-encoded binary data.
+This parameter must be specified if the `icalendar-valuetypeparam'
+is \"BINARY\"."
+  (or "8BIT" "BASE64")
+  :default "8BIT"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.7")
+
+(rx-define ical:mimetype
+  (seq ical:mimetype-regname "/" ical:mimetype-regname))
+
+;; from https://www.rfc-editor.org/rfc/rfc4288#section-4.2:
+(rx-define ical:mimetype-regname
+  (** 1 127 (any "A-Za-z0-9" ?! ?# ?$ ?& ?. ?+ ?- ?^ ?_)))
+
+(ical:define-param ical:fmttypeparam "FMTTYPE"
+  "Format Type (Mimetype per RFC4288)
+
+Specifies the media type of the object referenced in the property value,
+for example \"text/plain\" or \"text/html\".
+Valid media types are defined in RFC4288; see
+URL `https://www.rfc-editor.org/rfc/rfc4288#section-4.2'"
+  ical:mimetype
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.8")
+
+(ical:define-param ical:fbtypeparam "FBTYPE"
+  "Free/Busy Time Type.  Default is \"BUSY\".
+
+RFC5545 gives the following meanings to the values:
+
+FREE: the time interval is free for scheduling.
+BUSY: the time interval is busy because one or more events have
+  been scheduled for that interval.
+BUSY-UNAVAILABLE: the time interval is busy and the interval
+  can not be scheduled.
+BUSY-TENTATIVE: the time interval is busy because one or more
+  events have been tentatively scheduled for that interval.
+Other values are treated like BUSY."
+  (or "FREE"
+      "BUSY-UNAVAILABLE"
+      "BUSY-TENTATIVE"
+      "BUSY"
+      ical:x-name
+      ical:iana-token)
+  :default "BUSY"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.9")
+
+;; TODO: see https://www.rfc-editor.org/rfc/rfc5646#section-2.1
+(rx-define ical:rfc5646-lang
+  (one-or-more (any "A-Za-z0-9" ?-)))
+
+(ical:define-param ical:languageparam "LANGUAGE"
+  "Language tag (per RFC5646)
+
+This parameter specifies the language of the property value as a
+language tag, for example \"en-US\" for US English or \"no\" for
+Norwegian.  Valid language tags are defined in RFC5646; see
+URL `https://www.rfc-editor.org/rfc/rfc5646'"
+  ical:rfc5646-lang
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.10")
+
+(ical:define-param ical:memberparam "MEMBER"
+  "Group or List Membership.
+
+This is a comma-separated list of quoted `icalendar-cal-address'
+values.  These are addresses of groups or lists of which the user
+in the property value is a member."
+  ical:cal-address
+  :quoted t
+  :list-sep ","
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.11")
+
+(ical:define-param ical:partstatparam "PARTSTAT"
+  "Participation status.
+
+The value specifies the participation status of the calendar user
+in the property value.  They have different interpretations
+depending on whether they occur in a VEVENT, VTODO or VJOURNAL
+component.  RFC5545 gives the values the following meanings:
+
+NEEDS-ACTION (all): needs action by the user
+ACCEPTED (all): accepted by the user
+DECLINED (all): declined by the user
+TENTATIVE (VEVENT, VTODO): tentatively accepted by the user
+DELEGATED (VEVENT, VTODO): delegated by the user
+COMPLETED (VTODO): completed at the `icalendar-date-time' in the
+  VTODO's `icalendar-completed' property
+IN-PROCESS (VTODO): in the process of being completed"
+  (or "NEEDS-ACTION"
+      "ACCEPTED"
+      "DECLINED"
+      "TENTATIVE"
+      "DELEGATED"
+      "COMPLETED"
+      "IN-PROCESS"
+      (group-n 5 (or ical:x-name
+                     ical:iana-token)))
+  ;; "Applications MUST treat x-name and iana-token values
+  ;; they don't recognize the same way as they would the
+  ;; NEEDS-ACTION value."
+  :default "NEEDS-ACTION"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.12")
+
+(ical:define-param ical:rangeparam "RANGE"
+  "Recurrence Identifier Range.
+
+Specifies the effective range of recurrence instances of the property's value.
+The value \"THISANDFUTURE\" is the only value compliant with RFC5545;
+legacy applications might also produce \"THISANDPRIOR\"."
+  "THISANDFUTURE"
+  :default "THISANDFUTURE"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.13")
+
+(ical:define-param ical:trigrelparam "RELATED"
+  "Alarm Trigger Relationship.
+
+This parameter may be specified on properties whose values give
+an alarm trigger as an `icalendar-duration'.  If the parameter
+value is \"START\" (the default), the alarm triggers relative to
+the start of the component; similarly for \"END\"."
+  (or "START" "END")
+  :default "START"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.14")
+
+(ical:define-param ical:reltypeparam "RELTYPE"
+  "Relationship type.
+
+This parameter specifies a hierarchical relationship between the
+calendar component referenced in a `icalendar-related-to'
+property and the calendar component in which it occurs.
+\"PARENT\" means the referenced component is superior to this
+one, \"CHILD\" that the referenced component is subordinate to
+this one, and \"SIBLING\" means they are peers."
+  (or "PARENT"
+      "CHILD"
+      "SIBLING"
+      (group-n 5 (or ical:x-name
+                     ical:iana-token)))
+  ;; "Applications MUST treat x-name and iana-token values they don't
+  ;; recognize the same way as they would the PARENT value."
+  :default "PARENT"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.15")
+
+(ical:define-param ical:roleparam "ROLE"
+  "Participation role.
+
+This parameter specifies the participation role of the calendar
+user in the property value.  RFC5545 gives the parameter values
+the following meanings:
+CHAIR: chair of the calendar entity
+REQ-PARTICIPANT (default): user's participation is required
+OPT-PARTICIPANT: user's participation is optional
+NON-PARTICIPANT: user is copied for information purposes only"
+  (or "CHAIR"
+      "REQ-PARTICIPANT"
+      "OPT-PARTICIPANT"
+      "NON-PARTICIPANT"
+      (group-n 5 (or ical:x-name
+                     ical:iana-token)))
+  ;; "Applications MUST treat x-name and iana-token values
+  ;; they don't recognize the same way as they would the
+  ;; REQ-PARTICIPANT value."
+  :default "REQ-PARTICIPANT"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.16")
+
+(ical:define-param ical:rsvpparam "RSVP"
+  "RSVP expectation.
+
+This parameter is an `icalendar-boolean' which specifies whether
+the calendar user in the property value is expected to reply to
+the Organizer of a VEVENT or VTODO."
+  ical:boolean
+  :default "FALSE"
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.17")
+
+(ical:define-param ical:sentbyparam "SENT-BY"
+  "Sent by.
+
+This parameter specifies a calendar user that is acting on behalf
+of the user in the property value."
+  ;; "The parameter value MUST be a mailto URI as defined in [RFC2368]"
+  ;; Weirdly, this is the only place in the standard I've seen "mailto:"
+  ;; be *required* for a cal-address.  We ignore this requirement because
+  ;; coding around the exception is not worth it: it requires working
+  ;; around the fact that two different types, the looser and the more
+  ;; stringent cal-address, would need to have the same print name.
+  ical:cal-address
+  :quoted t
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.18")
+
+(ical:define-param ical:tzidparam "TZID"
+  "Time Zone identifier.
+
+This parameter identifies the VTIMEZONE component in the calendar
+which should be used to interpret the time value given in the
+property.  The value of this parameter must be equal to the value
+of the TZID property in that VTIMEZONE component; there must be
+exactly one such component for every unique value of this
+parameter in the calendar."
+  (seq (zero-or-one "/") ical:paramtext)
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.19")
+
+(defun ical:read-value-type (s)
+  "Read a value type from string S.
+S should contain the printed representation of a value type in a \"VALUE=...\"
+property parameter.  If S represents a known type in `icalendar-value-types',
+it is read as the associated type symbol.  Otherwise S is returned unchanged."
+  (let ((type-assoc (assoc s ical:value-types)))
+    (if type-assoc
+        (cdr type-assoc)
+      s)))
+
+(defun ical:print-value-type (type)
+  "Print a value type TYPE.
+TYPE should be an iCalendar type symbol naming a known value type
+defined with `icalendar-define-type', or a string naming an
+unknown type.  If it is a symbol, return the associated printed
+representation for the type from `icalendar-value-types'.
+Otherwise return TYPE."
+  (if (symbolp type)
+      (car (rassq type ical:value-types))
+    type))
+
+(ical:define-type ical:printed-value-type nil
+  "Type to represent values of the `icalendar-valuetypeparam' parameter.
+
+When read, if the type named by the parameter is a known value
+type in `icalendar-value-types', it is represented as a type
+symbol for that value type.  If it is an unknown value type, it is
+represented as a string.  When printed, a string is returned
+unchanged; a type symbol is printed as the associated name in
+`icalendar-value-types'.
+
+This is not a type defined by RFC5545; it is defined here to
+facilitate parsing of the `icalendar-valuetypeparam' parameter."
+  '(or string (satisfies ical:printable-value-type-symbol-p))
+  (or "BINARY"
+      "BOOLEAN"
+      "CAL-ADDRESS"
+      "DATE-TIME"
+      "DATE"
+      "DURATION"
+      "FLOAT"
+      "INTEGER"
+      "PERIOD"
+      "RECUR"
+      "TEXT"
+      "TIME"
+      "URI"
+      "UTC-OFFSET"
+      ;; Note: "Applications MUST preserve the value data for x-name
+      ;; and iana-token values that they don't recognize without
+      ;; attempting to interpret or parse the value data." So in this
+      ;; case we don't specify :default or :unrecognized in the
+      ;; parameter definition, and we don't put the value in group 5;
+      ;; the reader will just preserve whatever string matches here.
+      ical:x-name
+      ical:iana-token)
+  :reader ical:read-value-type
+  :printer ical:print-value-type)
+
+(ical:define-param ical:valuetypeparam "VALUE"
+  "Property value data type.
+
+This parameter is used to specify the value type of the
+containing property's value, if it is not of the default value
+type."
+  ical:printed-value-type
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.2.20")
+
+(ical:define-param ical:otherparam nil ; don't add to ical:param-types
+  "Parameter with an unknown name.
+
+This is not a parameter type defined by RFC5545; it represents
+parameters with an unknown name (matching rx `icalendar-param-name')
+whose values must be parsed and preserved but not further
+interpreted."
+  ical:param-value)
+
+(rx-define ical:other-param-safe
+  ;; we use this rx to skip params when matching properties and
+  ;; their values.  Thus we *don't* capture the param names and param values
+  ;; in numbered groups here, which would clobber the groups of the enclosing
+  ;; expression.
+  (seq ";"
+       (or ical:iana-token ical:x-name)
+       "="
+       (ical:comma-list ical:param-value)))
+
+
+;;; Properties:
+
+(defvar ical:property-types nil ;; populated by ical:define-property
+  "Alist mapping printed property names to type symbols.")
+
+(defun ical:read-property-value (type s &optional params)
+  "Read a value for the property type TYPE from a string S.
+
+TYPE should be a type symbol for an iCalendar property type
+defined with `icalendar-define-property'.  The property value is
+assumed to be of TYPE's default value type, unless an
+`icalendar-valuetypeparam' parameter appears in PARAMS, in which
+case a value of that type will be read.  S should have already
+been matched against TYPE's value regex and the match data should
+be available to this function.  Returns a property syntax node of
+type TYPE containing the read value and the list of PARAMS.
+
+If TYPE accepts lists of values, they will be split from S on the
+list separator and read separately."
+  (let* ((value-type (or (ical:value-type-from-params params)
+                         (get type 'ical:default-type)))
+         (list-sep (get type 'ical:list-sep))
+         (unrecognized-val (match-string 5))
+         (raw-val (if unrecognized-val
+                      (get type 'ical:substitute-value)
+                    s))
+         (value (if list-sep
+                    (ical:read-list-of value-type raw-val list-sep)
+                  (ical:read-value-node value-type raw-val))))
+    (ical:make-ast-node type
+                        (list :value value
+                              :original-value unrecognized-val)
+                        params)))
+
+(defun ical:parse-property-value (type limit &optional params)
+  "Parse a value for the property type TYPE from point up to LIMIT.
+This function expects point to be at the start of the value
+expression, after \"PROPERTY-NAME[PARAM...]:\".  Returns a syntax
+node of type TYPE containing the parsed value and the list of
+PARAMS."
+  (let ((start (point))
+        (full-value-regex (rx-to-string (get type 'ical:full-value-rx))))
+
+    ;; By far the most common invalid data seem to be text values that
+    ;; contain unescaped characters (e.g. commas in addresses in
+    ;; LOCATION).  These are harmless as long as the property accepts
+    ;; any text value, accepts no other types of values, and does not
+    ;; expect a list of values.  So we treat this as a special case and
+    ;; loosen the regexp to accept any non-control character until eol:
+    (when (and (eq 'ical:text (get type 'ical:default-type))
+               (equal (rx-to-string 'ical:text t)
+                      (rx-to-string (get type 'ical:value-rx) t))
+               (null (get type 'ical:other-types))
+               (not (ical:expects-list-of-values-p type))
+               (not ical:parse-strictly))
+        (setq full-value-regex
+              (rx (group-n 2 (zero-or-more (not (any control))))
+                  line-end)))
+
+    (unless (re-search-forward full-value-regex limit t)
+      (ical:signal-parse-error
+       (format "Unable to parse `%s' property value between %d and %d"
+               type start limit)
+       :restart-at (1+ limit)))
+
+    (when (match-string 3)
+      (ical:signal-parse-error
+       (format "Invalid value for `%s' property: %s" type (match-string 3))
+       :restart-at (1+ limit)))
+
+    (let* ((value-begin (match-beginning 2))
+           (value-end (match-end 2))
+           (end value-end)
+           (node (ical:read-property-value type (match-string 2) params)))
+      (ical:ast-node-meta-set node :buffer (current-buffer))
+      ;; 'begin must be set by parse-property
+      (ical:ast-node-meta-set node :value-begin value-begin)
+      (ical:ast-node-meta-set node :value-end value-end)
+      (ical:ast-node-meta-set node :end end)
+
+      node)))
+
+(defun ical:print-property-node (node)
+  "Serialize a property syntax node NODE to a string."
+  (setq node (ical:maybe-add-value-param node))
+  (let* ((type (ical:ast-node-type node))
+         (list-sep (get type 'ical:list-sep))
+         (property-name (car (rassq type ical:property-types)))
+         (name-str (or property-name
+                       (ical:ast-node-meta-get :original-name node)))
+         (params (ical:ast-node-children node))
+         (value (ical:ast-node-value node))
+         (value-str
+          (or (ical:ast-node-meta-get :original-value node)
+              ;; any ical:print-error here propagates:
+              (if list-sep
+                  (string-join (mapcar #'ical:default-value-printer value)
+                               list-sep)
+                (ical:default-value-printer value)))))
+
+    (unless (and (stringp name-str) (length> name-str 0))
+      (ical:signal-print-error
+       (format "Unknown property name for type `%s'" type)
+       :node node))
+
+    (concat name-str
+            (ical:print-params params)
+            ":"
+            value-str
+            "\n")))
+
+(defun ical:maybe-add-value-param (property-node)
+  "Add a VALUE parameter to PROPERTY-NODE if necessary.
+
+If the type of PROPERTY-NODE's value is not the same as its
+default-type, check that its parameter list contains an
+`icalendar-valuetypeparam' specifying that type as the type for
+the value.  If not, add such a parameter to PROPERTY-NODE's list
+of parameters.  Returns the possibly-modified PROPERTY-NODE.
+
+If the parameter list already contains a value type parameter for
+a type other than the property value's type, an
+`icalendar-validation-error' is signaled.
+
+If PROPERTY's value is a list, the type of the first element will
+be assumed to be the type for all the values in the list.  If the
+list is empty, no change will be made to PROPERTY's parameters."
+  (catch 'no-value-type
+    (let* ((property-type (ical:ast-node-type property-node))
+           (value/s (ical:ast-node-value property-node))
+           (value (if (and (ical:expects-list-of-values-p property-type)
+                           (listp value/s))
+                      (car value/s)
+                    value/s))
+           (value-type (cond ((stringp value) 'ical:text)
+                             ((ical:ast-node-p value)
+                              (ical:ast-node-type value))
+                             ;; if we can't determine a type from the value, bail:
+                             (t (throw 'no-value-type property-node))))
+           (params (ical:ast-node-children property-node))
+           (expected-type (ical:value-type-from-params params)))
+
+      (when (not (eq value-type (get property-type 'ical:default-type)))
+        (if expected-type
+            (when (not (eq value-type expected-type))
+              (ical:signal-validation-error
+                (format (concat "Mismatching VALUE parameter.  VALUE specifies %s "
+                                "but property value has type %s")
+                        expected-type value-type)
+                :node property-node))
+          ;; the value isn't of the default type, but we didn't find a
+          ;; VALUE parameter, so add one now:
+          (let* ((valuetype-param
+                  (ical:make-ast-node 'ical:valuetypeparam
+                                      (list :value (ical:make-ast-node
+                                                    'ical:printed-value-type
+                                                    (list :value value-type)))))
+                 (new-params (cons valuetype-param
+                                   (ical:ast-node-children property-node))))
+            (apply #'ical:ast-node-set-children property-node new-params))))
+
+      ;; Return the modified property node:
+      property-node)))
+
+(defun ical:value-type-from-params (params)
+  "Return the type symbol associated with any VALUE parameter in PARAMS.
+PARAMS should be a list of parameter nodes.  The type symbol specified by
+the first `icalendar-valuetypeparam' in PARAMS, or nil, will be returned."
+  (catch 'found
+    (dolist (param params)
+      (when (ical:value-param-p param)
+        (let ((type (ical:ast-node-value
+                     (ical:ast-node-value param))))
+          (throw 'found type))))))
+
+(defun ical:parse-property (limit)
+  "Parse the current property, up to LIMIT.
+
+Point should be at the beginning of a property line; LIMIT should be the
+position at the end of the line.
+
+Returns a syntax node for the property.  After parsing, point is at the
+beginning of the next content line."
+  (rx-let ((ical:property-start (seq line-start (group-n 1 ical:name))))
+    (let (line-begin line-end property-name property-type params node)
+      ;; Property name
+      (unless (re-search-forward (rx ical:property-start) limit t)
+        (ical:signal-parse-error
+         "Malformed property: could not match property name"
+         :restart-at (1+ limit)))
+
+      (setq property-name (match-string 1))
+      (setq line-begin (line-beginning-position))
+      (setq line-end (line-end-position))
+
+      ;; Parameters
+      (when (looking-at-p ";")
+        (setq params (ical:parse-params line-end)))
+
+      (unless (looking-at-p ":")
+        (ical:signal-parse-error
+         "Malformed property: parameters did not end at colon"
+         :restart-at (1+ limit)))
+      (forward-char)
+
+      ;; Value
+      (setq property-type (alist-get (upcase property-name)
+                                     ical:property-types
+                                     'ical:other-property
+                                     nil #'equal))
+      (setq node (ical:parse-property-value property-type limit params))
+
+      ;; sanity check, since e.g. invalid base64 data might not
+      ;; match all the way to the end of the line, as test
+      ;; rfc5545-sec3.1.3/2 initially revealed
+      (unless (eql (point) (line-end-position))
+        (ical:signal-parse-error
+         (format "%s property value did not consume line: %s"
+                 property-name
+                 (ical:default-value-printer (ical:ast-node-value node)))
+         :restart-at (1+ limit)))
+
+      ;; value, children are set in ical:read-property-value,
+      ;; value-begin, value-end, end in ical:parse-property-value.
+      ;; begin and original-name are only available here:
+      (ical:ast-node-meta-set node :begin line-begin)
+      (when (eq property-type 'ical:other-property)
+        (ical:ast-node-meta-set node :original-name property-name))
+
+      ;; Set point up for the next property parser.
+      (while (not (bolp))
+        (forward-char))
+
+      ;; Return the syntax node
+      node)))
+
+
+;;;; Section 3.7: Calendar Properties
+(ical:define-property ical:calscale "CALSCALE"
+  "Calendar scale.
+
+This property specifies the time scale of an
+`icalendar-vcalendar' object.  The only scale defined by RFC5545
+is \"GREGORIAN\", which is the default."
+  ;; only allowed value:
+  "GREGORIAN"
+  :default "GREGORIAN"
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.7.1")
+
+(ical:define-property ical:method "METHOD"
+  "Method for a scheduling request.
+
+When an `icalendar-vcalendar' is sent in a MIME message, this property
+specifies the semantics of the request in the message: e.g. it is
+a request to publish the calendar object, or a reply to an
+invitation.  This property and the MIME message's \"method\"
+parameter value must be the same.
+
+RFC5545 does not define any methods, but RFC5546 does; see
+URL `https://www.rfc-editor.org/rfc/rfc5546.html#section-3.2'"
+  ;; TODO: implement methods in RFC5546?
+  ical:iana-token
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.7.2")
+
+(ical:define-property ical:prodid "PRODID"
+  "Product Identifier.
+
+This property identifies the program that created an
+`icalendar-vcalendar' object.  It must be specified exactly once in a
+calendar object.  Its value should be a globally unique identifier for
+the program.  RFC5545 suggests using an ISO \"Formal Public Identifier\";
+see URL `https://en.wikipedia.org/wiki/Formal_Public_Identifier'."
+  ical:text
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.7.3")
+
+(ical:define-property ical:version "VERSION"
+  "Version (2.0 corresponds to RFC5545).
+
+This property specifies the version number of the iCalendar
+specification to which an `icalendar-vcalendar' object conforms,
+and must be specified exactly once in a calendar object.  It is
+either the string \"2.0\" or a string like MIN;MAX specifying
+minimum and maximum versions of future revisions of the
+specification."
+  (or "2.0"
+      ;; minver ";" maxver
+      (seq ical:iana-token ?\; ical:iana-token))
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.7.4")
+
+
+;;;; Section 3.8:
+;;;;; Section 3.8.1: Descriptive Component Properties
+
+(ical:define-property ical:attach "ATTACH"
+  "Attachment.
+
+This property specifies a file attached to an iCalendar
+component, either via a URI, or as encoded binary data.  In
+`icalendar-valarm' components, it is used to specify the
+notification sent by the alarm."
+  ;; Groups 11, 12 are used in ical:uri
+  (or (group-n 13 ical:uri)
+      (group-n 14 ical:binary))
+  :default-type ical:uri
+  :other-types (ical:binary)
+  :child-spec (:zero-or-one (ical:fmttypeparam
+                             ical:valuetypeparam
+                             ical:encodingparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:attach-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.1")
+
+(defun ical:attach-validator (node)
+  "Additional validator for an `icalendar-attach' NODE.
+Checks that NODE has a correct `icalendar-encodingparam' and
+`icalendar-valuetypeparam' if its value is an `icalendar-binary'.
+
+This function is called by `icalendar-ast-node-valid-p' for
+ATTACH nodes; it is not normally necessary to call it directly."
+  (let* ((value-node (ical:ast-node-value node))
+         (value-type (ical:ast-node-type value-node))
+         (valtypeparam (ical:ast-node-first-child-of 'ical:valuetypeparam node))
+         (encodingparam (ical:ast-node-first-child-of 'ical:encodingparam node)))
+
+    (when (eq value-type 'ical:binary)
+      (unless (and (ical:ast-node-p valtypeparam)
+                   (eq 'ical:binary
+                       (ical:ast-node-value ; unwrap inner printed-value-type
+                        (ical:ast-node-value valtypeparam))))
+        (ical:signal-validation-error
+         "`icalendar-binary' attachment requires 'VALUE=BINARY' parameter"
+        :node node))
+      (unless (and (ical:ast-node-p encodingparam)
+                   (equal "BASE64" (ical:ast-node-value encodingparam)))
+        (ical:signal-validation-error
+         "`icalendar-binary' attachment requires 'ENCODING=BASE64' parameter"
+         :node node)))
+    ;; success:
+    node))
+
+(ical:define-property ical:categories "CATEGORIES"
+  "Categories.
+
+This property lists categories or subtypes of an iCalendar
+component for e.g. searching or filtering.  The categories can be
+any `icalendar-text' value."
+  ical:text
+  :list-sep ","
+  :child-spec (:zero-or-one (ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.2")
+
+(ical:define-property ical:class "CLASS"
+  "(Access) Classification.
+
+This property specifies the scope of access that the calendar
+owner intends for a given component, e.g. public or private."
+  (or "PUBLIC"
+      "PRIVATE"
+      "CONFIDENTIAL"
+      (group-n 5
+        (or ical:iana-token
+            ical:x-name)))
+  ;; "If not specified in a component that allows this property, the
+  ;; default value is PUBLIC.  Applications MUST treat x-name and
+  ;; iana-token values they don't recognize the same way as they would
+  ;; the PRIVATE value."
+  :default "PUBLIC"
+  :unrecognized "PRIVATE"
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.3")
+
+(ical:define-property ical:comment "COMMENT"
+  "Comment to calendar user.
+
+This property can be specified multiple times in calendar components,
+and can contain any `icalendar-text' value."
+  ical:text
+  :child-spec (:zero-or-one (ical:altrepparam ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.4")
+
+(ical:define-property ical:description "DESCRIPTION"
+  "Description.
+
+This property should be a longer, more complete description of
+the calendar component than is contained in the
+`icalendar-summary' property.  In a `icalendar-vjournal'
+component, it is used to capture a journal entry, and may be
+specified multiple times.  Otherwise it may only be specified
+once.  In an `icalendar-valarm' component, it contains the
+notification text for a DISPLAY or EMAIL alarm."
+  ical:text
+  :child-spec (:zero-or-one (ical:altrepparam ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.5")
+
+(defun ical:read-geo-coordinates (s)
+  "Read an `icalendar-geo-coordinates' value from string S."
+  (let ((vals (mapcar #'string-to-number (string-split s ";"))))
+    (cons (car vals) (cadr vals))))
+
+(defun ical:print-geo-coordinates (val)
+  "Serialize an `icalendar-geo-coordinates' value to a string."
+  (concat (number-to-string (car val)) ";" (number-to-string (cdr val))))
+
+(defun ical:geo-coordinates-p (val)
+  "Return non-nil if VAL is an `icalendar-geo-coordinates' value."
+  (and (floatp (car val)) (floatp (cdr val))))
+
+(ical:define-type ical:geo-coordinates nil ; don't add to ical:value-types
+  "Type for global positions.
+
+This is not a type defined by RFC5545; it is defined here to
+facilitate parsing the `icalendar-geo' property.  When printed, it
+is represented as a pair of `icalendar-float' values separated by
+a semicolon, like LATITUDE;LONGITUDE.  When read, it is a dotted
+pair of Elisp floats (LATITUDE . LONGITUDE)."
+  '(satisfies ical:geo-coordinates-p)
+  (seq ical:float ";" ical:float)
+  :reader ical:read-geo-coordinates
+  :printer ical:print-geo-coordinates)
+
+(ical:define-property ical:geo "GEO"
+  "Global position of a component as a pair LATITUDE;LONGITUDE.
+
+Both values are floats representing a number of degrees.  The
+latitude value is north of the equator if positive, and south of
+the equator if negative.  The longitude value is east of the prime
+meridian if positive, and west of it if negative."
+  ical:geo-coordinates
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.6")
+
+(ical:define-property ical:location "LOCATION"
+  "Location.
+
+This property describes the intended location or venue of a
+component, e.g. a particular room or building, with an
+`icalendar-text' value.  RFC5545 suggests using the
+`icalendar-altrep' parameter on this property to provide more
+structured location information."
+  ical:text
+  :child-spec (:zero-or-one (ical:altrepparam ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.7")
+
+;; TODO: type for percentages?
+(ical:define-property ical:percent-complete "PERCENT-COMPLETE"
+  "Percent Complete.
+
+This property describes progress toward the completion of an
+`icalendar-vtodo' component.  It can appear at most once in such a
+component.  If this TODO is assigned to multiple people, the value
+represents the completion state for each person individually.  The
+value should be between 0 and 100 (though this is not currently
+enforced here)."
+  ical:integer
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.8")
+
+;; TODO: type for priority values?
+(ical:define-property ical:priority "PRIORITY"
+  "Priority.
+
+This property describes the priority of a component. 0 means an
+undefined priority.  Other values range from 1 (highest priority)
+to 9 (lowest priority).  See RFC5545 for suggestions on how to
+represent other priority schemes with this property."
+  ical:integer
+  :default "0"
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.9")
+
+(ical:define-property ical:resources "RESOURCES"
+  "Resources for an activity.
+
+This property is a list of `icalendar-text' values that describe
+any resources required or foreseen for the activity represented
+by a component, e.g. a projector and screen for a meeting."
+  ical:text
+  :list-sep ","
+  :child-spec (:zero-or-one (ical:altrepparam ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.10")
+
+(ical:define-type ical:status-keyword nil
+  "Keyword value of a STATUS property.
+
+This is not a real type defined by RFC5545; it is defined here to
+facilitate parsing that property."
+  '(and string (satisfies ical:match-status-keyword-value))
+  ;; Note that this type does NOT allow arbitrary text:
+  (or "TENTATIVE"
+      "CONFIRMED"
+      "CANCELLED"
+      "NEEDS-ACTION"
+      "COMPLETED"
+      "IN-PROCESS"
+      "DRAFT"
+      "FINAL"))
+
+(ical:define-property ical:status "STATUS"
+  "Overall status or confirmation.
+
+This property is a keyword used by an Organizer to inform
+Attendees about the status of a component, e.g. whether an
+`icalendar-vevent' has been cancelled, whether an
+`icalendar-vtodo' has been completed, or whether an
+`icalendar-vjournal' is still in draft form.  It can be specified
+at most once on these components."
+  ical:status-keyword
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.11")
+
+(ical:define-property ical:summary "SUMMARY"
+  "Short summary.
+
+This property provides a short, one-line description of a
+component for display purposes.  In an EMAIL `icalendar-valarm',
+it is used as the subject of the email.  A longer description of
+the component can be provided in the `icalendar-description'
+property."
+  ical:text
+  :child-spec (:zero-or-one (ical:altrepparam ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.1.12")
+
+;;;;; Section 3.8.2: Date and Time Component Properties
+
+(defun ical:property-w/tzid-validator (node)
+  "Additional validator for property NODE with `icalendar-tzid' parameters.
+Checks that this parameter does not occur in combination with an
+`icalendar-date' value or an `icalendar-date-time' in UTC time."
+  (ical:with-property node
+     ((ical:tzidparam :first tzidnode))
+    (when (and tzidnode (eq value-type 'ical:date))
+      (icalendar-signal-validation-error
+       "Property cannot contain `icalendar-tzidparam' with `icalendar-date' value"
+       :node node))
+    (when (and tzidnode (eq value-type 'ical:date-time)
+               (ical:date-time-is-utc-p value))
+      (icalendar-signal-validation-error
+       "Property cannot contain `icalendar-tzidparam' in combination with UTC time"
+       :node node))))
+
+(ical:define-property ical:completed "COMPLETED"
+  "Time completed.
+
+This property is a timestamp that records the date and time when
+an `icalendar-vtodo' was actually completed.  The value must be an
+`icalendar-date-time' with a UTC time."
+  ical:date-time
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.1")
+
+(ical:define-property ical:dtend "DTEND"
+  "End time of an event or free/busy block.
+
+This property's value specifies when an `icalendar-vevent' or
+`icalendar-freebusy' ends.  Its value must be of the same type as
+the value of the component's corresponding `icalendar-dtstart'
+property.  The value is a non-inclusive bound, i.e., the value of
+this property must be the first time or date *after* the end of
+the event or free/busy block."
+  (or ical:date-time
+      ical:date)
+  :default-type ical:date-time
+  :other-types (ical:date)
+  :child-spec (:zero-or-one (ical:valuetypeparam ical:tzidparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:property-w/tzid-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.2")
+
+(ical:define-property ical:due "DUE"
+  "Due date.
+
+This property specifies the date (and possibly time) by which an
+`icalendar-todo' item is expected to be completed, i.e., its
+deadline.  If the component also has an `icalendar-dtstart'
+property, the two properties must have the same value type, and
+the value of the DTSTART property must be earlier than the value
+of this property."
+  (or ical:date-time
+      ical:date)
+  :default-type ical:date-time
+  :other-types (ical:date)
+  :child-spec (:zero-or-one (ical:valuetypeparam ical:tzidparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:property-w/tzid-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.3")
+
+(ical:define-property ical:dtstart "DTSTART"
+  "Start time of a component.
+
+This property's value specifies when a component starts.  In an
+`icalendar-vevent', it specifies the start of the event.  In an
+`icalendar-vfreebusy', it specifies the start of the free/busy
+block.  In `icalendar-standard' and `icalendar-daylight'
+sub-components, it defines the start time of a time zone
+specification.
+
+It is required in any component with an `icalendar-rrule'
+property, and in any `icalendar-vevent' component contained in a
+calendar that does not have a `icalendar-method' property.
+
+Its value must be of the same type as the value of the
+component's corresponding `icalendar-dtend' property.  In an
+`icalendar-vtodo' component, it must also be of the same type as
+the value of an `icalendar-due' property (if present)."
+  (or ical:date-time
+      ical:date)
+  :default-type ical:date-time
+  :other-types (ical:date)
+  :child-spec (:zero-or-one (ical:valuetypeparam ical:tzidparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:property-w/tzid-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.4")
+
+(ical:define-property ical:duration "DURATION"
+  "Duration.
+
+This property specifies a duration of time for a component.
+In an `icalendar-vevent', it can be used to implicitly specify
+the end of the event, instead of an explicit `icalendar-dtend'.
+In an `icalendar-vtodo', it can likewise be used to implicitly specify
+the due date, instead of an explicit `icalendar-due'.
+In an `icalendar-valarm', it used to specify the delay period
+before the alarm repeats.
+
+If a related `icalendar-dtstart' property has an `icalendar-date'
+value, then the duration must be given as a number of weeks or days."
+  ical:dur-value
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.5")
+
+(ical:define-property ical:freebusy "FREEBUSY"
+  "Free/Busy Times.
+
+This property specifies a list of periods of free or busy time in
+an `icalendar-vfreebusy' component.  Whether it specifies free or
+busy times is determined by its `icalendar-fbtype' parameter.  The
+times in each period must be in UTC format."
+  ical:period
+  :list-sep ","
+  :child-spec (:zero-or-one (ical:fbtypeparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.6")
+
+(ical:define-property ical:transp "TRANSP"
+  "Time Transparency for free/busy searches.
+
+Note that this property only allows two values: \"TRANSPARENT\"
+or \"OPAQUE\".  An OPAQUE value means that the component consumes
+time on a calendar.  TRANSPARENT means it does not, and thus is
+invisible to free/busy time searches."
+  ;; Note that this does NOT allow arbitrary text:
+  (or "TRANSPARENT"
+      "OPAQUE")
+  :default "OPAQUE"
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.2.7")
+
+;;;;; Section 3.8.3: Time Zone Component Properties
+
+(ical:define-property ical:tzid "TZID"
+  "Time Zone Identifier.
+
+This property specifies the unique identifier for a time zone in
+an `icalendar-vtimezone' component, and is a required property of
+that component.  This is an identifier that `icalendar-tzidparam'
+parameters in other components may then refer to."
+  (seq (zero-or-one "/") ical:text)
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.3.1")
+
+(ical:define-property ical:tzname "TZNAME"
+  "Time Zone Name.
+
+This property specifies a customary name for a time zone in
+`icalendar-daylight' and `icalendar-standard' sub-components."
+  ical:text
+  :child-spec (:zero-or-one (ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.3.2")
+
+(ical:define-property ical:tzoffsetfrom "TZOFFSETFROM"
+  "Time Zone Offset (prior to observance).
+
+This property specifies the time zone offset that is in use
+*prior to* this time zone observance.  It is used to calculate the
+absolute time at which the observance takes place.  It is a
+required property of an `icalendar-vtimezone' component.  Positive
+numbers indicate time east of the prime meridian (ahead of UTC).
+Negative numbers indicate time west of the prime meridian (behind
+UTC)."
+  ical:utc-offset
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.3.3")
+
+(ical:define-property ical:tzoffsetto "TZOFFSETTO"
+  "Time Zone Offset (in this observance).
+
+This property specifies the time zone offset that is in use *in*
+this time zone observance.  It is used to calculate the absolute
+time at which a new observance takes place.  It is a required
+property of `icalendar-standard' and `icalendar-daylight'
+components.  Positive numbers indicate time east of the prime
+meridian (ahead of UTC).  Negative numbers indicate time west of
+the prime meridian (behind UTC)."
+  ical:utc-offset
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.3.4")
+
+(ical:define-property ical:tzurl "TZURL"
+  "Time Zone URL.
+
+This property specifies a URL where updated versions of an
+`icalendar-vtimezone' component are published."
+  ical:uri
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.3.5")
+
+;;;;; Section 3.8.4: Relationship Component Properties
+
+(ical:define-property ical:attendee "ATTENDEE"
+  "Attendee.
+
+This property specfies a participant in a `icalendar-vevent',
+`icalendar-vtodo', or `icalendar-valarm'.  It is required when the
+containing component represents event, task, or notification for
+a *group* of people, but not for components that simply represent
+these items in a single user's calendar (in that case, it should
+not be specified).  The property can be specified multiple times,
+once for each participant in the event or task.  In an
+EMAIL-category VALARM component, this property specifies the
+address of the user(s) who should receive the notification email.
+
+The parameters `icalendar-roleparam', `icalendar-partstatparam',
+`icalendar-rsvpparam', `icalendar-delfromparam', and
+`icalendar-deltoparam' are especially relevant for further
+specifying the roles of each participant in the containing
+component."
+  ical:cal-address
+  :child-spec (:zero-or-one (ical:cutypeparam
+                             ical:memberparam
+                             ical:roleparam
+                             ical:partstatparam
+                             ical:rsvpparam
+                             ical:deltoparam
+                             ical:delfromparam
+                             ical:sentbyparam
+                             ical:cnparam
+                             ical:dirparam
+                             ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.1")
+
+(ical:define-property ical:contact "CONTACT"
+  "Contact.
+
+This property provides textual contact information relevant to an
+`icalendar-vevent', `icalendar-vtodo', `icalendar-vjournal', or
+`icalendar-vfreebusy'."
+  ical:text
+  :child-spec (:zero-or-one (ical:altrepparam ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.2")
+
+(ical:define-property ical:organizer "ORGANIZER"
+  "Organizer.
+
+This property specifies the organizer of a group-scheduled
+`icalendar-vevent', `icalendar-vtodo', or `icalendar-vjournal'.
+It is required in those components if they represent a calendar
+entity with multiple participants.  In an `icalendar-vfreebusy'
+component, it used to specify the user requesting free or busy
+time, or the user who published the calendar that the free/busy
+information comes from."
+  ical:cal-address
+  :child-spec (:zero-or-one (ical:cnparam
+                             ical:dirparam
+                             ical:sentbyparam
+                             ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.3")
+
+(ical:define-property ical:recurrence-id "RECURRENCE-ID"
+  "Recurrence ID.
+
+This property is used together with the `icalendar-uid' and
+`icalendar-sequence' properties to identify a specific instance
+of a recurring `icalendar-vevent', `icalendar-vtodo', or
+`icalendar-vjournal' component.  The property value is the
+original value of the `icalendar-dtstart' property of the
+recurrence instance.  Its value must have the same type as that
+property's value, and both must specify times in the same way
+(either local or UTC)."
+  (or ical:date-time
+      ical:date)
+  :default-type ical:date-time
+  :other-types (ical:date)
+  :child-spec (:zero-or-one (ical:valuetypeparam
+                             ical:tzidparam
+                             ical:rangeparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.4")
+
+(ical:define-property ical:related-to "RELATED-TO"
+  "Related To (component UID).
+
+This property specifies the `icalendar-uid' value of a different,
+related calendar component.  It can be specified on an
+`icalendar-vevent', `icalendar-vtodo', or `icalendar-vjournal'
+component.  An `icalendar-reltypeparam' can be used to specify the
+relationship type."
+  ical:text
+  :child-spec (:zero-or-one (ical:reltypeparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.5")
+
+(ical:define-property ical:url "URL"
+  "Uniform Resource Locator.
+
+This property specifies the URL associated with an
+`icalendar-vevent', `icalendar-vtodo', `icalendar-vjournal', or
+`icalendar-vfreebusy' component."
+  ical:uri
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.6")
+
+;; TODO: UID should probably be its own type
+(ical:define-property ical:uid "UID"
+  "Unique Identifier.
+
+This property specifies a globally unique identifier for the
+containing component, and is required in an `icalendar-vevent',
+`icalendar-vtodo', `icalendar-vjournal', or `icalendar-vfreebusy'
+component.
+
+RFC5545 requires that the program generating the UID guarantee
+that it be unique, and recommends generating it in a format which
+includes a timestamp on the left hand side of an '@' character,
+and the domain name or IP address of the host on the right-hand
+side."
+  ical:text
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.4.7")
+
+;;;;; Section 3.8.5: Recurrence Component Properties
+
+(ical:define-property ical:exdate "EXDATE"
+  "Exception Date-Times.
+
+This property defines a list of exceptions to a recurrence rule
+in an `icalendar-vevent', `icalendar-todo', `icalendar-vjournal',
+`icalendar-standard', or `icalendar-daylight' component.  Together
+with the `icalendar-dtstart', `icalendar-rrule', and
+`icalendar-rdate' properties, it defines the recurrence set of
+the component."
+  (or ical:date-time
+      ical:date)
+  :default-type ical:date-time
+  :other-types (ical:date)
+  :list-sep ","
+  :child-spec (:zero-or-one (ical:valuetypeparam ical:tzidparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:property-w/tzid-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.5.1")
+
+(ical:define-property ical:rdate "RDATE"
+  "Recurrence Date-Times.
+
+This property defines a list of date-times or dates on which an
+`icalendar-vevent', `icalendar-todo', `icalendar-vjournal',
+`icalendar-standard', or `icalendar-daylight' component recurs.
+Together with the `icalendar-dtstart', `icalendar-rrule', and
+`icalendar-exdate' properties, it defines the recurrence set of
+the component."
+  (or ical:period
+      ical:date-time
+      ical:date)
+  :default-type ical:date-time
+  :other-types (ical:date ical:period)
+  :list-sep ","
+  :child-spec (:zero-or-one (ical:valuetypeparam ical:tzidparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:property-w/tzid-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.5.2")
+
+(ical:define-property ical:rrule "RRULE"
+  "Recurrence Rule.
+
+This property defines a rule or repeating pattern for the dates
+and times on which an `icalendar-vevent', `icalendar-todo',
+`icalendar-vjournal', `icalendar-standard', or
+`icalendar-daylight' component recurs.  Together with the
+`icalendar-dtstart', `icalendar-rdate', and `icalendar-exdate'
+properties, it defines the recurrence set of the component."
+  ical:recur
+  ;; TODO: faces for subexpressions?
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.5.3")
+
+;;;;; Section 3.8.6: Alarm Component Properties
+
+(ical:define-property ical:action "ACTION"
+  "Action (when alarm triggered).
+
+This property defines the action to be taken when the containing
+`icalendar-valarm' component is triggered.  It is a required
+property in an alarm component."
+  (or "AUDIO"
+      "DISPLAY"
+      "EMAIL"
+      (group-n 5
+        (or ical:iana-token
+            ical:x-name)))
+  ;; "Applications MUST ignore alarms with x-name and iana-token values
+  ;; they don't recognize." This substitute is not defined in the
+  ;; standard but is the simplest way to parse such alarms:
+  :unrecognized "IGNORE"
+  :default-type ical:text
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.6.1")
+
+(ical:define-property ical:repeat "REPEAT"
+  "Repeat Count (after initial trigger).
+
+This property specifies the number of times an `icalendar-valarm'
+should repeat after it is initially triggered.  This property,
+along with the `icalendar-duration' property, is required if the
+alarm triggers more than once."
+  ical:integer
+  :default "0"
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.6.2")
+
+(ical:define-property ical:trigger "TRIGGER"
+  "Trigger.
+
+This property specifies when an `icalendar-valarm' should
+trigger.  If the value is an `icalendar-dur-value', it represents
+a time of that duration relative to the start or end of a related
+`icalendar-vevent' or `icalendar-vtodo'.  Whether the trigger
+applies to the start time or end time of the related component
+can be specified with the `icalendar-trigrelparam' parameter.  A
+positive duration value triggers after the start or end of the
+related component; a negative duration value triggers before.
+
+If the value is an `icalendar-date-time', it must be in UTC
+format, and it triggers at the specified time."
+  (or ical:dur-value
+      ical:date-time)
+  :default-type ical:dur-value
+  :other-types (ical:date-time)
+  :child-spec (:zero-or-one (ical:valuetypeparam ical:trigrelparam)
+               :zero-or-more (ical:otherparam))
+  :other-validator ical:trigger-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.6.3")
+
+(defun ical:trigger-validator (node)
+  "Additional validator for an `icalendar-trigger' NODE.
+Checks that NODE has valid parameters depending on the type of its value.
+
+This function is called by `icalendar-ast-node-valid-p' for
+TRIGGER nodes; it is not normally necessary to call it directly."
+  (let* ((params (ical:ast-node-children node))
+         (value-node (ical:ast-node-value node))
+         (value-type (and value-node (ical:ast-node-type value-node))))
+    (when (eq value-type 'ical:date-time)
+      (let ((expl-type (ical:value-type-from-params params))
+            (dt-value (ical:ast-node-value value-node)))
+        (unless (eq expl-type 'ical:date-time)
+          (ical:signal-validation-error
+           (concat "Explicit `icalendar-valuetypeparam' required in "
+                   "`icalendar-trigger' with non-duration value")
+           :node node))
+        (when (ical:ast-node-first-child-of 'ical:trigrelparam node)
+          (ical:signal-validation-error
+           (concat "`icalendar-trigrelparam' not allowed in "
+                   "`icalendar-trigger' with non-duration value")
+           :node node))
+        (unless (ical:date-time-is-utc-p dt-value)
+          (ical:signal-validation-error
+           (concat "`icalendar-date-time' value of `icalendar-trigger' "
+                   "must be in UTC time")
+           :node node))))
+    ;; success:
+    node))
+
+;;;;; Section 3.8.7: Change Management Component Properties
+
+(ical:define-property ical:created "CREATED"
+  "Date-Time Created.
+
+This property specifies the date and time when the calendar user
+initially created an `icalendar-vevent', `icalendar-vtodo', or
+`icalendar-vjournal' in the calendar database.  The value must be
+in UTC time."
+  ical:date-time
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.7.1")
+
+(ical:define-property ical:dtstamp "DTSTAMP"
+  "Timestamp (of last revision or instance creation).
+
+In an `icalendar-vevent', `icalendar-vtodo',
+`icalendar-vjournal', or `icalendar-vfreebusy', this property
+specifies the date and time when the calendar user last revised
+the component's data in the calendar database.  (In this case, it
+is equivalent to the `icalendar-last-modified' property.)
+
+If this property is specified on an `icalendar-vcalendar' object
+which contains an `icalendar-method' property, it specifies the
+date and time when that instance of the calendar object was
+created.  In this case, it differs from the `icalendar-creation'
+and `icalendar-last-modified' properties: whereas those specify
+the time the underlying data was created and last modified in the
+calendar database, this property specifies when the calendar
+object *representing* that data was created.
+
+The value must be in UTC time."
+  ical:date-time
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.7.2")
+
+(ical:define-property ical:last-modified "LAST-MODIFIED"
+  "Last Modified timestamp.
+
+This property specifies when the data in an `icalendar-vevent',
+`icalendar-vtodo', `icalendar-vjournal', or `icalendar-vtimezone'
+was last modified in the calendar database."
+  ical:date-time
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.7.3")
+
+(ical:define-property ical:sequence "SEQUENCE"
+  "Revision Sequence Number.
+
+This property specifies the number of the current revision in a
+sequence of revisions in an `icalendar-vevent',
+`icalendar-vtodo', or `icalendar-vjournal' component.  It starts
+at 0 and should be incremented monotonically every time the
+Organizer makes a significant revision to the calendar data that
+component represents."
+  ical:integer
+  :default "0"
+  :child-spec (:zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.7.4")
+
+;;;;; Section 3.8.8: Miscellaneous Component Properties
+;; IANA and X- properties should be parsed and printed but can be ignored:
+(ical:define-property ical:other-property nil ; don't add to ical:property-types
+  "IANA or X-name property.
+
+This property type corresponds to the IANA Properties and
+Non-Standard Properties defined in RFC5545; it represents
+properties with an unknown name (matching rx
+`icalendar-iana-token' or `icalendar-x-name') whose values must
+be parsed and preserved but not further interpreted.  Its value
+may be set to any type with the `icalendar-valuetypeparam'
+parameter."
+  ical:value
+  :default-type ical:text
+  ;; "The default value type is TEXT.  The value type can be set to any
+  ;; value type." TODO: should we specify :other-types?  Without it, a
+  ;; VALUE param will be required to parse anything other than text,
+  ;; but that seems reasonable.
+  :child-spec (:allow-others t)
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.8")
+
+(defun ical:read-req-status-info (s)
+  "Read a request status value from S.
+S should have been previously matched against `icalendar-request-status-info'."
+  ;; TODO: this smells like a design flaw.  Silence the byte compiler for now.
+  (ignore s)
+  (let ((code (match-string 11))
+        (desc (match-string 12))
+        (exdata (match-string 13)))
+    (list code (ical:read-text desc) (when exdata (ical:read-text exdata)))))
+
+(defun ical:print-req-status-info (rsi)
+  "Serialize request status info value RSI to a string."
+  (let ((code (car rsi))
+        (desc (cadr rsi))
+        (exdata (caddr rsi)))
+    (if exdata
+        (format "%s;%s;%s" code (ical:print-text desc) (ical:print-text exdata))
+      (format "%s;%s" code (ical:print-text desc)))))
+
+(defun ical:req-status-info-p (val)
+  "Return non-nil if VAL is an `icalendar-request-status-info' value."
+  (and (listp val)
+       (length= val 3)
+       (stringp (car val))
+       (stringp (cadr val))
+       (cl-typep (caddr val) '(or string null))))
+
+(ical:define-type ical:req-status-info nil
+  "Type for REQUEST-STATUS property values.
+
+When read, a list (CODE DESCRIPTION EXCEPTION).  CODE is a hierarchical
+numerical code, represented as a string, with the following meanings:
+  1.xx Preliminary success
+  2.xx Successful
+  3.xx Client Error
+  4.xx Scheduling Error
+DESCRIPTION is a longer description of the request status, also a string.
+EXCEPTION (which may be nil) is textual data describing an error.
+
+When printed, the three elements are separated by semicolons, like
+  CODE;DESCRIPTION;EXCEPTION
+or
+  CODE;DESCRIPTION
+if EXCEPTION is nil.
+
+This is not a type defined by RFC5545; it is defined here to
+facilitate parsing the `icalendar-request-status' property."
+  '(satisfies ical:req-status-info-p)
+  (seq
+   ;; statcode: hierarchical status code
+   (group-n 11
+     (seq (one-or-more digit)
+          (** 1 2 (seq ?. (one-or-more digit)))))
+   ?\;
+   ;; statdesc: status description
+   (group-n 12 ical:text)
+   ;; exdata: exception data
+   (zero-or-one (seq ?\; (group-n 13 ical:text))))
+  :reader ical:read-req-status-info
+  :printer ical:print-req-status-info
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.8.3")
+
+(ical:define-property ical:request-status "REQUEST-STATUS"
+  "Request status"
+  ical:req-status-info
+  :child-spec (:zero-or-one (ical:languageparam)
+               :zero-or-more (ical:otherparam))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.8.8.3")
+
+
+;;; Section 3.6: Calendar Components
+
+(defvar ical:component-types nil ;; populated by ical:define-component
+  "Alist mapping printed component names to type symbols.")
+
+(defun ical:parse-component (limit)
+  "Parse an iCalendar component from point up to LIMIT.
+Point should be at the start of the component, i.e., at the start
+of a line that looks like \"BEGIN:[COMPONENT-NAME]\".  After parsing,
+point is at the beginning of the next line following the component
+\(or end of the buffer).  Returns a syntax node representing the component."
+  (let ((begin-pos nil)
+        (body-begin-pos nil)
+        (end-pos nil)
+        (body-end-pos nil)
+        (begin-regex (rx line-start "BEGIN:" (group-n 2 ical:name) line-end)))
+
+    (unless (re-search-forward begin-regex limit t)
+      (ical:signal-parse-error "Not at start of a component"))
+
+    (setq begin-pos (match-beginning 0)
+          body-begin-pos (1+ (match-end 0))) ; start of next line
+
+    (let* ((component-name (match-string 2))
+           (known-type (alist-get (upcase component-name)
+                                  ical:component-types
+                                  nil nil #'equal))
+           (component-type (or known-type 'ical:other-component))
+           child children)
+
+      ;; Find end of component:
+      (save-excursion
+        (if (re-search-forward (concat "^END:" component-name "$") limit t)
+            (setq end-pos (match-end 0)
+                  body-end-pos (1- (match-beginning 0))) ; end of prev. line
+          (ical:signal-parse-error
+           (format  "Matching 'END:%s' not found between %d and %d"
+                    component-name begin-pos limit)
+           :restart-at (1+ limit))))
+
+      (while (not (bolp))
+        (forward-char))
+
+      ;; Parse the properties and subcomponents of this component:
+      (while (<= (point) body-end-pos)
+        (condition-case err
+            (setq child (ical:parse-property-or-component end-pos))
+          (ical:parse-error
+           (ical:handle-parse-error err)
+           (setq child nil)))
+        (when child (push child children)))
+
+      ;; Set point up for the next parser:
+      (goto-char end-pos)
+      (while (and (< (point) (point-max)) (not (bolp)))
+        (forward-char))
+
+      ;; Return the syntax node for the component:
+      (when children
+        (ical:make-ast-node component-type
+                            (list
+                             :original-name
+                             (when (eq component-type 'ical:other-component)
+                               component-name)
+                             :buffer (current-buffer)
+                             :begin begin-pos
+                             :end end-pos
+                             :value-begin body-begin-pos
+                             :value-end body-end-pos)
+                            (nreverse children))))))
+
+(defun ical:parse-property-or-component (limit)
+  "Parse a component or a property at point, up to LIMIT.
+Point should be at the beginning of a line which begins a
+component or contains a property."
+  (cond ((looking-at-p (rx line-start "BEGIN:" ical:name line-end))
+         (ical:parse-component limit))
+        ((looking-at-p (rx line-start ical:name))
+         (ical:parse-property (line-end-position)))
+        (t (ical:signal-parse-error
+            "Not at start of property or component"
+            :restart-at ; find start of next content line:
+            (save-excursion
+              (if (re-search-forward (rx line-start ical:name) nil t)
+                  (match-beginning 0)
+                (point-max)))))))
+
+(defun ical:print-component-node (node)
+  "Serialize a component syntax node NODE to a string."
+  (let* ((type (ical:ast-node-type node))
+         (name (or (ical:ast-node-meta-get :original-name node)
+                   (car (rassq type ical:component-types))))
+         (children (ical:ast-node-children node))
+         body)
+
+    (unless name
+      (ical:signal-print-error
+       (format "Unknown component name for type `%s'" type)
+       :node node))
+
+    (dolist (child children)
+      (condition-case err
+          (setq body
+                (concat body (ical:print-property-or-component child)))
+        (ical:print-error
+         (if (ical:ast-node-required-child-p child node)
+             (ical:signal-print-error
+              (format
+               "Unable to print required `%s' %s in `%s' component.  Error was:\n%s"
+               (ical:ast-node-type child)
+               (if (ical:component-node-p child) "subcomponent" "property")
+               (ical:ast-node-type node)
+               (plist-get (cdr err) :message))
+              :node node)
+           (ical:handle-print-error err)))))
+    (concat
+     (format "BEGIN:%s\n" name)
+     body
+     (format "END:%s\n" name))))
+
+(defun ical:print-property-or-component (node)
+  "Serialize a property or component node NODE to a string."
+  (cond ((ical:property-node-p node)
+         (ical:print-property-node node))
+        ((ical:component-node-p node)
+         (ical:print-component-node node))
+        (t (ical:signal-print-error "Not a component or property node"
+                                    :node node))))
+
+(ical:define-component ical:vevent "VEVENT"
+  "Represents an event.
+
+This component contains properties which describe an event, such
+as its start and end time (`icalendar-dtstart' and
+`icalendar-dtend') and a summary (`icalendar-summary') and
+description (`icalendar-description').  It may also contain
+`icalendar-valarm' components as subcomponents which describe
+reminder notifications related to the event.  Event components can
+only be direct children of an `icalendar-vcalendar'; they cannot
+be subcomponents of any other component."
+  :child-spec (:one (ical:dtstamp ical:uid)
+               :zero-or-one (ical:dtstart
+                             ;; TODO: dtstart required if METHOD not present
+                             ;; in parent calendar
+                             ical:class
+                             ical:created
+                             ical:description
+                             ical:dtend
+                             ical:duration
+                             ical:geo
+                             ical:last-modified
+                             ical:location
+                             ical:organizer
+                             ical:priority
+                             ical:sequence
+                             ical:status
+                             ical:summary
+                             ical:transp
+                             ical:url
+                             ical:recurrence-id
+                             ical:rrule)
+               :zero-or-more (ical:attach
+                              ical:attendee
+                              ical:categories
+                              ical:comment
+                              ical:contact
+                              ical:exdate
+                              ical:request-status
+                              ical:related-to
+                              ical:resources
+                              ical:rdate
+                              ical:other-property
+                              ical:valarm))
+  :other-validator ical:vevent-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.1")
+
+(defun ical:rrule-validator (node)
+  "Validate that NODE has the properties required by a recurrence rule.
+
+NODE should represent an iCalendar component.  When NODE has an
+`icalendar-rrule' property, this function validates that its
+`icalendar-dtstart', `icalendar-rdate', and `icalendar-exdate'
+properties satisfy the requirements imposed by this rule.
+
+This function is called by the additional validator functions for
+component nodes (e.g. `icalendar-vevent-validator'); it is not normally
+necessary to call it directly."
+  (let* ((rrule (ical:ast-node-first-child-of 'ical:rrule node))
+         (recval (when rrule (ical:ast-node-value rrule)))
+         (dtstart (ical:ast-node-first-child-of 'ical:dtstart node))
+         (start (when dtstart (ical:ast-node-value dtstart)))
+         (rdates (ical:ast-node-children-of 'ical:rdate node))
+         (included (when rdates
+                     (mapcar #'ical:ast-node-value
+                             (apply #'append
+                                    (mapcar #'ical:ast-node-value rdates))))))
+    (when rrule
+      (unless dtstart
+        (ical:signal-validation-error
+         "An `icalendar-rrule' requires an `icalendar-dtstart' property"
+         :node node))
+      (when included
+        ;; ""RDATE" in this usage [i.e., in STANDARD and DAYLIGHT
+        ;; subcomponents] MUST be specified as a date with local time
+        ;; value, relative to the UTC offset specified in the
+        ;; "TZOFFSETFROM" property."
+        (when (and (memq (ical:ast-node-type node) '(ical:standard ical:daylight)))
+          (unless (ical:list-of-p included 'ical:date-time)
+            (ical:signal-validation-error
+             (format
+              (concat "`icalendar-rdate' values must be `icalendar-date-time' "
+                      "values in %s components")
+              (ical:ast-node-type node))
+             :node node))
+          (when (seq-some #'decoded-time-zone included)
+            (ical:signal-validation-error
+             (format
+              (concat "`icalendar-rdate' values must be in local (\"floating\")"
+                      "time in %s components")
+              (ical:ast-node-type node))
+             :node node))))
+
+      (let* ((freq (car (alist-get 'FREQ recval)))
+             (until (car (alist-get 'UNTIL recval))))
+        (when (eq 'ical:date (ical:ast-node-type start))
+          (when (or (memq freq '(HOURLY MINUTELY SECONDLY))
+                    (assq 'BYSECOND recval)
+                    (assq 'BYMINUTE recval)
+                    (assq 'BYHOUR recval))
+            (ical:signal-validation-error
+             (concat "`icalendar-rrule' must not contain time-based "
+                     "rules when `icalendar-dtstart' is a plain date")
+             :node node)))
+        (when until
+          (unless (eq (ical:ast-node-type start)
+                      (ical:ast-node-type until))
+            (ical:signal-validation-error
+             (concat "`icalendar-rrule' UNTIL clause must agree with "
+                     "type of `icalendar-dtstart' property")
+             :node node))
+          (when (eq 'ical:date-time (ical:ast-node-type until))
+            (let ((until-zone
+                   (decoded-time-zone (ical:ast-node-value until)))
+                  (start-zone
+                   (decoded-time-zone (ical:ast-node-value start))))
+              ;; "If the "DTSTART" property is specified as a date
+              ;; with local time, then the UNTIL rule part MUST also
+              ;; be specified as a date with local time":
+              (when (and (null start-zone) (not (null until-zone)))
+                (ical:signal-validation-error
+                  (concat "`icalendar-rrule' UNTIL clause must be in "
+                          "local time if `icalendar-dtstart' is")
+                  :node node))
+              ;; "If the "DTSTART" property is specified as a date
+              ;; with UTC time or a date with local time and time zone
+              ;; reference, then the UNTIL rule part MUST be specified
+              ;; as a date with UTC time":
+              (when (and (integerp start-zone)
+                         (not (ical:date-time-is-utc-p until)))
+                (ical:signal-validation-error
+                  (concat "`icalendar-rrule' UNTIL clause must be in UTC time "
+                          "if `icalendar-dtstart' has a defined time zone")
+                  :node node))))
+          (when (memq (ical:ast-node-type node) '(ical:standard ical:daylight))
+            ;; "In the case of the "STANDARD" and "DAYLIGHT"
+            ;; sub-components the UNTIL rule part MUST always be
+            ;; specified as a date with UTC time":
+            (unless (ical:date-time-is-utc-p until)
+              (ical:signal-validation-error
+               (concat "`icalendar-rrule' UNTIL clause must be in UTC time in "
+                       "`icalendar-standard' and `icalendar-daylight' components")
+               :node node))))
+
+        ;; "DTSTART in this usage [i.e., in STANDARD and DAYLIGHT
+        ;; subcomponents] MUST be specified as a date with a local
+        ;; time value."
+        (when (memq (ical:ast-node-type node) '(ical:standard ical:daylight))
+          (unless (eq 'ical:date-time (ical:ast-node-type start))
+            (ical:signal-validation-error
+              (concat "`icalendar-dtstart' must be an `icalendar-date-time' in "
+                      "`icalendar-standard' and `icalendar-daylight' components")
+              :node node))
+
+          (when (decoded-time-zone (ical:ast-node-value start))
+            (ical:signal-validation-error
+             (concat "`icalendar-dtstart' must be in local (\"floating\") time in "
+                     "`icalendar-standard' and `icalendar-daylight' components")
+             :node node)))))
+
+    ;; Success:
+    node))
+
+(defun ical:vevent-validator (node)
+  "Additional validator for an `icalendar-vevent' NODE.
+Checks that NODE has does not have both `icalendar-duration' and
+`icalendar-dtend' properties, and calls `icalendar-rrule-validator'.
+
+This function is called by `icalendar-ast-node-valid-p' for
+VEVENT nodes; it is not normally necessary to call it directly."
+  (let* ((duration (ical:ast-node-first-child-of 'ical:duration node))
+         (dur-value (when duration (ical:ast-node-value
+                                     (ical:ast-node-value duration))))
+         (dtend (ical:ast-node-first-child-of 'ical:dtend node))
+         (dtstart (ical:ast-node-first-child-of 'ical:dtstart node)))
+    (when (and dtend duration)
+      (ical:signal-validation-error
+       (concat "`icalendar-dtend' and `icalendar-duration' properties must "
+               "not appear in the same `icalendar-vevent'")
+       :node node))
+    ;; don't allow time-based durations with dates
+    ;; TODO: check that the standard disallows this...?
+    (when (and dtstart duration
+               (eq 'ical:date (ical:ast-node-type dtstart))
+               (or (not (integerp dur-value))
+                   (decoded-time-hour dur-value)
+                   (decoded-time-minute dur-value)
+                   (decoded-time-second dur-value)))
+      (ical:signal-validation-error
+       (concat "Event with `icalendar-date' value in `icalendar-dtstart' "
+               "cannot have time units in `icalendar-duration'")
+       :node node))
+
+  (ical:rrule-validator node)
+  ;; success:
+  node))
+
+(ical:define-component ical:vtodo "VTODO"
+  "Represents a To-Do item or task.
+
+This component contains properties which describe a to-do item or
+task, such as its due date (`icalendar-due') and a summary
+(`icalendar-summary') and description (`icalendar-description').
+It may also contain `icalendar-valarm' components as
+subcomponents which describe reminder notifications related to
+the task.  To-do components can only be direct children of an
+`icalendar-vcalendar'; they cannot be subcomponents of any other
+component."
+  :child-spec (:one (ical:dtstamp ical:uid)
+               :zero-or-one (ical:class
+                             ical:completed
+                             ical:created
+                             ical:description
+                             ical:dtstart
+                             ical:due
+                             ical:duration
+                             ical:geo
+                             ical:last-modified
+                             ical:location
+                             ical:organizer
+                             ical:percent-complete
+                             ical:priority
+                             ical:recurrence-id
+                             ical:sequence
+                             ical:status
+                             ical:summary
+                             ical:url
+                             ical:rrule)
+               :zero-or-more (ical:attach
+                              ical:attendee
+                              ical:categories
+                              ical:comment
+                              ical:contact
+                              ical:exdate
+                              ical:request-status
+                              ical:related-to
+                              ical:resources
+                              ical:rdate
+                              ical:other-property
+                              ical:valarm))
+  :other-validator ical:vtodo-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.2")
+
+(defun ical:vtodo-validator (node)
+  "Additional validator for an `icalendar-vtodo' NODE.
+Checks that NODE has conformant `icalendar-due',
+`icalendar-duration', and `icalendar-dtstart' properties, and calls
+`icalendar-rrule-validator'.
+
+This function is called by `icalendar-ast-node-valid-p' for
+VTODO nodes; it is not normally necessary to call it directly."
+  (let* ((due (ical:ast-node-first-child-of 'ical:due node))
+         (duration (ical:ast-node-first-child-of 'ical:duration node))
+         (dtstart (ical:ast-node-first-child-of 'ical:dtstart node)))
+    (when (and due duration)
+      (ical:signal-validation-error
+       (concat "`icalendar-due' and `icalendar-duration' properties "
+               "must not appear in the same `icalendar-vtodo'")
+       :node node))
+    (when (and duration (not dtstart))
+      (ical:signal-validation-error
+       (concat "`icalendar-duration' requires `icalendar-dtstart' "
+               "property in the same `icalendar-vtodo'")
+       :node node)))
+  (ical:rrule-validator node)
+  ;; success:
+  node)
+
+(ical:define-component ical:vjournal "VJOURNAL"
+  "Represents a journal entry.
+
+This component contains properties which describe a journal
+entry, which might be any longer-form data (e.g., meeting notes,
+a diary entry, or information needed to complete a task).  It can
+be associated with an `icalendar-vevent' or `icalendar-vtodo' via
+the `icalendar-related-to' property.  A journal entry does not
+take up time in a calendar, and plays no role in searches for
+free or busy time.  Journal components can only be direct children
+of `icalendar-vcalendar'; they cannot be subcomponents of any
+other component."
+  :child-spec (:one (ical:dtstamp ical:uid)
+               :zero-or-one (ical:class
+                             ical:created
+                             ical:dtstart
+                             ical:last-modified
+                             ical:organizer
+                             ical:recurrence-id
+                             ical:sequence
+                             ical:status
+                             ical:summary
+                             ical:url
+                             ical:rrule)
+               :zero-or-more (ical:attach
+                              ical:attendee
+                              ical:categories
+                              ical:comment
+                              ical:contact
+                              ical:description
+                              ical:exdate
+                              ical:related-to
+                              ical:rdate
+                              ical:request-status
+                              ical:other-property)
+               :other-validator ical:rrule-validator)
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.3")
+
+(ical:define-component ical:vfreebusy "VFREEBUSY"
+  "Represents a published set of free/busy time blocks, or a request
+or response for such blocks.
+
+The free/busy information is represented by the
+`icalendar-freebusy' property (which may be given more than once)
+and the related `icalendar-fbtype' parameter.  Note that
+recurrence properties (`icalendar-rrule', `icalendar-rdate', and
+`icalendar-exdate') are NOT permitted in this component.
+
+When used to publish blocks of free/busy time in a user's
+schedule, the `icalendar-organizer' property specifies the user.
+
+When used to request free/busy time in a user's schedule, or to
+respond to such a request, the `icalendar-attendee' property
+specifies the user whose time is being requested, and the
+`icalendar-organizer' property specifies the user making the
+request.
+
+Free/busy components can only be direct children
+of `icalendar-vcalendar'; they cannot be subcomponents of any
+other component, and cannot contain subcomponents."
+  :child-spec (:one (ical:dtstamp ical:uid)
+               :zero-or-one (ical:contact
+                             ical:dtstart
+                             ical:dtend
+                             ical:organizer
+                             ical:url)
+               :zero-or-more (ical:attendee
+                              ical:comment
+                              ical:freebusy
+                              ical:request-status
+                              ical:other-property))
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.4")
+
+;; TODO: RFC7808 defines additional properties that are relevant here:
+;; https://www.rfc-editor.org/rfc/rfc7808.html#section-7
+(ical:define-component ical:vtimezone "VTIMEZONE"
+  "Represents a time zone.
+
+A time zone is identified by an `icalendar-tzid' property, which
+is required in this component.  Times in other calendar components
+can be specified in local time in this time zone with the
+`icalendar-tzidparam' parameter.  An `icalendar-vcalendar' object
+must contain exactly one `icalendar-vtimezone' component for each
+unique time zone identifier used in the calendar.
+
+Besides the time zone identifier, a time zone component must
+contain at least one `icalendar-standard' or `icalendar-daylight'
+subcomponent, which describe the observance of standard or
+daylight time in the time zone, including the dates of the
+observance and the relevant offsets from UTC time."
+  :child-spec (:one (ical:tzid)
+               :zero-or-one (ical:last-modified
+                             ical:tzurl)
+               :zero-or-more (ical:standard
+                              ical:daylight
+                              ical:other-property))
+  :other-validator ical:vtimezone-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.5")
+
+(defun ical:vtimezone-validator (node)
+  "Additional validator for an `icalendar-vtimezone' NODE.
+Checks that NODE has at least one `icalendar-standard' or
+`icalendar-daylight' child.
+
+This function is called by `icalendar-ast-node-valid-p' for
+VTIMEZONE nodes; it is not normally necessary to call it directly."
+  (let ((child-counts (ical:count-children-by-type node)))
+    (when (and (= 0 (alist-get 'ical:standard child-counts 0))
+               (= 0 (alist-get 'ical:daylight child-counts 0)))
+      (ical:signal-validation-error
+       (concat "`icalendar-vtimezone' must have at least one "
+               "`icalendar-standard' or `icalendar-daylight' child")
+       :node node)))
+
+  ;; success:
+  node)
+
+(ical:define-component ical:standard "STANDARD"
+  "Represents a Standard Time observance in a time zone.
+
+The observance has a start time, specified by an
+`icalendar-dtstart' property, which is required in this component
+and must be in *local* time format.  The observance may have a
+recurring onset (e.g. each year on a particular day or date)
+described by the `icalendar-rrule' and `icalendar-rdate'
+properties.  An end date for the observance, if there is one, must
+be specified in the UNTIL clause of the `icalendar-rrule' in UTC
+time.
+
+The offset from UTC time when the observance begins is specified
+in the `icalendar-tzoffsetfrom' property, which is required.  The
+offset from UTC time while the observance is in effect is
+specified by the `icalendar-tzoffsetto' property, which is also
+required.  A common identifier for the time zone observance can be
+specified in the `icalendar-tzname' property.  Other explanatory
+comments can be provided in `icalendar-comment'.
+
+This component must be a direct child of an `icalendar-vtimezone'
+component and cannot contain other subcomponents."
+  :child-spec (:one (ical:dtstart
+                     ical:tzoffsetto
+                     ical:tzoffsetfrom)
+               :zero-or-one (ical:rrule)
+               :zero-or-more (ical:comment
+                              ical:rdate
+                              ical:tzname
+                              ical:other-property)
+               :other-validator ical:rrule-validator)
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.5")
+
+(ical:define-component ical:daylight "DAYLIGHT"
+  "Represents a Daylight Savings Time observance in a time zone.
+
+The observance has a start time, specified by an
+`icalendar-dtstart' property, which is required in this component
+and must be in *local* time format.  The observance may have a
+recurring onset (e.g. each year on a particular day or date)
+described by the `icalendar-rrule' and `icalendar-rdate'
+properties.  An end date for the observance, if there is one, must
+be specified in the UNTIL clause of the `icalendar-rrule' in UTC
+time.
+
+The offset from UTC time when the observance begins is specified
+in the `icalendar-tzoffsetfrom' property, which is required.  The
+offset from UTC time while the observance is in effect is
+specified by the `icalendar-tzoffsetto' property, which is also
+required.  A common identifier for the time zone observance can be
+specified in the `icalendar-tzname' property.  Other
+explanatory comments can be provided in `icalendar-comment'.
+
+This component must be a direct child of an `icalendar-vtimezone'
+component and cannot contain other subcomponents."
+  :child-spec (:one (ical:dtstart
+                     ical:tzoffsetto
+                     ical:tzoffsetfrom)
+               :zero-or-one (ical:rrule)
+               :zero-or-more (ical:comment
+                              ical:rdate
+                              ical:tzname
+                              ical:other-property)
+               :other-validator ical:rrule-validator)
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.5")
+
+(ical:define-component ical:valarm "VALARM"
+  "Represents an alarm.
+
+An alarm is a notification or reminder for an event or task.  The
+type of notification is determined by this component's
+`icalendar-action' property: it may be an AUDIO, DISPLAY, or
+EMAIL notification.
+If it is an audio alarm, it can include an
+`icalendar-attach' property specifying the audio to be rendered.
+If it is a DISPLAY alarm, it must include an `icalendar-description'
+property containing the text to be displayed.
+If it is an EMAIL alarm, it must include both an
+`icalendar-summary' and an `icalendar-description', which specify
+the subject and body of the email, and one or more
+`icalendar-attendee' properties, which specify the recipients.
+
+The required `icalendar-trigger' property specifies when the
+alarm triggers.  If the alarm repeats, then `icalendar-duration'
+and `icalendar-repeat' properties are also both required.
+
+This component must occur as a direct child of an
+`icalendar-vevent' or `icalendar-vtodo' component, and cannot
+contain any subcomponents."
+  :child-spec (:one (ical:action ical:trigger)
+               :zero-or-one (ical:duration ical:repeat)
+               :zero-or-more (ical:summary
+                              ical:description
+                              ical:attendee
+                              ical:attach
+                              ical:other-property))
+  :other-validator ical:valarm-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6.6")
+
+(defun ical:valarm-validator (node)
+  "Additional validator function for `icalendar-valarm' components.
+Checks that NODE has the right properties corresponding to its
+`icalendar-action' type, e.g., that an EMAIL alarm has a
+subject (`icalendar-summary') and recipients (`icalendar-attendee').
+
+This function is called by `icalendar-ast-node-valid-p' for
+VALARM nodes; it is not normally necessary to call it directly."
+  (let* ((action (ical:ast-node-first-child-of 'ical:action node))
+         (duration (ical:ast-node-first-child-of 'ical:duration node))
+         (repeat (ical:ast-node-first-child-of 'ical:repeat node))
+         (child-counts (ical:count-children-by-type node)))
+
+    (when (and duration (not repeat))
+      (ical:signal-validation-error
+       (concat "`icalendar-valarm' node with `icalendar-duration' "
+               "must also have `icalendar-repeat' property")
+       :node node))
+
+    (when (and repeat (not duration))
+      (ical:signal-validation-error
+       (concat "`icalendar-valarm' node with `icalendar-repeat' "
+               "must also have `icalendar-duration' property")
+       :node node))
+
+    (let ((action-str (upcase (ical:text-to-string
+                               (ical:ast-node-value action)))))
+      (cond ((equal "AUDIO" action-str)
+             (unless (<= (alist-get 'ical:attach child-counts 0) 1)
+               (ical:signal-validation-error
+                (concat "AUDIO `icalendar-valarm' may not have "
+                        "more than one `icalendar-attach'")
+                :node node))
+             node)
+
+            ((equal "DISPLAY" action-str)
+             (unless (= 1 (alist-get 'ical:description child-counts 0))
+               (ical:signal-validation-error
+                (concat "DISPLAY `icalendar-valarm' must have "
+                        "exactly one `icalendar-description'")
+                :node node))
+             node)
+
+            ((equal "EMAIL" action-str)
+             (unless (= 1 (alist-get 'ical:summary child-counts 0))
+               (ical:signal-validation-error
+                (concat "EMAIL `icalendar-valarm' must have "
+                        "exactly one `icalendar-summary'")
+                :node node))
+             (unless (= 1 (alist-get 'ical:description child-counts 0))
+               (ical:signal-validation-error
+                (concat "EMAIL `icalendar-valarm' must have "
+                        "exactly one `icalendar-description'")
+                :node node))
+             (unless (<= 1 (alist-get 'ical:attendee child-counts 0))
+               (ical:signal-validation-error
+                (concat "EMAIL `icalendar-valarm' must have "
+                        "at least one `icalendar-attendee'")
+                :node node))
+             node)
+
+            (t
+             ;; "Applications MUST ignore alarms with x-name and iana-token
+             ;; values they don't recognize." So this is not a validation-error:
+             (ical:warn
+              (format "Unknown ACTION value in VALARM: %s" action-str)
+              :buffer (ical:ast-node-meta-get node :buffer)
+              :position (ical:ast-node-meta-get node :value-begin))
+             node)))))
+
+(ical:define-component ical:other-component nil
+  "Component type for unrecognized component names.
+
+This component type corresponds to the IANA and X-name components
+allowed by RFC5545 sec. 3.6; it represents components with an
+unknown name (matching rx `icalendar-iana-token' or
+`icalendar-x-name') which must be parsed and preserved but not
+further interpreted."
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.6")
+
+;; Technically VCALENDAR is not a "component", but for the
+;; purposes of parsing and syntax highlighting, it looks just like
+;; one, so we define it as such here.
+;; (If this becomes a problem, modify `ical:component-node-p'
+;; to return nil for VCALENDAR components.)
+(ical:define-component ical:vcalendar "VCALENDAR"
+  "Calendar Object.
+
+This is the top-level data structure defined by RFC5545.  A
+VCALENDAR must contain the calendar properties `icalendar-prodid'
+and `icalendar-version', and may contain the calendar properties
+`icalendar-method' and `icalendar-calscale'.
+
+It must also contain at least one VEVENT, VTODO, VJOURNAL,
+VFREEBUSY, or other component, and for every unique
+`icalendar-tzidparam' value appearing in a property within these
+components, the calendar object must contain an
+`icalendar-vtimezone' defining a time zone with that TZID."
+  :child-spec (:one (ical:prodid ical:version)
+               :zero-or-one (ical:calscale ical:method)
+               :zero-or-more (ical:other-property
+                              ical:vevent
+                              ical:vtodo
+                              ical:vjournal
+                              ical:vfreebusy
+                              ical:vtimezone
+                              ical:other-component))
+  :other-validator ical:vcalendar-validator
+  :link "https://www.rfc-editor.org/rfc/rfc5545#section-3.4")
+
+(defun ical:all-tzidparams-in (node)
+  "Recursively find all `icalendar-tzidparam' values in NODE and its children."
+  (cond ((ical:tzid-param-p node)
+         (list (ical:ast-node-value node)))
+        ((ical:param-node-p node)
+         nil)
+        (t ;; TODO: could prune search here when properties don't allow tzidparam
+         (seq-uniq (mapcan #'ical:all-tzidparams-in
+                           (ical:ast-node-children node))))))
+
+(defun ical:vcalendar-validator (node)
+  "Additional validator for `icalendar-vcalendar' NODE.
+
+Checks that NODE has at least one component child and that all of the
+`ical-tzidparam' values appearing in subcomponents have a corresponding
+`icalendar-vtimezone' definition.
+
+This function is called by `icalendar-ast-node-valid-p' for
+VCALENDAR nodes; it is not normally necessary to call it directly."
+  (let* ((children (ical:ast-node-children node))
+         (comp-children (seq-filter #'ical:component-node-p children))
+         (tz-children (seq-filter #'ical:vtimezone-component-p children))
+         (defined-tzs
+          (mapcar
+           (lambda (tz)
+             ;; ensure vtimezone component has a TZID property and
+             ;; extract its string value:
+             (when (ical:ast-node-valid-p tz)
+               (ical:with-component tz ((ical:tzid :value-node tzid-text))
+                 (ical:text-to-string tzid-text))))
+           tz-children))
+         (appearing-tzids (ical:all-tzidparams-in node)))
+    (unless comp-children
+      (ical:signal-validation-error
+       "`icalendar-vcalendar' must contain at least one component"
+       :node node))
+
+    (let ((seen nil))
+      (dolist (tzid appearing-tzids)
+        (unless (member tzid seen)
+          (unless (member tzid defined-tzs)
+            (ical:signal-validation-error
+             (format "No `icalendar-vtimezone' with TZID '%s' in calendar" tzid)
+             :node node)))
+        (push tzid seen)))
+
+    ;; success:
+    node))
+
+(defun ical:contains-vcalendar-p (&optional buffer)
+  "Determine whether BUFFER contains \"BEGIN:VCALENDAR\".
+
+If so, then BUFFER is a candidate for parsing with, e.g.,
+`icalendar-parse-calendar'.  BUFFER defaults to the current
+buffer.  Returns the position where parsing should start, or nil."
+  (with-current-buffer (or buffer (current-buffer))
+    (save-excursion
+      (goto-char (point-min))
+      (when (re-search-forward "^BEGIN:VCALENDAR" nil t)
+        (beginning-of-line)
+        (point)))))
+
+;; `icalendar-parse-component' is sufficient to parse all the syntax in
+;; a calendar, but a calendar-level parsing function is needed to add
+;; support for time zones.  This function ensures that every
+;; `icalendar-tzidparam' in the calendar has a corresponding
+;; `icalendar-vtimezone' component, and modifies the zone information of
+;; the parsed date-time according to the offset in that time zone.
+(defun ical:parse-calendar (limit)
+  "Parse an `icalendar-vcalendar' object from point up to LIMIT.
+Point should be at the start of the calendar object, i.e., at the start
+of a line that looks like \"BEGIN:VCALENDAR\".  After parsing, point is
+at the beginning of the next line following the calendar (or end of the
+buffer).  Returns a syntax node representing the calendar."
+  (require 'icalendar-recur) ; for icr:tz-set-zones-in; avoids circular require
+  (declare-function icr:tz-set-zones-in "icalendar-recur")
+  (unless (looking-at-p "^BEGIN:VCALENDAR")
+    (ical:signal-parse-error "Not at start of VCALENDAR"))
+  (let ((cal-node (ical:parse-component limit)))
+      ;(when (ical:ast-node-valid-p cal-node t)
+      (ical:with-component cal-node
+          ((ical:vtimezone :all tzs))
+        ;; After parsing the whole calendar, set the zone and dst slots
+        ;; in all date-times which are relative to a time zone defined
+        ;; in the calendar:
+        ;; (TODO: if this proves too slow in general, we could instead
+        ;; do it lazily when individual components are queried somehow.
+        ;; But I'm not convinced that will actually save any time, because
+        ;; if we're parsing, we're probably already in the middle of a
+        ;; function that will immediately query all these times, e.g.
+        ;; `diary-icalendar-import-buffer'.)
+        (dolist (comp (ical:ast-node-children cal-node))
+          (unless (ical:vtimezone-component-p comp)
+            (icr:tz-set-zones-in tzs comp))));)
+      cal-node))
+
+;; TODO: should we do anything to *create* VTIMEZONE nodes in VCALENDAR
+;; when they're required but don't exist?
+(defun ical:print-calendar-node (vcalendar)
+  "Serialize an `icalendar-vcalendar' VCALENDAR to a string.
+
+If VCALENDAR is not a valid `icalendar-vcalendar', an
+`icalendar-validation-error' will be signaled.  Any errors that arise
+during printing will be logged in the buffer returned by
+`icalendar-error-buffer'."
+  (when (ical:ast-node-valid-p vcalendar t)
+    (condition-case err
+        (ical:print-component-node vcalendar)
+      (ical:print-error
+       (ical:handle-print-error err)))))
+
+
+;;; High-level parsing and printing functions.
+(defun ical:parse (&optional buffer)
+  "Parse an `icalendar-vcalendar' object in BUFFER (default: current buffer).
+
+An unfolded copy of BUFFER (see `icalendar-unfolded-buffer-from-buffer')
+will first be obtained if necessary.  Parsing will begin at the first
+occurrence of \"BEGIN:VCALENDAR\" in the unfolded buffer.
+
+The buffer may be tidied up by user functions before parsing begins; see
+`icalendar-pre-unfolding-hook' and `icalendar-pre-parsing-hook'.
+
+If parsing is successful, the VCALENDAR object is returned.  Otherwise,
+nil is returned, a warning is issued, and errors are logged in the
+buffer returned by `icalendar-error-buffer'."
+  (let* ((buf (or buffer (current-buffer)))
+         (unfolded (cond ((ical:unfolded-p buf) buf)
+                         ((buffer-file-name buf)
+                          (ical:unfolded-buffer-from-file (buffer-file-name buf)))
+                         (t (ical:unfolded-buffer-from-buffer buf)))))
+    (ical:init-error-buffer)
+    (with-current-buffer unfolded
+      (run-hooks 'ical:pre-parsing-hook)
+      (let ((cal-start (ical:contains-vcalendar-p))
+            vcalendar)
+        (unless cal-start
+          (ical:signal-parse-error "Buffer does not contain \"BEGIN:VCALENDAR\""))
+        (save-excursion
+          (goto-char cal-start)
+          (ical:condition-case err
+              (setq vcalendar (ical:parse-calendar (point-max)))
+            (ical:parse-error
+             (ical:handle-parse-error err)
+             (warn "Errors while parsing %s; see buffer %s"
+                   buffer (buffer-name (ical:error-buffer))))))
+        vcalendar))))
+
+;; TODO: The function `ical:print' below is not really useful yet.
+;; Feels like it's needed for completeness but interface needs more thought.
+;; Should this instead be a generic function that prints any
+;; kind of node at point? at a given marker?
+;; What about the coding system?  If we want to use this function to print
+;; iCalendar data to stdout, need to set up coding system correctly and
+;; perform line folding.
+;; Etc.
+;;
+;; (defun ical:print (vcalendar &optional buffer pos)
+;;   "Insert VCALENDAR as a string at position POS in BUFFER.
+;;
+;; VCALENDAR should be an `icalendar-vcalendar'.  BUFFER defaults to the
+;; current buffer and POS defaults to point.
+;;
+;; If printing is successful, VCALENDAR is returned.  Otherwise, nil is
+;; returned, a warning is issued, and errors are logged in the buffer
+;; returned by `icalendar-error-buffer'."
+;;   (with-current-buffer (or buffer (current-buffer))
+;;     (when pos (goto-char pos))
+;;     (condition-case err
+;;         (insert (ical:print-calendar-node vcalendar))
+;;       (ical:print-error
+;;        (ical:handle-print-error err)
+;;        (setq vcalendar nil) ; return
+;;        (warn "Errors while printing; see buffer %s"
+;;              (buffer-name (ical:error-buffer)))))
+;;     vcalendar))
+
+
+;;; Pre-parsing cleanup
+;;
+;; The following functions are based on observed syntax errors in
+;; real-world data and can help clean up such data before parsing.
+;; More functions can be added here based on user feedback.
+(defcustom ical:pre-parsing-hook nil
+  "Hook run by `icalendar-parse' before parsing iCalendar data.
+
+If you routinely receive iCalendar data in an incorrect format, you can
+add functions to this hook which clean up that data before parsing is
+attempted.  The functions in this hook will be run after the iCalendar
+data has been \"unfolded\" but before parsing begins.  (If you need to
+clean up data before unfolding happens, see
+`icalendar-pre-unfolding-hook'.)
+
+Each function should accept zero arguments and should perform its
+operation on the entire current buffer."
+  :version "31.1"
+  :type '(hook)
+  :options '(ical:fix-blank-lines
+             ical:fix-hyphenated-dates
+             ical:fix-missing-mailtos))
+
+(defun ical:fix-blank-lines ()
+  "Remove blank lines.
+This function is intended to be used from `icalendar-pre-parsing-hook',
+which see."
+  (goto-char (point-min))
+  (while (re-search-forward (rx "\n" (zero-or-more space) line-end)
+                            nil t)
+    (replace-match "" nil nil)))
+
+(defun ical:fix-hyphenated-dates ()
+  "Correct dates in \"YYYY-MM-DD...\" format to \"YYYYMMDD...\" format.
+This function is intended to be used from `icalendar-pre-parsing-hook',
+which see."
+  (goto-char (point-min))
+  (while (re-search-forward
+          (rx line-start
+              (or "COMPLETED" "DTEND" "DUE" "DTSTART" "RECURRENCE-ID"
+                  "EXDATE" "RDATE" "CREATED" "DTSTAMP" "LAST-MODIFIED")
+              (zero-or-more ical:other-param-safe)
+              ":")
+          nil t)
+    (unless (looking-at-p (rx (or ical:date ical:date-time)))
+      (while (re-search-forward ; exdate, rdate allow lists
+              (rx (group-n 1 (= 4 digit))
+                  "-"
+                  (group-n 2 (= 2 digit))
+                  "-"
+                  (group-n 3 (= 2 digit)))
+              (line-end-position) t)
+      (replace-match "\\1\\2\\3" nil nil)))))
+
+(defun ical:fix-missing-mailtos ()
+  "Insert \"mailto:\" when it is missing before email addresses.
+This function is intended to be used from `icalendar-pre-parsing-hook',
+which see."
+  ;; fix property values in properties that require an address:
+  (goto-char (point-min))
+  (while (re-search-forward
+          (rx line-start (or "ORGANIZER" "ATTENDEE")
+              (zero-or-more ical:other-param-safe) ":")
+          nil t)
+   (unless (looking-at-p (rx ical:cal-address))
+     (when (looking-at
+            (rx
+             ;; match local part of mail address: all the characters
+             ;; allowed after a URI scheme, *except*
+             ;; ?@ (so we can match that after) and
+             ;; ?: (in case we're looking at a non-"mailto:" scheme)
+             (group-n 1
+               (one-or-more
+                (any "A-Za-z0-9" ?- ?. ?_ ?~ ?/ ?? ?# ?\[ ?\] ?! ?$ ?& ?'
+                     ?\( ?\) ?* ?+ ?, ?\; ?= ?%)))
+             "@"))
+       (when (or (< (length (match-string 0)) 7)
+                 (not (equal "mailto:"
+                             (substring (downcase (match-string 0)) 0 7))))
+         (replace-match "mailto:\\1" nil nil nil 1)))))
+
+  ;; fix parameter values in parameters that require an address:
+  (goto-char (point-min))
+  (while (re-search-forward
+          (rx line-start ical:name
+              (zero-or-more icalendar-other-param-safe)
+              ";"
+              (or "DELEGATED-FROM" "DELEGATED-TO" "MEMBER" "SENT-BY")
+              "=")
+          nil t)
+    (unless (looking-at-p (rx ical:cal-address))
+      (while ; DELEGATED* params accept lists
+          (looking-at
+           (rx
+            ?\" ; values of these params must always be quoted
+            (group-n 1 ; matches local part of mail address as above
+              (one-or-more
+               (any "A-Za-z0-9" ?- ?. ?_ ?~ ?/ ?? ?# ?\[ ?\] ?! ?$ ?& ?'
+                    ?\( ?\) ?* ?+ ?, ?= ?%)))
+            "@"
+            (zero-or-more (not ?\"))
+            ?\"
+            (zero-or-one ",")))
+        (when (or (< (length (match-string 1)) 7)
+                  (not (equal "mailto:"
+                              (substring (downcase (match-string 1)) 0 7))))
+          (replace-match "mailto:\\1" nil nil nil 1))
+        (goto-char (match-end 0))))))
+
+
+;;; Caching and indexing parse trees
+;;
+;; The following functions provide a simple in-memory cache and index
+;; for faster access to parsed iCalendar data by date, UID, and other
+;; fields of interest.  The index and parse tree are stored in a
+;; buffer-local variable of the parsed buffer and not recomputed if the
+;; buffer hasn't changed.  Most users of the library should just call
+;; `icalendar-parse-and-index' to get both the parse tree and a
+;; reference to the index, and get objects of interest from them
+;; with `icalendar-index-get'.
+(defun ical:make-index ()
+  "Create an empty index of iCalendar components."
+  (list :bydate (make-hash-table :test #'equal) ;; date => list of components
+        :byuid (make-hash-table :test #'equal)  ;; UID => component
+        :bytzid (make-hash-table :test #'equal) ;; tzid => vtimezone
+        :recurring (list))) ;; list of components
+
+(defun ical:index-insert-tz (index vtimezone)
+  "Insert VTIMEZONE into INDEX."
+  (ical:with-component vtimezone
+      ((ical:tzid :value tzid))
+    (let ((tzid-index (plist-get index :bytzid)))
+      (puthash tzid vtimezone tzid-index)
+      ;; Update and return the index:
+      (plist-put index :bytzid tzid-index))))
+
+
+(defun ical:index-insert (index component)
+  "Insert COMPONENT into INDEX."
+  (require 'icalendar-recur) ; avoid circular imports
+  (require 'icalendar-utils) ;
+  (declare-function icr:recurrences-to-count "icalendar-recur")
+  (declare-function ical:date/time-to-local "icalendar-utils")
+  (declare-function ical:date/time-to-date "icalendar-utils")
+  (declare-function ical:dates-until "icalendar-utils")
+
+  (ical:with-component component
+    ((ical:dtstart :first dtstart-node :value dtstart)
+     (ical:dtend :first dtend-node :value dtend)
+     (ical:due :value due)
+     (ical:duration :value duration)
+     (ical:rrule :value recur-value)
+     (ical:rdate :all rdate-nodes)
+     (ical:exdate :all exdate-nodes)
+     (ical:uid :value uid))
+    (let ((date-index (plist-get index :bydate))
+          (uid-index (plist-get index :byuid))
+          (tzid-index (plist-get index :bytzid))
+          (recurring (plist-get index :recurring))
+          (rdates
+           (mapcar #'ical:ast-node-value
+                   (apply #'append (mapcar #'ical:ast-node-value rdate-nodes))))
+          (exdates
+           (mapcar #'ical:ast-node-value
+                   (apply #'append (mapcar #'ical:ast-node-value exdate-nodes))))
+          dates)
+      ;; Everything with a UID goes into the uid-index:
+      (when uid
+        (puthash uid component uid-index))
+      ;; For all top-level components, we gather a list of dates on which
+      ;; they recur for date-index, or put them in the recurring list:
+      (when dtstart
+        (cond
+         ;; If the component has an RRULE that specifies a fixed number
+         ;; of recurrences, compute them now and index them for each date
+         ;; in each recurrence:
+         ((and recur-value (ical:recur-count recur-value))
+          (let* ((tz (gethash (ical:with-param-of dtstart-node 'ical:tzidparam)
+                              tzid-index))
+                 (recs (cons dtstart (icr:recurrences-to-count component tz))))
+            (dolist (rec recs)
+              (let ((end-time
+                     (when duration (ical:date/time-add-duration rec duration))))
+                (setq dates
+                      (append dates
+                              (if end-time (ical:dates-until rec end-time t)
+                                (list (ical:date/time-to-date
+                                       (ical:date/time-to-local rec))))))))))
+         ;; Same with RDATEs when there's no RRULE:
+         ((and rdates (not recur-value))
+          (dolist (rec (cons dtstart rdates))
+            (unless (or (cl-typep rec 'ical:period) (member rec exdates))
+              (let ((end-time
+                     (when duration
+                       (ical:date/time-add-duration rec duration))))
+                (setq dates
+                      (append dates
+                              (if end-time (ical:dates-until rec end-time t)
+                                (list (ical:date/time-to-date
+                                       (ical:date/time-to-local rec))))))))
+            (when (cl-typep rec 'ical:period)
+              (let* ((start (ical:period-start rec))
+                     (end (or (ical:period-end rec)
+                              (ical:date/time-add-duration
+                               start (ical:period-dur-value rec)))))
+                (setq dates (append dates (ical:dates-until start end t)))))))
+         ;; A non-recurring event also gets an index entry for each date
+         ;; until its end time:
+         ((not recur-value)
+          (let ((end-time
+                 (or dtend due
+                     (when duration
+                       (ical:date/time-add-duration dtstart duration)))))
+            (setq dates (if end-time (ical:dates-until dtstart end-time t)
+                          (list
+                           (ical:date/time-to-date
+                            (ical:date/time-to-local dtstart)))))))
+         ;; Otherwise, we put off the computation of recurrences until queried:
+         (t (push component recurring)))
+
+        (dolist (date (seq-uniq dates))
+          (let ((others (gethash date date-index)))
+            ;; TODO: wonder if we should normalize, and instead store UIDs
+            ;; in the date index, then look them up by UID when queried.
+            (puthash date (cons component others) date-index))))
+
+      ;; Return the updated index:
+      (setq index (plist-put index :byuid uid-index))
+      (setq index (plist-put index :bytzid tzid-index))
+      (setq index (plist-put index :bydate date-index))
+      (setq index (plist-put index :recurring recurring))
+      index)))
+
+(defun ical:index-populate-from-calendar (index vcalendar)
+  "Insert all components in VCALENDAR into INDEX."
+  (let* ((tzs (ical:ast-node-children-of 'ical:vtimezone vcalendar))
+         (vevents (ical:ast-node-children-of 'ical:vevent vcalendar))
+         (vjournals (ical:ast-node-children-of 'ical:vjournal vcalendar))
+         (vtodos (ical:ast-node-children-of 'ical:vtodo vcalendar))
+         ;; TODO: customizable selection? what about valarms?
+         (to-index (append vevents vjournals vtodos)))
+
+    ;; First insert the tzs, so that they're available when inserting
+    ;; the others by date:
+    (dolist (tz tzs)
+      (setq index (ical:index-insert-tz index tz)))
+
+    (dolist (component to-index)
+      (setq index (ical:index-insert index component)))
+    index))
+
+(cl-defun ical:index-get (index &rest args &key date uid tzid)
+  "Get an iCalendar component from INDEX by date, UID, or TZID.
+
+INDEX should be a reference to a parse tree index as returned by
+`icalendar-parse-and-index', which see.  The index can be queried by:
+
+:uid UID (string, see `icalendar-uid') - returns the component with that
+  UID.
+
+:tzid TZID (string, see `icalendar-tzid' and `icalendar-tzidparam') -
+  returns the `icalendar-vtimezone' component with that TZID.
+
+:date DT (an `icalendar-date', i.e. a list (M D Y)) - returns a list of
+  the components occurring (or recurring) on that date.
+
+Only one keyword argument can be queried at a time."
+  (require 'icalendar-recur) ; avoid circular imports
+  (require 'icalendar-utils) ;
+
+  (declare-function icr:find-interval "icalendar-recur")
+  (declare-function icr:recurrences-in-interval "icalendar-recur")
+  (declare-function ical:date/time-in-period-p "icalendar-utils")
+  (declare-function ical:date/time<= "icalendar-utils")
+  (declare-function ical:date/time< "icalendar-utils")
+  (declare-function ical:date/time-add-duration "icalendar-utils")
+
+  (when (length> args 2)
+    (error "Only one keyword argument can be queried"))
+  (cond (uid (gethash uid (plist-get index :byuid)))
+        (tzid (gethash tzid (plist-get index :bytzid)))
+        (date
+         (let ((computed (gethash date (plist-get index :bydate)))
+               (recurring (plist-get index :recurring)))
+           (dolist (component recurring)
+             (ical:with-component component
+                 ((ical:dtstart :first dtstart-node :value dtstart)
+                  (ical:rrule :value recur-value)
+                  (ical:rdate :all rdate-nodes)
+                  (ical:duration :value duration))
+               (unless (ical:date/time<= date dtstart)
+                 (let* ((tz (ical:with-param-of dtstart-node 'ical:tzidparam nil
+                              (gethash value (plist-get index :bytzid))))
+                        (int (icr:find-interval date dtstart recur-value tz))
+                        (recs (icr:recurrences-in-interval int component tz)))
+                   (catch 'found
+                     (dolist (rec recs)
+                       (let* ((local-rec (ical:date/time-to-local rec))
+                              (end
+                               (when duration
+                                 (ical:date/time-add-duration local-rec duration)))
+                              (rec-dates
+                               (if end (ical:dates-until local-rec end t)
+                                 (list (ical:date/time-to-date local-rec)))))
+                         (when (member date rec-dates)
+                           (push component computed)
+                           (throw 'found nil))))
+                     (dolist (node rdate-nodes)
+                       ;; normal RDATE recurrences have already been
+                       ;; checked above, but we check whether `date'
+                       ;; occurs in any RDATE period values here:
+                       (when (eq 'ical:period
+                                 (ical:value-type-from-params
+                                  (ical:ast-node-children node)))
+                         (let* ((tz
+                                 (ical:with-param-of node 'ical:tzidparam nil
+                                   (gethash value (plist-get index :bytzid)))))
+                           (ical:with-property node nil
+                             (dolist (period values)
+                               (when (ical:date/time-in-period-p date period tz)
+                                 (push component computed)
+                                 (throw 'found nil))))))))))))
+           computed))
+        (t (error "At least one of :uid, :tzid, or :date is required"))))
+
+;; Buffer local variable to cache the index and parse tree.
+;; Format: (TICKS VCALENDAR INDEX)
+;; TICKS is the value of (buffer-modified-tick) at last parse
+(defvar-local ical:-parsed-calendar-and-index '(0 nil nil))
+
+(defun ical:parse-and-index (&optional buffer-or-file)
+  "Parse and index the first iCalendar VCALENDAR object in BUFFER-OR-FILE.
+
+Returns a list (VCALENDAR INDEX), where VCALENDAR is the parsed
+`icalendar-vcalendar' syntax tree.  The index can then be queried to
+retrieve components from this calendar by UID, TZID, or date; see
+`icalendar-index-get'.
+
+BUFFER-OR-FILE may be a buffer or a string containing a filename; it
+defaults to the current buffer.  If it is a filename, an unfolded buffer
+containing its data will be found, or created if necessary (see
+`icalendar-unfolded-buffer-from-file').  The resulting buffer must
+contain an iCalendar VCALENDAR object, which will be parsed and indexed.
+
+The results of parsing and indexing are cached in buffer-local
+variables, and subsequent calls with the same BUFFER-OR-FILE will return
+the cached results as long as the buffer has not been modified in the
+meantime."
+  (let* ((buffer (cond ((null buffer-or-file) (current-buffer))
+                       ((bufferp buffer-or-file) buffer-or-file)
+                       ((and (stringp buffer-or-file)
+                             (file-exists-p buffer-or-file))
+                        (find-buffer-visiting buffer-or-file))))
+         (file-name (cond (buffer (buffer-file-name buffer))
+                          ((and (stringp buffer-or-file)
+                                (file-exists-p buffer-or-file))
+                           (expand-file-name buffer-or-file))))
+         (unfolded (cond ((and buffer (ical:unfolded-p buffer))
+                          buffer)
+                         (file-name
+                          (or (ical:find-unfolded-buffer-visiting file-name)
+                              (ical:unfolded-buffer-from-file file-name)))
+                         (buffer
+                          (ical:unfolded-buffer-from-buffer buffer))
+                         (t
+                          (error "Unable to get unfolded buffer for '%s'"
+                                 buffer-or-file)))))
+    (with-current-buffer unfolded
+      (when (ical:contains-vcalendar-p)
+        (if (eql (car ical:-parsed-calendar-and-index) (buffer-modified-tick))
+            (cdr ical:-parsed-calendar-and-index)
+          (message "Parsing and indexing iCalendar data in %s..." (buffer-name))
+          (let ((vcalendar (ical:parse)))
+            (when vcalendar
+              (setq ical:-parsed-calendar-and-index
+                    (list
+                     (buffer-modified-tick)
+                     vcalendar
+                     (ical:index-populate-from-calendar (ical:make-index)
+                                                         vcalendar)))
+              (message "Parsing and indexing iCalendar data in %s...Done."
+                       (buffer-name))
+              (cdr ical:-parsed-calendar-and-index))))))))
+
+
+
+;;; Documentation for all of the above via `describe-symbol':
+(defun ical:documented-symbol-p (sym)
+  "Return non-nil if SYM is a symbol with iCalendar documentation."
+  (or (get sym 'icalendar-type-documentation)
+      ;; grammatical categories defined with rx-define, but with no
+      ;; other special icalendar docs:
+      (and (get sym 'rx-definition)
+           (length> (symbol-name sym) 10)
+           (equal "icalendar-" (substring (symbol-name sym) 0 10)))))
+
+(defun ical:documentation (sym buf frame)
+  "iCalendar documentation backend for `describe-symbol-backends'."
+  (ignore buf frame) ; Silence the byte compiler
+  (with-help-window (help-buffer)
+    (with-current-buffer standard-output
+      (let* ((type-doc (get sym 'icalendar-type-documentation))
+             (link (get sym 'icalendar-link))
+             (rx-def (get sym 'rx-definition))
+             (rx-doc (when rx-def
+                       (with-output-to-string
+                         (pp rx-def))))
+             (value-rx-def (get sym 'ical:value-rx))
+             (value-rx-doc (when value-rx-def
+                             (with-output-to-string
+                               (pp value-rx-def))))
+             (values-rx-def (get sym 'ical:values-rx))
+             (values-rx-doc (when values-rx-def
+                             (with-output-to-string
+                               (pp values-rx-def))))
+
+             (full-doc
+              (concat
+               (when type-doc
+                 (format "`%s' is an iCalendar type:\n\n%s\n\n"
+                         sym type-doc))
+               (when link
+                 (format "For further information see\nURL `%s'\n\n" link))
+               ;; FIXME: this is probably better done in rx.el!
+               ;; TODO: could also generalize this to recursively
+               ;; search rx-def for any symbol that starts with "icalendar-"...
+               (when rx-def
+                 (format "`%s' is an iCalendar grammar category.
+Its `rx' definition is:\n\n%s%s%s"
+                         sym
+                         rx-doc
+                         (if value-rx-def
+                             (format "\nIndividual values must match:\n%s"
+                                      value-rx-doc)
+                           "")
+                         (if values-rx-def
+                             (format "\nLists of values must match:\n%s"
+                                      values-rx-doc)
+                           "")))
+               "\n")))
+
+        (insert full-doc)
+        full-doc))))
+
+
+(defconst ical:describe-symbol-backend
+  '(nil icalendar-documented-symbol-p icalendar-documentation)
+  "Entry for icalendar documentation in `describe-symbol-backends'.")
+
+(push ical:describe-symbol-backend describe-symbol-backends)
+
+;; Unloading:
+(defun ical:parser-unload-function ()
+  "Unload function for `icalendar-parser'."
+  (mapatoms
+   (lambda (sym)
+     (when (string-match "^icalendar-" (symbol-name sym))
+       (makunbound sym)
+       (fmakunbound sym))))
+
+  (setq describe-symbol-backends
+        (remq ical:describe-symbol-backend describe-symbol-backends))
+  ;; Proceed with normal unloading:
+  nil)
+
+(provide 'icalendar-parser)
+
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-") ("icr:" . "icalendar-recur-"))
+;; End:
+;;; icalendar-parser.el ends here
diff --git a/lisp/calendar/icalendar-recur.el b/lisp/calendar/icalendar-recur.el
new file mode 100644
index 00000000000..28a05aacf7c
--- /dev/null
+++ b/lisp/calendar/icalendar-recur.el
@@ -0,0 +1,2148 @@
+;;; icalendar-recur.el --- Support for iCalendar recurrences and time zones -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024 Richard Lawrence
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: December 2024
+;; Keywords: calendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This is a sub-library for working with recurrence rules and time
+;; zones, as defined by RFC5545 (see especially Secs. 3.3.10 and
+;; 3.8.5.3, which are required reading before you make any changes to
+;; the code below) and related standards (especially RFC8984 Sec. 4.3,
+;; also strongly recommended reading).  Recurrence rules and time zones
+;; are mutually dependent: to calculate the date and time of future
+;; instances of a recurring event, you must be able to apply time zone
+;; rules; and to apply time zone rules, you must be able to calculate
+;; the date and time of recurring events, namely the shifts between
+;; observances of standard and daylight savings time.  For example, an
+;; event that occurs "on the last Friday of every month at 11AM" in a
+;; given time zone should recur at 11AM daylight savings time in July,
+;; but 11AM standard time in January, for a typical time zone that
+;; shifts from standard to DST and back once each year.  These shifts
+;; occur at, say, "the last Sunday in March at 2AM" and "the first
+;; Sunday in November at 2AM".  So to calculate an absolute time for a
+;; given instance of the original event, you first have to calculate the
+;; nearest instance of the shift between standard and daylight savings
+;; time, which itself involves applying a recurrence rule of the same
+;; form.
+;;
+;; This mutual dependence between recurrence rules and time zones is not
+;; a *vicious* circle, because the shifts between time zone observances
+;; have fixed offsets from UTC time which are made explicit in iCalendar
+;; data.  But it does make things complicated.  RFC5545 focuses on making
+;; recurrence rules expressive enough to cover existing practices,
+;; including time zone observance shifts, rather than on being easy to
+;; implement.
+;;
+;; So be forewarned: here be dragons.  The code here was difficult to get
+;; working, in part because this mutual dependence means it is difficult
+;; to implement anything less than the whole system, in part because
+;; recurrence rules are very flexible in order to cover as many
+;; practical uses as possible, in part because time zone practices are
+;; themselves complicated, and in part because there are a *lot* of edge
+;; cases to worry about.  Much of it is tedious and repetitive but
+;; doesn't lend itself to further simplification or abstraction.  If you
+;; need to make changes, make them slowly, and use the tests in
+;; test/lisp/calendar/icalendar-recur-tests.el to make sure they don't
+;; break anything.
+;;
+;; Notation: `date/time' with a slash in symbol names means "`date' or
+;; `date-time'", i.e., is a way of indicating that a function can
+;; accept either type of value, and `dt' is typically used for an
+;; argument of either type.  `date-time' should always refer to *just*
+;; date-time values, not plain (calendar-style) dates.
+
+;;; Code:
+(require 'icalendar-ast)
+(require 'icalendar-parser)
+(require 'icalendar-utils)
+(require 'cl-lib)
+(require 'calendar)
+(require 'cal-dst)
+(require 'simple)
+(require 'seq)
+(eval-when-compile '(require 'icalendar-macs))
+
+
+;; Recurrence Intervals
+;;
+;; Two important ideas in the following:
+;;
+;; 1) Because recurrence sets are potentially infinite, we always
+;; calculate recurrences within certain upper and lower bounds.  These
+;; bounds might be determined by a user interface (e.g. the week or
+;; month displayed in a calendar) or might be derived from the logic of
+;; the recurrence rule itself.  In the former case, where the bounds can
+;; be arbitrary, it's called a 'window' here (as in "window of
+;; time").  In the latter case, it's called an 'interval' here (after the
+;; "INTERVAL=..." clause in recurrence rules).
+;;
+;; Unlike a window, an interval must be synced up with the recurrence
+;; rule: its bounds must fall at successive integer multiples of the
+;; product of the recurrence rule's FREQ and INTERVAL values, relative
+;; to a starting date/time.  For example, a recurrence rule with a
+;; MONTHLY frequency and INTERVAL=3 will have an interval that is three
+;; months long.  If its start date is, e.g., in November, then the first
+;; interval runs from November to February, the next from February to
+;; May, and so on.  Because intervals depend only on the starting
+;; date/time, the frequency, and the interval length, it is relatively
+;; straightforward to compute the bounds of the interval surrounding an
+;; arbitrary point in time (without enumerating them successively from
+;; the start time); see `icalendar-recur-find-interval', which calls
+;; this arbitrary point in time the 'target'.
+;;
+;; 2) An interval is the smallest unit of time for which we compute
+;; values of the recurrence set.  This is because the "BYSETPOS=..."
+;; clause in a recurrence rule operates on the sequence of recurrences
+;; in a single interval.  Since it selects recurrences by their index in
+;; this sequence, the sequence must have a determinate length and known
+;; bounds.  The function `icalendar-recur-recurrences-in-interval' is the
+;; main function to compute recurrences in a given interval.
+;;
+;; The way to compute the recurrences in an arbitrary *window* is thus
+;; to find the interval bounds which are closest to the window's lower
+;; and upper bound, and then compute the recurrences for all the
+;; intervals in between, i.e., that "cover" the window.  This is what the
+;; function `icalendar-recur-recurrences-in-window' does.
+;;
+;; Note that the recurrence set for a recurrence rule with a COUNT
+;; clause cannot be computed for an arbitrary interval (or window);
+;; instead, the set must be enumerated from the beginning, so that the
+;; enumeration can stop after a fixed number of recurrences.  This is
+;; what the function `icalendar-recur-recurrences-to-count' does.  But
+;; also in this case, recurrences are generated for one interval at a
+;; time, because a BYSETPOS clause might apply.
+;;
+;; An interval is represented as a list (LOW HIGH NEXT-LOW) of decoded
+;; times.  The length of time between LOW and HIGH corresponds to the
+;; FREQ rule part: they are one year apart for a 'YEARLY rule, a month
+;; apart for a 'MONTHLY rule, etc.  NEXT-LOW is the upper bound of the
+;; interval: it is equal to LOW in the subsequent interval.  When the
+;; INTERVAL rule part is equal to 1 (the default), HIGH and NEXT-LOW are
+;; the same, but if it is > 1, NEXT-LOW is equal to LOW + INTERVAL *
+;; FREQ.  For example, in a 'MONTHLY rule where INTERVAL=3, which means
+;; "every three months", LOW and HIGH bound the first month, while HIGH
+;; and NEXT-LOW bound the following two months.
+;;
+;; The times between LOW and HIGH are candidates for recurrences.  LOW
+;; is an inclusive lower bound, and HIGH is an exclusive upper bound:
+;; LOW <= R < HIGH for each recurrence R in the interval.  The times
+;; between HIGH and NEXT-LOW are not candidates for recurrences.
+;;
+;; The following functions deal with constructing intervals, given a
+;; target, a start date/time, and intervalsize, and optionally a time
+;; zone.  The main entry point is `icalendar-recur-find-interval'.
+
+;; Look, dragons already:
+(defun icr:find-absolute-interval (target dtstart intervalsize freqs
+                                   &optional vtimezone)
+  "Find a recurrence interval based on a fixed number of seconds.
+
+INTERVALSIZE should be the total size of the interval in seconds.  FREQS
+should be the number of seconds between the lower bound of the interval
+and the upper bound for candidate recurrences; it is the number of
+seconds in the unit of time in a recurrence rule's FREQ part.  The
+returned interval looks like (LOW LOW+FREQS LOW+INTERVALSIZE).  See
+`icalendar-recur-find-interval' for other arguments' meanings."
+  ;; We assume here that the interval needs to be calculated using
+  ;; absolute times for SECONDLY, MINUTELY, and HOURLY rules.
+  ;; There are two reasons for this:
+  ;;
+  ;; 1) Time zone shifts.  If we don't use absolute times, and instead
+  ;;    find interval boundaries using local clock times with e.g.
+  ;;    `ical:date/time-add' (as we do with time units of a day or
+  ;;    greater below), we have to adjust for clock time changes.  Using
+  ;;    absolute times is simpler.
+  ;; 2) More problematically, using local clock times, at least in its
+  ;;    most straightforward implementation, has pathological results
+  ;;    when `intervalsize' is relatively prime with 60 (for a SECONDLY
+  ;;    rule, similarly for the others): intervals generated by
+  ;;    successive enumeration from one target value will not in general
+  ;;    align with intervals generated from a different, but nearby,
+  ;;    target value.  (So going this route seems to mean giving up on
+  ;;    the idea that intervals can be calculated just from `target',
+  ;;    `dtstart' and `intervalsize', and instead always enumerating
+  ;;    them from the beginning.)
+  ;;
+  ;; In effect, we are deciding that a rule like "every 3 hours" always
+  ;; means every 3 * 60 * 60 = 10800 seconds after `dtstart', and not
+  ;; "every 10800 seconds, except when there's a time zone observance
+  ;; change".  People who want the latter have another option: use a
+  ;; DAILY rule and specify the (local) times for the hours they want in
+  ;; the BYHOUR clause, etc.  (People who want it for a number of hours,
+  ;; e.g. 7, which does not divide 24, unfortunately do *not* have this
+  ;; option, but anyone who wants that but does not want to understand
+  ;; "7 hours" as a fixed number of seconds has a pathology that I
+  ;; cannot cure here.)
+  ;;
+  ;; RFC5545 does not seem to pronounce one way or the other on whether
+  ;; this decision is correct: there are no examples of SECONDLY rules
+  ;; to go on, and the few examples for MINUTELY and HOURLY rules only
+  ;; use "nice" values in the INTERVAL clause (real-life examples
+  ;; probably(?)  will too).  Our assumption has some possibly
+  ;; unintuitive consequences for `intervalsize' values that are not
+  ;; "nice" (basically, whenever intervalsize and either 60 or 24 are
+  ;; relatively prime), and for how interval boundaries behave at the
+  ;; shifts between time zone observances (since local clock times in
+  ;; the interval bounds will shift from what they would have been
+  ;; before the observance change -- arguably correct but possibly
+  ;; surprising, depending on the case).  But the alternative seems
+  ;; worse, so until countervailing evidence emerges, this approach
+  ;; seems reasonable.
+  (let* ((given-start-zone (decoded-time-zone dtstart))
+         (start-w/zone (cond (given-start-zone dtstart)
+                             ((ical:vtimezone-component-p vtimezone)
+                              (ical:date-time-variant dtstart :tz vtimezone))
+                             (t
+                              ;; "Floating" time should be interpreted in user's
+                              ;; current time zone; see RFC5545 Sec 3.3.5
+                              (ical:date-time-variant
+                               dtstart :zone (car (current-time-zone))))))
+         (start-abs (ignore-errors
+                      (time-convert (encode-time start-w/zone) 'integer)))
+         (given-target-zone (decoded-time-zone target))
+         (target-w/zone (cond (given-target-zone target)
+                              (vtimezone
+                               (ical:date-time-variant target :tz vtimezone))
+                              (t
+                               (ical:date-time-variant
+                                target :zone (car (current-time-zone))))))
+         (target-abs (ignore-errors
+                         (time-convert (encode-time target-w/zone) 'integer)))
+         low-abs low high next-low)
+
+    (unless (zerop (mod intervalsize freqs))
+      ;; Bad things will happen if intervalsize is not an integer
+      ;; multiple of freqs
+      (error "FREQS=%d does not divide INTERVALSIZE=%d" freqs intervalsize))
+    (unless (and start-abs target-abs)
+      (when (not start-abs)
+        (error "Could not determine an offset for DTSTART=%s" dtstart))
+      (when (not target-abs)
+        (error "Could not determine an offset for TARGET=%s" target)))
+
+    ;; Find the lower bound below target that is the closest integer
+    ;; multiple of intervalsize seconds from dtstart
+    (setq low-abs (- target-abs
+                     (mod (- target-abs start-abs) intervalsize)))
+
+    (if vtimezone
+        (setq low (icr:tz-decode-time low-abs vtimezone)
+              high (icr:tz-decode-time (+ low-abs freqs) vtimezone)
+              next-low (icr:tz-decode-time (+ low-abs intervalsize) vtimezone))
+      ;; best we can do is decode into target's zone:
+      (let ((offset (decoded-time-zone target-w/zone)))
+        (setq low (icr:tz-decode-time low-abs offset)
+              high (icr:tz-decode-time (+ low-abs freqs) offset)
+              next-low (icr:tz-decode-time (+ low-abs intervalsize) offset))))
+
+    (unless (and given-start-zone given-target-zone)
+      ;; but if we started with floating times, we should return floating times:
+      (setf (decoded-time-zone low) nil)
+      (setf (decoded-time-dst low) -1)
+      (setf (decoded-time-zone high) nil)
+      (setf (decoded-time-dst high) -1)
+      (setf (decoded-time-zone next-low) nil)
+      (setf (decoded-time-dst next-low) -1))
+
+    (list low high next-low)))
+
+(defun icr:find-secondly-interval (target dtstart intervalsize &optional vtimezone)
+  "Find a SECONDLY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (icr:find-absolute-interval
+   target
+   dtstart
+   intervalsize
+   1
+   vtimezone))
+
+(defun icr:find-minutely-interval (target dtstart intervalsize &optional vtimezone)
+  "Find a MINUTELY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (icr:find-absolute-interval
+   target
+   ;; A MINUTELY interval always runs from the beginning of a minute to
+   ;; the beginning of the next minute:
+   (ical:date-time-variant dtstart :second 0 :tz 'preserve)
+   (* 60 intervalsize)
+   60
+   vtimezone))
+
+(defun icr:find-hourly-interval (target dtstart intervalsize &optional vtimezone)
+  "Find an HOURLY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (icr:find-absolute-interval
+   target
+   ;; An HOURLY interval always runs from the beginning of an hour to
+   ;; the beginning of the next hour:
+   (ical:date-time-variant dtstart :minute 0 :second 0 :tz 'preserve)
+   (* 60 60 intervalsize)
+   (* 60 60)
+   vtimezone))
+
+(defun icr:find-daily-interval (target dtstart intervalsize &optional vtimezone)
+  "Find a DAILY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (let* ((start-absdate (calendar-absolute-from-gregorian
+                         (ical:date/time-to-date dtstart)))
+         (target-absdate (calendar-absolute-from-gregorian
+                          (ical:date/time-to-date target)))
+         ;; low-absdate is the closest absolute date below target that
+         ;; is an integer multiple of intervalsize days from dtstart
+         (low-absdate (- target-absdate
+                         (mod (- target-absdate start-absdate) intervalsize)))
+         (high-absdate (1+ low-absdate))
+         (next-low-absdate (+ low-absdate intervalsize)))
+
+    (let* ((low-dt (ical:date-to-date-time
+                     (calendar-gregorian-from-absolute low-absdate)))
+           (high-dt (ical:date-to-date-time
+                      (calendar-gregorian-from-absolute high-absdate)))
+           (next-low-dt (ical:date-to-date-time
+                          (calendar-gregorian-from-absolute next-low-absdate))))
+
+      (when vtimezone
+        (icr:tz-set-zone low-dt vtimezone)
+        (icr:tz-set-zone high-dt vtimezone)
+        (icr:tz-set-zone next-low-dt vtimezone))
+
+      ;; Return the bounds:
+      (list low-dt high-dt next-low-dt))))
+
+(defun icr:find-weekly-interval (target dtstart intervalsize
+                                 &optional weekstart vtimezone)
+  "Find a WEEKLY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (let* ((target-date (ical:date/time-to-date target))
+         (start-date (ical:date/time-to-date dtstart))
+         ;; the absolute dates of the week start before target and
+         ;; dtstart; these are always a whole number of weeks apart:
+         (target-week-abs (calendar-nth-named-absday
+                           -1
+                           (or weekstart 1)
+                           (calendar-extract-month target-date)
+                           (calendar-extract-year target-date)
+                           (calendar-extract-day target-date)))
+         (start-abs (calendar-nth-named-absday
+                     -1
+                     (or weekstart 1)
+                     (calendar-extract-month start-date)
+                     (calendar-extract-year start-date)
+                     (calendar-extract-day start-date)))
+         (intsize-days (* 7 intervalsize))
+         ;; the absolute date of the week start before target which is
+         ;; an integer multiple of intervalsize weeks from dtstart:
+         (low-abs (- target-week-abs
+                  (mod (- target-week-abs start-abs) intsize-days)))
+         ;; then use this to find the interval bounds:
+         (low (ical:date-to-date-time
+               (calendar-gregorian-from-absolute low-abs)))
+         (high (ical:date-to-date-time
+               (calendar-gregorian-from-absolute (+ 7 low-abs))))
+         (next-low (ical:date-to-date-time
+                    (calendar-gregorian-from-absolute (+ intsize-days low-abs)))))
+
+    (when vtimezone
+      (icr:tz-set-zone low vtimezone)
+      (icr:tz-set-zone high vtimezone)
+      (icr:tz-set-zone next-low vtimezone))
+
+    ;; Return the bounds:
+    (list low high next-low)))
+
+(defun icr:find-monthly-interval (target dtstart intervalsize &optional vtimezone)
+  "Find a MONTHLY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (let* ((start-month (ical:date/time-month dtstart))
+         (start-year (ical:date/time-year dtstart))
+         ;; we calculate in "absolute months", i.e., number of months
+         ;; since the beginning of the Gregorian calendar, to make
+         ;; finding the lower bound easier:
+         (start-abs-months (+ (* 12 (1- start-year)) (1- start-month)))
+         (target-month (ical:date/time-month target))
+         (target-year (ical:date/time-year target))
+         (target-abs-months (+ (* 12 (1- target-year)) (1- target-month)))
+         ;; number of "absolute months" between start of dtstart's month
+         ;; and start of target's month:
+         (nmonths (- target-abs-months start-abs-months))
+         ;; the number of months after dtstart that is the closest integer
+         ;; multiple of intervalsize months before target:
+         (lmonths (- nmonths (mod nmonths intervalsize)))
+         ;; convert these "absolute months" back to Gregorian month and year:
+         (mod-month (mod (+ start-month lmonths) 12))
+         (low-month (if (zerop mod-month) 12 mod-month))
+         (low-year (+ (/ lmonths 12) start-year
+                      ;; iff we cross a year boundary moving forward in
+                      ;; time from start-month to target-month, we need
+                      ;; to add one to the year:
+                      (if (<= start-month target-month) 0 1)))
+         ;; and now we can use these to calculate the interval bounds:
+         (low (ical:make-date-time :year low-year :month low-month :day 1
+                                   :hour 0 :minute 0 :second 0 :tz vtimezone))
+         (high (ical:date/time-add low :month 1 vtimezone))
+         (next-low (ical:date/time-add low :month intervalsize vtimezone)))
+
+    ;; Return the bounds:
+    (list low high next-low)))
+
+(defun icr:find-yearly-interval (target dtstart intervalsize &optional vtimezone)
+  "Find a YEARLY recurrence interval.
+See `icalendar-recur-find-interval' for arguments' meanings."
+  (let* ((start-year (ical:date/time-year dtstart))
+         (target-year (ical:date/time-year target))
+         ;; The year before target that is the closest integer multiple
+         ;; of intervalsize years after dtstart:
+         (low-year (- target-year
+                      (mod (- target-year start-year) intervalsize)))
+         (low (ical:make-date-time :year low-year :month 1 :day 1
+                                   :hour 0 :minute 0 :second 0 :tz vtimezone))
+         (high (ical:make-date-time :year (1+ low-year) :month 1 :day 1
+                                    :hour 0 :minute 0 :second 0 :tz vtimezone))
+         (next-low (ical:make-date-time :year (+ low-year intervalsize)
+                                        :month 1 :day 1 :hour 0 :minute 0 :second 0
+                                        :tz vtimezone)))
+
+    ;; Return the bounds:
+    (list low high next-low)))
+
+(defun icr:find-interval (target dtstart recur-value &optional vtimezone)
+  "Return the recurrence interval around TARGET.
+
+TARGET and DTSTART should be `icalendar-date' or `icalendar-date-time'
+values.  RECUR-VALUE should be an `icalendar-recur'.
+
+The returned value is a list (LOW HIGH NEXT-LOW) which
+represents the lower and upper bounds of a recurrence interval around
+TARGET.  For some N, LOW is equal to START + N*INTERVALSIZE units, HIGH
+is equal to START + (N+1)*INTERVALSIZE units, and LOW <= TARGET < HIGH.
+START here is a time derived from DTSTART depending on RECUR-VALUE's
+FREQ part: the first day of the year for a \\='YEARLY rule, first day
+of the month for a \\='MONTHLY rule, etc.
+
+RECUR-VALUE's interval determines INTERVALSIZE, and its frequency
+determines the units: a month for \\='MONTHLY, etc.
+
+If VTIMEZONE is provided, it is used to set time zone information in the
+returned interval bounds.  Otherwise, the bounds contain no time zone
+information and represent floating local times."
+  (let ((freq (ical:recur-freq recur-value))
+        (intsize (ical:recur-interval-size recur-value))
+        (weekstart (ical:recur-weekstart recur-value)))
+    (cl-case freq
+      (SECONDLY (icr:find-secondly-interval target dtstart intsize vtimezone))
+      (MINUTELY (icr:find-minutely-interval target dtstart intsize vtimezone))
+      (HOURLY (icr:find-hourly-interval target dtstart intsize vtimezone))
+      (DAILY (icr:find-daily-interval target dtstart intsize vtimezone))
+      (WEEKLY (icr:find-weekly-interval target dtstart intsize
+                                        weekstart vtimezone))
+      (MONTHLY (icr:find-monthly-interval target dtstart intsize vtimezone))
+      (YEARLY (icr:find-yearly-interval target dtstart intsize vtimezone)))))
+
+(defun icr:nth-interval (n dtstart recur-value &optional vtimezone)
+  "Return the Nth recurrence interval after DTSTART.
+
+The returned value is a list (LOW HIGH NEXT-LOW) which represent the Nth
+recurrence interval after DTSTART.  LOW is equal to START +
+N*INTERVALSIZE units, HIGH is equal to START + (N+1)*INTERVALSIZE units,
+and LOW <= TARGET < HIGH.  START here is a time derived from DTSTART
+depending on RECUR-VALUE's FREQ part: the first day of the year for a
+\\='YEARLY rule, first day of the month for a \\='MONTHLY rule, etc.
+
+RECUR-VALUE's interval determines INTERVALSIZE, and its frequency
+determines the units: a month for \\='MONTHLY, etc.
+
+N should be a non-negative integer.  Interval 0 is the interval
+containing DTSTART.  DTSTART should be an `icalendar-date' or
+`icalendar-date-time' value.  RECUR-VALUE should be an
+`icalendar-recur'.
+
+If VTIMEZONE is provided, it is used to set time zone information in the
+returned interval bounds.  Otherwise, the bounds contain no time zone
+information and represent floating local times."
+  (when (< n 0) (error "Recurrence interval undefined for negative N"))
+  (let* ((start-dt (if (cl-typep dtstart 'ical:date)
+                       (ical:date-to-date-time dtstart :tz vtimezone)
+                     dtstart))
+         (freq (ical:recur-freq recur-value))
+         (intervalsize (ical:recur-interval-size recur-value))
+         (unit (cl-case freq
+                 (YEARLY :year)
+                 (MONTHLY :month)
+                 (WEEKLY :week)
+                 (DAILY :day)
+                 (HOURLY :hour)
+                 (MINUTELY :minute)
+                 (SECONDLY :second)))
+         (target (ical:date/time-add start-dt unit (* n intervalsize) vtimezone)))
+    (icr:find-interval target dtstart recur-value vtimezone)))
+
+(defun icr:next-interval (interval recur-value &optional vtimezone)
+  "Return the next recurrence interval after INTERVAL.
+
+Given a recurrence interval (LOW HIGH NEXT), returns the next interval
+\(NEXT HIGHER HIGHER-NEXT), where HIGHER and HIGHER-NEXT are determined
+by the frequency and interval sizes of RECUR-VALUE."
+  (let* ((new-low (caddr interval))
+         (freq (ical:recur-freq recur-value))
+         (unit (cl-case freq
+                 (YEARLY :year)
+                 (MONTHLY :month)
+                 (WEEKLY :week)
+                 (DAILY :day)
+                 (HOURLY :hour)
+                 (MINUTELY :minute)
+                 (SECONDLY :second)))
+         (intervalsize (ical:recur-interval-size recur-value))
+         (new-high (ical:date/time-add new-low unit 1 vtimezone))
+         (new-next (ical:date/time-add new-low unit intervalsize vtimezone)))
+
+    (when vtimezone
+      (icr:tz-set-zone new-low vtimezone)
+      ;; (icr:tz-set-zone new-high vtimezone)
+      ;; (icr:tz-set-zone new-next vtimezone)
+      )
+
+    (list new-low new-high new-next)))
+
+(defun icr:previous-interval (interval recur-value dtstart &optional vtimezone)
+  "Given a recurrence INTERVAL, return the previous interval.
+
+For an interval (LOW HIGH NEXT-LOW), the previous interval is
+\(PREV-LOW PREV-HIGH LOW), where PREV-LOW and PREV-HIGH are determined by
+the frequency and interval sizes of RECUR-VALUE (see
+`icalendar-recur-find-interval').  If the resulting period of time
+between PREV-LOW and PREV-HIGH occurs entirely before DTSTART, then the
+interval does not exist; in this case nil is returned."
+  (let* ((upper (car interval))
+         (freq (ical:recur-freq recur-value))
+         (unit (cl-case freq
+                 (YEARLY :year)
+                 (MONTHLY :month)
+                 (WEEKLY :week)
+                 (DAILY :day)
+                 (HOURLY :hour)
+                 (MINUTELY :minute)
+                 (SECONDLY :second)))
+         (intervalsize (ical:recur-interval-size recur-value))
+         (new-low (ical:date/time-add upper unit (* -1 intervalsize) vtimezone))
+         (new-high (ical:date/time-add new-low unit 1 vtimezone)))
+
+    (when vtimezone
+      ;; (icr:tz-set-zone new-low vtimezone)
+      ;; (icr:tz-set-zone new-high vtimezone)
+      (icr:tz-set-zone upper vtimezone))
+
+    (unless (ical:date-time< new-high dtstart)
+      (list new-low new-high upper))))
+
+
+
+;; Refining intervals into subintervals
+;;
+;; For a given interval, the various BY*=... clauses in a recurrence
+;; rule specify the recurrences in that interval.
+;;
+;; RFC5545 unfortunately has an overly-complicated conceptual model for
+;; how recurrences are to be calculated which is based on "expanding" or
+;; "limiting" the recurrence set for each successive clause.  This model
+;; is difficult to think about and implement, and the text of the
+;; standard is ambiguous.  I did not succeed in producing a working
+;; implementation based on the description in the standard, and the
+;; existing implementations don't seem to agree on how it's to be
+;; implemented anyway.
+;;
+;; Fortunately, RFC8984 (JSCalendar) is a forthcoming standard which
+;; attempts to resolve the ambiguities while being semantically
+;; backward-compatible with RFC5545.  It provides a much cleaner
+;; conceptual model: the recurrence set is generated by starting with a
+;; list of candidates, which consist of every second in (what is here
+;; called) an interval, and then filtering out any candidates which do
+;; not match the rule's clauses.  The most straightforward implementation
+;; of this model, however, is unusably slow in typical cases.  Consider
+;; for example the case of calculating the onset of daylight savings
+;; time in a given year: the interval is a year long, so it consists of
+;; over 31 million seconds.  Although it's easy to generate Lisp
+;; timestamps for each of those seconds, filtering them through the
+;; various BY* clauses means decoding each of those timestamps, which
+;; means doing a fairly expensive computation over 31 million times, and
+;; then throwing away the result in all but one case.  When I implemented
+;; this model, I was not patient enough to sit through the calculations
+;; for even MONTHLY rules (which on my laptop took minutes).
+;;
+;; So instead of implementing RFC8984's model directly, the strategy
+;; here is to do something equivalent but much more efficient: rather
+;; than thinking of an interval as consisting of a set of successive
+;; seconds, we think of it as described by its bounds; and for each BY*
+;; clause, we *refine* the interval into subintervals by computing the
+;; bounds of each subinterval corresponding to the value(s) in that
+;; clause.  For example, in a YEARLY rule, the initial interval is one
+;; year long, say all of 2025.  If it has a "BYMONTH=4,10" clause, then
+;; we refine this interval into two subintervals, each one month long:
+;; one for April 2025 and one for October 2025.  This is much more
+;; efficient in the typical case, because the number of bounds which
+;; describe the final set of subintervals is usually *much* smaller than
+;; the number of seconds in the original interval.
+;;
+;; The following functions are responsible for computing these
+;; refinements.  The main entry point here is
+;; `icalendar-recur-refine-from-clauses', which takes care of
+;; successively refining the interval both by the explicit values in the
+;; rule's clauses and by the implicit values in DTSTART.  (There, too,
+;; RFC8984 is helpful: it gives a much more explicit description of how
+;; the information in DTSTART interacts with the BY* clauses to further
+;; refine the subintervals.)
+
+(defun icr:refine-byyearday (interval yeardays &optional vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching YEARDAYS.
+
+YEARDAYS should be a list of values from a recurrence rule's
+BYYEARDAY=... clause; see `icalendar-recur' for the possible values."
+  (let* ((sorted-ydays (sort yeardays
+                             :lessp (lambda (a b)
+                                      (let ((pos-a (if (< 0 a) a (+ 366 a)))
+                                            (pos-b (if (< 0 b) b (+ 366 b))))
+                                        (< pos-a pos-b)))))
+         (interval-start (car interval))
+         (start-year (decoded-time-year interval-start))
+         (interval-end (cadr interval))
+         (end-year (decoded-time-year interval-end))
+         (subintervals nil))
+    (while (<= start-year end-year)
+      ;; For each year in the interval...
+      (dolist (n sorted-ydays)
+        ;; ...the subinterval is one day long on the nth yearday
+        (let* ((nthday (calendar-date-from-day-of-year start-year n))
+               (low (ical:make-date-time :year start-year
+                                         :month (calendar-extract-month nthday)
+                                         :day (calendar-extract-day nthday)
+                                         :hour 0 :minute 0 :second 0
+                                         :tz vtimezone))
+               (high (ical:date/time-add low :day 1 vtimezone)))
+          ;; "Clip" the subinterval bounds if they fall outside the
+          ;; interval.  Careful!  This clipping can lead to high <= low,
+          ;; so need to check it is still the case that low < high
+          ;; before pushing the subinterval
+          (when (ical:date/time< low interval-start)
+            (setq low interval-start))
+          (when (ical:date/time< interval-end high)
+            (setq high interval-end))
+          (when (and (ical:date-time<= interval-start low)
+                     (ical:date-time< low high)
+                     (ical:date-time<= high interval-end))
+            (push (list low high) subintervals))))
+
+      (setq start-year (1+ start-year)))
+    (nreverse subintervals)))
+
+(defun icr:refine-byweekno (interval weeknos &optional weekstart vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching WEEKNOS.
+
+WEEKNOS should be a list of values from a recurrence rule's
+BYWEEKNO=... clause, and WEEKSTART should be the value of its
+WKST=... clause (if any).  See `icalendar-recur' for the possible values."
+  (let* ((sorted-weeknos (sort weeknos
+                               :lessp (lambda (a b)
+                                        (let ((pos-a (if (< 0 a) a (+ 53 a)))
+                                              (pos-b (if (< 0 b) b (+ 53 b))))
+                                          (< pos-a pos-b)))))
+         (interval-start (car interval))
+         (start-year (decoded-time-year interval-start))
+         (interval-end (cadr interval))
+         (end-year (decoded-time-year interval-end))
+         (subintervals nil))
+    (while (<= start-year end-year)
+      ;; For each year in the interval...
+      (dolist (wn sorted-weeknos)
+        ;; ...the subinterval is one week long in the wn-th week
+        (let* ((nth-wstart (ical:start-of-weekno wn start-year weekstart))
+               (low (ical:make-date-time :year (calendar-extract-year nth-wstart)
+                                         :month (calendar-extract-month nth-wstart)
+                                         :day (calendar-extract-day nth-wstart)
+                                         :hour 0 :minute 0 :second 0
+                                         :tz vtimezone))
+               (high (ical:date/time-add low :day 7 vtimezone)))
+          ;; "Clip" the subinterval bounds if they fall outside the
+          ;; interval, as above.  This can happen often here because week
+          ;; boundaries generally do not align with year boundaries.
+          (when (ical:date/time< low interval-start)
+            (setq low interval-start))
+          (when (ical:date/time< interval-end high)
+            (setq high interval-end))
+          (when (and (ical:date-time<= interval-start low)
+                     (ical:date-time< low high)
+                     (ical:date-time<= high interval-end))
+              (push (list low high) subintervals))))
+      (setq start-year (1+ start-year)))
+    (nreverse subintervals)))
+
+(defun icr:refine-bymonth (interval months &optional vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching MONTHS.
+
+MONTHS should be a list of values from a recurrence rule's
+BYMONTH=... clause; see `icalendar-recur' for the possible values."
+  (let* ((sorted-months (sort months))
+         (interval-start (car interval))
+         (start-year (decoded-time-year interval-start))
+         (interval-end (cadr interval))
+         (end-year (decoded-time-year interval-end))
+         (subintervals nil))
+    (while (<= start-year end-year)
+      ;; For each year in the interval...
+      (dolist (m sorted-months)
+        ;; ...the subinterval is from the first day of the given month
+        ;; to the first day of the next
+        (let* ((low (ical:make-date-time :year start-year :month m :day 1
+                                         :hour 0 :minute 0 :second 0
+                                         :tz vtimezone))
+               (high (ical:date/time-add low :month 1 vtimezone)))
+
+          ;; Clip the subinterval bounds, as above
+          (when (ical:date/time< low interval-start)
+            (setq low interval-start))
+          (when (ical:date/time< interval-end high)
+            (setq high interval-end))
+          (when (and (ical:date/time<= interval-start low)
+                     (ical:date/time< low high)
+                     (ical:date/time<= high interval-end))
+            (push (list low high) subintervals))))
+      (setq start-year (1+ start-year)))
+
+    (nreverse subintervals)))
+
+(defun icr:refine-bymonthday (interval monthdays &optional vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching MONTHDAYS.
+
+MONTHDAYS should be a list of values from a recurrence rule's
+BYMONTHDAY=... clause; see `icalendar-recur' for the possible values."
+  (let* ((sorted-mdays (sort monthdays
+                             :lessp (lambda (a b)
+                                      (let ((pos-a (if (< 0 a) a (+ 31 a)))
+                                            (pos-b (if (< 0 b) b (+ 31 b))))
+                                        (< pos-a pos-b)))))
+         (interval-start (car interval))
+         (interval-end (cadr interval))
+         (subintervals nil))
+    (while (ical:date-time<= interval-start interval-end)
+      ;; For each month in the interval...
+      (dolist (m sorted-mdays)
+        ;; ...the subinterval is one day long on the given monthday
+        (let* ((month (ical:date/time-month interval-start))
+               (year (ical:date/time-year interval-start))
+               (monthday (if (< 0 m) m
+                           (+ m 1 (calendar-last-day-of-month month year))))
+               (low (ical:date-time-variant interval-start :day monthday
+                                            :hour 0 :minute 0 :second 0
+                                            :tz vtimezone))
+               (high (ical:date/time-add low :day 1 vtimezone)))
+
+          (ignore-errors ; ignore invalid dates, e.g. 2025-02-29
+            ;; Clip subinterval, as above
+            (when (ical:date/time< low interval-start)
+              (setq low interval-start))
+            (when (ical:date/time< interval-end high)
+              (setq high interval-end))
+            (when (and (ical:date/time<= interval-start low)
+                       (ical:date/time< low high)
+                       (ical:date/time<= high interval-end))
+              (push (list low high) subintervals)))))
+      (setq interval-start
+            (ical:date/time-add interval-start :month 1 vtimezone)))
+    (nreverse subintervals)))
+
+(defun icr:refine-byday (interval weekdays &optional in-month vtimezone)
+  "Refine INTERVAL to days matching the given WEEKDAYS.
+
+WEEKDAYS should be a list of values from a recurrence rule's
+BYDAY=... clause; see `icalendar-recur' for the possible values.
+
+If WEEKDAYS contains pairs (DOW . OFFSET), then IN-MONTH indicates
+whether OFFSET is relative to the month of the start of the interval.  If
+it is nil, OFFSET will be relative to the year, rather than the month."
+  (let* ((sorted-weekdays (sort (seq-filter #'natnump weekdays)))
+         (with-offsets (sort (seq-filter #'consp weekdays)
+                             :lessp (lambda (w1 w2) (and (< (car w1) (car w2))))))
+         (interval-start (car interval))
+         (start-abs (calendar-absolute-from-gregorian
+                     (ical:date-time-to-date interval-start)))
+         (interval-end (cadr interval))
+         (end-abs (calendar-absolute-from-gregorian
+                   (ical:date-time-to-date interval-end)))
+         (subintervals nil))
+
+    ;; For days where an offset was given, the subinterval is a single
+    ;; weekday relative to the month or year of interval-start:
+    (dolist (wo with-offsets)
+      (let* ((dow (car wo))
+             (offset (cdr wo))
+             (low-date
+              (ical:nth-weekday-in offset dow
+                                   (ical:date/time-year interval-start)
+                                   (when in-month
+                                     (ical:date/time-month interval-start))))
+             (low (ical:date-to-date-time low-date :tz vtimezone))
+             (high (ical:date/time-add low :day 1 vtimezone)))
+        (when (ical:date/time< low interval-start)
+          (setq low interval-start))
+        (when (ical:date/time< interval-end high)
+          (setq high interval-end))
+        (when vtimezone
+          (icr:tz-set-zone low vtimezone)
+          (icr:tz-set-zone high vtimezone))
+        (when (and (ical:date/time<= interval-start low)
+                   (ical:date/time<= high interval-end)
+                   (ical:date/time< low high))
+          (push (list low high) subintervals))))
+
+    ;; When no offset was given, for each day in the interval...
+    (while (and (<= start-abs end-abs)
+                sorted-weekdays)
+      ;; ...the subinterval is one day long on matching weekdays.
+      (let* ((gdate (calendar-gregorian-from-absolute start-abs)))
+        (when (memq (calendar-day-of-week gdate) sorted-weekdays)
+          (let* ((low (ical:date-to-date-time gdate))
+                 (high (ical:date/time-add low :day 1 vtimezone)))
+            (when (ical:date/time< low interval-start)
+              (setq low interval-start))
+            (when (ical:date/time< interval-end high)
+              (setq high interval-end))
+            (when vtimezone
+              (icr:tz-set-zone low vtimezone)
+              (icr:tz-set-zone high vtimezone))
+            (when (and (ical:date/time<= interval-start low)
+                       (ical:date/time<= high interval-end)
+                       (ical:date/time< low high))
+              (push (list low high) subintervals)))))
+      (setq start-abs (1+ start-abs)))
+
+    ;; Finally, sort and return all subintervals:
+    (sort subintervals
+          :lessp (lambda (int1 int2)
+                   (ical:date-time< (car int1) (car int2)))
+          :in-place t)))
+
+(defun icr:refine-byhour (interval hours &optional vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching HOURS.
+
+HOURS should be a list of values from a recurrence rule's
+BYHOUR=... clause; see `icalendar-recur' for the possible values."
+  (let* ((sorted-hours (sort hours))
+         (interval-start (car interval))
+         (interval-end (cadr interval))
+         (subintervals nil))
+    (while (ical:date-time<= interval-start interval-end)
+      ;; For each day in the interval...
+      (dolist (h sorted-hours)
+        ;; ...the subinterval is one hour long in the given hour
+        (let* ((low (ical:date-time-variant interval-start
+                                            :hour h :minute 0 :second 0
+                                            :tz vtimezone))
+               (high (ical:date/time-add low :hour 1 vtimezone)))
+          (ignore-errors ; do not generate subintervals for nonexisting times
+            (when (ical:date/time< low interval-start)
+              (setq low interval-start))
+            (when (ical:date/time< interval-end high)
+              (setq high interval-end))
+            (when (and (ical:date/time<= interval-start low)
+                       (ical:date/time< low high)
+                       (ical:date/time<= high interval-end))
+              (push (list low high) subintervals)))))
+      (setq interval-start (ical:date/time-add interval-start :day 1 vtimezone)))
+    (nreverse subintervals)))
+
+(defun icr:refine-byminute (interval minutes &optional vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching MINUTES.
+
+MINUTES should be a list of values from a recurrence rule's
+BYMINUTE=... clause; see `icalendar-recur' for the possible values."
+  (let* ((sorted-minutes (sort minutes))
+         (interval-start (car interval))
+         (interval-end (cadr interval))
+         ;; we use absolute times (in seconds) for the loop variables in
+         ;; case the interval crosses the boundary between two observances:
+         (low-ts (time-convert (encode-time interval-start) 'integer))
+         (end-ts (time-convert (encode-time interval-end) 'integer))
+         (subintervals nil))
+    (while (<= low-ts end-ts)
+      ;; For each hour in the interval...
+      (dolist (m sorted-minutes)
+        ;; ...the subinterval is one minute long in the given minute
+        (let* ((low (ical:date-time-variant interval-start :minute m :second 0
+                                            :tz vtimezone))
+               (high (ical:date/time-add low :minute 1 vtimezone)))
+          (ignore-errors ; do not generate subintervals for nonexisting times
+            ;; Clip the subinterval, as above
+            (when (ical:date/time< low interval-start)
+              (setq low interval-start))
+            (when (ical:date/time< interval-end high)
+              (setq high interval-end))
+            (when (and (ical:date/time<= interval-start low)
+                       (ical:date/time< low high)
+                       (ical:date/time<= high interval-end))
+              (push (list low high) subintervals)))))
+      (setq low-ts (+ low-ts (* 60 60))
+            interval-start (if vtimezone (icr:tz-decode-time low-ts vtimezone)
+                             (ical:date/time-add interval-start :hour 1))))
+    (nreverse subintervals)))
+
+(defun icr:refine-bysecond (interval seconds &optional vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching SECONDS.
+
+SECONDS should be a list of values from a recurrence rule's
+BYSECOND=... clause; see `icalendar-recur' for the possible values."
+  (let* ((sorted-seconds (sort seconds))
+         (interval-start (car interval))
+         (interval-end (cadr interval))
+         ;; we use absolute times (in seconds) for the loop variables in
+         ;; case the interval crosses the boundary between two observances:
+         (low-ts (time-convert (encode-time interval-start) 'integer))
+         (end-ts (time-convert (encode-time interval-end) 'integer))
+         (subintervals nil))
+    (while (<= low-ts end-ts)
+      ;; For each minute in the interval...
+      (dolist (s sorted-seconds)
+        ;; ...the subinterval is one second long: the given second
+        (let* ((low (ical:date-time-variant interval-start :second s
+                                            :tz vtimezone))
+               (high (ical:date/time-add low :second 1 vtimezone)))
+          (when (ical:date/time< low interval-start)
+            (setq low interval-start))
+          (when (ical:date/time< interval-end high)
+            (setq high interval-end))
+          (when (and (ical:date/time<= interval-start low)
+                     (ical:date/time< low high)
+                     (ical:date/time<= high interval-end))
+            (push (list low high) subintervals))))
+      (setq low-ts (+ low-ts 60)
+            interval-start (if vtimezone
+                               (icr:tz-decode-time low-ts vtimezone)
+                             (ical:date/time-add interval-start :minute 1))))
+    (nreverse subintervals)))
+
+;; TODO: should this just become a generic function, with the above
+;; refine-by* functions becoming its methods?
+(defun icr:refine-by (unit interval values
+                      &optional byday-inmonth weekstart vtimezone)
+  "Resolve INTERVAL into a list of subintervals matching VALUES for UNIT."
+  (cl-case unit
+    (BYYEARDAY (icr:refine-byyearday interval values vtimezone))
+    (BYWEEKNO (icr:refine-byweekno interval values weekstart vtimezone))
+    (BYMONTH (icr:refine-bymonth interval values vtimezone))
+    (BYMONTHDAY (icr:refine-bymonthday interval values vtimezone))
+    (BYDAY (icr:refine-byday interval values byday-inmonth vtimezone))
+    (BYHOUR (icr:refine-byhour interval values vtimezone))
+    (BYMINUTE (icr:refine-byminute interval values vtimezone))
+    (BYSECOND (icr:refine-bysecond interval values vtimezone))))
+
+(defun icr:make-bysetpos-filter (setpos)
+  "Return a filter on values for the indices in SETPOS.
+
+SETPOS should be a list of positive or negative integers between -366
+and 366, indicating a fixed index in a set of recurrences for *one
+interval* of a recurrence set, as found in the BYSETPOS=...  clause of
+an `icalendar-recur'.  For example, in a YEARLY recurrence rule with an
+INTERVAL of 1, the SETPOS represent indices in the recurrence instances
+generated for a single year.
+
+The returned value is a closure which can be called on the list of
+recurrences for one interval to filter it by index."
+  (lambda (dts)
+    (let* ((len (length dts))
+           (keep-indices (mapcar
+                          (lambda (pos)
+                            ;; sequence indices are 0-based, POS's are 1-based:
+                            (if (< pos 0)
+                                (+ pos len)
+                              (1- pos)))
+                          setpos)))
+      (delq nil
+        (seq-map-indexed
+         (lambda (dt index)
+           (when (memq index keep-indices)
+                 dt))
+         dts)))))
+
+(defun icr:refine-from-clauses (interval recur-value dtstart
+                                &optional vtimezone)
+  "Resolve INTERVAL into subintervals based on the clauses in RECUR-VALUE.
+
+The resulting list of subintervals represents all times in INTERVAL
+which match the BY* clauses of RECUR-VALUE except BYSETPOS, as well as
+the constraints implicit in DTSTART.  (For example, if there is no
+BYMINUTE clause, subintervals will have the same minute value as
+DTSTART.)
+
+If specified, VTIMEZONES should be a list of `icalendar-vtimezone'
+components and TZID should be the `icalendar-tzid' property value of one
+of those timezones.  In this case, TZID states the time zone of DTSTART,
+and the offsets effective in that time zone on the dates and times of
+recurrences will be local to that time zone."
+  (let ((freq (ical:recur-freq recur-value))
+        (weekstart (ical:recur-weekstart recur-value))
+        (subintervals (list interval)))
+
+    (dolist (byunit (list 'BYMONTH 'BYWEEKNO
+                          'BYYEARDAY 'BYMONTHDAY 'BYDAY
+                          'BYHOUR 'BYMINUTE 'BYSECOND))
+      (let ((values (ical:recur-by* byunit recur-value))
+            (in-month nil))
+        ;; When there is no explicit BY* clause, use the value implicit
+        ;; in DTSTART.  (These conditions are adapted from RFC8984:
+        ;;   https://www.rfc-editor.org/rfc/rfc8984.html#section-4.3.3.1-4.3.1
+        ;; Basically, the conditions are somewhat complicated because
+        ;; the meanings of various BY* clauses are not independent and
+        ;; so we have to be careful about the information we take to be
+        ;; implicit in DTSTART, especially with MONTHLY and YEARLY
+        ;; rules.  For example, we *do* want to take the weekday of
+        ;; DTSTART as an implicit constraint if a BYWEEKNO clause is
+        ;; present, but not if an explicit BYDAY or BYMONTHDAY clause is
+        ;; also present, since they might contain conflicting
+        ;; constraints.)
+        (when (and (eq byunit 'BYSECOND)
+                   (not (eq freq 'SECONDLY))
+                   (not values))
+          (setq values (list (ical:date/time-second dtstart))))
+        (when (and (eq byunit 'BYMINUTE)
+                   (not (memq freq '(SECONDLY MINUTELY)))
+                   (not values))
+          (setq values (list (ical:date/time-minute dtstart))))
+        (when (and (eq byunit 'BYHOUR)
+                   (not (memq freq '(SECONDLY MINUTELY HOURLY)))
+                   (not values))
+          (setq values (list (ical:date/time-hour dtstart))))
+        (when (and (eq byunit 'BYDAY)
+                   (eq freq 'WEEKLY)
+                   (not values))
+          (setq values (list (ical:date/time-weekday dtstart))))
+        (when (and (eq byunit 'BYMONTHDAY)
+                   (eq freq 'MONTHLY)
+                   (not (ical:recur-by* 'BYDAY recur-value))
+                   (not values))
+          (setq values (list (ical:date/time-monthday dtstart))))
+        (when (and (eq freq 'YEARLY)
+                   (not (ical:recur-by* 'BYYEARDAY recur-value)))
+          (when (and (eq byunit 'BYMONTH)
+                     (not values)
+                     (not (ical:recur-by* 'BYWEEKNO recur-value))
+                     (or (ical:recur-by* 'BYMONTHDAY recur-value)
+                         (not (ical:recur-by* 'BYDAY recur-value))))
+            (setq values (list (ical:date/time-month dtstart))))
+          (when (and (eq byunit 'BYMONTHDAY)
+                     (not values)
+                     (not (ical:recur-by* 'BYWEEKNO recur-value))
+                     (not (ical:recur-by* 'BYDAY recur-value)))
+            (setq values (list (ical:date/time-monthday dtstart))))
+          (when (and (eq byunit 'BYDAY)
+                     (not values)
+                     (ical:recur-by* 'BYWEEKNO recur-value)
+                     (not (ical:recur-by* 'BYMONTHDAY recur-value)))
+            (setq values (list (ical:date/time-weekday dtstart)))))
+
+        ;; Handle offsets in a BYDAY clause:
+        ;; "If present, this [offset] indicates the nth occurrence of a
+        ;; specific day within the MONTHLY or YEARLY "RRULE".  For
+        ;; example, within a MONTHLY rule, +1MO (or simply 1MO)
+        ;; represents the first Monday within the month, whereas -1MO
+        ;; represents the last Monday of the month.  The numeric value
+        ;; in a BYDAY rule part with the FREQ rule part set to YEARLY
+        ;; corresponds to an offset within the month when the BYMONTH
+        ;; rule part is present"
+        (when (and (eq byunit 'BYDAY)
+                   (or (eq freq 'MONTHLY)
+                       (and (eq freq 'YEARLY)
+                            (ical:recur-by* 'BYMONTH recur-value))))
+          (setq in-month t))
+
+        ;; On each iteration of the loop, we refine the subintervals
+        ;; with these explicit or implicit values:
+        (when values
+          (setq subintervals
+                (delq nil
+                      (mapcan (lambda (in)
+                                (icr:refine-by byunit in values in-month
+                                               weekstart vtimezone))
+                              subintervals))))))
+
+    ;; Finally return the refined subintervals after we've looked at all
+    ;; clauses:
+    subintervals))
+
+;; Once we have refined an interval into a final set of subintervals, we
+;; need to convert those subintervals into a set of recurrences.  For a
+;; recurrence set where DTSTART and the recurrences are date-times, the
+;; recurrence set (in this interval) consists of every date-time
+;; corresponding to each second of any subinterval.  When DTSTART and the
+;; recurrences are plain dates, the recurrence set consists of each
+;; distinct date in any subinterval.
+(defun icr:subintervals-to-date-times (subintervals &optional vtimezone)
+  "Transform SUBINTERVALS into a list of `icalendar-date-time' recurrences.
+
+The returned list of recurrences contains one date-time value for each
+second of each subinterval."
+  (let (recurrences)
+    (dolist (int subintervals)
+      (let* ((start (car int))
+             (dt start)
+             ;; Use absolute times for the loop in case the subinterval
+             ;; crosses the boundary between two observances.
+             ;; N.B. floating times will be correctly treated as local
+             ;; times by encode-time.
+             (end (time-convert (encode-time (cadr int)) 'integer))
+             (tick (time-convert (encode-time start) 'integer)))
+        (while (time-less-p tick end)
+          (push dt recurrences)
+          (setq tick (1+ tick)
+                dt (if vtimezone (icr:tz-decode-time tick vtimezone)
+                     (ical:date/time-add dt :second 1))))))
+    (nreverse recurrences)))
+
+(defun icr:subintervals-to-dates (subintervals)
+  "Transform SUBINTERVALS into a list of `icalendar-date' recurrences.
+
+The returned list of recurrences contains one date value for each
+day of each subinterval."
+  (let (recurrences)
+    (dolist (int subintervals)
+      (let* ((start (car int))
+             (start-abs (calendar-absolute-from-gregorian
+                         (ical:date-time-to-date start)))
+             (end (cadr int))
+             (end-abs (calendar-absolute-from-gregorian
+                       (ical:date-time-to-date end)))
+             ;; end is an exclusive upper bound, but number-sequence
+             ;; needs an *inclusive* upper bound, so if end is at
+             ;; midnight, the bound is the previous day:
+             (bound (if (zerop (+ (decoded-time-hour end)
+                                  (decoded-time-minute end)
+                                  (decoded-time-second end)))
+                        (1- end-abs)
+                      end-abs)))
+        (setq recurrences
+              (append recurrences
+                      (mapcar #'calendar-gregorian-from-absolute
+                              (number-sequence start-abs bound))))))
+    recurrences))
+
+(defun icr:subintervals-to-recurrences (subintervals dtstart &optional vtimezone)
+  "Transform SUBINTERVALS into a list of recurrences.
+
+The returned list of recurrences contains all distinct values in each
+subinterval of the same type as DTSTART."
+  (if (cl-typep dtstart 'ical:date)
+      (icr:subintervals-to-dates subintervals)
+    (icr:subintervals-to-date-times subintervals vtimezone)))
+
+
+;; Calculating recurrences in a given interval or window
+;;
+;; We can now put all of the above together to compute the set of
+;; recurrences in a given interval (`icr:recurrences-in-interval'), and
+;; thereby in a given window (`icr:recurences-in-window'); or, if the
+;; rule describing the set has a COUNT clause, we can enumerate the
+;; recurrences in each interval starting from the beginning of the set
+;; (`icr:recurrences-to-count').
+(defun icr:recurrences-in-interval (interval component &optional vtimezone nmax)
+  "Return a list of the recurrences of COMPONENT in INTERVAL.
+
+INTERVAL should be a list (LOW HIGH NEXT) of date-times which bound a
+single recurrence interval, as returned e.g. by
+`icalendar-recur-find-interval'.  (To find the recurrences in an
+arbitrary window of time, rather than between interval boundaries, see
+`icalendar-recur-recurrences-in-window'.)
+
+COMPONENT should be an iCalendar component node representing a recurring
+event: it should contain at least an `icalendar-dtstart' and either an
+`icalendar-rrule' or `icalendar-rdate' property.
+
+If specified, VTIMEZONE should be an `icalendar-vtimezone' component.
+In this case, the dates and times of recurrences will be computed with
+UTC offsets local to that time zone.
+
+If specified, NMAX should be a positive integer containing a maximum
+number of recurrences to return from this interval.  In this case, if the
+interval contains more than NMAX recurrences, only the first NMAX
+recurrences will be returned; otherwise all recurrences in the interval
+are returned.  (The NMAX argument mainly exists to support recurrence
+rules with a COUNT clause; see `icalendar-recur-recurrences-to-count'.)
+
+The returned list is a list of `icalendar-date' or `icalendar-date-time'
+values representing the start times of recurrences.  Note that any
+values of type `icalendar-period' in COMPONENT's `icalendar-rdate'
+property (or properties) will NOT be included in the list; it is the
+callee's responsibility to handle any such values separately.
+
+The computed recurrences for INTERVAL are cached in COMPONENT and
+retrieved on subsequent calls with the same arguments."
+  (ical:with-component component
+      ((ical:dtstart :value dtstart)
+       (ical:tzoffsetfrom :value offset-from)
+       (ical:rrule :value recur-value)
+       (ical:rdate :all rdate-nodes) ;; TODO: these can also be ical:period values
+       (ical:exdate :all exdate-nodes))
+    (if (not (or recur-value rdate-nodes))
+        ;; No recurrences to calculate, so just return early:
+        nil
+      ;; Otherwise, calculate recurrences in the interval:
+      (when (memq (ical:ast-node-type component) '(ical:standard ical:daylight))
+        ;; In time zone observances, set the zone field in dtstart
+        ;; from the TZOFFSETFROM property:
+        (setq dtstart
+              (ical:date-time-variant dtstart
+                                      :zone offset-from
+                                      :dst (not (ical:daylight-component-p
+                                                 component)))))
+      (cl-labels ((get-interval
+                    (apply-partially #'icr:-set-get-interval component))
+                  (put-interval
+                    (apply-partially #'icr:-set-put-interval component)))
+        (let ((cached (get-interval interval)))
+          (cond ((eq cached :none) nil)
+                (cached cached)
+                (t
+                 (let* (;; Start by generating all the recurrences matching the
+                        ;; BY* clauses except for BYSETPOS:
+                        (subs (icr:refine-from-clauses interval recur-value dtstart
+                                                       vtimezone))
+                        (sub-recs (icr:subintervals-to-recurrences subs dtstart
+                                                                   vtimezone))
+                        ;; Apply any BYSETPOS clause to this set:
+                        (keep-indices (ical:recur-by* 'BYSETPOS recur-value))
+                        (pos-recs
+                         (if keep-indices
+                             (funcall (icr:make-bysetpos-filter keep-indices)
+                                      sub-recs)
+                           sub-recs))
+                        ;; Remove any recurrences before DTSTART or after UNTIL
+                        ;; (both of which are inclusive bounds):
+                        (until (ical:recur-until recur-value))
+                        (until-recs
+                         (seq-filter
+                          (lambda (rec) (and (ical:date/time<= dtstart rec)
+                                             (or (not until)
+                                                 (ical:date/time<= rec until))))
+                          pos-recs))
+                        ;; Include any values in the interval from the
+                        ;; RDATE property:
+                        (low (car interval))
+                        (high (cadr interval))
+                        (rdates
+                         (mapcar #'ical:ast-node-value
+                                 (apply #'append
+                                        (mapcar #'ical:ast-node-value
+                                                rdate-nodes))))
+                        (interval-rdates
+                         (seq-filter
+                          (lambda (rec)
+                            ;; only include ical:date and ical:date-time
+                            ;; values from RDATE; callee is responsible
+                            ;; for handling ical:period values
+                            (unless (cl-typep rec 'ical:period)
+                              (and (ical:date/time<= low rec)
+                                   (ical:date/time< high rec))))
+                          rdates))
+                        (included-recs (append until-recs interval-rdates))
+                        ;; Exclude any values from the EXDATE property;
+                        ;; this gives us the complete set of recurrences
+                        ;; in this interval:
+                        (exdates
+                         (mapcar #'ical:ast-node-value
+                                 (append
+                                  (mapcar #'ical:ast-node-value exdate-nodes))))
+                        (all-recs
+                         (if exdates
+                             (seq-filter
+                              (lambda (rec) (not (member rec exdates)))
+                              included-recs)
+                           included-recs))
+                        ;; Limit to the first NMAX recurrences if requested.
+                        ;; `icr:recurrences-to-count' provides NMAX so as not to
+                        ;; store more recurrences in the final interval than the
+                        ;; COUNT clause allows:
+                        (nmax-recs
+                         (if nmax (seq-take all-recs nmax)
+                           all-recs)))
+                   ;; Store and return the computed recurrences:
+                   (put-interval interval (or nmax-recs :none))
+                   nmax-recs))))))))
+
+(defun icr:recurrences-in-window (lower upper component &optional vtimezone)
+  "Return the recurrences of COMPONENT in the window between LOWER and UPPER.
+
+LOWER and UPPER may be arbitrary `icalendar-date' or
+`icalendar-date-time' values.  COMPONENT should be an iCalendar component
+node representing a recurring event: it should contain at least an
+`icalendar-dtstart' and either an `icalendar-rrule' or `icalendar-rdate'
+property.
+
+If specified, VTIMEZONE should be an `icalendar-vtimezone' component.
+In this case, the dates and times of recurrences will be computed with
+UTC offsets local to that time zone."
+  (ical:with-component component
+      ((ical:dtstart :value dtstart)
+       (ical:tzoffsetfrom :value offset-from)
+       (ical:rrule :value recur-value)
+       (ical:rdate :all rdate-nodes))
+    (if (not (or recur-value rdate-nodes))
+        ;; No recurrences to calculate, so just return early:
+        nil
+      ;; Otherwise, calculate the recurrences in the window:
+      (when (memq (ical:ast-node-type component) '(ical:standard ical:daylight))
+        ;; in time zone observances, set the zone field in dtstart
+        ;; from the TZOFFSETFROM property:
+        (setq dtstart
+              (ical:date-time-variant dtstart
+                                      :zone offset-from
+                                      :dst (not (ical:daylight-component-p
+                                                 component)))))
+
+      (let* (;; don't look for nonexistent intervals:
+             (low-start (if (ical:date/time< lower dtstart) dtstart lower))
+             (until (ical:recur-until recur-value))
+             (high-end (if (and until (ical:date/time< until upper)) until upper))
+             (curr-interval (icr:find-interval low-start dtstart recur-value
+                                               vtimezone))
+             (high-interval (icr:find-interval high-end dtstart recur-value
+                                               vtimezone))
+             (high-intbound (cadr high-interval))
+             (recurrences nil))
+
+        (while (ical:date-time< (car curr-interval) high-intbound)
+          (setq recurrences
+                (append
+                 (icr:recurrences-in-interval curr-interval component vtimezone)
+                 recurrences))
+          (setq curr-interval (icr:next-interval curr-interval recur-value
+                                                 vtimezone)))
+
+        ;; exclude any recurrences inside the first and last intervals but
+        ;; outside the window before returning:
+        (seq-filter
+         (lambda (dt)
+           (and (ical:date/time<= lower dt)
+                (ical:date/time< dt upper)))
+         recurrences)))))
+
+(defun icr:recurrences-in-window-w/end-times
+    (lower upper component &optional vtimezone)
+  "Like `icalendar-recurrences-in-window', but returns end times.
+
+The return value is a list of (START END) pairs representing the start
+and end time of each recurrence of COMPONENT in the window defined by
+LOWER and UPPER.
+
+In the returned pairs, START and END are both `icalendar-date' or
+`icalendar-date-time' values of the same type as COMPONENT's
+`icalendar-dtstart'.  Each END time is computed by adding COMPONENT's
+`icalendar-duration' value to START for each recurrence START between
+LOWER and UPPER.  Or, if the recurrence is given by an `icalendar-period'
+value in an `icalendar-rdate' property, START and END are determined by
+the period."
+  (ical:with-component component
+    ((ical:duration :value duration)
+     (ical:rdate :all rdate-nodes))
+    ;; TODO: for higher-level applications showing a schedule, it might
+    ;; be useful to include recurrences which start outside the window,
+    ;; but end inside it.  This would mean we can't simply use
+    ;; `recurrences-in-window' like this.
+    (let ((starts (icr:recurrences-in-window lower upper component vtimezone))
+          (periods (seq-filter
+                    (lambda (vnode)
+                      (when (eq 'ical:period (ical:ast-node-type vnode))
+                        (ical:ast-node-value vnode)))
+                    (append
+                     (mapcar #'ical:ast-node-value rdate-nodes)))))
+      (when (or starts periods)
+        (seq-uniq
+         (append (mapcar
+                  (lambda (dt) (list dt (ical:date/time-add-duration
+                                         dt duration vtimezone)))
+                  starts)
+                 (mapcar
+                  (lambda (p)
+                    (let ((start (ical:period-start p)))
+                      (list start
+                            (or (ical:period-end p)
+                                (ical:date/time-add-duration
+                                 start (ical:period-dur-value p) vtimezone)))))
+                  periods)))))))
+
+(defun icr:recurrences-to-count (component &optional vtimezone)
+  "Return all the recurrences in COMPONENT up to COUNT in its recurrence rule.
+
+COMPONENT should be an iCalendar component node representing a recurring
+event: it should contain at least an `icalendar-dtstart' and an
+`icalendar-rrule', which must contain a COUNT=... clause.
+
+Warning: this function finds *all* the recurrences in COMPONENT's
+recurrence set.  If the value of COUNT is large, this can be slow.
+
+If specified, VTIMEZONE should be an `icalendar-vtimezone' component.
+In this case, the dates and times of recurrences will be computed with
+UTC offsets local to that time zone."
+  (ical:with-component component
+      ((ical:dtstart :value dtstart)
+       (ical:tzoffsetfrom :value offset-from)
+       (ical:rrule :value recur-value)
+       (ical:rdate :all rdate-nodes))
+    (when (memq (ical:ast-node-type component) '(ical:standard ical:daylight))
+      ;; in time zone observances, set the zone field in dtstart
+      ;; from the TZOFFSETFROM property:
+      (setq dtstart
+            (ical:date-time-variant dtstart
+                                    :zone offset-from
+                                    :dst (not (ical:daylight-component-p
+                                               component)))))
+    (unless (or recur-value rdate-nodes)
+      (error "No recurrence data in component: %s" component))
+    (unless (ical:recur-count recur-value)
+      (error "Recurrence rule has no COUNT clause"))
+    (let ((count (ical:recur-count recur-value))
+          (int (icr:nth-interval 0 dtstart recur-value vtimezone))
+          recs)
+      (while (length< recs count)
+        (setq recs
+              (append recs (icr:recurrences-in-interval int component vtimezone
+                                                        (- count (length recs)))))
+        (setq int (icr:next-interval int recur-value vtimezone)))
+      recs)))
+
+
+
+;; Recurrence set representation
+;;
+;; We represent a recurrence set as a map from intervals to the
+;; recurrences in that interval.  The primary purpose of this
+;; representation is to memoize the computation of recurrences, since
+;; the computation is relatively expensive and the results are needed
+;; repeatedly, particularly for time zone observances.  The map is stored
+;; in the `:recurrence-set' property of the iCalendar component which
+;; represents the recurring event.
+;;
+;; Internally, we use a hash table for the map, since the set can grow
+;; quite large.  We use the start date-times of intervals as the keys,
+;; since these uniquely identify intervals within a given component; we
+;; ignore the weekday, zone and dst fields in the keys, mostly to avoid
+;; cache misses during time zone observance lookups, which must generate
+;; intervals with different zone values.
+;;
+;; In order to avoid repeating the computation of recurrences, we store
+;; the keyword `:none' as the value when there are no recurrences in a
+;; given interval.  This distinguishes the value from nil, so that,
+;; whereas (gethash some-key the-map) => nil means "We haven't computed
+;; recurrences yet for this interval", (gethash some-key the-map) =>
+;; :none means "We've computed that there are no recurrences in this
+;; interval", and can skip the computation of recurrences.  See
+;; `icalendar-recur-recurrences-in-interval', which performs the check.
+
+(defun icr:-make-set ()
+  (make-hash-table :test #'equal))
+
+(defsubst icr:-key-from-interval (interval)
+  (take 6 (car interval))) ; (secs mins hours day month year)
+
+(defun icr:-set-get-interval (component interval)
+  (let ((set (ical:ast-node-meta-get :recurrence-set component))
+        (key (icr:-key-from-interval interval)))
+    (when (hash-table-p set)
+      (gethash key set))))
+
+(defun icr:-set-put-interval (component interval recurrences)
+  (let ((set (or (ical:ast-node-meta-get :recurrence-set component)
+                 (icr:-make-set)))
+        (key (icr:-key-from-interval interval)))
+    (setf (gethash key set) recurrences)
+    (ical:ast-node-meta-set component :recurrence-set set)))
+
+
+;; Timezones:
+
+(define-error 'ical:tz-nonexistent-time "Date-time does not exist" 'ical:error)
+
+(define-error 'ical:tz-no-observance "No observance found for date-time"
+              'ical:error)
+
+(define-error 'ical:tz-data-insufficient
+              "Insufficient time zone data to create VTIMEZONE"
+              'ical:error)
+
+(define-error 'ical:tz-unsupported
+              "Time zone rules not expressible as iCalendar RRULE"
+              'ical:error)
+
+;; In RFC5545 Section 3.3.10, we read: "If the computed local start time
+;; of a recurrence instance does not exist ... the time of the
+;; recurrence instance is interpreted in the same manner as an explicit
+;; DATE-TIME value describing that date and time, as specified in
+;; Section 3.3.5." which in turn says:
+;; "If, based on the definition of the referenced time zone, the local
+;; 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
+;; 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)."
+
+;; TODO: verify that these functions are correct for time zones other
+;; than US Eastern.
+(defun icr:nonexistent-date-time-p (dt obs-onset observance)
+  "Return non-nil if DT does not exist in a given OBSERVANCE.
+
+Some local date-times do not exist in a given time zone.  When switching
+from standard to daylight savings time, the local clock time jumps over
+a certain range of times.  This function tests whether DT is one of those
+non-existent local times.
+
+DT and OBS-ONSET should be `icalendar-date-time' values; OBS-ONSET
+should be the (local) time immediately at the onset of the
+OBSERVANCE.  OBSERVANCE should be an `icalendar-standard' or
+`icalendar-daylight' component.
+
+If this function returns t, then per RFC5545 Section 3.3.5, DT must be
+interpreted using the UTC offset in effect prior to the onset of
+OBSERVANCE.  For example, at the switch from Standard to Daylight
+Savings time in US Eastern, the nonexistent time 2:30AM (Standard) must
+be re-interpreted as 3:30AM DST."
+  (when (ical:daylight-component-p observance)
+    (ical:with-component observance
+        ((ical:tzoffsetfrom :value offset-from)
+         (ical:tzoffsetto :value offset-to))
+      (and (= (decoded-time-year dt) (decoded-time-year obs-onset))
+           (= (decoded-time-month dt) (decoded-time-month obs-onset))
+           (= (decoded-time-day dt) (decoded-time-day obs-onset))
+           (let* ((onset-secs (+ (decoded-time-second obs-onset)
+                                 (* 60 (decoded-time-minute obs-onset))
+                                 (* 60 60 (decoded-time-hour obs-onset))))
+                  (dt-secs (+ (decoded-time-second dt)
+                              (* 60 (decoded-time-minute dt))
+                              (* 60 60 (decoded-time-hour dt))))
+                  (jumped (abs (- offset-from offset-to)))
+                  (after-jumped (+ onset-secs jumped)))
+             (and
+              (<= onset-secs dt-secs)
+              (< dt-secs after-jumped)))))))
+
+(defun icr:date-time-occurs-twice-p (dt obs-onset observance)
+  "Return non-nil if DT occurs twice in the given OBSERVANCE.
+
+Some local date-times occur twice in a given time zone.  When switching
+from daylight savings to standard time time, the local clock time is
+typically set back, so that a certain range of clock times occurs twice,
+once in daylight savings time and once in standard time.  This function
+tests whether DT is one of those local times which occur twice.
+
+DT and OBS-ONSET should be `icalendar-date-time' values; OBS-ONSET
+should be the (local) time immediately at the relevant onset of the
+OBSERVANCE.  OBSERVANCE should be an `icalendar-standard' or
+`icalendar-daylight' component.
+
+If this function returns t, then per RFC5545 Section 3.3.5, DT must be
+interpreted as the first occurrence of this clock time, i.e., in
+daylight savings time, prior to OBS-ONSET."
+  (when (ical:standard-component-p observance)
+    (ical:with-component observance
+        ((ical:tzoffsetfrom :value offset-from)
+         (ical:tzoffsetto :value offset-to))
+      (and (= (decoded-time-year dt) (decoded-time-year obs-onset))
+           (= (decoded-time-month dt) (decoded-time-month obs-onset))
+           (= (decoded-time-day dt) (decoded-time-day obs-onset))
+           (let* ((onset-secs (+ (decoded-time-second obs-onset)
+                                 (* 60 (decoded-time-minute obs-onset))
+                                 (* 60 60 (decoded-time-hour obs-onset))))
+                  (dt-secs (+ (decoded-time-second dt)
+                              (* 60 (decoded-time-minute dt))
+                              (* 60 60 (decoded-time-hour dt))))
+                  (repeated (abs (- offset-from offset-to)))
+                  (start-repeateds (- onset-secs repeated)))
+             (and
+              (<= start-repeateds dt-secs)
+              (< dt-secs onset-secs)))))))
+
+(defun icr:tz--get-updated-in (dt obs-onset observance)
+  "Determine how to update DT's zone and dst slots from OBSERVANCE.
+
+DT should be an `icalendar-date-time', OBSERVANCE an
+`icalendar-standard' or `icalendar-daylight', and OBS-ONSET the nearest
+onset of OBSERVANCE before DT.  Returns an `icalendar-date-time' that can
+be used to update DT.
+
+In most cases, the return value will contain a zone offset equal to
+OBSERVANCE's `icalendar-tzoffsetto' value.
+
+However, when DT falls within a range of nonexistent times after
+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 occurence."
+  (ical:with-component observance
+      ((ical:tzoffsetfrom :value offset-from)
+       (ical:tzoffsetto :value offset-to))
+    (let* ((is-daylight (ical:daylight-component-p observance))
+           (to-dt (ical:date-time-variant dt :dst is-daylight :zone offset-to))
+           (from-dt (ical:date-time-variant dt :dst (not is-daylight)
+                                            :zone offset-from))
+          updated)
+      (cond ((icr:nonexistent-date-time-p to-dt obs-onset observance)
+             ;; In this case, RFC5545 requires that we take the same
+             ;; point in absolute time as from-dt, but re-decode it into
+             ;; to-dt's zone:
+             (setq updated (decode-time (encode-time from-dt) offset-to))
+             (setf (decoded-time-dst updated) is-daylight))
+            ((icr:date-time-occurs-twice-p to-dt obs-onset observance)
+             ;; In this case, RFC5545 requires that we interpret dt as
+             ;; from-dt, since that is the first occurrence of the clock
+             ;; time in the zone:
+             (setq updated from-dt))
+            (t
+             ;; Otherwise we interpret dt as to-dt, i.e., with the
+             ;; offset effective within the observance:
+             (setq updated to-dt)))
+      updated)))
+
+(defun icr:tz-for (tzid vtimezones)
+  "Return the `icalendar-vtimezone' for the TZID.
+
+VTIMEZONES should be a list of `icalendar-vtimezone' components.  TZID
+should be a time zone identifier, as found e.g. in an
+`icalendar-tzidparam' parameter.  The first time zone in VTIMEZONES whose
+`icalendar-tzid' value matches this parameter's value is returned."
+  (catch 'found
+    (dolist (tz vtimezones)
+      (ical:with-component tz
+          ((ical:tzid :value tzidval))
+        (when (equal tzidval tzid)
+          (throw 'found tz))))))
+
+;; DRAGONS DRAGONS DRAGONS
+(defun icr:tz-observance-on (dt vtimezone &optional update nonexisting)
+  "Return the time zone observance in effect on DT in VTIMEZONE.
+
+If there is such an observance, the returned value is a list (OBSERVANCE
+ONSET).  OBSERVANCE is an `icalendar-standard' or `icalendar-daylight'
+component node.  ONSET is the recurrence of OBSERVANCE (an
+`icalendar-date-time') which occurs closest in time, but before, DT.
+
+If there is no such observance in VTIMEZONE, the returned value is nil.
+
+VTIMEZONE should be an `icalendar-vtimezone' component node.
+
+DT may be an an `icalendar-date-time' or a Lisp timestamp.  If it is a
+date-time, it represents a local time assumed to be in VTIMEZONE.  Any
+existing offset in DT is ignored, and DT is compared with the local
+clock time at the start of each observance in VTIMEZONE to determine the
+correct observance and onset.  (This is so that the correct observance
+can be found for clock times generated during recurrence rule
+calculations.)
+
+If UPDATE is non-nil, the observance found will be used to update the
+offset value in DT (as a side effect) before returning the observance
+and onset.
+
+If UPDATE is non-nil, NONEXISTING specifies how to handle clock times
+that do not exist in the observance (see
+`icalendar-recur-tz-nonexistent-date-time-p').  The keyword `:error'
+means to signal an \\='icalendar-tz-nonexistent-time error, without
+modifying any of the fields in DT.  Otherwise, the default is to
+interpret DT using the offset from UTC before the onset of the found
+observance, and then reset the clock time in DT to the corresponding
+existing time after the onset of the observance.  For example, the
+nonexisting time 2:30AM in Standard time on the day of the switch to
+Daylight time in the US Eastern time zone will be reset to 3:30AM
+Eastern Daylight time.
+
+If DT is a Lisp timestamp, it represents an absolute time and
+comparisons with the onsets in VTIMEZONE are performed with absolute
+times.  UPDATE and NONEXISTING have no meaning in this case and are
+ignored."
+  (ical:with-component vtimezone
+    ((ical:standard :all stds)
+     (ical:daylight :all dls))
+    (let (given-abs-time     ;; = `dt', if given a Lisp timestamp
+          given-clock-time   ;; = `dt', if given a decoded time
+          nearest-observance ;; the observance we're looking for
+          nearest-onset      ;; latest onset of this observance before `dt'
+          updated)           ;; stores how `dt's fields should be updated
+                             ;; in line with this observance, if requested
+
+      (if (cl-typep dt 'ical:date-time)
+          ;; We were passed a date-time with local clock time, not an
+          ;; absolute time; in this case, we must make local clock time
+          ;; comparisons with the observance onset start and recurrences
+          ;; (in order to determine the correct offset for it within the
+          ;; zone)
+          (setq given-clock-time dt
+                given-abs-time nil)
+        ;; We were passed an absolute time, not a date-time; in this
+        ;; case, we can make comparisons in absolute time with
+        ;; observance onset start and recurrences (in order to determine
+        ;; the correct offset for decoding it)
+        (setq given-abs-time dt
+              given-clock-time nil))
+
+      (dolist (obs (append stds dls))
+        (ical:with-component obs
+          ((ical:dtstart :value start)
+           (ical:rrule :value recur-value)
+           (ical:rdate :all rdate-nodes)
+           (ical:tzoffsetfrom :value offset-from))
+          ;; DTSTART of the observance must be given as local time, and is
+          ;; combined with TZOFFSETFROM to define the effective onset
+          ;; for the observance in absolute time.
+          (let* ((is-daylight (ical:daylight-component-p obs))
+                 (effective-start
+                  (ical:date-time-variant start :zone offset-from
+                                          :dst (not is-daylight)))
+                 (observance-might-apply
+                  (if given-clock-time
+                      (ical:date-time-locally<= effective-start given-clock-time)
+                    (ical:time<= (encode-time effective-start) given-abs-time))))
+
+            (when observance-might-apply
+              ;; Initialize our return values on the first iteration
+              ;; where an observance potentially applies:
+              (unless nearest-onset
+                (setq nearest-onset effective-start
+                      nearest-observance obs)
+                (when (and update given-clock-time)
+                  (setq updated
+                        (icr:tz--get-updated-in given-clock-time
+                                                effective-start obs))))
+
+              ;; We first check whether any RDATEs in the observance are
+              ;; the relevant onset:
+              (let ((rdates
+                     (mapcar #'ical:ast-node-value
+                             (apply #'append
+                                    (mapcar #'ical:ast-node-value rdate-nodes)))))
+                (dolist (rd rdates)
+                  (let* ((effective-rd
+                          ;; N.B.: we don't have to worry about rd being
+                          ;; an ical:period or ical:date here because in
+                          ;; time zone observances, RDATE values are
+                          ;; *only* allowed to be local date-times; see
+                          ;; https://www.rfc-editor.org/rfc/rfc5545#section-3.6.5
+                          ;; and `ical:rrule-validator'
+                          (ical:date-time-variant rd :zone offset-from
+                                                  :dst (not is-daylight)))
+                         (onset-applies
+                          (if given-clock-time
+                              (ical:date-time-locally<= effective-rd
+                                                        given-clock-time)
+                            (ical:time<= (encode-time effective-rd)
+                                         given-abs-time))))
+
+                    (when (and onset-applies nearest-onset
+                               (ical:date-time< nearest-onset effective-rd))
+                      (setq nearest-onset effective-rd
+                            nearest-observance obs)
+
+                      (when (and update given-clock-time)
+                        (setq updated
+                              (icr:tz--get-updated-in given-clock-time
+                                                      effective-rd obs)))))))
+
+              ;; If the observance has a recurrence value, it's the
+              ;; relevant observance if it:
+              ;; (1) has a recurrence which starts before dt
+              ;; (2) that recurrence is the nearest in the zone
+              ;;     which starts before dt
+              ;; Note that we intentionally do *not* pass `vtimezone'
+              ;; through here to find-interval, recurrences-in-interval,
+              ;; etc. so as not to cause infinite recursion.  Instead we
+              ;; directly pass `offset-from' (the offset from UTC at the
+              ;; start of each observance onset), which
+              ;; `icr:tz-set-zone' knows to handle specially without
+              ;; calling this function.
+              (when recur-value
+                (let* ((target (or given-clock-time
+                                   (decode-time given-abs-time offset-from)))
+                       (int (icr:find-interval
+                             target effective-start recur-value offset-from))
+                       (int-recs (icr:recurrences-in-interval
+                                  int obs offset-from))
+                       ;; The closest observance onset before `dt' might
+                       ;; actually be in the previous interval, e.g.
+                       ;; if `dt' is in January after an annual change to
+                       ;; Standard Time in November.  So check that as well.
+                       (prev-int (icr:previous-interval int recur-value
+                                                        effective-start
+                                                        offset-from))
+                       (prev-recs (when prev-int
+                                    (icr:recurrences-in-interval
+                                     prev-int obs offset-from)))
+                       (recs (append prev-recs int-recs))
+                       (keep-recs<=given
+                        (if given-clock-time
+                            (lambda (rec)
+                              (ical:date-time-locally<= rec given-clock-time))
+                          (lambda (rec)
+                            (ical:time<= (encode-time rec) given-abs-time))))
+                       (srecs (sort (seq-filter ; (1)
+                                     keep-recs<=given
+                                     recs)
+                                    :lessp #'ical:date-time<
+                                    :in-place t :reverse t))
+                       (latest-rec (car srecs)))
+
+                  (when (and latest-rec
+                             (ical:date-time< nearest-onset latest-rec)) ; (2)
+                    (setf (decoded-time-dst latest-rec)
+                          ;; if obs is a DAYLIGHT observance, latest-rec
+                          ;; represents the last moment of standard time, and
+                          ;; vice versa
+                          (not is-daylight))
+                    (setq nearest-onset latest-rec
+                          nearest-observance obs)
+                    (when (and update given-clock-time)
+                      (setq updated
+                            (icr:tz--get-updated-in given-clock-time
+                                                    latest-rec obs))))))))))
+
+      ;; We've now found the nearest observance, if there was one.
+      ;; Update `dt' as a side effect if requested.  This saves
+      ;; repeating a lot of the above in a separate function.
+      (when (and update given-clock-time nearest-observance updated)
+        ;; signal an error when `dt' does not exist if requested, so the
+        ;; nonexistence can be handled further up the stack:
+        (when (and (eq :error nonexisting)
+                   (not (ical:date-time-locally-simultaneous-p dt updated)))
+          (signal 'ical:tz-nonexistent-time
+                  (list
+                   :message
+                   (format "%d-%02d-%02d %02d:%02d:%02d does not exist in %s"
+                           (decoded-time-year dt)
+                           (decoded-time-month dt)
+                           (decoded-time-day dt)
+                           (decoded-time-hour dt)
+                           (decoded-time-minute dt)
+                           (decoded-time-second dt)
+                           (or
+                            (ical:with-property-of nearest-observance
+                                                   'ical:tzname nil value)
+                            "time zone observance"))
+                   :date-time dt
+                   :observance nearest-observance)))
+        ;; otherwise we copy `updated' over to `dt', which resets the
+        ;; clock time in `dt' if it did not exist:
+        (setf (decoded-time-zone dt) (decoded-time-zone updated))
+        (setf (decoded-time-dst dt) (decoded-time-dst updated))
+        (setf (decoded-time-second dt) (decoded-time-second updated))
+        (setf (decoded-time-minute dt) (decoded-time-minute updated))
+        (setf (decoded-time-hour dt) (decoded-time-hour updated))
+        (setf (decoded-time-day dt) (decoded-time-day updated))
+        (setf (decoded-time-month dt) (decoded-time-month updated))
+        (setf (decoded-time-year dt) (decoded-time-year updated))
+        (setf (decoded-time-weekday dt)
+              (calendar-day-of-week (ical:date-time-to-date updated))))
+
+      ;; Return the observance and onset if found, nil if not:
+      (when nearest-observance
+        (list nearest-observance nearest-onset)))))
+
+(defun icr:tz-offset-in (observance)
+  "Return the offset (in seconds) from UTC in effect during OBSERVANCE.
+
+OBSERVANCE should be an `icalendar-standard' or `icalendar-daylight'
+subcomponent of a particular `icalendar-vtimezone'.  The returned value
+is the value of its `icalendar-tzoffsetto' property."
+  (ical:with-property-of observance 'ical:tzoffsetto nil value))
+
+(defun icr:tz-decode-time (ts vtimezone)
+  "Decode Lisp timestamp TS with the appropriate offset in VTIMEZONE.
+
+VTIMEZONE should be an `icalendar-vtimezone' component node.  The correct
+observance for TS will be looked up in VTIMEZONE, TS will be decoded
+with the UTC offset of that observance, and its dst slot will be set
+based on whether the observance is an `icalendar-standard' or
+`icalendar-daylight' component.  If VTIMEZONE does not have an
+observance that applies to TS, it is decoded into UTC time.
+
+VTIMEZONE may also be an `icalendar-utc-offset'.  In this case TS is
+decoded directly into this UTC offset, and its dst slot is set to -1."
+  (let* ((observance (when (ical:vtimezone-component-p vtimezone)
+                       (car (icr:tz-observance-on ts vtimezone))))
+         (offset (cond (observance (icr:tz-offset-in observance))
+                       ((cl-typep vtimezone 'ical:utc-offset)
+                        vtimezone)
+                       (t 0))))
+
+    (ical:date-time-variant ; ensures weekday gets set, too
+     (decode-time ts offset)
+     :zone offset
+     :dst (if observance (ical:daylight-component-p observance)
+            -1))))
+
+(defun icr:tz-set-zone (dt vtimezone &optional nonexisting)
+  "Set the time zone offset and dst flag in DT based on VTIMEZONE.
+
+DT should be an `icalendar-date-time' and VTIMEZONE should be an
+`icalendar-vtimezone'.  VTIMEZONE can also be an `icalendar-utc-offset',
+in which case this value is directly set in DT's zone field (without
+changing its dst flag).  The updated DT is returned.
+
+This function generally sets only the zone and dst slots of DT, without
+changing the other slots; its main purpose is to adjust date-times
+generated from other date-times during recurrence rule calculations,
+where a different time zone observance may be in effect in the original
+date-time.  It cannot be used to re-decode a fixed point in time into a
+different time zone; for that, see `icalendar-recur-tz-decode-time'.
+
+If given, NONEXISTING is a keyword that specifies what to do if DT
+represents a clock time that does not exist according to the relevant
+observance in VTIMEZONE.  The value :error means to signal an
+\\='icalendar-tz-nonexistent-time error, and nil means to reset the
+clock time in DT to an existing one; see
+`icalendar-recur-tz-observance-on'."
+  (if (cl-typep vtimezone 'ical:utc-offset)
+      ;; This is where the recurrence rule/time zone mutual dependence
+      ;; bottoms out; don't remove this conditional!
+      (setf (decoded-time-zone dt) vtimezone)
+
+    ;; Otherwise, if there's already zone information in dt, trust it
+    ;; without looking up the observance.  This is partly a performance
+    ;; optimization (because the lookup is expensive) and partly about
+    ;; avoiding problems: looking up the observance uses the clock time
+    ;; in dt without considering the zone information, and doing this
+    ;; when dt has already been adjusted to contain valid zone
+    ;; information can invalidate that information.
+    ;;
+    ;; It's reliable to skip the lookup when dt already contains zone
+    ;; information only because `icalendar-make-date-time',
+    ;; `icalendar-date/time-add', and in particular
+    ;; `icalendar-date-time-variant' are careful to remove the UTC
+    ;; offset and DST information in the date-times they construct,
+    ;; unless provided with enough information to fill those slots.
+    (unless (and (cl-typep dt 'ical:date-time)
+                 (decoded-time-zone dt)
+                 (booleanp (decoded-time-dst dt)))
+      ;; This updates the relevant slots in dt as a side effect:
+      ;; TODO: if no observance is found, is it ever sensible to signal an error,
+      ;; instead of just leaving the zone slot unset?
+      (icr:tz-observance-on dt vtimezone t nonexisting)))
+    dt)
+
+(defun icr:tz-set-zones-in (vtimezones node)
+  "Recursively set time zone offset and dst flags in times in NODE.
+
+VTIMEZONES should be a list of the `icalendar-vtimezone' components in
+the calendar containing NODE.  NODE can be any iCalendar syntax node.  If
+NODE is a property node with an `icalendar-tzidparam' parameter and an
+`icalendar-date-time' or `icalendar-period' value, the appropriate time
+zone observance for its value is looked up in VTIMEZONES, and used to
+set the zone and dst slots in its value.  Otherwise, the function is
+called recursively on NODE's children."
+  (cond
+   ((ical:property-node-p node)
+    (ical:with-property node
+      ((ical:tzidparam :value tzid))
+      (when (and tzid (eq value-type 'ical:date-time))
+        (let* ((tz (icr:tz-for tzid vtimezones))
+               updated)
+          (cond ((eq value-type 'ical:date-time)
+                 (setq updated (icr:tz-set-zone value tz)))
+                ((eq value-type 'ical:period)
+                 (setq updated
+                       (ical:make-period
+                        (icr:tz-set-zone (ical:period-start value) tz)
+                        :end
+                        (if (ical:period--defined-end value)
+                            (icr:tz-set-zone (ical:period--defined-end value) tz)
+                          (ical:period-end value tz))
+                        :duration (ical:period-dur-value value)))))
+          (ical:ast-node-set-value value-node updated)))))
+   ((ical:component-node-p node) ; includes VCALENDAR nodes
+    (mapc (apply-partially #'icr:tz-set-zones-in vtimezones)
+          (ical:ast-node-children node)))
+   (t nil)))
+
+(defun icr:tzname-on (dt vtimezone)
+  "Return the name of the time zone observance in effect on DT in VTIMEZONE.
+
+DT should be an `icalendar-date' or `icalendar-date-time'.  VTIMEZONE
+should be the `icalendar-vtimezone' component in which to interpret DT.
+
+The observance in effect on DT within VTIMEZONE is computed.  The
+returned value is the value of the `icalendar-tzname' property of this
+observance."
+  (when-let* ((obs/onset (icr:tz-observance-on dt vtimezone))
+              (observance (car obs/onset)))
+    (ical:with-property-of observance 'ical:tzname)))
+
+(defconst icr:-tz-warning
+  "This time zone information was inferred from incomplete system information; it should be correct for the date-times within this calendar file referencing this zone, but you should not rely on it more widely.")
+
+(defconst icr:-emacs-local-tzid
+  "Emacs_Local_")
+
+(defun icr:-tz-info-sexp-p (_ sexp)
+  "Validate that SEXP gives time zone info like from `calendar-current-time-zone'."
+  (and (listp sexp)
+       (length= sexp 8)
+       (let ((utc-diff (nth 0 sexp))
+             (dst-offset (nth 1 sexp))
+             (std-zone (nth 2 sexp))
+             (dst-zone (nth 3 sexp))
+             (dst-starts (nth 4 sexp))
+             (dst-ends (nth 5 sexp))
+             (dst-starts-time (nth 6 sexp))
+             (dst-ends-time (nth 7 sexp)))
+         (and
+          (integerp utc-diff) (< (abs utc-diff) (* 60 24))
+          (integerp dst-offset) (< (abs utc-diff) (* 60 24))
+          (stringp std-zone)
+          (stringp dst-zone)
+          (or (and (listp dst-starts) (memq 'year (flatten-list dst-starts)))
+              (and (null dst-starts) (equal std-zone dst-zone)))
+          (or (and (listp dst-ends) (memq 'year (flatten-list dst-ends)))
+              (and (null dst-ends) (equal std-zone dst-zone)))
+          (or (and (integerp dst-starts-time) (< (abs dst-starts-time) (* 60 24)))
+              (null dst-starts-time))
+          (or (and (integerp dst-ends-time) (< (abs dst-ends-time) (* 60 24)))
+              (null dst-ends-time))))))
+
+(defun icr:current-tz-to-vtimezone (&optional tz tzid start-year)
+  "Convert TZ to an `icalendar-vtimezone'.
+
+TZ defaults to the output of `calendar-current-time-zone'; if specified,
+it should be a list of the same form as that function returns.
+Depending on TZ, this function might signal the following errors:
+
+`icalendar-tz-data-insufficient' if the data in TZ is not complete
+  enough to determine time zone rules.
+`icalendar-tz-unsupported' if the data in TZ cannot be expressed as an
+  RFC5545 `icalendar-rrule' property.
+
+TZID, if specified, should be a string to identify this time zone; it
+defaults to `icalendar-recur--emacs-local-tzid' plus the name of the
+standard observance according to `calendar-current-time-zone'.
+
+START-YEAR, if specified, should be an integer giving the year in which
+to start the observances in the time zone.  It defaults to 1970."
+  (when (and tz (not (icr:-tz-info-sexp-p nil tz)))
+    (signal 'ical:tz-data-insufficient
+            (list :tz tz
+                  :level 2
+                  :message
+                  "Badly formed TZ data; see `calendar-current-time-zone'")))
+  (let* ((tzdata (or tz (calendar-current-time-zone)))
+         (std-offset (* 60 (nth 0 tzdata)))
+         (dst-offset (+ std-offset
+                        (* 60 (nth 1 tzdata))))
+         (std-name (nth 2 tzdata))
+         (dst-name (nth 3 tzdata))
+         (dst-starts (nth 4 tzdata))
+         (dst-ends (nth 5 tzdata))
+         (dst-start-minutes (nth 6 tzdata))
+         (dst-end-minutes (nth 7 tzdata)))
+
+    (unless (and std-offset
+                 (or (equal std-name dst-name)
+                     (and dst-starts dst-ends dst-start-minutes dst-end-minutes)))
+      (signal 'ical:tz-data-insufficient
+              (list :tz tz :level 2
+                    :message "Unable to create VTIMEZONE from TZ")))
+
+    (if (equal std-name dst-name)
+        ;; Local time zone doesn't use DST:
+        (ical:make-vtimezone
+         (ical:tzid (or tzid (concat icr:-emacs-local-tzid std-name)))
+         (ical:make-standard
+          (ical:tzname std-name)
+          (ical:dtstart (ical:make-date-time :year (or start-year 1970)
+                                             :month 1 :day 1
+                                             :hour 0 :minute 0 :second 0))
+          (ical:tzoffsetfrom std-offset)
+          (ical:tzoffsetto std-offset)
+          (ical:comment icr:-tz-warning)))
+
+      ;; Otherwise we can provide both STANDARD and DAYLIGHT subcomponents:
+      (let* ((std->dst-rule
+              (if (eq (car dst-starts) 'calendar-nth-named-day)
+                  `((FREQ YEARLY)
+                    (BYMONTH (,(nth 3 dst-starts)))
+                    (BYDAY (,(cons (nth 2 dst-starts)
+                                   (nth 1 dst-starts)))))
+                ;; The only other rules that `calendar-current-time-zone'
+                ;; can return are based on the Persian calendar, which we
+                ;; cannot express in an `icalendar-recur' value, at least
+                ;; pending an implementation of RFC 7529
+                (signal 'ical:tz-unsupported
+                        (list :tz tz
+                              :level 2
+                              :message
+                              (format "Unable to export DST rule for time zone: %s"
+                                      dst-starts)))))
+             (dst-start-date (calendar-dlet ((year (or start-year 1970)))
+                               (eval dst-starts t)))
+             (dst-start
+              (ical:date-to-date-time dst-start-date
+                                      :hour (/ dst-start-minutes 60)
+                                      :minute (mod dst-start-minutes 60)
+                                      :second 0))
+             (dst->std-rule
+              (if (eq (car dst-ends) 'calendar-nth-named-day)
+                  `((FREQ YEARLY)
+                    (BYMONTH (,(nth 3 dst-ends)))
+                    (BYDAY (,(cons (nth 2 dst-ends)
+                                   (nth 1 dst-ends)))))
+                (signal 'ical:tz-unsupported
+                        (list :tz tz
+                              :level 2
+                              :message
+                              (format "Unable to export DST rule for time zone: %s"
+                                      dst-ends)))))
+             (std-start-date (calendar-dlet ((year (1- (or start-year 1970))))
+                               (eval dst-ends t)))
+             (std-start
+              (ical:date-to-date-time std-start-date
+                                      :hour (/ dst-end-minutes 60)
+                                      :minute (mod dst-end-minutes 60)
+                                      :second 0)))
+
+        (ical:make-vtimezone
+         (ical:tzid (or tzid (concat icr:-emacs-local-tzid std-name)))
+         (ical:make-standard
+          (ical:tzname std-name)
+          (ical:dtstart std-start)
+          (ical:rrule dst->std-rule)
+          (ical:tzoffsetfrom dst-offset)
+          (ical:tzoffsetto std-offset)
+          (ical:comment icr:-tz-warning))
+         (ical:make-daylight
+          (ical:tzname dst-name)
+          (ical:dtstart dst-start)
+          (ical:rrule std->dst-rule)
+          (ical:tzoffsetfrom std-offset)
+          (ical:tzoffsetto dst-offset)
+          (ical:comment icr:-tz-warning)))))))
+
+(provide 'icalendar-recur)
+
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-") ("icr:" . "icalendar-recur-"))
+;; End:
+;;; icalendar-recur.el ends here
diff --git a/lisp/calendar/icalendar-utils.el b/lisp/calendar/icalendar-utils.el
new file mode 100644
index 00000000000..3f8e9d085c2
--- /dev/null
+++ b/lisp/calendar/icalendar-utils.el
@@ -0,0 +1,754 @@
+;;; icalendar-utils.el --- iCalendar utility functions  -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024 Richard Lawrence
+
+;; Author: Richard Lawrence <rwl@recursewithless.net>
+;; Created: January 2025
+;; Keywords: calendar
+
+;; This file is part of GNU Emacs.
+
+;; This file is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This file is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this file.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; This file contains a variety of utility functions to work with
+;; iCalendar data which are used throughout the rest of the iCalendar
+;; library.  Most of the functions here deal with calendar and clock
+;; arithmetic, and help smooth over the type distinction between plain
+;; dates and date-times.
+
+;;; Code:
+(require 'cl-lib)
+(require 'calendar)
+(eval-when-compile (require 'icalendar-macs))
+(require 'icalendar-parser)
+
+;; Accessors for commonly used properties
+
+(defun ical:component-dtstart (component)
+  "Return the value of the `icalendar-dtstart' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:dtstart nil value))
+
+(defun ical:component-dtend (component)
+  "Return the value of the `icalendar-dtend' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:dtend nil value))
+
+(defun ical:component-rdate (component)
+  "Return the value of the `icalendar-rdate' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:rdate nil value))
+
+(defun ical:component-summary (component)
+  "Return the value of the `icalendar-summary' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:summary nil value))
+
+(defun ical:component-description (component)
+  "Return the value of the `icalendar-description' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:description nil value))
+
+(defun ical:component-tzname (component)
+  "Return the value of the `icalendar-tzname' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:tzname nil value))
+
+(defun ical:component-uid (component)
+  "Return the value of the `icalendar-uid' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:uid nil value))
+
+(defun ical:component-url (component)
+  "Return the value of the `icalendar-url' property of COMPONENT.
+COMPONENT can be any component node."
+  (ical:with-property-of component 'ical:url nil value))
+
+(defun ical:property-tzid (property)
+  "Return the value of the `icalendar-tzid' parameter of PROPERTY."
+  (ical:with-param-of property 'ical:tzidparam nil value))
+
+;; String manipulation
+(defun ical:trimp (s &optional trim-left trim-right)
+  "Like `string-trim', but return nil if the trimmed string is empty."
+  (when (and s (stringp s))
+    (let ((trimmed (string-trim s trim-left trim-right)))
+      (unless (equal "" trimmed) trimmed))))
+
+(defun ical:strip-mailto (s)
+  "Remove \"mailto:\" case-insensitively from the start of S."
+  (let ((case-fold-search t))
+    (replace-regexp-in-string "^mailto:" "" s)))
+
+
+;; Date/time
+
+;; N.B. Notation: "date/time" is used in function names when a function
+;; can accept either `icalendar-date' or `icalendar-date-time' values;
+;; in contrast, "date-time" means it accepts *only*
+;; `icalendar-date-time' values, not plain dates.
+;; TODO: turn all the 'date/time' functions into methods dispatched by
+;; type?
+
+(defun ical:date-time-to-date (dt)
+  "Convert an `icalendar-date-time' value DT to an `icalendar-date'."
+  (list (decoded-time-month dt)
+        (decoded-time-day dt)
+        (decoded-time-year dt)))
+
+(cl-defun ical:date-to-date-time (dt &key (hour 0) (minute 0) (second 0) (tz nil))
+  "Convert an `icalendar-date' value DT to an `icalendar-date-time'.
+
+The following keyword arguments are accepted:
+  :hour, :minute, :second - integers representing a local clock time on date DT
+  :tz - an `icalendar-vtimezone' in which to interpret this clock time
+
+If these arguments are all unspecified, the hour, minute, and second
+slots of the returned date-time will be zero, and it will contain no
+time zone information.  See `icalendar-make-date-time' for more on these
+arguments."
+  (ical:make-date-time
+   :year (calendar-extract-year dt)
+   :month (calendar-extract-month dt)
+   :day (calendar-extract-day dt)
+   :hour hour
+   :minute minute
+   :second second
+   :tz tz))
+
+(defun ical:date/time-to-date (dt)
+  "Extract a Gregorian date from DT.
+An `icalendar-date' value is returned unchanged.
+An `icalendar-date-time' value is converted to an `icalendar-date'."
+  (if (cl-typep dt 'ical:date)
+      dt
+    (ical:date-time-to-date dt)))
+
+;; Type-aware accessors for date/time slots that work for both ical:date
+;; and ical:date-time:
+;; NOTE: cl-typecase ONLY works here if dt is valid according to
+;; `ical:-decoded-date-time-p'!  May need to adjust this if it's
+;; necessary to work with incomplete decoded-times
+(defun ical:date/time-year (dt)
+  "Return DT's year slot.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (cl-typecase dt
+    (ical:date (calendar-extract-year dt))
+    (ical:date-time (decoded-time-year dt))))
+
+(defun ical:date/time-month (dt)
+  "Return DT's month slot.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (cl-typecase dt
+    (ical:date (calendar-extract-month dt))
+    (ical:date-time (decoded-time-month dt))))
+
+(defun ical:date/time-monthday (dt)
+  "Return DT's day of the month slot.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (cl-typecase dt
+    (ical:date (calendar-extract-day dt))
+    (ical:date-time (decoded-time-day dt))))
+
+(defun ical:date/time-weekno (dt &optional weekstart)
+  "Return DT's ISO week number.
+DT may be either an `icalendar-date' or an `icalendar-date-time'.
+WEEKSTART defaults to 1; it represents the day which starts the week,
+and should be an integer between 0 (= Sunday) and 6 (= Saturday)."
+  ;; TODO: Add support for weekstart.
+  ;; calendar-iso-from-absolute doesn't support this yet.
+  (when (and weekstart (not (= weekstart 1)))
+    (error "Support for WEEKSTART other than 1 (=Monday) not implemented yet"))
+  (let* ((gdate (ical:date/time-to-date dt))
+         (isodate (calendar-iso-from-absolute
+                   (calendar-absolute-from-gregorian gdate)))
+         (weekno (car isodate)))
+    weekno))
+
+(defun ical:date/time-weekday (dt)
+  "Return DT's day of the week.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (cl-typecase dt
+    (ical:date (calendar-day-of-week dt))
+    (ical:date-time
+     (or (decoded-time-weekday dt)
+         ;; compensate for possibly-nil weekday slot if the date-time
+         ;; has been constructed by `make-decoded-time'; cf. comment
+         ;; in `icalendar--decoded-date-time-p':
+         (calendar-day-of-week (ical:date-time-to-date dt))))))
+
+(defun ical:date/time-hour (dt)
+  "Return DT's hour slot, or nil.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (when (cl-typep dt 'ical:date-time)
+    (decoded-time-hour dt)))
+
+(defun ical:date/time-minute (dt)
+  "Return DT's minute slot, or nil.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (when (cl-typep dt 'ical:date-time)
+    (decoded-time-minute dt)))
+
+(defun ical:date/time-second (dt)
+  "Return DT's second slot, or nil.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (when (cl-typep dt 'ical:date-time)
+    (decoded-time-second dt)))
+
+(defun ical:date/time-zone (dt)
+  "Return DT's time zone slot, or nil.
+DT may be either an `icalendar-date' or an `icalendar-date-time'."
+  (when (cl-typep dt 'ical:date-time)
+    (decoded-time-zone dt)))
+
+;;; Date/time comparisons and arithmetic:
+(defun ical:date< (dt1 dt2)
+  "Return non-nil if date DT1 is strictly earlier than date DT2.
+DT1 and DT2 must both be `icalendar-date' values of the form (MONTH DAY YEAR)."
+  (< (calendar-absolute-from-gregorian dt1)
+     (calendar-absolute-from-gregorian dt2)))
+
+(defun ical:date<= (dt1 dt2)
+  "Return non-nil if date DT1 is earlier than or the same date as DT2.
+DT1 and DT2 must both be `icalendar-date' values of the form (MONTH DAY YEAR)."
+  (or (calendar-date-equal dt1 dt2) (ical:date< dt1 dt2)))
+
+(defun ical:date-time-locally-earlier (dt1 dt2 &optional or-equal)
+  "Return non-nil if date-time DT1 is locally earlier than DT2.
+
+Unlike `icalendar-date-time<', this function assumes both times are
+local to some time zone and does not consider their zone information.
+
+If OR-EQUAL is non-nil, this function acts like `<=' rather than `<':
+it will return non-nil if DT1 and DT2 are locally the same time."
+  (let ((year1 (decoded-time-year dt1))
+        (year2 (decoded-time-year dt2))
+        (month1 (decoded-time-month dt1))
+        (month2 (decoded-time-month dt2))
+        (day1 (decoded-time-day dt1))
+        (day2 (decoded-time-day dt2))
+        (hour1 (decoded-time-hour dt1))
+        (hour2 (decoded-time-hour dt2))
+        (minute1 (decoded-time-minute dt1))
+        (minute2 (decoded-time-minute dt2))
+        (second1 (decoded-time-second dt1))
+        (second2 (decoded-time-second dt2)))
+    (or (< year1 year2)
+        (and (= year1 year2)
+             (or (< month1 month2)
+                 (and (= month1 month2)
+                      (or (< day1 day2)
+                          (and (= day1 day2)
+                               (or (< hour1 hour2)
+                                   (and (= hour1 hour2)
+                                        (or (< minute1 minute2)
+                                            (and (= minute1 minute2)
+                                                 (if or-equal
+                                                     (<= second1 second2)
+                                                   (< second1 second2))))))))))))))
+
+(defun ical:date-time-locally< (dt1 dt2)
+  "Return non-nil if date-time DT1 is locally strictly earlier than DT2.
+
+Unlike `icalendar-date-time<', this function assumes both times are
+local to some time zone and does not consider their zone information."
+  (ical:date-time-locally-earlier dt1 dt2 nil))
+
+(defun ical:date-time-locally<= (dt1 dt2)
+  "Return non-nil if date-time DT1 is locally earlier than, or equal to, DT2.
+
+Unlike `icalendar-date-time<=', this function assumes both times are
+local to some time zone and does not consider their zone information."
+  (ical:date-time-locally-earlier dt1 dt2 t))
+
+(defun ical:date-time< (dt1 dt2)
+  "Return non-nil if date-time DT1 is strictly earlier than DT2.
+
+DT1 and DT2 must both be decoded times, and either both or neither
+should have time zone information.
+
+If one has a time zone offset and the other does not, the offset
+returned from `current-time-zone' is used as the missing offset; if
+`current-time-zone' cannot provide this information, an error is
+signaled."
+  (let ((zone1 (decoded-time-zone dt1))
+        (zone2 (decoded-time-zone dt2)))
+    (cond ((and (integerp zone1) (integerp zone2))
+           (time-less-p (encode-time dt1) (encode-time dt2)))
+          ((and (null zone1) (null zone2))
+           (ical:date-time-locally< dt1 dt2))
+          (t
+           ;; Cf. RFC5545 Sec. 3.3.5:
+           ;; "The recipient of an iCalendar object with a property value
+           ;; consisting of a local time, without any relative time zone
+           ;; information, SHOULD interpret the value as being fixed to whatever
+           ;; time zone the "ATTENDEE" is in at any given moment.  This means
+           ;; that two "Attendees", in different time zones, receiving the same
+           ;; event definition as a floating time, may be participating in the
+           ;; event at different actual times.  Floating time SHOULD only be
+           ;; used where that is the reasonable behavior."
+           ;; I'm interpreting this to mean that if we get here, where
+           ;; one date-time has zone information and the other doesn't,
+           ;; we should use the offset from (current-time-zone).
+           (let* ((user-tz (current-time-zone))
+                  (user-offset (car user-tz))
+                  (dt1z (ical:date-time-variant dt1 :zone (or zone1 user-offset)))
+                  (dt2z (ical:date-time-variant dt2 :zone (or zone2 user-offset))))
+             (if user-offset
+                 (time-less-p (encode-time dt1z) (encode-time dt2z))
+               (error "Too little zone information for comparison: %s %s"
+                      dt1 dt2)))))))
+
+;; Two different notions of equality are relevant to decoded times:
+;; strict equality (`icalendar-date-time=') of all slots, or
+;; simultaneity (`icalendar-date-time-simultaneous-p').
+;; Most tests probably want the strict notion, because it distinguishes
+;; between simultaneous events decoded into different time zones,
+;; whereas most user-facing functions (e.g. sorting events by date and time)
+;; probably want simultaneity.
+(defun ical:date-time= (dt1 dt2)
+  "Return non-nil if DT1 and DT2 are decoded-times with identical slot values.
+
+Note that this function returns nil if DT1 and DT2 represent times in
+different time zones, even if they are simultaneous.  For the latter, see
+`icalendar-date-time-simultaneous-p'."
+  (equal dt1 dt2))
+
+(defun ical:date-time-locally-simultaneous-p (dt1 dt2)
+  "Return non-nil if DT1 and DT2 are locally simultaneous date-times.
+Note that this function ignores zone information in dt1 and dt2.  It
+returns non-nil if DT1 and DT2 represent the same clock time in
+different time zones, even if they encode to different absolute times."
+  (and (eq (decoded-time-year dt1)   (decoded-time-year dt2))
+       (eq (decoded-time-month dt1)  (decoded-time-month dt2))
+       (eq (decoded-time-day dt1)    (decoded-time-day dt2))
+       (eq (decoded-time-hour dt1)   (decoded-time-hour dt2))
+       (eq (decoded-time-minute dt1) (decoded-time-minute dt2))
+       (eq (decoded-time-second dt1) (decoded-time-second dt2))))
+
+(defun ical:date-time-simultaneous-p (dt1 dt2)
+  "Return non-nil if DT1 and DT2 are simultaneous date-times.
+
+This function returns non-nil if DT1 and DT2 encode to the same Lisp
+timestamp.  Thus they can count as simultaneous even if they represent
+times in different timezones.  If both date-times lack an offset from
+UTC, they are treated as simultaneous if they encode to the same
+timestamp in UTC.
+
+If only one date-time has an offset, they are treated as
+non-simultaneous if they represent different clock times according to
+`icalendar-date-time-locally-simultaneous-p'.  Otherwise an error is
+signaled."
+  (let ((zone1 (decoded-time-zone dt1))
+        (zone2 (decoded-time-zone dt2)))
+    (cond ((and (integerp zone1) (integerp zone2))
+           (time-equal-p (encode-time dt1) (encode-time dt2)))
+          ((and (null zone1) (null zone2))
+           (time-equal-p (encode-time (ical:date-time-variant dt1 :zone 0))
+                         (encode-time (ical:date-time-variant dt2 :zone 0))))
+          (t
+           ;; Best effort:
+           ;; TODO: I'm not convinced this is the right thing to do yet.
+           ;; Might want to be stricter here and fix the problem of comparing
+           ;; times with and without zone information elsewhere.
+           (if (ical:date-time-locally-simultaneous-p dt1 dt2)
+               (error "Missing zone information: %s %s" dt1 dt2)
+             nil)))))
+
+(defun ical:date-time<= (dt1 dt2)
+  "Return non-nil if DT1 is earlier than, or simultaneous with, DT2.
+DT1 and DT2 must both be decoded times, and either both or neither must have
+time zone information."
+  (or (ical:date-time< dt1 dt2)
+      (ical:date-time-simultaneous-p dt1 dt2)))
+
+(defun ical:date/time< (dt1 dt2)
+  "Return non-nil if DT1 is strictly earlier than DT2.
+DT1 and DT2 must be either `icalendar-date' or `icalendar-date-time'
+values.  If they are not of the same type, only the date in the
+`icalendar-date-time' value will be considered."
+  (cl-typecase dt1
+    (ical:date
+     (if (cl-typep dt2 'ical:date)
+         (ical:date< dt1 dt2)
+       (ical:date< dt1 (ical:date-time-to-date dt2))))
+
+    (ical:date-time
+     (if (cl-typep dt2 'ical:date-time)
+         (ical:date-time< dt1 dt2)
+       (ical:date< (ical:date-time-to-date dt1) dt2)))))
+
+(defun ical:date/time<= (dt1 dt2)
+  "Return non-nil if DT1 is earlier than or simultaneous to DT2.
+DT1 and DT2 must be either `icalendar-date' or `icalendar-date-time'
+values.  If they are not of the same type, only the date in the
+`icalendar-date-time' value will be considered."
+  (cl-typecase dt1
+    (ical:date
+     (if (cl-typep dt2 'ical:date)
+         (ical:date<= dt1 dt2)
+       (ical:date<= dt1 (ical:date-time-to-date dt2))))
+
+    (ical:date-time
+     (if (cl-typep dt2 'ical:date-time)
+         (ical:date-time<= dt1 dt2)
+       (ical:date<= (ical:date-time-to-date dt1) dt2)))))
+
+(defun ical:date/time-min (&rest dts)
+  "Return the earliest date or date-time among DTS.
+
+The DTS may be any `icalendar-date' or `icalendar-date-time' values, and
+will be ordered by `icalendar-date/time<='."
+  (car (sort dts :lessp #'ical:date/time<=)))
+
+(defun ical:date/time-max (&rest dts)
+  "Return the latest date or date-time among DTS.
+
+The DTS may be any `icalendar-date' or `icalendar-date-time' values, and
+will be ordered by `icalendar-date/time<='."
+  (car (sort dts :reverse t :lessp #'ical:date/time<=)))
+
+(defun ical:date-add (date unit n)
+  "Add N UNITs to DATE.
+
+UNIT should be `:year', `:month', `:week', or `:day'; time units will be
+ignored.  N may be a positive or negative integer."
+  (if (memq unit '(:hour :minute :second))
+      date
+    (let* ((dt (ical:make-date-time :year (calendar-extract-year date)
+                                    :month (calendar-extract-month date)
+                                    :day (calendar-extract-day date)))
+           (delta (if (eq unit :week)
+                      (make-decoded-time :day (* 7 n))
+                    (make-decoded-time unit n)))
+           (new-dt (decoded-time-add dt delta)))
+      (ical:date-time-to-date new-dt))))
+
+(defun ical:date-time-add (dt delta &optional vtimezone)
+  "Like `decoded-time-add', but also updates weekday and time zone slots.
+
+DT and DELTA should be `icalendar-date-time' values (decoded times), as
+in `decoded-time-add'.  VTIMEZONE, if given, should be an
+`icalendar-vtimezone'.  The resulting date-time will be given the offset
+determined by VTIMEZONE at the local time determined by adding DELTA to
+DT.
+
+This function assumes that time units in DELTA larger than an hour
+should not affect the local clock time in the result, even when crossing
+an observance boundary in VTIMEZONE.  This means that e.g. if DT is at
+9AM daylight savings time on the day before the transition to standard
+time, then the result of adding a DELTA of two days will be at 9AM
+standard time, even though this is not exactly 48 hours later.  Adding a
+DELTA of 48 hours, on the other hand, will result in a time exactly 48
+hours later, but at a different local time."
+  (require 'icalendar-recur) ; for icr:tz-decode-time; avoids circular requires
+  (declare-function icalendar-recur-tz-decode-time "icalendar-recur")
+
+  (if (not vtimezone)
+      ;; the simple case: we have no time zone info, so just use
+      ;; `decoded-time-add':
+      (let ((sum (decoded-time-add dt delta)))
+        (ical:date-time-variant sum))
+    ;; `decoded-time-add' does not take time zone shifts into account,
+    ;; so we need to do the adjustment ourselves.  We first add the units
+    ;; larger than an hour using `decoded-time-add', holding the clock
+    ;; time fixed, as described in the docstring.  Then we add the time
+    ;; units as a fixed number of seconds and re-decode the resulting
+    ;; absolute time into the time zone.
+    (let* ((cal-delta (make-decoded-time :year (or (decoded-time-year delta) 0)
+                                         :month (or (decoded-time-month delta) 0)
+                                         :day (or (decoded-time-day delta) 0)))
+           (cal-sum (decoded-time-add dt cal-delta))
+           (dt-w/zone (ical:date-time-variant cal-sum
+                                              :tz vtimezone))
+           (secs-delta (+ (or (decoded-time-second delta) 0)
+                          (* 60 (or (decoded-time-minute delta) 0))
+                          (* 60 60 (or (decoded-time-hour delta) 0))))
+           (sum-ts (time-add (encode-time dt-w/zone) secs-delta)))
+      (icalendar-recur-tz-decode-time sum-ts vtimezone))))
+
+;; TODO: rework so that it's possible to add dur-values to plain dates.
+;; Perhaps rename this to "date/time-inc" or so, or use kwargs to allow
+;; multiple units, or...
+(defun ical:date/time-add (dt unit n &optional vtimezone)
+  "Add N UNITs to DT.
+
+DT should be an `icalendar-date' or `icalendar-date-time'.  UNIT should
+be `:year', `:month', `:week', `:day', `:hour', `:minute', or `:second';
+time units will be ignored if DT is an `icalendar-date'.  N may be a
+positive or negative integer."
+  (cl-typecase dt
+    (ical:date-time
+     (let ((delta (if (eq unit :week) (make-decoded-time :day (* 7 n))
+                    (make-decoded-time unit n))))
+       (ical:date-time-add dt delta vtimezone)))
+    (ical:date (ical:date-add dt unit n))))
+
+(defun ical:date/time-add-duration (start duration &optional vtimezone)
+  "Return the end date(-time) which is a length of DURATION after START.
+
+START should be an `icalendar-date' or `icalendar-date-time'; the
+returned value will be of the same type as START.  DURATION should be an
+`icalendar-dur-value'.  VTIMEZONE, if specified, should be the
+`icalendar-vtimezone' representing the time zone of START."
+  (if (integerp duration)
+      ;; number of weeks:
+      (setq duration (make-decoded-time :day (* 7 duration))))
+  (cl-typecase start
+    (ical:date
+     (ical:date-time-to-date
+      (ical:date-time-add (ical:date-to-date-time start) duration)))
+    (ical:date-time
+     (ical:date-time-add start duration vtimezone))))
+
+(defun ical:duration-between (start end)
+  "Return the duration between START and END.
+
+START should be an `icalendar-date' or `icalendar-date-time'; END must
+be of the same type as START.  The returned value is an
+`icalendar-dur-value', i.e., a time delta in the sense of
+`decoded-time-add'."
+  (cl-typecase start
+    (ical:date
+     (make-decoded-time :day (- (calendar-absolute-from-gregorian end)
+                                (calendar-absolute-from-gregorian start))))
+    (ical:date-time
+     (let* ((start-abs (time-convert (encode-time start) 'integer))
+            (end-abs (time-convert (encode-time end) 'integer))
+            (dur-secs (- end-abs start-abs))
+            (days (/ dur-secs (* 60 60 24)))
+            (dur-nodays (mod dur-secs (* 60 60 24)))
+            (hours (/ dur-nodays (* 60 60)))
+            (dur-nohours (mod dur-nodays (* 60 60)))
+            (minutes (/ dur-nohours 60))
+            (seconds (mod dur-nohours 60)))
+       (make-decoded-time :day days
+                          :hour hours :minute minutes :second seconds)))))
+
+(defun ical:date/time-to-local (dt)
+  "Reinterpret DT in Emacs local time if necessary.
+If DT is an `icalendar-date-time', encode and re-decode it into Emacs
+local time.  If DT is an `icalendar-date', return it unchanged."
+  (cl-typecase dt
+    (ical:date dt)
+    (ical:date-time
+     (ical:date-time-variant ; ensure weekday is present too
+      (decode-time (encode-time dt))))))
+
+(defun ical:dates-until (start end &optional locally)
+  "Return a list of `icalendar-date' values between START and END.
+
+START and END may be either `icalendar-date' or `icalendar-date-time'
+values.  START is an inclusive lower bound, and END is an exclusive
+upper bound.  (Note, however, that if END is a date-time and its time is
+after midnight, then its date will be included in the returned list.)
+
+If LOCALLY is non-nil and START and END are date-times, these will be
+interpreted into Emacs local time, so that the dates returned are valid
+for the local time zone."
+  (require 'icalendar-recur) ; avoid circular requires
+  (declare-function icalendar-recur-subintervals-to-dates "icalendar-recur")
+
+  (when locally
+    (when (cl-typep start 'ical:date-time)
+      (setq start (ical:date/time-to-local start)))
+    (when (cl-typep end 'ical:date-time)
+      (setq end (ical:date/time-to-local end))))
+  (cl-typecase start
+    (ical:date
+     (cl-typecase end
+       (ical:date
+        (icalendar-recur-subintervals-to-dates
+         (list (list (ical:date-to-date-time start)
+                     (ical:date-to-date-time end)))))
+       (ical:date-time
+        (icalendar-recur-subintervals-to-dates
+         (list (list (ical:date-to-date-time start) end))))))
+    (ical:date-time
+     (cl-typecase end
+       (ical:date
+        (icalendar-recur-subintervals-to-dates
+         (list (list start (ical:date-to-date-time end)))))
+       (ical:date-time
+        (icalendar-recur-subintervals-to-dates (list (list start end))))))))
+
+
+(cl-defun ical:make-date-time (&key second minute hour day month year
+                                    (dst -1 given-dst) zone tz)
+  "Make an `icalendar-date-time' from the given keyword arguments.
+
+This function is like `make-decoded-time', except that it automatically
+sets the weekday slot set based on the date arguments, and it accepts an
+additional keyword argument: `:tz'.  If provided, its value should be an
+`icalendar-vtimezone', and the `:zone' and `:dst' arguments should not
+be provided.  In this case, the zone and dst slots in the returned
+date-time will be adjusted to the correct values in the given time zone
+for the local time represented by the remaining arguments."
+  (when (and tz (or zone given-dst))
+    (error "Possibly conflicting time zone data in args"))
+  (apply #'ical:date-time-variant (make-decoded-time)
+         `(:second ,second :minute ,minute :hour ,hour
+           :day ,day :month ,month :year ,year
+           ;; Don't pass these keywords unless they were given explicitly.
+           ;; TODO: is there a cleaner way to write this?
+           ,@(when tz (list :tz tz))
+           ,@(when given-dst (list :dst dst))
+           ,@(when zone (list :zone zone)))))
+
+(cl-defun ical:date-time-variant (dt &key second minute hour
+                                          day month year
+                                          (dst -1 given-dst)
+                                          (zone nil given-zone)
+                                          tz)
+  "Return a variant of DT with slots modified as in the given arguments.
+
+DT should be an `icalendar-date-time'; the keyword arguments have the
+same meanings as in `make-decoded-time'.  The returned variant will have
+slot values as specified by the arguments or copied from DT, except that
+the weekday slot will be updated if necessary, and the zone and dst
+fields will not be set unless given explicitly (because varying the date
+and clock time generally invalidates the time zone information in DT).
+
+One additional keyword argument is accepted: `:tz'.  If provided, its
+value should be an `icalendar-vtimezone', an `icalendar-utc-offset', or
+the symbol \\='preserve.  If it is a time zone component, the zone and
+dst slots in the returned variant will be adjusted to the correct
+values in the given time zone for the local time represented by the
+variant.  If it is a UTC offset, the variant's zone slot will contain
+this value, but its dst slot will not be adjusted.  If it is the symbol
+\\='preserve, then both the zone and dst fields are copied from DT into
+the variant."
+  (require 'icalendar-recur) ; for icr:tz-set-zone; avoids circular requires
+  (declare-function icalendar-recur-tz-set-zone "icalendar-recur")
+
+  (let ((variant
+         (make-decoded-time :second (or second (decoded-time-second dt))
+                            :minute (or minute (decoded-time-minute dt))
+                            :hour (or hour (decoded-time-hour dt))
+                            :day (or day (decoded-time-day dt))
+                            :month (or month (decoded-time-month dt))
+                            :year (or year (decoded-time-year dt))
+                            ;; For zone and dst slots, trust the value
+                            ;; if explicitly specified or explicitly
+                            ;; requested to preserve, but not otherwise
+                            :dst (cond (given-dst dst)
+                                       ((eq 'preserve tz) (decoded-time-dst dt))
+                                       (t -1))
+                            :zone (cond (given-zone zone)
+                                        ((eq 'preserve tz) (decoded-time-zone dt))
+                                        (t nil)))))
+    ;; update weekday slot when possible, since it depends on the date
+    ;; slots, which might have changed.  (It's not always possible,
+    ;; because pure time values are also represented as decoded-times,
+    ;; with empty date slots.)
+    (unless (or (null (decoded-time-year variant))
+                (null (decoded-time-month variant))
+                (null (decoded-time-day variant)))
+      (setf (decoded-time-weekday variant)
+            (calendar-day-of-week (ical:date-time-to-date variant))))
+    ;; if given a time zone or UTC offset, update zone and dst slots,
+    ;; which also might have changed:
+    (when (and tz (not (eq 'preserve tz)))
+      (icalendar-recur-tz-set-zone variant tz))
+    variant))
+
+(defun ical:date/time-in-period-p (dt period &optional vtimezone)
+  "Return non-nil if DT occurs within PERIOD.
+
+DT can be an `icalendar-date' or `icalendar-date-time' value.  PERIOD
+should be an `icalendar-period' value.  VTIMEZONE, if given, is passed
+to `icalendar-period-end' to compute the end time of the period if it
+was not specified explicitly."
+  (and (ical:date/time<= (ical:period-start period) dt)
+       (ical:date/time< dt (ical:period-end period vtimezone))))
+
+;; TODO: surely this exists already?
+(defun ical:time<= (a b)
+  "Compare two Lisp timestamps A and B: is A <= B?"
+  (or (time-equal-p a b)
+      (time-less-p a b)))
+
+(defun ical:number-of-weeks (year &optional weekstart)
+  "Return the number of weeks in (Gregorian) YEAR.
+
+RFC5545 defines week 1 as the first week to include at least four days
+in the year.  Weeks are assumed to start on Monday (= 1) unless WEEKSTART
+is specified, in which case it should be an integer between 0 (= Sunday)
+and 6 (= Saturday)."
+  ;; There are 53 weeks in a year if Jan 1 is the fourth day after
+  ;; WEEKSTART, e.g. if the week starts on Monday and Jan 1 is a
+  ;; Thursday, or in a leap year if Jan 1 is the third day after WEEKSTART
+  (let* ((jan1wd (calendar-day-of-week (list 1 1 year)))
+         (delta (mod (- jan1wd (or weekstart 1)) 7)))
+    (if (or (= 4 delta)
+            (and (= 3 delta) (calendar-leap-year-p year)))
+        53
+      52)))
+
+(defun ical:start-of-weekno (weekno year &optional weekstart)
+  "Return the start of the WEEKNOth week in the (Gregorian) YEAR.
+
+RFC5545 defines week 1 as the first week to include at least four days
+in the year.  Weeks are assumed to start on Monday (= 1) unless WEEKSTART
+is specified, in which case it should be an integer between 0 (= Sunday)
+and 6 (= Saturday).  The returned value is an `icalendar-date'.
+
+If WEEKNO is negative, it refers to the WEEKNOth week before the end of
+the year: -1 is the last week of the year, -2 second to last, etc."
+  (calendar-gregorian-from-absolute
+   (+
+    (* 7 (if (< 0 weekno)
+             (1- weekno)
+           (+ 1 weekno (ical:number-of-weeks year weekstart))))
+    (calendar-dayname-on-or-before
+     (or weekstart 1)
+     ;; Three days after Jan 1. gives us the nearest occurrence;
+     ;; see `calendar-dayname-on-or-before'
+     (+ 3 (calendar-absolute-from-gregorian (list 1 1 year)))))))
+
+(defun ical:nth-weekday-in (n weekday year &optional month)
+  "Return the Nth WEEKDAY in YEAR or MONTH.
+
+If MONTH is specified, it refers to MONTH in YEAR, and N acts as an
+index for WEEKDAYs within the month.  Otherwise, N acts as an index for
+WEEKDAYs within the entire YEAR.
+
+N should be an integer.  If N<0, it counts from the end of the month or
+year: if N=-1, it refers to the last WEEKDAY in the month or year, if
+N=-2 the second to last, and so on."
+  (if month
+      (calendar-nth-named-day n weekday month year)
+    (let* ((jan1 (calendar-absolute-from-gregorian (list 1 1 year)))
+           (dec31 (calendar-absolute-from-gregorian (list 12 31 year))))
+      ;; Adapted from `calendar-nth-named-absday'.
+      ;; TODO: we could generalize that function to make month an optional
+      ;; argument, but that would mean changing its interface.
+      (calendar-gregorian-from-absolute
+       (if (> n 0)
+           (+ (* 7 (1- n))
+              (calendar-dayname-on-or-before
+               weekday
+               (+ 6 jan1)))
+         (+ (* 7 (1+ n))
+            (calendar-dayname-on-or-before
+             weekday
+             dec31)))))))
+
+(provide 'icalendar-utils)
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-"))
+;; End:
+;;; icalendar-utils.el ends here
diff --git a/lisp/calendar/icalendar.el b/lisp/calendar/icalendar.el
index 84a83284537..4956dc82f09 100644
--- a/lisp/calendar/icalendar.el
+++ b/lisp/calendar/icalendar.el
@@ -26,6 +26,11 @@
 
 ;;; Commentary:
 
+;; Most of the code in this file is now obsolete and has been marked as such.
+;; For the new implementation of diary import/export, see diary-icalendar.el.
+;; Error handling code, global variables, and user options relevant for the
+;; entire iCalendar library remain in this file.
+
 ;; This package is documented in the Emacs Manual.
 
 ;;   Please note:
@@ -73,39 +78,11 @@
 ;;  0.01: (2003-03-21)
 ;;  - First published version.  Trial version.  Alpha version.
 
-;; ======================================================================
-;; To Do:
-
-;;  * Import from ical to diary:
-;;    + Need more properties for icalendar-import-format
-;;      (added all that Mozilla Calendar uses)
-;;      From iCal specifications (RFC2445: 4.8.1), icalendar.el lacks
-;;      ATTACH, CATEGORIES, COMMENT, GEO, PERCENT-COMPLETE (VTODO),
-;;      PRIORITY, RESOURCES) not considering date/time and time-zone
-;;    + check vcalendar version
-;;    + check (unknown) elements
-;;    + recurring events!
-;;    + works for european style calendars only! Does it?
-;;    + alarm
-;;    + exceptions in recurring events
-;;    + the parser is too soft
-;;    + error log is incomplete
-;;    + nice to have: #include "webcal://foo.com/some-calendar.ics"
-;;    + timezones probably still need some improvements.
-
-;;  * Export from diary to ical
-;;    + diary-date, diary-float, and self-made sexp entries are not
-;;      understood
-
-;;  * Other things
-;;    + clean up all those date/time parsing functions
-;;    + Handle todo items?
-;;    + Check iso 8601 for datetime and period
-;;    + Which chars to (un)escape?
-
-
 ;;; Code:
 
+(eval-when-compile (require 'compile))
+(eval-when-compile (require 'cl-lib))
+
 ;; ======================================================================
 ;; Customizables
 ;; ======================================================================
@@ -135,48 +112,78 @@ argument.  It must return a string.  See
 `icalendar-import-format-sample' for an example."
   :type '(choice
           (string :tag "String")
-          (function :tag "Function"))
-  :group 'icalendar)
+          (function :tag "Function")))
+
+(make-obsolete-variable
+ 'icalendar-import-format
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-summary
   "%s"
   "Format string defining how the summary element is formatted.
 This applies only if the summary is not empty! `%s' is replaced
 by the summary."
-  :type 'string
-  :group 'icalendar)
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-summary
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-description
   "\n Desc: %s"
   "Format string defining how the description element is formatted.
 This applies only if the description is not empty! `%s' is
 replaced by the description."
-  :type 'string
-  :group 'icalendar)
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-description
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-location
   "\n Location: %s"
   "Format string defining how the location element is formatted.
 This applies only if the location is not empty! `%s' is replaced
 by the location."
-  :type 'string
-  :group 'icalendar)
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-location
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-organizer
   "\n Organizer: %s"
   "Format string defining how the organizer element is formatted.
 This applies only if the organizer is not empty! `%s' is
 replaced by the organizer."
-  :type 'string
-  :group 'icalendar)
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-organizer
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-url
   "\n URL: %s"
   "Format string defining how the URL element is formatted.
 This applies only if the URL is not empty! `%s' is replaced by
 the URL."
-  :type 'string
-  :group 'icalendar)
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-url
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-uid
   "\n UID: %s"
@@ -184,87 +191,91 @@ the URL."
 This applies only if the UID is not empty! `%s' is replaced by
 the UID."
   :type 'string
-  :version "24.3"
-  :group 'icalendar)
+  :version "24.3")
+
+(make-obsolete-variable
+ 'icalendar-import-format-uid
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-status
   "\n Status: %s"
   "Format string defining how the status element is formatted.
 This applies only if the status is not empty! `%s' is replaced by
 the status."
-  :type 'string
-  :group 'icalendar)
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-status
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
 
 (defcustom icalendar-import-format-class
   "\n Class: %s"
   "Format string defining how the class element is formatted.
 This applies only if the class is not empty! `%s' is replaced by
 the class."
-  :type 'string
-  :group 'icalendar)
-
-(defcustom icalendar-recurring-start-year
-  2005
-  "Start year for recurring events.
-Some calendar browsers only propagate recurring events for
-several years beyond the start time.  Set this string to a year
-just before the start of your personal calendar."
-  :type 'integer
-  :group 'icalendar)
-
-(defcustom icalendar-export-hidden-diary-entries
-  t
-  "Determines whether hidden diary entries are exported.
-If non-nil hidden diary entries (starting with `&') get exported,
-if nil they are ignored."
-  :type 'boolean
-  :group 'icalendar)
-
-(defcustom icalendar-uid-format
-  "emacs%t%c"
-  "Format of unique ID code (UID) for each iCalendar object.
+  :type 'string)
+
+(make-obsolete-variable
+ 'icalendar-import-format-class
+ "please use `diary-icalendar-vevent-format-function' for import
+formatting instead."
+ "31.1")
+
+(define-obsolete-variable-alias
+ 'icalendar-recurring-start-year
+ 'diary-icalendar-recurring-start-year
+ "31.1")
+
+(define-obsolete-variable-alias
+ 'icalendar-export-hidden-diary-entries
+ 'diary-icalendar-export-nonmarking-entries
+ "31.1")
+
+(defcustom ical:uid-format
+  "%h"
+  "Format string for unique ID (UID) values for iCalendar components.
+
+This string is used by `icalendar-make-uid' to generate UID values when
+creating iCalendar components.
+
 The following specifiers are available:
 %c COUNTER, an integer value that is increased each time a uid is
    generated.  This may be necessary for systems which do not
    provide time-resolution finer than a second.
-%h HASH, a hash value of the diary entry,
-%s DTSTART, the start date (excluding time) of the diary entry,
+%h HASH, a hash value of the component's contents or system information,
 %t TIMESTAMP, a unique creation timestamp,
-%u USERNAME, the variable `user-login-name'.
-
-For example, a value of \"%s_%h@mydomain.com\" will generate a
-UID code for each entry composed of the time of the event, a hash
-code for the event, and your personal domain name."
-  :type 'string
-  :group 'icalendar)
-
-(defcustom icalendar-export-sexp-enumeration-days
-  14
-  "Number of days over which a sexp diary entry is enumerated.
-In general sexp entries cannot be translated to icalendar format.
-They are therefore enumerated, i.e. explicitly evaluated for a
-certain number of days, and then exported.  The enumeration starts
-on the current day and continues for the number of days given here.
-
-See `icalendar-export-sexp-enumerate-all' for a list of sexp
-entries which by default are NOT enumerated."
-  :version "25.1"
-  :type 'integer
-  :group 'icalendar)
-
-(defcustom icalendar-export-sexp-enumerate-all
-  nil
-  "Determines whether ALL sexp diary entries are enumerated.
-If non-nil all sexp diary entries are enumerated for
-`icalendar-export-sexp-enumeration-days' days instead of
-translating into an icalendar equivalent.  This affects the
-following sexp diary entries: `diary-anniversary',
-`diary-cyclic', `diary-date', `diary-float', `diary-block'.  All
-other sexp entries are enumerated in any case."
-  :version "25.1"
-  :type 'boolean
-  :group 'icalendar)
-
+%u USERNAME, the value of `user-login-name'.
+%s (obsolete, ignored)
+
+For example, a value of \"%h%t@mydomain.com\" will generate a UID code
+for each entry composed of a hash of the event data, a creation
+timestamp, and your personal domain name."
+  :type 'string)
+
+(defcustom ical:vcalendar-prodid
+  (format "-//gnu.org//GNU Emacs %s//EN" emacs-version)
+  "The value of the `icalendar-prodid' property for VCALENDAR objects
+produced by this Emacs."
+  :type 'string)
+
+(defconst ical:vcalendar-version "2.0"
+  "The current version of the VCALENDAR object, used in the
+`icalendar-version' property. \"2.0\" is the version corresponding to
+RFC5545.")
+
+(define-obsolete-variable-alias
+  'icalendar-export-sexp-enumeration-days
+  'diary-icalendar-export-sexp-enumeration-days
+  "31.1")
+
+(define-obsolete-variable-alias
+  'icalendar-export-sexp-enumerate-all
+  'diary-icalendar-export-sexp-enumerate-all
+  "31.1")
 
 (defcustom icalendar-export-alarms
   nil
@@ -283,19 +294,39 @@ other sexp entries are enumerated in any case."
                             (list :tag "Email"
                                   (const email)
                                   (repeat :tag "Attendees"
-                                          (string :tag "Email"))))))
-  :group 'icalendar)
+                                          (string :tag "Email")))))))
 
+(make-obsolete-variable
+ 'icalendar-export-alarms
+ "please use the new format in `diary-icalendar-export-alarms' instead."
+ "31.1")
+
+(defcustom icalendar-debug-level 1
+  "Minimum severity for logging iCalendar error messages.
+A value of 2 only logs errors.
+A value of 1 also logs warnings.
+A value of 0 also logs debugging information."
+  :type 'integer)
 
 (defvar icalendar-debug nil
   "Enable icalendar debug messages.")
 
+(make-obsolete-variable
+ 'icalendar-debug
+ 'icalendar-debug-level
+ "31.1")
+
 ;; ======================================================================
 ;; NO USER SERVICEABLE PARTS BELOW THIS LINE
 ;; ======================================================================
 
 (defconst icalendar--weekday-array ["SU" "MO" "TU" "WE" "TH" "FR" "SA"])
 
+(make-obsolete-variable
+ 'icalendar--weekday-array
+ 'icalendar-weekday-numbers
+ "31.1")
+
 ;; ======================================================================
 ;; all the other libs we need
 ;; ======================================================================
@@ -307,8 +338,305 @@ other sexp entries are enumerated in any case."
 ;; ======================================================================
 (defun icalendar--dmsg (&rest args)
   "Print message ARGS if `icalendar-debug' is non-nil."
-  (if icalendar-debug
-      (apply 'message args)))
+  (declare (obsolete icalendar-warn "31.1"))
+  (if (or icalendar-debug (= 0 icalendar-debug-level))
+      (with-current-buffer (ical:error-buffer)
+        (goto-char (point-max))
+        (insert (apply #'format-message args))
+        (insert "\n"))))
+
+;; ======================================================================
+;; Error handling
+;; ======================================================================
+(define-error 'ical:error "iCalendar error")
+
+(defconst ical:error-buffer-name "*icalendar-errors*"
+  "Name of buffer in which errors are listed when processing iCalendar data.")
+
+(defun ical:error-buffer ()
+  "Return the iCalendar errors buffer, creating it if necessary.
+The buffer name is based on `icalendar-error-buffer-name'."
+  (get-buffer-create ical:error-buffer-name))
+
+(defvar ical:inhibit-error-erasure nil
+  "When non-nil, `icalendar-init-error-buffer' will not erase the errors
+buffer.")
+
+(defun ical:init-error-buffer (&optional err-buffer)
+  "Prepare ERR-BUFFER for iCalendar errors.
+ERR-BUFFER defaults to the buffer returned by `icalendar-error-buffer'.
+Erases ERR-BUFFER and places it in `icalendar-errors-mode'."
+  (with-current-buffer (or err-buffer (ical:error-buffer))
+    (unless ical:inhibit-error-erasure
+      (let ((inhibit-read-only t))
+        (erase-buffer)))
+    (if (not (eq major-mode 'icalendar-errors-mode))
+        (icalendar-errors-mode))))
+
+(defun ical:errors-p (&optional err-buffer)
+  "Return non-nil if iCalendar errors have been reported in ERR-BUFFER.
+ERR-BUFFER defaults to the buffer returned by `icalendar-error-buffer'."
+  (with-current-buffer (or err-buffer (ical:error-buffer))
+    (not (= (point-min) (point-max)))))
+
+(defun ical:warn (msg &rest err-plist)
+  "Write a warning to the `icalendar-error-buffer' without signaling an error."
+  (plist-put err-plist :message msg)
+  (unless (plist-get err-plist :severity)
+    (plist-put err-plist :severity 1))
+  (ical:handle-generic-error `(ical:warning . ,err-plist)))
+
+(defconst ical:error-regexp
+  (rx line-start
+      (zero-or-one
+       (group "("
+              (or (group-n 3 "ERROR") (group-n 4 "WARNING") (group-n 5 "INFO"))
+              ")"))
+      (group-n 1 (zero-or-one " *UNFOLDED:") (zero-or-more (not ":"))) ":"
+      (zero-or-one (group-n 2 (one-or-more digit)))
+      ":")
+  "Regexp to match iCalendar errors.
+
+Group 1 contains the buffer name where the error originated.
+Group 2 contains the buffer position.
+Groups 3-5 match the severity:
+  3 matches ERROR
+  4 matches WARNING
+  5 matches INFO")
+
+(cl-defun ical:format-error (&rest error-plist
+                             &key (message "Unknown error")
+                                  severity
+                                  buffer
+                                  position
+                                  &allow-other-keys)
+  "Format iCalendar error data to a string.
+
+MESSAGE should be a string; it defaults to \"Unknown error\".
+BUFFER should be a buffer; POSITION should be a position in BUFFER.
+SEVERITY can be 0 for debug information, or 1 for a warning; otherwise
+a genuine error is reported.
+
+The returned error message looks like
+
+(LEVEL)BUFFER:POSITION: MESSAGE
+DEBUG-INFO...
+
+where LEVEL is derived from SEVERITY.  DEBUG-INFO contains any additional
+data in ERROR-PLIST, if `icalendar-debug-level' is
+0. `icalendar-error-regexp' matches the fields in such messages."
+  (let ((name (copy-sequence (buffer-name buffer)))
+        (pos (if (integer-or-marker-p position)
+                 (format "%d" position)
+               ""))
+        (level (cond ((eq severity 0) "INFO")
+                     ((eq severity 1) "WARNING")
+                     (t "ERROR")))
+        (debug-info (if (not (= 0 icalendar-debug-level))
+                        ""
+                      (mapconcat ;; (:key val...) => "Key: val\n..."
+                       (lambda (val)
+                         (if (keywordp val)
+                             (capitalize (substring (symbol-name val) 1))
+                           (format ": %s\n" val)))
+                       error-plist))))
+    ;; Make sure buffer name doesn't take too much space:
+    (when (< 8 (length name))
+      (if (equal " *UNFOLDED:" (substring name 0 11))
+          (put-text-property 0 11 'display "..." name)
+        (put-text-property 9 (length name) 'display "..." name)))
+    (format "(%s)%s:%s: %s\n%s" level name pos message debug-info)))
+
+(defun ical:handle-generic-error (err-data &optional err-buffer)
+  "Log error data to ERR-BUFFER (default: the iCalendar error buffer).
+ERR-DATA should be a list (ERROR-SYMBOL . SIGNAL-DATA) where
+SIGNAL-DATA is a plist of error data."
+  (let* ((signal-data (cdr err-data))
+         (err-plist (when (plistp signal-data) signal-data))
+         (err-symbol (car err-data))
+         (severity (or (plist-get err-plist :severity) 2))
+         (buf (current-buffer)))
+    (when (<= ical:debug-level severity)
+      (with-current-buffer (or err-buffer (ical:error-buffer))
+        (goto-char (point-max))
+        (let ((inhibit-read-only t))
+          (unless (bolp) (insert "\n"))
+          (insert (apply #'ical:format-error
+                         (or err-plist
+                             (list :buffer buf
+                                   :message
+                                   (format "Unhandled %s error: %s"
+                                           err-symbol signal-data))))))))))
+
+(defmacro ical:condition-case (var bodyform &rest handlers)
+  "Like `condition-case', but with default handler for unhandled iCalendar errors.
+If none of HANDLERS handles an error, it will be handled by
+`icalendar-handle-generic-error'."
+  `(condition-case ,var
+       ,bodyform
+     ,@handlers
+     (ical:error (ical:handle-generic-error ,var))))
+
+;;; Mode based on compilation-mode for navigating error buffer:
+(defun ical:-buffer-from-error ()
+  (when-let* ((name (match-string 1)))
+    (or (get-buffer name)
+        (find-buffer-visiting name))))
+
+(defun ical:-filename-from-error ()
+  (when-let* ((buf (ical:-buffer-from-error)))
+    (buffer-file-name buf)))
+
+(defun ical:-lineno-from-error ()
+  (when-let* ((buf (ical:-buffer-from-error))
+              (posstr (match-string 2))
+              (pos (string-to-number posstr)))
+    (with-current-buffer buf
+      (line-number-at-pos pos))))
+
+(defconst ical:error-regexp-alist
+  (list (list icalendar-error-regexp
+              #'ical:-filename-from-error
+              #'ical:-lineno-from-error
+              nil
+              nil
+              nil
+              '(2 compilation-line-face)
+              '(3 compilation-error-face)
+              '(4 compilation-warning-face)
+              '(5 compilation-info-face)))
+  "Specifies how errors are parsed in `icalendar-errors-mode';
+see `compilation-error-regexp-alist'.")
+
+(define-compilation-mode ical:errors-mode "iCalendar Errors"
+  "Mode for listing and visiting errors when processing iCalendar data."
+  (setq-local compilation-error-regexp-alist ical:error-regexp-alist))
+
+;; ======================================================================
+;; UIDs
+;; ======================================================================
+(defvar ical:-uid-count 0
+  "Internal counter for creating unique ids.")
+
+(defun ical:make-uid (&optional contents _)
+  "Construct a unique ID from `icalendar-uid-format'.
+
+CONTENTS can be any object which represents the contents of the
+iCalendar component for which the UID is generated.  If CONTENTS is a
+string with the text property \\='uid, that property's value will be
+used as the returned UID.
+
+Otherwise, CONTENTS will be used to create the hash substituted for
+\\='%h' in `icalendar-uid-format'.  If CONTENTS is not given, the hash
+will be based on an internal counter, the system name, and the current
+time in nanoseconds.
+
+The second optional argument is for backward compatibility and is ignored."
+  (cl-incf icalendar--uid-count)
+  (let* ((uid icalendar-uid-format)
+         (timestamp (format-time-string "%s%N"))
+         (tohash (or contents
+                     (format "%d%s%s" ical:-uid-count (system-name) timestamp))))
+    (if (and (stringp contents) (get-text-property 0 'uid contents))
+        ;; "Allow other apps (such as org-mode) to create its own uid"
+        ;; FIXME: is this necessary?  If caller already has a UID, why
+        ;; call this function at all?
+        (setq uid (get-text-property 0 'uid contents))
+      (progn
+        (setq uid (replace-regexp-in-string
+                   "%c" (format "%d" icalendar--uid-count) uid t t))
+        (setq uid (replace-regexp-in-string
+                   "%t" timestamp uid t t))
+        (setq uid (replace-regexp-in-string
+                   "%h" (format "%d" (abs (sxhash tohash))) uid t t))
+        (setq uid (replace-regexp-in-string
+                   "%u" (or user-login-name "UNKNOWN_USER") uid t t))
+        ;; `%s' no longer used, but allowed for backward compatibility:
+        (setq uid (replace-regexp-in-string "%s" "" uid t t))))
+    uid))
+
+
+;; Essentially everything beyond this point is obsoleted by the new
+;; implementation in diary-icalendar.el.  Since the functions below call
+;; each other and they still need to live in this file for now (see
+;; Bug#74994), prevent byte compiler warnings when compiling this file:
+(with-suppressed-warnings
+    ((obsolete icalendar-import-format
+               icalendar-import-format-summary
+               icalendar-import-format-description
+               icalendar-import-format-location
+               icalendar-import-format-organizer
+               icalendar-import-format-url
+               icalendar-import-format-uid
+               icalendar-import-format-status
+               icalendar-import-format-class
+               icalendar-recurring-start-year
+               icalendar-export-hidden-diary-entries
+               icalendar-export-sexp-enumeration-days
+               icalendar-export-sexp-enumerate-all
+               icalendar-export-alarms
+               icalendar-debug nil
+               icalendar--weekday-array
+               icalendar--dmsg
+               icalendar--get-unfolded-buffer
+               icalendar--clean-up-line-endings
+               icalendar--rris
+               icalendar--read-element
+               icalendar--get-event-property
+               icalendar--get-event-property-attributes
+               icalendar--get-event-properties
+               icalendar--get-children
+               icalendar--all-events
+               icalendar--split-value
+               icalendar--convert-tz-offset
+               icalendar--parse-vtimezone
+               icalendar--get-most-recent-observance
+               icalendar--convert-all-timezones
+               icalendar--find-time-zone
+               icalendar--decode-isodatetime
+               icalendar--decode-isoduration
+               icalendar--add-decoded-times
+               icalendar--datetime-to-american-date
+               icalendar--datetime-to-european-date
+               icalendar--datetime-to-iso-date
+               icalendar--datetime-to-diary-date
+               icalendar--datetime-to-colontime
+               icalendar--get-month-number
+               icalendar--get-weekday-number
+               icalendar--get-weekday-numbers
+               icalendar--get-weekday-abbrev
+               icalendar--date-to-isodate
+               icalendar--datestring-to-isodate
+               icalendar--diarytime-to-isotime
+               icalendar--convert-string-for-export
+               icalendar--convert-string-for-import
+               icalendar-export-file
+               icalendar-export-region
+               icalendar--create-uid
+               icalendar--convert-to-ical
+               icalendar--parse-summary-and-rest
+               icalendar--create-ical-alarm
+               icalendar--do-create-ical-alarm
+               icalendar--convert-ordinary-to-ical
+               icalendar-first-weekday-of-year
+               icalendar--convert-weekly-to-ical
+               icalendar--convert-yearly-to-ical
+               icalendar--convert-sexp-to-ical
+               icalendar--convert-block-to-ical
+               icalendar--convert-float-to-ical
+               icalendar--convert-date-to-ical
+               icalendar--convert-cyclic-to-ical
+               icalendar--convert-anniversary-to-ical
+               icalendar-import-file
+               icalendar-import-buffer
+               icalendar--format-ical-event
+               icalendar--convert-ical-to-diary
+               icalendar--convert-recurring-to-diary
+               icalendar--convert-non-recurring-all-day-to-diary
+               icalendar--convert-non-recurring-not-all-day-to-diary
+               icalendar--add-diary-entry
+               icalendar-import-format-sample
+               icalendar-version))
 
 ;; ======================================================================
 ;; Core functionality
@@ -321,6 +649,7 @@ Folding is the iCalendar way of wrapping long lines.  In the
 created buffer all occurrences of CR LF BLANK are replaced by the
 empty string.  Argument FOLDED-ICAL-BUFFER is the folded input
 buffer."
+  (declare (obsolete icalendar-unfolded-buffer-from-buffer "31.1"))
   (let ((unfolded-buffer (get-buffer-create " *icalendar-work*")))
     (save-current-buffer
       (set-buffer unfolded-buffer)
@@ -337,13 +666,14 @@ buffer."
 All occurrences of (CR LF) and (LF CF) are replaced with LF in
 the current buffer.  This is necessary in buffers which contain a
 mix of different line endings."
+  (declare (obsolete nil "31.1"))
   (save-excursion
     (goto-char (point-min))
     (while (re-search-forward "\r\n\\|\n\r" nil t)
       (replace-match "\n" nil nil))))
 
 (define-obsolete-function-alias 'icalendar--rris
-  'replace-regexp-in-string "27.1")
+  #'replace-regexp-in-string "27.1")
 
 (defun icalendar--read-element (invalue inparams)
   "Recursively read the next iCalendar element in the current buffer.
@@ -352,6 +682,8 @@ INPARAMS gives the current parameters.....
 This function calls itself recursively for each nested calendar element
 it finds.  The current buffer should be an unfolded buffer as returned
 from `icalendar--get-unfolded-buffer'."
+  (declare (obsolete "use `icalendar-parse' or one of `icalendar-parse-component',
+`icalendar-parse-property', `icalendar-parse-params' instead." "31.1"))
   (let (element children line name params param param-name param-value
                 value
                 (continue t))
@@ -408,6 +740,7 @@ from `icalendar--get-unfolded-buffer'."
 
 (defun icalendar--get-event-property (event prop)
   "For the given EVENT return the value of the first occurrence of PROP."
+  (declare (obsolete icalendar-with-component "31.1"))
   (catch 'found
     (let ((props (car (cddr event))) pp)
       (while props
@@ -419,6 +752,7 @@ from `icalendar--get-unfolded-buffer'."
 
 (defun icalendar--get-event-property-attributes (event prop)
   "For the given EVENT return attributes of the first occurrence of PROP."
+  (declare (obsolete icalendar-with-component "31.1"))
   (catch 'found
     (let ((props (car (cddr event))) pp)
       (while props
@@ -430,6 +764,7 @@ from `icalendar--get-unfolded-buffer'."
 
 (defun icalendar--get-event-properties (event prop)
   "For the given EVENT return a list of all values of the property PROP."
+  (declare (obsolete icalendar-with-component "31.1"))
   (let ((props (car (cddr event))) pp result)
     (while props
       (setq pp (car props))
@@ -456,6 +791,7 @@ from `icalendar--get-unfolded-buffer'."
   "Return all children of the given NODE which have a name NAME.
 For instance the VCALENDAR node can have VEVENT children as well as VTODO
 children."
+  (declare (obsolete icalendar-ast-node-children "31.1"))
   (let ((result nil)
         (children (cadr (cddr node))))
     (when (eq (car node) name)
@@ -476,6 +812,7 @@ children."
 ;; private
 (defun icalendar--all-events (icalendar)
   "Return the list of all existing events in the given ICALENDAR."
+  (declare (obsolete icalendar-with-component "31.1"))
   (let ((result '()))
     (mapc (lambda (elt)
             (setq result (append (icalendar--get-children elt 'VEVENT)
@@ -485,6 +822,7 @@ children."
 
 (defun icalendar--split-value (value-string)
   "Split VALUE-STRING at `;='."
+  (declare (obsolete nil "31.1"))
   (let ((result '())
         param-name param-value)
     (when value-string
@@ -509,6 +847,7 @@ children."
 ALIST is an alist entry from a VTIMEZONE, like STANDARD.
 DST-P is non-nil if this is for daylight savings time.
 The strings are suitable for assembling into a TZ variable."
+  (declare (obsolete nil "31.1"))
   (let* ((offsetto (car (cddr (assq 'TZOFFSETTO alist))))
          (offsetfrom (car (cddr (assq 'TZOFFSETFROM alist))))
          (rrule-value (car (cddr (assq 'RRULE alist))))
@@ -561,6 +900,7 @@ The strings are suitable for assembling into a TZ variable."
   "Turn a VTIMEZONE ALIST into a cons (ID . TZ-STRING).
 Consider only the most recent date specification.
 Return nil if timezone cannot be parsed."
+  (declare (obsolete nil "31.1"))
   (let* ((tz-id (icalendar--convert-string-for-import
                  (icalendar--get-event-property alist 'TZID)))
          (daylight (cadr (cdar (icalendar--get-most-recent-observance alist 'DAYLIGHT))))
@@ -578,6 +918,7 @@ Return nil if timezone cannot be parsed."
   "Return the latest observance for SUB-COMP DAYLIGHT or STANDARD.
 ALIST is a VTIMEZONE potentially containing historical records."
 ;FIXME?: "most recent" should be relative to a given date
+  (declare (obsolete icalendar-recur-tz-observance-on "31.1"))
   (let ((components (icalendar--get-children alist sub-comp)))
     (list
      (car
@@ -591,7 +932,7 @@ ALIST is a VTIMEZONE potentially containing historical records."
                                                      (and (memq (car p) '(DTSTART RDATE))
                                                           (car (cddr p))))
                                                    n))
-                                     'string-greaterp))))
+                                     #'string-greaterp))))
                      (a-recent (funcall get-recent (car (cddr a))))
                      (b-recent (funcall get-recent (car (cddr b)))))
                 (string-greaterp a-recent b-recent))))))))
@@ -600,6 +941,7 @@ ALIST is a VTIMEZONE potentially containing historical records."
   "Convert all timezones in the ICALENDAR into an alist.
 Each element of the alist is a cons (ID . TZ-STRING),
 like `icalendar--parse-vtimezone'."
+  (declare (obsolete nil "31.1"))
   (let (result)
     (dolist (zone (icalendar--get-children (car icalendar) 'VTIMEZONE))
       (setq zone (icalendar--parse-vtimezone zone))
@@ -610,6 +952,7 @@ like `icalendar--parse-vtimezone'."
 (defun icalendar--find-time-zone (prop-list zone-map)
   "Return a timezone string for the time zone in PROP-LIST, or nil if none.
 ZONE-MAP is a timezone alist as returned by `icalendar--convert-all-timezones'."
+  (declare (obsolete nil "31.1"))
   (let ((id (plist-get prop-list 'TZID)))
     (if id
         (cdr (assoc id zone-map)))))
@@ -628,6 +971,7 @@ in any format understood by `encode-time'.
 RESULT-ZONE, if provided, is the timezone for encoding the result
 in any format understood by `decode-time'.
 FIXME: multiple comma-separated values should be allowed!"
+  (declare (obsolete icalendar-read-date-time "31.1"))
   (icalendar--dmsg isodatetimestring)
   (if isodatetimestring
       ;; day/month/year must be present
@@ -685,6 +1029,7 @@ Optional argument DURATION-CORRECTION shortens result by one day.
 
 FIXME: TZID-attributes are ignored....!
 FIXME: multiple comma-separated values should be allowed!"
+  (declare (obsolete icalendar-read-dur-value "31.1"))
   (if isodurationstring
       (save-match-data
         (string-match
@@ -740,6 +1085,7 @@ FIXME: multiple comma-separated values should be allowed!"
   "Add TIME1 to TIME2.
 Both times must be given in decoded form.  One of these times must be
 valid (year > 1900 or something)."
+  (declare (obsolete icalendar-date-time-add "31.1"))
   ;; FIXME: does this function exist already?  Can we use decoded-time-add?
   (decode-time (encode-time
                 ;; FIXME: Support subseconds.
@@ -761,6 +1107,8 @@ valid (year > 1900 or something)."
 Optional argument SEPARATOR gives the separator between month,
 day, and year.  If nil a blank character is used as separator.
 American format: \"month day year\"."
+  (declare (obsolete "use `icalendar-date/time-to-date' and
+`diary-icalendar-format-date' instead." "31.1"))
   (if datetime
       (format "%d%s%d%s%d" (nth 4 datetime) ;month
               (or separator " ")
@@ -776,6 +1124,7 @@ Optional argument SEPARATOR gives the separator between month,
 day, and year.  If nil a blank character is used as separator.
 European format: (day month year).
 FIXME"
+  (declare (obsolete "use `icalendar-date/time-to-date' and `diary-icalendar-format-date' instead." "31.1"))
   (if datetime
       (format "%d%s%d%s%d" (nth 3 datetime) ;day
               (or separator " ")
@@ -790,6 +1139,7 @@ FIXME"
 Optional argument SEPARATOR gives the separator between month,
 day, and year.  If nil a blank character is used as separator.
 ISO format: (year month day)."
+  (declare (obsolete "use `icalendar-date/time-to-date' and `diary-icalendar-format-date' instead." "31.1"))
   (if datetime
       (format "%d%s%d%s%d" (nth 5 datetime) ;year
               (or separator " ")
@@ -805,6 +1155,7 @@ Optional argument SEPARATOR gives the separator between month,
 day, and year.  If nil a blank character is used as separator.
 Call icalendar--datetime-to-*-date according to the current
 calendar date style."
+  (declare (obsolete "use `icalendar-date/time-to-date' and `diary-icalendar-format-date' instead." "31.1"))
   (funcall (intern-soft (format "icalendar--datetime-to-%s-date"
                                 calendar-date-style))
            datetime separator))
@@ -812,10 +1163,12 @@ calendar date style."
 (defun icalendar--datetime-to-colontime (datetime)
   "Extract the time part of a decoded DATETIME into 24-hour format.
 Note that this silently ignores seconds."
+  (declare (obsolete diary-icalendar-format-time "31.1"))
   (format "%02d:%02d" (nth 2 datetime) (nth 1 datetime)))
 
 (defun icalendar--get-month-number (monthname)
   "Return the month number for the given MONTHNAME."
+  (declare (obsolete nil "31.1"))
   (catch 'found
     (let ((num 1)
           (m (downcase monthname)))
@@ -831,6 +1184,7 @@ Note that this silently ignores seconds."
 
 (defun icalendar--get-weekday-number (abbrevweekday)
   "Return the number for the ABBREVWEEKDAY."
+  (declare (obsolete "see `icalendar-weekday-numbers'" "31.1"))
   (if abbrevweekday
       (catch 'found
         (let ((num 0)
@@ -846,6 +1200,7 @@ Note that this silently ignores seconds."
 
 (defun icalendar--get-weekday-numbers (abbrevweekdays)
   "Return the list of numbers for the comma-separated ABBREVWEEKDAYS."
+  (declare (obsolete "see `icalendar-weekday-numbers'" "31.1"))
   (when abbrevweekdays
     (let* ((num -1)
            (weekday-alist (mapcar (lambda (day)
@@ -860,6 +1215,7 @@ Note that this silently ignores seconds."
 
 (defun icalendar--get-weekday-abbrev (weekday)
   "Return the abbreviated WEEKDAY."
+  (declare (obsolete "see `icalendar-weekday-numbers'" "31.1"))
   (catch 'found
     (let ((num 0)
           (w (downcase weekday)))
@@ -877,6 +1233,7 @@ Note that this silently ignores seconds."
   "Convert DATE to iso-style date.
 DATE must be a list of the form (month day year).
 If DAY-SHIFT is non-nil, the result is shifted by DAY-SHIFT days."
+  (declare (obsolete icalendar-print-date "31.1"))
   (let ((mdy (calendar-gregorian-from-absolute
               (+ (calendar-absolute-from-gregorian date)
                  (or day-shift 0)))))
@@ -891,6 +1248,7 @@ non-nil, the result is shifted by YEAR-SHIFT years -- YEAR-SHIFT
 must be either nil or an integer.  This function tries to figure
 the date style from DATESTRING itself.  If that is not possible
 it uses the current calendar date style."
+  (declare (obsolete "use `diary-icalendar-parse-date-form' and `icalendar-print-date' instead." "31.1"))
   (let ((day -1) month year)
     (save-match-data
       (cond ( ;; iso-style numeric date
@@ -981,6 +1339,7 @@ In this example the TIMESTRING would be \"9:30\" and the
 AMPMSTRING would be \"pm\".  The minutes may be missing as long
 as the colon is missing as well, i.e. \"9\" is allowed as
 TIMESTRING and has the same result as \"9:00\"."
+  (declare (obsolete "use `diary-icalendar-parse-time' and `icalendar-print-date-time' instead." "31.1"))
   (if timestring
       (let* ((parts (save-match-data (split-string timestring ":")))
              (h (car parts))
@@ -1018,20 +1377,19 @@ TIMESTRING and has the same result as \"9:00\"."
   "Export diary file to iCalendar format.
 All diary entries in the file DIARY-FILENAME are converted to iCalendar
 format.  The result is appended to the file ICAL-FILENAME."
+  (declare (obsolete diary-icalendar-export-file "31.1"))
   (interactive "FExport diary data from file: \n\
 Finto iCalendar file: ")
   (save-current-buffer
     (set-buffer (find-file diary-filename))
     (icalendar-export-region (point-min) (point-max) ical-filename)))
 
-(defvar icalendar--uid-count 0
-  "Auxiliary counter for creating unique ids.")
-
 (defun icalendar--create-uid (entry-full contents)
   "Construct a unique iCalendar UID for a diary entry.
 ENTRY-FULL is the full diary entry string.  CONTENTS is the
 current iCalendar object, as a string.  Increase
 `icalendar--uid-count'.  Returns the UID string."
+  (declare (obsolete icalendar-make-uid "31.1"))
   (let ((uid icalendar-uid-format))
     (if
         ;; Allow other apps (such as org-mode) to create its own uid
@@ -1055,7 +1413,6 @@ current iCalendar object, as a string.  Increase
                          (substring contents (match-beginning 1) (match-end 1))
                        "DTSTART")))
         (setq uid (replace-regexp-in-string "%s" dtstart uid t t))))
-
     ;; Return the UID string
     uid))
 
@@ -1068,6 +1425,7 @@ ICAL-FILENAME.
 This function attempts to return t if something goes wrong.  In this
 case an error string which describes all the errors and problems is
 written into the buffer `*icalendar-errors*'."
+  (declare (obsolete diary-icalendar-export-region "31.1"))
   (interactive "r
 FExport diary data into iCalendar file: ")
   (let ((result "")
@@ -1179,6 +1537,7 @@ FExport diary data into iCalendar file: ")
   "Convert a diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (or
    (unless icalendar-export-sexp-enumerate-all
      (or
@@ -1208,6 +1567,7 @@ entries.  ENTRY-MAIN is the first line of the diary entry."
 (defun icalendar--parse-summary-and-rest (summary-and-rest)
   "Parse SUMMARY-AND-REST from a diary to fill iCalendar properties.
 Returns an alist."
+  (declare (obsolete diary-icalendar-parse-entry "31.1"))
   (save-match-data
     (if (functionp icalendar-import-format)
         ;; can't do anything
@@ -1223,7 +1583,7 @@ Returns an alist."
              (p-sta (or (string-match "%t" icalendar-import-format) -1))
              (p-url (or (string-match "%u" icalendar-import-format) -1))
              (p-uid (or (string-match "%U" icalendar-import-format) -1))
-             (p-list (sort (list p-cla p-des p-loc p-org p-sta p-sum p-url p-uid) '<))
+             (p-list (sort (list p-cla p-des p-loc p-org p-sta p-sum p-url p-uid) #'<))
              (ct 0)
              pos-cla pos-des pos-loc pos-org pos-sta pos-url pos-uid) ;pos-sum
         (dotimes (i (length p-list))
@@ -1322,6 +1682,7 @@ Returns an alist."
 
 (defun icalendar--create-ical-alarm (summary)
   "Return VALARM blocks for the given SUMMARY."
+  (declare (obsolete diary-icalendar-add-valarms "31.1"))
   (when icalendar-export-alarms
     (let* ((advance-time (car icalendar-export-alarms))
            (alarm-specs (cadr icalendar-export-alarms))
@@ -1337,6 +1698,7 @@ is a list which must be one of (audio), (display) or
 \(email (ADDRESS1 ...)), see `icalendar-export-alarms'.  Argument
 SUMMARY is a string which contains a short description for the
 alarm."
+  (declare (obsolete diary-icalendar-add-valarms "31.1"))
   (let* ((action (car alarm-spec))
          (act (format "\nACTION:%s"
                       (cdr (assoc action '((audio . "AUDIO")
@@ -1362,6 +1724,7 @@ alarm."
   "Convert \"ordinary\" diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match
        (concat nonmarker
                "\\([^ /]+[ /]+[^ /]+[ /]+[^ ]+\\)\\s-*" ; date
@@ -1445,6 +1808,7 @@ entries.  ENTRY-MAIN is the first line of the diary entry."
 (defun icalendar-first-weekday-of-year (abbrevweekday year)
   "Find the first ABBREVWEEKDAY in a given YEAR.
 Returns day number."
+  (declare (obsolete icalendar-nth-weekday-in "31.1"))
   (let* ((day-of-week-jan01 (calendar-day-of-week (list 1 1 year)))
          (result (+ 1
                     (- (icalendar--get-weekday-number abbrevweekday)
@@ -1459,6 +1823,7 @@ Returns day number."
   "Convert weekly diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (and (string-match (concat nonmarker
                                  "\\([a-z]+\\)\\s-+"
                                  "\\(\\([0-9][0-9]?:[0-9][0-9]\\)"
@@ -1541,6 +1906,7 @@ entries.  ENTRY-MAIN is the first line of the diary entry."
   "Convert yearly diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match (concat nonmarker
                             (if (eq calendar-date-style 'european)
                                 "\\([0-9]+[0-9]?\\)\\s-+\\([a-z]+\\)\\s-+"
@@ -1626,6 +1992,7 @@ ENTRY-MAIN is the first line of the diary entry.
 
 Optional argument START determines the first day of the
 enumeration, given as a Lisp time value -- used for test purposes."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (cond ((string-match (concat nonmarker
                                "%%(and \\(([^)]+)\\))\\(\\s-*.*?\\) ?$")
                        entry-main)
@@ -1678,6 +2045,7 @@ enumeration, given as a Lisp time value -- used for test purposes."
   "Convert block diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match (concat nonmarker
                             "%%(diary-block \\([^ /]+[ /]+[^ /]+[ /]+[^ ]+\\)"
                             " +\\([^ /]+[ /]+[^ /]+[ /]+[^ ]+\\))\\s-*"
@@ -1753,10 +2121,11 @@ entries.  ENTRY-MAIN is the first line of the diary entry."
 (defun icalendar--convert-float-to-ical (nonmarker entry-main)
   "Convert float diary entry to iCalendar format -- partially unsupported!
 
-  FIXME! DAY from `diary-float' yet unimplemented.
+  FIXME!  DAY from `diary-float' yet unimplemented.
 
   NONMARKER is a regular expression matching the start of non-marking
   entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match (concat nonmarker "%%\\((diary-float .+\\) ?$") entry-main)
       (with-temp-buffer
         (insert (match-string 1 entry-main))
@@ -1817,6 +2186,7 @@ FIXME!
 
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match (concat nonmarker
                             "%%(diary-date \\([^)]+\\))\\s-*\\(.*?\\) ?$")
                     entry-main)
@@ -1830,6 +2200,7 @@ entries.  ENTRY-MAIN is the first line of the diary entry."
   "Convert `diary-cyclic' diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match (concat nonmarker
                             "%%(diary-cyclic \\([^ ]+\\) +"
                             "\\([^ /]+[ /]+[^ /]+[ /]+[^ ]+\\))\\s-*"
@@ -1904,6 +2275,7 @@ entries.  ENTRY-MAIN is the first line of the diary entry."
   "Convert `diary-anniversary' diary entry to iCalendar format.
 NONMARKER is a regular expression matching the start of non-marking
 entries.  ENTRY-MAIN is the first line of the diary entry."
+  (declare (obsolete "use `diary-icalendar-parse-entry' and `icalendar-print-component-node' instead." "31.1"))
   (if (string-match (concat nonmarker
                             "%%(diary-anniversary \\([^)]+\\))\\s-*"
                             "\\(\\([0-9][0-9]?:[0-9][0-9]\\)\\([ap]m\\)?"
@@ -1986,6 +2358,7 @@ Argument ICAL-FILENAME output iCalendar file.
 Argument DIARY-FILENAME input `diary-file'.
 Optional argument NON-MARKING determines whether events are created as
 non-marking or not."
+  (declare (obsolete diary-icalendar-import-file "31.1"))
   (interactive "fImport iCalendar data from file: \nFInto diary file: \nP")
   ;; clean up the diary file
   (save-current-buffer
@@ -2012,6 +2385,7 @@ non-marking.
 Return code t means that importing worked well, return code nil
 means that an error has occurred.  Error messages will be in the
 buffer `*icalendar-errors*'."
+  (declare (obsolete diary-icalendar-import-buffer "31.1"))
   (interactive)
   (save-current-buffer
     ;; prepare ical
@@ -2048,6 +2422,7 @@ buffer `*icalendar-errors*'."
 
 (defun icalendar--format-ical-event (event)
   "Create a string representation of an iCalendar EVENT."
+  (declare (obsolete diary-icalendar-format-entry "31.1"))
   (if (functionp icalendar-import-format)
       (funcall icalendar-import-format event)
     (let ((string icalendar-import-format)
@@ -2093,6 +2468,7 @@ events are created as non-marking.
 This function attempts to return t if something goes wrong.  In this
 case an error string which describes all the errors and problems is
 written into the buffer `*icalendar-errors*'."
+  (declare (obsolete diary-icalendar-import-buffer "31.1"))
   (let* ((ev (icalendar--all-events ical-list))
          (error-string "")
          (event-ok t)
@@ -2255,6 +2631,7 @@ written into the buffer `*icalendar-errors*'."
 DTSTART-DEC is the DTSTART property of E.
 START-T is the event's start time in diary format.
 END-T is the event's end time in diary format."
+  (declare (obsolete diary-icalendar-format-entry "31.1"))
   (icalendar--dmsg "recurring event")
   (let* ((rrule        (icalendar--get-event-property e 'RRULE))
          (rrule-props  (icalendar--split-value rrule))
@@ -2492,6 +2869,7 @@ END-T is the event's end time in diary format."
 DTSTART is the decoded DTSTART property of E.
 Argument START-D gives the first day.
 Argument END-D gives the last day."
+  (declare (obsolete diary-icalendar-format-time-range "31.1"))
   (icalendar--dmsg "non-recurring all-day event")
   (format "%%%%(and (diary-block %s %s))" start-d end-d))
 
@@ -2503,6 +2881,7 @@ Argument END-D gives the last day."
 DTSTART-DEC is the decoded DTSTART property of E.
 START-T is the event's start time in diary format.
 END-T is the event's end time in diary format."
+  (declare (obsolete diary-icalendar-format-time-range "31.1"))
   (icalendar--dmsg "not all day event")
   (cond (end-t
          (format "%s %s-%s"
@@ -2523,6 +2902,8 @@ determines whether diary events are created as non-marking.  If
 SUMMARY is not nil it must be a string that gives the summary of the
 entry.  In this case the user will be asked whether he wants to insert
 the entry."
+  (declare (obsolete "see `diary-icalendar-post-entry-format-hook' and
+`diary-icalendar--entry-import'" "31.1"))
   (when (or (not summary)
             (y-or-n-p (format-message "Add appointment for `%s' to diary? "
                                       summary)))
@@ -2541,6 +2922,7 @@ the entry."
 ;; ======================================================================
 (defun icalendar-import-format-sample (event)
   "Example function for formatting an iCalendar EVENT."
+  (declare (obsolete "see `diary-icalendar-vevent-skeleton'" "31.1"))
   (format (concat "SUMMARY='%s' DESCRIPTION='%s' LOCATION='%s' ORGANIZER='%s' "
                   "STATUS='%s' URL='%s' CLASS='%s'")
           (or (icalendar--get-event-property event 'SUMMARY) "")
@@ -2551,6 +2933,8 @@ the entry."
           (or (icalendar--get-event-property event 'URL) "")
           (or (icalendar--get-event-property event 'CLASS) "")))
 
+) ; Closes the top-level `with-suppressed-warnings' form above
+
 ;; Obsolete
 
 (defconst icalendar-version "0.19" "Version number of icalendar.el.")
@@ -2558,4 +2942,7 @@ the entry."
 
 (provide 'icalendar)
 
+;; Local Variables:
+;; read-symbol-shorthands: (("ical:" . "icalendar-"))
+;; End:
 ;;; icalendar.el ends here
diff --git a/lisp/calendar/lunar.el b/lisp/calendar/lunar.el
index 1f7107b1037..e20cf52013e 100644
--- a/lisp/calendar/lunar.el
+++ b/lisp/calendar/lunar.el
@@ -150,7 +150,7 @@ remainder mod 4 gives the phase: 0 new moon, 1 first quarter, 2 full moon,
          (time (* 24 (- date (truncate date))))
          (date (calendar-gregorian-from-absolute (truncate date)))
          (adj (dst-adjust-time date time)))
-    (list (car adj) (apply 'solar-time-string (cdr adj)) phase eclipse)))
+    (list (car adj) (apply #'solar-time-string (cdr adj)) phase eclipse)))
 
 ;; from "Astronomy with your Personal Computer", Subroutine Eclipse
 ;; Line 7000 Peter Duffett-Smith Cambridge University Press 1990
diff --git a/lisp/calendar/solar.el b/lisp/calendar/solar.el
index bb3d5cc1546..eeba372e69c 100644
--- a/lisp/calendar/solar.el
+++ b/lisp/calendar/solar.el
@@ -668,7 +668,7 @@ Optional NOLOCATION non-nil means do not print the location."
          (concat "sunset " (apply #'solar-time-string (cadr l)))
        "no sunset")
      (if nolocation ""
-       (format " at %s" (eval calendar-location-name)))
+       (format " at %s" (eval calendar-location-name t)))
      (nth 2 l))))
 
 (defconst solar-data-list
@@ -881,7 +881,7 @@ Accurate to a few seconds."
          (last (calendar-last-day-of-month month year))
          (title (format "Sunrise/sunset times for %s %d at %s"
                         (calendar-month-name month) year
-                        (eval calendar-location-name))))
+                        (eval calendar-location-name t))))
     (calendar-in-read-only-buffer solar-sunrises-buffer
       (calendar-set-mode-line title)
       (insert title ":\n\n")
diff --git a/lisp/calendar/timeclock.el b/lisp/calendar/timeclock.el
index 8afecb19cfa..acdf99f77ae 100644
--- a/lisp/calendar/timeclock.el
+++ b/lisp/calendar/timeclock.el
@@ -296,7 +296,7 @@ set before switching this mode on."
 `timeclock-use-display-time' to see timeclock information"))
               (add-hook 'display-time-hook #'timeclock-update-mode-line))
           (setq timeclock-update-timer
-                (run-at-time nil 60 'timeclock-update-mode-line))))
+                (run-at-time nil 60 #'timeclock-update-mode-line))))
     (setq global-mode-string
           (delq 'timeclock-mode-string global-mode-string))
     (remove-hook 'timeclock-event-hook #'timeclock-update-mode-line)
@@ -513,8 +513,8 @@ non-nil, the amount returned will be relative to past time worked."
         (message "%s" string)
       string)))
 
-(define-obsolete-function-alias 'timeclock-time-to-seconds 'float-time "26.1")
-(define-obsolete-function-alias 'timeclock-seconds-to-time 'time-convert "26.1")
+(define-obsolete-function-alias 'timeclock-time-to-seconds #'float-time "26.1")
+(define-obsolete-function-alias 'timeclock-seconds-to-time #'time-convert "26.1")
 
 ;; Should today-only be removed in favor of timeclock-relative? - gm
 (defsubst timeclock-when-to-leave (&optional today-only)
diff --git a/lisp/cedet/semantic/decorate/include.el b/lisp/cedet/semantic/decorate/include.el
index c91b04fb6a1..021c2d8fee9 100644
--- a/lisp/cedet/semantic/decorate/include.el
+++ b/lisp/cedet/semantic/decorate/include.el
@@ -352,9 +352,9 @@ Argument EVENT is the mouse clicked event."
          (file (semantic-dependency-tag-file tag))
          (table (when file
                   (semanticdb-file-table-object file t))))
-    (with-output-to-temp-buffer (help-buffer) ; "*Help*"
-      (help-setup-xref (list #'semantic-decoration-include-describe)
-                       (called-interactively-p 'interactive))
+    (help-setup-xref (list #'semantic-decoration-include-describe)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer) ; "*Help*"
       (princ "Include File: ")
       (princ (semantic-format-tag-name tag nil t))
       (princ "\n")
@@ -451,9 +451,9 @@ Argument EVENT is the mouse clicked event."
   (interactive)
   (let ((tag (semantic-current-tag))
         (mm major-mode))
-    (with-output-to-temp-buffer (help-buffer) ; "*Help*"
-      (help-setup-xref (list #'semantic-decoration-unknown-include-describe)
-                       (called-interactively-p 'interactive))
+    (help-setup-xref (list #'semantic-decoration-unknown-include-describe)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer) ; "*Help*"
       (princ "Include File: ")
       (princ (semantic-format-tag-name tag nil t))
       (princ "\n\n")
@@ -534,9 +534,9 @@ Argument EVENT is the mouse clicked event."
   (let* ((tag (semantic-current-tag))
          (table (semanticdb-find-table-for-include tag (current-buffer)))
          ) ;; (mm major-mode)
-    (with-output-to-temp-buffer (help-buffer) ; "*Help*"
-      (help-setup-xref (list #'semantic-decoration-fileless-include-describe)
-                       (called-interactively-p 'interactive))
+    (help-setup-xref (list #'semantic-decoration-fileless-include-describe)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer) ; "*Help*"
       (princ "Include Tag: ")
       (princ (semantic-format-tag-name tag nil t))
       (princ "\n\n")
@@ -573,10 +573,9 @@ Argument EVENT describes the event that caused this function to be called."
 Argument EVENT is the mouse clicked event."
   (interactive)
   (let ((tag (semantic-current-tag)))
-    (with-output-to-temp-buffer (help-buffer); "*Help*"
-      (help-setup-xref (list #'semantic-decoration-unparsed-include-describe)
-                       (called-interactively-p 'interactive))
-
+    (help-setup-xref (list #'semantic-decoration-unparsed-include-describe)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer); "*Help*"
       (princ "Include File: ")
       (princ (semantic-format-tag-name tag nil t))
       (princ "\n")
@@ -654,10 +653,9 @@ Argument EVENT describes the event that caused this function to be called."
          (tags (semantic-fetch-tags))
          (inc (semantic-find-tags-by-class 'include table))
          )
-    (with-output-to-temp-buffer (help-buffer) ;"*Help*"
-      (help-setup-xref (list #'semantic-decoration-all-include-summary)
-                       (called-interactively-p 'interactive))
-
+    (help-setup-xref (list #'semantic-decoration-all-include-summary)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer) ;"*Help*"
       (princ "Include Summary for File: ")
       (princ (file-truename (buffer-file-name)))
       (princ "\n")
diff --git a/lisp/cedet/semantic/util.el b/lisp/cedet/semantic/util.el
index a1cd2cfde24..2ca8de839b5 100644
--- a/lisp/cedet/semantic/util.el
+++ b/lisp/cedet/semantic/util.el
@@ -271,10 +271,9 @@ If TAG is not specified, use the tag at point."
   (interactive)
   (let ((buff (current-buffer))
         )
-
-    (with-output-to-temp-buffer (help-buffer)
-      (help-setup-xref (list #'semantic-describe-buffer)
-                       (called-interactively-p 'interactive))
+    (help-setup-xref (list #'semantic-describe-buffer)
+                     (called-interactively-p 'interactive))
+    (with-help-window (help-buffer)
       (with-current-buffer standard-output
         (princ "Semantic Configuration in ")
         (princ (buffer-name buff))
diff --git a/lisp/comint.el b/lisp/comint.el
index f4d484f037d..8d2692e50e6 100644
--- a/lisp/comint.el
+++ b/lisp/comint.el
@@ -3715,6 +3715,9 @@ last function is the text that is actually inserted in the redirection buffer.
 You can use `add-hook' to add functions to this list
 either globally or locally.")
 
+(defvar comint-redirect-hook nil
+  "Normal hook run after completing a comint-redirect.")
+
 ;; Internal variables
 
 (defvar comint-redirect-output-buffer nil
diff --git a/lisp/desktop.el b/lisp/desktop.el
index 74961032303..df98079b1c2 100644
--- a/lisp/desktop.el
+++ b/lisp/desktop.el
@@ -1064,13 +1064,19 @@ DIRNAME must be the directory in which the desktop file will be saved."
 
 ;; ----------------------------------------------------------------------------
 (defun desktop--check-dont-save (frame)
-  (not (frame-parameter frame 'desktop-dont-save)))
+  (and (not (frame-parameter frame 'desktop-dont-save))
+       ;; Don't save daemon initial frames, since we cannot (and don't
+       ;; need to) restore them.
+       (not (and (daemonp)
+                 (equal (terminal-name (frame-terminal frame))
+                        "initial_terminal")))))
 
 (defconst desktop--app-id `(desktop . ,desktop-file-version))
 
 (defun desktop-save-frameset ()
   "Save the state of existing frames in `desktop-saved-frameset'.
-Frames with a non-nil `desktop-dont-save' parameter are not saved."
+Frames with a non-nil `desktop-dont-save' parameter are not saved.
+Likewise the initial frame of a daemon sesion."
   (setq desktop-saved-frameset
         (and desktop-restore-frames
              (frameset-save nil
diff --git a/lisp/doc-view.el b/lisp/doc-view.el
index 30311e1a8ed..4e28dd400ce 100644
--- a/lisp/doc-view.el
+++ b/lisp/doc-view.el
@@ -955,7 +955,7 @@ It's a subdirectory of `doc-view-cache-directory'."
 (defun doc-view-mode-p (type)
   "Return non-nil if document type TYPE is available for `doc-view'.
 Document types are symbols like `dvi', `ps', `pdf', `epub',
-`cbz', `fb2', `xps', `oxps', or`odf' (any OpenDocument format)."
+`cbz', `fb2', `xps', `oxps', or `odf' (any OpenDocument format)."
   (and (display-graphic-p)
        (image-type-available-p 'png)
        (cond
diff --git a/lisp/emacs-lisp/byte-opt.el b/lisp/emacs-lisp/byte-opt.el
index c5458c1ba69..0290a2fd6ca 100644
--- a/lisp/emacs-lisp/byte-opt.el
+++ b/lisp/emacs-lisp/byte-opt.el
@@ -341,14 +341,13 @@ There can be multiple entries for the same NAME if it has several aliases.")
        (if (cdr exps)
            (macroexp-progn (byte-optimize-body exps for-effect))
          (byte-optimize-form (car exps) for-effect)))
+
       (`(prog1 ,exp . ,exps)
-       (let ((exp-opt (byte-optimize-form exp for-effect)))
-         (if exps
-             (let ((exps-opt (byte-optimize-body exps t)))
-               (if (macroexp-const-p exp-opt)
-                   `(progn ,@exps-opt ,exp-opt)
-                 `(,fn ,exp-opt ,@exps-opt)))
-           exp-opt)))
+       (let ((exp-opt (byte-optimize-form exp for-effect))
+             (exps-opt (byte-optimize-body exps t)))
+         (cond ((null exps-opt) exp-opt)
+               ((macroexp-const-p exp-opt) `(progn ,@exps-opt ,exp-opt))
+               (t `(,fn ,exp-opt ,@exps-opt)))))
 
       (`(,(or `save-excursion `save-restriction `save-current-buffer) . ,exps)
        ;; Those subrs which have an implicit progn; it's not quite good
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index fbb2b8e6971..98dbbb8e2f8 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/lisp/emacs-lisp/bytecomp.el
@@ -1857,7 +1857,8 @@ It is too wide if it has any lines longer than the largest of
          ;; The native compiler doesn't use those dynamic docstrings.
          (not byte-native-compiling)
          ;; Docstrings can only be dynamic when compiling a file.
-         byte-compile--\#$)
+         byte-compile--\#$
+         (not (equal doc "")))        ; empty lazy strings are pointless
     (let* ((byte-pos (with-memoization
                          ;; Reuse a previously written identical docstring.
                          ;; This is not done out of thriftiness but to try and
@@ -5142,7 +5143,8 @@ binding slots have been popped."
          (when (stringp doc)
            (setq rest (byte-compile--list-with-n
                        rest 0
-                       (byte-compile--docstring doc (nth 0 form) name)))))
+                       (byte-compile--docstring doc (nth 0 form) name)))
+           (setq form (nconc (take 3 form) rest))))
        (pcase-let*
            ;; `macro' is non-nil if it defines a macro.
            ;; `fun' is the function part of `arg' (defaults to `arg').
diff --git a/lisp/emacs-lisp/checkdoc.el b/lisp/emacs-lisp/checkdoc.el
index c9f9082a27a..fd226b89fda 100644
--- a/lisp/emacs-lisp/checkdoc.el
+++ b/lisp/emacs-lisp/checkdoc.el
@@ -381,6 +381,9 @@ large number of libraries means it is impractical to fix all
 of these warnings masse.  In almost any other case, setting
 this to anything but t is likely to be counter-productive.")
 
+(defvar checkdoc--batch-flag nil
+  "Non-nil in batch mode.")
+
 (defun checkdoc-list-of-strings-p (obj)
   "Return t when OBJ is a list of strings."
   (declare (obsolete list-of-strings-p "29.1"))
@@ -1063,12 +1066,13 @@ Optional argument INTERACT permits more interactive fixing."
          (e (checkdoc-rogue-space-check-engine nil nil interact))
          (checkdoc-generate-compile-warnings-flag
           (or take-notes checkdoc-generate-compile-warnings-flag)))
-    (if (not (called-interactively-p 'interactive))
+    (if (not (or (called-interactively-p 'interactive) checkdoc--batch-flag))
         e
       (if e
           (message "%s" (checkdoc-error-text e))
         (checkdoc-show-diagnostics)
-        (message "Space Check: done.")))))
+        (if (called-interactively-p 'interactive)
+            (message "Space Check: done."))))))
 
 ;;;###autoload
 (defun checkdoc-message-text (&optional take-notes)
@@ -1081,7 +1085,7 @@ Optional argument TAKE-NOTES causes all errors to be logged."
          (checkdoc-generate-compile-warnings-flag
           (or take-notes checkdoc-generate-compile-warnings-flag)))
     (setq e (checkdoc-message-text-search))
-    (if (not (called-interactively-p 'interactive))
+    (if (not (or (called-interactively-p 'interactive) checkdoc--batch-flag))
         e
       (if e
           (user-error "%s" (checkdoc-error-text e))
@@ -2819,7 +2823,7 @@ function called to create the messages."
 
 (defun checkdoc-show-diagnostics ()
   "Display the checkdoc diagnostic buffer in a temporary window."
-  (if checkdoc-pending-errors
+  (if (and checkdoc-pending-errors (not checkdoc--batch-flag))
       (let* ((b (get-buffer checkdoc-diagnostic-buffer))
              (win (if b (display-buffer b))))
         (when win
@@ -2832,6 +2836,23 @@ function called to create the messages."
         (setq checkdoc-pending-errors nil)
         nil)))
 
+
+;;;###autoload
+(defun checkdoc-batch ()
+  "Check current buffer in batch mode.
+Report any errors and signal the first found error."
+  (when noninteractive
+    (let ((checkdoc-autofix-flag nil)
+          (checkdoc--batch-flag t))
+      (checkdoc-current-buffer t)
+      (when checkdoc-pending-errors
+        (when-let* ((b (get-buffer checkdoc-diagnostic-buffer)))
+          (with-current-buffer b
+            (princ (buffer-string)))
+          (terpri))
+        (checkdoc-current-buffer)))))
+
+
 (defun checkdoc-get-keywords ()
   "Return a list of package keywords for the current file."
   (save-excursion
diff --git a/lisp/emacs-lisp/cond-star.el b/lisp/emacs-lisp/cond-star.el
index fc8e261339e..33a21602d9b 100644
--- a/lisp/emacs-lisp/cond-star.el
+++ b/lisp/emacs-lisp/cond-star.el
@@ -58,7 +58,7 @@ normally has the form (CONDITION BODY...).
 
 CONDITION can be a Lisp expression, as in `cond'.
 Or it can be one of `(bind* BINDINGS...)', `(match* PATTERN DATUM)',
-or `(pcase* PATTERN DATUM)',
+`(bind-and* BINDINGS...)' or `(pcase* PATTERN DATUM)',
 
 `(bind* BINDINGS...)' means to bind BINDINGS (as if they were in `let*')
 for the body of the clause, and all subsequent clauses, since the `bind*'
@@ -81,15 +81,17 @@ When a clause's condition is true, and it exits the `cond*'
 or is the last clause, the value of the last expression
 in its body becomes the return value of the `cond*' construct.
 
-Non-exit clause:
+Non-exit clauses:
 
-If a clause has only one element, or if its first element is
-t or a `bind*' clause, this clause never exits the `cond*' construct.
-Instead, control always falls through to the next clause (if any).
-All bindings made in CONDITION for the BODY of the non-exit clause
-are passed along to the rest of the clauses in this `cond*' construct.
+If a clause has only one element, or if its first element is t or a
+`bind*' form, or if it ends with the keyword `:non-exit', then this
+clause never exits the `cond*' construct.  Instead, control always falls
+through to the next clause (if any).  Except for a `bind-and*' clause,
+all bindings made in CONDITION for the BODY of the non-exit clause are
+passed along to the rest of the clauses in this `cond*' construct.
 
-\\[match*] for documentation of the patterns for use in `match*'."
+See `match*' for documentation of the patterns for use in `match*'
+conditions."
   ;; FIXME: Want an Edebug declaration.
   (cond*-convert clauses))
 
@@ -195,7 +197,9 @@ CONDITION of a `cond*' clause.  See `cond*' for details."
            (or (eq (car clause) t)
                ;; Starts with a `bind*' pseudo-form.
                (and (consp (car clause))
-                    (eq (caar clause) 'bind*))))))
+                    (eq (caar clause) 'bind*))))
+      ;; Ends with keyword.
+      (eq (car (last clause)) :non-exit)))
 
 (defun cond*-non-exit-clause-substance (clause)
   "For a non-exit cond* clause CLAUSE, return its substance.
@@ -214,7 +218,7 @@ This removes a final keyword if that's what makes CLAUSE non-exit."
          (cons t (cdr clause)))
 
         ;; Ends with keyword.
-        ((keywordp (car (last clause)))
+        ((eq (car (last clause)) :non-exit)
          ;; Do NOT include the final keyword.
          (butlast clause))))
 
diff --git a/lisp/emacs-lisp/crm.el b/lisp/emacs-lisp/crm.el
index 6bd763d2ea2..a1c7175fc66 100644
--- a/lisp/emacs-lisp/crm.el
+++ b/lisp/emacs-lisp/crm.el
@@ -255,14 +255,11 @@ with empty strings removed."
                   crm-local-must-match-map
                 crm-local-completion-map))
          (map (minibuffer-visible-completions--maybe-compose-map map))
-         (buffer (current-buffer))
          input)
     (minibuffer-with-setup-hook
         (lambda ()
           (add-hook 'choose-completion-string-functions
                     'crm--choose-completion-string nil 'local)
-          (setq-local minibuffer-completion-table #'crm--collection-fn)
-          (setq-local minibuffer-completion-predicate predicate)
           (setq-local completion-list-insert-choice-function
                       (lambda (_start _end choice)
                         (let* ((beg (save-excursion
@@ -276,14 +273,9 @@ with empty strings removed."
                                           (1- (point))
                                         (point-max)))))
                           (completion--replace beg end choice))))
-          ;; see completing_read in src/minibuf.c
-          (setq-local minibuffer-completion-confirm
-                      (unless (eq require-match t) require-match))
-          (setq-local minibuffer--require-match require-match)
-          (setq-local minibuffer--original-buffer buffer)
           (setq-local crm-completion-table table)
-          (completions--start-eager-display))
-      (setq input (read-from-minibuffer
+          (use-local-map map))
+      (setq input (completing-read
                    (format-spec
                     crm-prompt
                     (let* ((sep (or (get-text-property 0 'separator crm-separator)
@@ -291,11 +283,8 @@ with empty strings removed."
                            (desc (or (get-text-property 0 'description crm-separator)
                                      (concat "list separated by " sep))))
                       `((?s . ,sep) (?d . ,desc) (?p . ,prompt))))
-                   initial-input map nil hist def inherit-input-method)))
-    ;; If the user enters empty input, `read-from-minibuffer'
-    ;; returns the empty string, not DEF.
-    (when (and def (string-equal input ""))
-      (setq input (if (consp def) (car def) def)))
+                   #'crm--collection-fn predicate
+                   require-match initial-input hist def inherit-input-method)))
     ;; Remove empty strings in the list of read strings.
     (split-string input crm-separator t)))
 
diff --git a/lisp/emacs-lisp/loaddefs-gen.el b/lisp/emacs-lisp/loaddefs-gen.el
index 60d250b564f..0dc0d873bcd 100644
--- a/lisp/emacs-lisp/loaddefs-gen.el
+++ b/lisp/emacs-lisp/loaddefs-gen.el
@@ -732,11 +732,8 @@ instead of just updating them with the new/changed autoloads."
              '(t (escape-newlines . t)
                  (escape-control-characters . t)))
       (insert " "))
-    (let ((start (point)))
-      (prin1 (pop def) (current-buffer) t)
-      (save-excursion
-        (goto-char (1+ start))
-        (insert "\\\n")))
+    (delete-char -1) (insert "\n")
+    (prin1 (pop def) (current-buffer) t)
     (while def
       (insert " ")
       (prin1 (pop def) (current-buffer)
diff --git a/lisp/emacs-lisp/package-activate.el b/lisp/emacs-lisp/package-activate.el
index e130304be5c..1689d985c28 100644
--- a/lisp/emacs-lisp/package-activate.el
+++ b/lisp/emacs-lisp/package-activate.el
@@ -30,6 +30,8 @@
 ;; activate packages at startup, as well as other functions that are
 ;; useful without having to load the entirety of package.el.
 
+;; Note that the contents of this file are preloaded!
+
 ;;; Code:
 
 (eval-when-compile (require 'cl-lib))
@@ -534,5 +536,148 @@ the `Version:' header."
           (require 'lisp-mnt)
           (lm-package-version mainfile)))))))
 
+
+;;;; Package suggestions system
+
+;; Note that only the definitions necessary to recognise package
+;; suggestions are defined here.  The user interface to select and act
+;; on package suggestions is to be found in package.el.
+
+(defcustom package-autosuggest-style 'mode-line
+  "How to draw attention to `package-autosuggest-mode' suggestions.
+You can set this value to `mode-line' (default) to indicate the
+availability of a package suggestion in the minor mode, `always' to
+prompt the user in the minibuffer every time a suggestion is available
+in a `fundamental-mode' buffer, or `message' to just display a message
+hinting at the existence of a suggestion.  If you only wish to be
+reminded of package suggestions once every session, consider customizing
+the `package-autosuggest-once' user option."
+  :type '(choice (const :tag "Indicate in mode line" mode-line)
+                 (const :tag "Always prompt" always)
+                 (const :tag "Indicate with message" message))
+  :group 'package)
+
+(defcustom package-autosuggest-once nil
+  "Non-nil means not to repeat package suggestions."
+  :type 'boolean
+  :group 'package)
+
+(defvar package--autosuggest-database 'unset
+  "A list of package suggestions.
+Each entry in the list is of a form suitable to for
+`package--suggestion-applies-p', which see.  The special value `unset'
+is used to indicate that `package--autosuggest-find-candidates' should
+load the database into memory.")
+
+(defvar package--autosuggest-suggested '()
+  "List of packages that have already been suggested.
+Suggestions found in this list will not count as suggestions (e.g. if
+`package-autosuggest-style' is set to `mode-line', a suggestion found in
+here will inhibit `package-autosuggest-mode' from displaying a hint in
+the mode line).")
+
+(defun package--suggestion-applies-p (sug)
+  "Check if a suggestion SUG is applicable to the current buffer.
+Each suggestion has the form (PACKAGE TYPE DATA), where PACKAGE is a
+symbol denoting the package and major-mode the suggestion applies to,
+TYPE is one of `auto-mode-alist', `magic-mode-alist' or
+`interpreter-mode-alist' indicating the type of check to be made and
+DATA is the value to check against TYPE in the intuitive way (e.g. for
+`auto-mode-alist' DATA is a regular expression matching a file name that
+PACKAGE should be suggested for).  If the package name and the major
+mode name differ, then an optional forth element MAJOR-MODE can indicate
+what command to invoke to enable the package."
+  (pcase sug
+    ((or (guard (not (eq major-mode 'fundamental-mode)))
+         (guard (and package-autosuggest-once
+                     (not (memq (car sug) package--autosuggest-suggested))))
+         `(,(pred package-installed-p) . ,_))
+     nil)
+    (`(,_ auto-mode-alist ,ext . ,_)
+     (and (buffer-file-name) (string-match-p ext (buffer-file-name)) t))
+    (`(,_ magic-mode-alist ,mag . ,_)
+     (without-restriction
+       (save-excursion
+         (goto-char (point-min))
+         (looking-at-p mag))))
+    (`(,_ interpreter-mode-alist ,intr . ,_)
+     (without-restriction
+       (save-excursion
+         (goto-char (point-min))
+         (and (looking-at auto-mode-interpreter-regexp)
+              (string-match-p
+               (concat "\\`" (file-name-nondirectory (match-string 2)) "\\'")
+               intr)))))))
+
+(defun package--autosuggest-find-candidates ()
+    "Return a list of suggestions that might be interesting the current buffer.
+The elements of the returned list will have the form described in
+`package--suggestion-applies-p'."
+    (and (eq major-mode 'fundamental-mode)
+         (let ((suggetions '()))
+           (when (eq package--autosuggest-database 'unset)
+             (setq package--autosuggest-database
+                   (with-temp-buffer
+                     (insert-file-contents
+                      (expand-file-name "package-autosuggest.eld"
+                                        data-directory))
+                     (read (current-buffer)))))
+           (dolist (sug package--autosuggest-database)
+             (when (package--suggestion-applies-p sug)
+               (push sug suggetions)))
+           suggetions)))
+
+(defvar package--autosugest-line-format
+  '(:eval (package--autosugest-line-format)))
+(put 'package--autosugest-line-format 'risky-local-variable t)
+
+(defun package--autosugest-line-format ()
+  "Generate a mode-line string to indicate a suggested package."
+  `(,@(and-let* (((not (null package-autosuggest-mode)))
+                 ((eq package-autosuggest-style 'mode-line))
+                 (avail (package--autosuggest-find-candidates)))
+        (propertize
+         "[Upgrade?]"
+         'face 'mode-line-emphasis
+         'mouse-face 'mode-line-highlight
+         'help-echo "Click to install suggested package."
+         'keymap (let ((map (make-sparse-keymap)))
+                   (define-key map [mode-line down-mouse-1] #'package-autosuggest)
+                   map)))))
+
+(declare-function package-autosuggest "package" (&optional candidates))
+
+(defun package--autosuggest-after-change-mode ()
+  "Display package suggestions for the current buffer.
+This function should be added to `after-change-major-mode-hook'."
+  (when-let* ((avail (package--autosuggest-find-candidates))
+              (pkgs (mapconcat #'symbol-name
+                               (delete-dups (mapcar #'car avail))
+                               ", ")))
+    (pcase-exhaustive package-autosuggest-style
+      ('mode-line
+       (setq mode-name (append (ensure-list mode-name)
+                               '((package-autosuggest-mode
+                                  package--autosugest-line-format))))
+       (force-mode-line-update t))
+      ('always
+       (package-autosuggest avail))
+      ('message
+       (message
+        (substitute-command-keys
+         (format "Found suggested packages: %s.  Install using  \\[package-autosuggest]"
+                 pkgs)))
+       (dolist (rec avail)
+         (add-to-list 'package--autosuggest-suggested (car rec)))))))
+
+;;;###autoload
+(define-minor-mode package-autosuggest-mode
+  "Enable the automatic suggestion and installation of packages."
+  :global t :group 'package
+  ;; :initialize #'custom-initialize-delay
+  (funcall (if package-autosuggest-mode #'add-hook #'remove-hook)
+           'after-change-major-mode-hook
+           #'package--autosuggest-after-change-mode))
+
 (provide 'package-activate)
 ;;; package-activate.el ends here
diff --git a/lisp/emacs-lisp/package.el b/lisp/emacs-lisp/package.el
index 407c4496d81..e2d35f20eb5 100644
--- a/lisp/emacs-lisp/package.el
+++ b/lisp/emacs-lisp/package.el
@@ -4530,6 +4530,122 @@ The list is displayed in a buffer named `*Packages*'."
   (list-packages t))
 
 
+;;;; Package Suggestions
+
+(defun package--autosuggest-install-and-enable (sug)
+  "Install and enable a package suggestion PKG-ENT.
+SUG should be of the form as described in `package--suggestion-applies-p'."
+  (let ((buffers-to-update '()))
+    (dolist (buf (buffer-list))
+      (with-current-buffer buf
+        (when (and (eq major-mode 'fundamental-mode) (buffer-file-name)
+                   (package--suggestion-applies-p sug))
+          (push buf buffers-to-update))))
+    (with-demoted-errors "Failed to install package: %S"
+      (package-install (car sug))
+      (dolist (buf buffers-to-update)
+        (with-demoted-errors "Failed to enable major mode: %S"
+          (with-current-buffer buf
+            (funcall-interactively (or (cadddr sug) (car sug)))))))))
+
+(defun package--autosugest-prompt (packages)
+  "Query the user whether to install PACKAGES or not.
+PACKAGES is a list of package suggestions in the form as described in
+`package--suggestion-applies-p'.  The function returns a non-nil value
+if affirmative, otherwise nil"
+  (let* ((inhibit-read-only t) (use-hard-newlines t)
+         (nl (propertize "\n" 'hard t)) (nlnl (concat nl nl))
+         (buf (current-buffer)))
+    (with-current-buffer (get-buffer-create
+                          (format "*package suggestion: %s*"
+                                  (buffer-name buf)))
+      (erase-buffer)
+      (insert
+       "The buffer \""
+       (buffer-name buf)
+       "\" currently lacks any language-specific support.
+The package manager can provide the editor support for these kinds of
+files by downloading a package from Emacs's package archive:" nl)
+
+      (when (length> packages 1)
+        (insert nl "(Note that there are multiple candidate packages,
+so you have to select which to install!)" nl))
+
+      (pcase-dolist (`(,pkg . ,sugs) (seq-group-by #'car packages))
+        (insert nl "* "
+                (buttonize (concat "Install " (symbol-name pkg))
+                           (lambda (_)
+                             (package--autosuggest-install-and-enable
+                              (car sugs))
+                             (quit-window)))
+                " ("
+                (buttonize "about"
+                           (lambda (_)
+                             (unless (assq pkg package-archive-contents)
+                               (package-read-all-archive-contents))
+                             (describe-package pkg)))
+                ", matches ")
+        (dolist (sug sugs)
+          (unless (eq (char-before) ?\s)
+            (insert ", "))
+          (pcase sug
+            (`(,_ auto-mode-alist . ,_)
+             (insert "file extension "))
+            (`(,_ magic-mode-alist . ,_)
+             (insert "magic bytes"))
+            (`(,_ interpreter-mode-alist . ,_)
+             (insert "interpreter "))))
+        (delete-horizontal-space) (insert ").")
+
+        (add-to-list 'package--autosuggest-suggested pkg))
+
+      (insert nl "* " (buttonize "Do not install anything" (lambda (_) (quit-window))) "."
+              nl "* " (buttonize "Permanently disable package suggestions"
+                            (lambda (_)
+                              (customize-save-variable
+                               'package-autosuggest-mode nil
+                               "Disabled at user's request")
+                              (quit-window)))
+              "."
+
+              nlnl "To learn more about package management, read "
+              (buttonize "(emacs) Packages" (lambda (_) (info "(emacs) Packages")))
+              ", and to learn more about how Emacs supports specific languages, read "
+              (buttonize "(emacs) Major modes" (lambda (_) (info "(emacs) Major modes")))
+              ".")
+
+      (fill-region (point-min) (point-max))
+      (special-mode)
+      (button-mode t)
+
+      (let ((win (display-buffer-below-selected (current-buffer) '())))
+        (fit-window-to-buffer win)
+        (select-window win)
+        (set-window-dedicated-p win t)
+        (set-window-point win (point-min))))))
+
+;;;###autoload
+(defun package-autosuggest (&optional candidates)
+  "Prompt the user to install the suggested packages.
+The optional argument CANDIDATES may be a list of packages that match
+for form described in `package--suggestion-applies-p'.  If omitted, the
+list of candidates will be computed from the database."
+  (interactive)
+  (package--autosugest-prompt
+   (or candidates
+       (package--autosuggest-find-candidates)
+       (user-error "No package suggestions found"))))
+
+(defun package-reset-suggestions ()
+  "Forget previous package suggestions.
+Emacs will remember if you have previously rejected a suggestion during
+a session and won't mention it afterwards.  If you have made a mistake
+or would like to reconsider this, use this command to want to reset the
+suggestions."
+  (interactive)
+  (setq package--autosuggest-suggested nil))
+
+
 ;;;; Quickstart: precompute activation actions for faster start up.
 
 (defvar Info-directory-list)
diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el
index 4963624ee2d..e0a41b380b5 100644
--- a/lisp/emacs-lisp/seq.el
+++ b/lisp/emacs-lisp/seq.el
@@ -567,7 +567,7 @@ This does not modify SEQUENCE1 or SEQUENCE2."
 
 ;;;###autoload
 (cl-defgeneric seq-intersection (sequence1 sequence2 &optional testfn)
-  "Return copy of SEQUENCE1 with elements that appear in SEQUENCE2 removed.
+  "Return copy of SEQUENCE1 with elements that do not appear in SEQUENCE2 removed.
 \"Equality\" of elements is defined by the function TESTFN, which
 defaults to `equal'.
 This does not modify SEQUENCE1 or SEQUENCE2."
@@ -579,7 +579,7 @@ This does not modify SEQUENCE1 or SEQUENCE2."
               '()))
 
 (cl-defgeneric seq-difference (sequence1 sequence2 &optional testfn)
-  "Return list of all the elements that appear in SEQUENCE1 but not in SEQUENCE2.
+  "Return copy of SEQUENCE1 with elements that appear in SEQUENCE2 removed.
 \"Equality\" of elements is defined by the function TESTFN, which
 defaults to `equal'.
 This does not modify SEQUENCE1 or SEQUENCE2."
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 70583e08dbd..8b382bd14dd 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -1707,7 +1707,9 @@ function's documentation in the Info manual"))
     ;; Doc string.
     (insert "  "
             (or (plist-get data :doc)
-                (car (split-string (documentation function) "\n"))))
+                (car (split-string (or (documentation function)
+                                       "Error: missing docstring.")
+                                   "\n"))))
     (insert "\n")
     (add-face-text-property start-section (point) 'shortdoc-section t)
     (let ((print-escape-newlines t)
diff --git a/lisp/emacs-lisp/smie.el b/lisp/emacs-lisp/smie.el
index 91f3332a79b..33821b8be28 100644
--- a/lisp/emacs-lisp/smie.el
+++ b/lisp/emacs-lisp/smie.el
@@ -1153,7 +1153,7 @@ METHOD can be:
 - :before, in which case ARG is a token and the function should return the
   OFFSET to use to indent ARG itself.
 - :elem, in which case the function should return either:
-  - the offset to use to indent function arguments (ARG = `arg')
+  - the offset to use to indent function arguments (ARG = `args')
   - the basic indentation step (ARG = `basic').
   - the token to use (when ARG = `empty-line-token') when we don't know how
     to indent an empty line.
diff --git a/lisp/emacs-lisp/subr-x.el b/lisp/emacs-lisp/subr-x.el
index 8d04958487f..b36b14b9b50 100644
--- a/lisp/emacs-lisp/subr-x.el
+++ b/lisp/emacs-lisp/subr-x.el
@@ -37,6 +37,7 @@
 
 (eval-when-compile (require 'cl-lib))
 
+(require 'mule-util)
 
 (defmacro internal--thread-argument (first? &rest forms)
   "Internal implementation for `thread-first' and `thread-last'.
@@ -357,6 +358,29 @@ buffer when possible, instead of creating a new one on each call."
              (progn ,@body)
            (work-buffer--release ,work-buffer))))))
 
+(defun work-buffer--prepare-pixelwise (string buffer)
+  "Set up the current buffer to correctly compute STRING's pixel width.
+Call this with a work buffer as the current buffer.
+BUFFER is the originating buffer and if non-nil, make the current
+buffer's (work buffer) face remappings match it."
+  (when buffer
+    (dolist (v '(face-remapping-alist
+                 char-property-alias-alist
+                 default-text-properties))
+      (if (local-variable-p v buffer)
+          (set (make-local-variable v)
+               (buffer-local-value v buffer)))))
+  ;; Avoid deactivating the region as side effect.
+  (let (deactivate-mark)
+    (insert string))
+  ;; If `display-line-numbers' is enabled in internal
+  ;; buffers (e.g. globally), it breaks width calculation
+  ;; (bug#59311).  Disable `line-prefix' and `wrap-prefix',
+  ;; for the same reason.
+  (add-text-properties
+   (point-min) (point-max)
+   '(display-line-numbers-disable t line-prefix "" wrap-prefix "")))
+
 ;;;###autoload
 (defun string-pixel-width (string &optional buffer)
   "Return the width of STRING in pixels.
@@ -371,27 +395,71 @@ substring that does not include newlines."
     ;; Keeping a work buffer around is more efficient than creating a
     ;; new temporary buffer.
     (with-work-buffer
-      ;; Setup current buffer to correctly compute pixel width.
-      (when buffer
-        (dolist (v '(face-remapping-alist
-                     char-property-alias-alist
-                     default-text-properties))
-          (if (local-variable-p v buffer)
-              (set (make-local-variable v)
-                   (buffer-local-value v buffer)))))
-      ;; Avoid deactivating the region as side effect.
-      (let (deactivate-mark)
-        (insert string))
-      ;; If `display-line-numbers' is enabled in internal
-      ;; buffers (e.g. globally), it breaks width calculation
-      ;; (bug#59311).  Disable `line-prefix' and `wrap-prefix',
-      ;; for the same reason.
-      (add-text-properties
-       (point-min) (point-max)
-       '(display-line-numbers-disable t line-prefix "" wrap-prefix ""))
+     (work-buffer--prepare-pixelwise string buffer)
       (car (buffer-text-pixel-size nil nil t)))))
 
 ;;;###autoload
+(defun truncate-string-pixelwise (string max-pixels &optional buffer
+                                  ellipsis ellipsis-pixels)
+  "Return STRING truncated to fit within MAX-PIXELS.
+If BUFFER is non-nil, use the face remappings, alternative and default
+properties from that buffer when determining the width.
+If you call this function to measure pixel width of a string
+with embedded newlines, it returns the width of the widest
+substring that does not include newlines.
+
+If ELLIPSIS is non-nil, it should be a string which will replace the end
+of STRING if it extends beyond MAX-PIXELS, unless the pixel width of
+STRING is equal to or less than the pixel width of ELLIPSIS.  If it is
+non-nil and not a string, then ELLIPSIS defaults to
+`truncate-string-ellipsis', or to three dots when it's nil.
+
+If ELLIPSIS-PIXELS is non-nil, it is the pixel width of ELLIPSIS, and
+can be used to avoid the cost of recomputing this for multiple calls to
+this function using the same ELLIPSIS."
+  (declare (important-return-value t))
+  (if (zerop (length string))
+      string
+    ;; Keeping a work buffer around is more efficient than creating a
+    ;; new temporary buffer.
+    (let ((original-buffer (or buffer (current-buffer))))
+      (with-work-buffer
+       (work-buffer--prepare-pixelwise string buffer)
+       (set-window-buffer nil (current-buffer) 'keep-margins)
+       ;; Use a binary search to prune the number of calls to
+       ;; `window-text-pixel-size'.
+       ;; These are 1-based buffer indexes.
+       (let* ((low 1)
+              (high (1+ (length string)))
+              mid)
+         (when (> (car (window-text-pixel-size nil 1 high)) max-pixels)
+           (when (and ellipsis (not (stringp ellipsis)))
+             (setq ellipsis (truncate-string-ellipsis)))
+           (setq ellipsis-pixels (if ellipsis
+                                     (if ellipsis-pixels
+                                         ellipsis-pixels
+                                       (string-pixel-width ellipsis buffer))
+                                   0))
+           (let ((adjusted-pixels
+                  (if (> max-pixels ellipsis-pixels)
+                      (- max-pixels ellipsis-pixels)
+                    max-pixels)))
+             (while (<= low high)
+               (setq mid (floor (+ low high) 2))
+               (if (<= (car (window-text-pixel-size nil 1 mid))
+                       adjusted-pixels)
+                   (setq low (1+ mid))
+                 (setq high (1- mid))))))
+         (set-window-buffer nil original-buffer 'keep-margins)
+         (if mid
+             ;; Binary search ran.
+             (if (and ellipsis (> max-pixels ellipsis-pixels))
+                 (concat (substring string 0 (1- high)) ellipsis)
+               (substring string 0 (1- high)))
+           ;; Fast path.
+           string))))))
+
+;;;###autoload
 (defun string-glyph-split (string)
   "Split STRING into a list of strings representing separate glyphs.
 This takes into account combining characters and grapheme clusters:
diff --git a/lisp/frameset.el b/lisp/frameset.el
index 85a90f67c68..e11a1da7e9b 100644
--- a/lisp/frameset.el
+++ b/lisp/frameset.el
@@ -1362,9 +1362,18 @@ All keyword parameters default to nil."
     ;; Clean up the frame list
     (when cleanup-frames
       (let ((map nil)
-            (cleanup (if (eq cleanup-frames t)
-                         (lambda (frame action)
-                           (when (memq action '(:rejected :ignored))
+            (cleanup
+             (if (eq cleanup-frames t)
+                 (lambda (frame action)
+                   (when (and (memq action '(:rejected :ignored))
+                              ;; Don't try deleting the daemon's initial
+                              ;; frame, as that would only trigger
+                              ;; warnings.
+                              (not
+                               (and (daemonp)
+                                    (equal (terminal-name (frame-terminal
+                                                           frame))
+                                           "initial_terminal"))))
                              (delete-frame frame)))
                        cleanup-frames)))
         (maphash (lambda (frame _action) (push frame map)) frameset--action-map)
diff --git a/lisp/gnus/gnus-group.el b/lisp/gnus/gnus-group.el
index 7214b440732..28c8c677d13 100644
--- a/lisp/gnus/gnus-group.el
+++ b/lisp/gnus/gnus-group.el
@@ -640,6 +640,7 @@ simple manner."
   "M-&" #'gnus-group-universal-argument
   "#" #'gnus-group-mark-group
   "M-#" #'gnus-group-unmark-group
+  "M-i" #'gnus-symbolic-argument
 
   "~" (define-keymap :prefix 'gnus-group-cloud-map
         "u" #'gnus-cloud-upload-all-data
diff --git a/lisp/gnus/gnus-topic.el b/lisp/gnus/gnus-topic.el
index 315f1a018c9..4fb796105e2 100644
--- a/lisp/gnus/gnus-topic.el
+++ b/lisp/gnus/gnus-topic.el
@@ -1158,7 +1158,8 @@ articles in the topic and its subtopics."
                   #'gnus-topic-group-indentation)
       (setq-local gnus-group-update-group-function
                   #'gnus-topic-update-topics-containing-group)
-      (setq-local gnus-group-sort-alist-function #'gnus-group-sort-topic)
+      (setq-local gnus-group-sort-alist-function #'gnus-group-sort-topic
+                  gnus-group-sort-selected-function #'gnus-group-sort-selected-topic)
       (setq gnus-group-change-level-function #'gnus-topic-change-level)
       (setq gnus-goto-missing-group-function #'gnus-topic-goto-missing-group)
       (add-hook 'gnus-check-bogus-groups-hook #'gnus-topic-clean-alist
@@ -1173,7 +1174,8 @@ articles in the topic and its subtopics."
       (setq gnus-group-change-level-function nil)
       (remove-hook 'gnus-check-bogus-groups-hook #'gnus-topic-clean-alist)
       (setq gnus-group-prepare-function #'gnus-group-prepare-flat)
-      (setq gnus-group-sort-alist-function #'gnus-group-sort-flat))
+      (setq gnus-group-sort-alist-function #'gnus-group-sort-flat
+            gnus-group-sort-selected-function #'gnus-group-sort-selected-flat))
     (when (called-interactively-p 'any)
       (gnus-group-list-groups))))
 
@@ -1651,6 +1653,28 @@ If performed on a topic, edit the topic parameters instead."
       (setcar alist (delete "dummy.group" (car alist)))
       (gnus-topic-sort-topic (pop alist) func reverse))))
 
+(defun gnus-group-sort-selected-topic (groups func reverse)
+  "Sort selected GROUPS in the topics according to FUNC and REVERSE."
+  (let ((alist gnus-topic-alist))
+    (while alist
+      ;; !!!Sometimes nil elements sneak into the alist,
+      ;; for some reason or other.
+      (setcar alist (delq nil (car alist)))
+      (setcar alist (delete "dummy.group" (car alist)))
+      (let* ((topic (pop alist))
+             (inter (seq-intersection groups (cdr topic))))
+        ;; Do something only if there are some selected groups in this
+        ;; topic.
+        (when inter
+          (let ((sorted (mapcar #'gnus-info-group
+                                (sort (mapcar #'gnus-get-info inter) func))))
+            ;; Do the reversal, if necessary.
+            (when reverse
+              (setq sorted (nreverse (cdr sorted))))
+            ;; Set the topic contents as the union of the sorted
+            ;; selected groups and its previous contents.
+            (setcdr topic (seq-union sorted (cdr topic)))))))))
+
 (defun gnus-topic-sort-topic (topic func reverse)
   ;; Each topic only lists the name of the group, while
   ;; the sort predicates expect group infos as inputs.
diff --git a/lisp/help-fns.el b/lisp/help-fns.el
index 6cbc75f92fb..f1ee109c87e 100644
--- a/lisp/help-fns.el
+++ b/lisp/help-fns.el
@@ -40,8 +40,8 @@
 
 (defvar help-fns-describe-function-functions nil
   "List of functions to run in help buffer in `describe-function'.
-Those functions will be run after the header line and argument
-list was inserted, and before the documentation is inserted.
+Those functions will be run after the header line, the argument
+list, and the function's documentation are inserted.
 The functions will be called with one argument: the function's symbol.
 They can assume that a newline was output just before they were called,
 and they should terminate any of their own output with a newline.
@@ -2242,7 +2242,7 @@ is enabled in the Help buffer."
             (insert (format "Minor mode%s enabled in this buffer:"
                             (if (length> local-minors 1)
                                 "s" ""))))
-          (describe-mode--minor-modes local-minors))
+          (describe-mode--minor-modes local-minors nil buffer))
 
         ;; Document the major mode.
         (let ((major (buffer-local-value 'major-mode buffer)))
@@ -2269,7 +2269,9 @@ is enabled in the Help buffer."
                                (help-function-def--button-function
                                 major file-name))))))
           (insert ":\n\n"
-                  (help-split-fundoc (documentation major) nil 'doc)
+                  (help-split-fundoc (with-current-buffer buffer
+                                       (documentation major))
+                                     nil 'doc)
                   (with-current-buffer buffer
                     (help-fns--list-local-commands)))
           (ensure-empty-lines 1)
@@ -2280,7 +2282,7 @@ is enabled in the Help buffer."
               (insert (format "Global minor mode%s enabled:"
                               (if (length> global-minor-modes 1)
                                   "s" ""))))
-            (describe-mode--minor-modes global-minor-modes t)
+            (describe-mode--minor-modes global-minor-modes t buffer)
             (unless describe-mode-outline
               (when (re-search-forward "^\f")
                 (beginning-of-line)
@@ -2297,7 +2299,7 @@ is enabled in the Help buffer."
           ;; For the sake of IELM and maybe others
           nil)))))
 
-(defun describe-mode--minor-modes (modes &optional global)
+(defun describe-mode--minor-modes (modes &optional global buffer)
   (dolist (mode (seq-sort #'string< modes))
     (let ((pretty-minor-mode
            (capitalize
@@ -2338,7 +2340,10 @@ is enabled in the Help buffer."
                               "no indicator"
                             (format "indicator%s"
                                     indicator)))))
-        (insert (or (help-split-fundoc (documentation mode) nil 'doc)
+        (insert (or (help-split-fundoc
+                     (with-current-buffer (or buffer (current-buffer))
+                       (documentation mode))
+                     nil 'doc)
                     "No docstring"))
         (when describe-mode-outline
           (insert "\n\n")))))
diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index f15ae633edc..47fa3590177 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -501,9 +501,13 @@ buffer after following a reference.  INTERACTIVE-P is non-nil if the
 calling command was invoked interactively.  In this case the stack of
 items for help buffer \"back\" buttons is cleared.
 
-This should be called very early, before the output buffer is cleared,
-because we want to record the \"previous\" position of point so we can
-restore it properly when going back."
+This function also re-enables the major mode of the buffer, thus
+resetting local variables to the values set by the mode and running the
+mode hooks.
+
+So this should be called very early, before the output buffer is
+cleared, also because we want to record the \"previous\" position of
+point so we can restore it properly when going back."
   (with-current-buffer (help-buffer)
     ;; Re-enable major mode, killing all unrelated local vars.
     (funcall major-mode)
diff --git a/lisp/icomplete.el b/lisp/icomplete.el
index c1d9556e24d..875c41bd841 100644
--- a/lisp/icomplete.el
+++ b/lisp/icomplete.el
@@ -79,11 +79,12 @@ selection process starts again from the user's $HOME."
 (defcustom icomplete-show-matches-on-no-input nil
   "When non-nil, show completions when first prompting for input.
 This means to show completions even when the current minibuffer contents
-is the same as was the initial input after minibuffer activation.
-This also means that if you traverse the list of completions with
-commands like \\`C-.' and just hit \\`RET' without typing any
-characters, the match under point will be chosen instead of the
-default."
+is the same as the initial input after minibuffer activation.
+This also means that if you just hit \\`C-j' without typing any
+characters, this chooses the first completion candidate instead of the
+minibuffer's default value.
+
+See also `icomplete-ret'."
   :type 'boolean
   :version "24.4")
 
@@ -242,16 +243,25 @@ Used to implement the option `icomplete-show-matches-on-no-input'.")
   :doc "Keymap used by `icomplete-mode' in the minibuffer."
   "C-M-i" #'icomplete-force-complete
   "C-j"   #'icomplete-force-complete-and-exit
-  "M-j"   #'icomplete-exit
   "C-."   #'icomplete-forward-completions
-  "C-,"   #'icomplete-backward-completions
-  "<remap> <minibuffer-complete-and-exit>" #'icomplete-ret)
+  "C-,"   #'icomplete-backward-completions)
 
 (defun icomplete-ret ()
-  "Exit minibuffer for icomplete."
+  "Alternative minibuffer exit for Icomplete.
+If there is a completion candidate and the minibuffer contents is the
+same as it was right after minibuffer activation, exit selecting that
+candidate.  Otherwise do as `minibuffer-complete-and-exit'.
+
+You may wish to consider binding this command to \\`RET' (or to
+`<remap> <minibuffer-complete-and-exit>') in `icomplete-minibuffer-map'.
+If you do that, then when Emacs first prompts for input such that the
+current minibuffer contents is equal to the initial input right after
+minibuffer activation, \\`RET' chooses the first completion candidate
+instead of the minibuffer's default value.
+This rebinding is especially useful if you have customized
+`icomplete-show-matches-on-no-input' to a non-nil value."
   (interactive)
-  (if (and icomplete-show-matches-on-no-input
-           (car completion-all-sorted-completions)
+  (if (and (car completion-all-sorted-completions)
            (equal (icomplete--field-string) icomplete--initial-input))
       (icomplete-force-complete-and-exit)
     (minibuffer-complete-and-exit)))
@@ -456,8 +466,6 @@ if that doesn't produce a completion match."
       (minibuffer-complete-and-exit)
     (exit-minibuffer)))
 
-(defalias 'icomplete-exit #'icomplete-fido-exit)
-
 (defun icomplete-fido-backward-updir ()
   "Delete char before or go up directory, like `ido-mode'."
   (interactive)
diff --git a/lisp/isearch.el b/lisp/isearch.el
index 5b5b2f0561a..b677e89c7cd 100644
--- a/lisp/isearch.el
+++ b/lisp/isearch.el
@@ -274,8 +274,6 @@ It is nil if none yet.")
 Default value, nil, means edit the string instead."
   :type 'boolean)
 
-(autoload 'char-fold-to-regexp "char-fold")
-
 (defcustom search-default-mode nil
   "Default mode to use when starting isearch.
 Value is nil, t, or a function.
@@ -2827,7 +2825,6 @@ With argument, add COUNT copies of the character."
                                            (mapconcat 'isearch-text-char-description
                                                       string ""))))))))
 
-(autoload 'emoji--read-emoji "emoji")
 (defun isearch-emoji-by-name (&optional count)
   "Read an Emoji name and add it to the search string COUNT times.
 COUNT (interactively, the prefix argument) defaults to 1.
@@ -2835,6 +2832,7 @@ The command accepts Unicode names like \"smiling face\" or
 \"heart with arrow\", and completion is available."
   (interactive "p")
   (emoji--init)
+  (declare-function emoji--read-emoji "emoji" ())
   (with-isearch-suspended
    (pcase-let* ((`(,glyph . ,derived) (emoji--read-emoji))
                 (emoji (if derived
diff --git a/lisp/json.el b/lisp/json.el
index f2086474a8b..82cc9c71bf5 100644
--- a/lisp/json.el
+++ b/lisp/json.el
@@ -609,12 +609,11 @@ transforms an unsortable MAP into a sortable alist."
   "Insert a JSON representation of ALIST at point.
 Sort ALIST first if `json-encoding-object-sort-predicate' is
 non-nil.  Sorting can optionally be DESTRUCTIVE for speed."
-  (json--print-map (if (and json-encoding-object-sort-predicate alist)
-                       (sort (if destructive alist (copy-sequence alist))
-                             (lambda (a b)
-                               (funcall json-encoding-object-sort-predicate
-                                        (car a) (car b))))
-                     alist)))
+  (json--print-map (let ((pred json-encoding-object-sort-predicate))
+                     (if (and pred alist)
+                         (sort alist :key #'car :lessp pred
+                               :in-place destructive)
+                       alist))))
 
 ;; The following two are unused but useful to keep around due to the
 ;; inherent ambiguity of lists.
diff --git a/lisp/language/indian.el b/lisp/language/indian.el
index 59076faea69..d0373086fe4 100644
--- a/lisp/language/indian.el
+++ b/lisp/language/indian.el
@@ -308,6 +308,7 @@ environment."))
            ("H" . "\u094D")             ; HALANT
            ("s" . "[\u0951\u0952]")     ; stress sign
            ("t" . "[\u0953\u0954]")     ; accent
+           ("D" . "[\u0964\u0965]")     ; punctuation sign
            ("1" . "\u0967")             ; numeral 1
            ("3" . "\u0969")             ; numeral 3
            ("N" . "\u200C")             ; ZWNJ
@@ -316,15 +317,15 @@ environment."))
     (indian-compose-regexp
      (concat
       ;; syllables with an independent vowel, or
-      "\\(?:RH\\)?Vn?\\(?:J?HR\\)?v*n?a?s?t?A?\\|"
+      "\\(?:RH\\)?Vn?\\(?:J?HR\\)?v*n?a?s?t?A?D?\\|"
       ;; consonant-based syllables, or
-      "Cn?\\(?:J?HJ?Cn?\\)*\\(?:H[NJ]?\\|v*n?a?s?t?A?\\)\\|"
+      "Cn?\\(?:J?HJ?Cn?\\)*\\(?:H[NJ]?D?\\|v*n?a?s?t?A?D?\\)\\|"
       ;; special consonant form, or
-      "JHR\\|"
+      "JHRD?\\|"
       ;; vedic accents with numerals, or
       "1ss?\\|3ss\\|s3ss\\|"
       ;; any other singleton characters
-      "X")
+      "XD?")
      table))
   "Regexp matching a composable sequence of Devanagari characters.")
 
diff --git a/lisp/leim/quail/ipa.el b/lisp/leim/quail/ipa.el
index 2d6c6fe5a38..846c9f96f0d 100644
--- a/lisp/leim/quail/ipa.el
+++ b/lisp/leim/quail/ipa.el
@@ -74,6 +74,7 @@ Upside-down characters are obtained by a preceding slash (/)."
  ("A~" ["ɑ̃"])
  ("oe~" ["œ̃"])
  ("/c~" ["ɔ̃"])
+ ("/E" ?ɜ)
  ("p" ?p)
  ("b" ?b)
  ("t" ?t)
diff --git a/lisp/leim/quail/iroquoian.el b/lisp/leim/quail/iroquoian.el
index 0bd822217b3..38b53f39483 100644
--- a/lisp/leim/quail/iroquoian.el
+++ b/lisp/leim/quail/iroquoian.el
@@ -24,7 +24,7 @@
 
 ;; This file implements input methods for Northern Iroquoian languages.
 
-;; Input methods are implemented for all Five Nations Iroquois
+;; Input methods are implemented for the following Northern Iroquoian
 ;; languages:
 
 ;; - Mohawk (Kanien’kéha / Kanyen’kéha / Onkwehonwehnéha)
@@ -32,6 +32,7 @@
 ;; - Onondaga (Onųdaʔgegáʔ)
 ;; - Cayuga (Gayogo̱ho:nǫhnéha:ˀ)
 ;; - Seneca (Onödowá’ga:’)
+;; - Tuscarora (Skarù·ręʔ)
 
 ;; A composite input method for all of the languages above is also
 ;; defined: `haudenosaunee-postfix'.
@@ -39,7 +40,6 @@
 ;; Input methods are not yet implemented for the remaining Northern
 ;; Iroquoian languages, including:
 
-;; - Tuscarora (Skarù:ręʔ)
 ;; - Wendat (Huron) / Wyandot
 
 ;;; Code:
@@ -799,6 +799,159 @@ simultaneously using the input method `haudenosaunee-postfix'."
   (quail-defrule key trans))
 
 
+;;; Tuscarora
+
+;;
+;; The primary community orthography used for Tuscarora follows that
+;; used in Blair Rudes's dictionary (see below).
+;;
+;; Reference work for Tuscarora orthography:
+;;
+;; Blair Rudes. 1999. Tuscarora-English/English-Tuscarora
+;; dictionary. Toronto: University of Toronto Press.
+;;
+
+(defconst iroquoian-tuscarora-modifier-alist
+  '(("::" ?\N{MIDDLE DOT}))
+  "Alist of rules for modifier letters in Tuscarora input methods.
+Entries are as with rules in `quail-define-rules'.")
+
+(defconst iroquoian-tuscarora-vowel-alist
+  '(("a'" ?á)
+    ("a`" ?à)
+    ("A'" ?Á)
+    ("A`" ?À)
+    ("e'" ?é)
+    ("e`" ?è)
+    ("E'" ?É)
+    ("E`" ?È)
+    ("i'" ?í)
+    ("i`" ?ì)
+    ("I'" ?Í)
+    ("I`" ?Ì)
+    ("u'" ?ú)
+    ("u`" ?ù)
+    ("U'" ?Ú)
+    ("U`" ?Ù)
+    ("e," ?ę)
+    ("e,'" ["ę́"])
+    ("e,`" ["ę̀"])
+    ("E," ?Ę)
+    ("E,'" ["Ę́"])
+    ("E,`" ["Ę̀"])
+
+    ("a''" ["a'"])
+    ("a``" ["a`"])
+    ("A''" ["A'"])
+    ("A``" ["A`"])
+    ("e''" ["e'"])
+    ("e``" ["e`"])
+    ("E''" ["E'"])
+    ("E``" ["E`"])
+    ("i''" ["i'"])
+    ("i``" ["i`"])
+    ("I''" ["I'"])
+    ("I``" ["I`"])
+    ("u''" ["u'"])
+    ("u``" ["u`"])
+    ("U''" ["U'"])
+    ("U``" ["U`"])
+
+    ("e,," ["e,"])
+    ("e,''" ["ę'"])
+    ("e,``" ["ę`"])
+    ("E,," ["E,"])
+    ("E,''" ["Ę'"])
+    ("E,``" ["Ę`"]))
+  "Alist of rules for vowel letters in Tuscarora input methods.
+Entries are as with rules in `quail-define-rules'.")
+
+(defconst iroquoian-tuscarora-consonant-alist
+  '((";;" ?\N{LATIN LETTER GLOTTAL STOP})
+    ("c/" ?č)
+    ("c//" ["c/"])
+    ("C/" ?Č)
+    ("C//" ["C/"])
+    ("t/" ?θ)
+    ("t//" ["t/"]))
+  "Alist of rules for consonant letters in Tuscarora input methods.
+Entries are as with rules in `quail-define-rules'.")
+
+(defconst iroquoian-tuscarora-exception-alist
+  '(("_" ?\N{COMBINING LOW LINE})
+    ("__" ?_))
+  "Alist of rules for phonological exception marking in Tuscarora input methods.
+Entries are as with rules in `quail-define-rules'.")
+
+(quail-define-package
+ "tuscarora-postfix" "Tuscarora" "TUS<" t
+ "Tuscarora (Skarù·ręʔ) input method with postfix modifiers
+
+Modifiers:
+
+| Key | Translation | Description              |
+|-----+-------------+--------------------------|
+| ::  | ·           | Vowel length             |
+
+Stress diacritics:
+
+| Key  | Description  | Example |
+|------+--------------+---------|
+| \\='    | Acute accent | a' -> á |
+| \\=`    | Grave accent | a` -> à |
+
+Doubling the postfix separates the letter and the postfix.
+
+Vowels:
+
+| Key | Translation | Description                     |
+|-----+-------------+---------------------------------|
+| e,  | ę           | Mid front nasal vowel           |
+| E,  | Ę           | Mid front nasal vowel (capital) |
+
+a, e, i, and u are bound to a single key.
+
+Consonants:
+
+| Key   | Translation | Description                        |
+|-------+-------------+------------------------------------|
+| ;;    | ˀ            | Glottal stop                       |
+| c/    | č            | Postalveolar affricate            |
+| C/    | Č            | Postalveolar affricate (capital)  |
+| t/    | θ            | Voiceless dental fricative        |
+
+h, k, n, r, s, t, w, and y are bound to a single key.
+
+b, l, m, and p are used rarely in loanwords.  They are also each bound
+to a single key.
+
+Stress exception markers:
+
+| Key | Description        | Example  |
+|-----+--------------------+----------|
+| _   | Combining low line | a_ -> a̲ |
+
+Note: Not all fonts can properly display a combining low line on all
+letters.
+
+Underlining has been used by some to indicate that vowels behave
+exceptionally with regard to stress placement.  Alternatively, markup or
+other methods can be used to create an underlining effect.
+
+To enter a plain underscore, type the underscore twice.
+
+All Haudenosaunee languages, including Tuscarora can be input
+simultaneously using the input method `haudenosaunee-postfix'."
+ nil t nil nil nil nil nil nil nil nil t)
+
+(pcase-dolist (`(,key ,trans)
+               (append iroquoian-tuscarora-modifier-alist
+                       iroquoian-tuscarora-consonant-alist
+                       iroquoian-tuscarora-vowel-alist
+                       iroquoian-tuscarora-exception-alist))
+  (quail-defrule key trans))
+
+
 ;;; Haudenosaunee (composite Northern Iroquoian)
 
 ;;
@@ -857,7 +1010,8 @@ simultaneously using the input method `haudenosaunee-postfix'."
                     iroquoian-oneida-modifier-alist
                     iroquoian-onondaga-modifier-alist
                     iroquoian-cayuga-modifier-alist
-                    iroquoian-seneca-modifier-alist))
+                    iroquoian-seneca-modifier-alist
+                    iroquoian-tuscarora-modifier-alist))
   "Alist of rules for modifier letters in Haudenosaunee input methods.
 Entries are as with rules in `quail-define-rules'.")
 
@@ -866,7 +1020,8 @@ Entries are as with rules in `quail-define-rules'.")
                     iroquoian-oneida-vowel-alist
                     iroquoian-onondaga-vowel-alist
                     iroquoian-cayuga-vowel-alist
-                    iroquoian-seneca-vowel-alist))
+                    iroquoian-seneca-vowel-alist
+                    iroquoian-tuscarora-vowel-alist))
   "Alist of rules for vowel letters in Haudenosaunee input methods.
 Entries are as with rules in `quail-define-rules'.")
 
@@ -879,16 +1034,17 @@ Entries are as with rules in `quail-define-rules'.")
              iroquoian-oneida-consonant-alist
              iroquoian-onondaga-consonant-alist
              iroquoian-cayuga-consonant-alist
-             iroquoian-seneca-consonant-alist)
+             iroquoian-seneca-consonant-alist
+             iroquoian-tuscarora-consonant-alist)
             (lambda (c1 c2)
               (equal (car c1) (car c2))))
   "Alist of rules for consonant letters in Haudenosaunee input methods.
 Entries are as with rules in `quail-define-rules'.")
 
-(defconst iroquoian-haudenosaunee-devoicing-alist
+(defconst iroquoian-haudenosaunee-exception-alist
   '(("_" ?\N{COMBINING LOW LINE})
     ("__" ?_))
-  "Alist of rules for devoicing characters in Haudenosaunee input methods.
+  "Rules alist for phonological exception markers in Haudenosaunee input methods.
 Entries are as with rules in `quail-define-rules'.")
 
 (defconst iroquoian-haudenosaunee-nasal-alist iroquoian-onondaga-nasal-alist
@@ -906,6 +1062,7 @@ This input method can be used to enter the following languages:
 - Cayuga (Gayogo̱ho:nǫhnéha:ˀ)
 - Onondaga (Onųdaʔgegáʔ)
 - Seneca (Onödowá’ga:’)
+- Tuscarora (Skarù·ręʔ)
 
 Modifiers:
 
@@ -989,6 +1146,12 @@ Vowels:
 | a\"   | ä           | Low front vowel                                 |
 | A\"   | Ä           | Low front vowel (capital)                       |
 | Single-key vowels: a e i o u                                         |
+|----------------------------------------------------------------------|
+| Tuscarora                                                            |
+| -------------------------------------------------------------------- |
+| e,   | ę           | Mid front nasal vowel                           |
+| E,   | Ę           | Mid front nasal vowel (capital)                 |
+| Single-key vowels: a e i u                                           |
 
 Consonants:
 
@@ -1023,8 +1186,16 @@ Consonants:
 | s/    | š           | Voiceless postalveolar fricative               |
 | S/    | Š           | Voiceless postalveolar fricative (capital)     |
 | Single-key consonants: d g h j k n s t w y z (b m p)                 |
+|----------------------------------------------------------------------|
+| Tuscarora                                                            |
+| -------------------------------------------------------------------- |
+| ;:    | ʔ           | Glottal stop (alternate)                       |
+| c/    | č            | Postalveolar affricate                        |
+| C/    | Č            | Postalveolar affricate (capital)              |
+| t/    | θ            | Voiceless dental fricative                    |
+| Single-key consonants: h k n r s t w y (b l m p)                     |
 
-Devoicing:
+Phonological exception markers:
 
 | Key | Description            | Examples                     |
 |-----+------------------------+------------------------------|
@@ -1035,8 +1206,10 @@ Note: Not all fonts can properly display a combining low line on all
 letters and a combining macron below on all vowels.
 
 Underlining is commonly used in Oneida to indicate devoiced syllables on
-pre-pausal forms (also called utterance-final forms).  Alternatively,
-markup or other methods can be used to create an underlining effect.
+pre-pausal forms (also called utterance-final forms), and it has been
+used in some Tuscarora orthographies to indicate that vowels behave
+exceptionally with regard to stress placement. Alternatively, markup or
+other methods can be used to create an underlining effect.
 
 To enter a plain underscore, the underscore twice.
 
@@ -1046,7 +1219,8 @@ To enter a plain hyphen after a vowel, simply type the hyphen twice.
 
 There are individual input methods for each of the languages that can be
 entered with this input method: `mohawk-postfix', `oneida-postfix',
-`onondaga-postfix', `cayuga-postfix', `seneca-postfix'."
+`onondaga-postfix', `cayuga-postfix', `seneca-postfix',
+`tuscarora-postfix'.."
  nil t nil nil nil nil nil nil nil nil t)
 
 (pcase-dolist (`(,key ,trans)
@@ -1054,7 +1228,7 @@ entered with this input method: `mohawk-postfix', `oneida-postfix',
                        iroquoian-haudenosaunee-consonant-alist
                        iroquoian-haudenosaunee-nasal-alist
                        iroquoian-haudenosaunee-vowel-alist
-                       iroquoian-haudenosaunee-devoicing-alist))
+                       iroquoian-haudenosaunee-exception-alist))
   (quail-defrule key trans))
 
 (provide 'iroquoian)
diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 1c8f329fdd7..465de028725 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -319,6 +319,10 @@ If the parameter `:authorizable' is given and the following AUTH
 is non-nil, the invoked method may interactively prompt the user
 for authorization.  The default is nil.
 
+If the parameter `:keep-fd' is given, and the return message has a first
+argument with a D-Bus type `:unix-fd', the returned file desriptor is
+kept internally, and can be used in a later `dbus--close-fd' call.
+
 All other arguments ARGS are passed to METHOD as arguments.  They are
 converted into D-Bus types via the following rules:
 
@@ -453,6 +457,10 @@ If the parameter `:authorizable' is given and the following AUTH
 is non-nil, the invoked method may interactively prompt the user
 for authorization.  The default is nil.
 
+If the parameter `:keep-fd' is given, and the return message has a first
+argument with a D-Bus type `:unix-fd', the returned file desriptor is
+kept internally, and can be used in a later `dbus--close-fd' call.
+
 All other arguments ARGS are passed to METHOD as arguments.  They are
 converted into D-Bus types via the following rules:
 
@@ -604,6 +612,7 @@ This is an internal function, it shall not be used outside dbus.el."
 
 ;;; Hash table of registered functions.
 
+;; Seems to be unused.  Dow we want to keep it?
 (defun dbus-list-hash-table ()
   "Return all registered member registrations to D-Bus.
 The return value is a list, with elements of kind (KEY . VALUE).
@@ -613,7 +622,7 @@ hash table."
     (maphash
      (lambda (key value) (push (cons key value) result))
      dbus-registered-objects-table)
-    result))
+    (nreverse result)))
 
 (defun dbus-setenv (bus variable value)
   "Set the value of the BUS environment variable named VARIABLE to VALUE.
@@ -2098,6 +2107,7 @@ either a method name, a signal name, or an error name."
 
 (defun dbus-monitor-goto-serial ()
   "Goto D-Bus message with the same serial number."
+  (declare (completion ignore))
   (interactive)
   (when (mouse-event-p last-input-event) (mouse-set-point last-input-event))
   (when-let* ((point (get-text-property (point) 'dbus-serial)))
diff --git a/lisp/net/newst-backend.el b/lisp/net/newst-backend.el
index babd55fb29d..58bbb1b7fcb 100644
--- a/lisp/net/newst-backend.el
+++ b/lisp/net/newst-backend.el
@@ -1109,12 +1109,13 @@ same as in `newsticker--parse-atom-1.0'."
 
 (defun newsticker--parse-text-container (node)
   "Handle content according to ``type'' attribute."
-  (let ((content (car (xml-node-children node))))
-    (if (string= "html" (xml-get-attribute node 'type))
-        ;; element contains entity escaped html
-        content
-      ;; plain text or xhtml
-      (newsticker--unxml content))))
+  (let ((content (car (xml-node-children node)))
+        (type (xml-get-attribute node 'type)))
+    (if (string= "xhtml" type)
+        ;; xhtml: reverse-parse xml nodes back to string
+        (newsticker--unxml content)
+      ;; plain text (default) or entity-escaped html: return as-is
+      content)))
 
 (defun newsticker--unxml (node)
   "Reverse parsing of an xml string.
diff --git a/lisp/net/shr.el b/lisp/net/shr.el
index bf78cce13bf..517cb3cc237 100644
--- a/lisp/net/shr.el
+++ b/lisp/net/shr.el
@@ -2731,7 +2731,7 @@ flags that control whether to collect or render objects."
                         (aref widths width-column)
                       (* 10 shr-table-separator-pixel-width)))
               (when (setq colspan (dom-attr column 'colspan))
-                (setq colspan (min (string-to-number colspan)
+                (setq colspan (min (truncate (string-to-number colspan))
                                    ;; The colspan may be wrong, so
                                    ;; truncate it to the length of the
                                    ;; remaining columns.
diff --git a/lisp/net/tramp-adb.el b/lisp/net/tramp-adb.el
index 5bcb92536fd..c20b5df9b59 100644
--- a/lisp/net/tramp-adb.el
+++ b/lisp/net/tramp-adb.el
@@ -974,7 +974,7 @@ E.g. a host name \"192.168.1.1#5555\" returns \"192.168.1.1:5555\"
               (sleep-for 0.1)
               host)
              (t (tramp-error
-                 vec 'file-error "Could not find device %s" host)))))))
+                 vec 'remote-file-error "Could not find device %s" host)))))))
 
 (defun tramp-adb-execute-adb-command (vec &rest args)
   "Execute an adb command.
@@ -1047,7 +1047,7 @@ the exit status."
   (with-current-buffer (tramp-get-connection-buffer vec)
     (unless (tramp-search-regexp (rx "tramp_exit_status " (+ digit)))
       (tramp-error
-       vec 'file-error "Couldn't find exit status of `%s'" command))
+       vec 'remote-file-error "Couldn't find exit status of `%s'" command))
     (skip-chars-forward "^ ")
     (prog1
         (if exit-status
@@ -1060,13 +1060,14 @@ the exit status."
   "Run COMMAND, check exit status, throw error if exit status not okay.
 FMT and ARGS are passed to `error'."
   (unless (tramp-adb-send-command-and-check vec command)
-    (apply #'tramp-error vec 'file-error fmt args)))
+    (apply #'tramp-error vec 'remote-file-error fmt args)))
 
 (defun tramp-adb-wait-for-output (proc &optional timeout)
   "Wait for output from remote command."
   (unless (buffer-live-p (process-buffer proc))
     (delete-process proc)
-    (tramp-error proc 'file-error "Process `%s' not available, try again" proc))
+    (tramp-error
+     proc 'remote-file-error "Process `%s' not available, try again" proc))
   (let ((prompt (tramp-get-connection-property proc "prompt" tramp-adb-prompt)))
     (with-current-buffer (process-buffer proc)
       (if (tramp-wait-for-regexp proc timeout prompt)
@@ -1085,10 +1086,11 @@ FMT and ARGS are passed to `error'."
               (delete-region (point) (point-max))))
         (if timeout
             (tramp-error
-             proc 'file-error
+             proc 'remote-file-error
              "[[Remote prompt `%s' not found in %d secs]]" prompt timeout)
           (tramp-error
-           proc 'file-error "[[Remote prompt `%s' not found]]" prompt))))))
+           proc 'remote-file-error
+           "[[Remote prompt `%s' not found]]" prompt))))))
 
 (defun tramp-adb-maybe-open-connection (vec)
   "Maybe open a connection VEC.
@@ -1110,13 +1112,14 @@ connection if a previous connection has died for some reason."
       ;; whether it is still the same device.
       (when
           (and user (not (tramp-get-connection-property vec " su-command-p" t)))
-        (tramp-error vec 'file-error "Cannot switch to user `%s'" user))
+        (tramp-error vec 'remote-file-error "Cannot switch to user `%s'" user))
 
       (unless (process-live-p p)
         (save-match-data
           (when (and p (processp p)) (delete-process p))
           (if (tramp-string-empty-or-nil-p device)
-              (tramp-error vec 'file-error "Device %s not connected" host))
+              (tramp-error
+               vec 'remote-file-error "Device %s not connected" host))
           (with-tramp-progress-reporter vec 3 "Opening adb shell connection"
             (let* ((coding-system-for-read 'utf-8-dos) ; Is this correct?
                    (process-connection-type tramp-process-connection-type)
@@ -1137,7 +1140,7 @@ connection if a previous connection has died for some reason."
               (tramp-send-string vec tramp-rsh-end-of-line)
               (tramp-adb-wait-for-output p 30)
               (unless (process-live-p p)
-                (tramp-error vec 'file-error "Terminated!"))
+                (tramp-error vec 'remote-file-error "Terminated!"))
 
               ;; Set connection-local variables.
               (tramp-set-connection-local-variables vec)
@@ -1193,7 +1196,7 @@ connection if a previous connection has died for some reason."
                   ;; Do not flush, we need the nil value.
                   (tramp-set-connection-property vec " su-command-p" nil)
                   (tramp-error
-                   vec 'file-error "Cannot switch to user `%s'" user)))
+                   vec 'remote-file-error "Cannot switch to user `%s'" user)))
 
               ;; Mark it as connected.
               (tramp-set-connection-property p "connected" t))))))))
diff --git a/lisp/net/tramp-archive.el b/lisp/net/tramp-archive.el
index a4323156c2a..e970fd1cd56 100644
--- a/lisp/net/tramp-archive.el
+++ b/lisp/net/tramp-archive.el
@@ -737,7 +737,7 @@ offered."
               (apply #'tramp-archive-file-name-for-operation operation args)))))
     (tramp-message v 10 "%s" (cons operation args))
     (tramp-error
-     v 'file-error
+     v 'remote-file-error
      "Operation `%s' not implemented for file archives" operation)))
 
 (add-hook 'tramp-unload-hook
diff --git a/lisp/net/tramp-crypt.el b/lisp/net/tramp-crypt.el
index 565b9f0a5aa..59e4cea2edb 100644
--- a/lisp/net/tramp-crypt.el
+++ b/lisp/net/tramp-crypt.el
@@ -446,7 +446,7 @@ Otherwise, return NAME."
                      crypt-vec (if (eq op 'encrypt) "encode" "decode")
                      tramp-compat-temporary-file-directory localname)
               (tramp-error
-               crypt-vec 'file-error "%s of file name %s failed"
+               crypt-vec 'remote-file-error "%s of file name %s failed"
                (if (eq op 'encrypt) "Encoding" "Decoding") name))
             (with-current-buffer (tramp-get-connection-buffer crypt-vec)
               (goto-char (point-min))
@@ -481,7 +481,7 @@ Raise an error if this fails."
                (file-name-directory infile)
                (concat "/" (file-name-nondirectory infile)))
         (tramp-error
-         crypt-vec 'file-error "%s of file %s failed"
+         crypt-vec 'remote-file-error "%s of file %s failed"
          (if (eq op 'encrypt) "Encrypting" "Decrypting") infile))
       (with-current-buffer (tramp-get-connection-buffer crypt-vec)
         (write-region nil nil outfile)))))
diff --git a/lisp/net/tramp-gvfs.el b/lisp/net/tramp-gvfs.el
index 64efce227d6..0f68e4d768a 100644
--- a/lisp/net/tramp-gvfs.el
+++ b/lisp/net/tramp-gvfs.el
@@ -1006,7 +1006,7 @@ The global value will always be nil; it is bound where needed.")
   "Called when a D-Bus error message arrives, see `dbus-event-error-functions'."
   (when tramp-gvfs-dbus-event-vector
     (tramp-message tramp-gvfs-dbus-event-vector 6 "%S" event)
-    (tramp-error tramp-gvfs-dbus-event-vector 'file-error (cadr err))))
+    (tramp-error tramp-gvfs-dbus-event-vector 'remote-file-error (cadr err))))
 
 (add-hook 'dbus-event-error-functions #'tramp-gvfs-dbus-event-error)
 (add-hook 'tramp-gvfs-unload-hook
@@ -2234,7 +2234,7 @@ connection if a previous connection has died for some reason."
                    method)
                tramp-gvfs-mounttypes)
         (tramp-error
-         vec 'file-error "Method `%s' not supported by GVFS" method)))
+         vec 'remote-file-error "Method `%s' not supported by GVFS" method)))
 
     ;; For password handling, we need a process bound to the
     ;; connection buffer.  Therefore, we create a dummy process.
@@ -2332,10 +2332,10 @@ connection if a previous connection has died for some reason."
                 vec 'tramp-connection-timeout tramp-connection-timeout)
                (if (tramp-string-empty-or-nil-p user-domain)
                    (tramp-error
-                    vec 'file-error
+                    vec 'remote-file-error
                     "Timeout reached mounting %s using %s" host-port method)
                  (tramp-error
-                  vec 'file-error
+                  vec 'remote-file-error
                   "Timeout reached mounting %s@%s using %s"
                   user-domain host-port method)))
             (while (not (tramp-get-file-property vec "/" "fuse-mountpoint"))
@@ -2345,7 +2345,7 @@ connection if a previous connection has died for some reason."
           ;; is marked with the fuse-mountpoint "/".  We shall react.
           (when (string-equal
                  (tramp-get-file-property vec "/" "fuse-mountpoint" "") "/")
-            (tramp-error vec 'file-error "FUSE mount denied"))
+            (tramp-error vec 'remote-file-error "FUSE mount denied"))
 
           ;; Save the password.
           (ignore-errors
diff --git a/lisp/net/tramp-rclone.el b/lisp/net/tramp-rclone.el
index 6b0daeba2ac..cd5c3f46f54 100644
--- a/lisp/net/tramp-rclone.el
+++ b/lisp/net/tramp-rclone.el
@@ -381,53 +381,53 @@ connection if a previous connection has died for some reason."
 
   (with-tramp-debug-message vec "Opening connection"
     (let ((host (tramp-file-name-host vec)))
-      (when (rassoc `(,host) (tramp-rclone-parse-device-names nil))
-        (if (tramp-string-empty-or-nil-p host)
-            (tramp-error vec 'file-error "Storage %s not connected" host))
-        ;; We need a process bound to the connection buffer.
-        ;; Therefore, we create a dummy process.  Maybe there is a
-        ;; better solution?
-        (unless (get-buffer-process (tramp-get-connection-buffer vec))
-          (let ((p (make-network-process
-                    :name (tramp-get-connection-name vec)
-                    :buffer (tramp-get-connection-buffer vec)
-                    :server t :host 'local :service t :noquery t)))
-            (tramp-post-process-creation p vec)
-
-            ;; Set connection-local variables.
-            (tramp-set-connection-local-variables vec)))
-
-        ;; Create directory.
-        (unless (file-directory-p (tramp-fuse-mount-point vec))
-          (make-directory (tramp-fuse-mount-point vec) 'parents))
-
-        ;; Mount.  This command does not return, so we use 0 as
-        ;; DESTINATION of `tramp-call-process'.
-        (unless (tramp-fuse-mounted-p vec)
-          (apply
-           #'tramp-call-process
-           vec tramp-rclone-program nil 0 nil
-           "mount" (tramp-fuse-mount-spec vec)
-           (tramp-fuse-mount-point vec)
-           (tramp-get-method-parameter vec 'tramp-mount-args))
-          (while (not (file-exists-p (tramp-make-tramp-file-name vec 'noloc)))
-            (tramp-cleanup-connection vec 'keep-debug 'keep-password))
-          (add-to-list 'tramp-fuse-mount-points (tramp-file-name-unify vec)))
-
-        ;; Mark it as connected.
-        (tramp-set-connection-property
-         (tramp-get-connection-process vec) "connected" t)))
-
-    ;; In `tramp-check-cached-permissions', the connection properties
-    ;; "{uid,gid}-{integer,string}" are used.  We set them to proper values.
-    (with-tramp-connection-property
-        vec "uid-integer" (tramp-get-local-uid 'integer))
-    (with-tramp-connection-property
-        vec "gid-integer" (tramp-get-local-gid 'integer))
-    (with-tramp-connection-property
-        vec "uid-string" (tramp-get-local-uid 'string))
-    (with-tramp-connection-property
-        vec "gid-string" (tramp-get-local-gid 'string))))
+      (when (or (tramp-string-empty-or-nil-p host)
+                (not (rassoc `(,host) (tramp-rclone-parse-device-names nil))))
+        (tramp-error vec 'remote-file-error "Storage %s not connected" host))
+
+      ;; We need a process bound to the connection buffer.  Therefore,
+      ;; we create a dummy process.  Maybe there is a better solution?
+      (unless (get-buffer-process (tramp-get-connection-buffer vec))
+        (let ((p (make-network-process
+                  :name (tramp-get-connection-name vec)
+                  :buffer (tramp-get-connection-buffer vec)
+                  :server t :host 'local :service t :noquery t)))
+          (tramp-post-process-creation p vec)
+
+          ;; Set connection-local variables.
+          (tramp-set-connection-local-variables vec)))
+
+      ;; Create directory.
+      (unless (file-directory-p (tramp-fuse-mount-point vec))
+        (make-directory (tramp-fuse-mount-point vec) 'parents))
+
+      ;; Mount.  This command does not return, so we use 0 as
+      ;; DESTINATION of `tramp-call-process'.
+      (unless (tramp-fuse-mounted-p vec)
+        (apply
+         #'tramp-call-process
+         vec tramp-rclone-program nil 0 nil
+         "mount" (tramp-fuse-mount-spec vec)
+         (tramp-fuse-mount-point vec)
+         (tramp-get-method-parameter vec 'tramp-mount-args))
+        (while (not (file-exists-p (tramp-make-tramp-file-name vec 'noloc)))
+          (tramp-cleanup-connection vec 'keep-debug 'keep-password))
+        (add-to-list 'tramp-fuse-mount-points (tramp-file-name-unify vec)))
+
+      ;; Mark it as connected.
+      (tramp-set-connection-property
+       (tramp-get-connection-process vec) "connected" t)))
+
+  ;; In `tramp-check-cached-permissions', the connection properties
+  ;; "{uid,gid}-{integer,string}" are used.  We set them to proper values.
+  (with-tramp-connection-property
+      vec "uid-integer" (tramp-get-local-uid 'integer))
+  (with-tramp-connection-property
+      vec "gid-integer" (tramp-get-local-gid 'integer))
+  (with-tramp-connection-property
+      vec "uid-string" (tramp-get-local-uid 'string))
+  (with-tramp-connection-property
+      vec "gid-string" (tramp-get-local-gid 'string)))
 
 (defun tramp-rclone-send-command (vec &rest args)
   "Send a command to connection VEC.
diff --git a/lisp/net/tramp-sh.el b/lisp/net/tramp-sh.el
index 97b72ba00ad..13e886b2c13 100644
--- a/lisp/net/tramp-sh.el
+++ b/lisp/net/tramp-sh.el
@@ -1969,7 +1969,7 @@ ID-FORMAT valid values are `string' and `integer'."
          (tramp-send-command-and-read
           vec (format "tramp_perl_directory_files_and_attributes %s"
                       (tramp-shell-quote-argument localname)))))
-    (when (stringp object) (tramp-error vec 'file-error object))
+    (when (stringp object) (tramp-error vec 'remote-file-error object))
     object))
 
 ;; FIXME: Fix function to work with count parameter.
@@ -2378,7 +2378,7 @@ the uid and gid from FILENAME."
                         ((eq op 'copy) "cp -f")
                         ((eq op 'rename) "mv -f")
                         (t (tramp-error
-                            v 'file-error
+                            v 'remote-file-error
                             "Unknown operation `%s', must be `copy' or `rename'"
                             op))))
              (localname1 (tramp-file-local-name filename))
@@ -2608,7 +2608,7 @@ The method used must be an out-of-band method."
       ;; Check for local copy program.
       (unless (executable-find copy-program)
         (tramp-error
-         v 'file-error "Cannot find local copy program: %s" copy-program))
+         v 'remote-file-error "Cannot find local copy program: %s" copy-program))
 
       ;; Install listener on the remote side.  The prompt must be
       ;; consumed later on, when the process does not listen anymore.
@@ -2618,7 +2618,7 @@ The method used must be an out-of-band method."
                   (tramp-find-executable
                    v remote-copy-program (tramp-get-remote-path v)))
           (tramp-error
-           v 'file-error
+           v 'remote-file-error
            "Cannot find remote listener: %s" remote-copy-program))
         (setq remote-copy-program
               (string-join
@@ -2629,7 +2629,7 @@ The method used must be an out-of-band method."
         (tramp-send-command v remote-copy-program)
         (with-timeout
             (60 (tramp-error
-                 v 'file-error
+                 v 'remote-file-error
                  "Listener process not running on remote host: `%s'"
                  remote-copy-program))
           (tramp-send-command v (format "netstat -l | grep -q :%s" listener))
@@ -3468,7 +3468,8 @@ will be used."
 
                ;; Oops, I don't know what to do.
                (t (tramp-error
-                   v 'file-error "Wrong method specification for `%s'" method)))
+                   v 'remote-file-error
+                   "Wrong method specification for `%s'" method)))
 
             ;; Error handling.
             ((error quit)
@@ -3663,7 +3664,7 @@ will be used."
              ;; That's not expected.
              (t
               (tramp-error
-               v 'file-error
+               v 'remote-file-error
                (concat "Method `%s' should specify both encoding and "
                        "decoding command or an scp program")
                method)))))))))
@@ -3689,7 +3690,7 @@ are \"file-exists-p\", \"file-readable-p\", \"file-directory-p\" and
                      tramp-end-of-heredoc
                      (mapconcat #'tramp-shell-quote-argument files "\n")
                      tramp-end-of-heredoc))
-             (tramp-error vec 'file-error "%s" (tramp-get-buffer-string)))
+             (tramp-error vec 'remote-file-error "%s" (tramp-get-buffer-string)))
            ;; Read the expression.
            (goto-char (point-min))
            (read (current-buffer))))
@@ -4165,7 +4166,7 @@ Only send the definition if it has not already been done."
         ;; Expand format specifiers.
         (unless (setq script (tramp-expand-script vec script))
           (tramp-error
-           vec 'file-error
+           vec 'remote-file-error
            (format "Script %s is not applicable on remote host" name)))
         ;; Send it.
         (tramp-barf-unless-okay
@@ -4325,13 +4326,15 @@ file exists and nonzero exit status otherwise."
              ;; We cannot use `tramp-get-ls-command', this results in an infloop.
              ;; (Bug#65321)
              (ignore-errors
-               (and (setq result (format "ls -d >%s" (tramp-get-remote-null-device vec)))
+               (and (setq
+                     result
+                     (format "ls -d >%s" (tramp-get-remote-null-device vec)))
                     (tramp-send-command-and-check
                      vec (format "%s %s" result existing))
                     (not (tramp-send-command-and-check
                           vec (format "%s %s" result nonexistent))))))
       (tramp-error
-       vec 'file-error "Couldn't find command to check if file exists"))
+       vec 'remote-file-error "Couldn't find command to check if file exists"))
     (tramp-set-file-property vec existing "file-exists-p" t)
     result))
 
@@ -4484,7 +4487,8 @@ seconds.  If not, it produces an error message with the given ERROR-ARGS."
       (error
        (delete-process proc)
        (apply #'tramp-error-with-buffer
-              (tramp-get-connection-buffer vec) vec 'file-error error-args)))))
+              (tramp-get-connection-buffer vec) vec
+              'remote-file-error error-args)))))
 
 (defvar tramp-config-check nil
   "A function to be called with one argument, VEC.
@@ -5293,8 +5297,8 @@ connection if a previous connection has died for some reason."
             (unless (and (process-live-p p)
                          (tramp-wait-for-output p 10))
               ;; The error will be caught locally.
-              (tramp-error vec 'file-error "Awake did fail")))
-        (file-error
+              (tramp-error vec 'remote-file-error "Awake did fail")))
+        (remote-file-error
          (tramp-cleanup-connection vec t)
          (setq p nil)))
 
@@ -5314,7 +5318,8 @@ connection if a previous connection has died for some reason."
                       (setenv "HISTFILESIZE" "0")
                       (setenv "HISTSIZE" "0"))))
               (unless (stringp tramp-encoding-shell)
-                (tramp-error vec 'file-error "`tramp-encoding-shell' not set"))
+                (tramp-error
+                 vec 'remote-file-error "`tramp-encoding-shell' not set"))
               (let* ((current-host tramp-system-name)
                      (target-alist (tramp-compute-multi-hops vec))
                      (previous-hop tramp-null-hop)
@@ -5520,7 +5525,8 @@ function waits for output unless NOOUTPUT is set."
   "Wait for output from remote command."
   (unless (buffer-live-p (process-buffer proc))
     (delete-process proc)
-    (tramp-error proc 'file-error "Process `%s' not available, try again" proc))
+    (tramp-error
+     proc 'remote-file-error "Process `%s' not available, try again" proc))
   (with-current-buffer (process-buffer proc)
     (let* (;; Initially, `tramp-end-of-output' is "#$ ".  There might
            ;; be leading ANSI control escape sequences, which must be
@@ -5551,11 +5557,11 @@ function waits for output unless NOOUTPUT is set."
               (delete-region (point) (point-max))))
         (if timeout
             (tramp-error
-             proc 'file-error
+             proc 'remote-file-error
              "[[Remote prompt `%s' not found in %d secs]]"
              tramp-end-of-output timeout)
           (tramp-error
-           proc 'file-error
+           proc 'remote-file-error
            "[[Remote prompt `%s' not found]]" tramp-end-of-output)))
       ;; Return value is whether end-of-output sentinel was found.
       found)))
@@ -5594,7 +5600,7 @@ the exit status."
   (with-current-buffer (tramp-get-connection-buffer vec)
     (unless (tramp-search-regexp (rx "tramp_exit_status " (+ digit)))
       (tramp-error
-       vec 'file-error "Couldn't find exit status of `%s'" command))
+       vec 'remote-file-error "Couldn't find exit status of `%s'" command))
     (skip-chars-forward "^ ")
     (prog1
         (if exit-status
@@ -5608,7 +5614,7 @@ the exit status."
 Similar to `tramp-send-command-and-check' but accepts two more arguments
 FMT and ARGS which are passed to `error'."
   (or (tramp-send-command-and-check vec command)
-      (apply #'tramp-error vec 'file-error fmt args)))
+      (apply #'tramp-error vec 'remote-file-error fmt args)))
 
 (defun tramp-send-command-and-read (vec command &optional noerror marker)
   "Run COMMAND and return the output, which must be a Lisp expression.
@@ -5627,7 +5633,7 @@ raises an error."
             (search-forward-regexp marker)
           (error (unless noerror
                    (tramp-error
-                    vec 'file-error
+                    vec 'remote-file-error
                     "`%s' does not return the marker `%s': `%s'"
                     command marker (buffer-string))))))
       ;; Read the expression.
@@ -5641,7 +5647,7 @@ raises an error."
               (error nil)))
         (error (unless noerror
                  (tramp-error
-                  vec 'file-error
+                  vec 'remote-file-error
                   "`%s' does not return a valid Lisp expression: `%s'"
                   command (buffer-string))))))))
 
@@ -5854,7 +5860,8 @@ Nonexistent directories are removed from spec."
                  (setq result (concat result " --color=never")))
                (throw 'ls-found result))
              (setq dl (cdr dl))))))
-     (tramp-error vec 'file-error "Couldn't find a proper `ls' command"))))
+     (tramp-error
+      vec 'remote-file-error "Couldn't find a proper `ls' command"))))
 
 (defun tramp-get-ls-command-with (vec option)
   "Return OPTION, if the remote `ls' command supports the OPTION option."
diff --git a/lisp/net/tramp-smb.el b/lisp/net/tramp-smb.el
index b87eee0fcce..554aa354c00 100644
--- a/lisp/net/tramp-smb.el
+++ b/lisp/net/tramp-smb.el
@@ -821,7 +821,7 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
   (setq filename (directory-file-name (expand-file-name filename)))
   (with-parsed-tramp-file-name filename nil
     (tramp-convert-file-attributes v localname id-format
-      (ignore-errors
+      (condition-case err
         (if (tramp-smb-get-stat-capability v)
             (tramp-smb-do-file-attributes-with-stat v)
           ;; Reading just the filename entry via "dir localname" is
@@ -851,7 +851,9 @@ PRESERVE-UID-GID and PRESERVE-EXTENDED-ATTRIBUTES are completely ignored."
                     (nth 1 entry)        ;8 mode
                     nil                  ;9 gid weird
                     inode                ;10 inode number
-                    device))))))))       ;11 file system number
+                    device))))           ;11 file system number
+        (remote-file-error (signal (car err) (cdr err)))
+        (error)))))
 
 (defun tramp-smb-do-file-attributes-with-stat (vec)
   "Implement `file-attributes' for Tramp files using `stat' command."
@@ -1382,7 +1384,7 @@ will be used."
   "Like `make-symbolic-link' for Tramp files."
   (let ((v (tramp-dissect-file-name (expand-file-name linkname))))
     (unless (tramp-smb-get-cifs-capabilities v)
-      (tramp-error v 'file-error "make-symbolic-link not supported")))
+      (tramp-error v 'remote-file-error "make-symbolic-link not supported")))
 
   (tramp-skeleton-make-symbolic-link target linkname ok-if-already-exists
     (unless (tramp-smb-send-command
@@ -1571,8 +1573,7 @@ will be used."
                     (tramp-search-regexp (rx "tramp_exit_status " (+ digit)))
                   (tramp-error
                    v 'file-error
-                   "Couldn't find exit status of `%s'"
-                   tramp-smb-acl-program))
+                   "Couldn't find exit status of `%s'" tramp-smb-acl-program))
                 (skip-chars-forward "^ ")
                 (when (zerop (read (current-buffer)))
                   ;; Success.
@@ -1705,7 +1706,7 @@ If VEC has no cifs capabilities, exchange \"/\" by \"\\\\\"."
       (when (string-match-p (rx blank eol) localname)
         (tramp-error
          vec 'file-error
-         "Invalid file name %s" (tramp-make-tramp-file-name vec localname)))
+         "Invalid file name `%s'" (tramp-make-tramp-file-name vec localname)))
 
       localname)))
 
@@ -1988,7 +1989,7 @@ If ARGUMENT is non-nil, use it as argument for
           (unless tramp-smb-version
             (unless (executable-find tramp-smb-program)
               (tramp-error
-               vec 'file-error
+               vec 'remote-file-error
                "Cannot find command %s in %s" tramp-smb-program exec-path))
             (setq tramp-smb-version (shell-command-to-string command))
             (tramp-message vec 6 command)
@@ -2165,11 +2166,12 @@ Removes smb prompt.  Returns nil if an error message has appeared."
   ;; Check for program.
   (unless (executable-find tramp-smb-winexe-program)
     (tramp-error
-     vec 'file-error "Cannot find program: %s" tramp-smb-winexe-program))
+     vec 'remote-file-error "Cannot find program: %s" tramp-smb-winexe-program))
 
   ;; winexe does not supports ports.
   (when (tramp-file-name-port vec)
-    (tramp-error vec 'file-error "Port not supported for remote processes"))
+    (tramp-error
+     vec 'remote-file-error "Port not supported for remote processes"))
 
   ;; Check share.
   (unless (tramp-smb-get-share vec)
diff --git a/lisp/net/tramp-sshfs.el b/lisp/net/tramp-sshfs.el
index 338d128cc4e..2cb5b5b1ed1 100644
--- a/lisp/net/tramp-sshfs.el
+++ b/lisp/net/tramp-sshfs.el
@@ -359,7 +359,7 @@ connection if a previous connection has died for some reason."
                  vec 'tramp-mount-args nil
                  ?p (or (tramp-file-name-port vec) ""))))))
       (tramp-error
-       vec 'file-error "Error mounting %s" (tramp-fuse-mount-spec vec)))
+       vec 'remote-file-error "Error mounting %s" (tramp-fuse-mount-spec vec)))
 
     ;; Mark it as connected.
     (add-to-list 'tramp-fuse-mount-points (tramp-file-name-unify vec))
diff --git a/lisp/net/tramp-sudoedit.el b/lisp/net/tramp-sudoedit.el
index d3bb8b8478e..9511c899b2b 100644
--- a/lisp/net/tramp-sudoedit.el
+++ b/lisp/net/tramp-sudoedit.el
@@ -52,6 +52,10 @@
               `(,(rx bos (literal tramp-sudoedit-method) eos)
                 nil ,tramp-root-id-string))
 
+ (add-to-list 'tramp-default-host-alist
+              `(,(rx bos (literal tramp-sudoedit-method) eos)
+                nil ,(system-name)))
+
  (tramp-set-completion-function
   tramp-sudoedit-method tramp-completion-function-alist-su))
 
@@ -742,6 +746,10 @@ connection if a previous connection has died for some reason."
   (unless (tramp-connectable-p vec)
     (throw 'non-essential 'non-essential))
 
+  (unless (string-match-p tramp-local-host-regexp (tramp-file-name-host vec))
+    (tramp-error
+     vec 'remote-file-error "%s is not a local host" (tramp-file-name-host vec)))
+
   (with-tramp-debug-message vec "Opening connection"
     ;; We need a process bound to the connection buffer.  Therefore,
     ;; we create a dummy process.  Maybe there is a better solution?
@@ -775,7 +783,6 @@ in case of error, t otherwise."
                (append
                 (tramp-expand-args
                  vec 'tramp-sudo-login nil
-                 ?h (or (tramp-file-name-host vec) "")
                  ?u (or (tramp-file-name-user vec) ""))
                 (flatten-tree args))))
            ;; We suppress the messages `Waiting for prompts from remote shell'.
@@ -817,7 +824,7 @@ In case there is no valid Lisp expression, it raises an error."
             (when (search-forward-regexp (rx (not blank)) (line-end-position) t)
               (error nil)))
         (error (tramp-error
-                vec 'file-error
+                vec 'remote-file-error
                 "`%s' does not return a valid Lisp expression: `%s'"
                 (car args) (buffer-string)))))))
 
diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el
index f57b572532a..5281d8e4db5 100644
--- a/lisp/net/tramp.el
+++ b/lisp/net/tramp.el
@@ -3931,7 +3931,7 @@ BODY is the backend specific code."
      ;; The implementation is not complete yet.
      (when (and (numberp ,destination) (zerop ,destination))
        (tramp-error
-        v 'file-error "Implementation does not handle immediate return"))
+        v 'remote-file-error "Implementation does not handle immediate return"))
 
      (let (command input tmpinput stderr tmpstderr outbuf ret)
        ;; Determine input.
@@ -5239,6 +5239,9 @@ Do not set it manually, it is used buffer-local in `tramp-get-lock-pid'.")
                     ?u (or (tramp-file-name-user (car target-alist)) "")
                     ?h (or (tramp-file-name-host (car target-alist)) ""))))
             (with-parsed-tramp-file-name proxy l
+              (when (member l target-alist)
+                (tramp-user-error
+                 vec "Cycle proxy definition `%s' in multi-hop" proxy))
               ;; Add the hop.
               (push l target-alist)
               ;; Start next search.
@@ -5505,7 +5508,7 @@ processes."
 This is the fallback implementation for backends which do not
 support symbolic links."
   (tramp-error
-   (tramp-dissect-file-name (expand-file-name linkname)) 'file-error
+   (tramp-dissect-file-name (expand-file-name linkname)) 'remote-file-error
    "make-symbolic-link not supported"))
 
 (defun tramp-handle-memory-info ()
@@ -6255,7 +6258,7 @@ performed successfully.  Any other value means an error."
           (tramp-clear-passwd vec)
           (delete-process proc)
           (tramp-error-with-buffer
-           (tramp-get-connection-buffer vec) vec 'file-error
+           (tramp-get-connection-buffer vec) vec 'remote-file-error
            (cond
             ((eq exit 'permission-denied) "Permission denied")
             ((eq exit 'out-of-band-failed)
@@ -6402,7 +6405,7 @@ nil."
         (tramp-accept-process-output proc)
         (unless (process-live-p proc)
           (tramp-error-with-buffer
-           nil proc 'file-error "Process has died"))
+           nil proc 'remote-file-error "Process has died"))
         (setq found (tramp-check-for-regexp proc regexp))))
     ;; The process could have timed out, for example due to session
     ;; timeout of sudo.  The process buffer does not exist any longer then.
@@ -6412,9 +6415,10 @@ nil."
     (unless found
       (if timeout
           (tramp-error
-           proc 'file-error "[[Regexp `%s' not found in %d secs]]"
+           proc 'remote-file-error "[[Regexp `%s' not found in %d secs]]"
            regexp timeout)
-        (tramp-error proc 'file-error "[[Regexp `%s' not found]]" regexp)))
+        (tramp-error
+         proc 'remote-file-error "[[Regexp `%s' not found]]" regexp)))
     found))
 
 ;; It seems that Tru64 Unix does not like it if long strings are sent
@@ -6431,7 +6435,8 @@ the remote host use line-endings as defined in the variable
          (chunksize (tramp-get-connection-property p "chunksize")))
     (unless p
       (tramp-error
-       vec 'file-error "Can't send string to remote host -- not logged in"))
+       vec 'remote-file-error
+       "Can't send string to remote host -- not logged in"))
     (tramp-set-connection-property p "last-cmd-time" (current-time))
     (tramp-message vec 10 "%s" string)
     (with-current-buffer (tramp-get-connection-buffer vec)
diff --git a/lisp/pixel-scroll.el b/lisp/pixel-scroll.el
index dbb532f691b..23e63add994 100644
--- a/lisp/pixel-scroll.el
+++ b/lisp/pixel-scroll.el
@@ -90,7 +90,6 @@
 (require 'mwheel)
 (require 'subr-x)
 (require 'ring)
-(require 'cua-base)
 
 (defvar pixel-wait 0
   "Idle time on each step of pixel scroll specified in second.
@@ -831,7 +830,13 @@ It is a vector of the form [ VELOCITY TIME SIGN ]."
                                           ;; since we want exactly 1
                                           ;; page to be scrolled.
                                           nil 1)
-    (cua-scroll-up)))
+    (cond
+     ((eobp)
+      (scroll-up))  ; signal error
+     (t
+      (condition-case nil
+          (scroll-up)
+        (end-of-buffer (goto-char (point-max))))))))
 
 ;;;###autoload
 (defun pixel-scroll-interpolate-up ()
@@ -840,7 +845,13 @@ It is a vector of the form [ VELOCITY TIME SIGN ]."
   (if pixel-scroll-precision-interpolate-page
       (pixel-scroll-precision-interpolate (window-text-height nil t)
                                           nil 1)
-    (cua-scroll-down)))
+    (cond
+     ((bobp)
+      (scroll-down))  ; signal error
+     (t
+      (condition-case nil
+          (scroll-down)
+        (beginning-of-buffer (goto-char (point-min))))))))
 
 ;;;###autoload
 (define-minor-mode pixel-scroll-precision-mode
diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index 80099a26ee8..4752b0100d9 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -282,7 +282,8 @@ automatically)."
      . ,(eglot-alternatives
          '(("solargraph" "socket" "--port" :autoport) "ruby-lsp")))
     (haskell-mode
-     . ("haskell-language-server-wrapper" "--lsp"))
+     . ,(eglot-alternatives
+         '(("haskell-language-server-wrapper" "--lsp") "static-ls")))
     (elm-mode . ("elm-language-server"))
     (mint-mode . ("mint" "ls"))
     ((kotlin-mode kotlin-ts-mode) . ("kotlin-language-server"))
@@ -308,7 +309,7 @@ automatically)."
     (racket-mode . ("racket" "-l" "racket-langserver"))
     ((latex-mode plain-tex-mode context-mode texinfo-mode bibtex-mode tex-mode)
      . ,(eglot-alternatives '("digestif" "texlab")))
-    (erlang-mode . ("erlang_ls" "--transport" "stdio"))
+    (erlang-mode . ("elp" "server"))
     (wat-mode . ("wat_server"))
     ((yaml-ts-mode yaml-mode) . ("yaml-language-server" "--stdio"))
     ((toml-ts-mode conf-toml-mode) . ("tombi" "lsp"))
@@ -1438,6 +1439,12 @@ PRESERVE-BUFFERS as in `eglot-shutdown', which see."
   (maphash (lambda (f s)
              (when (eq s server) (remhash f eglot--servers-by-xrefed-file)))
            eglot--servers-by-xrefed-file)
+  ;; Cleanup entries in 'flymake-list-only-diagnostics'
+  (setq flymake-list-only-diagnostics
+        (cl-delete-if
+         (lambda (x) (eq server
+                         (get-text-property 0 'eglot--server (car x))))
+         flymake-list-only-diagnostics))
   (cond ((eglot--shutdown-requested server)
          t)
         ((not (eglot--inhibit-autoreconnect server))
@@ -2024,21 +2031,25 @@ according to `eglot-advertise-cancellation'.")
                                 (timeout-fn nil timeout-fn-supplied-p)
                                 (timeout nil timeout-supplied-p)
                                 hint
-                                &aux moreargs
-                                id (buf (current-buffer)))
+                                &aux moreargs id
+                                (buf (current-buffer))
+                                (inflight eglot--inflight-async-requests))
   "Like `jsonrpc-async-request', but for Eglot LSP requests.
 SUCCESS-FN, ERROR-FN and TIMEOUT-FN run in buffer of call site.
 HINT argument is a symbol passed as DEFERRED to `jsonrpc-async-request'
 and also used as a hint of the request cancellation mechanism (see
 `eglot-advertise-cancellation')."
   (cl-labels
-      ((clearing-fn (fn)
+      ((wrapfn (fn)
          (lambda (&rest args)
            (eglot--when-live-buffer buf
-             (when (and
-                    fn (memq id (cl-getf eglot--inflight-async-requests hint)))
-               (apply fn args))
-             (cl-remf eglot--inflight-async-requests hint)))))
+             (cond (eglot-advertise-cancellation
+                    (when-let* ((tail (and fn (plist-member inflight hint))))
+                      (when (memq id (cadr tail))
+                        (apply fn args))
+                      (setf (cadr tail) (delete id (cadr tail)))))
+                   (t
+                    (apply fn args)))))))
     (eglot--cancel-inflight-async-requests (list hint))
     (when timeout-supplied-p
       (setq moreargs (nconc `(:timeout ,timeout) moreargs)))
@@ -2047,13 +2058,12 @@ and also used as a hint of the request cancellation mechanism (see
     (setq id
           (car (apply #'jsonrpc-async-request
                       server method params
-                      :success-fn (clearing-fn success-fn)
-                      :error-fn (clearing-fn error-fn)
-                      :timeout-fn (clearing-fn timeout-fn)
+                      :success-fn (wrapfn success-fn)
+                      :error-fn (wrapfn error-fn)
+                      :timeout-fn (wrapfn timeout-fn)
                       moreargs)))
     (when (and hint eglot-advertise-cancellation)
-      (push id
-            (plist-get eglot--inflight-async-requests hint)))
+      (push id (plist-get inflight hint)))
     id))
 
 (cl-defun eglot--delete-overlays (&optional (prop 'eglot--overlays))
@@ -3422,11 +3432,8 @@ object.  The originator of this \"push\" is usually either regular
       (with-current-buffer buffer
         (if (and version (/= version eglot--docver))
             (cl-return-from eglot--flymake-handle-push))
-        (setq
-         ;; if no explicit version received, assume it's current.
-         version eglot--docver
-         flymake-list-only-diagnostics
-         (assoc-delete-all path flymake-list-only-diagnostics))
+        ;; if no explicit version received, assume it's current.
+        (setq version eglot--docver)
         (funcall then diagnostics))
     (cl-loop
      for diag-spec across diagnostics
@@ -3437,12 +3444,13 @@ object.  The originator of this \"push\" is usually either regular
                  (flymake-make-diagnostic
                   path (cons line char) nil
                   (eglot--flymake-diag-type severity)
-                  (list source code message))))
+                  (list source code message)
+                  `((eglot-lsp-diag . ,diag-spec)))))
      into diags
      finally
-     (setq flymake-list-only-diagnostics
-           (assoc-delete-all path flymake-list-only-diagnostics))
-     (push (cons path diags) flymake-list-only-diagnostics))))
+     (setf (alist-get (propertize path 'eglot--server server)
+                      flymake-list-only-diagnostics nil nil #'equal)
+           diags))))
 
 (cl-defun eglot--flymake-pull (&aux (server (eglot--current-server-or-lose))
                                     (origin (current-buffer)))
@@ -3506,6 +3514,17 @@ MODE is like `eglot--flymake-report-1'."
      (pushed-outdated-p (and pushed-docver (< pushed-docver eglot--docver))))
   "Push previously collected diagnostics to `eglot--flymake-report-fn'.
 If KEEP, knowingly push a dummy do-nothing update."
+  ;; Maybe hack in diagnostics we previously may have saved in
+  ;; `flymake-list-only-diagnostics', pushed for this file before it was
+  ;; visited (github#1531).
+  (when-let* ((hack (and (<= eglot--docver 0)
+                         (null eglot--pushed-diagnostics)
+                         (cdr (assoc (buffer-file-name)
+                                     flymake-list-only-diagnostics)))))
+    (cl-loop
+     for x in hack
+     collect (alist-get 'eglot-lsp-diag (flymake-diagnostic-data x)) into res
+     finally (setq eglot--pushed-diagnostics `(,(vconcat res) ,eglot--docver))))
   (eglot--widening
    (if (and (null eglot--pulled-diagnostics) pushed-outdated-p)
        ;; Here, we don't have anything interesting to give to Flymake.
diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el
index c4fb6946aeb..f5c3dc3fbb2 100644
--- a/lisp/progmodes/elisp-mode.el
+++ b/lisp/progmodes/elisp-mode.el
@@ -1783,7 +1783,9 @@ and `eval-expression-print-level'.
   (funcall
    (syntax-propertize-rules
     (emacs-lisp-byte-code-comment-re
-     (1 (prog1 "< b" (elisp--byte-code-comment end (point))))))
+     (1 (prog1 "< b"
+          (goto-char (match-end 2))
+          (elisp--byte-code-comment end (point))))))
    start end))
 
 ;;;###autoload
diff --git a/lisp/progmodes/etags-regen.el b/lisp/progmodes/etags-regen.el
index b6adca8af7a..3d3ddc0521f 100644
--- a/lisp/progmodes/etags-regen.el
+++ b/lisp/progmodes/etags-regen.el
@@ -348,7 +348,7 @@ File extensions to generate the tags for."
 
 (defun etags-regen--build-program-options (ctags-p)
   (when (and etags-regen-regexp-alist ctags-p)
-    (user-error "etags-regen-regexp-alist is not supported with Ctags"))
+    (user-error "etags-regen-regexp-alist not supported with Ctags; to use this option, customize `etags-regen-program'"))
   (nconc
    (mapcan
     (lambda (group)
diff --git a/lisp/progmodes/etags.el b/lisp/progmodes/etags.el
index 79cfb91caa9..f7532fce6b1 100644
--- a/lisp/progmodes/etags.el
+++ b/lisp/progmodes/etags.el
@@ -2114,8 +2114,14 @@ file name, add `tag-partial-file-name-match-p' to the list value.")
   :type 'boolean
   :version "28.1")
 
-;;;###autoload
-(defun etags--xref-backend () 'etags)
+;;;###autoload (defun etags--xref-backend ()
+;;;###autoload   (when (or tags-table-list tags-file-name)
+;;;###autoload     (load "etags")
+;;;###autoload     'etags))
+
+(defun etags--xref-backend ()
+  (when (or tags-table-list tags-file-name)
+    'etags))
 
 (cl-defmethod xref-backend-identifier-at-point ((_backend (eql 'etags)))
   (find-tag--default))
diff --git a/lisp/progmodes/make-mode.el b/lisp/progmodes/make-mode.el
index 8856856100e..e34eaba3150 100644
--- a/lisp/progmodes/make-mode.el
+++ b/lisp/progmodes/make-mode.el
@@ -331,7 +331,7 @@ not be enclosed in { } or ( )."
                                              &rest fl-keywords)
   `(;; Do macro assignments.  These get the "variable-name" face.
     (,makefile-macroassign-regex
-     (1 font-lock-variable-name-face)
+     (1 'font-lock-variable-name-face)
      ;; This is for after !=
      (2 'makefile-shell prepend t)
      ;; This is for after normal assignment
@@ -340,10 +340,10 @@ not be enclosed in { } or ( )."
     ;; Rule actions.
     ;; FIXME: When this spans multiple lines we need font-lock-multiline.
     (makefile-match-action
-     (1 font-lock-type-face nil t)
+     (1 'font-lock-type-face nil t)
      (2 'makefile-shell prepend)
      ;; Only makepp has builtin commands.
-     (3 font-lock-builtin-face prepend t))
+     (3 'font-lock-builtin-face prepend t))
 
     ;; Variable references even in targets/strings/comments.
     (,var 2 font-lock-variable-name-face prepend)
@@ -364,11 +364,11 @@ not be enclosed in { } or ( )."
                    (string-replace "-" "[_-]" (regexp-opt (cdr keywords) t))
                  (regexp-opt keywords t)))
               "\\>[ \t]*\\([^: \t\n#]*\\)")
-             (1 font-lock-keyword-face) (2 font-lock-variable-name-face))))
+             (1 'font-lock-keyword-face) (2 'font-lock-variable-name-face))))
 
     ,@(if negation
-          `((,negation (1 font-lock-negation-char-face prepend)
-                       (2 font-lock-negation-char-face prepend t))))
+          `((,negation (1 'font-lock-negation-char-face prepend)
+                       (2 'font-lock-negation-char-face prepend t))))
 
     ,@(if space
           '(;; Highlight lines that contain just whitespace.
@@ -436,9 +436,9 @@ not be enclosed in { } or ( )."
 
    ;; Colon modifier keywords.
    '("\\(:\\s *\\)\\(build_c\\(?:ache\\|heck\\)\\|env\\(?:ironment\\)?\\|foreach\\|signature\\|scanner\\|quickscan\\|smartscan\\)\\>\\([^:\n]*\\)"
-     (1 font-lock-type-face t)
-     (2 font-lock-keyword-face t)
-     (3 font-lock-variable-name-face t))
+     (1 'font-lock-type-face t)
+     (2 'font-lock-keyword-face t)
+     (3 'font-lock-variable-name-face t))
 
    ;; $(function ...) $((function ...)) ${...} ${{...}} $[...] $[[...]]
    '("[^$]\\$\\(?:((?\\|{{?\\|\\[\\[?\\)\\([-a-zA-Z0-9_.]+\\s \\)"
diff --git a/lisp/progmodes/project.el b/lisp/progmodes/project.el
index 997c876b1fa..9e5a8be5e13 100644
--- a/lisp/progmodes/project.el
+++ b/lisp/progmodes/project.el
@@ -84,6 +84,12 @@
 ;; This project type can also be used for non-VCS controlled
 ;; directories, see the variable `project-vc-extra-root-markers'.
 ;;
+;; Some of the methods on this backend cache their computations for time
+;; determined either by variable `project-vc-cache-timeout' or
+;; `project-vc-non-essential-cache-timeout', depending on whether the
+;; MAYBE-PROMPT argument to `project-current' is non-nil, or the value
+;; of `non-essential' when project methods are called.
+;;
 ;; Utils:
 ;;
 ;; `project-combine-directories' and `project-subtract-directories',
@@ -275,7 +281,8 @@ of the project instance object."
       (if pr
           (project-remember-project pr)
         (project--remove-from-project-list
-         directory "Project `%s' not found; removed from list")
+         (abbreviate-file-name directory)
+         "Project `%s' not found; removed from list")
         (setq pr (cons 'transient directory))))
     pr))
 
@@ -586,16 +593,74 @@ project backend implementation of `project-external-roots'.")
 
 See `project-vc-extra-root-markers' for the marker value format.")
 
-;; FIXME: Should perhaps use `vc--repo-*prop' functions
-;;        (after promoting those to public).  --spwhitton
+(defvar project-vc-cache-timeout '((file-remote-p . nil)
+                                   (always . 2))
+  "Number of seconds to cache a value in VC-aware project methods.
+It can be nil, a number, or an alist where
+the key is a predicate, and the value is a number.
+A predicate function should take a directory string and if it returns
+non-nil, the corresponding value will be used as the timeout.
+Set to nil to disable time-based expiration.")
+
+(defvar project-vc-non-essential-cache-timeout '((file-remote-p . nil)
+                                                 (always . 300))
+  "Number of seconds to cache non-essential information.
+The format of the value is same as `project-vc-cache-timeout', but while
+the former is intended for interactive commands, this variable uses
+higher numbers, intended for \"background\" things like
+`project-mode-line' indicators and `project-uniquify-dirname-transform'.
+It is used when `non-essential' is non-nil.")
+
+(defun project--get-cached (dir key)
+  (let ((cached (vc-file-getprop dir key))
+        (current-time (float-time)))
+    (when (and (numberp (cdr cached))
+               ;; Support package upgrade mid-session.
+               (let* ((project-vc-cache-timeout
+                       (if non-essential
+                           project-vc-non-essential-cache-timeout
+                         project-vc-cache-timeout))
+                      (timeout
+                       (cond
+                        ((numberp project-vc-cache-timeout)
+                         project-vc-cache-timeout)
+                        ((null project-vc-cache-timeout)
+                         nil)
+                        ((listp project-vc-cache-timeout)
+                         (cdr
+                          (seq-find (lambda (pair)
+                                      (and (functionp (car pair))
+                                           (funcall (car pair) dir)))
+                                    project-vc-cache-timeout)))
+                        (t nil))))
+                 (or (null timeout)
+                     (< (- current-time (cdr cached)) timeout))))
+      (car cached))))
+
+(defun project--set-cached (dir key value)
+  (vc-file-setprop dir key (cons value (float-time))))
+
+;; TODO: We can have our own, separate obarray.
+(defun project--clear-cache ()
+  (obarray-map
+   (lambda (sym)
+     (if (get sym 'project-vc)
+         (put sym 'project-vc nil)))
+   vc-file-prop-obarray))
+
 (defun project-try-vc (dir)
-  ;; FIXME: Learn to invalidate when the value changes:
-  ;; `project-vc-merge-submodules' or `project-vc-extra-root-markers'.
-  (or (vc-file-getprop dir 'project-vc)
-      ;; FIXME: Cache for a shorter time (bug#78545).
-      (let ((res (project-try-vc--search dir)))
-        (and res (vc-file-setprop dir 'project-vc res))
-        res)))
+  "Returns a project value corresponding to DIR from the VC-aware backend.
+
+The value is cached, and depending on whether MAYBE-PROMPT was non-nil
+in the `project-current' call, the timeout is determined by
+`project-vc-cache-timeout' or `project-vc-non-essential-cache-timeout'."
+  (let ((cached (project--get-cached dir 'project-vc)))
+    (if (eq cached 'none)
+        nil
+      (or cached
+          (let ((res (project-try-vc--search dir)))
+            (project--set-cached dir 'project-vc (or res 'none))
+            res)))))
 
 (defun project-try-vc--search (dir)
   (let* ((backend-markers
@@ -896,13 +961,24 @@ DIRS must contain directory names."
   (cl-set-difference files dirs :test #'file-in-directory-p))
 
 (defun project--value-in-dir (var dir)
+  (alist-get
+   var
+   (let ((cached (project--get-cached dir 'project-vc-dir-locals)))
+     (if (eq cached 'none)
+         nil
+       (or cached
+           (let ((res (project--read-dir-locals dir)))
+             (project--set-cached dir 'project-vc-dir-locals (or res 'none))
+             res))))
+   (symbol-value var)))
+
+(defun project--read-dir-locals (dir)
   (with-temp-buffer
     (setq default-directory (file-name-as-directory dir))
+    ;; Don't use `hack-local-variables-apply' to avoid setting modes.
     (let ((enable-local-variables :all))
       (hack-dir-local-variables))
-    ;; Don't use `hack-local-variables-apply' to avoid setting modes.
-    (alist-get var file-local-variables-alist
-               (symbol-value var))))
+    file-local-variables-alist))
 
 (cl-defmethod project-buffers ((project (head vc)))
   (let* ((root (expand-file-name (file-name-as-directory (project-root project))))
@@ -924,6 +1000,11 @@ DIRS must contain directory names."
     (nreverse bufs)))
 
 (cl-defmethod project-name ((project (head vc)))
+  "Returns the name of this VC-aware type PROJECT.
+
+The value is cached, and depending on whether `non-essential' is nil,
+the timeout is determined by `project-vc-cache-timeout' or
+`project-vc-non-essential-cache-timeout'."
   (or (project--value-in-dir 'project-vc-name (project-root project))
       (cl-call-next-method)))
 
@@ -2206,7 +2287,7 @@ result in `project-list-file'.  Announce the project's removal
 from the list using REPORT-MESSAGE, which is a format string
 passed to `message' as its first argument."
   (project--ensure-read-project-list)
-  (when-let* ((ent (assoc (abbreviate-file-name project-root) project--list)))
+  (when-let* ((ent (assoc project-root project--list)))
     (setq project--list (delq ent project--list))
     (message report-message project-root)
     (project--write-project-list)))
@@ -2385,6 +2466,7 @@ projects.
 Display a message at the end summarizing what was found.
 Return the number of detected projects."
   (interactive "DDirectory: \nP")
+  (project--clear-cache)
   (project--ensure-read-project-list)
   (let ((dirs (if recursive
                   (directory-files-recursively dir "" t)
@@ -2417,12 +2499,18 @@ PREDICATE can be a function with 1 argument which determines which
 projects should be deleted."
   (dolist (proj (project-known-project-roots))
     (when (and (funcall (or predicate #'identity) proj)
-               (not (file-exists-p proj)))
+               (condition-case-unless-debug nil
+                   (not (file-exists-p proj))
+                 (file-error
+                  (yes-or-no-p
+                   (format "Forget unreachable project `%s'? "
+                           proj)))))
       (project-forget-project proj))))
 
 (defun project-forget-zombie-projects (&optional interactive)
   "Forget all known projects that don't exist any more."
   (interactive (list t))
+  (project--clear-cache)
   (let ((pred (when interactive (alist-get 'interactively project-prune-zombie-projects))))
     (project--delete-zombie-projects pred)))
 
@@ -2435,6 +2523,7 @@ to remove those projects from the index.
 Display a message at the end summarizing what was forgotten.
 Return the number of forgotten projects."
   (interactive "DDirectory: \nP")
+  (project--clear-cache)
   (let ((count 0))
     (if recursive
         (dolist (proj (project-known-project-roots))
@@ -2624,7 +2713,8 @@ slash-separated components from `project-name' will be appended to
 the buffer's directory name when buffers from two different projects
 would otherwise have the same name."
   (if-let* ((proj (project-current nil dirname)))
-      (let ((root (project-root proj)))
+      (let ((root (project-root proj))
+            (non-essential t))
         (expand-file-name
          (file-name-concat
           (file-name-directory root)
@@ -2634,27 +2724,6 @@ would otherwise have the same name."
 
 ;;; Project mode-line
 
-(defvar project-name-cache-timeout 300
-  "Number of seconds to cache the project name.
-Used by `project-name-cached'.")
-
-(defun project-name-cached (dir)
-  "Return the cached project name for the directory DIR.
-Until it's cached, retrieve the project name using `project-current'
-and `project-name', then put the name to the cache for the time defined
-by the variable `project-name-cache-timeout'.  This function is useful
-for project indicators such as on the mode line."
-  (let ((cached (vc-file-getprop dir 'project-name))
-        (current-time (float-time)))
-    (if (and cached (< (- current-time (cdr cached))
-                       project-name-cache-timeout))
-        (let ((value (car cached)))
-          (if (eq value 'none) nil value))
-      (let ((res (when-let* ((project (project-current nil dir)))
-                   (project-name project))))
-        (vc-file-setprop dir 'project-name (cons (or res 'none) current-time))
-        res))))
-
 ;;;###autoload
 (defcustom project-mode-line nil
   "Whether to show current project name and Project menu on the mode line.
@@ -2691,7 +2760,9 @@ value is `non-remote', show the project name only for local files."
     ;; 'last-coding-system-used' when reading the project name
     ;; from .dir-locals.el also enables flyspell-mode (bug#66825).
     (when-let* ((last-coding-system-used last-coding-system-used)
-                (project-name (project-name-cached default-directory)))
+                (non-essential t)
+                (project (project-current))
+                (project-name (project-name project)))
       (concat
        " "
        (propertize
diff --git a/lisp/progmodes/python.el b/lisp/progmodes/python.el
index b6981c9156c..2a3035c95c5 100644
--- a/lisp/progmodes/python.el
+++ b/lisp/progmodes/python.el
@@ -3366,6 +3366,16 @@ from `python-shell-prompt-regexp',
             python-shell--prompt-calculated-output-regexp
             (funcall build-regexp output-prompts)))))
 
+(defun python-shell-get-project-name ()
+  "Return the project name for the current buffer.
+Use `project-name-cached' if available."
+  (when (featurep 'project)
+    (if (fboundp 'project-name-cached)
+        (project-name-cached default-directory)
+      (when-let* ((proj (project-current)))
+        (file-name-nondirectory
+         (directory-file-name (project-root proj)))))))
+
 (defun python-shell-get-process-name (dedicated)
   "Calculate the appropriate process name for inferior Python process.
 If DEDICATED is nil, this is simply `python-shell-buffer-name'.
@@ -3374,11 +3384,8 @@ name respectively the current project name."
   (pcase dedicated
     ('nil python-shell-buffer-name)
     ('project
-     (if-let* ((proj (and (featurep 'project)
-                          (project-current))))
-         (format "%s[%s]" python-shell-buffer-name (file-name-nondirectory
-                                                    (directory-file-name
-                                                     (project-root proj))))
+     (if-let* ((proj-name (python-shell-get-project-name)))
+         (format "%s[%s]" python-shell-buffer-name proj-name)
        python-shell-buffer-name))
     (_ (format "%s[%s]" python-shell-buffer-name (buffer-name)))))
 
@@ -3816,16 +3823,6 @@ variable.
   (compilation-shell-minor-mode 1)
   (python-pdbtrack-setup-tracking))
 
-(defvar-local python-shell--process-cache)
-(defvar-local python-shell--process-cache-valid)
-
-(defun python-shell--invalidate-process-cache ()
-  "Invalidate process cache."
-  (dolist (buffer (buffer-list))
-    (with-current-buffer buffer
-      (setq python-shell--process-cache nil
-            python-shell--process-cache-valid nil))))
-
 (defun python-shell-make-comint (cmd proc-name &optional show internal)
   "Create a Python shell comint buffer.
 CMD is the Python command to be executed and PROC-NAME is the
@@ -3842,7 +3839,6 @@ killed."
       (let* ((proc-buffer-name
               (format (if (not internal) "*%s*" " *%s*") proc-name)))
         (when (not (comint-check-proc proc-buffer-name))
-          (python-shell--invalidate-process-cache)
           (let* ((cmdlist (split-string-and-unquote cmd))
                  (interpreter (car cmdlist))
                  (args (cdr cmdlist))
@@ -3966,15 +3962,7 @@ If current buffer is in `inferior-python-mode', return it."
 
 (defun python-shell-get-process ()
   "Return inferior Python process for current buffer."
-  (unless (and python-shell--process-cache-valid
-               (or (not python-shell--process-cache)
-                   (and (process-live-p python-shell--process-cache)
-                        (buffer-live-p
-                         (process-buffer python-shell--process-cache)))))
-    (setq python-shell--process-cache
-          (get-buffer-process (python-shell-get-buffer))
-          python-shell--process-cache-valid t))
-  python-shell--process-cache)
+  (get-buffer-process (python-shell-get-buffer)))
 
 (defun python-shell-get-process-or-error (&optional interactivep)
   "Return inferior Python process for current buffer or signal error.
@@ -5854,7 +5842,7 @@ Set to nil by `python-eldoc-function' if
 
 (defcustom python-eldoc-function-timeout 1
   "Timeout for `python-eldoc-function' in seconds."
-  :type 'integer
+  :type 'number
   :version "25.1")
 
 (defcustom python-eldoc-function-timeout-permanent t
diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el
index 84a3fa4dfba..1e51b23eaff 100644
--- a/lisp/progmodes/xref.el
+++ b/lisp/progmodes/xref.el
@@ -247,11 +247,9 @@ generic functions.")
 
 ;;;###autoload
 (defun xref-find-backend ()
-  (or
-   (run-hook-with-args-until-success 'xref-backend-functions)
-   (user-error "No Xref backend available")))
+  (run-hook-with-args-until-success 'xref-backend-functions))
 
-(cl-defgeneric xref-backend-definitions (backend identifier)
+(cl-defgeneric xref-backend-definitions (_backend _identifier)
   "Find definitions of IDENTIFIER.
 
 The result must be a list of xref objects.  If IDENTIFIER
@@ -264,7 +262,8 @@ IDENTIFIER can be any string returned by
 `xref-backend-identifier-at-point', or from the table returned by
 `xref-backend-identifier-completion-table'.
 
-To create an xref object, call `xref-make'.")
+To create an xref object, call `xref-make'."
+  (xref--no-backend-available))
 
 (cl-defgeneric xref-backend-references (_backend identifier)
   "Find references of IDENTIFIER.
@@ -285,12 +284,13 @@ The default implementation uses `xref-references-in-directory'."
        (xref--project-root pr)
        (project-external-roots pr))))))
 
-(cl-defgeneric xref-backend-apropos (backend pattern)
+(cl-defgeneric xref-backend-apropos (_backend _pattern)
   "Find all symbols that match PATTERN string.
 The second argument has the same meaning as in `apropos'.
 
 If BACKEND is implemented in Lisp, it can use
-`xref-apropos-regexp' to convert the pattern to regexp.")
+`xref-apropos-regexp' to convert the pattern to regexp."
+  (xref--no-backend-available))
 
 (cl-defgeneric xref-backend-identifier-at-point (_backend)
   "Return the relevant identifier at point.
@@ -306,8 +306,9 @@ recognize and then delegate the work to an external process."
   (let ((thing (thing-at-point 'symbol)))
     (and thing (substring-no-properties thing))))
 
-(cl-defgeneric xref-backend-identifier-completion-table (backend)
-  "Return the completion table for identifiers.")
+(cl-defgeneric xref-backend-identifier-completion-table (_backend)
+  "Return the completion table for identifiers."
+  nil)
 
 (cl-defgeneric xref-backend-identifier-completion-ignore-case (_backend)
   "Return t if case is not significant in identifier completion."
@@ -329,6 +330,10 @@ KEY extracts the key from an element."
     (cl-loop for key being hash-keys of table using (hash-values value)
              collect (cons key (nreverse value)))))
 
+(defun xref--no-backend-available ()
+  (user-error
+   "No Xref backend.  Try `M-x eglot', `M-x visit-tags-table', or `M-x etags-regen-mode'."))
+
 (defun xref--insert-propertized (props &rest strings)
   "Insert STRINGS with text properties PROPS."
   (let ((start (point)))
diff --git a/lisp/replace.el b/lisp/replace.el
index d8b27544128..933249d824c 100644
--- a/lisp/replace.el
+++ b/lisp/replace.el
@@ -1878,9 +1878,6 @@ is not modified."
          (bound-and-true-p ido-everywhere))
      (substitute-command-keys
       "(\\<ido-completion-map>\\[ido-select-text] to end): "))
-    ((bound-and-true-p icomplete-mode)
-     (substitute-command-keys
-      "(\\<icomplete-minibuffer-map>\\[icomplete-exit] to end): "))
     ((bound-and-true-p fido-mode)
      (substitute-command-keys
       "(\\<icomplete-fido-mode-map>\\[icomplete-fido-exit] to end): "))
diff --git a/lisp/subr.el b/lisp/subr.el
index 40325c30326..6f2dcb8c16d 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1148,8 +1148,8 @@ side-effects, and the argument LIST is not modified."
                              (make-symbol "f")))
                      (r (make-symbol "r")))
                 `(let (,@(and f `((,f ,pred)))
-                       (,tail ,list)
-                       (,r nil))
+                       (,r nil)
+                       (,tail ,list))
                    (while (and ,tail (funcall ,(or f pred) (car ,tail)))
                      (push (car ,tail) ,r)
                      (setq ,tail (cdr ,tail)))
@@ -5445,9 +5445,11 @@ If BODY finishes, `while-no-input' returns whatever value BODY produced."
             (t val)))))))
 
 (defmacro condition-case-unless-debug (var bodyform &rest handlers)
-  "Like `condition-case' except that it does not prevent debugging.
-More specifically if `debug-on-error' is set then the debugger will be invoked
-even if this catches the signal."
+  "Like `condition-case', except that it does not prevent debugging.
+More specifically, if `debug-on-error' is set, then the debugger will
+be invoked even if some handler catches the signal.
+Note that this doesn't prevent the handler from executing, it just
+causes the debugger to be called before running the handler."
   (declare (debug condition-case) (indent 2))
   `(condition-case ,var
        ,bodyform
diff --git a/lisp/system-sleep.el b/lisp/system-sleep.el
new file mode 100644
index 00000000000..e09f2fedcd1
--- /dev/null
+++ b/lisp/system-sleep.el
@@ -0,0 +1,513 @@
+;;; system-sleep.el --- System sleep/wake event management -*- lexical-binding: t -*-
+
+;; Copyright (C) 2025-2026 Free Software Foundation, Inc.
+
+;; Author: Stephane Marks <shipmints@gmail.com>
+;; Maintainer: emacs-devel@gnu.org
+;; Keywords: convenience
+;; Package-Requires: ((emacs "31.1"))
+
+;; This file is part of GNU Emacs.
+
+;; GNU Emacs is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; GNU Emacs is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Call `system-sleep-block-sleep' to inhibit system-wide idle sleep.
+;; Idle sleep is typically triggered when the system does not detect
+;; user activity and is independent of any processing that may be on
+;; going.  This function is useful to block idle sleep for long-running
+;; operations, for example, when a compilation is running.  You have the
+;; option of keeping the system active while letting the display sleep.
+;; This function returns a token which you must use to unblock this
+;; request.
+;;
+;; Call `system-sleep-unblock-sleep' with the token from
+;; `system-sleep-block-sleep' to unblock system-wide idle sleep for this
+;; request.  There may be other active requests which will prevent the
+;; system from sleeping.
+;;
+;; The function `system-sleep-sleep-blocked-p' will tell you if
+;; `system-sleep' has any active system sleep blocks.
+;;
+;; Note: When the Emacs process dies, blocks are released on all
+;; platforms.
+;;
+;; You can register functions on the abnormal hook
+;; `system-sleep-event-functions'.  Each function will be called when
+;; the system is preparing for sleep and when the system wakes from
+;; sleep.  These functions are useful when you want to close (and
+;; potentially reopen) external connections or serial ports.
+;;
+;; On supported GNU/Linux systems, the implementation is via D-Bus to
+;; inhibit idle sleep, keep the display active, and forward events from
+;; logind for system sleep events.
+;;
+;; On macOS and MS-Windows, native APIs are used to block idle sleep,
+;; keep the display active, and provide sleep event notifications.
+;;
+;; On MS-Windows, an idle sleep block that keeps the display active may
+;; not inhibit the screen saver.
+;;
+;; Externally to Emacs, there are system utility functions that you can
+;; use to inspect all processes on your system that might be blocking it
+;; from sleeping.
+;;
+;; On D-Bus systems, you can use the commands:
+;;
+;;   systemd-inhibit --list
+;; or
+;;   dbus-send --system --print-reply --dest=org.freedesktop.login1 \
+;;   /org/freedesktop/login1 \
+;;   org.freedesktop.login1.Manager.ListInhibitors
+;;
+;; Note: You can find the sleep/shutdown delay InhibitDelayMaxUSec in
+;; the file logind.conf(5) which typically defaults to 5 seconds.
+;;
+;; On macOS, you can use the command:
+;;
+;;   pmset -g assertions
+;;
+;; On MS-Windows, you can use the following command which may need to be
+;; run as an administrator:
+;;
+;;   powercfg -requests
+
+;;; Code:
+
+(require 'cl-lib)
+
+;; Pacify the byte compiler.
+(declare-function dbus--fd-close "dbusbind.c")
+(declare-function dbus-unregister-object "dbus.el")
+(declare-function dbus-register-signal "dbus.el")
+(declare-function dbus-call-method "dbus.el")
+(declare-function dbus-list-activatable-names "dbus.el")
+(defvar dbus-service-emacs)
+
+(defgroup system-sleep nil
+  "System sleep/wake blocking and event management."
+  :group 'system-interface
+  :version "31.1")
+
+(defvar system-sleep--back-end nil
+  "Generic sleep-wake method system dispatcher.")
+
+(defvar system-sleep--sleep-block-tokens nil
+  "A list of active sleep-block tokens.
+If non-nil, idle sleep is inhibited by `system-sleep'.")
+
+(cl-defstruct
+    (sleep-event (:type list) :named
+                 (:constructor nil)
+                 (:constructor make-sleep-event (state)))
+  state)
+
+;;;###autoload
+(defcustom system-sleep-event-functions nil
+  "Abnormal hook invoked on system sleep events.
+Each function is called with one argument EVENT, a sleep event.  EVENT
+state can be retrieved via \\+`(sleep-event-state EVENT)'.  It will be
+one of the symbols \\+`pre-sleep' or \\+`post-wake'.
+
+Handling \\+`pre-sleep' events should be done as fast as possible, do as
+little as possible and avoid user prompts.  Systems often grant a very
+short pre-sleep processing interval, typically ranging between 2 and 5
+seconds.  The system may sleep even if your processing is not complete.
+For example, your function could close active connections or serial
+ports.
+
+Handling \\+`post-wake' events offers more leeway.  Your function could
+reestablish connections.
+
+Note: Your code, or the functions it calls, should not raise any signals
+or all hooks will be halted preventing other hook functions from
+cleaning up or waking up.  You can wrap your code in a `condition-case'
+block."
+  :type 'hook
+  :version "31.1")
+
+;;;###autoload
+(defun system-sleep-block-sleep (&optional why allow-display-sleep)
+  "Inhibit system idle sleep.
+Optional WHY is a string that identifies a sleep block to system utility
+commands that inspect system-wide blocks.  WHY defaults to \"Emacs\".
+
+Optional ALLOW-DISPLAY-SLEEP, when non-nil, allows the display to sleep
+or a screen saver to run while the system idle sleep is blocked.  The
+default is to keep the display active.
+
+Return a sleep blocking token.  You must retain this value and provide
+it to `system-sleep-unblock-sleep' to unblock its associated block.
+
+Return nil if system sleep cannot be inhibited.
+
+Note: All active blocks are released when the Emacs process dies.
+Despite this, you should unblock your blocks when your processing is
+complete.  See `with-system-sleep-block' for an easy way to do that."
+  (when system-sleep--back-end
+    (system-sleep--block-sleep (or why "Emacs") allow-display-sleep)))
+
+(defun system-sleep-unblock-sleep (token)
+  "Unblock the system sleep block associated with TOKEN.
+Return non-nil TOKEN was unblocked, or nil if not.
+In the unlikely event that unblock fails, the block will be released
+when the Emacs process dies."
+  (when system-sleep--back-end
+    (system-sleep--unblock-sleep token)))
+
+;;;###autoload
+(defmacro with-system-sleep-block (&optional why allow-display-sleep &rest body)
+  "Execute the forms in BODY while blocking system sleep.
+The optional arguments WHY and ALLOW-DISPLAY-SLEEP have the same meaning
+as in `system-sleep-block-sleep', which see.
+The block is unblocked when BODY completes."
+  (declare (indent 1) (debug t))
+  (let ((token (make-symbol "--sleep-token--")))
+    `(let ((,token (system-sleep-block-sleep ,why ,allow-display-sleep)))
+       (unwind-protect
+           (progn
+             ,@body)
+         (system-sleep-unblock-sleep ,token)))))
+
+(defun system-sleep-unblock-all-sleep-blocks ()
+  "Unblock all `system-sleep' blocks."
+  (while system-sleep--sleep-block-tokens
+    (system-sleep-unblock-sleep (car system-sleep--sleep-block-tokens))))
+
+;;;###autoload
+(defun system-sleep-sleep-blocked-p ()
+  "Return non-nil if there are active sleep blocks."
+  (and system-sleep--back-end
+       system-sleep--sleep-block-tokens))
+
+
+;; Internal implementation.
+
+(defun system-sleep--set-back-end ()
+  "Determine sleep/wake host system type."
+  ;; Order matters to accommodate the cases where an NS or MS-Windows
+  ;; build have the dbus feature.
+  (setq system-sleep--back-end
+        (cond ((featurep 'ns) 'ns)
+              ((featurep 'w32) 'w32)
+              ((and (require 'dbus)
+                    (featurep 'dbusbind)
+                    (member "org.freedesktop.login1"
+                            (dbus-list-activatable-names :system)))
+               'dbus)
+              (t nil))))
+
+(defun system-sleep--sleep-event-handler (event)
+  "`sleep-event' EVENT handler."
+  (declare (completion ignore))
+  (interactive "e")
+  (run-hook-with-args 'system-sleep-event-functions event))
+
+(defun system-sleep-enable ()
+  "Enable `system-sleep'."
+  (unless system-sleep--back-end
+    (if (and (system-sleep--set-back-end)
+             (system-sleep--enable))
+        (keymap-set special-event-map "<sleep-event>"
+                    #'system-sleep--sleep-event-handler)
+      (warn "`system-sleep' could not be initialized"))))
+
+(defun system-sleep-disable ()
+  "Disable `system-sleep'."
+  (when system-sleep--back-end
+    (keymap-set special-event-map "<sleep-event>" #'ignore)
+    (system-sleep-unblock-all-sleep-blocks)
+    (system-sleep--disable)
+    (setq system-sleep--back-end nil)))
+
+(cl-defgeneric system-sleep--enable ()
+  "Enable the `system-sleep' back end.
+Return t if the back end is initialized, or nil.")
+
+(cl-defgeneric system-sleep--disable ()
+  "Disable the sleep/wake back end.")
+
+(cl-defgeneric system-sleep--block-sleep (why allow-display-sleep)
+  "Inhibit system idle sleep.
+WHY is a string that identifies a sleep block to system utility commands
+that inspect system-wide blocks.
+When non-nil, ALLOW-DISPLAY-SLEEP allows the display to sleep or a
+screen saver to run while the system idle sleep is blocked.  The default
+is to keep the display active.
+Return a sleep-block token.")
+
+(cl-defgeneric system-sleep--unblock-sleep (token)
+  "Unblock the system sleep block associated with TOKEN.
+Return non-nil TOKEN was unblocked, or nil if not.")
+
+(defvar system-sleep--event-in-progress nil)
+(defvar system-sleep--event-queue nil)
+
+(defun system-sleep--sleep-event-function (event)
+  "Handle <sleep-event> special events and avoid races."
+  ;; Queue incoming event.
+  (setq system-sleep--event-queue
+        (append system-sleep--event-queue (list event)))
+  ;; If an event is already in progress, return right away.
+  ;; Otherwise, process queued events.
+  (while (and (not system-sleep--event-in-progress)
+              system-sleep--event-queue)
+    (let ((current-event (pop system-sleep--event-queue)))
+      (setq system-sleep--event-in-progress current-event)
+      (unwind-protect
+          (run-hook-with-args 'system-sleep-event-functions
+                              current-event)
+        (setq system-sleep--event-in-progress nil)))))
+
+
+;; D-Bus support.
+
+(defvar system-sleep--dbus-sleep-inhibitor-types "sleep"
+  "This is a colon-separated list of options.
+The default is \"sleep\" which is compatible with the other supported
+`system-sleep' platforms.  This could also be
+\"sleep:shutdown\". Shutdown is available only on D-Bus systems.")
+
+(defvar system-sleep--dbus-delay-lock nil)
+(defvar system-sleep--dbus-pre-sleep-signal nil)
+
+(defun system-sleep--dbus-delay-lock (make-or-close)
+  (cond (make-or-close
+         (if system-sleep--dbus-delay-lock
+             (error "Delay lock should be nil")
+           (setq system-sleep--dbus-delay-lock
+                 (dbus-call-method
+                  :system
+                  "org.freedesktop.login1"
+                  "/org/freedesktop/login1"
+                  "org.freedesktop.login1.Manager"
+                  "Inhibit"
+                  :keep-fd
+                  system-sleep--dbus-sleep-inhibitor-types
+                  dbus-service-emacs
+                  "Emacs sleep event watcher"
+                  "delay"))))
+        (t
+         (when system-sleep--dbus-delay-lock
+           (dbus--fd-close system-sleep--dbus-delay-lock)
+           (setq system-sleep--dbus-delay-lock nil)))))
+
+(defun system-sleep--dbus-prepare-for-sleep-callback (sleep-or-wake)
+  (cond (sleep-or-wake
+         (insert-special-event (make-sleep-event 'pre-sleep)))
+        (t
+         (insert-special-event (make-sleep-event 'post-wake)))))
+
+(defun system-sleep--dbus-prepare-for-sleep-watcher (make-or-close)
+  (cond (make-or-close
+         (if system-sleep--dbus-pre-sleep-signal
+             (error "PrepareForSleep watcher should be nil")
+           (setq system-sleep--dbus-pre-sleep-signal
+                 (dbus-register-signal
+                  :system
+                  "org.freedesktop.login1"
+                  "/org/freedesktop/login1"
+                  "org.freedesktop.login1.Manager"
+                  "PrepareForSleep"
+                  #'system-sleep--dbus-prepare-for-sleep-callback))))
+        (t
+         (dbus-unregister-object system-sleep--dbus-pre-sleep-signal)
+         (setq system-sleep--dbus-pre-sleep-signal nil))))
+
+(defun system-sleep--dbus-prepare-for-sleep-function (event)
+  (pcase (sleep-event-state event)
+    ('pre-sleep
+     (system-sleep--dbus-delay-lock nil))
+    ('post-wake
+     (system-sleep--dbus-delay-lock t))))
+
+(cl-defmethod system-sleep--enable (&context
+                                    (system-sleep--back-end (eql 'dbus)))
+  ;; Order matters.
+  (add-hook 'system-sleep-event-functions
+          #'system-sleep--dbus-prepare-for-sleep-function
+          ;; This must run last.
+          99)
+  (system-sleep--dbus-delay-lock t)
+  (system-sleep--dbus-prepare-for-sleep-watcher t)
+  t)
+
+(cl-defmethod system-sleep--disable (&context
+                                     (system-sleep--back-end (eql 'dbus)))
+  (system-sleep--dbus-prepare-for-sleep-watcher nil)
+  (system-sleep--dbus-delay-lock nil)
+  (remove-hook 'system-sleep-event-functions
+               #'system-sleep--dbus-prepare-for-sleep-function))
+
+(cl-defmethod system-sleep--block-sleep (why
+                                         allow-display-sleep
+                                         &context
+                                         (system-sleep--back-end (eql 'dbus)))
+  (let ((subtokens))
+    (if-let* ((sleep-cookie (dbus-call-method
+                             :system
+                             "org.freedesktop.login1"
+                             "/org/freedesktop/login1"
+                             "org.freedesktop.login1.Manager"
+                             "Inhibit"
+                             :keep-fd
+                             system-sleep--dbus-sleep-inhibitor-types
+                             dbus-service-emacs
+                             why
+                             "block")))
+        (progn
+          (let ((inhibit-quit t))
+            (push (cons 'dbus-inhibitor-lock sleep-cookie) subtokens))
+          (unless allow-display-sleep
+            (if-let* ((screen-cookie
+                       (dbus-call-method
+                        :session
+                        "org.freedesktop.ScreenSaver"
+                        "/org/freedesktop/ScreenSaver"
+                        "org.freedesktop.ScreenSaver"
+                        "Inhibit"
+                        dbus-service-emacs
+                        "Screen Saver Block")))
+                (let ((inhibit-quit t))
+                  (push (cons 'dbus-screensaver-lock screen-cookie) subtokens))
+              (warn "Unable to block the screen saver")))
+          (let ((inhibit-quit t))
+            (let ((token (list :system 'dbus :why why :subtokens subtokens)))
+              (push token system-sleep--sleep-block-tokens)
+              token)))
+      (warn "Unable to block system sleep"))))
+
+(cl-defmethod system-sleep--unblock-sleep (token
+                                           &context
+                                           (system-sleep--back-end (eql 'dbus)))
+
+  (if (memq token system-sleep--sleep-block-tokens)
+      (progn
+        (let ((inhibit-quit t))
+          (setq system-sleep--sleep-block-tokens
+                (remq token system-sleep--sleep-block-tokens)))
+        (dolist (subtoken (plist-get token :subtokens))
+          (pcase (car subtoken)
+            ('dbus-inhibitor-lock
+             (dbus--fd-close (cdr subtoken)))
+            ('dbus-screensaver-lock
+             (dbus-call-method
+              :session
+              "org.freedesktop.ScreenSaver"
+              "/org/freedesktop/ScreenSaver"
+              "org.freedesktop.ScreenSaver"
+              "UnInhibit"
+              (cdr subtoken)))))
+        t)
+    (warn "Unknown `system-sleep' sleep token")
+    nil))
+
+
+;; macOS/GNUstep NS support.
+
+(declare-function ns-block-system-sleep "nsfns.m")
+(declare-function ns-unblock-system-sleep "nsfns.m")
+
+(cl-defmethod system-sleep--enable (&context
+                                    (system-sleep--back-end (eql 'ns)))
+  t)
+
+(cl-defmethod system-sleep--disable (&context
+                                     (system-sleep--back-end (eql 'ns)))
+  (ignore))
+
+(cl-defmethod system-sleep--block-sleep (why
+                                         allow-display-sleep
+                                         &context
+                                         (system-sleep--back-end (eql 'ns)))
+  (if-let* ((cookie (ns-block-system-sleep why allow-display-sleep))
+            (token (list :system 'ns :why why
+                         :token (cons 'ns-sleep-block cookie))))
+      (progn
+        (let ((inhibit-quit t))
+          (push token system-sleep--sleep-block-tokens))
+        token)
+    (warn "Unable to block system sleep")))
+
+(cl-defmethod system-sleep--unblock-sleep (token
+                                           &context
+                                           (system-sleep--back-end (eql 'ns)))
+  (if (memq token system-sleep--sleep-block-tokens)
+      (progn
+        (let ((inhibit-quit t))
+          (setq system-sleep--sleep-block-tokens
+                (remq token system-sleep--sleep-block-tokens)))
+        (if (ns-unblock-system-sleep (cdr (plist-get token :token)))
+            t
+          (warn "Unable to unblock system sleep (blocks are released when Emacs dies)")
+          nil))
+    (warn "Unknown `system-sleep' sleep token")
+    nil))
+
+
+;; MS-Windows support.
+
+(declare-function w32-block-system-sleep "w32fns.c")
+(declare-function w32-unblock-system-sleep "w32fns.c")
+(declare-function w32-system-sleep-block-count "w32fns.c")
+
+(defvar system-sleep--w32-sleep-block-count 0)
+
+(cl-defmethod system-sleep--enable (&context
+                                    (system-sleep--back-end (eql 'w32)))
+  t)
+
+(cl-defmethod system-sleep--disable (&context
+                                     (system-sleep--back-end (eql 'w32)))
+  (ignore))
+
+(cl-defmethod system-sleep--block-sleep (why
+                                         allow-display-sleep
+                                         &context
+                                         (system-sleep--back-end (eql 'w32)))
+  (if-let* ((cookie (w32-block-system-sleep allow-display-sleep))
+            (token (list :system 'w32 :why why
+                         :token (cons 'w32-sleep-block cookie))))
+      (progn
+        (let ((inhibit-quit t))
+          (push token system-sleep--sleep-block-tokens))
+        token)
+    (warn "Unable to block system sleep")))
+
+(cl-defmethod system-sleep--unblock-sleep (token
+                                           &context
+                                           (system-sleep--back-end (eql 'w32)))
+  (if (memq token system-sleep--sleep-block-tokens)
+      (progn
+        (let ((inhibit-quit t))
+          (setq system-sleep--sleep-block-tokens
+                (remq token system-sleep--sleep-block-tokens)))
+        (if (eq 0 (w32-system-sleep-block-count))
+            (warn "Unable to unblock system sleep (no active tokens)")
+          (if (w32-unblock-system-sleep)
+              t
+            (warn "Unable to unblock system sleep (blocks are released when Emacs dies)")
+            nil)))
+    (warn "Unknown `system-sleep' sleep token")
+    nil))
+
+
+;; Initialize system-sleep.
+
+(system-sleep-enable)
+
+(provide 'system-sleep)
+
+;;; system-sleep.el ends here
diff --git a/lisp/textmodes/yaml-ts-mode.el b/lisp/textmodes/yaml-ts-mode.el
index 948186b5a9a..c1521c82c22 100644
--- a/lisp/textmodes/yaml-ts-mode.el
+++ b/lisp/textmodes/yaml-ts-mode.el
@@ -48,12 +48,11 @@
 
 (defcustom yaml-ts-mode-yamllint-options nil
   "Additional options to pass to yamllint command used for Flymake support.
-If non-nil, this should be a single string with command-line options
-for the yamllint command, with individual options separated by whitespace."
+This should be a list of strings, each one passed as a separate argument
+to the yamllint command."
   :group 'yaml-ts-mode
   :version "31.1"
-  :type '(choice (const :tag "None" nil)
-                 (string :tag "Options as a single string")))
+  :type '(repeat string))
 
 (defvar yaml-ts-mode--syntax-table
   (let ((table (make-syntax-table)))
@@ -199,10 +198,7 @@ Calls REPORT-FN directly."
   (when (process-live-p yaml-ts-mode--flymake-process)
     (kill-process yaml-ts-mode--flymake-process))
   (let ((yamllint (executable-find "yamllint"))
-        (params (if yaml-ts-mode-yamllint-options
-                    (append (split-string yaml-ts-mode-yamllint-options) '("-f" "parsable" "-"))
-                  '("-f" "parsable" "-")))
-
+        (params (append yaml-ts-mode-yamllint-options '("-f" "parsable" "-")))
         (source (current-buffer))
         (diagnostics-pattern (eval-when-compile
                                (rx bol (+? nonl) ":" ; every diagnostic line start with the filename
diff --git a/lisp/time.el b/lisp/time.el
index c78a51e9f97..f553ebab413 100644
--- a/lisp/time.el
+++ b/lisp/time.el
@@ -177,6 +177,18 @@ depend on `display-time-day-and-date' and `display-time-24hr-format'."
   :type '(choice (const :tag "Default" nil)
                  string))
 
+(defcustom display-time-help-echo-format "%a %b %e, %Y"
+  "Format for the help echo when hovering over the time in the mode line.
+Use the function `customize-variable' to choose a common format, and/or
+see the function `format-time-string' for an explanation of the syntax."
+  :version "31.1"
+  :type `(choice
+          ,@(mapcar #'(lambda (fmt)
+                        (list 'const
+                              ':tag (format-time-string fmt 0 "UTC") fmt))
+                    '("%a %b %e, %Y" "%F (%a)" "%a %D"))
+          (string :tag "Format string")))
+
 (defcustom display-time-string-forms
   '((if (and (not display-time-format) display-time-day-and-date)
         (format-time-string "%a %b %e " now)
@@ -186,7 +198,9 @@ depend on `display-time-day-and-date' and `display-time-24hr-format'."
                              (if display-time-24hr-format "%H:%M" "%-I:%M%p"))
                          now)
      'face 'display-time-date-and-time
-     'help-echo (format-time-string "%a %b %e, %Y" now))
+     'help-echo (format-time-string (if (stringp display-time-help-echo-format)
+                                        display-time-help-echo-format
+                                      "%a %b %e, %Y") now))
     load
     (if mail
         ;; Build the string every time to act on customization.
diff --git a/lisp/tutorial.el b/lisp/tutorial.el
index c071c1ff1d8..6ade473c975 100644
--- a/lisp/tutorial.el
+++ b/lisp/tutorial.el
@@ -69,18 +69,17 @@ Where
   WHERE       is a text describing the key sequences to which DEF-FUN is
               bound now (or, if it is remapped, a key sequence
               for the function it is remapped to)"
-  (with-output-to-temp-buffer (help-buffer)
-    (help-setup-xref (list #'tutorial--describe-nonstandard-key value)
-                     (called-interactively-p 'interactive))
-    (with-current-buffer (help-buffer)
-      (insert
-       "Your Emacs customizations override the default binding for this key:"
-       "\n\n")
-      (let ((inhibit-read-only t))
-        (cond
-         ((eq (car value) 'cua-mode)
-          (insert
-           "CUA mode is enabled.
+  (help-setup-xref (list #'tutorial--describe-nonstandard-key value)
+                   (called-interactively-p 'interactive))
+  (with-help-window (help-buffer)
+    (insert
+     "Your Emacs customizations override the default binding for this key:"
+     "\n\n")
+    (let ((inhibit-read-only t))
+      (cond
+       ((eq (car value) 'cua-mode)
+        (insert
+         "CUA mode is enabled.
 
 When CUA mode is enabled, you can use C-z, C-x, C-c, and C-v to
 undo, cut, copy, and paste in addition to the normal Emacs
@@ -94,70 +93,70 @@ options:
 - press the prefix key twice very quickly (within 0.2 seconds),
 - press the prefix key and the following key within 0.2 seconds, or
 - use the SHIFT key with the prefix key, i.e. C-S-x or C-S-c."))
-         ((eq (car value) 'current-binding)
-          (let ((cb    (nth 1 value))
-                (db    (nth 2 value))
-                (key   (nth 3 value))
-                (where (nth 4 value))
-                map
-                (maps (current-active-maps))
-                mapsym)
-            ;; Look at the currently active keymaps and try to find
-            ;; first the keymap where the current binding occurs:
-            (while maps
-              (let* ((m (car maps))
-                     (mb (lookup-key m key t)))
-                (setq maps (cdr maps))
-                (when (eq mb cb)
-                  (setq map m)
-                  (setq maps nil))))
-            ;; Now, if a keymap was found we must found the symbol
-            ;; name for it to display to the user.  This can not
-            ;; always be found since all keymaps does not have a
-            ;; symbol pointing to them, but here they should have
-            ;; that:
-            (when map
-              (mapatoms (lambda (s)
-                          (and
-                           ;; If not already found
-                           (not mapsym)
-                           ;; and if s is a keymap
-                           (and (boundp s)
-                                (keymapp (symbol-value s)))
-                           ;; and not the local symbol map
-                           (not (eq s 'map))
-                           ;; and the value of s is map
-                           (eq map (symbol-value s))
-                           ;; then save this value in mapsym
-                           (setq mapsym s)))))
-            (insert
-             (format-message
-              "The default Emacs binding for the key %s is the command `%s'.  "
-              (key-description key)
-              db))
-            (insert "However, your customizations have "
-                    (if cb
-                        (format-message "rebound it to the command `%s'" cb)
-                      "unbound it"))
-            (insert ".")
-            (when mapsym
-              (insert "  (For the more advanced user:"
-                      (format-message
-                       " This binding is in the keymap `%s'.)" mapsym)))
-            (if (string= where "")
-                (unless (keymapp db)
-                  (insert "\n\nYou can use M-x "
-                          (format "%s" db)
-                          " RET instead."))
-              (insert "\n\nWith your current key bindings"
-                      " you can use "
-                      (if (string-match-p "^the .*menus?$" where)
-                          ""
-                        "the key ")
-                      where
-                      (format-message " to get the function `%s'." db))))
-          (fill-region (point-min) (point)))))
-      (help-print-return-message))))
+       ((eq (car value) 'current-binding)
+        (let ((cb    (nth 1 value))
+              (db    (nth 2 value))
+              (key   (nth 3 value))
+              (where (nth 4 value))
+              map
+              (maps (current-active-maps))
+              mapsym)
+          ;; Look at the currently active keymaps and try to find
+          ;; first the keymap where the current binding occurs:
+          (while maps
+            (let* ((m (car maps))
+                   (mb (lookup-key m key t)))
+              (setq maps (cdr maps))
+              (when (eq mb cb)
+                (setq map m)
+                (setq maps nil))))
+          ;; Now, if a keymap was found we must found the symbol
+          ;; name for it to display to the user.  This can not
+          ;; always be found since all keymaps does not have a
+          ;; symbol pointing to them, but here they should have
+          ;; that:
+          (when map
+            (mapatoms (lambda (s)
+                        (and
+                         ;; If not already found
+                         (not mapsym)
+                         ;; and if s is a keymap
+                         (and (boundp s)
+                              (keymapp (symbol-value s)))
+                         ;; and not the local symbol map
+                         (not (eq s 'map))
+                         ;; and the value of s is map
+                         (eq map (symbol-value s))
+                         ;; then save this value in mapsym
+                         (setq mapsym s)))))
+          (insert
+           (format-message
+            "The default Emacs binding for the key %s is the command `%s'.  "
+            (key-description key)
+            db))
+          (insert "However, your customizations have "
+                  (if cb
+                      (format-message "rebound it to the command `%s'" cb)
+                    "unbound it"))
+          (insert ".")
+          (when mapsym
+            (insert "  (For the more advanced user:"
+                    (format-message
+                     " This binding is in the keymap `%s'.)" mapsym)))
+          (if (string= where "")
+              (unless (keymapp db)
+                (insert "\n\nYou can use M-x "
+                        (format "%s" db)
+                        " RET instead."))
+            (insert "\n\nWith your current key bindings"
+                    " you can use "
+                    (if (string-match-p "^the .*menus?$" where)
+                        ""
+                      "the key ")
+                    where
+                    (format-message " to get the function `%s'." db))))
+        (fill-region (point-min) (point)))))
+    (help-print-return-message)))
 
 (defconst tutorial--default-keys
   (eval-when-compile
@@ -272,71 +271,70 @@ options:
 
 (defun tutorial--detailed-help (button)
   "Give detailed help about changed keys."
-  (with-output-to-temp-buffer (help-buffer)
-    (help-setup-xref (list #'tutorial--detailed-help button)
-                     (called-interactively-p 'interactive))
-    (with-current-buffer (help-buffer)
-      (let* ((tutorial-buffer  (button-get button 'tutorial-buffer))
-             (explain-key-desc (button-get button 'explain-key-desc))
-             (changed-keys (with-current-buffer tutorial-buffer
-                             (save-excursion
-                               (goto-char (point-min))
-                               (tutorial--find-changed-keys
-                                tutorial--default-keys)))))
-        (when changed-keys
-          (insert
-           "The following key bindings used in the tutorial have been changed
+  (help-setup-xref (list #'tutorial--detailed-help button)
+                   (called-interactively-p 'interactive))
+  (with-help-window (help-buffer)
+    (let* ((tutorial-buffer  (button-get button 'tutorial-buffer))
+           (explain-key-desc (button-get button 'explain-key-desc))
+           (changed-keys (with-current-buffer tutorial-buffer
+                           (save-excursion
+                             (goto-char (point-min))
+                             (tutorial--find-changed-keys
+                              tutorial--default-keys)))))
+      (when changed-keys
+        (insert
+         "The following key bindings used in the tutorial have been changed
 from the Emacs default:\n\n" )
-          (let ((frm "   %-14s %-27s %-16s\n"))
-            (insert (format frm
-                            "Standard Key" "Command" "In Your Emacs")))
-          (dolist (tk changed-keys)
-            (let* ((def-fun     (nth 1 tk))
-                   (key         (nth 0 tk))
-                   (def-fun-txt (nth 2 tk))
-                   (where       (nth 3 tk))
-                   (remark      (nth 4 tk))
-                   (key-txt (key-description key))
-                   (key-fun (with-current-buffer tutorial-buffer (key-binding key))))
-              (unless (eq def-fun key-fun)
-                ;; Insert key binding description:
-                (when (string= key-txt explain-key-desc)
-                  (put-text-property 0 (length key-txt)
-                                     'face 'tutorial-warning-face key-txt))
-                (insert "   " key-txt " ")
-                (indent-to 18)
-                ;; Insert a link describing the old binding:
-                (insert-button def-fun-txt
-                               'value def-fun
-                               'action
-                               (lambda (button) (interactive)
-                                 (describe-function
-                                  (button-get button 'value)))
-                               'follow-link t)
-                (indent-to 45)
-                (when (listp where)
-                  (setq where "list"))
-                ;; Tell where the old binding is now:
-                (insert (format " %-16s "
-                                (if (string= "" where)
-                                    (format "M-x %s" def-fun-txt)
-                                  where)))
-                ;; Insert a link with more information, for example
-                ;; current binding and keymap or information about
-                ;; cua-mode replacements:
-                (insert-button (car remark)
-                               'action
-                               (lambda (b) (interactive)
-                                 (let ((value (button-get b 'value)))
-                                   (tutorial--describe-nonstandard-key value)))
-                               'value (cdr remark)
-                               'follow-link t)
-                (insert "\n")))))
-
-        (insert "
+        (let ((frm "   %-14s %-27s %-16s\n"))
+          (insert (format frm
+                          "Standard Key" "Command" "In Your Emacs")))
+        (dolist (tk changed-keys)
+          (let* ((def-fun     (nth 1 tk))
+                 (key         (nth 0 tk))
+                 (def-fun-txt (nth 2 tk))
+                 (where       (nth 3 tk))
+                 (remark      (nth 4 tk))
+                 (key-txt (key-description key))
+                 (key-fun (with-current-buffer tutorial-buffer (key-binding key))))
+            (unless (eq def-fun key-fun)
+              ;; Insert key binding description:
+              (when (string= key-txt explain-key-desc)
+                (put-text-property 0 (length key-txt)
+                                   'face 'tutorial-warning-face key-txt))
+              (insert "   " key-txt " ")
+              (indent-to 18)
+              ;; Insert a link describing the old binding:
+              (insert-button def-fun-txt
+                             'value def-fun
+                             'action
+                             (lambda (button) (interactive)
+                               (describe-function
+                                (button-get button 'value)))
+                             'follow-link t)
+              (indent-to 45)
+              (when (listp where)
+                (setq where "list"))
+              ;; Tell where the old binding is now:
+              (insert (format " %-16s "
+                              (if (string= "" where)
+                                  (format "M-x %s" def-fun-txt)
+                                where)))
+              ;; Insert a link with more information, for example
+              ;; current binding and keymap or information about
+              ;; cua-mode replacements:
+              (insert-button (car remark)
+                             'action
+                             (lambda (b) (interactive)
+                               (let ((value (button-get b 'value)))
+                                 (tutorial--describe-nonstandard-key value)))
+                             'value (cdr remark)
+                             'follow-link t)
+              (insert "\n")))))
+
+      (insert "
 It is OK to change key bindings, but changed bindings do not
 correspond to what the tutorial says.\n\n")
-        (help-print-return-message)))))
+      (help-print-return-message))))
 
 (defun tutorial--find-changed-keys (default-keys)
   "Find the key bindings used in the tutorial that have changed.
diff --git a/lisp/vc/diff-mode.el b/lisp/vc/diff-mode.el
index 5c0fb5fba4c..559310ff770 100644
--- a/lisp/vc/diff-mode.el
+++ b/lisp/vc/diff-mode.el
@@ -201,8 +201,9 @@ The default \"-b\" means to ignore whitespace-only changes,
 (defvar-keymap diff-mode-shared-map
   :doc "Bindings for read-only `diff-mode' buffers.
 These bindings are also available with an ESC prefix
-(i.e. a \\=`M-' prefix) in read-write `diff-mode' buffers,
-and with a `diff-minor-mode-prefix' prefix in `diff-minor-mode'.
+(i.e. a \\=`M-' prefix) in all `diff-mode' buffers, including in
+particular read-write `diff-mode' buffers, and with a
+`diff-minor-mode-prefix' prefix in `diff-minor-mode'.
 See also `diff-mode-read-only-map'."
   "n" #'diff-hunk-next
   "N" #'diff-file-next
@@ -217,14 +218,7 @@ See also `diff-mode-read-only-map'."
   "RET" #'diff-goto-source
   "<mouse-2>" #'diff-goto-source
   "o" #'diff-goto-source                ; other-window
-  "<remap> <undo>" #'undo-ignore-read-only
-
-  ;; The foregoing commands don't affect buffers beyond this one.
-  ;; The following command is the only one that has a single-letter
-  ;; binding and which affects buffers beyond this one.
-  ;; However, the following command asks for confirmation by default,
-  ;; so that seems okay.  --spwhitton
-  "u" #'diff-revert-and-kill-hunk)
+  "<remap> <undo>" #'undo-ignore-read-only)
 
 ;; Not `diff-read-only-mode-map' because there is no such mode
 ;; `diff-read-only-mode'; see comment above.
@@ -233,15 +227,28 @@ See also `diff-mode-read-only-map'."
   :doc "Additional bindings for read-only `diff-mode' buffers.
 Most of the bindings for read-only `diff-mode' buffers are in
 `diff-mode-shared-map'.  This map contains additional bindings for
-read-only `diff-mode' buffers that are *not* available with an ESC
-prefix (i.e. a \\=`M-' prefix) in read-write `diff-mode' buffers."
+read-only `diff-mode' buffers that are *not* also available with an ESC
+prefix (i.e. a \\=`M-' prefix) in read-write (nor read-only) `diff-mode'
+buffers."
   ;; We don't want the following in read-write `diff-mode' buffers
   ;; because they hide useful `M-<foo>' global bindings when editing.
   "W" #'widen
   "w" #'diff-kill-ring-save
   "A" #'diff-ediff-patch
   "r" #'diff-restrict-view
-  "R" #'diff-reverse-direction)
+  "R" #'diff-reverse-direction
+  "s" #'diff-split-hunk
+
+  ;; The foregoing commands in `diff-mode-shared-map' and
+  ;; `diff-mode-read-only-map' don't affect buffers beyond this one.
+  ;; The following command is the only one that has a single-character
+  ;; binding and which affects buffers beyond this one.  However, the
+  ;; following command asks for confirmation by default, so that seems
+  ;; okay.  --spwhitton
+  "u" #'diff-revert-and-kill-hunk
+  ;; `diff-revert-and-kill-hunk' is the `diff-mode' analogue of what '@'
+  ;; does in VC-Dir, so give it the same short binding.
+  "@" #'diff-revert-and-kill-hunk)
 
 (defvar-keymap diff-mode-map
   :doc "Keymap for `diff-mode'.  See also `diff-mode-shared-map'."
@@ -882,31 +889,19 @@ If the prefix ARG is given, restrict the view to the current file instead."
     (goto-char (point-min))
     (re-search-forward diff-hunk-header-re nil t)))
 
-(defun diff-hunk-kill ()
-  "Kill the hunk at point."
-  (interactive)
-  (if (not (diff--some-hunks-p))
-      (error "No hunks")
-    (diff-beginning-of-hunk t)
-    (let* ((hunk-bounds (diff-bounds-of-hunk))
-           (file-bounds (ignore-errors (diff-bounds-of-file)))
-           ;; If the current hunk is the only one for its file, kill the
-           ;; file header too.
-           (bounds (if (and file-bounds
-                            (progn (goto-char (car file-bounds))
-                                   (= (progn (diff-hunk-next) (point))
-                                      (car hunk-bounds)))
-                            (progn (goto-char (cadr hunk-bounds))
-                                   ;; bzr puts a newline after the last hunk.
-                                   (while (looking-at "^\n")
-                                     (forward-char 1))
-                                   (= (point) (cadr file-bounds))))
-                       file-bounds
-                     hunk-bounds))
-           (inhibit-read-only t))
-      (apply #'kill-region bounds)
-      (goto-char (car bounds))
-      (ignore-errors (diff-beginning-of-hunk t)))))
+(defun diff-hunk-kill (&optional beg end)
+  "Kill the hunk at point.
+When killing the last hunk left for a file, kill the file header too.
+Interactively, if the region is active, kill all hunks that the region
+overlaps.
+
+When called from Lisp with optional arguments BEG and END non-nil, kill
+all hunks overlapped by the region from BEG to END as though called
+interactively with an active region delimited by BEG and END."
+  (interactive "R")
+  (when (xor beg end)
+    (error "Invalid call to `diff-hunk-kill'"))
+  (diff--revert-kill-hunks beg end nil))
 
 ;; This is not `diff-kill-other-hunks' because we might need to make
 ;; copies of file headers in order to ensure the new kill ring entry
@@ -2282,6 +2277,83 @@ With a prefix argument, try to REVERSE the hunk."
   :type 'boolean
   :version "31.1")
 
+(defun diff--revert-kill-hunks (beg end revertp)
+  "Workhorse routine for killing hunks, after possibly reverting them.
+If BEG and END are nil, kill the hunk at point.
+Otherwise kill all hunks overlapped by region delimited by BEG and END.
+When killing a hunk that's the only one remaining for its file, kill the
+file header too.
+If REVERTP is non-nil, reverse-apply hunks before killing them."
+  ;; With BEG and END non-nil, we push each hunk to the kill ring
+  ;; separately.  If we want to push to the kill ring just once, we have
+  ;; to decide how to handle file headers such that the meanings of the
+  ;; hunks in the kill ring entry, considered as a whole patch, do not
+  ;; deviate too far from the meanings the hunks had in this buffer.
+  ;;
+  ;; For example, if we have a single hunk for one file followed by
+  ;; multiple hunks for another file, and we naïvely kill the single
+  ;; hunk and the first of the multiple hunks, our kill ring entry will
+  ;; be a patch applying those two hunks to the first file.  This is
+  ;; because killing the single hunk will have brought its file header
+  ;; with it, but not so killing the second hunk.  So we will have put
+  ;; together hunks that were previously for two different files.
+  ;;
+  ;; One option is to *copy* every file header that the region overlaps
+  ;; (and that we will not kill, because we are leaving other hunks for
+  ;; that file behind).  But then the text this command pushes to the
+  ;; kill ring would be different from the text it removes from the
+  ;; buffer, which would be unintuitive for an Emacs kill command.
+  ;;
+  ;; An alternative might be to have restrictions as follows:
+  ;;
+  ;;   Interactively, if the region is active, try to kill all hunks that the
+  ;;   region overlaps.  This works when either
+  ;;   - all the hunks the region overlaps are for the same file; or
+  ;;   - the last hunk the region overlaps is the last hunk for its file.
+  ;;   These restrictions are so that the text added to the kill ring does not
+  ;;   merge together hunks for different files under a single file header.
+  ;;
+  ;; We would error out if neither property is met.  When either holds,
+  ;; any file headers the region overlaps are ones we should kill.
+  (unless (diff--some-hunks-p)
+    (error "No hunks"))
+  (if beg
+      (save-excursion
+        (goto-char beg)
+        (setq beg (car (diff-bounds-of-hunk)))
+        (goto-char end)
+        (unless (looking-at diff-hunk-header-re)
+          (setq end (cadr (diff-bounds-of-hunk)))))
+    (pcase-setq `(,beg ,end) (diff-bounds-of-hunk)))
+  (when (or (not revertp) (null (diff-apply-buffer beg end t)))
+    (goto-char end)
+    (when-let* ((pos (diff--at-diff-header-p)))
+      (goto-char pos))
+    (setq beg (copy-marker beg) end (point-marker))
+    (unwind-protect
+        (cl-loop initially (goto-char beg)
+                 with inhibit-read-only = t
+                 for (hunk-beg hunk-end) = (diff-bounds-of-hunk)
+                 for file-bounds = (ignore-errors (diff-bounds-of-file))
+                 for (file-beg file-end) = file-bounds
+                 if (and file-bounds
+                         (progn
+                           (goto-char file-beg)
+                           (diff-hunk-next)
+                           (eq (point) hunk-beg))
+                         (progn
+                           (goto-char hunk-end)
+                           ;; bzr puts a newline after the last hunk.
+                           (while (looking-at "^\n") (forward-char 1))
+                           (eq (point) file-end)))
+                 do (kill-region file-beg file-end) (goto-char file-beg)
+                 else do (kill-region hunk-beg hunk-end) (goto-char hunk-beg)
+                 do (ignore-errors (diff-beginning-of-hunk t))
+                 until (or (< (point) (marker-position beg))
+                           (eql (point) (marker-position end))))
+      (set-marker beg nil)
+      (set-marker end nil))))
+
 (defun diff-revert-and-kill-hunk (&optional beg end)
   "Reverse-apply and then kill the hunk at point.  Save changed buffer.
 Interactively, if the region is active, reverse-apply and kill all
@@ -2307,27 +2379,7 @@ BEG and END."
     (error "Invalid call to `diff-revert-and-kill-hunk'"))
   (when (or (not diff-ask-before-revert-and-kill-hunk)
             (y-or-n-p "Really reverse-apply and kill hunk(s)?"))
-    (if beg
-        (save-excursion
-          (goto-char beg)
-          (setq beg (car (diff-bounds-of-hunk)))
-          (goto-char end)
-          (unless (looking-at diff-hunk-header-re)
-            (setq end (cadr (diff-bounds-of-hunk)))))
-      (pcase-setq `(,beg ,end) (diff-bounds-of-hunk)))
-    (when (null (diff-apply-buffer beg end t))
-      ;; Use `diff-hunk-kill' because it properly handles file headers.
-      (goto-char end)
-      (when-let* ((pos (diff--at-diff-header-p)))
-        (goto-char pos))
-      (setq beg (copy-marker beg) end (point-marker))
-      (unwind-protect
-          (cl-loop initially (goto-char beg)
-                   do (diff-hunk-kill)
-                   until (or (< (point) (marker-position beg))
-                             (eql (point) (marker-position end))))
-        (set-marker beg nil)
-        (set-marker end nil)))))
+    (diff--revert-kill-hunks beg end t)))
 
 (defun diff-apply-buffer (&optional beg end reverse test-or-no-save)
   "Apply the diff in the entire diff buffer.
diff --git a/lisp/vc/vc-dispatcher.el b/lisp/vc/vc-dispatcher.el
index dc17b582ed7..2015e7540ae 100644
--- a/lisp/vc/vc-dispatcher.el
+++ b/lisp/vc/vc-dispatcher.el
@@ -384,6 +384,9 @@ the man pages for \"torsocks\" for more details about Tor."
   :version "27.1"
   :group 'vc)
 
+(defvar vc-user-edit-command-history nil
+  "Name of minibuffer history variable for `vc-user-edit-command'.")
+
 (defun vc-user-edit-command (command file-or-list flags)
   "Prompt the user to edit VC command COMMAND and FLAGS.
 Intended to be used as the value of `vc-filter-command-function'."
@@ -398,7 +401,8 @@ Intended to be used as the value of `vc-filter-command-function'."
                             (cons command (remq nil (if files-separator-p
                                                         (butlast flags)
                                                       flags))))
-                           " ")))))
+                           " ")
+                   vc-user-edit-command-history))))
     (list (car edited) file-or-list
           (nconc (cdr edited) (and files-separator-p '("--"))))))
 
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index 73db9c0f181..5e51b28fb37 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -772,70 +772,91 @@ or an empty string if none."
   (vc-git--out-match '("symbolic-ref" "HEAD")
                      "^\\(refs/heads/\\)?\\(.+\\)$" 2))
 
+(defun vc-git--branch-remotes ()
+  "Return alist of configured remote branches for current branch.
+If there is a configured upstream, return the remote-tracking branch
+with key `upstream'.  If there is a distinct configured push remote,
+return the remote-tracking branch there with key `push'.
+A configured push remote that's just the same as the upstream remote is
+ignored because that means we're not actually in a triangular workflow."
+  ;; Possibly we could simplify this using @{push}, but that may involve
+  ;; an unwanted dependency on the setting of push.default.
+  (cl-flet ((get (key)
+              (string-trim-right (vc-git--out-str "config" key))))
+    (let* ((branch (vc-git-working-branch))
+           (pull (get (format "branch.%s.remote" branch)))
+           (merge (string-remove-prefix "refs/heads/"
+                                        (get (format "branch.%s.merge"
+                                                     branch))))
+           (push (get (format "branch.%s.pushRemote" branch)))
+           (push (if (string-empty-p push)
+                     (get "remote.pushDefault")
+                   push))
+           (alist (and (not (string-empty-p pull))
+                       (not (string-empty-p merge))
+                       `((upstream . ,(format "%s/%s" pull merge))))))
+      (if (or (string-empty-p push) (equal push pull))
+          alist
+        (cl-acons 'push (format "%s/%s" push branch) alist)))))
+
 (defun vc-git-trunk-or-topic-p ()
   "Return `topic' if branch has distinct pull and push remotes, else nil.
 This is able to identify topic branches for certain forge workflows."
-  (let* ((branch (vc-git-working-branch))
-         (merge (string-trim-right
-                 (vc-git--out-str "config" (format "branch.%s.remote"
-                                                   branch))))
-         (push (string-trim-right
-                (vc-git--out-str "config" (format "branch.%s.pushRemote"
-                                                  branch))))
-         (push (if (string-empty-p push)
-                   (string-trim-right
-                    (vc-git--out-str "config" "remote.pushDefault"))
-                 push)))
-    (and (plusp (length merge))
-         (plusp (length push))
-         (not (equal merge push))
-         'topic)))
+  (let ((remotes (vc-git--branch-remotes)))
+    (and (assq 'upstream remotes) (assq 'push remotes) 'topic)))
 
 (defun vc-git-topic-outgoing-base ()
   "Return the outgoing base for the current branch as a string.
 This works by considering the current branch as a topic branch
 (whether or not it actually is).
-Requires that the corresponding trunk exists as a local branch.
-
-The algorithm employed is as follows.  Find all merge bases between the
-current branch and other local branches.  Each of these is a commit on
-the current branch.  Use `git merge-base --independent' on them all to
-find the topologically most recent.  Take the branch for which that
-commit is a merge base with the current branch to be the branch into
-which the current branch will eventually be merged.  Find its upstream.
-(If there is more than one branch whose merge base with the current
-branch is that same topologically most recent commit, try them
-one-by-one, accepting the first that has an upstream.)"
-  (cl-flet ((get-line () (buffer-substring (point) (pos-eol))))
-    (let* ((branches (vc-git-branches))
-           (current (pop branches))
-           merge-bases)
-      (with-temp-buffer
-        (dolist (branch branches)
-          (erase-buffer)
-          (when (vc-git--out-ok "merge-base" "--all" branch current)
-            (goto-char (point-min))
-            (while (not (eobp))
-              (push branch
-                    (alist-get (get-line) merge-bases nil nil #'equal))
-              (forward-line 1))))
-        (erase-buffer)
-        (unless (apply #'vc-git--out-ok "merge-base" "--independent"
-                       (mapcar #'car merge-bases))
-          (error "`git merge-base --independent' failed"))
-        ;; If 'git merge-base --independent' printed more than one line,
-        ;; just pick the first.
-        (goto-char (point-min))
-        (catch 'ret
-          (dolist (target (cdr (assoc (get-line) merge-bases)))
+
+If there is a distinct push remote for this branch, assume the target
+for outstanding changes is the tracking branch, and return that.
+
+Otherwise, fall back to the following algorithm, which requires that the
+corresponding trunk exists as a local branch.  Find all merge bases
+between the current branch and other local branches.  Each of these is a
+commit on the current branch.  Use `git merge-base --independent' on
+them all to find the topologically most recent.  Take the branch for
+which that commit is a merge base with the current branch to be the
+branch into which the current branch will eventually be merged.  Find
+its upstream.  (If there is more than one branch whose merge base with
+the current branch is that same topologically most recent commit, try
+them one-by-one, accepting the first that has an upstream.)"
+  (if-let* ((remotes (vc-git--branch-remotes))
+            (_ (assq 'push remotes))
+            (upstream (assq 'upstream remotes)))
+      (cdr upstream)
+    (cl-flet ((get-line () (buffer-substring (point) (pos-eol))))
+      (let* ((branches (vc-git-branches))
+             (current (pop branches))
+             merge-bases)
+        (with-temp-buffer
+          (dolist (branch branches)
             (erase-buffer)
-            (when (vc-git--out-ok "for-each-ref"
-                                  "--format=%(upstream:short)"
-                                  (concat "refs/heads/" target))
+            (when (vc-git--out-ok "merge-base" "--all" branch current)
               (goto-char (point-min))
-              (let ((outgoing-base (get-line)))
-                (unless (string-empty-p outgoing-base)
-                  (throw 'ret outgoing-base))))))))))
+              (while (not (eobp))
+                (push branch (alist-get (get-line) merge-bases
+                                        nil nil #'equal))
+                (forward-line 1))))
+          (erase-buffer)
+          (unless (apply #'vc-git--out-ok "merge-base" "--independent"
+                         (mapcar #'car merge-bases))
+            (error "`git merge-base --independent' failed"))
+          ;; If 'git merge-base --independent' printed more than one
+          ;; line, just pick the first.
+          (goto-char (point-min))
+          (catch 'ret
+            (dolist (target (cdr (assoc (get-line) merge-bases)))
+              (erase-buffer)
+              (when (vc-git--out-ok "for-each-ref"
+                                    "--format=%(upstream:short)"
+                                    (concat "refs/heads/" target))
+                (goto-char (point-min))
+                (let ((outgoing-base (get-line)))
+                  (unless (string-empty-p outgoing-base)
+                    (throw 'ret outgoing-base)))))))))))
 
 (defun vc-git-dir--branch-headers ()
   "Return headers for branch-related information."
@@ -1451,7 +1472,9 @@ line of the commit message in an entry with key \"Subject\"."
                  (if (eq system-type 'windows-nt)
                      locale-coding-system
                    coding-system-for-write)))
-            (vc-git--call input-file t "mailinfo" msg-file patch-file))
+            (vc-git--call input-file t "mailinfo"
+                          (file-local-name msg-file)
+                          (file-local-name patch-file)))
           (goto-char (point-min))
           ;; git-mailinfo joins up any header continuation lines for us.
           (while (re-search-forward "^\\([^\t\n\s:]+\\):\\(.*\\)$" nil t)
@@ -1591,7 +1614,9 @@ If PROMPT is non-nil, prompt for the Git command to run."
          (vc-filter-command-function
           (if prompt
               (lambda (&rest args)
-                (cl-destructuring-bind (&whole args git _ flags)
+                (cl-destructuring-bind
+                    (&whole args git _ flags
+                            &aux (vc-user-edit-command-history 'vc-git-history))
                     (apply #'vc-user-edit-command args)
                   (setq git-program git
                         command (car flags)
@@ -2567,9 +2592,9 @@ This command shares argument histories with \\[rgrep] and \\[grep]."
   ;; In *vc-dir*, if nothing is marked, act on the whole working tree
   ;; regardless of the position of point.  This preserves historical
   ;; behavior and is also probably more useful.
-  (if (derived-mode-p 'vc-dir-mode)
-      (vc-dir-marked-files)
-    (cadr (vc-deduce-fileset))))
+  (mapcar #'file-relative-name (if (derived-mode-p 'vc-dir-mode)
+                                   (vc-dir-marked-files)
+                                 (cadr (vc-deduce-fileset)))))
 
 (defun vc-git-stash (name)
   "Create a stash named NAME.
diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index 770906ff6cc..88324a2a444 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -3330,15 +3330,13 @@ to which `vc-push' would push as UPSTREAM-LOCATION, unconditionally.
 (This is passed when the user invokes an outgoing base command with a
  \\`C-u C-u' prefix argument; see `vc--maybe-read-outgoing-base'.)
 REFRESH is passed on to `vc--incoming-revision'."
-  (if-let* ((incoming
-             (vc--incoming-revision backend
-                                    (pcase upstream-location
-                                      ('t nil)
-                                      ('nil (vc--outgoing-base backend))
-                                      (_ upstream-location))
-                                    refresh)))
-      (vc-call-backend backend 'mergebase incoming)
-    (user-error "No incoming revision -- local-only branch?")))
+  (vc-call-backend backend 'mergebase
+                   (vc--incoming-revision backend
+                                          (pcase upstream-location
+                                            ('t nil)
+                                            ('nil (vc--outgoing-base backend))
+                                            (_ upstream-location))
+                                          refresh)))
 
 ;;;###autoload
 (defun vc-root-diff-outgoing-base (&optional upstream-location)
@@ -3349,7 +3347,9 @@ Uncommitted changes are included in the diff.
 
 When unspecified, UPSTREAM-LOCATION is the outgoing base.
 For a trunk branch this is always the place \\[vc-push] would push to.
-For a topic branch, query the backend for an appropriate outgoing base.
+For a topic branch, see whether the branch matches one of
+`vc-trunk-branch-regexps' or `vc-topic-branch-regexps', or else query
+the backend for an appropriate outgoing base.
 See `vc-trunk-branch-regexps' and `vc-topic-branch-regexps' regarding
 the difference between trunk and topic branches.
 
@@ -3377,7 +3377,9 @@ Uncommitted changes are included in the diff.
 
 When unspecified, UPSTREAM-LOCATION is the outgoing base.
 For a trunk branch this is always the place \\[vc-push] would push to.
-For a topic branch, query the backend for an appropriate outgoing base.
+For a topic branch, see whether the branch matches one of
+`vc-trunk-branch-regexps' or `vc-topic-branch-regexps', or else query
+the backend for an appropriate outgoing base.
 See `vc-trunk-branch-regexps' and `vc-topic-branch-regexps' regarding
 the difference between trunk and topic branches.
 
@@ -3411,7 +3413,9 @@ working revision and UPSTREAM-LOCATION.
 
 When unspecified, UPSTREAM-LOCATION is the outgoing base.
 For a trunk branch this is always the place \\[vc-push] would push to.
-For a topic branch, query the backend for an appropriate outgoing base.
+For a topic branch, see whether the branch matches one of
+`vc-trunk-branch-regexps' or `vc-topic-branch-regexps', or else query
+the backend for an appropriate outgoing base.
 See `vc-trunk-branch-regexps' and `vc-topic-branch-regexps' regarding
 the difference between trunk and topic branches.
 
@@ -3443,7 +3447,9 @@ working revision and UPSTREAM-LOCATION.
 
 When unspecified, UPSTREAM-LOCATION is the outgoing base.
 For a trunk branch this is always the place \\[vc-push] would push to.
-For a topic branch, query the backend for an appropriate outgoing base.
+For a topic branch, see whether the branch matches one of
+`vc-trunk-branch-regexps' or `vc-topic-branch-regexps', or else query
+the backend for an appropriate outgoing base.
 See `vc-trunk-branch-regexps' and `vc-topic-branch-regexps' regarding
 the difference between trunk and topic branches.
 
@@ -4435,20 +4441,23 @@ BACKEND is the VC backend."
   ;; Do store `nil', before signaling an error, if there is no incoming
   ;; revision, because that's also something that can be slow to
   ;; determine and so should be remembered.
-  (if-let* ((_ (not refresh))
-            (record (assoc upstream-location
-                           (vc--repo-getprop backend 'vc-incoming-revision))))
-      (cdr record)
-    (let ((res (vc-call-backend backend 'incoming-revision
-                                upstream-location refresh)))
-      (if-let* ((alist (vc--repo-getprop backend 'vc-incoming-revision)))
-          (setf (alist-get upstream-location alist nil nil #'equal)
-                res)
-        (vc--repo-setprop backend
-                          'vc-incoming-revision
-                          `((,upstream-location . ,res))))
-      (or res
-          (user-error "No incoming revision -- local-only branch?")))))
+  (or (if-let* ((_ (not refresh))
+                (record (assoc upstream-location
+                               (vc--repo-getprop backend
+                                                 'vc-incoming-revision))))
+          (cdr record)
+        (let ((res (vc-call-backend backend 'incoming-revision
+                                    upstream-location refresh)))
+          (if-let* ((alist (vc--repo-getprop backend
+                                             'vc-incoming-revision)))
+              (setf (alist-get upstream-location alist
+                               nil nil #'equal)
+                    res)
+            (vc--repo-setprop backend
+                              'vc-incoming-revision
+                              `((,upstream-location . ,res))))
+          res))
+      (user-error "No incoming revision -- local-only branch?")))
 
 ;;;###autoload
 (defun vc-root-log-incoming (&optional upstream-location)
@@ -5017,6 +5026,9 @@ log entries should be gathered."
 
 (defvar vc-filter-command-function)
 
+(defvar vc-edit-next-command-history nil
+  "Minibuffer history for `vc-edit-next-command'.")
+
 ;;;###autoload
 (defun vc-edit-next-command ()
   "Request editing the next VC shell command before execution.
@@ -5040,7 +5052,8 @@ immediately after this one."
     (add-hook 'prefix-command-echo-keystrokes-functions echofun)
     (setq vc-filter-command-function
           (lambda (&rest args)
-            (apply #'vc-user-edit-command (apply old args))))))
+            (let ((vc-user-edit-command-history 'vc-edit-next-command-history))
+              (apply #'vc-user-edit-command (apply old args)))))))
 
 ;; This is used in .dir-locals.el in the Emacs source tree.
 ;;;###autoload (put 'vc-prepare-patches-separately 'safe-local-variable 'booleanp)
diff --git a/lisp/wid-edit.el b/lisp/wid-edit.el
index 6d576a10b73..353d546fce4 100644
--- a/lisp/wid-edit.el
+++ b/lisp/wid-edit.el
@@ -1334,10 +1334,10 @@ POS defaults to the value of (point).  If user option
 This is much faster.")
 
 (defun widget-move (arg &optional suppress-echo)
-  "Move point to the ARG next field or button.
+  "Move point to the ARGth next field or button.
 ARG may be negative to move backward.
-When the second optional argument is non-nil,
-nothing is shown in the echo area."
+If the optional argument SUPPRESS-ECHO is non-nil, suppress showing
+in the echo area the help-echo, if any, for the final position."
   (let* ((wrapped 0)
          (number arg)
          (fwd (> arg 0))                ; widget-forward is caller.
@@ -1384,19 +1384,19 @@ nothing is shown in the echo area."
   (run-hooks 'widget-move-hook))
 
 (defun widget-forward (arg &optional suppress-echo)
-  "Move point to the next field or button.
-With optional ARG, move across that many fields.
-When the second optional argument is non-nil,
-nothing is shown in the echo area."
+  "Move point forward across ARG fields or buttons.
+Interactively, ARG is the prefix numeric argument and defaults to 1.
+If the optional argument SUPPRESS-ECHO is non-nil, suppress showing
+in the echo area the help-echo, if any, for the final position."
   (interactive "p")
   (run-hooks 'widget-forward-hook)
   (widget-move arg suppress-echo))
 
 (defun widget-backward (arg &optional suppress-echo)
-  "Move point to the previous field or button.
-With optional ARG, move across that many fields.
-When the second optional argument is non-nil,
-nothing is shown in the echo area."
+  "Move point back across ARG fields or buttons.
+Interactively, ARG is the prefix numeric argument and defaults to 1.
+If the optional argument SUPPRESS-ECHO is non-nil, suppress showing
+in the echo area the help-echo, if any, for the final position."
   (interactive "p")
   (run-hooks 'widget-backward-hook)
   (widget-move (- arg) suppress-echo))
diff --git a/lisp/window.el b/lisp/window.el
index 3a1ebd16fa6..2327ffcd5f2 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7586,7 +7586,7 @@ strategy."
 
 (defun window--frame-landscape-p (&optional frame)
   "Non-nil if FRAME is wider than it is tall.
-This means actually wider on the screen, not character-wise.
+This means actually wider on the screen, not wider character-wise.
 On text frames, use the heuristic that characters are roughtly twice as
 tall as they are wide."
   (if (display-graphic-p frame)