From 43cd5b0ce1fd591a92bb40d52f3dfb3ca5491930 Mon Sep 17 00:00:00 2001 From: Detlef Steuer Date: Sat, 4 Feb 2023 21:40:09 +0100 Subject: [PATCH] lisp/ox-icalendar.el: Add defcustom `org-icalendar-ttl' to ox-icalendar * lisp/ox-icalendar.el: The option `org-icalendar-ttl' allows to advise a subscriber to the exported ICS file to reload after the given time interval. Default for `org-icalendar-ttl' is nil. In that case the setting will not be used in the exported ICS file. The option may also be set using the ICAL-TTL keyword. --- etc/ORG-NEWS | 17 ++++++++++++++ lisp/ox-icalendar.el | 53 +++++++++++++++++++++++++++++++++++--------- 2 files changed, 60 insertions(+), 10 deletions(-) diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index c5e9cd568..52c1bae93 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -24,6 +24,23 @@ consider [[https://gitlab.com/jackkamm/ob-python-mode-mode][ob-python-mode-mode] has been ported to. ** New and changed options +*** New custom setting ~org-icalendar-ttl~ for the ~ox-icalendar~ backend + +The option ~org-icalendar-ttl~ allows to advise a subscriber to the +exported ~.ics~ file to reload after the given time interval. + +This is useful i.e. if a calendar server subscribes to your exported +file and that file is updated regularly. + +See IETF RFC 5545, Section 3.3.6 Duration, and +https://en.wikipedia.org/wiki/ICalendar#Other_component_types for +details. + +Default for ~org-icalendar-ttl~ is nil. In that case the setting will +not be used in the exported ICS file. + +The option may also be set using the ICAL-TTL keyword. + *** ~org-clock-x11idle-program-name~ now defaults to =xprintidle=, when available When =xprintidle= executable is available at =org-clock= load time, it diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el index 81a77a770..9651c74a0 100644 --- a/lisp/ox-icalendar.el +++ b/lisp/ox-icalendar.el @@ -295,7 +295,31 @@ Interesting value are: (const :tag "Local time" ":%Y%m%dT%H%M%S") (const :tag "Explicit local time" ";TZID=%Z:%Y%m%dT%H%M%S") (const :tag "Universal time" ":%Y%m%dT%H%M%SZ") - (string :tag "Explicit format"))) + (string :tag "Other"))) + +(defcustom org-icalendar-ttl "PT1H" + "The time-to-live for the exported calendar. +Subscribing clients to the exported ics file can derive the time interval +to read the file again from the server. One example of such a client is +the nextcloud calendar, which respects the setting of +X-PUBLISHED-TTL in an ICS file. Setting org-icalendar-ttl to \"PT1H\" +would advise a server to reload the file every hour. + +See https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html +for a complete description of possiblee values of this option. For example +\"PT1H\" stands for 1 hour, \"PT0H27M34S\" stands for 0 hours, 27 minutes +and 34 seconds. Default value is nil, which means no such option +is set in the ICS file. + +This option can also be set with the ICAL-TTL keyword." + :group 'org-export-icalendar + :type '(choice + (const :tag "no refresh" nil) + (const :tag "One day" "PT1D") + (const :tag "One week" "PT7D") + (string :tag "Other")) + :package-version '(Org . "9.7")) + (defvar org-icalendar-after-save-hook nil "Hook run after an iCalendar file has been saved. @@ -333,6 +357,7 @@ re-read the iCalendar file.") (:icalendar-timezone nil nil org-icalendar-timezone) (:icalendar-use-deadline nil nil org-icalendar-use-deadline) (:icalendar-use-scheduled nil nil org-icalendar-use-scheduled) + (:icalendar-ttl "ICAL-TTL" nil org-icalendar-ttl) (:icalendar-scheduled-summary-prefix nil nil org-icalendar-scheduled-summary-prefix) (:icalendar-deadline-summary-prefix nil nil org-icalendar-deadline-summary-prefix)) :filters-alist @@ -872,24 +897,29 @@ as a communication channel." (or (org-string-nw-p org-icalendar-timezone) (format-time-string "%Z")) ;; Description. (org-export-data (plist-get info :title) info) + ;; TTL + (plist-get info :icalendar-ttl) contents)) -(defun org-icalendar--vcalendar (name owner tz description contents) +(defun org-icalendar--vcalendar (name owner tz description ttl contents) "Create a VCALENDAR component. -NAME, OWNER, TZ, DESCRIPTION and CONTENTS are all strings giving, +NAME, OWNER, TZ, DESCRIPTION, TTL and CONTENTS are all strings giving, respectively, the name of the calendar, its owner, the timezone -used, a short description and the other components included." +used, a short description, the time-to-live resp. refresh period and +the other components included." (concat (format "BEGIN:VCALENDAR VERSION:2.0 X-WR-CALNAME:%s PRODID:-//%s//Emacs with Org mode//EN X-WR-TIMEZONE:%s -X-WR-CALDESC:%s -CALSCALE:GREGORIAN\n" - (org-icalendar-cleanup-string name) - (org-icalendar-cleanup-string owner) - (org-icalendar-cleanup-string tz) - (org-icalendar-cleanup-string description)) +X-WR-CALDESC:%s\n" +(when ttl "X-PUBLISHED-TTL:%s\n") +"CALSCALE:GREGORIAN\n") + (org-icalendar-cleanup-string name) + (org-icalendar-cleanup-string owner) + (org-icalendar-cleanup-string tz) + (org-icalendar-cleanup-string description) + (org-icalendar-cleanup-string ttl)) contents "END:VCALENDAR\n")) @@ -1018,6 +1048,7 @@ This function assumes major mode for current buffer is user-full-name (or (org-string-nw-p org-icalendar-timezone) (format-time-string "%Z")) org-icalendar-combined-description + org-icalendar-ttl contents))) (run-hook-with-args 'org-icalendar-after-save-hook file))) @@ -1042,6 +1073,8 @@ FILES is a list of files to build the calendar from." (format-time-string "%Z")) ;; Description. org-icalendar-combined-description + ;; TTL (Refresh period) + org-icalendar-ttl ;; Contents. (concat ;; Agenda contents. -- 2.39.1