bug#44202: [PATCH] Add variable to control confirmation of help-mode-revert-buffer

[Kevin Foley]

Drew Adams <drew.adams@oracle.com> writes:

> I think the first line of the doc string should
> say what a true value means, because the option
> name does that.

> Or at least the doc string should somehow make
> clear which Boolean value means which behavior.

> E.g.:

> Non-nil means do not prompt for confirmation when reverting a help
> buffer.

I agree this is better and also matches the recommendation in
`(elisp)Documentation Tips', I've updated the patch to reflect this.


Stefan Kangas <stefan@marxist.se> writes:

> Your patch seems to be lacking ChangeLog entries as described in
> etc/CONTRIBUTE.  You would help us if you could add such entries,
> especially if you are planning to do more changes.

I've updated the commit message per the CONTRIBUTE file, let me know if
there are any changes needed.

As a side note, it may be helpful to mention this file in the
`(emacs)Sending Patches for GNU Emacs' info node.  That was the page I
was referencing for info before submitting this.

>> +(defcustom help-mode-revert-buffer-noconfirm nil
>
> This would change the default, right?  Any rationale for that?

The default should be the same.  I've updated the docstring which I
think makes this clearer.

>> +  "Indicates whether to prompt for confirmation when reverting a
>> +help buffer."
>
> The first sentence of a doc string should fit on one line.

Updated with Drew's suggestion.

>>  (defun help-mode-revert-buffer (_ignore-auto noconfirm)
>> -  (when (or noconfirm (yes-or-no-p "Revert help buffer? "))
>> +  "Revert help-mode buffer.  See
>> +`help-mode-revert-buffer-noconfirm' to control whether user is
>> +prompted for confirmation."
>
> The first line should be one sentence only, and the second sentence
> start on the second line.

Updated to match these conventions.

Thank you both for the feedback, let me know if there any other changes
that should be made.

>From 42f226804ac20c2650ccfb063668e24e915b2cb2 Mon Sep 17 00:00:00 2001
From: "Kevin J. Foley" <kevin@kevinjfoley.me>
Date: Sat, 24 Oct 2020 16:14:31 -0400
Subject: [PATCH] Add option to disable confirmation prompt when reverting help
 buffer

    * lisp/help-mode.el (help-mode-revert-buffer-noconfirm):
    (help-mode-revert-buffer): Add variable and reference it in revert
    function.
---
 lisp/help-mode.el | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 0dc6c9ffae..729529e4db 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -98,6 +98,12 @@ The format is (FUNCTION ARGS...).")
   "Hook run by `help-mode'."
   :type 'hook
   :group 'help)
+
+(defcustom help-mode-revert-buffer-noconfirm nil
+  "Non-nil means do not prompt for confirmation when reverting a help buffer."
+  :type 'boolean
+  :group 'help
+  :version "28.1")
 
 ;; Button types used by help
 
@@ -757,7 +763,11 @@ Show all docs for that symbol as either a variable, 
function or face."
       (user-error "No symbol here"))))
 
 (defun help-mode-revert-buffer (_ignore-auto noconfirm)
-  (when (or noconfirm (yes-or-no-p "Revert help buffer? "))
+  "Revert help-mode buffer.
+See `help-mode-revert-buffer-noconfirm' to control confirmation prompt."
+  (when (or noconfirm
+            help-mode-revert-buffer-noconfirm
+            (yes-or-no-p "Revert help buffer? "))
     (let ((pos (point))
          (item help-xref-stack-item)
          ;; Pretend there is no current item to add to the history.
-- 
2.28.0