bug#61552: Feature request: Add variable Man-prefer-synchronous-call

[Sebastian Tennant]

Quoth Robert Pluim <rpluim@gmail.com>
on Tue, 21 Feb 2023 15:47:11 +0100:
> […]
> Everything in Emacs should be in the manual :-)

Indeed.

> […]
> Sorry, I meant "a complete sentence, and only taking up one screen
> line, not exceeding `emacs-lisp-docstring-fill-column'", ie
>
>     Whether to call the Un*x 'man' command synchronously.
>     When this is non-nil call 'man' synchronously instead of the default
>     asynchronous behaviour.
>
> since `apropos' displays only the first line

Understood.  Hopefully this updated patch (against master) is starting
to look acceptable:

>From 80fab7ad842bd9f41a98e18bb7a09a9e07866707 Mon Sep 17 00:00:00 2001
From: Sebastian Tennant <sdt@sebyte.me>
Date: Thu, 10 Mar 2022 08:36:04 +0000
Subject: [PATCH] Add new user option Man-prefer-synchronous-call

* lisp/man.el (Man-getpage-in-background): Add new defcustom
Man-prefer-synchronous-call and modify #'Man-getpage-in-background.
Only call #'start-process when 'make-process satisfies #'fboundp AND
Man-prefer-synchronous-call is bound to nil.
---
 doc/emacs/programs.texi |  6 ++++++
 etc/NEWS                |  7 +++++++
 lisp/man.el             | 11 ++++++++++-
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index d97bd56be21..c6c67047c43 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1387,6 +1387,12 @@ Man Page
 @kbd{M-p} to switch between man pages in different sections.  The mode
 line shows how many manual pages are available.
 
+@vindex Man-prefer-synchronous-call
+  By default, @kbd{M-x man} calls the @code{man} program
+asynchronously.  If you would prefer it if @kbd{M-x man} called the
+@code{man} program synchronously, you may set variable
+@code{Man-prefer-synchronous-calls} to a non-@code{nil} value.
+
 @findex woman
 @cindex manual pages, on MS-DOS/MS-Windows
   An alternative way of reading manual pages is the @kbd{M-x woman}
diff --git a/etc/NEWS b/etc/NEWS
index 4b0e4e6bd46..51526079313 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -192,6 +192,13 @@ This command adds a docstring comment to the current 
defun.  If a
 comment already exists, point is only moved to the comment.  It is
 bound to 'C-c C-d' in 'go-ts-mode'.
 
+** Man-mode
+
++++
+*** New user option 'Man-prefer-synchronous-call'.
+When this is non-nil, call the 'man' program synchronously rather than
+asynchronously, which is the default behaviour.
+
 
 * New Modes and Packages in Emacs 30.1
 
diff --git a/lisp/man.el b/lisp/man.el
index 9f75c07c791..5e5c10aac36 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -97,6 +97,14 @@ man
   :group 'external
   :group 'help)
 
+(defcustom Man-prefer-synchronous-call nil
+  "Whether to call the Un*x 'man' program synchronously.
+When this is non-nil, call the 'man' program synchronously
+(rather than asynchronously, which is the default behaviour)."
+  :type 'boolean
+  :group 'man
+  :version 30.1)
+
 (defcustom Man-filter-list nil
   "Manpage cleaning filter command phrases.
 This variable contains a list of the following form:
@@ -1118,7 +1126,8 @@ Man-getpage-in-background
                                        "[cleaning...]")
                                      'face 'mode-line-emphasis)))
        (Man-start-calling
-        (if (fboundp 'make-process)
+        (if (and (fboundp 'make-process)
+                  (not Man-prefer-synchronous-call))
             (let ((proc (start-process
                          manual-program buffer
                          (if (memq system-type '(cygwin windows-nt))
-- 
2.30.2