Subject: Various improvements to sieve.el

From: Björn Bidar <[email-masked]>
Date: Fri, 31 Jan 2025 03:54:11 +0200

Tags: patch

I noticed it is not possible to specific the sieve-manage port when
calling `sieve-manage`. While fixing that I noticed various other issues.
- Missing documentation strings on many functions
- There is function to refresh the buffer but it is not bound

The attached patches try to fix these issues.

In GNU Emacs 31.0.50 (build 1, x86_64-suse-linux-gnu, GTK+ Version
3.24.43, cairo version 1.18.2)
Repository revision: 2efffbe7731ba979540df851819af0ef15b94c62
Repository branch: master
Windowing system distributor 'The X.Org Foundation', version 11.0.12101015
System Description: openSUSE Tumbleweed

Configured using:
 'configure --disable-build-details --without-pop --with-mailutils
 --without-hesiod --with-gameuser=:games --with-kerberos
 --with-kerberos5 --with-file-notification=inotify --with-modules
 --enable-autodepend --enable-link-time-optimization --prefix=/usr
 --mandir=/usr/share/man --infodir=/usr/share/info --datadir=/usr/share
 --localstatedir=/var --sharedstatedir=/var/lib
 --libexecdir=/usr/libexec --with-file-notification=yes
 --libdir=/usr/lib64 --with-native-compilation=aot
 --enable-locallisppath=/usr/share/emacs/31.0.50/site-lisp:/usr/share/emacs/site-lisp
 --with-x --with-xim --with-sound --with-xpm --with-jpeg --with-tiff
 --with-gif --with-png --with-rsvg --with-dbus --with-xft --without-gpm
 --with-tree-sitter --with-x-toolkit=gtk --without-pgtk
 --with-toolkit-scroll-bars --x-includes=/usr/include
 --x-libraries=/usr/lib64 --with-libotf --with-m17n-flt --with-cairo
 --build=x86_64-suse-linux --with-dumping=pdumper
 build_alias=x86_64-suse-linux 'CC=sccache cc' 'CFLAGS=-O2 -Wall
 -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3 -fstack-protector-strong
 -funwind-tables -fasynchronous-unwind-tables -fstack-clash-protection
 -Werror=return-type -flto=auto -march=znver3 -mmmx -mpopcnt -msse
 -msse2 -msse3 -mssse3 -msse4.1 -msse4.2 -mavx -mavx2 -msse4a -mno-fma4
 -mno-xop -mfma -mbmi -mbmi2 -maes -mpclmul -mno-gfni -mvpclmulqdq
 -mno-3dnow -madx -mabm -mno-cldemote -mclflushopt -mclwb -mclzero
 -mcx16 -mno-enqcmd -mf16c -mfsgsbase -mfxsr -mno-hle -msahf -mno-lwp
 -mlzcnt -mmovbe -mno-movdir64b -mno-movdiri -mmwaitx -mno-pconfig -mpku
 -mprfchw -mno-ptwrite -mrdpid -mrdrnd -mrdseed -mno-rtm -mno-serialize
 -mno-sgx -msha -mshstk -mno-tbm -mno-tsxldtrk -mvaes -mno-waitpkg
 -mwbnoinvd -mxsave -mxsavec -mxsaveopt -mxsaves -mno-amx-tile
 -mno-amx-int8 -mno-amx-bf16 -mno-uintr -mno-hreset -mno-kl -mno-widekl
 -mno-avxvnni -mno-avxifma -mno-avxvnniint8 -mno-avxneconvert
 -mno-cmpccxadd -mno-amx-fp16 -mno-prefetchi -mno-raoint
 -mno-amx-complex --param l1-cache-size=32 --param l1-cache-line-size=64
 --param l2-cache-size=512 -mtune=znver3 -fno-optimize-sibling-calls -O2
 -Wall -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3 -fstack-protector-strong
 -funwind-tables -fasynchronous-unwind-tables -fstack-clash-protection
 -Werror=return-type -flto=auto -g -D_GNU_SOURCE
 -DGDK_DISABLE_DEPRECATION_WARNINGS -DGLIB_DISABLE_DEPRECATION_WARNINGS
 -pipe -Wno-pointer-sign -Wno-unused-variable -Wno-unused-label
 -DPDMP_BASE='\''"emacs-gtk"'\''' LDFLAGS=-Wl,-O2 'CXX=sccache c++'
 PKG_CONFIG_PATH=:/usr/lib64/pkgconfig:/usr/share/pkgconfig'

>From e54ab1de5bbd214e38b4064ae6f2c81c12e54cf6 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.
---
 lisp/net/sieve.el | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
index f9f036e1589..8d44c384539 100644
--- a/lisp/net/sieve.el
+++ b/lisp/net/sieve.el
@@ -338,7 +338,13 @@ sieve-refresh-scriptlist
 
 ;;;###autoload
 (defun sieve-manage (server &optional port)
-  (interactive "sServer: ")
+  "Open ManageSieve SERVER.
+Optionally with PORT.
+
+When called in interactively prompt for SERVER:PORT
+if :PORT is not specified fallback to `sieve-manage-default-port'."
+  (interactive
+   (split-string (read-string "Server: ") ":"))
   (switch-to-buffer (get-buffer-create sieve-buffer))
   (sieve-manage-mode)
   (sieve-setup-buffer server port)
-- 
2.45.2

>From 537db1a9595e08a0169a406257e90d6b9d9f7b67 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
---
 lisp/net/sieve.el | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
index 8d44c384539..cd7053a7e65 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)
@@ -354,6 +359,9 @@ sieve-manage
 
 ;;;###autoload
 (defun sieve-upload (&optional name)
+  "Upload to script NAME to currently opened server.
+If NAME is nil detect name 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)))
@@ -372,12 +380,14 @@ sieve-upload
 
 ;;;###autoload
 (defun sieve-upload-and-bury (&optional name)
+  "Upload script NAME and bury buffer."
   (interactive)
   (sieve-upload name)
   (bury-buffer))
 
 ;;;###autoload
 (defun sieve-upload-and-kill (&optional name)
+  "Upload script NAME and kill buffer."
   (interactive)
   (sieve-upload name)
   (kill-buffer))
-- 
2.45.2

>From 4c5a9c6267989d888b0b8aaa4a5b91508cd62d6e 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] * lisp/net/sieve.el: Bind sieve-refresh-scriptlist to
 refresh buffer

(sieve-manage-mode-map: Bind `sieve-refersh-scriptlist' to 'g' to refresh
buffer.
---
 lisp/net/sieve.el | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lisp/net/sieve.el b/lisp/net/sieve.el
index cd7053a7e65..98f1832d58d 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
-- 
2.45.2