GNU bug report logs -
#30792
26.0.91; improve docstring of with-help-window
Previous Next
Reported by: Nick Helm <nick <at> tenpoint.co.nz>
Date: Tue, 13 Mar 2018 09:40:02 UTC
Severity: minor
Found in version 26.0.91
Done: Eli Zaretskii <eliz <at> gnu.org>
Bug is archived. No further changes may be made.
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
Your message dated Tue, 20 Mar 2018 14:28:00 +0200
with message-id <83605rlynj.fsf <at> gnu.org>
and subject line Re: bug#30792: 26.0.91; improve docstring of with-help-window
has caused the debbugs.gnu.org bug report #30792,
regarding 26.0.91; improve docstring of with-help-window
to be marked as done.
(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)
--
30792: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=30792
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems
[Message part 2 (message/rfc822, inline)]
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
[Message part 3 (message/rfc822, inline)]
> From: Nick Helm <nick <at> tenpoint.co.nz>
> Cc: Eli Zaretskii <eliz <at> gnu.org>, martin rudalics <rudalics <at> gmx.at>
> Date: Mon, 19 Mar 2018 00:19:03 +1300
>
> Two patches attached.
Thanks, I pushed them to the emacs-26 branch.
Note that they needed "some work", please try to make sure these minor
nits are taken care of in your future contributions:
. always mention the bug number in the commit log message
. make sure the lines in the commit log message are shorter than 67
characters, so that they don't overflow a line when converted to a
ChangeLog file
. be sure to read the docs after renaming variables, because
frequently additional changes are needed to make the result clear
and/or palatable
. it's better not to break a changeset into separate parts, unless
really necessary, so that the result is a single commit on the
mainline
Keeping those rules will allow us to use "git am" instead of
committing manually.
This bug report was last modified 7 years and 122 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.