From b52920bfcfc804cefa68fa3615c921e89f462b37 Mon Sep 17 00:00:00 2001
From: "Dirk-Jan C. Binnema" <djcb@djcbsoftware.nl>
Date: Sun, 17 Aug 2025 12:01:27 +0300
Subject: [PATCH] scm: update documentation

Describe the new --listen flag, and give some example of its usage, including
some snippet for using it with Emacs/Geiser.
---
 man/mu-scm.1.org | 15 ++++++++
 scm/mu-scm.texi  | 94 ++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 106 insertions(+), 3 deletions(-)

diff --git a/man/mu-scm.1.org b/man/mu-scm.1.org
index 42e7652e..90fe4df0 100644
--- a/man/mu-scm.1.org
+++ b/man/mu-scm.1.org
@@ -25,6 +25,19 @@ Using *mu scm*, you can script *mu*.
 
 * SCM OPTIONS
 
+** --listen
+
+With the ~--listen~ parameter, *mu scm* starts listening on a UNIX domain socket.
+This can be used for communicating with the REPL using some external tool, such
+as Emacs with the "Geiser" package. For details, refer to the *mu-scm* Info
+manual.
+
+It blocks after printing the name of the socket (which is a randomized name),
+prefixed by *UNIX_CONNECT:* and ending with a newline. For instance:
+#+begin_example
+UNIX-CONNECT:/run/user/1000/mu-scm-socket-4eb5db40
+#+end_example
+
 #+include: "muhome.inc" :minlevel 2
 
 #+include: "common-options.inc" :minlevel 1
@@ -45,4 +58,6 @@ should give you access to the complete manual.
 
 http://www.schemers.org provides a general introduction to the Scheme language.
 
+{{{man-link(emacs,1)}}}
+
 #+include: "prefooter.inc" :minlevel 1
diff --git a/scm/mu-scm.texi b/scm/mu-scm.texi
index da2eb032..36c56972 100644
--- a/scm/mu-scm.texi
+++ b/scm/mu-scm.texi
@@ -104,7 +104,9 @@ Indices
 @menu
 * Using distributions::
 * Building it yourself::
-* Verifying support::
+* Starting the REPL::
+* Listening on a Unix Domain Socket::
+* Hooking up with GNU/Emacs and Geiser::
 @end menu
 
 This chapter walks you through the installation and basic setup.
@@ -139,8 +141,8 @@ however, you can still use it un-installed as well by setting an environment
 variable @t{MU_SCM_DIR} to the source-directory, e.g.
 @t{/home/user/sources/mu/scm}.
 
-@node Verifying support
-@section Verifying support
+@node Starting the REPL
+@section Starting the REPL
 
 After installing @t{mu}, you can check the output of @command{mu info}. If
 @t{mu-scm} is available, in the table you should find a line:
@@ -148,6 +150,92 @@ After installing @t{mu}, you can check the output of @command{mu info}. If
 | scm-support      | yes     | GNU Guile 3.x support (new)?          |
 @end example
 
+You can then start an interactive shell, also known as the
+``REPL''@footnote{Read-Eval-Print-Loop}.
+@cindex REPL
+
+@example
+$ mu scm
+[....]
+Welcome to the mu shell!
+
+GNU Guile 3.0.9
+Copyright (C) 1995-2023 Free Software Foundation, Inc.
+
+Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
+This program is free software, and you are welcome to redistribute it
+under certain conditions; type `,show c' for details.
+
+Enter `,help' for help.
+scheme@@(guile-user)>
+@end example
+
+Refer to the @xref{Shell} chapter to learn about the wonderful things you can do
+in this shell.
+
+@node Listening on a Unix Domain Socket
+@section Listening on a Unix Domain Socket
+
+Instead of using the interactive shell, it is also possible to expose the
+REPL over a Unix domain socket, using the @t{--listen} flag.
+@cindex Unix domain sockets
+
+When you start @command{mu scm} with the @t{--listen} flag, it prints a
+(randomized) UNIX domain socket name and blocks after that; for instance:
+@example
+$mu scm --listen
+UNIX-CONNECT:/run/user/1000/mu-scm-socket-6ef6222e
+@end example
+
+You can connect to this with exernal tools, for instance with @command{socat}:
+@example
+socat - UNIX-CONNECT:/run/user/1000/mu-scm-socket-6ef6222e
+GNU Guile 3.0.9
+Copyright (C) 1995-2023 Free Software Foundation, Inc.
+
+Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
+This program is free software, and you are welcome to redistribute it
+under certain conditions; type `,show c' for details.
+
+Enter `,help' for help.
+scheme@@(guile-user)>
+@end example
+
+That is not much of improvement over the normal Guile shell, but you can of
+course use more advanced tools; @xref{Hooking up with GNU/Emacs and Geiser}.
+
+@node Hooking up with GNU/Emacs and Geiser
+@section Hooking up with GNU/Emacs and Geiser
+@cindex GNU/Emacs
+@cindex Geiser
+
+Many people like interacting with Guile through Emacs and the ``Geiser''
+package, and that is possible with @command{mu scm} as well, using the Unix
+domain socket, as discussed in @xref{Listening on a Unix Domain Socket}.
+
+Assuming you have installed the @t{guile-geiser} package, the following snippet
+makes that easy:
+@lisp
+(require 'guiser-guile)
+
+(defvar mu-scm-listen-command "mu scm --listen"
+  "mu command to start an scm repl listening on a socket.")
+
+(defun mu-scm-geiser-connect ()
+  "Start a mu scm repl and connect to it using geiser.
+Connect to mu's scm (guile) interface through Geiser."
+  (interactive)
+  (make-process
+   :name "*mu-scm-repl*"
+   :command `("sh" "-c"  ,mu-scm-listen-command)
+   :filter (lambda (_proc chunk)
+             (when (string-match "^UNIX-CONNECT:\\(.*\\)$" chunk)
+               (geiser-connect-local 'guile (match-string 1 chunk))))))
+@end lisp
+
+After evaluating this, you can use @command{M-x mu-scm-geiser-connect} to start
+the REPL, with all the Geiser bells & whistles.
+
 @node Shell
 @chapter Shell