From e24c2c282673fb3ed22e7361a5b65af88da2c90c Mon Sep 17 00:00:00 2001
From: "Dirk-Jan C. Binnema" <djcb@djcbsoftware.nl>
Date: Mon, 22 Dec 2025 15:01:51 +0200
Subject: [PATCH] mu4e-get-mail-command: improve documentation

Make a bit clearer and add an example of using a function.
---
 mu4e/mu4e-update.el | 13 +++++++------
 mu4e/mu4e.texi      | 33 +++++++++++++++++++++++++++++----
 2 files changed, 36 insertions(+), 10 deletions(-)

diff --git a/mu4e/mu4e-update.el b/mu4e/mu4e-update.el
index 5c050f46..18b60fd3 100644
--- a/mu4e/mu4e-update.el
+++ b/mu4e/mu4e-update.el
@@ -36,13 +36,14 @@
   "Shell command for retrieving new mail or a function.
 
 Common values are \"offlineimap\", \"fetchmail\" or \"mbsync\", but
-arbitrary shell-commands can be used. If it is a function, it should
-return a string specifying the same.
+arbitrary shell commands can be used. If it is a function, it should
+return a string specifying a shell command.
 
-When set to the literal string \"true\" (the default), the
-command simply finishes successfully (running the \"true\"
-command) without retrieving any mail. This can be useful when
-mail is already retrieved in another way, such as a local MDA."
+The default is the string \"true\", which refers to the
+`man:true(1)' shell command, which does nothing but return
+success. This default is all you need if mail is already
+retrieved in some other way outside mu4e, such as through a local
+MDA, but otherwise you need to customize it as described."
   :type '(choice
           (string :tag "Shell command")
           (function :tag "Function that returns a string (shell command)"))
diff --git a/mu4e/mu4e.texi b/mu4e/mu4e.texi
index f8d11a5d..a4f515c1 100644
--- a/mu4e/mu4e.texi
+++ b/mu4e/mu4e.texi
@@ -571,12 +571,37 @@ indicate `no mail'; we can handle that with:
 A similar approach can be used with other mail retrieval programs,
 although not all of them have their exit codes documented.
 
+@subsection Conditional mail retrieval
+
+The value of @code{mu4e-get-mail-command} can also be a @emph{function} that
+returns a shell command. This allows for more sophistication. For
+instance, you may want to attempt to retrieve mail only when online.
+
+Let us look at an example.
+
+On many GNU/Linux systems the online-status an be checked using @emph{Network
+Manager}'s @command{nm-online}, which returns non-zero when you are online.
+
+Thus, we could use something like:
+@lisp
+(setq mu4e-get-mail-command
+  (lambda ()
+    (if (zerop (shell-command "nm-online -q"))
+		"mbsync -a"
+                "true")))
+@end lisp
+
+Of course, the can be customized to the particulars of your system.
+
 @subsection Implicit mail retrieval
 
-If you don't have a specific command for getting mail, for example
-because you are running your own mail-server, you can leave
-@code{mu4e-get-mail-command} at @t{"true"} (the default), in which case
-@code{mu4e} won't try to get new mail, but still re-index your messages.
+Not everyone needs to run a shell command for getting mail. For example, you may
+be running your own mail-server, or you already have some other way to
+periodically retrieve messages.
+
+In that case, you can leave @code{mu4e-get-mail-command} at @t{"true"} (the
+default), in which case @code{mu4e} does not attempt to retrieve new mail, but
+still re-indexes your messages as per @code{mu4e-update-interval}.
 
 @subsection Speeding up indexing
 @anchor{Speeding up indexing}