unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#30792: 26.0.91; improve docstring of with-help-window
@ 2018-03-13  9:39 Nick Helm
  2018-03-13 10:17 ` martin rudalics
  0 siblings, 1 reply; 13+ messages in thread
From: Nick Helm @ 2018-03-13  9:39 UTC (permalink / raw)
  To: 30792


I find the docstring of `with-help-window' a little hard to follow, so I
had a go at improving it. This also renames the var BUFFER-NAME to
BUFFER-OR-NAME to match `with-temp-buffer-window' and others.

--- a/lisp/help.el	2018-03-13 19:52:32.000000000 +1300
+++ b/lisp/help.el	2018-03-13 21:54:07.000000000 +1300
@@ -1370,15 +1370,20 @@
 
 ;; (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)
+  "Show buffer BUFFER-OR-NAME with output of BODY in a help window.
+Make the buffer specified by BUFFER-OR-NAME empty (or create it
+if it does not exist).  Evaluate BODY with `standard-output' bound
+to that buffer, so that output from `prin1' and similar functions
+in BODY go into that buffer.  The buffer is not made current while
+BODY is evaluated.  Finally, display the buffer in a window and
+put it in `help-mode'.  Return the value returned by BODY.
+
+The help window will be selected if `help-window-select' is
+non-nil.  However, if the help window displays on a different
+frame, the window manager may automatically select that frame.
+
+See `with-temp-buffer-window' for more details."
   (declare (indent 1) (debug t))
   `(progn
      ;; Make `help-window-point-marker' point nowhere.  The only place





^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2018-03-20 12:28 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-03-13  9:39 bug#30792: 26.0.91; improve docstring of with-help-window Nick Helm
2018-03-13 10:17 ` martin rudalics
2018-03-13 10:31   ` Nick Helm
2018-03-13 16:53     ` Eli Zaretskii
2018-03-14  0:09       ` Nick Helm
2018-03-14  8:14         ` martin rudalics
2018-03-14 16:18           ` Eli Zaretskii
2018-03-14 20:05             ` martin rudalics
2018-03-14 23:12               ` Nick Helm
2018-03-15  8:20                 ` martin rudalics
2018-03-18 11:19               ` Nick Helm
2018-03-20 12:28                 ` Eli Zaretskii
2018-03-14 15:56         ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).