[patch] add TTL as defcustom to ox-icalendar

[patch] add TTL as defcustom to ox-icalendar

[Detlef Steuer]

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

This is my first try ever to contribute anything in elisp.

The nextcloud calendar app supports the X-PUBLISHED-TTL 
option if subscribing to an ics file. Nextcloud defaults
to a TTL of 1 week, what is much too long for my use case.

When exporting to such a file from org I did not find any way
to set this option during export. So I tried to add a defcustom
in ox-icalendar.el.

The default TTL in this patch is 1 hour.

I think this qualifies as an tiny patch, as it is mostly a docstring
:-), in case anybody finds this an useful addition.

The patch is relative to 9.5.1 from elpa.

All comments very much appreciated.

And a happy new year to you all
Detlef

[-- Attachment #2: patch.ttl --]
[-- Type: text/turtle, Size: 1619 bytes --]

267a268,280
> (defcustom org-icalendar-ttl "PT1H"
>   "The time to life 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, i.e. X-PUBLISHED-TTL:PT1H .
> 
> See https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html
> for a complete description of possiblee values of this option. I.e.
> PT1H stands for 1 hour, PT0H27M34S for 0 hours, 27 minutes and 34 seconds."
>   :group 'org-export-icalendar
>   :type 'string)
> 
303c316,317
<     (:icalendar-use-scheduled nil nil org-icalendar-use-scheduled))
---
>     (:icalendar-use-scheduled nil nil org-icalendar-use-scheduled)
>     (:icalendar-ttl nil nil org-icalendar-ttl))
833c847
< (defun org-icalendar--vcalendar (name owner tz description contents)
---
> (defun org-icalendar--vcalendar (name owner tz description ttl contents)
835c849
< NAME, OWNER, TZ, DESCRIPTION and CONTENTS are all strings giving,
---
> NAME, OWNER, TZ, DESCRIPTION, TTL and CONTENTS are all strings giving,
837c851,852
< 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."
843a859
> X-PUBLISHED-TTL:%s
848c864,865
< 		  (org-icalendar-cleanup-string description))
---
> 		  (org-icalendar-cleanup-string description)
> 		  (org-icalendar-cleanup-string ttl))
976a994
> 	org-icalendar-ttl
1000a1019,1020
> 	      ;; TTL (Refresh period)
> 	      org-icalendar-ttl

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

[Detlef Steuer]

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

Improved patch since org-icalendar-template needed to use
the new variable, too.

And now based on 9.5.2 from elpa.

Detlef


Am Thu, 30 Dec 2021 22:59:19 +0100
schrieb Detlef Steuer <steuer@hsu-hh.de>:

> This is my first try ever to contribute anything in elisp.
> 
> The nextcloud calendar app supports the X-PUBLISHED-TTL 
> option if subscribing to an ics file. Nextcloud defaults
> to a TTL of 1 week, what is much too long for my use case.
> 
> When exporting to such a file from org I did not find any way
> to set this option during export. So I tried to add a defcustom
> in ox-icalendar.el.
> 
> The default TTL in this patch is 1 hour.
> 
> I think this qualifies as an tiny patch, as it is mostly a docstring
> :-), in case anybody finds this an useful addition.
> 
> The patch is relative to 9.5.1 from elpa.
> 
> All comments very much appreciated.
> 
> And a happy new year to you all
> Detlef


[-- Attachment #2: addttl.patch --]
[-- Type: text/x-patch, Size: 1666 bytes --]

267a268,280
> (defcustom org-icalendar-ttl "PT1H"
>   "The time to life 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, i.e. X-PUBLISHED-TTL:PT1H .
> 
> See https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html
> for a complete description of possiblee values of this option. I.e.
> PT1H stands for 1 hour, PT0H27M34S for 0 hours, 27 minutes and 34 seconds."
>   :group 'org-export-icalendar
>   :type 'string)
> 
303c316,317
<     (:icalendar-use-scheduled nil nil org-icalendar-use-scheduled))
---
>     (:icalendar-use-scheduled nil nil org-icalendar-use-scheduled)
>     (:icalendar-ttl nil nil org-icalendar-ttl))
830a845,846
>    ;; TTL
>    org-icalendar-ttl
833c849
< (defun org-icalendar--vcalendar (name owner tz description contents)
---
> (defun org-icalendar--vcalendar (name owner tz description ttl contents)
835c851
< NAME, OWNER, TZ, DESCRIPTION and CONTENTS are all strings giving,
---
> NAME, OWNER, TZ, DESCRIPTION, TTL and CONTENTS are all strings giving,
837c853,854
< 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."
843a861
> X-PUBLISHED-TTL:%s
848c866,867
< 		  (org-icalendar-cleanup-string description))
---
> 		  (org-icalendar-cleanup-string description)
> 		  (org-icalendar-cleanup-string ttl))
976a996
> 	org-icalendar-ttl
1000a1021,1022
> 	      ;; TTL (Refresh period)
> 	      org-icalendar-ttl

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

[Max Nikulin]

On 02/01/2022 20:28, Detlef Steuer wrote:
> 
>> This is my first try ever to contribute anything in elisp.

Thanks for the patch. It is tracked on https://updates.orgmode.org/

It is easier to review and to apply a patch when it it is prepared in 
context format ("-u" option of diff). Several additional lines of code 
above and below changed ones makes the patch more tolerate to unrelated 
changes in the same file. It is a hint for humans as well.

See info "(diffutils) Tips for Patch Producers" 
https://www.gnu.org/software/diffutils/manual/html_node/Tips-for-Patch-Producers.html 
or "NOTES FOR PATCH SENDERS" section in "man patch".

If you have never used git (or other VCS) before then it is likely an 
overkill for a single patch, diff output with manually added description 
is OK. However you may find such tool rather convenient as number of 
changes will grow. See https://orgmode.org/worg/org-contribute.html for 
some hints addressed to contributors.

I am not a nextcloud or org-icalendar user, so while I expect that 
suggested change is an improvement, I can say nothing concerning the code.

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

[Detlef Steuer]

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

Thank you for the hints.

Attached a diff -u version.

The patch in principle is unrelated to nextcloud. That's just my
use case. The addiditional TTL setting gives a hint to clients
when to reload an imported ics file that was exported from org.

Is there any document how to setup an org-mode developer environment?
Normally I use git, but I even struggled to use org from elpa instead
of the built-in version, so I avoided touching this house of cards :-)

Probably I should use a git clone instead of elpa, if I want to work
on org?

Thx for the feedback!
Detlef



Am Mon, 3 Jan 2022 13:08:54 +0700
schrieb Max Nikulin <manikulin@gmail.com>:

> On 02/01/2022 20:28, Detlef Steuer wrote:
> >   
> >> This is my first try ever to contribute anything in elisp.  
> 
> Thanks for the patch. It is tracked on https://updates.orgmode.org/
> 
> It is easier to review and to apply a patch when it it is prepared in 
> context format ("-u" option of diff). Several additional lines of
> code above and below changed ones makes the patch more tolerate to
> unrelated changes in the same file. It is a hint for humans as well.
> 
> See info "(diffutils) Tips for Patch Producers" 
> https://www.gnu.org/software/diffutils/manual/html_node/Tips-for-Patch-Producers.html 
> or "NOTES FOR PATCH SENDERS" section in "man patch".
> 
> If you have never used git (or other VCS) before then it is likely an 
> overkill for a single patch, diff output with manually added
> description is OK. However you may find such tool rather convenient
> as number of changes will grow. See
> https://orgmode.org/worg/org-contribute.html for some hints addressed
> to contributors.
> 
> I am not a nextcloud or org-icalendar user, so while I expect that 
> suggested change is an improvement, I can say nothing concerning the
> code.
> 
> 


[-- Attachment #2: addttl.patch --]
[-- Type: text/x-patch, Size: 3177 bytes --]

--- ox-icalendar.el.orig	2022-01-02 13:38:17.586027624 +0100
+++ ox-icalendar.el	2022-01-02 14:12:10.446157056 +0100
@@ -265,6 +265,19 @@
 	  (const :tag "Universal time" ":%Y%m%dT%H%M%SZ")
 	  (string :tag "Explicit format")))
 
+(defcustom org-icalendar-ttl "PT1H"
+  "The time to life 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, i.e. X-PUBLISHED-TTL:PT1H .
+
+See https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html
+for a complete description of possiblee values of this option. I.e.
+PT1H stands for 1 hour, PT0H27M34S for 0 hours, 27 minutes and 34 seconds."
+  :group 'org-export-icalendar
+  :type 'string)
+
 (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
@@ -300,7 +313,8 @@
     (:icalendar-store-UID nil nil org-icalendar-store-UID)
     (: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-use-scheduled nil nil org-icalendar-use-scheduled)
+    (:icalendar-ttl nil nil org-icalendar-ttl))
   :filters-alist
   '((:filter-headline . org-icalendar-clear-blank-lines))
   :menu-entry
@@ -828,24 +842,29 @@
      (cadr (current-time-zone)))
    ;; Description.
    (org-export-data (plist-get info :title) info)
+   ;; TTL
+   org-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
+X-PUBLISHED-TTL:%s
 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 description)
+		  (org-icalendar-cleanup-string ttl))
 	  contents
 	  "END:VCALENDAR\n"))
 
@@ -974,6 +993,7 @@
 	user-full-name
 	(or (org-string-nw-p org-icalendar-timezone) (cadr (current-time-zone)))
 	org-icalendar-combined-description
+	org-icalendar-ttl
 	contents)))
     (run-hook-with-args 'org-icalendar-after-save-hook file)))
 
@@ -998,6 +1018,8 @@
 		  (cadr (current-time-zone)))
 	      ;; Description.
 	      org-icalendar-combined-description
+	      ;; TTL (Refresh period)
+	      org-icalendar-ttl
 	      ;; Contents.
 	      (concat
 	       ;; Agenda contents.

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

[Max Nikulin]

On 03/01/2022 14:41, Detlef Steuer wrote:
> 
> The patch in principle is unrelated to nextcloud. That's just my
> use case. The addiditional TTL setting gives a hint to clients
> when to reload an imported ics file that was exported from org.

I think, it is better to wait for comments from an ox-icalendar user. I 
am afraid, you will be tired trying to convince me that TTL should be 
overridden for all users (not to say that I am not a maintainer). I 
assume that some of them might have reasonable default in their server 
configuration.

> Is there any document how to setup an org-mode developer environment?
> Normally I use git, but I even struggled to use org from elpa instead
> of the built-in version, so I avoided touching this house of cards :-)

- info "(org) Installation" https://orgmode.org/manual/Installation.html
- info "(org) Feedback" https://orgmode.org/manual/Feedback.html

After "make autoloads" I usually run
     emacs -Q -L ~/src/org-mode/lisp test.org

In addition, I have a LXC container to run tests (and check for compile 
warnings) in an isolated environment.

> Probably I should use a git clone instead of elpa, if I want to work
> on org?

Maintainers prefer patches generated using "git format-patch".

>> https://orgmode.org/worg/org-contribute.html for some hints addressed
>> to contributors.

I am not completely sure, but you patch may exceed "TINYCHANGE" limit, 
so signing FSF copyright papers may be a prerequisite to accept your patch.

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

[Detlef Steuer]

Am Mon, 3 Jan 2022 18:23:43 +0700
schrieb Max Nikulin <manikulin@gmail.com>:

> On 03/01/2022 14:41, Detlef Steuer wrote:
> > 
> > The patch in principle is unrelated to nextcloud. That's just my
> > use case. The addiditional TTL setting gives a hint to clients
> > when to reload an imported ics file that was exported from org.  
> 
> I think, it is better to wait for comments from an ox-icalendar user.

Sure.

> I am afraid, you will be tired trying to convince me that TTL should
> be overridden for all users (not to say that I am not a maintainer).

No, that wasn't my intention. Just tried to explain.

> I assume that some of them might have reasonable default in their
> server configuration.
> 
> > Is there any document how to setup an org-mode developer
> > environment? Normally I use git, but I even struggled to use org
> > from elpa instead of the built-in version, so I avoided touching
> > this house of cards :-)  
> 
> - info "(org) Installation"
> https://orgmode.org/manual/Installation.html
> - info "(org) Feedback" https://orgmode.org/manual/Feedback.html
> 
> After "make autoloads" I usually run
>      emacs -Q -L ~/src/org-mode/lisp test.org
> 
> In addition, I have a LXC container to run tests (and check for
> compile warnings) in an isolated environment.
> 
> > Probably I should use a git clone instead of elpa, if I want to work
> > on org?  
> 
> Maintainers prefer patches generated using "git format-patch".
>

Ok, thx for the hints.

> >> https://orgmode.org/worg/org-contribute.html for some hints
> >> addressed to contributors.  
> 
> I am not completely sure, but you patch may exceed "TINYCHANGE"
> limit, so signing FSF copyright papers may be a prerequisite to
> accept your patch.
>

Hmm, probably a good idea anyway.

Regards
Detlef


> 
> 

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

[Ihor Radchenko]

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

>> I think, it is better to wait for comments from an ox-icalendar user.
>
> Sure.

Sorry for the late reply.
I am not a user, but will the patch looks reasonable in general.

>> I am afraid, you will be tired trying to convince me that TTL should
>> be overridden for all users (not to say that I am not a maintainer).
>
> No, that wasn't my intention. Just tried to explain.

I agree that it is not a good idea to force-override server defaults.
Instead, I'd prefer the defcustom to default to nil (no TTL inserted)
and other possible values documented and listed in :type defcustom
argument.

>> >> https://orgmode.org/worg/org-contribute.html for some hints
>> >> addressed to contributors.  
>> 
>> I am not completely sure, but you patch may exceed "TINYCHANGE"
>> limit, so signing FSF copyright papers may be a prerequisite to
>> accept your patch.
>>
>
> Hmm, probably a good idea anyway.

The patch is on the edge, probably still acceptable without copyright
assignment. If you have it, it would be much better though.

-- 
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>

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

[Ihor Radchenko]

[Adding Org ML back to CC; please use "Reply All" when replying in ML threads]

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

>> The patch is on the edge, probably still acceptable without copyright
>> assignment. If you have it, it would be much better though.
>> 
>
> In the meantime I have the paperwork done and have "it" :-)

Bastien, could you please check FSF records?

-- 
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>

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

[Bastien Guerry]

Hi,

Ihor Radchenko <yantar92@posteo.net> writes:

>> In the meantime I have the paperwork done and have "it" :-)
>
> Bastien, could you please check FSF records?

Yes, I confirm Detlef is registered in the FSF records.

-- 
 Bastien

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

[Detlef Steuer]

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

Hi Ihor!

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

Detlef

Am Sat, 14 Jan 2023 10:26:17 +0000
schrieb Ihor Radchenko <yantar92@posteo.net>:

> Detlef Steuer <steuer@hsu-hh.de> writes:
> 
> > I now finally followed your advice for that patch.
> >
> > Attached a diff against a clean git checkout from two
> > hours ago.  
> 
> Thanks!
> Rather than diff, it would help to format a proper patch with author
> info and commit message (if you can).
> See https://orgmode.org/worg/org-contribute.html#first-patch and
> https://orgmode.org/worg/org-contribute.html#commit-messages
> 
> > (I send it privately, because I'm such a noob regarding elisp...)  
> 
> Do not be afraid to post on the mailing list in future.
> We do not shame anyone or attack in any other way. See
> https://www.gnu.org/philosophy/kind-communication.html
> 
> If there are problems with the code, we will help to improve them. If
> the problems are also discussed in public, other people will have a
> chance to learn as well.
> 
> Let me know if you still prefer private communication.
> 
> > 
> > mail: steuer@hsu-hh.de
> > commit e7574a8d429634112a2eb622759b4eef670ee44c
> > Author: Detlef Steuer <steuer@hsu-hh.de>
> > Date:   Fri Jan 13 17:55:57 2023 +0100
> >
> >     Add variable org-icalendar-ttl to ox-icalendar.el  
> 
> See https://orgmode.org/worg/org-contribute.html#commit-messages for
> our preferred commit message format.
> 
> > +(defcustom org-icalendar-ttl nil
> > +  "The time to life 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  
> 
> Elisp convention is to use double space (" ") between sentences in
> docstrings. 
> 
> > +the nextcloud calendar, which respects the setting of
> > +X-PUBLISHED-TTL, i.e. X-PUBLISHED-TTL:PT1H .
> > +See https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html
> > +for a complete description of possiblee values of this option. I.e.
> > +PT1H stands for 1 hour, PT0H27M34S for 0 hours, 27 minutes and 34
> > seconds."
> > +  :group 'org-export-icalendar
> > +  :type '(choice
> > +          (const :tag "no refresh" nil)
> > +          (const :tag "One day" "PT1D")
> > +          (const :tag "One week" "PT7D")
> > +          (string :tag "Explizit format")))  
> 
> Maybe just "Other"?
> 
> Also, please add
> 
> :package-version '(Org . "9.7")
> 
> to indicate when the new customization is introduced.
> 
> Finally, please document the new feature in etc/ORG-NEWS file.
> 
> > -    (: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,24 +889,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
> > +   org-icalendar-ttl  
> 
> Please use (plist-get info :icalendar-ttl) here and later rather than
> the variable. It will then integrate better with Org's export system.
> 
> >  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, the time-to-live resp. refresh period
> > and   
> 
> "time-to-life"? or maybe "time to life"?
> 




[-- Attachment #2: 0001-lisp-ox-icalendar.el-Add-customize-option-org-icalen.patch --]
[-- Type: text/x-patch, Size: 5650 bytes --]

From 7ad4b2df9609fd5893e71836aa2e172023fe2895 Mon Sep 17 00:00:00 2001
From: Detlef Steuer <steuer@hsu-hh.de>
Date: Mon, 16 Jan 2023 23:27:33 +0100
Subject: [PATCH] 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 | 45 ++++++++++++++++++++++++++++++++++++--------
 2 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index c5d9bdf6e..47d808df2 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..a116ba231 100644
--- a/lisp/ox-icalendar.el
+++ b/lisp/ox-icalendar.el
@@ -297,6 +297,26 @@ Interesting value are:
 	  (const :tag "Universal time" ":%Y%m%dT%H%M%SZ")
 	  (string :tag "Explicit format")))
 
+(defcustom org-icalendar-ttl nil
+  "The time to life 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 possible specifications 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."
+  :group 'org-export-icalendar
+  :type '(choice
+          (const :tag "no refresh" nil)
+          (const :tag "One day" "PT1D")
+          (const :tag "One week" "PT7D")
+          (string :tag "Explizit format"))
+  :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 +354,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 nil nil org-icalendar-ttl))
   :filters-alist
   '((:filter-headline . org-icalendar-clear-blank-lines))
   :menu-entry
@@ -872,24 +893,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."
-  (concat (format "BEGIN:VCALENDAR
+used, a short description, the 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"
+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 description)
+		  (org-icalendar-cleanup-string ttl))
 	  contents
 	  "END:VCALENDAR\n"))
 
@@ -1018,6 +1044,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 +1069,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.0

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

[Ihor Radchenko]

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

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?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-lisp-ox-icalendar.el-Add-customize-option-org-ica.patch --]
[-- Type: text/x-patch, Size: 5996 bytes --]

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"))
 
 
 \f
@@ -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


[-- Attachment #3: Type: text/plain, Size: 224 bytes --]


-- 
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>

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

[Detlef Steuer]

Am Tue, 17 Jan 2023 09:43:18 +0000
schrieb Ihor Radchenko <yantar92@posteo.net>:

> 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/)
> 

Thx!

> 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?
> 

Hmm. Surely it would be useful to have the option to use different TTL
settings for different calendar exports, yes.

The next question would be, if org-icalendar-combine-agenda-files is
called and the files have different per-file settings, which will be
used?

May be single file org-icalendar-export-to-ics and
org-icalender-export-agenda-files use an existing per-file setting,
global setting otherwise, but org-icalendar-combine-agenda-files always
uses the global setting?

Detlef

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

[Ihor Radchenko]

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

>> 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?
>> 
>
> Hmm. Surely it would be useful to have the option to use different TTL
> settings for different calendar exports, yes.
>
> The next question would be, if org-icalendar-combine-agenda-files is
> called and the files have different per-file settings, which will be
> used?

The only sane way would be using the global default.

> May be single file org-icalendar-export-to-ics and
> org-icalender-export-agenda-files use an existing per-file setting,
> global setting otherwise, but org-icalendar-combine-agenda-files always
> uses the global setting?

Agree.

To achieve this you just need to update the export option settings:

    (:icalendar-ttl nil nil org-icalendar-ttl)

adding a file keyword to be used.
See `org-export-options-alist' docstring.

-- 
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>

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

[Detlef Steuer]

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

Am Tue, 17 Jan 2023 10:30:07 +0000
schrieb Ihor Radchenko <yantar92@posteo.net>:

> Detlef Steuer <steuer@hsu-hh.de> writes:
> 
> >> 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? 
> >
> > Hmm. Surely it would be useful to have the option to use different
> > TTL settings for different calendar exports, yes.
> >
> > The next question would be, if org-icalendar-combine-agenda-files is
> > called and the files have different per-file settings, which will be
> > used?  
> 
> The only sane way would be using the global default.
> 
> > May be single file org-icalendar-export-to-ics and
> > org-icalender-export-agenda-files use an existing per-file setting,
> > global setting otherwise, but org-icalendar-combine-agenda-files
> > always uses the global setting?  
> 
> Agree.
> 
> To achieve this you just need to update the export option settings:
> 
>     (:icalendar-ttl nil nil org-icalendar-ttl)
> 
> adding a file keyword to be used.
> See `org-export-options-alist' docstring.
> 

Hi Ihor, 

I hope I understood your advice and the docstring and examples in other
exporters correctly. Is it really that easy?

Next iteration of the patch.

Detlef


[-- Attachment #2: 0001-Add-TTL-to-icalendar-export-options.patch --]
[-- Type: text/x-patch, Size: 3398 bytes --]

From 0af9cf3d1e742271531f047f2ed0a690a81261c7 Mon Sep 17 00:00:00 2001
From: Detlef Steuer <detlef.steuer@hsu-hh.de>
Date: Fri, 3 Feb 2023 14:11:00 +0100
Subject: [PATCH 1/2] Add TTL to icalendar export options

---
 lisp/ox-icalendar.el | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/lisp/ox-icalendar.el b/lisp/ox-icalendar.el
index 81a77a770..600eaae24 100644
--- a/lisp/ox-icalendar.el
+++ b/lisp/ox-icalendar.el
@@ -297,6 +297,21 @@ Interesting value are:
 	  (const :tag "Universal time" ":%Y%m%dT%H%M%SZ")
 	  (string :tag "Explicit format")))
 
+(defcustom org-icalendar-ttl "PT1H"
+  "The time to life 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, i.e. X-PUBLISHED-TTL:PT1H .
+
+See https://icalendar.org/iCalendar-RFC-5545/3-8-2-5-duration.html
+for a complete description of possiblee values of this option. I.e.
+PT1H stands for 1 hour, PT0H27M34S for 0 hours, 27 minutes and 34 seconds.
+
+This option can also be set with the ICAL-TTL keyword."
+  :group 'org-export-icalendar
+  :type 'string)
+
 (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
@@ -333,6 +348,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,13 +888,16 @@ 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
+   org-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
@@ -1018,6 +1037,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 +1062,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


[-- Attachment #3: 0002-Add-entry-for-new-org-icalendar-ttl-option-to-ORG-NE.patch --]
[-- Type: text/x-patch, Size: 1363 bytes --]

From 2a1376457a7d09b6586bea55061aa0aa99509106 Mon Sep 17 00:00:00 2001
From: Detlef Steuer <detlef.steuer@hsu-hh.de>
Date: Fri, 3 Feb 2023 14:20:52 +0100
Subject: [PATCH 2/2] Add entry for new org-icalendar-ttl option to ORG-NEWS

---
 etc/ORG-NEWS | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 40477e73f..c10f95d67 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
-- 
2.39.1

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

[Ihor Radchenko]

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

>> To achieve this you just need to update the export option settings:
>> 
>>     (:icalendar-ttl nil nil org-icalendar-ttl)
>> 
>> adding a file keyword to be used.
>> See `org-export-options-alist' docstring.
>> 
>
> Hi Ihor, 
>
> I hope I understood your advice and the docstring and examples in other
> exporters correctly. Is it really that easy?

Yup.

> Next iteration of the patch.

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.

-- 
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>

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

[Detlef Steuer]

[-- 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

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

[Ihor Radchenko]

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

> Next try.

Thanks!

> +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.

Should quote the Org syntax keyword according to our documentation
standards: =ICAL-TTL= 

> @@ -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")))

This does not belong to this patch. Probably accidental change.

> +(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\"

`org-icalendar-ttl'.

> +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

The default

> +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)

"No refresh"

>    (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"))

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.  

-- 
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>

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

[Jack Kamm]

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

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.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ox-icalendar.el-Add-time-to-live-functionality-.patch --]
[-- Type: text/x-patch, Size: 7258 bytes --]

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

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

[Ihor Radchenko]

Jack Kamm <jackkamm@gmail.com> writes:

> 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.

LGTM. Thanks!

-- 
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>

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

[Jack Kamm]

Ihor Radchenko <yantar92@posteo.net> writes:

> LGTM. Thanks!

Thanks, I've applied now:

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=da2b61b09e1eff957e6b2560a2f9c8509de6beac