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

From: Björn Bidar <[email-masked]>
Date: Wed, 12 Feb 2025 21:23:10 +0200

Stefan Kangas <[email-masked]> writes:

> Björn Bidar via "Bug reports for GNU Emacs, the Swiss army knife of text
> editors" <[email-masked]> writes:
>
>> Eli Zaretskii <[email-masked]> writes:
>>
>>>> From: Stefan Kangas <[email-masked]>
>>>> Date: Tue, 11 Feb 2025 12:09:16 -0800
>>>> Cc: Eli Zaretskii <[email-masked]>, [email-masked]
>>>>
>>>> Yeah, we have to be brief, which makes this hard.  How about this:
>>>>
>>>>     Server (optionally followed by `:port'):
>>>>
>>>> Eli, any better ideas?
>>>
>>> That's not bad.  Another possibility:
>>>
>>>   Server and port (SERVER[:PORT]):
>>
>> Which one is preferred? Personally I'm fine with either. I already
>> updated the patch with Stefan's suggestion.
>
> I think we can go with Eli's suggestion here.  Users that want to
> understand things better should read the docstring.

Ok there you go:

>From 653a0196fd32c2fe0262beeb50e7fb74a0345d13 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..f0801238ab1 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 and port (SERVER[:PORT]): ") ":"))
   (switch-to-buffer (get-buffer-create sieve-buffer))
   (sieve-manage-mode)
   (sieve-setup-buffer server port)
-- 
2.45.2

>From 8f4f586617805a349339cb5e35341d96c82aa107 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 f0801238ab1..5b4c2440266 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 f65be55e92b720e2fb8b7f94c575aa2714a1e904 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 5b4c2440266..7a5bdf02065 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