From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31574: 27.0; Doc string for `with-help-window' Date: Thu, 24 May 2018 11:26:22 -0700 (PDT) Message-ID: References: <<>> <<<83k1rtauc7.fsf@gnu.org>>> <<73e710f8-8373-46e5-913a-b3cba178a384@default>> <<83zi0p9b8l.fsf@gnu.org>> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1527188531 14321 195.159.176.226 (24 May 2018 19:02:11 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 24 May 2018 19:02:11 +0000 (UTC) Cc: 31574@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu May 24 21:02:06 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 1fLvV0-0003WZ-0B for geb-bug-gnu-emacs@m.gmane.org; Thu, 24 May 2018 21:02:06 +0200 Original-Received: from localhost ([::1]:40311 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLvX4-0000dd-NR for geb-bug-gnu-emacs@m.gmane.org; Thu, 24 May 2018 15:04:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:44167) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fLvWw-0000dQ-EH for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 15:04:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fLvWs-0007H0-B3 for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 15:04:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:38899) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fLvWs-0007Gq-71 for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 15:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fLvWr-0007M4-Vc for bug-gnu-emacs@gnu.org; Thu, 24 May 2018 15:04:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 24 May 2018 19:04:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31574 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31574-submit@debbugs.gnu.org id=B31574.152718858828190 (code B ref 31574); Thu, 24 May 2018 19:04:01 +0000 Original-Received: (at 31574) by debbugs.gnu.org; 24 May 2018 19:03:08 +0000 Original-Received: from localhost ([127.0.0.1]:46786 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fLvW0-0007Kc-G9 for submit@debbugs.gnu.org; Thu, 24 May 2018 15:03:08 -0400 Original-Received: from aserp2130.oracle.com ([141.146.126.79]:37414) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fLvVw-0007K4-V5 for 31574@debbugs.gnu.org; Thu, 24 May 2018 15:03:05 -0400 Original-Received: from pps.filterd (aserp2130.oracle.com [127.0.0.1]) by aserp2130.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w4OJ11ws178855; Thu, 24 May 2018 19:02:57 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=caClaWmvnLXP7X/6jp5uXlTOFOw6La8Co42Sz/meWeo=; b=JrXyJSvY0MMGaYqCxTzWHVU4EcnuHyKqYRHNFlU9zHk4pXyBgsxZTe/57hu0olEfDdIc dQzNDL0rItVDJ+0OaqJuQsowaeH9h9ZWFs2cOvl+stiCdTf5STebgbWa5N2KhaL6vLg0 ZkMby7XDMuN7kK/NzZdvkbdE3lNxf3LTUv+YZiorxV4Yp6CUh88Vikt+gYtghmGgho+E NjOUM8wMkMxHBMDYdxodkanazhD1AQi8OGZHgSTVJZGHvOfaVwLbXH8xbSrQ/RucP25s XNrMa5ONGNG0y/IT6XGpPkZyzA9yt3x/VBPST1mhLyeOzVSCALpIs2u9jgUK7+jfSGjA 7Q== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by aserp2130.oracle.com with ESMTP id 2j62sw86ae-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 24 May 2018 19:02:57 +0000 Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id w4OIQOjs009829 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 24 May 2018 18:26:25 GMT Original-Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w4OIQNJi002266; Thu, 24 May 2018 18:26:24 GMT In-Reply-To: <<83zi0p9b8l.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4690.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8903 signatures=668700 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1805240218 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:146492 Archived-At: > I told yesterday in response to another message of yours how can you > see the changes in the repository using Web browser. Please take a > look, then we can discuss the fix. I looked at your mention of this, which was apparently in a bug #31311 message. After jumping through some hoops, yes, one can see the texinfo source code. But even trying that for this bug, I don't see it. I don't see anything about 31574 here, which is presumably the latest and right place to look for it (?): http://git.savannah.gnu.org/cgit/emacs.git/log/ > > The real problem is that after you follow the link there > > is NOTHING about `with-help-window', AFAICT. >=20 > No, the real problem is that the reference to help-window-setup gave > you wrong expectations regarding what information that function should > add. My change tried to make those expectations match the original > intent. Which was what? > > And I should have been clear that the doc string of > > `help-window-setup' is even more problematic. It doesn't > > say anything helpful at all, AFAICT. >=20 > That's a subroutine, so I don't necessarily see its doc string as > something we need to invest an effort in. We disagree. A doc string that says only that WINDOW is the windo for displaying the help buffer (obvious), plus just "Return VALUE" might as well not even exist (and the optional arg should be called RETURN-VALUE). This is a non-trivial function. Some explanation of what the window "setup" entails is appropriate.