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: Mon, 19 Mar 2018 00:19:03 +1300 Message-ID: References: <5AA7A52D.6060808@gmx.at> <83zi3brk6r.fsf@gnu.org> <5AA8D9E9.2090204@gmx.at> <83605yska4.fsf@gnu.org> <5AA980A5.5020707@gmx.at> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: blaine.gmane.org 1521371892 10766 195.159.176.226 (18 Mar 2018 11:18:12 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 18 Mar 2018 11:18:12 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.0.91 (darwin) To: 30792@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Mar 18 12:18:08 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 1exWKG-0002ia-5i for geb-bug-gnu-emacs@m.gmane.org; Sun, 18 Mar 2018 12:18:08 +0100 Original-Received: from localhost ([::1]:37026 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1exWMJ-0006Wf-B3 for geb-bug-gnu-emacs@m.gmane.org; Sun, 18 Mar 2018 07:20:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46751) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1exWMC-0006Ru-A5 for bug-gnu-emacs@gnu.org; Sun, 18 Mar 2018 07:20:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1exWM7-0007gt-A4 for bug-gnu-emacs@gnu.org; Sun, 18 Mar 2018 07:20:08 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:59417) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1exWM7-0007gh-4t for bug-gnu-emacs@gnu.org; Sun, 18 Mar 2018 07:20:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1exWM6-00005u-PS for bug-gnu-emacs@gnu.org; Sun, 18 Mar 2018 07:20:02 -0400 X-Loop: help-debbugs@gnu.org 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: Original-Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152137195932766 (code B ref 30792); Sun, 18 Mar 2018 11:20:02 +0000 Original-Received: (at 30792) by debbugs.gnu.org; 18 Mar 2018 11:19:19 +0000 Original-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 Original-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= Original-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 In-Reply-To: <5AA980A5.5020707@gmx.at> (martin rudalics's message of "Wed, 14 Mar 2018 21:05:57 +0100") 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/hq7QMzy7w4ryBRG9W4cSx7KJHPp4Y1h3j 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/ldlZ1wMeMbJ X4NmLXxH9EIY8mwYcQbF+yFihup0+uuokUuPslMmRr4fkq 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+XiNYqDL8IA 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-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:144380 Archived-At: --=-=-= 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) --=-=-=--