From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#30792: 26.0.91; improve docstring of with-help-window Date: Tue, 13 Mar 2018 18:53:32 +0200 Message-ID: <83zi3brk6r.fsf@gnu.org> References: <5AA7A52D.6060808@gmx.at> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1520961151 6605 195.159.176.226 (13 Mar 2018 17:12:31 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 13 Mar 2018 17:12:31 +0000 (UTC) Cc: 30792@debbugs.gnu.org To: Nick Helm Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Mar 13 18:12:26 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evnTN-0001Zm-D1 for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Mar 2018 18:12:25 +0100 Original-Received: from localhost ([::1]:41354 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evnVP-0007iX-UC for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Mar 2018 13:14:31 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:42159) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evnBe-0007Hu-2H for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 12:54:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evnBa-0003rk-0w for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 12:54:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:51858) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1evnBZ-0003rS-S7 for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 12:54:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1evnBZ-00074w-KR for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 12:54:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 13 Mar 2018 16:54:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30792 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152096001527176 (code B ref 30792); Tue, 13 Mar 2018 16:54:01 +0000 Original-Received: (at 30792) by debbugs.gnu.org; 13 Mar 2018 16:53:35 +0000 Original-Received: from localhost ([127.0.0.1]:59755 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evnB9-00074G-F3 for submit@debbugs.gnu.org; Tue, 13 Mar 2018 12:53:35 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:50923) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evnB7-000742-R9 for 30792@debbugs.gnu.org; Tue, 13 Mar 2018 12:53:34 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evnAy-0003Id-Fc for 30792@debbugs.gnu.org; Tue, 13 Mar 2018 12:53:28 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:39356) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evnAy-0003IZ-C3; Tue, 13 Mar 2018 12:53:24 -0400 Original-Received: from [176.228.60.248] (port=4394 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1evnAx-00059G-OZ; Tue, 13 Mar 2018 12:53:24 -0400 In-reply-to: (message from Nick Helm on Tue, 13 Mar 2018 23:31:01 +1300) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:144198 Archived-At: > From: Nick Helm > Date: Tue, 13 Mar 2018 23:31:01 +1300 > Cc: 30792@debbugs.gnu.org > > Sorry, got a little ahead of myself. Try this. > > --- a/lisp/help.el 2018-03-13 19:52:32.000000000 +1300 > +++ b/lisp/help.el 2018-03-13 23:23:52.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." Thanks. 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' [...]