* [patch] add TTL as defcustom to ox-icalendar
@ 2021-12-30 21:59 Detlef Steuer
2022-01-02 13:28 ` [patch] improved: " Detlef Steuer
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2021-12-30 21:59 UTC (permalink / raw)
To: emacs-orgmode
[-- 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
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2021-12-30 21:59 [patch] add TTL as defcustom to ox-icalendar Detlef Steuer
@ 2022-01-02 13:28 ` Detlef Steuer
2022-01-03 6:08 ` Max Nikulin
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2022-01-02 13:28 UTC (permalink / raw)
To: emacs-orgmode
[-- 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
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2022-01-02 13:28 ` [patch] improved: " Detlef Steuer
@ 2022-01-03 6:08 ` Max Nikulin
2022-01-03 7:41 ` Detlef Steuer
0 siblings, 1 reply; 17+ messages in thread
From: Max Nikulin @ 2022-01-03 6:08 UTC (permalink / raw)
To: emacs-orgmode
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.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2022-01-03 6:08 ` Max Nikulin
@ 2022-01-03 7:41 ` Detlef Steuer
2022-01-03 11:23 ` Max Nikulin
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2022-01-03 7:41 UTC (permalink / raw)
To: emacs-orgmode
[-- 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.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2022-01-03 7:41 ` Detlef Steuer
@ 2022-01-03 11:23 ` Max Nikulin
2022-01-03 11:32 ` Detlef Steuer
0 siblings, 1 reply; 17+ messages in thread
From: Max Nikulin @ 2022-01-03 11:23 UTC (permalink / raw)
To: emacs-orgmode
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.
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2022-01-03 11:23 ` Max Nikulin
@ 2022-01-03 11:32 ` Detlef Steuer
2022-11-09 6:57 ` Ihor Radchenko
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2022-01-03 11:32 UTC (permalink / raw)
To: emacs-orgmode
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
>
>
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2022-01-03 11:32 ` Detlef Steuer
@ 2022-11-09 6:57 ` Ihor Radchenko
[not found] ` <20221109082520.066dc4c6@linux.fritz.box>
0 siblings, 1 reply; 17+ messages in thread
From: Ihor Radchenko @ 2022-11-09 6:57 UTC (permalink / raw)
To: Detlef Steuer; +Cc: emacs-orgmode
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>
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
[not found] ` <20221109082520.066dc4c6@linux.fritz.box>
@ 2022-11-09 7:58 ` Ihor Radchenko
2022-11-09 8:32 ` Bastien Guerry
[not found] ` <20230113181035.1469ab37@hsu-hh.de>
1 sibling, 1 reply; 17+ messages in thread
From: Ihor Radchenko @ 2022-11-09 7:58 UTC (permalink / raw)
To: Detlef Steuer, Bastien; +Cc: emacs-orgmode
[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>
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2022-11-09 7:58 ` Ihor Radchenko
@ 2022-11-09 8:32 ` Bastien Guerry
0 siblings, 0 replies; 17+ messages in thread
From: Bastien Guerry @ 2022-11-09 8:32 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: Detlef Steuer, emacs-orgmode
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
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
[not found] ` <878ri52z06.fsf@localhost>
@ 2023-01-16 22:42 ` Detlef Steuer
2023-01-17 9:43 ` Ihor Radchenko
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2023-01-16 22:42 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Ihor Radchenko
[-- 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
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-01-16 22:42 ` Detlef Steuer
@ 2023-01-17 9:43 ` Ihor Radchenko
2023-01-17 10:03 ` Detlef Steuer
0 siblings, 1 reply; 17+ messages in thread
From: Ihor Radchenko @ 2023-01-17 9:43 UTC (permalink / raw)
To: Detlef Steuer; +Cc: emacs-orgmode
[-- 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>
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-01-17 9:43 ` Ihor Radchenko
@ 2023-01-17 10:03 ` Detlef Steuer
2023-01-17 10:30 ` Ihor Radchenko
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2023-01-17 10:03 UTC (permalink / raw)
To: emacs-orgmode; +Cc: Ihor Radchenko
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
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-01-17 10:03 ` Detlef Steuer
@ 2023-01-17 10:30 ` Ihor Radchenko
2023-02-03 13:25 ` Detlef Steuer
0 siblings, 1 reply; 17+ messages in thread
From: Ihor Radchenko @ 2023-01-17 10:30 UTC (permalink / raw)
To: Detlef Steuer; +Cc: emacs-orgmode
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>
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-01-17 10:30 ` Ihor Radchenko
@ 2023-02-03 13:25 ` Detlef Steuer
2023-02-04 11:09 ` Ihor Radchenko
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2023-02-03 13:25 UTC (permalink / raw)
To: emacs-orgmode
[-- 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
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-02-03 13:25 ` Detlef Steuer
@ 2023-02-04 11:09 ` Ihor Radchenko
2023-02-04 21:01 ` Detlef Steuer
0 siblings, 1 reply; 17+ messages in thread
From: Ihor Radchenko @ 2023-02-04 11:09 UTC (permalink / raw)
To: Detlef Steuer; +Cc: emacs-orgmode
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>
^ permalink raw reply [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-02-04 11:09 ` Ihor Radchenko
@ 2023-02-04 21:01 ` Detlef Steuer
2023-02-05 11:09 ` Ihor Radchenko
0 siblings, 1 reply; 17+ messages in thread
From: Detlef Steuer @ 2023-02-04 21:01 UTC (permalink / raw)
To: Ihor Radchenko; +Cc: emacs-orgmode
[-- 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
^ permalink raw reply related [flat|nested] 17+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar
2023-02-04 21:01 ` Detlef Steuer
@ 2023-02-05 11:09 ` Ihor Radchenko
0 siblings, 0 replies; 17+ messages in thread
From: Ihor Radchenko @ 2023-02-05 11:09 UTC (permalink / raw)
To: Detlef Steuer; +Cc: emacs-orgmode
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>
^ permalink raw reply [flat|nested] 17+ messages in thread
end of thread, other threads:[~2023-02-05 11:10 UTC | newest]
Thread overview: 17+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-12-30 21:59 [patch] add TTL as defcustom to ox-icalendar Detlef Steuer
2022-01-02 13:28 ` [patch] improved: " Detlef Steuer
2022-01-03 6:08 ` Max Nikulin
2022-01-03 7:41 ` Detlef Steuer
2022-01-03 11:23 ` Max Nikulin
2022-01-03 11:32 ` Detlef Steuer
2022-11-09 6:57 ` Ihor Radchenko
[not found] ` <20221109082520.066dc4c6@linux.fritz.box>
2022-11-09 7:58 ` Ihor Radchenko
2022-11-09 8:32 ` Bastien Guerry
[not found] ` <20230113181035.1469ab37@hsu-hh.de>
[not found] ` <878ri52z06.fsf@localhost>
2023-01-16 22:42 ` Detlef Steuer
2023-01-17 9:43 ` Ihor Radchenko
2023-01-17 10:03 ` Detlef Steuer
2023-01-17 10:30 ` Ihor Radchenko
2023-02-03 13:25 ` Detlef Steuer
2023-02-04 11:09 ` Ihor Radchenko
2023-02-04 21:01 ` Detlef Steuer
2023-02-05 11:09 ` Ihor Radchenko
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).