emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Detlef Steuer <steuer@hsu-hh.de>
To: emacs-orgmode@gnu.org
Cc: Ihor Radchenko <yantar92@posteo.net>
Subject: Re: [patch] improved: add TTL as defcustom to ox-icalendar
Date: Mon, 16 Jan 2023 23:42:30 +0100	[thread overview]
Message-ID: <20230116234230.5080fb07@linux.fritz.box> (raw)
In-Reply-To: <878ri52z06.fsf@localhost>

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


  parent reply	other threads:[~2023-01-16 22:43 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
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 [this message]
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

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20230116234230.5080fb07@linux.fritz.box \
    --to=steuer@hsu-hh.de \
    --cc=emacs-orgmode@gnu.org \
    --cc=yantar92@posteo.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).