From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: martin rudalics Newsgroups: gmane.emacs.bugs Subject: bug#30792: 26.0.91; improve docstring of with-help-window Date: Thu, 15 Mar 2018 09:20:52 +0100 Message-ID: <5AAA2CE4.5020003@gmx.at> 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: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: blaine.gmane.org 1521102013 9881 195.159.176.226 (15 Mar 2018 08:20:13 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 15 Mar 2018 08:20:13 +0000 (UTC) Cc: 30792@debbugs.gnu.org To: Nick Helm , Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Mar 15 09:20: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 1ewO7M-0002TH-90 for geb-bug-gnu-emacs@m.gmane.org; Thu, 15 Mar 2018 09:20:08 +0100 Original-Received: from localhost ([::1]:50221 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ewO9P-0002BF-8I for geb-bug-gnu-emacs@m.gmane.org; Thu, 15 Mar 2018 04:22:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44544) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ewO9G-0002AX-Pz for bug-gnu-emacs@gnu.org; Thu, 15 Mar 2018 04:22:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ewO9C-0008Ph-RO for bug-gnu-emacs@gnu.org; Thu, 15 Mar 2018 04:22:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:54336) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ewO9C-0008PY-Nk for bug-gnu-emacs@gnu.org; Thu, 15 Mar 2018 04:22:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1ewO9C-0007Xm-H8 for bug-gnu-emacs@gnu.org; Thu, 15 Mar 2018 04:22:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: martin rudalics Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: 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: Original-Received: via spool by 30792-submit@debbugs.gnu.org id=B30792.152110207728934 (code B ref 30792); Thu, 15 Mar 2018 08:22:02 +0000 Original-Received: (at 30792) by debbugs.gnu.org; 15 Mar 2018 08:21:17 +0000 Original-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 Original-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 Original-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 In-Reply-To: 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+EnfhgA4b5xw2jUsgVnuje0LCMKKK39GB8lx1xL6ARO920Qe 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:144306 Archived-At: > 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