Subject: Re: bug#75956: Various improvements to sieve.el

From: Björn Bidar <[email-masked]>
Date: Tue, 11 Feb 2025 23:58:09 +0200

Stefan Kangas <[email-masked]> writes:

> Björn Bidar <[email-masked]> writes:
>
>> Stefan Kangas <[email-masked]> writes:
>>
>>>> A compromise would be to mention in the prompt that the port can be
>>>> specified in the prompt.
>>>
>>> OK, then let's do that.
>>
>> What did you have in mind? For example for man pages the optional arguments
>> it is custom to put optional arguments in [].
>> Going with that the prompt could look like that: 'Server[:port] : '.
>
> Yeah, we have to be brief, which makes this hard.  How about this:
>
>     Server (optionally followed by `:port'):

OK changed the prompt to look like this. Regarding the bug reference
again.
When the patch touches multiple files should the reference go to the
first change only?

Anyway here the updated patches.

>From 1291a3f4467df1a6bdb0be6500b0f44f2c6dd731 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Bidar?= <[email-masked]>
Date: Fri, 31 Jan 2025 02:34:19 +0200
Subject: [PATCH 1/3] * lisp/net/sieve.el: Read port in sieve-manage when
 interactive

(sieve-manage): Optionally read port when called interactively.
Add previously missing documentation string. (Bug#75956)
---
 lisp/net/sieve.el | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
index f9f036e1589..6b40e1e6af7 100644
--- a/lisp/net/sieve.el
+++ b/lisp/net/sieve.el
@@ -338,7 +338,15 @@ sieve-refresh-scriptlist
 
 ;;;###autoload
 (defun sieve-manage (server &optional port)
-  (interactive "sServer: ")
+  "Open ManageSieve SERVER.
+Optionally argument PORT specifies the port use;
+otherwise it defaults to `sieve-manage-default-port'.
+
+When called interactively, prompt for SERVER:PORT
+if :PORT is not specified fall back to `sieve-manage-default-port'."
+  (interactive
+   (split-string (read-string
+                  "Server (optionally followed by `:port'): ") ":"))
   (switch-to-buffer (get-buffer-create sieve-buffer))
   (sieve-manage-mode)
   (sieve-setup-buffer server port)
-- 
2.45.2

>From 401586830b3bb64de4bbdfcf6e4fe0fc48be8c27 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Bidar?= <[email-masked]>
Date: Fri, 31 Jan 2025 02:53:34 +0200
Subject: [PATCH 2/3] * lisp/net/sieve.el: Add missing documentation strings

(sieve-activate, sieve-deactivate-all, sieve-remove)
(sieve-edit-script, sieve-refersh-scriptlist)
(sieve-upload, sieve-upload-and-burry)
(sieve-upload-and-kill): Add documentation strings (Bug#75956)
---
 lisp/net/sieve.el | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
index 6b40e1e6af7..8feb1c0bdbd 100644
--- a/lisp/net/sieve.el
+++ b/lisp/net/sieve.el
@@ -161,6 +161,7 @@ sieve-bury-buffer
   (bury-buffer))
 
 (defun sieve-activate (&optional _pos)
+  "Activate script at point."
   (interactive)
   (let ((name (sieve-script-at-point)) err)
     (when (or (null name) (string-equal name sieve-new-script))
@@ -173,6 +174,7 @@ sieve-activate
       (message "Activating script %s...failed: %s" name (nth 2 err)))))
 
 (defun sieve-deactivate-all (&optional _pos)
+  "Deactivate all currently active scripts."
   (interactive)
   (message "Deactivating scripts...")
   (let (;; (name (sieve-script-at-point))
@@ -185,6 +187,7 @@ sieve-deactivate-all
 (defalias 'sieve-deactivate #'sieve-deactivate-all)
 
 (defun sieve-remove (&optional _pos)
+  "Remove script at point."
   (interactive)
   (let ((name (sieve-script-at-point)) err)
     (when (or (null name) (string-equal name sieve-new-script))
@@ -197,6 +200,7 @@ sieve-remove
     (message "Removing sieve script %s...done" name)))
 
 (defun sieve-edit-script (&optional _pos)
+  "Edit script at point."
   (interactive)
   (let ((name (sieve-script-at-point)))
     (unless name
@@ -310,6 +314,7 @@ sieve-open-server
     (sieve-manage-authenticate)))
 
 (defun sieve-refresh-scriptlist ()
+  "Refresh list of scripts found the currently opened server."
   (interactive)
   (with-current-buffer sieve-buffer
     (setq buffer-read-only nil)
@@ -356,6 +361,9 @@ sieve-manage
 
 ;;;###autoload
 (defun sieve-upload (&optional name)
+  "Upload script NAME to currently opened server.
+If NAME is nil, detect it from script buffer name.
+If no open sieve buffer exists, call `sieve-manage' first."
   (interactive)
   (when (or (get-buffer sieve-buffer)
             (save-current-buffer (call-interactively 'sieve-manage)))
@@ -374,12 +382,14 @@ sieve-upload
 
 ;;;###autoload
 (defun sieve-upload-and-bury (&optional name)
+  "Upload script NAME and bury the current buffer."
   (interactive)
   (sieve-upload name)
   (bury-buffer))
 
 ;;;###autoload
 (defun sieve-upload-and-kill (&optional name)
+  "Upload script NAME and kill the current buffer."
   (interactive)
   (sieve-upload name)
   (kill-buffer))
-- 
2.45.2

>From abe3024fd1019de535b7643e0637b2aaffcca675 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Bidar?= <[email-masked]>
Date: Fri, 31 Jan 2025 03:24:44 +0200
Subject: [PATCH 3/3] Bind sieve-refresh-scriptlist to refresh buffer

* lisp/net/sieve.el (sieve-manage-mode-map):
Bind `sieve-refersh-scriptlist' to 'g' to refresh buffer.
(sieve-refresh-scriptlist): Highlight that the function updates
the current sieve buffer. (Bug#75956)

* etc/NEWS: Announce new keybinding

* doc/misc/siev.texi (Managing Sieve):
Document new keybinding and the existing `sieve-refresh-scriptlist`
function.
---
 doc/misc/sieve.texi | 6 ++++++
 etc/NEWS            | 6 ++++++
 lisp/net/sieve.el   | 4 +++-
 3 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi
index 5d4b3b369d7..deadc991173 100644
--- a/doc/misc/sieve.texi
+++ b/doc/misc/sieve.texi
@@ -213,6 +213,12 @@ Managing Sieve
 @findex sieve-help
 Displays help in the minibuffer.
 
+@item g
+@kindex g
+@findex sieve-refresh-scriptlist
+Refresh list of scripts found on the currently opened server.
+Update contents of the current sieve buffer.
+
 @item Q
 @kindex Q
 @findex sieve-manage-quit
diff --git a/etc/NEWS b/etc/NEWS
index 2f04204ad94..fc40b07fa59 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -392,6 +392,12 @@ When called with a prefix argument, accepting, declining, or tentatively
 accepting an icalendar event will prompt for a comment to add to the
 response.
 
+** Sieve
++++
+*** New keybinding to refresh buffer in sieve-manage-mode
+'sieve-refresh-scriptlist' is now bound to 'g' to refresh the contents
+of the current sieve buffer.
+
 ** Button
 
 +++
diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
index 8feb1c0bdbd..0ee95599d3e 100644
--- a/lisp/net/sieve.el
+++ b/lisp/net/sieve.el
@@ -111,6 +111,7 @@ sieve-manage-mode-map
   ;; various
   "?"      #'sieve-help
   "h"      #'sieve-help
+  "g"      #'sieve-refresh-scriptlist
   ;; activating
   "m"      #'sieve-activate
   "u"      #'sieve-deactivate
@@ -314,7 +315,8 @@ sieve-open-server
     (sieve-manage-authenticate)))
 
 (defun sieve-refresh-scriptlist ()
-  "Refresh list of scripts found the currently opened server."
+  "Refresh list of scripts found the currently opened server.
+Update contents of the current sieve buffer."
   (interactive)
   (with-current-buffer sieve-buffer
     (setq buffer-read-only nil)
-- 
2.45.2