bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

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

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

Tags: patch

Hi,

This patch adds a user option for disabling the *Patch Help* buffer that
`submit-emacs-patch` displays.


In GNU Emacs 30.0.50 (build 23, x86_64-apple-darwin22.5.0, NS
 appkit-2299.60 Version 13.4 (Build 22F66)) of 2023-08-19 built on
 Dazzs-MacBook-Pro.local
Repository revision: 44697457c6048464a68b6d58a1c4cf967fd5be06
Repository branch: submit-emacs-patch-display-help
Windowing system distributor 'Apple', version 10.3.2299
System Description:  macOS 13.4

Configured using:
 'configure 'CFLAGS=-g0 -O3' --with-native-compilation --with-json
 --with-imagemagick --with-tree-sitter --enable-link-time-optimization'


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-New-user-option-submit-emacs-patch-display-help.patch --]
[-- Type: text/patch, Size: 4796 bytes --]

From 28bf05cdafa8b9d00a47a932d20569097289b6d4 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Sat, 19 Aug 2023 21:24:34 +0200
Subject: [PATCH] New user option 'submit-emacs-patch-display-help'

This lets users prevent 'submit-emacs-patch' from displaying a buffer
with instructions about submitting patches when they no longer need it.

* lisp/mail/emacsbug.el (submit-emacs-patch-display-help): New user
option.
(submit-emacs-patch): Use it.
* doc/emacs/trouble.texi (Sending Patches): Document it.
* etc/NEWS: Announce it.
---
 doc/emacs/trouble.texi |  7 +++++++
 etc/NEWS               |  6 ++++++
 lisp/mail/emacsbug.el  | 45 +++++++++++++++++++++++-------------------
 3 files changed, 38 insertions(+), 20 deletions(-)

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index d2e8ac3452a..279b17dca2d 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1336,6 +1336,13 @@ Sending Patches
 form that is clearly safe to install.
 @end itemize
 
+@vindex submit-emacs-patch-display-help
+By default, @kbd{M-x submit-emacs-patch} displays a buffer with some
+instructions alongside the Message mode buffer.  If you're already
+familiar with these instructions after submitting a patch or two, you
+can disable this help by customizing the user option
+@code{submit-emacs-patch-display-help} to @code{nil}.
+
 @node Contributing
 @section Contributing to Emacs Development
 @cindex contributing to Emacs
diff --git a/etc/NEWS b/etc/NEWS
index 6588299c532..ab868b9f3a4 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -99,6 +99,12 @@ This allows the user to customize the prompt that is appended by
 'yes-or-no-p' when asking questions.  The default value is
 "(yes or no) ".
 
++++
+** New user option 'submit-emacs-patch-display-help'.
+You can set this user option to nil to prevent 'submit-emacs-patch'
+from displaying a help buffer with instructions for submitting
+patches.
+
 ---
 ** New face 'display-time-date-and-time'.
 This is used for displaying the time and date components of
diff --git a/lisp/mail/emacsbug.el b/lisp/mail/emacsbug.el
index bebaad720db..9c2120530a6 100644
--- a/lisp/mail/emacsbug.el
+++ b/lisp/mail/emacsbug.el
@@ -50,6 +50,10 @@ report-emacs-bug-no-explanations
   "If non-nil, suppress the explanations given for the sake of novice users."
   :type 'boolean)
 
+(defcustom submit-emacs-patch-display-help t
+  "If non-nil, `submit-emacs-patch' displays some help in another buffer."
+  :type 'boolean)
+
 ;; User options end here.
 
 (defvar report-emacs-bug-orig-text nil
@@ -509,26 +513,27 @@ submit-emacs-patch
      (list (read-string (format-prompt "This patch is about" guess)
                         nil nil guess)
            file)))
-  (switch-to-buffer "*Patch Help*")
-  (let ((inhibit-read-only t))
-    (erase-buffer)
-    (insert "Thank you for considering submitting a patch to the Emacs project.\n\n"
-            "Please describe what the patch fixes (or, if it's a new feature, what it\n"
-            "implements) in the mail buffer below.  When done, use the "
-            (substitute-command-keys "\\<message-mode-map>\\[message-send-and-exit] command\n")
-            "to send the patch as an email to the Emacs issue tracker.\n\n"
-            "If this is the first time you're submitting an Emacs patch, please\n"
-            "read the ")
-    (insert-text-button
-     "CONTRIBUTE"
-     'action (lambda (_)
-               (view-buffer
-                (find-file-noselect
-                 (expand-file-name "CONTRIBUTE" installation-directory)))))
-    (insert " file first.\n")
-    (goto-char (point-min))
-    (view-mode 1)
-    (button-mode 1))
+  (when submit-emacs-patch-display-help
+    (switch-to-buffer "*Patch Help*")
+    (let ((inhibit-read-only t))
+      (erase-buffer)
+      (insert "Thank you for considering submitting a patch to the Emacs project.\n\n"
+              "Please describe what the patch fixes (or, if it's a new feature, what it\n"
+              "implements) in the mail buffer below.  When done, use the "
+              (substitute-command-keys "\\<message-mode-map>\\[message-send-and-exit] command\n")
+              "to send the patch as an email to the Emacs issue tracker.\n\n"
+              "If this is the first time you're submitting an Emacs patch, please\n"
+              "read the ")
+      (insert-text-button
+       "CONTRIBUTE"
+       'action (lambda (_)
+                 (view-buffer
+                  (find-file-noselect
+                   (expand-file-name "CONTRIBUTE" installation-directory)))))
+      (insert " file first.\n")
+      (goto-char (point-min))
+      (view-mode 1)
+      (button-mode 1)))
   (compose-mail-other-window report-emacs-bug-address subject)
   (message-goto-body)
   (insert "\n\n\n")
-- 
2.41.0

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Eli Zaretskii]

> Date: Sat, 19 Aug 2023 21:33:14 +0200
> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
> 
> This patch adds a user option for disabling the *Patch Help* buffer that
> `submit-emacs-patch` displays.

Thanks, but why is it important to be able to disable the
instructions, enough to justify this new option?  I expect experienced
people not to use this command at all, so its main purpose is for the
newbies.

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

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

Eli Zaretskii <eliz@gnu.org> writes:

>> Date: Sat, 19 Aug 2023 21:33:14 +0200
>> From:  Eshel Yaron via "Bug reports for GNU Emacs,
>>  the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>
>> 
>> This patch adds a user option for disabling the *Patch Help* buffer that
>> `submit-emacs-patch` displays.
>
> Thanks, but why is it important to be able to disable the
> instructions, enough to justify this new option?  I expect experienced
> people not to use this command at all, so its main purpose is for the
> newbies.

Ah I actually find this command quite convenient, except for that
instructions buffer that tends to get in my way.  So I guess this option
is useful for us semi-newbies :)

I don't know if it justifies a new option, as you say, and I don't mind
keeping a modified `submit-emacs-patch` in my config.

I do wonder, since `(info "(emacs)Sending Patches")` recommends using
`submit-emacs-patch` and that always seemed easier than doing `C-x m`
and adding the destination address and the attachment patch afterwards,
what alternative you'd expect experienced users to go with?


Thanks,

Eshel

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Eli Zaretskii]

> From: Eshel Yaron <me@eshelyaron.com>
> Cc: 65387@debbugs.gnu.org
> Date: Sat, 19 Aug 2023 22:56:18 +0200
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> This patch adds a user option for disabling the *Patch Help* buffer that
> >> `submit-emacs-patch` displays.
> >
> > Thanks, but why is it important to be able to disable the
> > instructions, enough to justify this new option?  I expect experienced
> > people not to use this command at all, so its main purpose is for the
> > newbies.
> 
> Ah I actually find this command quite convenient, except for that
> instructions buffer that tends to get in my way.  So I guess this option
> is useful for us semi-newbies :)
> 
> I don't know if it justifies a new option, as you say, and I don't mind
> keeping a modified `submit-emacs-patch` in my config.
> 
> I do wonder, since `(info "(emacs)Sending Patches")` recommends using
> `submit-emacs-patch` and that always seemed easier than doing `C-x m`
> and adding the destination address and the attachment patch afterwards,
> what alternative you'd expect experienced users to go with?

Let's see what others think about this new command.

Would people please voice their opinions about adding it?

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Visuwesh]

[ஞாயிறு ஆகஸ்ட் 20, 2023] Eli Zaretskii wrote:
 
>> Ah I actually find this command quite convenient, except for that
>> instructions buffer that tends to get in my way.  So I guess this option
>> is useful for us semi-newbies :)
>> 
>> I don't know if it justifies a new option, as you say, and I don't mind
>> keeping a modified `submit-emacs-patch` in my config.
>> 
>> I do wonder, since `(info "(emacs)Sending Patches")` recommends using
>> `submit-emacs-patch` and that always seemed easier than doing `C-x m`
>> and adding the destination address and the attachment patch afterwards,
>> what alternative you'd expect experienced users to go with?
>
> Let's see what others think about this new command.
>
> Would people please voice their opinions about adding it?

I was thinking of proposing such a patch myself sometime™.  I think I
would end up using the command more if I could turn off the help buffer.
Though, I think the user option report-emacs-bug-no-explanations could
be reused instead.

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Daniel Martín via Bug reports for GNU Emacs, the Swiss army knife of text editors]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Eshel Yaron <me@eshelyaron.com>
>> Cc: 65387@debbugs.gnu.org
>> Date: Sat, 19 Aug 2023 22:56:18 +0200
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> This patch adds a user option for disabling the *Patch Help* buffer that
>> >> `submit-emacs-patch` displays.
>> >
>> > Thanks, but why is it important to be able to disable the
>> > instructions, enough to justify this new option?  I expect experienced
>> > people not to use this command at all, so its main purpose is for the
>> > newbies.
>> 
>> Ah I actually find this command quite convenient, except for that
>> instructions buffer that tends to get in my way.  So I guess this option
>> is useful for us semi-newbies :)
>> 
>> I don't know if it justifies a new option, as you say, and I don't mind
>> keeping a modified `submit-emacs-patch` in my config.
>> 
>> I do wonder, since `(info "(emacs)Sending Patches")` recommends using
>> `submit-emacs-patch` and that always seemed easier than doing `C-x m`
>> and adding the destination address and the attachment patch afterwards,
>> what alternative you'd expect experienced users to go with?
>
> Let's see what others think about this new command.
>
> Would people please voice their opinions about adding it?

Instead of just a toggle, we could make the new option a tristate:

- `nil`: Only displays the buffer to compose the email (what is proposed in
  this bug report).
- `help`: Displays instructions on how to send the patch (current
  behavior).  
- `patch`: Displays the patch that you want to submit in the split
  window.

Perhaps this adds useful enough functionality that adding a new
configuration option feels more justified.

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

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

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

Daniel Martín <mardani29@yahoo.es> writes:

> Instead of just a toggle, we could make the new option a tristate:
>
> - `nil`: Only displays the buffer to compose the email (what is proposed in
>   this bug report).
> - `help`: Displays instructions on how to send the patch (current
>   behavior).  
> - `patch`: Displays the patch that you want to submit in the split
>   window.

Good idea, thanks.  I've added something like that in the following
updated patch:



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: v2-0001-New-user-option-submit-emacs-patch-display-help.patch --]
[-- Type: text/x-patch, Size: 5529 bytes --]

From 10c943cbf340255d0577a03fe4b3d74af840a9e2 Mon Sep 17 00:00:00 2001
From: Eshel Yaron <me@eshelyaron.com>
Date: Sat, 19 Aug 2023 21:24:34 +0200
Subject: [PATCH v2] New user option 'submit-emacs-patch-display-help'

This lets users prevent 'submit-emacs-patch' from displaying a buffer
with instructions about submitting patches when they no longer need it.

* lisp/mail/emacsbug.el (submit-emacs-patch-display-help): New user
option.
(submit-emacs-patch): Use it.
* doc/emacs/trouble.texi (Sending Patches): Document it.
* etc/NEWS: Announce it.
---
 doc/emacs/trouble.texi |  9 +++++++
 etc/NEWS               |  7 ++++++
 lisp/mail/emacsbug.el  | 54 ++++++++++++++++++++++++++----------------
 3 files changed, 50 insertions(+), 20 deletions(-)

diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index d2e8ac3452a..042637ed8fc 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1336,6 +1336,15 @@ Sending Patches
 form that is clearly safe to install.
 @end itemize
 
+@vindex submit-emacs-patch-display-help
+By default, @kbd{M-x submit-emacs-patch} displays a buffer with some
+instructions alongside the Message mode buffer.  If you're already
+familiar with these instructions after submitting a patch or two, you
+can disable this help by customizing the user option
+@code{submit-emacs-patch-display-help} to @code{nil}.  If you set this
+option to @code{patch}, Emacs displays the patch you're about to
+submit instead of the instructions buffer.
+
 @node Contributing
 @section Contributing to Emacs Development
 @cindex contributing to Emacs
diff --git a/etc/NEWS b/etc/NEWS
index 6588299c532..5ea8a204522 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -99,6 +99,13 @@ This allows the user to customize the prompt that is appended by
 'yes-or-no-p' when asking questions.  The default value is
 "(yes or no) ".
 
++++
+** New user option 'submit-emacs-patch-display-help'.
+You can set this user option to nil to prevent 'submit-emacs-patch'
+from displaying a help buffer with instructions for submitting
+patches.  If you set this option to 'patch', Emacs displays the patch
+you're about to submit instead of the instructions buffer.
+
 ---
 ** New face 'display-time-date-and-time'.
 This is used for displaying the time and date components of
diff --git a/lisp/mail/emacsbug.el b/lisp/mail/emacsbug.el
index bebaad720db..b93aed47bac 100644
--- a/lisp/mail/emacsbug.el
+++ b/lisp/mail/emacsbug.el
@@ -50,6 +50,17 @@ report-emacs-bug-no-explanations
   "If non-nil, suppress the explanations given for the sake of novice users."
   :type 'boolean)
 
+(defcustom submit-emacs-patch-display-help t
+  "Whether `submit-emacs-patch' displays help in another buffer.
+
+If nil, display only the message buffer without additional help.  If this is
+the symbol `patch', display the patch you are submitting in another buffer.
+Any other value says to display a buffer with instructions for submitting
+patches (this is the default for the sake of novice users)."
+  :type '(choice (const :tag "Do not display help" nil)
+		 (const :tag "Display instructions" t)
+		 (const :tag "Display patch" patch)))
+
 ;; User options end here.
 
 (defvar report-emacs-bug-orig-text nil
@@ -509,26 +520,29 @@ submit-emacs-patch
      (list (read-string (format-prompt "This patch is about" guess)
                         nil nil guess)
            file)))
-  (switch-to-buffer "*Patch Help*")
-  (let ((inhibit-read-only t))
-    (erase-buffer)
-    (insert "Thank you for considering submitting a patch to the Emacs project.\n\n"
-            "Please describe what the patch fixes (or, if it's a new feature, what it\n"
-            "implements) in the mail buffer below.  When done, use the "
-            (substitute-command-keys "\\<message-mode-map>\\[message-send-and-exit] command\n")
-            "to send the patch as an email to the Emacs issue tracker.\n\n"
-            "If this is the first time you're submitting an Emacs patch, please\n"
-            "read the ")
-    (insert-text-button
-     "CONTRIBUTE"
-     'action (lambda (_)
-               (view-buffer
-                (find-file-noselect
-                 (expand-file-name "CONTRIBUTE" installation-directory)))))
-    (insert " file first.\n")
-    (goto-char (point-min))
-    (view-mode 1)
-    (button-mode 1))
+  (pcase submit-emacs-patch-display-help
+    ('patch (find-file file))
+    ((pred (not null))
+     (switch-to-buffer "*Patch Help*")
+     (let ((inhibit-read-only t))
+       (erase-buffer)
+       (insert "Thank you for considering submitting a patch to the Emacs project.\n\n"
+               "Please describe what the patch fixes (or, if it's a new feature, what it\n"
+               "implements) in the mail buffer below.  When done, use the "
+               (substitute-command-keys "\\<message-mode-map>\\[message-send-and-exit] command\n")
+               "to send the patch as an email to the Emacs issue tracker.\n\n"
+               "If this is the first time you're submitting an Emacs patch, please\n"
+               "read the ")
+       (insert-text-button
+        "CONTRIBUTE"
+        'action (lambda (_)
+                  (view-buffer
+                   (find-file-noselect
+                    (expand-file-name "CONTRIBUTE" installation-directory)))))
+       (insert " file first.\n")
+       (goto-char (point-min))
+       (view-mode 1)
+       (button-mode 1))))
   (compose-mail-other-window report-emacs-bug-address subject)
   (message-goto-body)
   (insert "\n\n\n")
-- 
2.41.0

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Juri Linkov]

>> I don't know if it justifies a new option, as you say, and I don't mind
>> keeping a modified `submit-emacs-patch` in my config.
>
> Let's see what others think about this new command.
>
> Would people please voice their opinions about adding it?

If 'submit-emacs-patch' used 'pop-to-buffer-same-window'
instead of 'switch-to-buffer' like in the patch below,
then using such simple config would be possible:

  (add-to-list 'display-buffer-alist
               '("\\*Patch Help\\*"
                 display-buffer-no-window
                 (allow-no-window . t)))

PS: This patch doesn't preclude adding an option.

diff --git a/lisp/mail/emacsbug.el b/lisp/mail/emacsbug.el
index bebaad720db..409ef7165fe 100644
--- a/lisp/mail/emacsbug.el
+++ b/lisp/mail/emacsbug.el
@@ -509,7 +509,7 @@ submit-emacs-patch
      (list (read-string (format-prompt "This patch is about" guess)
                         nil nil guess)
            file)))
-  (switch-to-buffer "*Patch Help*")
+  (pop-to-buffer-same-window "*Patch Help*")
   (let ((inhibit-read-only t))
     (erase-buffer)
     (insert "Thank you for considering submitting a patch to the Emacs project.\n\n"

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> Would people please voice their opinions about adding it?

I think it would be nice to eventually make `M-x submit-emacs-patch'
into something even more powerful, more suitable for advanced users.

I'm thinking of something closer to debbugs, so that you set some option
to your Emacs source tree, and it'll create the patches and attach them
to the current email for you.

So I think I like the idea here, as it seems to go in that direction.

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Wed, 6 Sep 2023 10:47:41 -0700
> Cc: Eshel Yaron <me@eshelyaron.com>, 65387@debbugs.gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > Would people please voice their opinions about adding it?
> 
> I think it would be nice to eventually make `M-x submit-emacs-patch'
> into something even more powerful, more suitable for advanced users.
> 
> I'm thinking of something closer to debbugs, so that you set some option
> to your Emacs source tree, and it'll create the patches and attach them
> to the current email for you.
> 
> So I think I like the idea here, as it seems to go in that direction.

TBH, I fail to see how disabling the instruction is going in the
direction you described.  But if this is part of some larger plan to
that effect, I don't mind.

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Juri Linkov]

>>> I don't know if it justifies a new option, as you say, and I don't mind
>>> keeping a modified `submit-emacs-patch` in my config.
>>
>> Let's see what others think about this new command.
>>
>> Would people please voice their opinions about adding it?
>
> If 'submit-emacs-patch' used 'pop-to-buffer-same-window'
> instead of 'switch-to-buffer' like in the patch below,
> then using such simple config would be possible:
>
>   (add-to-list 'display-buffer-alist
>                '("\\*Patch Help\\*"
>                  display-buffer-no-window
>                  (allow-no-window . t)))
>
> @@ -509,7 +509,7 @@ submit-emacs-patch
>       (list (read-string (format-prompt "This patch is about" guess)
>                          nil nil guess)
>             file)))
> -  (switch-to-buffer "*Patch Help*")
> +  (pop-to-buffer-same-window "*Patch Help*")

Now pushed.  And maybe this could be closed?

bug#65387: [PATCH] New user option 'submit-emacs-patch-display-help'

[Stefan Kangas]

Juri Linkov <juri@linkov.net> writes:

> Now pushed.  And maybe this could be closed?

Done.