From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#30792: 26.0.91; improve docstring of with-help-window Date: Tue, 13 Mar 2018 11:17:17 +0100 Message-ID: <5AA7A52D.6060808@gmx.at> References: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1520936185 7184 195.159.176.226 (13 Mar 2018 10:16:25 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 13 Mar 2018 10:16:25 +0000 (UTC) To: Nick Helm , 30792@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Mar 13 11:16:20 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 1evgyg-0001iC-O5 for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Mar 2018 11:16:18 +0100 Original-Received: from localhost ([::1]:38694 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evh0j-00084x-Kq for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Mar 2018 06:18:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52365) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evh0R-000846-DL for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 06:18:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evh0M-0007le-Et for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 06:18:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:50216) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1evh0M-0007lV-AA for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 06:18:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1evh0M-0002si-3n for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 06:18:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 13 Mar 2018 10:18:02 +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.152093627611064 (code B ref 30792); Tue, 13 Mar 2018 10:18:02 +0000 Original-Received: (at 30792) by debbugs.gnu.org; 13 Mar 2018 10:17:56 +0000 Original-Received: from localhost ([127.0.0.1]:58113 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evh0G-0002sO-4Q for submit@debbugs.gnu.org; Tue, 13 Mar 2018 06:17:56 -0400 Original-Received: from mout.gmx.net ([212.227.15.15]:50819) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evh0E-0002sA-9f for 30792@debbugs.gnu.org; Tue, 13 Mar 2018 06:17:54 -0400 Original-Received: from [192.168.1.100] ([46.125.249.67]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MXIov-1f7Yxt0cmz-00WFhI; Tue, 13 Mar 2018 11:17:24 +0100 In-Reply-To: X-Provags-ID: V03:K0:E0gT4CIBK1Dcn6LPLMeCTW1RQ3vriBwm/gKFabnEnIt7O/1i37Z 2VYoRgOQVbFk7cpYRCtMcwCBkcf62BVaFigA+szmiRVkI3/cwuaygKucLEDgfD6n6Ql2Pot FGmBPYHU7zua1e7YHPyNWWw6nbIBTiNOhixQKmZsIbG0eAKULRS/YErR4dgMYP9WZ6xU002 TzMe21KvOUEwdc4J7wwxA== X-UI-Out-Filterresults: notjunk:1;V01:K0:xEca/vKHuks=:YDz8QN33ndOZYfZAL4Pn/+ WIIok56i+5HrOZcPhbc+us8yaNRIF89VCvQGaet+GZK4erqyfb+WxMo1jA8Dt5kGJpAHNgvYm CsJX3V90T5UrS+RhNHioxhgvtnMKGFFh2756uo1jMJL/CGyxP3Zd7mjoEqechH2pN7GGpAj0C eLou9ee0r717YwnITJkXVP9j/sHhkhS1pTp4WWFUdGU/KFEvsuUNTE7dwyvTAxY+kGkPCAw0w w8peqCI2ROAbKDaEcPM1DaYU+HXAUiP5vL0d7/cnK8IwG5aBwYq2vK1a0dZHAsm2v3ByeOq/x 3QRkXr267Xe4Aa34vFPO0x2fG6S3skj9LId7Gp8T5dteOMxwF5AezQ/MNASr0M6Vqkg9BMF57 0SuA8JsyVK7lehqueMN32ENOL4b7MZYpkq7PftoiffOPB/WRewi7kNoWa5UxJ+gmQgrzrTlND 4e6hXt2iQuk4aQE74Y8gPQfCpGZqE5yJ0NKvIMhbDe+RSOxL1xK8iOYzjxZT8LDOjV6PEIDPy DO60gQYFQKuyAjszsCqCsJwzpqyhej0oI8K4hg9DZNd8+/phNPilLe0V/cFi3dHLrfTHYqqnl Quti5iLZfPELSBINuRONt6kBwIueahTyQIdeckC8c4J0CRZcwfd5fQvDaNP3Mbj04hCYKZKEj tLKc0iSViOf8YpeyyLqtorCphMz+QA/8m9SqmYtUjJw6I1cbMKTMYp5Z/HdfT7qCp6ZcRpTxo GWFx1W3vg4O9p5OQDBRJP4T13KXNu+0huAnhCTkyjtZQnI2d5pWKes4XFj0I4vNbZIubIINQ 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:144183 Archived-At: > 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. Thanks. I can see only part of that renaming in your patch. Am I something missing? martin > --- 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