From 24a6bc78c74d16a6aa7dbd081be9f626b20bbf20 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 time-to-live functionality to ox-icalendar This commit adds functionality for ox-icalendar to set X-PUBLISHED-TTL in the exported ICS, which advises a subscriber to the exported ICS file to reload after the given time interval. * lisp/ox-icalendar.el (org-icalendar-ttl): New option to set X-PUBLISHED-TTL in exported ICS (icalendar): Add ICAL-TTL export keyword (org-icalendar--vcalendar): Add argument for TTL (org-icalendar-template, org-icalendar-export-current-agenda, org-icalendar--combine-files): Pass TTL to `org-icalendar--vcalendar' Co-authored-by: Ihor Radchenko Co-authored-by: Jack Kamm --- doc/org-manual.org | 9 +++++++++ etc/ORG-NEWS | 17 ++++++++++++++++ lisp/ox-icalendar.el | 47 ++++++++++++++++++++++++++++++++++++++------ 3 files changed, 67 insertions(+), 6 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 7e5ac0673..8fe79ee45 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -16369,6 +16369,15 @@ information. The iCalendar standard defines three visibility classes: The server should treat unknown class properties the same as =PRIVATE=. +#+cindex: @samp{ICAL-TTL}, keyword +#+vindex: org-icalendar-ttl +The exported iCalendar file can advise clients how often to check for +updates. This duration can be set globally with the +~org-icalendar-ttl~ variable, or on a per-document basis with the +=ICAL-TTL= keyword. This option should be set using the iCalendar +notation for time durations; consult the docstring of +~org-icalendar-ttl~ for more details. + Exporting to iCalendar format depends in large part on the capabilities of the destination application. Some are more lenient than others. Consult the Org mode FAQ for advice on specific diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 1bf7eb5b4..5a93788e9 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -424,6 +424,23 @@ The change is breaking when ~org-use-property-inheritance~ is set to ~t~. The =TEST= parameter is better served by Emacs debugging tools. ** 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. + *** The default value of ~org-attach-store-link-p~ is now ~attached~ Now, after attaching a file, =[[attach:...]]= link to the attached file diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el index cb416a68f..584c78fcf 100644 --- a/lisp/ox-icalendar.el +++ b/lisp/ox-icalendar.el @@ -331,6 +331,32 @@ (defcustom org-icalendar-date-time-format ":%Y%m%dT%H%M%S" (const :tag "Universal time" ":%Y%m%dT%H%M%SZ") (string :tag "Explicit format"))) +(defcustom org-icalendar-ttl nil + "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 +client is Nextcloud calendar, which respects the setting of +X-PUBLISHED-TTL in ICS files. 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 possible specifications of this +option. For example, \"PT1H\" stands for 1 hour and +\"PT0H27M34S\" stands for 0 hours, 27 minutes and 34 seconds. + +The default value is nil, which means no such option is set in +the ICS file. This option can also be set on a per-document basis +with the ICAL-TTL export keyword." + :group 'org-export-icalendar + :type '(choice + (const :tag "No refresh period" nil) + (const :tag "One hour" "PT1H") + (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. This hook is run with the name of the file as argument. A good @@ -368,7 +394,8 @@ (org-export-define-derived-backend 'icalendar 'ascii (:icalendar-use-deadline nil nil org-icalendar-use-deadline) (:icalendar-use-scheduled nil nil org-icalendar-use-scheduled) (:icalendar-scheduled-summary-prefix nil nil org-icalendar-scheduled-summary-prefix) - (:icalendar-deadline-summary-prefix nil nil org-icalendar-deadline-summary-prefix)) + (:icalendar-deadline-summary-prefix nil nil org-icalendar-deadline-summary-prefix) + (:icalendar-ttl "ICAL-TTL" nil org-icalendar-ttl)) :filters-alist '((:filter-headline . org-icalendar-clear-blank-lines)) :menu-entry @@ -1021,25 +1048,30 @@ (defun org-icalendar-template (contents info) (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, time to live (refresh period) and +the other components included." (org-icalendar-fold-string (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" +X-WR-CALDESC:%s\n" (org-icalendar-cleanup-string name) (org-icalendar-cleanup-string owner) (org-icalendar-cleanup-string tz) (org-icalendar-cleanup-string description)) + (when ttl (format "X-PUBLISHED-TTL:%s\n" + (org-icalendar-cleanup-string ttl))) + "CALSCALE:GREGORIAN\n" contents "END:VCALENDAR\n"))) @@ -1167,6 +1199,7 @@ (defun org-icalendar-export-current-agenda (file) user-full-name (or (org-string-nw-p org-icalendar-timezone) (format-time-string "%Z")) org-icalendar-combined-description + org-icalendar-ttl contents))) (org-icalendar--post-process-file file))) @@ -1191,6 +1224,8 @@ (defun org-icalendar--combine-files (&rest files) (format-time-string "%Z")) ;; Description. org-icalendar-combined-description + ;; TTL (Refresh period) + org-icalendar-ttl ;; Contents. (concat ;; Agenda contents. -- 2.43.0