Subject: bug#30792: 26.0.91; improve docstring of with-help-window

From: Nick Helm <[email-masked]>
Date: Mon, 19 Mar 2018 00:19:03 +1300

Two patches attached.

Thanks,
Nick

>From 3b96b7ddeb2dc0049b036e1f552b7029031042ec Mon Sep 17 00:00:00 2001
From: Nick Helm <[email-masked]>
Date: Sun, 18 Mar 2018 17:26:34 +1300
Subject: [PATCH 1/2] Align `with-help-window' variable names with
 `with-temp-buffer-window'.

* doc/lispref/help.texi (Help Functions):
* lisp/help.el (with-help-window): Change variable name to buffer-or-name.
---
 doc/lispref/help.texi | 4 ++--
 lisp/help.el          | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 33cc2f0d55..ea5e525735 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -744,10 +744,10 @@ This function returns the name of the help buffer, which is normally
 @end defun
 
 @vindex help-window-select
-@defmac with-help-window buffer-name body@dots{}
+@defmac with-help-window buffer-or-name body@dots{}
 This macro evaluates @var{body} like @code{with-output-to-temp-buffer}
 (@pxref{Temporary Displays}), inserting any output produced by its forms
-into a buffer named @var{buffer-name}.  (Usually, @var{buffer-name}
+into a buffer named @var{buffer-or-name}.  (Usually, @var{buffer-or-name}
 should be the value returned by the function @code{help-buffer}.)  It
 also puts the specified buffer into Help mode and displays a message
 telling the user how to quit and scroll the help window.  It selects the
diff --git a/lisp/help.el b/lisp/help.el
index 014af5141e..55abecc05d 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1370,7 +1370,7 @@ Return VALUE."
 
 ;; (4) A marker (`help-window-point-marker') to move point in the help
 ;;     window to an arbitrary buffer position.
-(defmacro with-help-window (buffer-name &rest body)
+(defmacro with-help-window (buffer-or-name &rest body)
   "Display buffer named BUFFER-NAME in a help window.
 Evaluate the forms in BODY with standard output bound to a buffer
 called BUFFER-NAME (creating it if it does not exist), put that
@@ -1390,7 +1390,7 @@ the help window if the current value of the user option
 	    (cons 'help-mode-finish temp-buffer-window-show-hook)))
        (setq help-window-old-frame (selected-frame))
        (with-temp-buffer-window
-	,buffer-name nil 'help-window-setup (progn ,@body)))))
+	,buffer-or-name nil 'help-window-setup (progn ,@body)))))
 
 ;; Called from C, on encountering `help-char' when reading a char.
 ;; Don't print to *Help*; that would clobber Help history.
-- 
2.14.3 (Apple Git-98)

>From cbbb8d229f2b34f944493ea3415c18a80b776359 Mon Sep 17 00:00:00 2001
From: Nick Helm <[email-masked]>
Date: Sun, 18 Mar 2018 21:05:44 +1300
Subject: [PATCH 2/2] Improve `with-help-window' docstring.

* lisp/help.el (with-help-window): Rewrite docstring, adding reference to
`help-window-setup'.
---
 lisp/help.el | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/lisp/help.el b/lisp/help.el
index 55abecc05d..958b06c095 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1371,14 +1371,13 @@ Return VALUE."
 ;; (4) A marker (`help-window-point-marker') to move point in the help
 ;;     window to an arbitrary buffer position.
 (defmacro with-help-window (buffer-or-name &rest body)
-  "Display buffer named BUFFER-NAME in a help window.
-Evaluate the forms in BODY with standard output bound to a buffer
-called BUFFER-NAME (creating it if it does not exist), put that
-buffer in `help-mode', display the buffer in a window (see
-`with-temp-buffer-window' for details) and issue a message how to
-deal with that \"help\" window when it's no more needed.  Select
-the help window if the current value of the user option
-`help-window-select' says so.  Return last value in BODY."
+  "Evaluate BODY, send output to BUFFER-OR-NAME and show in a help window.
+This construct is like `with-temp-buffer-window' but unlike that
+puts the buffer specified by BUFFER-OR-NAME in `help-mode' and
+displays a message about how to delete the help window when it's no
+longer needed.  The help window will be selected if
+`help-window-select' is non-nil.  See `help-window-setup' for
+more options."
   (declare (indent 1) (debug t))
   `(progn
      ;; Make `help-window-point-marker' point nowhere.  The only place
-- 
2.14.3 (Apple Git-98)