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

[Jack Kamm]

Ihor Radchenko <yantar92@posteo.net> writes:

> This does not look right. Did you try to export anything with this patch
> applied? You are passing multiple string arguments to `format'.
>
> Finally, I think that we can document the new keyword in the manual.  

I've updated the patch so that it applies cleanly onto the latest main,
and also fixed a few issues including the ones Ihor pointed out above.

Let me know if there are any issues -- otherwise I'll apply it to main
in the near future.

>From 24a6bc78c74d16a6aa7dbd081be9f626b20bbf20 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 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 <yantar92@posteo.net>
Co-authored-by: Jack Kamm <jackkamm@gmail.com>
---
 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