Re: [patch] improved: add TTL as defcustom to ox-icalendar

[Detlef Steuer <steuer@hsu-hh.de>]

[-- Attachment #1: Type: text/plain, Size: 294 bytes --]

 
> 
> May you please also take into account the amendments I made in my
> patch I attached earlier? For example, you still appear to use
> time-to-live and "time to life" inconsistently herein.
> 

Oh, sorry, something went terribly wrong on my end.

Next try.

Thx for your patience!

Detlef

[-- Attachment #2: 0001-lisp-ox-icalendar.el-Add-defcustom-org-icalendar-ttl.patch --]
[-- Type: text/x-patch, Size: 5910 bytes --]

From 43cd5b0ce1fd591a92bb40d52f3dfb3ca5491930 Mon Sep 17 00:00:00 2001
From: Detlef Steuer <steuer@hsu-hh.de>
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