* [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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ messages in thread
[parent not found: <20221109082520.066dc4c6@linux.fritz.box>]
* 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; 20+ 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] 20+ 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; 20+ 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] 20+ messages in thread
[parent not found: <20230113181035.1469ab37@hsu-hh.de>]
[parent not found: <878ri52z06.fsf@localhost>]
* 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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; 20+ 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] 20+ 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 2024-01-27 5:00 ` Jack Kamm 0 siblings, 1 reply; 20+ 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] 20+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar 2023-02-05 11:09 ` Ihor Radchenko @ 2024-01-27 5:00 ` Jack Kamm 2024-01-28 13:42 ` Ihor Radchenko 0 siblings, 1 reply; 20+ messages in thread From: Jack Kamm @ 2024-01-27 5:00 UTC (permalink / raw) To: Ihor Radchenko, Detlef Steuer; +Cc: emacs-orgmode [-- 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 ^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar 2024-01-27 5:00 ` Jack Kamm @ 2024-01-28 13:42 ` Ihor Radchenko 2024-01-28 21:50 ` Jack Kamm 0 siblings, 1 reply; 20+ messages in thread From: Ihor Radchenko @ 2024-01-28 13:42 UTC (permalink / raw) To: Jack Kamm; +Cc: Detlef Steuer, emacs-orgmode 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> ^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: [patch] improved: add TTL as defcustom to ox-icalendar 2024-01-28 13:42 ` Ihor Radchenko @ 2024-01-28 21:50 ` Jack Kamm 0 siblings, 0 replies; 20+ messages in thread From: Jack Kamm @ 2024-01-28 21:50 UTC (permalink / raw) To: Ihor Radchenko; +Cc: Detlef Steuer, emacs-orgmode 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 ^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2024-01-28 21:51 UTC | newest]
Thread overview: 20+ 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
2024-01-27 5:00 ` Jack Kamm
2024-01-28 13:42 ` Ihor Radchenko
2024-01-28 21:50 ` Jack Kamm
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).