[elpa] externals/org da2b61b09e: lisp/ox-icalendar.el: Add time-to-live functionality to ox-icalendar

[ELPA Syncer]

branch: externals/org
commit da2b61b09e1eff957e6b2560a2f9c8509de6beac
Author: Detlef Steuer <steuer@hsu-hh.de>
Commit: Jack Kamm <jackkamm@gmail.com>

    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 73e9b7d879..ffb025c932 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 f9c916a9dd..f4e98d78bd 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -435,6 +435,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 cb416a68f2..584c78fcf8 100644
--- a/lisp/ox-icalendar.el
+++ b/lisp/ox-icalendar.el
@@ -331,6 +331,32 @@ Interesting value are:
          (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 @@ re-read the iCalendar file.")
     (: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 @@ 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, 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 @@ 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)))
     (org-icalendar--post-process-file file)))
 
@@ -1191,6 +1224,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.