GNU bug report logs - #30792
26.0.91; improve docstring of with-help-window

Previous Next

Full log

View this message in rfc822 format

From: Nick Helm <nick <at> tenpoint.co.nz>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 30792 <at> debbugs.gnu.org
Subject: bug#30792: 26.0.91; improve docstring of with-help-window
Date: Wed, 14 Mar 2018 13:09:15 +1300

On Wed, 14 Mar 2018 at 05:53:32 +1300, Eli Zaretskii wrote:

> It strikes me that instead of repeating most of what
> with-temp-buffer-window's doc string says, it might be better to
> simply refer to there.  Like this:
>
>   Display the output produced by evaluating BODY, like
>   `with-temp-buffer-window' does, then put the window in
>   `help-mode' [...]

Ok, how's this? (wording borrowed from other macros that use
`with-temp-buffer-window'):

--- a/lisp/help.el	2018-03-14 13:03:14.000000000 +1300
+++ b/lisp/help.el	2018-03-14 13:06:03.000000000 +1300
@@ -1370,15 +1370,10 @@

 ;; (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)
-  "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."
+(defmacro with-help-window (buffer-or-name &rest body)
+  "Evaluate BODY, send output to BUFFER-OR-NAME and show in a help window.
+This construct is like `with-current-buffer-window' but unlike that
+puts the buffer specified by BUFFER-OR-NAME in `help-mode'."
   (declare (indent 1) (debug t))
   `(progn
      ;; Make `help-window-point-marker' point nowhere.  The only place
@@ -1390,7 +1385,7 @@
 	    (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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.