Add more info on using rcirc with soju v1 PROPOSED

Sandra Snan: 1
 Add more info on using rcirc with soju

 1 files changed, 42 insertions(+), 0 deletions(-)

[PATCH] Add more info on using rcirc with soju Export this patch

This works, I have been testing this code for over a year across three
networks, all with the same "<server>" name in the car position. I've
also tested the autodetaching through all kinds of buffer killing and
Emacs crashing. I've had this up at a blog post since October 2022.
---
 contrib/clients.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/contrib/clients.md b/contrib/clients.md
index fc35e56..97e515e 100644
--- a/contrib/clients.md
+++ b/contrib/clients.md
@@ -48,6 +48,48 @@ The only thing needed here is the general config:
 
 Then run `M-x irc`.
 
+Here, `"<server>"` means the server that is running soju. You can have multiple
+entries for different networks, just set the user-name correspondingly (and the
+`"<nick>"` if that's different). Even though the var is called
+`rcirc-server-alist`, it's not really an alist, it's just a list, and it's OK
+that multiple entries have the same `"<server>"`.
+
+Here's how to detach an rcirc channel when using soju:
+
+    (defun-rcirc-command detach (channel)
+       "Detach channel to soju."
+      (interactive "sPart channel: ")
+      (let ((channel (if (> (length channel) 0) channel target)))
+        (rcirc-send-privmsg
+         process "BouncerServ"
+         (format
+          "channel update %s -detached true -reattach-on highlight" channel))))
+
+Soju/rcirc already lets you reattached detached channels with `/join`,
+and this lets you type `/detach` in a channel to detach it. This makes
+it easy to attach and detach channels.
+
+Also, rcirc parts the channel when you kill the buffer or change the major mode.
+To instead detach the channel when you do that, change `rcirc-clean-up-buffer`
+to this (after definining detach above):
+
+    (defun rcirc-clean-up-buffer (reason)
+      (let ((buffer (current-buffer)))
+        (rcirc-clear-activity buffer)
+        (when (and (rcirc-buffer-process)
+    	       (rcirc--connection-open-p (rcirc-buffer-process)))
+          (with-rcirc-server-buffer
+    	(setq rcirc-buffer-alist
+    	      (rassq-delete-all buffer rcirc-buffer-alist)))
+          (rcirc-update-short-buffer-names)
+          (when (rcirc-channel-p rcirc-target)
+    	(rcirc-cmd-detach rcirc-target)))
+        (setq rcirc-target nil)))
+
+This means that whenever you kill a channel buffer, you'll just detach it and
+still be idling in it; when you actually do want to leave a channel, `/part` it
+before you kill it.
+
 # [gamja]
 
 gamja has been designed together with soju, so should have excellent
-- 
2.39.2