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

[Ihor Radchenko]

Detlef Steuer <steuer@hsu-hh.de> writes:

> I tried to follow your advice to improve the patch accordingly.
> New version attached.

I have amended your patch fixing some of the spelling issues and
indentation. See the attached. Note that I used "time to live"
consistently instead of "time to life". The former is the right
abbreviation meaning, AFAIU
(https://www.cloudflare.com/learning/cdn/glossary/time-to-live-ttl/)

I also have a more general comment.

The patch only allows to the TTL globally for all the calendars.
However, it would make sense to specify TTL on per-file basis. WDYT?

>From 04174d53b84e32a2a73eb19ce9a1e12dff69d071 Mon Sep 17 00:00:00 2001
Message-Id: 
<04174d53b84e32a2a73eb19ce9a1e12dff69d071.1673948403.git.yantar92@posteo.net>
From: Detlef Steuer <steuer@hsu-hh.de>
Date: Mon, 16 Jan 2023 23:27:33 +0100
Subject: [PATCH v2] lisp/ox-icalendar.el: Add customize option
 `org-icalendar-ttl'

* ox-icalendar.el: New option `org-icalendar-ttl' to add en entry
for the X-PUBLISHED-TTL option to ox-icalendar.  Default value is nil,
what means no such entry is exported.  If non nil the value must be
formated according to
https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html.
---
 etc/ORG-NEWS         | 15 +++++++++++
 lisp/ox-icalendar.el | 62 ++++++++++++++++++++++++++++++++++----------
 2 files changed, 64 insertions(+), 13 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index c5d9bdf6e..fd44198ab 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -13,6 +13,21 @@ Please send Org bug reports to mailto:emacs-orgmode@gnu.org.
 
 * Version 9.7 (not released yet)
 ** New 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 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.
+
 *** New options for the "csl" citation export processor's LaTeX output
 
 The ~org-cite-csl-latex-label-separator~ and
diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el
index 81a77a770..081a0a516 100644
--- a/lisp/ox-icalendar.el
+++ b/lisp/ox-icalendar.el
@@ -297,6 +297,30 @@ (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."
+  :group 'org-export-icalendar
+  :type '(choice
+          (const :tag "No refresh period" 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.
 This hook is run with the name of the file as argument.  A good
@@ -334,7 +358,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 nil nil org-icalendar-ttl))
   :filters-alist
   '((:filter-headline . org-icalendar-clear-blank-lines))
   :menu-entry
@@ -872,26 +897,34 @@ (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."
-  (concat (format "BEGIN:VCALENDAR
+used, a short description, time to live resp. refresh period and 
+the other components included."
+  (concat
+   (format
+    (concat
+     "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))
-         contents
-         "END:VCALENDAR\n"))
+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 +1051,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)))
     (run-hook-with-args 'org-icalendar-after-save-hook file)))
 
@@ -1042,6 +1076,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.39.0

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>