emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] emacs-26 2fb52ab: Improve documentation of 'with-help-wind


From: Eli Zaretskii
Subject: [Emacs-diffs] emacs-26 2fb52ab: Improve documentation of 'with-help-window'
Date: Tue, 20 Mar 2018 08:21:33 -0400 (EDT)

branch: emacs-26
commit 2fb52abd9e74f722c08c5e59f63dee8821789e1a
Author: Nick Helm <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of 'with-help-window'
    
    * doc/lispref/help.texi (Help Functions): Change variable name
    to 'buffer-or-name'.
    
    * lisp/help.el (with-help-window): Change variable name to
    'buffer-or-name' and rewrite the doc string, adding reference
    to 'help-window-setup'.  (Bug#30792)
---
 doc/lispref/help.texi | 19 ++++++++++---------
 lisp/help.el          | 19 +++++++++----------
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 33cc2f0..6dd55d0 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -744,16 +744,17 @@ This function returns the name of the help buffer, which 
is normally
 @end defun
 
 @vindex help-window-select
address@hidden with-help-window buffer-name address@hidden
address@hidden with-help-window buffer-or-name address@hidden
 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}
-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
-help window if the current value of the user option
address@hidden has been set accordingly.  It returns the last
-value in @var{body}.
+(@pxref{Temporary Displays}), inserting any output produced by its
+forms into a buffer specified by @var{buffer-or-name}, which can be a
+buffer or the name of a buffer.  (Frequently, @var{buffer-or-name} is
+the value returned by the function @code{help-buffer}.)  This macro
+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 help window if the current value of the user option
address@hidden has been set accordingly.  It returns the
+last value in @var{body}.
 @end defmac
 
 @defun help-setup-xref item interactive-p
diff --git a/lisp/help.el b/lisp/help.el
index 014af51..958b06c 100644
--- a/lisp/help.el
+++ b/lisp/help.el
@@ -1370,15 +1370,14 @@ 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)
-  "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-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
@@ -1390,7 +1389,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.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]