From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Nick Helm Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 13 Mar 2018 09:40:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 30792 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 30792@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.152093399732272 (code B ref -1); Tue, 13 Mar 2018 09:40:02 +0000 Received: (at submit) by debbugs.gnu.org; 13 Mar 2018 09:39:57 +0000 Received: from localhost ([127.0.0.1]:58086 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evgPU-0008OS-Mq for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:56 -0400 Received: from eggs.gnu.org ([208.118.235.92]:51606) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evgPS-0008OE-3U for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evgPL-0007Yt-OS for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:48 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: *** X-Spam-Status: No, score=3.3 required=5.0 tests=BAYES_50, RECEIVED_FROM_WINDOWS_HOST,T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:48164) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1evgPL-0007Yc-Kk for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:47 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42555) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evgPH-0006IM-BS for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 05:39:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evgPD-0007Rj-CU for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 05:39:43 -0400 Received: from mail-me1aus01on0124.outbound.protection.outlook.com ([104.47.116.124]:45600 helo=AUS01-ME1-obe.outbound.protection.outlook.com) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1evgPC-0007OF-Nv for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 05:39:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tenpointcomms.onmicrosoft.com; s=selector1-tenpoint-co-nz; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=6rIg67otFd9mFZ4mwNmimV4UZeRD2KvDwXtkc1KAYps=; b=lqE/eNKOFCII1GHn/2ltZX0RzO5qFJGyvp2D/nKchUY0wvHJfarGJ5x0YkFay0skCsxJ1WnkS+qUllPnORUFBbqLNsvEi/Pzq8bn1tfor40jMcKbkGF80hcizkmzxqCNhRuvc2tsGoKGt9cNPmVRODWgd9IXwcEqPodFwbfOxUU= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=nick@tenpoint.co.nz; Received: from jupiter.local (125.239.174.80) by SY2PR01MB2906.ausprd01.prod.outlook.com (2603:10c6:1:1e::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.548.13; Tue, 13 Mar 2018 09:39:32 +0000 From: Nick Helm User-agent: mu4e 1.0; emacs 26.0.91 Date: Tue, 13 Mar 2018 22:39:27 +1300 Message-ID: MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [125.239.174.80] X-ClientProxiedBy: ME1PR01CA0125.ausprd01.prod.outlook.com (2603:10c6:200:19::34) To SY2PR01MB2906.ausprd01.prod.outlook.com (2603:10c6:1:1e::19) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: c8892f31-731a-41ea-c2a4-08d588c65373 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(7021125)(5600026)(4604075)(4534165)(7022125)(4603075)(4627221)(201702281549075)(7048125)(7024125)(7027125)(7028125)(7023125)(2017052603328)(7153060)(7193020); SRVR:SY2PR01MB2906; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 3:tkgViNe61WSkWlThdkJJtbbviu4s55GjgB+JDaeoAz3n/rpDfP7Uced8isUSLY2h+qgGcCavWRl8eFpWeBGgSopZJz7FAtKTOSro/J2owIHjaOqQdXCr+vXimp6f+HiYLH2Uy+cNsHmZbOkgCeu0LZs53cCIkosSswBkOwQe8LnH5C+jhAdGbmcnPxx5g4SVNdNsjHh1oausSZn+dML9ZxDtU2vH80RqwHkF7JMNmJFKY2FQ0zPnqy9Z2khrlbdO; 25:bEIr5aczQC3jRHbEl2zSbNiqNsmvF10zwou4cLTLqwmLAkjAnJLaaLoVTG4qMVMJBTE8uIEglZtRpg5ElEaUUDp3etddPnPnVAY2AVPeI4+4QVBK6NXJGeVu4l6eX8r8sk4sG952XvrGTprN0RXPsBYpiDAdH1wWFWv1lf0Olq8pVmhYznTphgBbGM8TYfuLmRUZFZRoqIH1aQQFAmwp8O1SVo7sf8AFwKo+mhQgi+vPsu9EmXZ1/B0T9mG2za16dMtIXl/z3dS2tEo2FWhK79i1m3JXrgS3B1LbVNDUFN7N4MMANclKuNw8GDtopY5L7OJpQaeIrZqQ7Hno7cXvFg==; 31:AaN3ctqAEoGpmN/T/0wX3wGR83HEvBUyTbv1TfSohPkEMO+09U55Pc6JKaOAyNaCOPeWC6gTKA6pbZmUxrcwlYovVa76/ReRrJ7Y6bNlcrdQHD9ucBLO0YYzzb2z/WCb3UaY4EVzLDbLy3DFcNfWDq4gA5lTZx8tFd3suWmLX2bV6W7NOFKP+ewmYLF0Mr4QeZq31Y8eSZrDlhViyTVFg5RtgxFnVVhx7X7TihvVyeY= X-MS-TrafficTypeDiagnostic: SY2PR01MB2906: X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040522)(2401047)(8121501046)(5005006)(10201501046)(93006095)(93001095)(3002001)(3231221)(944501244)(52105095)(6041310)(20161123558120)(20161123562045)(20161123564045)(20161123560045)(2016111802025)(6043046)(6072148)(201708071742011); SRVR:SY2PR01MB2906; BCL:0; PCL:0; RULEID:; SRVR:SY2PR01MB2906; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 4:UcknZDjeyFZ0OIulWQ5K5KkW0RpR73hL1Pe38BskVW/dEO/GHGksj3uuLMASjy4roJDba7eByLiE1q7fqCAbaEJE3457/YX1yPnuiPLvUEUyNZT5tsT4q+iqBpNX8A+4MQxAgPgGuXH09LTFCUkR27l30MytHjbTgAnqhmW09eyM9QdgzANRuYG1I2mqYHAoeLKq0B5M61T4hl3VEC8ltGPRBtYJAo/dsU4AzRDJn9iJQq1kkf/TFi6Lp8hYNJMcMEJdaR0ORY2FcnuC4zG99A== X-Forefront-PRVS: 0610D16BBE X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(39380400002)(39830400003)(376002)(366004)(346002)(396003)(377424004)(5423002)(189003)(199004)(6916009)(50466002)(81156014)(6486002)(2906002)(47776003)(305945005)(74482002)(26005)(16526019)(86362001)(36756003)(81166006)(316002)(386003)(6506007)(68736007)(8676002)(51416003)(52116002)(6512007)(2351001)(6116002)(5660300001)(106356001)(66066001)(7736002)(105586002)(6666003)(2361001)(48376002)(25786009)(53936002)(3846002)(186003)(16586007)(97736004)(478600001)(58126008)(8936002); DIR:OUT; SFP:1102; SCL:1; SRVR:SY2PR01MB2906; H:jupiter.local; FPR:; SPF:None; PTR:InfoNoRecords; MX:1; A:1; LANG:en; Received-SPF: None (protection.outlook.com: tenpoint.co.nz does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 23:IjQbwQm5Bc3uwKKxUm104U2i5HllHmJJdl4DYzz3zHNL5gjoqr7Xx0KXIb7y4PpCAsG8SJUXvGCdiy83rzjJzv+6QYTfBtF+/UoRUpDXjMHTukM1K8HXpnYbpGFRzqzuZjK9hGS8D9nkBFJ5Jyw+0ofDLDsQPUClZNi4YxzvIWPqwcOAJrbavASJmrG6/9QK0b6Pu47yum0v/3I998roPuVU/VzYu5uoJg68vsD02E7ReLNV7xzQpIamHHiXskgdi306rluKdcpkJRWz3CVD4k9D+So2oCgw1uylpGNPjcXDrxVM70wv4pwVr3tYiNTPiu/LGJP3tTO9ibxbg8BDHxerJP6NoBTypyys3d+JOpyqbLxSTyIojD1w4lhPsmyLYvrtmyOnDeLU/PdqxNCL3KSQsjOfk8I8JnDptgiPOKQymljPEi4uKAbZbcsNaay28LD61u2QU480S41rGN4JNkvBq6lehn7hLPDNwR/i88CiOPfQPRpP4Ql9Cc2zo9ofdsynQFInQRYSuMrzHRdOxmfHaQgKmgzFCKUkP+AJurufUd9IKpRQyWmY9kuHfWyE+08Rvzxd9V3WACxgUzu6uCIoNT1zq/MJLTTDTlfit4Q+DJj6Yo4nw9GhmWAW4bO35ugqrMWE16H3n6XB2+L1GttvqETX7umKJ9jy8UXPDHFcMKUibVegh8i0CrHLidTn5lOUpHznYY/pdFRWKpYorPJV+mhz9fwrNiDhLCbUNRQr0qs0iVbywSvw6epxH8BUQGWp+5w+pvozFHRnj14jFjXEl2ZvZE+deAXjtvVjF+H1FjeQfrK3BQjubWZnWHQWcbQiwfXglBGB2Q0e6GixO9y/qnRY2UGPRPvfZdseHVcc8etiisWIqENOAZmHn9KGjipWaunt0BmuySfISe85/ag9Dp0M51bsFcdnYgIS4DoAfKglNwEtCizjOAUhEO5kIlX0dpHtpq6XB7ogjjSrJdH0PU7xI/AOaf5m2WiaGg85zw0eGCpQ/3NwnuDTpBhL2/WuGRaCY9oITncIQiQ26cZ6T1zTMSv55wrIYBQqFfsIrMXavCo3cYaBl/BslYCsGbWWYyP4/p5VwqswQJT0ZIIgJZ+1F3NAwHQq5t3cpPGHOHV6ue8gbV+9gJwJqtLs X-Microsoft-Antispam-Message-Info: nKo3Kh5kY6Qv1lITAIKVKQzySGXPbhHsWAMvWHxKHYJnrFbAdbS6zC73XG0NmkuImNiTAfoC37WTIIwQthhx59FvcJbiKyReK2aoUBiu0ZHBiflU6Vq2ZWi/rz6tzK/QpN0bPn/x7oXYUPLB3Dv2jfzSvOuC3fmumDc1z6twpV0vrfTVFZTmlhqSV6t42GVi X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 6:PBOEhBsI8v+iCxNlSj3lmvps3Yt8Mu2EMj4hbVmZ747jrQRzqYl5YiUwuGVMMR+8LVp8pO5Js6xvWbHIHIHtvGx1Pr7iubx5mihx44TMw+gF/0xHpK9jnpHlSefh6O1E/2Mt5aU8eSkC2x/N8yc7x/vGzERVWG7/CvhpBNnOGcQG1M56By/N2IujJpGHD5wkkY0ELABKl0VdPpa3Js3VOnKFWU6HHcp5AY2HEAWMboKZDF5uATavi0x5SIwezfGNh1ObE1LqtSHF4sA19TnSChRSTHYHS1p9qnJJTq7LLUuCDQhz2Cq1Ipx7lpjp8WRDHYAfx1j2IDtcDaCRC750o2Puv2lskT95rG3flRm9Ins=; 5:fWMN/KuCi0BTzfmiD8IAPNEJ+ybplf1lpc4cufdmNmKCm96wPm88wSvCbt76EZdQZ3SJTwGxOMzT1RW2obHs9nznv6DEZJcXdz0Hz0sKRZf+gHE2r4REdkuz/lNcc7DMMrQaZZm+uBiFsLCL/0v/tM9FA9jZ1Fp5mdpjqBd1gN0=; 24:K9sjBd07elozDwwUWzzMLX2vBdNZl4lW4k5NqjB3912G6xxLkxKNpQvZBYrUT6KKuW2XiQvNG6sdq7xGBS7wMP9nVDu3OZjj0RoLwuGdicA=; 7:p1t7JfEYqOT1wWrBQ88mzM/iLJrZIhRwhERgsOjQjTVB6d5ohtRX8g1zBHPx0M/mo6Fb1OnpV7J0Jjd2jrkkxZmXJZNYbSdYoBHXoP7CaO0zvZ3VmhmJrdnxUes+6bgxnEF8fnYKa6B9NFJ49rvNORMrxslFEv4mKZ4hx3WHJ+v2rpblRz2O405SPWthx3ykbftBdXV6Pwy56nxVGwYi0ngdbRl9SmxYIStAr8SGf7r2PVW8z8zs3chbLqs9mjZG SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: tenpoint.co.nz X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Mar 2018 09:39:32.5446 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: c8892f31-731a-41ea-c2a4-08d588c65373 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: ed686f26-19e8-407b-91d0-7364c1c6f5cf X-MS-Exchange-Transport-CrossTenantHeadersStamped: SY2PR01MB2906 X-detected-operating-system: by eggs.gnu.org: Windows 7 or 8 [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.1 (----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.1 (----) 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 From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window 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: To: Nick Helm , 30792@debbugs.gnu.org Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152093627611064 (code B ref 30792); Tue, 13 Mar 2018 10:18:02 +0000 Received: (at 30792) by debbugs.gnu.org; 13 Mar 2018 10:17:56 +0000 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 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 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 Message-ID: <5AA7A52D.6060808@gmx.at> Date: Tue, 13 Mar 2018 11:17:17 +0100 From: martin rudalics MIME-Version: 1.0 References: In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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+0huAnhCTkyjtZQnI2d5pWKes4XFj0I4vNbZIubIINQO 6M2ABQTOHrM4rPFbGqW90Us6/GsTbTaGc3w5fegCnZZpORcwSAMmfbICkygkhlOBeStUESw X-Spam-Score: 0.8 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.8 (/) > 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 From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Nick Helm Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 13 Mar 2018 10:32: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: To: martin rudalics Cc: 30792@debbugs.gnu.org Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152093707812637 (code B ref 30792); Tue, 13 Mar 2018 10:32:01 +0000 Received: (at 30792) by debbugs.gnu.org; 13 Mar 2018 10:31:18 +0000 Received: from localhost ([127.0.0.1]:58118 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evhDB-0003Hk-SB for submit@debbugs.gnu.org; Tue, 13 Mar 2018 06:31:18 -0400 Received: from mail-sy3aus01on0132.outbound.protection.outlook.com ([104.47.117.132]:1653 helo=AUS01-SY3-obe.outbound.protection.outlook.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evhD8-0003HS-I8 for 30792@debbugs.gnu.org; Tue, 13 Mar 2018 06:31:15 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tenpointcomms.onmicrosoft.com; s=selector1-tenpoint-co-nz; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=DU+/HFLl21wdxLWVDaPvD2G0i+Z81h8hJzCLfUBW4nw=; b=o6pZIrdjCa63t7Y9iWWAdMbwl1m2a5hqv/QGE1kx2fgksto3SvlB4WAEur1ErfgbofRBnI3u0EiRHLMih6jCVMaQVFa6wExGckcnAKDSez/dAPkOq7RnaWhDfrzT+Q3BOU0vV4Gyp/FrDAUZnvSQqgRuBQ4J39y6EZlmgkvPpuA= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=nick@tenpoint.co.nz; Received: from jupiter.local (125.239.174.80) by SY2PR01MB2908.ausprd01.prod.outlook.com (2603:10c6:1:1e::21) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.548.16; Tue, 13 Mar 2018 10:31:05 +0000 From: Nick Helm References: <5AA7A52D.6060808@gmx.at> User-agent: mu4e 1.0; emacs 26.0.91 In-reply-to: <5AA7A52D.6060808@gmx.at> Date: Tue, 13 Mar 2018 23:31:01 +1300 Message-ID: MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [125.239.174.80] X-ClientProxiedBy: SY2PR01CA0046.ausprd01.prod.outlook.com (2603:10c6:1:15::34) To SY2PR01MB2908.ausprd01.prod.outlook.com (2603:10c6:1:1e::21) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 176b4ae8-3f20-4396-fdb9-08d588cd8743 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(7021125)(5600026)(4604075)(4534165)(7022125)(4603075)(4627221)(201702281549075)(7048125)(7024125)(7027125)(7028125)(7023125)(2017052603328)(7153060)(7193020); SRVR:SY2PR01MB2908; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2908; 3:63NvHv7Fr0O9eHwaHQhWFuoAoOi9LuThGnV9cLtDukgWNxeduNYkxEXaeAyCrBE4Bs/DS9RzVAUSRECafndRyoFRZ/LVXIEWx+1G5b7KE9cFH4Y+WpaJ4lNlrG9pkGdrnrm1kNbn9xUPds1R8njCSPqFcnIShqconvNPIPfhaYG38TI/+iwxYcy6jSlVpXv1S1YPeREgD5E4hNAfjIPVZu3ImFBtAq5nKllQR4ZGc4aIcilz4PzDk/nKqtsjv3as; 25:HxCuN86UMOtxRNAKgpQqJ4KkxNh0h2J0hjkNUExFNtRgw1MVSWaoJJw60gih4wJu07P3o+VGl4NFOYITBX3DNWE1jF6xTXsHSrlLH9keRgRWOCrd8Er9/NlrBmM0YpOgV9xUgs7Iz1ndI0M2/Xv4Isr7vnwX+PjaZEwZC9ykcQyKSvbT7Cb+DHbyoYhJ8aqYN7XxyfrmGNNVLqjTQdK5H/DLdb5OpjcO1I5lLjOjHVTfIFYykvjD0VUZs1CbkD9PXeYjAP3T+aFiGJIQTQdE+iMhFOSSeTn2B0f7HTevw8LOlAs2XZIoceUpDuagM0HaWxPFc1rlIUjN0arbCYuEPw==; 31:+PemLmYVmkb4kgI6aTdwXSQ4IwiUxwbEO1oXxRVZ4QDnafuYAjexxpaIkS/xMPClKuApPLugHtuLsyYyh6mtmVaDsFtAcxNo2YT0vkQab70NfpWEmt4v8LJ+ySQuDBj41L4k7PvX7JdDJCgqIz63eCNI0U2ZhzDDvea9i+Nz07pfwi+R51KBFvkZwFfvIa2Vr4rE4mxxK/rO2ELMruZt5s1S+Ba7Z620JG4lkRo2TXc= X-MS-TrafficTypeDiagnostic: SY2PR01MB2908: X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040522)(2401047)(8121501046)(5005006)(10201501046)(93006095)(93001095)(3002001)(3231221)(944501244)(52105095)(6041310)(20161123564045)(20161123562045)(20161123558120)(20161123560045)(2016111802025)(6043046)(6072148)(201708071742011); SRVR:SY2PR01MB2908; BCL:0; PCL:0; RULEID:; SRVR:SY2PR01MB2908; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2908; 4:DwtgwJMweKeW8x1Ql1ocP6lhznC3jikK5OinOFkEKlP1XJTeuJmvmbQMgS6M9cXilKm95MzImdDvZKQVSVi8Zp3ZbJa2KIPTTSNlHrF80aZ++yQ6Oq1SOyiXXJyy0twqvMLlW56tV2Kl0+D6jVuqvJxXzAkVBt9U+LhFVQAJpcZq1PyyLctJsoACmoHs66kwdpzEWJJmoBakQC8D9dF5Omhb6WAAu/k8z95x4amxzc3L4bcQ7+UA7iMx0fLsx+fiPXFl2h/VR640t3q3WHAscg== X-Forefront-PRVS: 0610D16BBE X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(979002)(396003)(366004)(346002)(39830400003)(39380400002)(376002)(377424004)(199004)(189003)(5423002)(97736004)(86362001)(478600001)(58126008)(6916009)(5660300001)(2950100002)(6486002)(81166006)(36756003)(6666003)(81156014)(316002)(7736002)(3846002)(52116002)(51416003)(68736007)(8936002)(6116002)(16586007)(50466002)(8676002)(48376002)(106356001)(8666007)(53936002)(66066001)(74482002)(16526019)(305945005)(6506007)(386003)(186003)(2906002)(76176011)(105586002)(6512007)(25786009)(229853002)(26005)(4326008)(47776003)(6246003)(969003)(989001)(999001)(1009001)(1019001); DIR:OUT; SFP:1102; SCL:1; SRVR:SY2PR01MB2908; H:jupiter.local; FPR:; SPF:None; PTR:InfoNoRecords; A:1; MX:1; LANG:en; Received-SPF: None (protection.outlook.com: tenpoint.co.nz does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2908; 23:PQSWYIt5HGZwlUgl2bcHV5W06r6p5Q82Wnw9M/Iwn62Kar9ErzipclK2pM28qojd4/qJ4panZVxTWf6+pL3S7pNYb5CoKWt6Oyh7uswDUpDMvEK0RMu0l4C7HkFPkw8RrBjJ3F8Cd4l4XQdXLlTNbXKsPy3wF5jZ+dW7iC3nbjeaGuwir8ywmkGr/zTz5XUPPiw4bMJEDu052qq6IKEkBodFQOfyGau1SAhlKKrprUzjnmcnkPtCNBpqi3XrlRkqtXVY1hkjhEHlJ+xuOULunKh3AxvayVp43YojxdqYuDsGJkZp1xIqYCqEurK3jsFxYrV6Yw6LajM3ZMUmmHmUWHtn8qAk0OxkIRxjQzmaBAGpSE6xxrsY7tEDztTPUR7GceS0JzcDwulOskzK/KlhScXsjMkv4WFyNpHMh4NFdY1zcZy2eCtaFwNzNpn61gxwUa9W7PFRG4mNJ2aCTMVMk4fmQCEdvo//691ZRNNZsmsoRQyUI39TEZ1Os4lWRec4/L0RA53KK62fNeBgwgA0wrFp3GmS7iSlYg04dkWgcdyZqIwhipRVd74qCjgzm9pFGgFdfXQQe9VyHmzC6n66xenBRFUJb+lVmupjoj7FYngArzQgu5TxGv4HXdTI3JjN073RgLX8jt17Q38y+srsyiIqKWo2fGiHPauZCV5zwq4bbzIwTccPgzb8qa/xVecK9JfgQpy0L6+T5xb8WjIGDXY/REr6l0mSnlm5/LkC1ATX+B7jKtHOGnYH6KGVA2MNW/c0SIrWOi8ePyxA6vG74XplubgXOGTD5YPFlGfGewKmBgaPWqH6Ixb3fIBkqmEpqV3P8nsS+WisvSiWmO9wOce+a1gGaBf39RvW8yF5KtRBi1g9BOLI6q/6IaEXQ90gPvBoGcc6mb+N084SpoTOGooxv7m+aHntXjTfye5EURL13xSvBQg6ugB0Jg0p9J6OaPofxKqmd6nkxk1cTw/q6dwPvKrLmJ7/F8RsV0BA1oZ7aZErBKiK8yodN78eT57m68nB0O1R05aBJa/yZV242/oB94nK2xUwQgTpdgCrSZt1B0MBioUed4D332Fs4F1IvhQeuD1Mu8eHBt9TtWEEUXEyromfb6fBI98Gi/XwMAav3MEMtY2Gs/Xma6fpWP5S5piCekQgksUiXhksgR3H84XA1yrBcg+xj+qpAsJKgRiunvGgdYfXFTocm2XzhJzxQeKoj5ecMYI8vroZ6Ss9CTk5AruqbjJRcnh5DMJQFjIfFvz5BZo2akPw+a9ve1fgbyJxkEZu6xGBGdF26RKku/Uh6O9BVT3h8ksL/ox0aPc= X-Microsoft-Antispam-Message-Info: hoSlfdWn9V3CRkQbvS8rSFR/B8m0VQLqSqVEeKmKMNINnjkO7uPrw088WZX3NomGbmQcWKcSYaEIoQFl6N8zwC+IrovfUON/m8JB+SUbk4T0aUommviF+xkRQEDsmzfqPBqXe02F4s5QJTw4odkGvED3CkA6T/5rTISusNtQOXe/0T7gNZ49rOZ2GZamwaoN X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2908; 6:jbslkxFHOzAotlkDERtmizOmqMSXDITicpCgKBe8F8Of8On7cvLnfdBSQXQYxzXvPbK1s6wOIZtFbQmoiP2kZ88LVa5UkMvj5rEgABcLfrFuJXxUOcNtVB7nYibPifE6cwSDzsc+rwlJkGTmbf+6RCwwahNC3FI+3+notdN79oW5SyOq8eNxjkkyHIdYhoY6ArPRGX7RY0p/mS89OI7PK3IXf+S6O9JotYfnhph/0T+HZ4llr+2SGhDoNDjCv+YXDXdXkFpSW+duVxfjJlBmik8zTVdwvsjHWVSSgS3EaLY6UaPNauqXlxLh6Q0Wv5lp/RDzbWi85QrNVEz5exGcpYIfSYxjJXF92smJ5ymvef4=; 5:MGCh/YVo4/uienHy7hia6Qd9ylAgHCeWKvDlLv76Qr0GxmSRrUGTfMu8pVNdmNvoNlI6JpHwy5zuAstVjyqNFweZDuvrS4F2iMp6tm5rA8t/WY1jc7znBBonKHsEHt1BWp67C7p5MZIcQaMm5CD+b0vFVU+0T+ng4wDpUd/uBxI=; 24:J1aBNNj9zDukl043GWCJGeLkQcBdDRuAL/DJco0SyE/9LqTqje3x/9rRBPVk+uxM/Lzxkd+5OR9ttxykQLYHrsKhl/QDrXdonAKO0E3I9TE=; 7:pRnItSvyVAIpEaTc0cif3jfSYtM0MRmaOXszLd4tA5K7wKXznq1mFlVC96VX+VVuyAJ4BCmukbXDG51Xi8GaSwD0QIDWx36NIdBSKrMXMjfYv4v/QSExw95UsWmXiWWY+Cd5sqktbBpFkgZpPfgkYnBin9s+ccuB903kiww8dSbd0WIktDH292GOWxwsR7zW8zuZUATf8eqzvbHbewqzNAp5mVMKCOcB4pgkoVtWqQKTe/wHSs4RCUuVQnDV8fpY SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: tenpoint.co.nz X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Mar 2018 10:31:05.9502 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 176b4ae8-3f20-4396-fdb9-08d588cd8743 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: ed686f26-19e8-407b-91d0-7364c1c6f5cf X-MS-Exchange-Transport-CrossTenantHeadersStamped: SY2PR01MB2908 X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) On Tue, 13 Mar 2018 at 23:17:17 +1300, martin rudalics wrote: >> 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 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." (declare (indent 1) (debug t)) `(progn ;; Make `help-window-point-marker' point nowhere. The only place @@ -1390,7 +1395,7 @@ (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. From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window 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: To: Nick Helm Cc: rudalics@gmx.at, 30792@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152096001527176 (code B ref 30792); Tue, 13 Mar 2018 16:54:01 +0000 Received: (at 30792) by debbugs.gnu.org; 13 Mar 2018 16:53:35 +0000 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 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 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 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,T_RP_MATCHES_RCVD autolearn=disabled version=3.3.2 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 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 Date: Tue, 13 Mar 2018 18:53:32 +0200 Message-Id: <83zi3brk6r.fsf@gnu.org> From: Eli Zaretskii In-reply-to: (message from Nick Helm on Tue, 13 Mar 2018 23:31:01 +1300) References: <5AA7A52D.6060808@gmx.at> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > 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' [...] From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Nick Helm Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 14 Mar 2018 00:10: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: To: Eli Zaretskii Cc: 30792@debbugs.gnu.org Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152098617022519 (code B ref 30792); Wed, 14 Mar 2018 00:10:02 +0000 Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 00:09:30 +0000 Received: from localhost ([127.0.0.1]:60165 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evtz0-0005r7-CJ for submit@debbugs.gnu.org; Tue, 13 Mar 2018 20:09:30 -0400 Received: from mail-me1aus01on0138.outbound.protection.outlook.com ([104.47.116.138]:29024 helo=AUS01-ME1-obe.outbound.protection.outlook.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evtyx-0005qf-Qi for 30792@debbugs.gnu.org; Tue, 13 Mar 2018 20:09:28 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tenpointcomms.onmicrosoft.com; s=selector1-tenpoint-co-nz; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=F0KkGQO0P4/BvZ2LU0MhzGD4z3ii8IJCmVPb7awF2IQ=; b=QZw+fCX18sNSbwg9V343b4sXXZIS5FbosfkXiYarI75AIU0AI3st7ToCls6Y5y7sWcFmggOiTfq/u5vulyl7X/fRXR8JslTxJrjH5x5P7FDTGRXE+ANKyDTgcoMvemOtkqVMiN7HdTypP+emRhaej/jtm5+2yEzWoMMFIJkQnXw= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=nick@tenpoint.co.nz; Received: from oberon.local (125.239.174.80) by SYAPR01MB2911.ausprd01.prod.outlook.com (2603:10c6:1:11::11) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.588.14; Wed, 14 Mar 2018 00:09:18 +0000 From: Nick Helm References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> User-agent: mu4e 1.0; emacs 26.0.91 In-reply-to: <83zi3brk6r.fsf@gnu.org> Date: Wed, 14 Mar 2018 13:09:15 +1300 Message-ID: MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [125.239.174.80] X-ClientProxiedBy: MEXPR01CA0083.ausprd01.prod.outlook.com (2603:10c6:200:2d::16) To SYAPR01MB2911.ausprd01.prod.outlook.com (2603:10c6:1:11::11) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 9a25d26b-8858-4340-408a-08d5893fd4d5 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(7021125)(5600026)(4604075)(4534165)(7022125)(4603075)(4627221)(201702281549075)(7048125)(7024125)(7027125)(7028125)(7023125)(2017052603328)(7153060)(7193020); SRVR:SYAPR01MB2911; X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2911; 3:guvzwtudjllL7ExcfU7i0fBqh+xI0fq7I3UFucZH6NCk84mIoAg0yRtCs9PeKnZu4S5aUZ54kJ7HoBJdM0U9X3/cIfp2uqSx8Uhd8eu6OfJD8DX83tJhyCfPyjM5tXPYQD9+WAF/xHMmlRl8R/sXYEJsGLlvgDbJpjIA4UmrD2bqRNM9jaxgUHy412NNVeA7TuONqvqnDQL6rRN5oDSwLCjHXbImcsBPNM6jwruk5bKc3YoV4LgBnK01LhkO+Ee6; 25:YDjS97PKJuldseWJ7RL692yIf5noBXp0MKE2m0QuJImYWXeNx7zKGc4TfFiqJt30JXPAtxi4uU5D5exlHbwRu6+u6aBg05GYEA0ztxKQR0cc7J/o2HtcrAANsS+mTMDj9Tb/n7JWJW0tHaxWC9jDpIspErAtt1EdBRVD+63XpvCsXijY1XggQYp8I8/bvtQvrsrWibfDuoD+jH5POzfGnnkWREdz8hExBXIT/52wEaq7KcZ4Pj40WxN1mZ5p6zGUVWnmgwse2vbxmb0ndXBOYYzcaamT5LHadg0YGj4aEZl4p9wl7uJwHPo0uPFPKBq79oqfw4/0IDeVaL4oGpLTNQ==; 31:+NabPB5V6uf8pdvfv4QM3f9cbyZvVv8er//KX57Ai83XiYKPf9NwLwH9yq5Ums7tbuwvD77JI1JIDzk5ujS/ldFpKK7p/GFD8yoNPIFDdH4uXlwI2bP6fYhZeT2h0X1tEucwkUbLdUjRS/jzlKO+6llYEuihMdcuhB3nLnMvgRHhVGmhaziMDDVrZQYexNIsWLp0O1i/k1mqdhzKuSjp2gLmWF96KXSli+RZaQQuru4= X-MS-TrafficTypeDiagnostic: SYAPR01MB2911: X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040522)(2401047)(8121501046)(5005006)(10201501046)(3231221)(944501244)(52105095)(93006095)(93001095)(3002001)(6041310)(2016111802025)(20161123562045)(20161123560045)(20161123564045)(20161123558120)(6072148)(6043046)(201708071742011); SRVR:SYAPR01MB2911; BCL:0; PCL:0; RULEID:; SRVR:SYAPR01MB2911; X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2911; 4:LRMsdvenA7HroEQBxxzLrt14JzpjIYyiNXXt5TZ57/rlhmR3lRzFEmU+lrPylLHpIw2IOuQWM4fBwzV0z4+DTNix1bHARzfifp0jcpyk/Yjl7ICQQNPBK3QnqDQvp5I52KrkBB7PkXAc0mArBY3NxGhp9Z7cUUO2HLcJblySJ6r+J0rYxxniYiz37pieoZM68/l62qzRoR92q638KAla7F8+7zz0Gcfqo6hgFx+T9iFwyX+h2PuF0yxphpHL7zm5K5JlVPFzgHj/NSFGCMxs9Q== X-Forefront-PRVS: 0611A21987 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(396003)(366004)(39830400003)(346002)(376002)(39380400002)(5423002)(199004)(189003)(377424004)(74482002)(76176011)(26005)(478600001)(52116002)(97736004)(186003)(6506007)(386003)(16586007)(316002)(16526019)(105586002)(58126008)(93886005)(106356001)(51416003)(7736002)(305945005)(6246003)(50466002)(48376002)(47776003)(25786009)(66066001)(5660300001)(4326008)(229853002)(68736007)(53936002)(6486002)(6666003)(8936002)(6116002)(6512007)(81156014)(3846002)(2950100002)(81166006)(8676002)(2906002)(36756003)(6916009)(86362001); DIR:OUT; SFP:1102; SCL:1; SRVR:SYAPR01MB2911; H:oberon.local; FPR:; SPF:None; PTR:InfoNoRecords; A:1; MX:1; LANG:en; Received-SPF: None (protection.outlook.com: tenpoint.co.nz does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2911; 23:6XB4F3hZCrCmEiSUqqMx5DjpONw/kAf1DLQRl1jOuPEtrmcU5/nj/mHXEbOV8ibsy8jaLsVfM8kPDwMcgwnoOMG67WTuGp+nPRoEC2imous/lBbCez+Q7kUf8lS4voeRRNBKgmgILSXQRTwmX4sxR8EGx6jQGGXVFs8TqHxvKsIb6m9MsJ4ysP6ISD/nL29dsq01jHf5xy8kZ2CJR7qGFSR7pqWSDZcg5gjTisJy0BzQtAshJZDcLmMHao6iA/UGKlxkpTMK64SJAg61Wyu27K9syRFuvEwsM3lUb3sUNUFGjlfyedemwAga3LQLeZTOWWi6R2vfw9T0tcFSvQO+ISY5/dDZhLGq+MJFmo0k5i+8JLFc7PpzHhuV7KoQZuifX4z6m2862QYUDnhc1UIwORvMVgMPPYvHvN7aKWDNVs/gyu8xezccRf3AOvyjOM0SRfgxvfp2TNJtm3puY6AHkhuCj/xfGS2awj9i8htSRwOq+ie04EUIpURCj2YbT4s3Dy2wDh3JfLE7EnMm3ALhg3KK5rE4uz5pFRG2/XdNNaCQASEvWzXMKtUJKfEJ7ZjpA6YIvQ5fyR32q+bgdD7y5P0hp3S/eLfTlsMYA2HqmMCpeDv3TGFVnKyqbvyQU+9i7Fj8XbIbV7TUh7+aABRD6blrLPAOrxXU+9aDBppDHXNplJqbgevapvgIj0dSFtG099M4CHPQI1/N82zLotaEl0DaT+b7zFlEOEFQZdHtYhQM7pg6komtEYbj/t/9k3KmC48ZjJsovujFRHAXosCbxcZXE1mYqXbxLHAwXiAiipWfJpxJabppvK6r9+j2OKWW5SeMFBPd08d3PsymIZSP/j+a7eVzCh3hLaiDkR6JPZMPL4D8u/067ih/z+vl8ZMENCiuDB2ie6yV34Tl380DifvOPD+25+Oyp8kxsT+dLmCty6o7LqVqjsMQoPYQ9Yl6tiQY+1si5G/GP8IJuKPAK/UnkN2wdh2mrVCUdPpr3CClX/EHoAX56GQk2f+r1AxRHna9oY8EU4cYVP8Vl5lmmJHJ7W5Ae6xsioN3WCGjZ8BHreD4GUSAqgkKPq7dNAZ7HjZg4Qt+CDF+ucSuHO/uePbLGYrYTkD6Eub959DzRbYOLehXu3FsaPndhd2I+1gco510Woqx67Cmsh/22F1E8Xq+jW3u1oBkgRTXom4i4ydngVBBQFfK8IlevfWlJ2LV/n1KrIkeBGd9HBbqSzcjfw== X-Microsoft-Antispam-Message-Info: sj8DANWcPggIYw0jBcz5x0rVFUyWRYqNcSLDm9eRcBHU2gZgEnGyASFpcvAwc2KrXDPq7B4iZ2Ymi8AVUKsVeO0M5Wc6E8Xz2NzdUUSRQxo+2wIvsdKGrQjUUQoF4obf30CbbvTP5LEE7DhFmGMvcP6PZSU/AFT0mmZNbwH/P6OtH2uabq3PYcS8QKaGUrqK X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2911; 6:sLz0hQGMn9w798ammCmF2Hh8Z9jusYXg8cQXOYAW14FecHEXVB8/VaTYF1tMYTInppWBz4BAx3jlUnvlMMOv9SvTgdSoV0hkc3aefVilXhx2bBF0mg3+kwPbzedoBoO9sUIAFkTDDZ2JAqn26mTDlNyPtFwKNjiWWzg4x2UTMxmjvm7LCy6fsEzt3taZe93goFGPvbYA2gDuI+B+chFWnOp+uQPJxP8nkAwUwy+8fBhjssVYpdSU21sHTktUqsWJUo+8FetjeXAg2MQvGjyI6V/CNy9RHG6aDWy1167rdWmUcCVve88XclUgt45w2wkbmOHrTfmUngc92SdG7RehrCQYI/usF/DWkcBfhIOjYUI=; 5:csw2QgkewpH6zIwjd4oJRN9dWXtMq5xFzHO31ikk/NomVx4H4+3bVIVG72D3S9i0tNgDH89vPwJK65kLLCNo9Zne7aarVCka69u/8na6jpm/ltDebcNQFNApcdwIJ0kdRjg59+sDcID2vZYzaQTeLkZYdaS3iiYY3axYX6cfzx8=; 24:7wmtxmg+nV9S2fOufS11jNZuoN5SY71IHRqiWP0uZtkS/a5S6+DJlFqy2+VrdgxRZOcdN4e8n22zXimnA/y8dSjWwTtEovlFFvL6SXgZVbw=; 7:9xAnFClTLxXl2kqahgBzL1FrAjsTdrIVlW5bAa1J3nDr23Vj6iuGHIj0D06906xunITQA7ISkzmukLAgXXBrKNCj0TFK6pwSJrYo5AKNXLiS9z5EaLLKMwa3/TssxjXJV0oSZguSaYhRqIcXahhp50Iqab+/b3eU/K5DoKebpGwvMT9b5IKgDOtHV0NcaaKsU9a3YKhcCWYRUPmSCx+FwPCvmdvnuaPHudr4g118MijeG7YFhskRW9VHm51ggR3B SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: tenpoint.co.nz X-MS-Exchange-CrossTenant-OriginalArrivalTime: 14 Mar 2018 00:09:18.6514 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 9a25d26b-8858-4340-408a-08d5893fd4d5 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: ed686f26-19e8-407b-91d0-7364c1c6f5cf X-MS-Exchange-Transport-CrossTenantHeadersStamped: SYAPR01MB2911 X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) On Wed, 14 Mar 2018 at 05:53:32 +1300, Eli Zaretskii wrote: > 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' [...] Ok, how's this? (wording borrowed from other macros that use `with-temp-buffer-window'): --- a/lisp/help.el 2018-03-14 13:03:14.000000000 +1300 +++ b/lisp/help.el 2018-03-14 13:06:03.000000000 +1300 @@ -1370,15 +1370,10 @@ ;; (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-current-buffer-window' but unlike that +puts the buffer specified by BUFFER-OR-NAME in `help-mode'." (declare (indent 1) (debug t)) `(progn ;; Make `help-window-point-marker' point nowhere. The only place @@ -1390,7 +1385,7 @@ (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. From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 14 Mar 2018 08:15: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: To: Nick Helm , Eli Zaretskii Cc: 30792@debbugs.gnu.org Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152101529630843 (code B ref 30792); Wed, 14 Mar 2018 08:15:02 +0000 Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 08:14:56 +0000 Received: from localhost ([127.0.0.1]:60371 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ew1Ym-00081O-1e for submit@debbugs.gnu.org; Wed, 14 Mar 2018 04:14:56 -0400 Received: from mout.gmx.net ([212.227.15.18]:48245) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ew1Yk-00081A-C9 for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 04:14:54 -0400 Received: from [192.168.1.100] ([46.125.249.49]) by mail.gmx.com (mrgmx001 [212.227.17.190]) with ESMTPSA (Nemesis) id 0LzskF-1eaf4b0EBH-0150FT; Wed, 14 Mar 2018 09:14:42 +0100 Message-ID: <5AA8D9E9.2090204@gmx.at> Date: Wed, 14 Mar 2018 09:14:33 +0100 From: martin rudalics MIME-Version: 1.0 References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:hGN2QR6PJ1vCtt4JHWwhKoW4p1CLQP9I57Djq2mWMUl+6CeJ0bw 3vgyvf3d7qtHVvdL2D6m457+aKHX70KgZQ+aN5Hed+nzbFnw4POx/AyyJ7g7zO1+7OT8IEe C7kX4iFdbQvr0JaqPMRMmaB/Z9A7HLvA4vm29OpjQS70oHgxAzPVkJ+DhI6q8ovR/JlABaB a8axT8aGHWZy9Sc5jXRZA== X-UI-Out-Filterresults: notjunk:1;V01:K0:twsDD8FIBgc=:StP3J1/lajlzIcaiFDGluF bc0qg+xHCrzTWORECntkr5wRRAdqToyrOV9wask0DsUEzRq16UG1LI956mqUW2LBOjN03lIWN 2XbwO5tIn0k+2hGZW6sdKyVcgnqBiNUi4/p288xoY6c/vQDQAC8M6ZmXPGich8p+d81leL+wP w90Mjnbv+ZE/weJlqm5rNKyPO+gY/OwsBT4Sb3GZLHE9bsoxW0ZGQ479BcPl+3y3QZCgGDdv1 fHGOrkTx06qSIn5ZawaH06ZYZmfUdUnFb+Kj2U1GqQGlHEEaxjSRabeAFsX7Jw81Uo+bJ6ar3 gxEPBzLSkVmCh3ZR2fyPcUKOYWXZfGcWEviMCezz6zOCcBgFPNhTc3mYZ2I/Z5ZHGSaDPir8s EnPSCT0RdBhk60AHo2VIz9ad/BghJi1dxOrrI+Ac/+3wwBD9wpiLvsUCOhhPMd3Ot/Y7bwncd EVhK2zKI/kEG6DEDnfnJtCJP/wuIxcXShBEg17x8f9QsRogviuhcfTb6pMND5iKS1AN+yYJq1 0o8mvkQ340qMUDKhLXJseAehNyMQowZhBzbPw1hST4xoNiayF4GckJIqzO3jKYkUFfnadTp+i TMn5CAuLDcyPgyM3w4poBexK/RI55RM7YyBXrr2pE+XPN2yrTf5bQM5OMS+aXD672wn9kJFBq Ya+5TbFs7fs/dWetOzF7H5cTlHIVe51ZTn3JGjcS87Lfu4HLiOC8nt59jetoEklyUAbwmXjT/ u8Eic13GsHFZqTYVv2muoELJuK+zCoGzCoz+PTzjSgsHKrwyIamJgVouBLsdnlAVFEieiQoCw rYKITlimfqHZvtzwev5DpMmtvDkqp7zN1FDKbfh4qE16PgYNIVc9MrAt0sjzJAnY37kSOaF X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) >> 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' [...] Neither `with-temp-buffer-window' nor `help-mode' are of any relevance here. The distinctive aspect of `with-help-window' is provided by `help-window-setup' which sets up the help window for quitting it later. Earlier macros failed miserably in this regard. (I have to admit that many people are still ignorant of this fact and believe they could resolve the quitting problem by saving and restoring window configurations. So the old doc-string probably failed to provide this rather crucial information as well.) > +This construct is like `with-current-buffer-window' but unlike that IIUC it does not make the buffer current when running BODY. martin From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 14 Mar 2018 15:57: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: To: Nick Helm Cc: 30792@debbugs.gnu.org Reply-To: Eli Zaretskii Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.15210430013931 (code B ref 30792); Wed, 14 Mar 2018 15:57:01 +0000 Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 15:56:41 +0000 Received: from localhost ([127.0.0.1]:33473 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ew8lc-00011K-NQ for submit@debbugs.gnu.org; Wed, 14 Mar 2018 11:56:41 -0400 Received: from eggs.gnu.org ([208.118.235.92]:49115) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ew8lb-000114-45 for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 11:56:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ew8lS-0003s8-3h for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 11:56:34 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=BAYES_40,T_RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:56294) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ew8lR-0003rz-WB; Wed, 14 Mar 2018 11:56:30 -0400 Received: from [176.228.60.248] (port=1253 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1ew8lR-0008Qc-C8; Wed, 14 Mar 2018 11:56:29 -0400 Date: Wed, 14 Mar 2018 17:56:26 +0200 Message-Id: <83bmfqslat.fsf@gnu.org> From: Eli Zaretskii In-reply-to: (message from Nick Helm on Wed, 14 Mar 2018 13:09:15 +1300) References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Nick Helm > Cc: 30792@debbugs.gnu.org > Date: Wed, 14 Mar 2018 13:09:15 +1300 > > On Wed, 14 Mar 2018 at 05:53:32 +1300, Eli Zaretskii wrote: > > > 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' [...] > > Ok, how's this? (wording borrowed from other macros that use > `with-temp-buffer-window'): OK, but I think you should mention this part of the old doc string: and issue a message how to deal with that \"help\" window when it's no more needed From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 14 Mar 2018 16:19: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: To: martin rudalics Cc: 30792@debbugs.gnu.org, nick@tenpoint.co.nz Reply-To: Eli Zaretskii Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.15210443236293 (code B ref 30792); Wed, 14 Mar 2018 16:19:02 +0000 Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 16:18:43 +0000 Received: from localhost ([127.0.0.1]:33499 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ew96x-0001dR-B5 for submit@debbugs.gnu.org; Wed, 14 Mar 2018 12:18:43 -0400 Received: from eggs.gnu.org ([208.118.235.92]:54985) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ew96v-0001dA-8x for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 12:18:41 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ew96l-0000Tv-GJ for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 12:18:36 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50,T_RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:56906) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ew96l-0000Tl-Ct; Wed, 14 Mar 2018 12:18:31 -0400 Received: from [176.228.60.248] (port=1385 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1ew96k-0008Gs-P9; Wed, 14 Mar 2018 12:18:31 -0400 Date: Wed, 14 Mar 2018 18:18:27 +0200 Message-Id: <83605yska4.fsf@gnu.org> From: Eli Zaretskii In-reply-to: <5AA8D9E9.2090204@gmx.at> (message from martin rudalics on Wed, 14 Mar 2018 09:14:33 +0100) References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > Date: Wed, 14 Mar 2018 09:14:33 +0100 > From: martin rudalics > CC: 30792@debbugs.gnu.org > > >> 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' [...] > > Neither `with-temp-buffer-window' nor `help-mode' are of any relevance > here. ??? with-help-window is a thin wrapper around with-temp-buffer-window. > The distinctive aspect of `with-help-window' is provided by > `help-window-setup' which sets up the help window for quitting it > later. Indeed, which is why I think the modified doc string should keep the part of the existing doc string which tells about this special setup. > > +This construct is like `with-current-buffer-window' but unlike that > > IIUC it does not make the buffer current when running BODY. I think the reference to with-current-buffer-window is a copy/paste mistake, it should instead refer to with-temp-buffer-window. From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 14 Mar 2018 20:07: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: To: Eli Zaretskii Cc: 30792@debbugs.gnu.org, nick@tenpoint.co.nz Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152105798112882 (code B ref 30792); Wed, 14 Mar 2018 20:07:02 +0000 Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 20:06:21 +0000 Received: from localhost ([127.0.0.1]:33668 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewCfF-0003Li-Cy for submit@debbugs.gnu.org; Wed, 14 Mar 2018 16:06:21 -0400 Received: from mout.gmx.net ([212.227.15.19]:34899) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewCfD-0003LV-Oz for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 16:06:20 -0400 Received: from [192.168.1.100] ([212.95.5.116]) by mail.gmx.com (mrgmx002 [212.227.17.190]) with ESMTPSA (Nemesis) id 0LikQP-1eLVSc1VXR-00cza5; Wed, 14 Mar 2018 21:06:07 +0100 Message-ID: <5AA980A5.5020707@gmx.at> Date: Wed, 14 Mar 2018 21:05:57 +0100 From: martin rudalics MIME-Version: 1.0 References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> <83605yska4.fsf@gnu.org> In-Reply-To: <83605yska4.fsf@gnu.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:BsYsANppqaLt8yyF/N6GtjsRzPpxJTmuPPWHd1d7/TQZiFbPDc5 Vs31Fz9i+KC+vEkOYBiOtyrXQX3bvS/e+hEJZO2UwzYvdRLJb2iBNWac6Tw/Si7TfVVsJ9a RL/uLMZy5Q+y+/Ue4xFjGuQEaBvahDrrRAlzeCadoJ3cWGI6h7DAEkAXNEm8bZpiaXLsYEf 5IF3Wu63jWSuUxTxtRmaA== X-UI-Out-Filterresults: notjunk:1;V01:K0:EJGVEYOb/8M=:6Xq5HJV/yCNC4jtNtcU6zr Mhu+bW2CwbpmiTJDorgTl9X0XLKNF/BaxJdoGp/kID/bHNYddfZSeVX6e3ro9+ZuAhXh0W96q 8NEstOvBTDD7oaPVeZIC2CTbTR6osMCjQnyy4qoz9QhmYv6cCGXi8zV4XB41JO2PYpw71zPSp 11fRE6tFJGE2nHxrA6YNT+kY5md3sCC9+MeaQm8R3LrRW3A8noRptHTxVAOjAHAX/ArjC+mc2 fxQ9ulfBz2poCLFAd9HJhsjUYy8fckmspzU7+vtp0t5MbOhTaxyP4x9paa8FdD7u1/EpY4j4A I1X++nggeTqSyJsTpkk5meDX7S3hlk8NTJQEP2ODcb1rCVnnHgPz/eETSnbi5FuJdtFByJikC uzqVFf5tu/LimhA+debDbDYKQrB40eG2NnxxMtekFstAVJkM8f5tD1kCH8Hxph38nM14dRrty F0rwPfjDz2Adg3ob6ThYHczKpGmCcaeHWBAen3lkaKF6cJ6w4OsPppdsv+HYD0ZFg0jfzode/ rz3hvjCZLqFn/etvZq+wWYzUxUOD51sQ0gRl0BFizrVRe3nRIlJZUmgYq+GVsppp5D7Eq7GiG bO9W1OkLvzwxXS1BFF94+TZJLiqsxFCo1e4fBxHauw8p46uaQgb4o9tkzEoTSsv3lGexWI5+Z E/W1ouYAvqbT8Hkq4ICxpWpzGpoTaUrG7tSuaQyQw2TwEH42xtAIzGu4vL/7zSaziRiJRK4FI JI51KQNnhz1Ak6ofDFMvVpjIi6G/1rKlU6PNQFfbYjwbqPDCFw0obo4MENVi5v3mBSEQGftsy Y0T19GtCmAyssayx7VO6/kn2JtAIgMFEFeUMdEGnCKMFIGiMWpIRv6rXMnK5fYDlk+L8d+V X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) >> Neither `with-temp-buffer-window' nor `help-mode' are of any relevance >> here. > > ??? with-help-window is a thin wrapper around with-temp-buffer-window. I confused `with-temp-buffer-window' and `with-output-to-temp-buffer'. It's the former that sets up the quitting mechanism. >> The distinctive aspect of `with-help-window' is provided by >> `help-window-setup' which sets up the help window for quitting it >> later. > > Indeed, ... not really, as mentioned abbove ... > which is why I think the modified doc string should keep the > part of the existing doc string which tells about this special setup. The comment before the definition of `with-help-window' says what it does additionally. It think it's really not necessary to say it in the doc-string. But if we change BUFFER-NAME to BUFFER-OR-NAME this should be reflected in the Elisp manual. martin From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Nick Helm Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 14 Mar 2018 23:13: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: To: martin rudalics , Eli Zaretskii Cc: 30792@debbugs.gnu.org Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152106915731148 (code B ref 30792); Wed, 14 Mar 2018 23:13:02 +0000 Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 23:12:37 +0000 Received: from localhost ([127.0.0.1]:33753 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewFZS-00086G-Jp for submit@debbugs.gnu.org; Wed, 14 Mar 2018 19:12:35 -0400 Received: from mail-sy3aus01on0129.outbound.protection.outlook.com ([104.47.117.129]:45082 helo=AUS01-SY3-obe.outbound.protection.outlook.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewFZP-000860-Qz for 30792@debbugs.gnu.org; Wed, 14 Mar 2018 19:12:32 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tenpointcomms.onmicrosoft.com; s=selector1-tenpoint-co-nz; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=Q0ZADG4htbgucvZcMOV708ObFZtrGHyAAcM9Lz+30t0=; b=ao4+KvAjdy4Ku/cWGsaH9hGospycMXlCV8uVGMxjtDGOZcrIRaam3bLBTLCMGMBejovSS7OFR5xwh+NTmVepmjZFrRzZgn0h3myuxV4XyG51PKGGcNpS3CUDfJ+44JnQ/RaXGozMDlX5XW2kkpUm+rRMzjAYQ0rKYe07tAn8gks= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=nick@tenpoint.co.nz; Received: from oberon.local (125.239.174.80) by SY2PR01MB2907.ausprd01.prod.outlook.com (2603:10c6:1:1e::20) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.548.13; Wed, 14 Mar 2018 23:12:22 +0000 From: Nick Helm References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> <83605yska4.fsf@gnu.org> <5AA980A5.5020707@gmx.at> User-agent: mu4e 1.0; emacs 26.0.91 In-reply-to: <5AA980A5.5020707@gmx.at> Date: Thu, 15 Mar 2018 12:12:19 +1300 Message-ID: MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [125.239.174.80] X-ClientProxiedBy: SY3PR01CA0126.ausprd01.prod.outlook.com (2603:10c6:0:1b::11) To SY2PR01MB2907.ausprd01.prod.outlook.com (2603:10c6:1:1e::20) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 0d6ddcb2-5896-4af6-f621-08d58a010b3d X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(7021125)(5600026)(4604075)(4534165)(7022125)(4603075)(4627221)(201702281549075)(7048125)(7024125)(7027125)(7028125)(7023125)(2017052603328)(7153060)(7193020); SRVR:SY2PR01MB2907; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2907; 3:sLdr+s6twuT0ctqg9HxzWHUO5j9+z8gIn4jVHdnT2MmsC/xAa/kUigE3pbE3PE/F5tnBn+wDJGQlli5e04FUj+NFnKFKP5l4t/Dy5OewaA3FuI0cMB/t1r/4M7MVDnQH6ECXtA7N5QOP/WSmGsjziA78vSoxfhOP+6flGNZzUZ3E0ao6ruWRwHlqXsjEyLjM4KH46Z2sWi78jeVlftNKpv+sEiPUdOBs/3BRTzOh8uvro7qufossJ4kR9Z8BeI+N; 25:REHy0Sl1cwL0qR4OsMccj69BQtECBcXBkB9meTMjZK8XBml5fgq1/N4q1SWdS4dQ1oNAcJ3Rgkc0IB56pBElc1lQsn4RevFEEi//qH3m42/hKKIlBO6BEp1k1U1C1qRALZnr64J5hD6/FpQ3CmtMUxRSdqGpSjCrp7EPt2X2qqzHO8mMKkYb6+bg80ghLXT5+XufGHvhTClToIyd3xw3Mo1ptL14q6RLxcz6Wch/dJZne7pAHgqQcYTAT2BPUTD3TPfsfMW4a22x68l6sg8vD4pZkuZ+Sv3pWo8AsGC5m/9g7UDuLt3VbcCMM7c+1SjG+Z7qY4VGsqtOvFnBY5tuNQ==; 31:4KjZUHt5lDqdIFwP02u1I5d0g8diQvjN2tHbyZiFnEZ99HhpC71VOcnB78AorsUNYq/Dd5a2wIUGwjwNohX8PAc8GqC3Yccke//aEiEFWbb7ozKLlqaftYS58twCFPRyIbMymUF7kzhCMIUivXXEiO6thYlZEpwCsOl19jV2+HCpeQqsWgwpao6pICQmI1iT0DTgysKoTGBBY24cbRhHESOvVaHHxlXryT8L/qutT1w= X-MS-TrafficTypeDiagnostic: SY2PR01MB2907: X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040522)(2401047)(5005006)(8121501046)(3231221)(944501244)(52105095)(93006095)(93001095)(3002001)(10201501046)(6041310)(20161123558120)(2016111802025)(20161123562045)(20161123560045)(20161123564045)(6043046)(6072148)(201708071742011); SRVR:SY2PR01MB2907; BCL:0; PCL:0; RULEID:; SRVR:SY2PR01MB2907; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2907; 4:Ax1TwaVKhu7PnHAGAetBvjzaKoQEs7Z7RaF/FQg0sz8TXuH1WxLNnbwq93hoj4xWU3eilo4wBOkElviBMUe/AE+wty1+eRQ5TEt8zJKX/A6tzN/wd9UlIBDeHTbdQDEsCW2yh3WjU/nf0VtPUrSegmSnHQx0aQqScHrLe3+bqds8qNL0wAAlUqvS7M5l545rEeUOXYFjz0gtIbp+N5j6ps2DR2Ml3u89PyAXhcpqOAe5/TrCJ2EOYZPpFf9hdmsrZB8Mgpn9E7L5wYNEKSGJCA== X-Forefront-PRVS: 0611A21987 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(39380400002)(396003)(346002)(39830400003)(366004)(376002)(189003)(199004)(3846002)(26005)(47776003)(5660300001)(6512007)(81156014)(6116002)(8676002)(76176011)(68736007)(52116002)(6246003)(305945005)(6666003)(105586002)(229853002)(51416003)(478600001)(74482002)(86362001)(2906002)(53936002)(2950100002)(81166006)(7736002)(8936002)(48376002)(66066001)(16586007)(58126008)(50466002)(110136005)(4326008)(97736004)(106356001)(386003)(6506007)(93886005)(16526019)(6486002)(186003)(316002)(36756003)(25786009)(8666007); DIR:OUT; SFP:1102; SCL:1; SRVR:SY2PR01MB2907; H:oberon.local; FPR:; SPF:None; PTR:InfoNoRecords; MX:1; A:1; LANG:en; Received-SPF: None (protection.outlook.com: tenpoint.co.nz does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2907; 23:NWvBlwgcr+HToaCUIg7VTzORQLTiKg725qMDc0K9CmVXa4tMXH5KJqnFbWJujFzSYW61FnE8SVroopMzwHS6u7sNVQoaRlyGtXg6/0tO9KIj2T86tXWY/PUAnNp6ORthoE4sOVDJtTDdKyEfumtHG1SXAtz6YRh2fQFRjFOn6xK4Kaq6qaabPewdMYEh2FzDaSobUvE5MiZL7Hym8QF5xqyRzNlvGO36/lXrh4smKZicAkt63TtT9aD2kXyq88/UFJNEkaIeXH0MOGBbVomclgCgeMqQW1c2aHEwWISNmfA39BHnFw9pwKTTP6rqUn1v0OO7UtP6zNhbslwL+qhr7gd/W4KhAnqAoHjKiKSzkbJKgx0htEPVnsylQ5BmGWXQKOVScr982d/UPh+JifSMR65/UcEv5JdGENKpN94sfuIKc8MWN2WrXqvyafBp+Bo3YZuFZREakZRelbKXNg1sN53akhoWPxeqH0cZvbLqxvKItkqM1Eb3bZxT+0z7w0jUWfRvZMmgbMfgDSOc9kcwLwMlWbUqosj5buN6uhLC78Y166EbI+aJqSDH02u7Wu5jWOSD8VNlUbGoAiVSU6QFqn7rW8WO7N0N0q1QsGQqJJHfUeK8ZyOi/m/3w+n3iBH1bEkJAWkhxXQg9Rwh0QOdrv5N7NI+EaAeB3SmdDKVBJyXKFSl3fLIyu9rWmFBEpXpuH/GbBuB6lef0CAPJhGcblEyQn/HyjFp0ROugJhE5bluydBqHNYYJYAws2CeUZTtjwOgwAOsJeNe8TlHuMteNJGBJ62jqzMQGq/myxSvkRolTGsdDZbDwkB5if2j83DSN5OSyK520suPSeINohyU0WryrhyJc8Ngix51EzThGgAhtsYoLfUHPpAYAotdCkLsg7+S4fV4TirDQ/H/nOmXMEoeIZ33rsCUteOq8hgUjfUo9M8JEIqg18coliC0XjXgBdXJrnBC7QFQNoHHFdl7CCqlg4BH8PCebJ6Tdr78ZHlgNCpuOhpE7HfVTgnrYnjHqzKX2N+7cKn7KCWRFtm2JqKzbdXVRpnkXO5una/MxoOh8LMQToW5DQeeYshQ/J3bFISDkQ21sMCwSGFYaAc/sN3IV3FwNgrwIYzqqO1z7lSYiehsiGFOAdySCBWGDBsxAzzJ+3cVmtQclICx3D/A/hHNiG7H9PdHBNPZ8FOftu19+bvHFN5yEX4ZV0Ru5GhB X-Microsoft-Antispam-Message-Info: ZlOZRs6Vt0rfwc1RAFVbkRpQo0WXR6LLwTzTirGiFRLsN547Ki5xtCyfwqxRheItYtDnM75LUa1gf8QoUwkA2HI986Z1bQNNBAd+WAxDjxFzbOWaF0B9pXSaEHw2crlLlSIr4zNSpL27tY1glwdeZfMWlyOs5KnhXYhvE4HHj4R7BFPvprmLH1ZaHsbaFdlF X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2907; 6:zxX/svWhOatpM0G8rsFsViaVYf9j/iZp+kJJHnDrzo53veKtU+A7TZGd5IXZVJ1BbSmoVwahXKjgS6RyDM41E9Nm1787X7j0H6xNxRpSioojnDhJ1IGzso++P2kUyMxkAWi4/B07FH0jV9XfkOriN2/jRkU/lIRuVkJzrDZf0giDdYaEGbSDasvr0RyH7fb3ZpyOlb8tRfON2fdM40vcHaJDpBcFaOVkVlNIK6aJzKKXiUCeCGfxqlvswFg+WQdB/7ZEZewPcah9FxA2UBF2x6chXubcoX3WPcFyMDmAxPu+B0HzF7YX23xj40VATQtw1LlWE3LC1LU9PN+vTIaBc1udgpQ/jxIBYuWRh5XND9I=; 5:R6VV5wsa8GRR+0mej6tCvf9gqfTTzWFt/H2KyI9IyCAPNJYrnxEZfrmFoVKT+gE5TfwEDwy9mbTyYnlCeFOWibpGV++W7ZimfevJtPN9U/TLPecnG6xVU540DiG/Kq3PgsIpMPNOS9T22X7oR+m0KnyRKJnssOQif3x1gbsMEfw=; 24:lhZV0l61xRrs8p7LU9rwvF7vFRxsr+UraPpVot6FTTJDjdF0jxv8TX8A6yC0uZAz5VENuJ7hDaUE1SQhJ9ZFpehGvnwfALfj12R6l8fnvQ4=; 7:l0o309R+BINhxcPTfjh7y4JAT49ra6E78JQ+LVl/Z+eTTAVSVcOjW/t9F39FCu10UyxfQk+o216PoMuGejGfWuRh923NDAdl2fegqlqQCBZ069SQ3Vps7x6mJmaN0js/xIcUtTPFg2GQ11tuIuXzsTzx1KXPDrY1I7yDRWCQCPuJpgP9UxZ85fHgDssGXeBEhsRB/81bfd6jAFOrZqKb0EANgCISrTTXpNfLZPm8/gB5EXn7TkFP6zP5SZfLdBL1 SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: tenpoint.co.nz X-MS-Exchange-CrossTenant-OriginalArrivalTime: 14 Mar 2018 23:12:22.8347 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: 0d6ddcb2-5896-4af6-f621-08d58a010b3d X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: ed686f26-19e8-407b-91d0-7364c1c6f5cf X-MS-Exchange-Transport-CrossTenantHeadersStamped: SY2PR01MB2907 X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) On Thu, 15 Mar 2018 at 09:05:57 +1300, martin rudalics wrote: >> which is why I think the modified doc string should keep the >> part of the existing doc string which tells about this special setup. > > The comment before the definition of `with-help-window' says what it > does additionally. It think it's really not necessary to say it in > the doc-string. I don't think a user should have to read code comments to work out how to use a macro. Besides, all of those comments (except (4)) appear in the macro's manual entry, though not as clearly. Isn't it sufficient that the docstring says it puts the buffer in `help-mode'? If a user wants to find out what that means and how to tweak the result, they can follow the link and read the help documentation. If they're reading the docstring in the first place, they almost certainly know how help works, and that pushing q quits a help window by default. > But if we change BUFFER-NAME to BUFFER-OR-NAME this should be > reflected in the Elisp manual. This was just a suggestion, as `with-help-window' simply passes the value along to `with-temp-buffer-window'. I think the expected use of `with-help-window' was to receive output from `help-buffer', which returns an existing help buffer object or "*Help*". But that's not the only way to use `with-help-window' and `with-temp-buffer-window' can accept any existing buffer object or a string name to create a new one. I think it would be useful if `with-help-window' made that clear by using the same name. Nick From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 15 Mar 2018 08:22: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: To: Nick Helm , Eli Zaretskii Cc: 30792@debbugs.gnu.org Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152110207728934 (code B ref 30792); Thu, 15 Mar 2018 08:22:02 +0000 Received: (at 30792) by debbugs.gnu.org; 15 Mar 2018 08:21:17 +0000 Received: from localhost ([127.0.0.1]:33997 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewO8T-0007Wc-35 for submit@debbugs.gnu.org; Thu, 15 Mar 2018 04:21:17 -0400 Received: from mout.gmx.net ([212.227.15.19]:57797) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1ewO8R-0007WP-L7 for 30792@debbugs.gnu.org; Thu, 15 Mar 2018 04:21:15 -0400 Received: from [192.168.1.100] ([213.162.73.147]) by mail.gmx.com (mrgmx001 [212.227.17.190]) with ESMTPSA (Nemesis) id 0MNqfr-1eyKCy04Gh-007VUp; Thu, 15 Mar 2018 09:21:03 +0100 Message-ID: <5AAA2CE4.5020003@gmx.at> Date: Thu, 15 Mar 2018 09:20:52 +0100 From: martin rudalics MIME-Version: 1.0 References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> <83605yska4.fsf@gnu.org> <5AA980A5.5020707@gmx.at> In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Provags-ID: V03:K0:ZCcf+Yq/P9FobJa0MRRmS7USAoTFqhVogcrJYmsincRE7EXo3YE ZJW8E72JeeJz1VbiT4AO76ROVnvQYJ6DCCCcKkvYFFnIE1ByAjwrHuyDzo+uMGvK/T9JgTV PfqTzHykI73VnpZilp9kvJc4+bB/EQvl6Hs6qfcsdem3EXZRBHI/Odgp+3ufjXRaRkyAP4e h58WyL6fMAyNmm+9V40IQ== X-UI-Out-Filterresults: notjunk:1;V01:K0:9+sJRWX6wJ8=:MTDSwTWlVvNOZKg8jkL57C 6N5yhrrdYyfC37pguZm95E5+hgXMLI2dAFe3pOM37ypU4UOv8kSPTMNi7byej1fEz8MwX0OOR DnN7kwPFm4YYeKbYlD98XIC0jsVAIC8y186sZeJY8O8mPv73MSAxnDKHo3FSAEjarOSHtIIiE 2uAs1LL79tL8gIrdjXX4D0mIT2Ok3U8XjcYieX/E7mgLhTPzODL3McCwavbi77bKQglwRiIOU 7tAxsz/IWQgmhtr7I3CrHrEioim9q7DxJ8KLOpb9nZKfKz4dRTT5qt/LToI0YL7lAbOS2eFOz hwiQw7UalcRbUwAnapFb09JLVlIq6J1ve9myRecDlu1zF260LDYmbwj+owEBy3ejRfhfxxRz4 Xno++7vPpA9nX9fBl0AS/s/mYUvvZOoTkdBPnXkbf/xWYfI8i+PuXP57DK3KNyjeWtX1IjzPh 3yfEcFksjfhCoxm8OnHHKCRJB7fRTiB/u72wcv+NinjlKwcR9x0cN/pZ7D85wLLV+RaUbgKfo 05vfjIH9InMVPsM9sJHwBUqhSLtdpg0c9gIZcaOZUZeqqItCWAsuLLOsr58m/k+hV5u/TJvCc JVPU5MFRvahkSXmpsCrvzGOC7pF9dmUIZau6hPg67TWXg7EAiQq5+S7h6l7S3u6UUhzVmLld1 RmPTXwkVhtG7/cdlztod7ZLAllr78GT2Bs3q6Lj7VXqWyP0u5K37ixIN83TDk44p1HgT5kPan OYI+HEwa09vqi8rTFFy7Mm+L+EnfhgA4b5xw2jUsgVnuje0LCMKKK39GB8lx1xL6ARO920Qeq 8sZWLBur0/6rQqTsoYhS5VWSMrW2gNwmumVwMuE+zDlGbUFO1ciacNlf1d44GPEFd15O6dQ X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) > Isn't it sufficient that the docstring says it puts the buffer in > `help-mode'? If a user wants to find out what that means and how to > tweak the result, they can follow the link and read the help > documentation. If they're reading the docstring in the first place, they > almost certainly know how help works, and that pushing q quits a help > window by default. Agreed. Please follow Eli's proposal in this regard. >> But if we change BUFFER-NAME to BUFFER-OR-NAME this should be >> reflected in the Elisp manual. > > This was just a suggestion, as `with-help-window' simply passes the > value along to `with-temp-buffer-window'. > > I think the expected use of `with-help-window' was to receive output > from `help-buffer', which returns an existing help buffer object or > "*Help*". But that's not the only way to use `with-help-window' and > `with-temp-buffer-window' can accept any existing buffer object or a > string name to create a new one. I think it would be useful if > `with-help-window' made that clear by using the same name. Agreed as well. But we should synchronize argument names in definitions and manuals so please provide a corresponding change for help.texi too. Thanks, martin From unknown Sat Aug 16 18:39:14 2025 X-Loop: help-debbugs@gnu.org Subject: bug#30792: 26.0.91; improve docstring of with-help-window Resent-From: Nick Helm Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 18 Mar 2018 11:20: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: To: 30792@debbugs.gnu.org Cc: martin rudalics , Eli Zaretskii Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152137195932766 (code B ref 30792); Sun, 18 Mar 2018 11:20:02 +0000 Received: (at 30792) by debbugs.gnu.org; 18 Mar 2018 11:19:19 +0000 Received: from localhost ([127.0.0.1]:39081 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1exWLO-0008WQ-IY for submit@debbugs.gnu.org; Sun, 18 Mar 2018 07:19:18 -0400 Received: from mail-sy3aus01on0121.outbound.protection.outlook.com ([104.47.117.121]:45034 helo=AUS01-SY3-obe.outbound.protection.outlook.com) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1exWLM-0008WB-IG for 30792@debbugs.gnu.org; Sun, 18 Mar 2018 07:19:17 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tenpointcomms.onmicrosoft.com; s=selector1-tenpoint-co-nz; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=LtmCSDHrFgdVihlFvOYa+OqI3ZNr/Fikl+jaicDeevQ=; b=OQmADTTgekMmdJxADiCFuuypV510D6VEsixRG5jRs+3C7bjFmwRoLoyCMjC98Pw5J9YwCNMo7FbkqfVEpdZnrYUnK+/LoNovYa0dWief4uhtLvxWsdzr2fYQIXCm7v2RiZGZNt0jEe6MoTWKzSSe5lMxcNR+mhUoMNBlacb+6fw= Received: from jupiter.local (125.239.174.80) by SYAPR01MB2910.ausprd01.prod.outlook.com (2603:10c6:1:11::10) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.588.14; Sun, 18 Mar 2018 11:19:07 +0000 From: Nick Helm References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> <83605yska4.fsf@gnu.org> <5AA980A5.5020707@gmx.at> Date: Mon, 19 Mar 2018 00:19:03 +1300 In-Reply-To: <5AA980A5.5020707@gmx.at> (martin rudalics's message of "Wed, 14 Mar 2018 21:05:57 +0100") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.91 (darwin) MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Originating-IP: [125.239.174.80] X-ClientProxiedBy: MEAPR01CA0046.ausprd01.prod.outlook.com (2603:10c6:201::34) To SYAPR01MB2910.ausprd01.prod.outlook.com (2603:10c6:1:11::10) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: acf5bbab-4dc6-412a-34fc-08d58cc21140 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(7021125)(5600026)(4604075)(4534165)(7022125)(4603075)(4627221)(201702281549075)(7048125)(7024125)(7027125)(7028125)(7023125)(2017052603328)(7153060)(49563074)(7193020); SRVR:SYAPR01MB2910; X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2910; 3:B5x1lvXFBDOm0f1xMwULv/YzfS7Ge4LV02PYvAJmuF6qXm2mLGFlHHLPs3QpGIlhOl8YR+b/tPQxqsds2WuEK+Wt66ddKJMvwzz2KbtAfFWqeHICBiPRpUYvkIBGXm4sCuPkGjulZXyT8nKH/b54H/IgxKWMISHg1jOanRObmY+MlbIG3h4eFTQysHfOTaZVfg2gN4Y+SRYiKKEICQZtZfGyzioLx9MxNkzjbqlST8wF7Y7vPHEigEpteNsGdL1T; 25:Ab3VqHXdH7b+NRONGSYZ8hbs2vIc4FiswHM9F1/AeYfrD9wlg/Ni2lhLOPawDHuo4Bwq/zPz45lCYTIKmlvivmLecJVQU0OonHB+5dKXJOKc0aZCMBVv01pfuArw/kX9mDktjoViPOn99eEzF9KHTnPck54F2Yz+YAohCIi+VloA9KH525YstoIju4Wq1UoVEFOt9uR9ZHwhcW4EQnzgdH5rdLmzoBKF1ijkSOWj0P7ZEO550dPw4HPn8cMuHLqTN43Da7/kzBPozytlsjive38Pzvja07kiIskItkDtY5PzETEwV3baoUGqfQx++PkF/YSlLqpXgOcVu21mveP0yQ==; 31:2sIqQZ4MZvCNEiJVwW/PyoHyX4D2slV/5Nad6Im7G7qMI9EQdX8lPQXco7FWuceLaCMKt8UVc+grgNjo8EuHcK8i2mbjd0cOZQ9zidgQ2C3W+fPB+J4vmC3Ret/1RRpTewcyh0a1C/f7JNLUEcZ1zWncetXbrb3o+eLXdpGwWXGFQB3ozl7o9o23xNAD00ELB1eHKJD/hq7QMzy7w4ryBRG9W4cSx7KJHPp4Y1h3jyE= X-MS-TrafficTypeDiagnostic: SYAPR01MB2910: X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(102415395)(6040522)(2401047)(8121501046)(5005006)(3002001)(93006095)(93001095)(10201501046)(3231221)(944501300)(52105095)(6041310)(20161123562045)(20161123558120)(2016111802025)(20161123560045)(20161123564045)(6043046)(6072148)(201708071742011); SRVR:SYAPR01MB2910; BCL:0; PCL:0; RULEID:; SRVR:SYAPR01MB2910; X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2910; 4:pWpqCIAb0iRJb4/KcIEvttinSXea65wVsNsHkoH4NHNfR++JK6qp09bvBvoQFRx2Wa/MDSeOfG3OZyYFmNElncWUnGVrX/seN6enI3e4GUjB4YVrQYItVfabRbavxXwMve5vKCD0pH6jb1dlK7zHXHYIATJNF1d3sH24YG19P3XGzbviG1t239/4llNPJW0ZwI5UBTzDgFaGHaM1NfBcm6m/8DMmYQn89qOzsI5+OHIUXZ1n2YXLoVX7elO0UsEpQ/KcuwcnFPpx1CLGBF3QDA== X-Forefront-PRVS: 06157D541C X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(346002)(366004)(376002)(39380400002)(39830400003)(396003)(199004)(189003)(7736002)(8676002)(3846002)(305945005)(58126008)(53936002)(36756003)(6246003)(54906003)(97736004)(76176011)(2476003)(66066001)(6486002)(316002)(2351001)(2361001)(93886005)(52116002)(84326002)(2950100002)(74482002)(6116002)(25786009)(6512007)(568964002)(229853002)(16586007)(478600001)(8666007)(6346003)(16526019)(19618925003)(106356001)(4326008)(386003)(6916009)(186003)(5660300001)(6666003)(6506007)(564344004)(4610100001)(81166006)(68736007)(2906002)(5890100001)(86362001)(8936002)(105586002)(5000100001)(81156014)(4810100001)(26005); DIR:OUT; SFP:1102; SCL:1; SRVR:SYAPR01MB2910; H:jupiter.local; FPR:; SPF:None; PTR:InfoNoRecords; A:1; MX:1; LANG:en; Received-SPF: None (protection.outlook.com: tenpoint.co.nz does not designate permitted sender hosts) Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=nick@tenpoint.co.nz; X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2910; 23:+Hhc20jzWMMb5lwhh+7dcvLyZcBMAb0YjmYvxQY+js79f1eZntv1L7Hm+0ahDBaolnclfk9aShLIdVqa/ngD0O/ocMJujI5g2UjT9XnE9jAsVVWYt+RMZbdUWBwSHHgtTcncV6aEaJs1w6WBGNyHvp4My4+zI0nxjpl2kSJC9u9VXZegCFMZqMPlWcB2MjC8E+GNs3qvL2yE1LgqVHJsJSlp93xB4q8EdDIr8xQSJ0ka3dzwKM14U8AvNiY4EBvLZNFaZ92eKfECG48jqpog/FEHPDYWrGQh/SyIbjx1R02uUjRf23nflRpj2S4fVo+5pf2sfX6/95C1EEfXrG+eYgQfkOmx2mAJN3LVTdwgFJhv5Xguk323/hgc6Sh9+G6KBCB1WYAE2CueftokkbypXPCS/5ciMXV+alXgtrZoe8+o+pJwGOW4UQZwVUq09cWUoWVLy4RqHTlNP4Owt/9Ww3LoOZLhWAFaoxgH/tuA507rHWGfkNbEsJ1qVNc1FgBzHT9nKfO5280NajJhFJmdaSdWShpiF85NMy22hpoce4RSeGdlsE+nMElXdqdkDQvPuI1shSIDu24MplfHbWeq6lKMJ51OIY3AI9UbxFoTLhLOLWWDjVJndbOpOD147FZ8i1R9+4VzBYK6PwJZGRGUTorP2RSF8kgGFJ9xE6AJ0cdfNoHb8fFwihasKlvlGeahNdM0LGiwgHXlHyKRwXvNf9uvoqzxSAaI3QB0QFGu0RX28RdI9lJpIYzKs3DFwXSdb9085elWDMngHdVj/ldlZ1wMeMbJX4NmLXxH9EIY8mwYcQbF+yFihup0+uuokUuPslMmRr4fkq+2gLwx2E9XHzBKKbacuOggcZBk6hNrd5m9c9cFGPATf+rVOSpukZhOpSfGHUqpf5kqdrFNDhCv4mZOnsvVOxc0RfS/gxsY01U+RiCkrn/Zxi+10Rl6fZ9n0tpOBcAnupTgC7qRfqZ5ah8kryQZoNSamRZnmqR+eHvJM/SgANk2OOEYxllZya5K44Cs/FoK11WF12JzxiJkK5qqfm9YN8KxINRJ5fDx7ZTvWCe/xOoSnUT95mWeCGoKZvPUhjGRs2hU4fFBczdjlBoMsB4RuvdshJPpwGfGVSnErr5Y+nw+LfuDSWh6DODaKbH/7Jm6WqR6El0w4BgHJWGi5ytOGoSe6gv0SVThvJhLeeHVsdDphv8sCFs9cVuVGjFmepmvYPyQZ8E1rpnYOdMvvo7eRyG/aIpbnRsALZa7BwV7zbBlY4CGEZg2qnUYeX94CBOPa20o3oY/naAQC+qv5XNnUmHBUEgXCItb0nhXdg0UPV5g3xhCOB6QYeg2Bw05IlYiXkBGPpdOD+z7ESuhxGPxBw1cmmOjDxKrQ1pdQeS0P3YBWLGYmN+w95AhYEmIG+CDz8dK8l4rN6I1Zg== X-Microsoft-Antispam-Message-Info: BuJIqmSzFlFdJA5KGXBNrKQ3BYy6/oSekRmlCAuRMoGmIy8mQGEGo6rJFjfr+VU5eLMr+ZefcRvYNnudZ4+11oCeLaS3UznF2sCx8Gpg35UmizWWkZYWsDf2bl7Zn16Y8Gp/DdwL+5CdvMdOxYhoPxHnRdupK7nuylC0lEnfKbHCQgEEtbVqwJbfUWDw9EVh X-Microsoft-Exchange-Diagnostics: 1; SYAPR01MB2910; 6:fL/vABkEtyuheVA/VujdZ+jHaFRVe935l+u6JD3CNz/KSxiMHzVUlTtmGervBuTTomL9fw3ZloK8s7XTtBY35PKJZTyrpy2FHk+3FVKUpaKQutfeLC5w+rM33XBff7dguamzrbgxVVxp9wMKu1Zu0bgOxR9adhudsPLhVTXzOrqWFNtl/A57I3n4g9aeTIKvN6aKO51rfgPKinmu/gHNS8D0wG5QaA7Zq84yP9guKqJZPcf930LJ6GSYsbcyxFgWpv3rjEy6m893ShdWEM/W5AFVHQMdbb3Z1IXSiEMkRMypLV1+Qtv7vk9etw88c6EogbMf9eCN1IlkaxRPXpA/WAWmjz1S4aLvMAaiKsrMQHM=; 5:Ozm8R7tas9J7dkwnUIgpu6ynFKlfGfTcS2H86qQ7JEuR9ZeuOBLbTeGw98p1mr6k6WTFpSDOWiJPMuNo/1fnzN1MId8dMf/dj55dNQuGBLdwElYAAEEWAr/BFEZFuDPjpiBUQhKU0g7pemdPbvAdZ6y7dGxAs8i9U1YqAonSwLk=; 24:6HbzsSgXA78RCjW4SyGwxik7Nj8zt5xw/sOvaw/fQ8JuLijuTI3fqpezcHJ4AusHrmCCHee/5zKedQiyOMlDj/d216noqgXYhR05/NIRKNI=; 7:JGK4iMwmdd68p3yBn9UN8m/AZ+Qn2nao9f0OmdOgJKCVNUQIe4AbCAMss0dkZLIM33ssyTn2n5xmISMNLnSCTLMeJyeB74supnWT9hsUhQL3C9Ii73ga14TH6hqUtlYfUX4+CmkDYcaSgsLgewTLdTyfuRybZI1Acc+NT7wSoxoUOR+XiNYqDL8IAjelSwVOQcGjUu6ZTEh2/7rMGjuGlTkYg27GoVz+i5AoSzss8s3kOZVEV7K3vki877m/5Xmc SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: tenpoint.co.nz X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Mar 2018 11:19:07.9851 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: acf5bbab-4dc6-412a-34fc-08d58cc21140 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: ed686f26-19e8-407b-91d0-7364c1c6f5cf X-MS-Exchange-Transport-CrossTenantHeadersStamped: SYAPR01MB2910 X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) --=-=-= Content-Type: text/plain Two patches attached. Thanks, Nick --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0001-Change-variable-names.patch >From 3b96b7ddeb2dc0049b036e1f552b7029031042ec Mon Sep 17 00:00:00 2001 From: Nick Helm Date: Sun, 18 Mar 2018 17:26:34 +1300 Subject: [PATCH 1/2] Align `with-help-window' variable names with `with-temp-buffer-window'. * doc/lispref/help.texi (Help Functions): * lisp/help.el (with-help-window): Change variable name to buffer-or-name. --- doc/lispref/help.texi | 4 ++-- lisp/help.el | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 33cc2f0d55..ea5e525735 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -744,10 +744,10 @@ This function returns the name of the help buffer, which is normally @end defun @vindex help-window-select -@defmac with-help-window buffer-name body@dots{} +@defmac with-help-window buffer-or-name body@dots{} 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} +into a buffer named @var{buffer-or-name}. (Usually, @var{buffer-or-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 diff --git a/lisp/help.el b/lisp/help.el index 014af5141e..55abecc05d 100644 --- a/lisp/help.el +++ b/lisp/help.el @@ -1370,7 +1370,7 @@ 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) +(defmacro with-help-window (buffer-or-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 @@ -1390,7 +1390,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. -- 2.14.3 (Apple Git-98) --=-=-= Content-Type: text/x-patch Content-Disposition: attachment; filename=0002-Improve-docstring.patch >From cbbb8d229f2b34f944493ea3415c18a80b776359 Mon Sep 17 00:00:00 2001 From: Nick Helm Date: Sun, 18 Mar 2018 21:05:44 +1300 Subject: [PATCH 2/2] Improve `with-help-window' docstring. * lisp/help.el (with-help-window): Rewrite docstring, adding reference to `help-window-setup'. --- lisp/help.el | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/lisp/help.el b/lisp/help.el index 55abecc05d..958b06c095 100644 --- a/lisp/help.el +++ b/lisp/help.el @@ -1371,14 +1371,13 @@ 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-or-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." + "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 -- 2.14.3 (Apple Git-98) --=-=-=-- From unknown Sat Aug 16 18:39:14 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.505 (Entity 5.505) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Nick Helm Subject: bug#30792: closed (Re: bug#30792: 26.0.91; improve docstring of with-help-window) Message-ID: References: <83605rlynj.fsf@gnu.org> X-Gnu-PR-Message: they-closed 30792 X-Gnu-PR-Package: emacs Reply-To: 30792@debbugs.gnu.org Date: Tue, 20 Mar 2018 12:29:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1521548942-635-1" This is a multi-part message in MIME format... ------------=_1521548942-635-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Your bug report #30792: 26.0.91; improve docstring of with-help-window which was filed against the emacs package, has been closed. The explanation is attached below, along with your original report. If you require more details, please reply to 30792@debbugs.gnu.org. --=20 30792: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D30792 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1521548942-635-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 30792-done) by debbugs.gnu.org; 20 Mar 2018 12:28:06 +0000 Received: from localhost ([127.0.0.1]:42816 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eyGN4-00008x-2U for submit@debbugs.gnu.org; Tue, 20 Mar 2018 08:28:06 -0400 Received: from eggs.gnu.org ([208.118.235.92]:48905) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1eyGN2-00008T-Lz for 30792-done@debbugs.gnu.org; Tue, 20 Mar 2018 08:28:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eyGMw-0004Sr-Mb for 30792-done@debbugs.gnu.org; Tue, 20 Mar 2018 08:27:59 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-0.5 required=5.0 tests=BAYES_05,T_RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:51042) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eyGMo-0004Q6-7S; Tue, 20 Mar 2018 08:27:50 -0400 Received: from [176.228.60.248] (port=4229 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1eyGMn-0002X7-J4; Tue, 20 Mar 2018 08:27:50 -0400 Date: Tue, 20 Mar 2018 14:28:00 +0200 Message-Id: <83605rlynj.fsf@gnu.org> From: Eli Zaretskii To: Nick Helm In-reply-to: (message from Nick Helm on Mon, 19 Mar 2018 00:19:03 +1300) Subject: Re: bug#30792: 26.0.91; improve docstring of with-help-window References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> <83605yska4.fsf@gnu.org> <5AA980A5.5020707@gmx.at> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 30792-done Cc: rudalics@gmx.at, 30792-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > From: Nick Helm > Cc: Eli Zaretskii , martin rudalics > 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. ------------=_1521548942-635-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 13 Mar 2018 09:39:57 +0000 Received: from localhost ([127.0.0.1]:58086 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evgPU-0008OS-Mq for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:56 -0400 Received: from eggs.gnu.org ([208.118.235.92]:51606) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evgPS-0008OE-3U for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:54 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evgPL-0007Yt-OS for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:48 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: *** X-Spam-Status: No, score=3.3 required=5.0 tests=BAYES_50, RECEIVED_FROM_WINDOWS_HOST,T_DKIM_INVALID autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:48164) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1evgPL-0007Yc-Kk for submit@debbugs.gnu.org; Tue, 13 Mar 2018 05:39:47 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42555) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evgPH-0006IM-BS for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 05:39:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evgPD-0007Rj-CU for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 05:39:43 -0400 Received: from mail-me1aus01on0124.outbound.protection.outlook.com ([104.47.116.124]:45600 helo=AUS01-ME1-obe.outbound.protection.outlook.com) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1evgPC-0007OF-Nv for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 05:39:39 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=tenpointcomms.onmicrosoft.com; s=selector1-tenpoint-co-nz; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=6rIg67otFd9mFZ4mwNmimV4UZeRD2KvDwXtkc1KAYps=; b=lqE/eNKOFCII1GHn/2ltZX0RzO5qFJGyvp2D/nKchUY0wvHJfarGJ5x0YkFay0skCsxJ1WnkS+qUllPnORUFBbqLNsvEi/Pzq8bn1tfor40jMcKbkGF80hcizkmzxqCNhRuvc2tsGoKGt9cNPmVRODWgd9IXwcEqPodFwbfOxUU= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=nick@tenpoint.co.nz; Received: from jupiter.local (125.239.174.80) by SY2PR01MB2906.ausprd01.prod.outlook.com (2603:10c6:1:1e::19) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.548.13; Tue, 13 Mar 2018 09:39:32 +0000 From: Nick Helm User-agent: mu4e 1.0; emacs 26.0.91 To: bug-gnu-emacs@gnu.org Subject: 26.0.91; improve docstring of with-help-window Date: Tue, 13 Mar 2018 22:39:27 +1300 Message-ID: MIME-Version: 1.0 Content-Type: text/plain X-Originating-IP: [125.239.174.80] X-ClientProxiedBy: ME1PR01CA0125.ausprd01.prod.outlook.com (2603:10c6:200:19::34) To SY2PR01MB2906.ausprd01.prod.outlook.com (2603:10c6:1:1e::19) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: c8892f31-731a-41ea-c2a4-08d588c65373 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(7020095)(4652020)(7021125)(5600026)(4604075)(4534165)(7022125)(4603075)(4627221)(201702281549075)(7048125)(7024125)(7027125)(7028125)(7023125)(2017052603328)(7153060)(7193020); SRVR:SY2PR01MB2906; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 3:tkgViNe61WSkWlThdkJJtbbviu4s55GjgB+JDaeoAz3n/rpDfP7Uced8isUSLY2h+qgGcCavWRl8eFpWeBGgSopZJz7FAtKTOSro/J2owIHjaOqQdXCr+vXimp6f+HiYLH2Uy+cNsHmZbOkgCeu0LZs53cCIkosSswBkOwQe8LnH5C+jhAdGbmcnPxx5g4SVNdNsjHh1oausSZn+dML9ZxDtU2vH80RqwHkF7JMNmJFKY2FQ0zPnqy9Z2khrlbdO; 25:bEIr5aczQC3jRHbEl2zSbNiqNsmvF10zwou4cLTLqwmLAkjAnJLaaLoVTG4qMVMJBTE8uIEglZtRpg5ElEaUUDp3etddPnPnVAY2AVPeI4+4QVBK6NXJGeVu4l6eX8r8sk4sG952XvrGTprN0RXPsBYpiDAdH1wWFWv1lf0Olq8pVmhYznTphgBbGM8TYfuLmRUZFZRoqIH1aQQFAmwp8O1SVo7sf8AFwKo+mhQgi+vPsu9EmXZ1/B0T9mG2za16dMtIXl/z3dS2tEo2FWhK79i1m3JXrgS3B1LbVNDUFN7N4MMANclKuNw8GDtopY5L7OJpQaeIrZqQ7Hno7cXvFg==; 31:AaN3ctqAEoGpmN/T/0wX3wGR83HEvBUyTbv1TfSohPkEMO+09U55Pc6JKaOAyNaCOPeWC6gTKA6pbZmUxrcwlYovVa76/ReRrJ7Y6bNlcrdQHD9ucBLO0YYzzb2z/WCb3UaY4EVzLDbLy3DFcNfWDq4gA5lTZx8tFd3suWmLX2bV6W7NOFKP+ewmYLF0Mr4QeZq31Y8eSZrDlhViyTVFg5RtgxFnVVhx7X7TihvVyeY= X-MS-TrafficTypeDiagnostic: SY2PR01MB2906: X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(6040522)(2401047)(8121501046)(5005006)(10201501046)(93006095)(93001095)(3002001)(3231221)(944501244)(52105095)(6041310)(20161123558120)(20161123562045)(20161123564045)(20161123560045)(2016111802025)(6043046)(6072148)(201708071742011); SRVR:SY2PR01MB2906; BCL:0; PCL:0; RULEID:; SRVR:SY2PR01MB2906; X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 4:UcknZDjeyFZ0OIulWQ5K5KkW0RpR73hL1Pe38BskVW/dEO/GHGksj3uuLMASjy4roJDba7eByLiE1q7fqCAbaEJE3457/YX1yPnuiPLvUEUyNZT5tsT4q+iqBpNX8A+4MQxAgPgGuXH09LTFCUkR27l30MytHjbTgAnqhmW09eyM9QdgzANRuYG1I2mqYHAoeLKq0B5M61T4hl3VEC8ltGPRBtYJAo/dsU4AzRDJn9iJQq1kkf/TFi6Lp8hYNJMcMEJdaR0ORY2FcnuC4zG99A== X-Forefront-PRVS: 0610D16BBE X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10019020)(39380400002)(39830400003)(376002)(366004)(346002)(396003)(377424004)(5423002)(189003)(199004)(6916009)(50466002)(81156014)(6486002)(2906002)(47776003)(305945005)(74482002)(26005)(16526019)(86362001)(36756003)(81166006)(316002)(386003)(6506007)(68736007)(8676002)(51416003)(52116002)(6512007)(2351001)(6116002)(5660300001)(106356001)(66066001)(7736002)(105586002)(6666003)(2361001)(48376002)(25786009)(53936002)(3846002)(186003)(16586007)(97736004)(478600001)(58126008)(8936002); DIR:OUT; SFP:1102; SCL:1; SRVR:SY2PR01MB2906; H:jupiter.local; FPR:; SPF:None; PTR:InfoNoRecords; MX:1; A:1; LANG:en; Received-SPF: None (protection.outlook.com: tenpoint.co.nz does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; SY2PR01MB2906; 23:IjQbwQm5Bc3uwKKxUm104U2i5HllHmJJdl4DYzz3z?= =?us-ascii?Q?HNL5gjoqr7Xx0KXIb7y4PpCAsG8SJUXvGCdiy83rzjJzv+6QYTfBtF+/UoRU?= =?us-ascii?Q?pDXjMHTukM1K8HXpnYbpGFRzqzuZjK9hGS8D9nkBFJ5Jyw+0ofDLDsQPUClZ?= =?us-ascii?Q?Ni4YxzvIWPqwcOAJrbavASJmrG6/9QK0b6Pu47yum0v/3I998roPuVU/VzYu?= =?us-ascii?Q?5uoJg68vsD02E7ReLNV7xzQpIamHHiXskgdi306rluKdcpkJRWz3CVD4k9D+?= =?us-ascii?Q?So2oCgw1uylpGNPjcXDrxVM70wv4pwVr3tYiNTPiu/LGJP3tTO9ibxbg8BDH?= =?us-ascii?Q?xerJP6NoBTypyys3d+JOpyqbLxSTyIojD1w4lhPsmyLYvrtmyOnDeLU/Pdqx?= =?us-ascii?Q?NCL3KSQsjOfk8I8JnDptgiPOKQymljPEi4uKAbZbcsNaay28LD61u2QU480S?= =?us-ascii?Q?41rGN4JNkvBq6lehn7hLPDNwR/i88CiOPfQPRpP4Ql9Cc2zo9ofdsynQFInQ?= =?us-ascii?Q?RYSuMrzHRdOxmfHaQgKmgzFCKUkP+AJurufUd9IKpRQyWmY9kuHfWyE+08Rv?= =?us-ascii?Q?zxd9V3WACxgUzu6uCIoNT1zq/MJLTTDTlfit4Q+DJj6Yo4nw9GhmWAW4bO35?= =?us-ascii?Q?ugqrMWE16H3n6XB2+L1GttvqETX7umKJ9jy8UXPDHFcMKUibVegh8i0CrHLi?= =?us-ascii?Q?dTn5lOUpHznYY/pdFRWKpYorPJV+mhz9fwrNiDhLCbUNRQr0qs0iVbywSvw6?= =?us-ascii?Q?epxH8BUQGWp+5w+pvozFHRnj14jFjXEl2ZvZE+deAXjtvVjF+H1FjeQfrK3B?= =?us-ascii?Q?QjubWZnWHQWcbQiwfXglBGB2Q0e6GixO9y/qnRY2UGPRPvfZdseHVcc8etii?= =?us-ascii?Q?sWIqENOAZmHn9KGjipWaunt0BmuySfISe85/ag9Dp0M51bsFcdnYgIS4DoAf?= =?us-ascii?Q?KglNwEtCizjOAUhEO5kIlX0dpHtpq6XB7ogjjSrJdH0PU7xI/AOaf5m2WiaG?= =?us-ascii?Q?g85zw0eGCpQ/3NwnuDTpBhL2/WuGRaCY9oITncIQiQ26cZ6T1zTMSv55wrIY?= =?us-ascii?Q?BQqFfsIrMXavCo3cYaBl/BslYCsGbWWYyP4/p5VwqswQJT0ZIIgJZ+1F3NAw?= =?us-ascii?Q?HQq5t3cpPGHOHV6ue8gbV+9gJwJqtLs?= X-Microsoft-Antispam-Message-Info: nKo3Kh5kY6Qv1lITAIKVKQzySGXPbhHsWAMvWHxKHYJnrFbAdbS6zC73XG0NmkuImNiTAfoC37WTIIwQthhx59FvcJbiKyReK2aoUBiu0ZHBiflU6Vq2ZWi/rz6tzK/QpN0bPn/x7oXYUPLB3Dv2jfzSvOuC3fmumDc1z6twpV0vrfTVFZTmlhqSV6t42GVi X-Microsoft-Exchange-Diagnostics: 1; SY2PR01MB2906; 6:PBOEhBsI8v+iCxNlSj3lmvps3Yt8Mu2EMj4hbVmZ747jrQRzqYl5YiUwuGVMMR+8LVp8pO5Js6xvWbHIHIHtvGx1Pr7iubx5mihx44TMw+gF/0xHpK9jnpHlSefh6O1E/2Mt5aU8eSkC2x/N8yc7x/vGzERVWG7/CvhpBNnOGcQG1M56By/N2IujJpGHD5wkkY0ELABKl0VdPpa3Js3VOnKFWU6HHcp5AY2HEAWMboKZDF5uATavi0x5SIwezfGNh1ObE1LqtSHF4sA19TnSChRSTHYHS1p9qnJJTq7LLUuCDQhz2Cq1Ipx7lpjp8WRDHYAfx1j2IDtcDaCRC750o2Puv2lskT95rG3flRm9Ins=; 5:fWMN/KuCi0BTzfmiD8IAPNEJ+ybplf1lpc4cufdmNmKCm96wPm88wSvCbt76EZdQZ3SJTwGxOMzT1RW2obHs9nznv6DEZJcXdz0Hz0sKRZf+gHE2r4REdkuz/lNcc7DMMrQaZZm+uBiFsLCL/0v/tM9FA9jZ1Fp5mdpjqBd1gN0=; 24:K9sjBd07elozDwwUWzzMLX2vBdNZl4lW4k5NqjB3912G6xxLkxKNpQvZBYrUT6KKuW2XiQvNG6sdq7xGBS7wMP9nVDu3OZjj0RoLwuGdicA=; 7:p1t7JfEYqOT1wWrBQ88mzM/iLJrZIhRwhERgsOjQjTVB6d5ohtRX8g1zBHPx0M/mo6Fb1OnpV7J0Jjd2jrkkxZmXJZNYbSdYoBHXoP7CaO0zvZ3VmhmJrdnxUes+6bgxnEF8fnYKa6B9NFJ49rvNORMrxslFEv4mKZ4hx3WHJ+v2rpblRz2O405SPWthx3ykbftBdXV6Pwy56nxVGwYi0ngdbRl9SmxYIStAr8SGf7r2PVW8z8zs3chbLqs9mjZG SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: tenpoint.co.nz X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 Mar 2018 09:39:32.5446 (UTC) X-MS-Exchange-CrossTenant-Network-Message-Id: c8892f31-731a-41ea-c2a4-08d588c65373 X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: ed686f26-19e8-407b-91d0-7364c1c6f5cf X-MS-Exchange-Transport-CrossTenantHeadersStamped: SY2PR01MB2906 X-detected-operating-system: by eggs.gnu.org: Windows 7 or 8 [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.1 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.1 (----) 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 ------------=_1521548942-635-1--