From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Nick Helm Newsgroups: gmane.emacs.bugs Subject: bug#30792: 26.0.91; improve docstring of with-help-window Date: Wed, 14 Mar 2018 13:09:15 +1300 Message-ID: References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1520986093 15692 195.159.176.226 (14 Mar 2018 00:08:13 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 14 Mar 2018 00:08:13 +0000 (UTC) User-Agent: mu4e 1.0; emacs 26.0.91 Cc: 30792@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Mar 14 01:08:09 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1evtxg-00040N-8f for geb-bug-gnu-emacs@m.gmane.org; Wed, 14 Mar 2018 01:08:08 +0100 Original-Received: from localhost ([::1]:43761 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evtzj-0008L7-A0 for geb-bug-gnu-emacs@m.gmane.org; Tue, 13 Mar 2018 20:10:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49387) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1evtza-0008J5-HH for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 20:10:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1evtzX-0002Gq-Aq for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 20:10:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:52269) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1evtzX-0002Gh-6J for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 20:10:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1evtzX-0005sJ-0P for bug-gnu-emacs@gnu.org; Tue, 13 Mar 2018 20:10:03 -0400 X-Loop: help-debbugs@gnu.org 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: Original-Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152098617022519 (code B ref 30792); Wed, 14 Mar 2018 00:10:02 +0000 Original-Received: (at 30792) by debbugs.gnu.org; 14 Mar 2018 00:09:30 +0000 Original-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 Original-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; Original-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 In-reply-to: <83zi3brk6r.fsf@gnu.org> 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+RZaQQur 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/9k3KmC48ZjJsovujFRHAXosCbxcZXE1mY qXbxLHAwXiAiipWfJpxJabppvK6r9+j2OKWW5SeMFBPd08 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/K5DoKebpGwvMT9b5IKgDOtHV 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-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:144223 Archived-At: 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.