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

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

[Sebastian Tennant]

Patch against master (on branch master-sebyte, rebased moments ago):

 https://gitweb.sebyte.me/cgi-bin/gitweb.cgi/emacs/commitdiff/280a56c96d4530273c308addda016d889082d058

Patch against emacs-28 (on branch emacs-28-sebyte):

 https://gitweb.sebyte.me/cgi-bin/gitweb.cgi/emacs/commitdiff/a08053f12303045905907b992cc78b84692cf26a

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

[Basil Contovounesios via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Sebastian Tennant [2023-02-16 16:12 +0000] wrote:

> Patch against master (on branch master-sebyte, rebased moments ago):
>
>  https://gitweb.sebyte.me/cgi-bin/gitweb.cgi/emacs/commitdiff/280a56c96d4530273c308addda016d889082d058
>
> Patch against emacs-28 (on branch emacs-28-sebyte):
>
>  https://gitweb.sebyte.me/cgi-bin/gitweb.cgi/emacs/commitdiff/a08053f12303045905907b992cc78b84692cf26a

Please attach the patches here so that they can be tracked in this
bugtracker.

Thanks,

-- 
Basil

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

[Sebastian Tennant]

[-- Attachment #1: Type: text/plain, Size: 246 bytes --]

Quoth Basil Contovounesios <contovob@tcd.ie>
on Thu, 16 Feb 2023 17:09:27 +0000:
> […]
> Please attach the patches here so that they can be tracked in this
> bugtracker.
>
> Thanks,

No problem Basil.  Here's a patch against master:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch against master --]
[-- Type: text/x-diff, Size: 1354 bytes --]

From 179af66f885630a7bdf3d3f3146aceb8ad205ce6 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 user-customizable variable Man-prefer-synchronous-call

* lisp/man.el (Man-getpage-in-background): Only call #'start-process
when 'make-process satisfies #'fboundp AND Man-prefer-synchronous-call
is bound to nil.
---
 lisp/man.el | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/lisp/man.el b/lisp/man.el
index 286edf9314e..fb4f8f02db7 100644
--- a/lisp/man.el
+++ b/lisp/man.el
@@ -97,6 +97,12 @@ man
   :group 'external
   :group 'help)
 
+(defcustom Man-prefer-synchronous-call nil
+  "Non-nil means always call the Un*x man command synchronously,
+rather than asynchronously, which is the default behaviour."
+  :type 'boolean
+  :group 'man)
+
 (defcustom Man-filter-list nil
   "Manpage cleaning filter command phrases.
 This variable contains a list of the following form:
@@ -1118,7 +1124,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

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

[Stefan Kangas]

Sebastian Tennant <sdt@sebyte.me> writes:

> Patch against master (on branch master-sebyte, rebased moments ago):
>
>  https://gitweb.sebyte.me/cgi-bin/gitweb.cgi/emacs/commitdiff/280a56c96d4530273c308addda016d889082d058
>
> Patch against emacs-28 (on branch emacs-28-sebyte):
>
>  https://gitweb.sebyte.me/cgi-bin/gitweb.cgi/emacs/commitdiff/a08053f12303045905907b992cc78b84692cf26a

Thanks.  Could you explain the use case for this?

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

[Robert Pluim]

>>>>> On Mon, 20 Feb 2023 18:11:17 +0000, Sebastian Tennant <sdt@sebyte.me> said:

    Sebastian> Quoth Basil Contovounesios <contovob@tcd.ie>
    Sebastian> on Thu, 16 Feb 2023 17:09:27 +0000:
    >> […]
    >> Please attach the patches here so that they can be tracked in this
    >> bugtracker.
    >> 
    >> Thanks,

    Sebastian> No problem Basil.  Here's a patch against master:

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

    Sebastian> * lisp/man.el (Man-getpage-in-background): Only call #'start-process
    Sebastian> when 'make-process satisfies #'fboundp AND Man-prefer-synchronous-call
    Sebastian> is bound to nil.

Your commit message should indicate that youʼve added a new defcustom,
and you should announce it in etc/NEWS (and add a description to the
manual, if that makes sense)

    Sebastian> ---
    Sebastian>  lisp/man.el | 9 ++++++++-
    Sebastian>  1 file changed, 8 insertions(+), 1 deletion(-)

    Sebastian> diff --git a/lisp/man.el b/lisp/man.el
    Sebastian> index 286edf9314e..fb4f8f02db7 100644
    Sebastian> --- a/lisp/man.el
    Sebastian> +++ b/lisp/man.el
    Sebastian> @@ -97,6 +97,12 @@ man
    Sebastian>    :group 'external
    Sebastian>    :group 'help)
 
    Sebastian> +(defcustom Man-prefer-synchronous-call nil
    Sebastian> +  "Non-nil means always call the Un*x man command synchronously,
    Sebastian> +rather than asynchronously, which is the default
    Sebastian> behaviour."

The first line should be a complete sentence. Something like

"Whether to call the Un*x 'manʼ command synchronously."

    Sebastian> +  :type 'boolean
    Sebastian> +  :group 'man)

This needs a :version tag

    Sebastian> +
    Sebastian>  (defcustom Man-filter-list nil
    Sebastian>    "Manpage cleaning filter command phrases.
    Sebastian>  This variable contains a list of the following form:
    Sebastian> @@ -1118,7 +1124,8 @@ Man-getpage-in-background
    Sebastian>  					"[cleaning...]")
    Sebastian>  				      'face 'mode-line-emphasis)))
    Sebastian>  	(Man-start-calling
    Sebastian> -	 (if (fboundp 'make-process)
    Sebastian> +	 (if (and (fboundp 'make-process)
    Sebastian> +                  (not Man-prefer-synchronous-call))
    Sebastian>  	     (let ((proc (start-process
    Sebastian>  			  manual-program buffer
    Sebastian>  			  (if (memq system-type '(cygwin windows-nt))
    Sebastian> -- 
    Sebastian> 2.30.2


Robert
-- 

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

[Sebastian Tennant]

Hello Stefan,

Quoth Stefan Kangas <stefankangas@gmail.com>
on Tue, 21 Feb 2023 01:53:18 -0800:
> […]
> Thanks.  Could you explain the use case for this?

A function I've written (called #’man-spot) allows me to make notes in
commentary which look like this:

;;; (man-spot "openssl" "^ +s_client")

for example.

By evaluating this form, I'm able to jump to the specific point in the
openssl manpage which describes the s_client command.

The second argument to #'man-spot is a regular expression which is
passed to #'re-search-backward.  This only works if #'manual-entry has
finished putting the manpage into a buffer.  Hence the preference for
a synchronous call to #'Man-getpage-in-background.

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

[Sebastian Tennant]

> Hence the preference for a synchronous call to
> #'Man-getpage-in-background.

Correction.

Hence the preference for THE synchronous call IN
#'Man-getpage-in-background.

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

[Sebastian Tennant]

Hello Robert,

Quoth Robert Pluim <rpluim@gmail.com>
on Tue, 21 Feb 2023 11:44:14 +0100:
> […]
>> * lisp/man.el (Man-getpage-in-background): Only call
>> #'start-process when 'make-process satisfies #'fboundp AND
>> Man-prefer-synchronous-call is bound to nil
>
> Your commit message should indicate that youʼve added a new
> defcustom

How about this:

 * lisp/man.el (Man-getpage-in-background): Add new defcustom
 Man-prefer-synchronous-call and only call #'start-process when
 'make-process satisfies #'fboundp AND Man-prefer-synchronous-call is
 bound to nil.

> and you should announce it in etc/NEWS

Rightio.  Will do.

> (and add a description to the manual, if that makes sense)

Sure.  I didn't think reading manpages would have an entry in the
manual but, sure enough, it does:

 (info "(emacs) Man Page")

I shall edit doc/emacs/programs.texi accordingly.

> […]
>> (defcustom Man-prefer-synchronous-call nil
>>   "Non-nil means always call the Un*x man command synchronously,
>>     rather than asynchronously, which is the default behaviour."
>
> The first line should be a complete sentence. Something like
>
>  "Whether to call the Un*x 'manʼ command synchronously."

How about this:

 "Control whether the Un*x 'man' command is called synchronously or
  asynchronously.  (Asynchronous is the default)."

> […]
>> :type 'boolean
>> :group 'man)
>
> This needs a :version tag

Noted.

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

[Robert Pluim]

>>>>> On Tue, 21 Feb 2023 14:08:35 +0000, Sebastian Tennant <sdt@sebyte.me> said:

    >> (and add a description to the manual, if that makes sense)

    Sebastian> Sure.  I didn't think reading manpages would have an entry in the
    Sebastian> manual but, sure enough, it does:

Everything in Emacs should be in the manual :-)

    Sebastian>  (info "(emacs) Man Page")

    Sebastian> I shall edit doc/emacs/programs.texi accordingly.

    >> […]
    >>> (defcustom Man-prefer-synchronous-call nil
    >>> "Non-nil means always call the Un*x man command synchronously,
    >>> rather than asynchronously, which is the default behaviour."
    >> 
    >> The first line should be a complete sentence. Something like
    >> 
    >> "Whether to call the Un*x 'manʼ command synchronously."

    Sebastian> How about this:

    Sebastian>  "Control whether the Un*x 'man' command is called synchronously or
    Sebastian>   asynchronously.  (Asynchronous is the default)."

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

Robert
-- 

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

[Sebastian Tennant]

[-- Attachment #1: Type: text/plain, Size: 610 bytes --]

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:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-new-user-option-Man-prefer-synchronous-call.patch --]
[-- Type: text/x-diff, Size: 2857 bytes --]

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.
+
 \f
 * 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

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

[Eli Zaretskii]

> From: Sebastian Tennant <sdt@sebyte.me>
> Date: Wed, 22 Feb 2023 17:16:24 +0000
> 
> 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:

Thanks, installed on the master branch, and closing the bug.

Assuming that you want to be able to submit contributions to Emacs in
the future, would you like to start the legal paperwork of assigning
the copyright for your changes to the FSF?  If yes, I will send you
the form to fill to start the paperwork.

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

[Sebastian Tennant]

Hello Eli,

Quoth Eli Zaretskii <eliz@gnu.org>
on Thu, 02 Mar 2023 13:30:46 +0200:
>> From: Sebastian Tennant <sdt@sebyte.me>
>> Date: Wed, 22 Feb 2023 17:16:24 +0000
>> […]
>> Understood.  Hopefully this updated patch (against master) is
>> starting to look acceptable:
>
> Thanks, installed on the master branch, and closing the bug.

Great!  Thank you.

> Assuming that you want to be able to submit contributions to Emacs
> in the future, would you like to start the legal paperwork of
> assigning the copyright for your changes to the FSF?

Yes, I would.

> If yes, I will send you the form to fill to start the paperwork.

Thank you again.

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

[Eli Zaretskii]

> From: Sebastian Tennant <sdt@sebyte.me>
> Cc: 61552-done@debbugs.gnu.org
> Date: Fri, 03 Mar 2023 08:51:36 +0000
> 
> > Assuming that you want to be able to submit contributions to Emacs
> > in the future, would you like to start the legal paperwork of
> > assigning the copyright for your changes to the FSF?
> 
> Yes, I would.
> 
> > If yes, I will send you the form to fill to start the paperwork.
> 
> Thank you again.

Thanks, form sent off-list.