From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#19421: 25.0.50; doc string of `browse-url' must describe parameter ARGS Date: Sat, 26 Dec 2015 14:19:05 -0800 (PST) Message-ID: <10972dc0-33fa-4ff0-974e-96156500da7f@default> References: << <87mvsywduo.fsf@gnus.org>>> <<<8db0a3c8-08b4-40c3-93a8-23ec9fcd8174@default>>> <<<83bn9dk208.fsf@gnu.org>>> <<41cee0e8-d5b7-4b6d-8f5b-314c01142f3a@default>> <<8337uphwi4.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1451168425 26983 80.91.229.3 (26 Dec 2015 22:20:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 26 Dec 2015 22:20:25 +0000 (UTC) Cc: larsi@gnus.org, 19421@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Dec 26 23:20:11 2015 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aCxC7-0001Zu-9j for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 23:20:11 +0100 Original-Received: from localhost ([::1]:40005 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCxC6-00079P-6Q for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 17:20:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52756) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCxC2-000799-7V for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 17:20:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aCxBz-0006Ji-1t for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 17:20:06 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:34654) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCxBy-0006Je-Ub for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 17:20:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aCxBy-0005AG-Hp for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 17:20:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 26 Dec 2015 22:20:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 19421 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 19421-submit@debbugs.gnu.org id=B19421.145116835519791 (code B ref 19421); Sat, 26 Dec 2015 22:20:02 +0000 Original-Received: (at 19421) by debbugs.gnu.org; 26 Dec 2015 22:19:15 +0000 Original-Received: from localhost ([127.0.0.1]:42256 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCxBC-000598-Th for submit@debbugs.gnu.org; Sat, 26 Dec 2015 17:19:15 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:16388) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCxBB-00058w-TC for 19421@debbugs.gnu.org; Sat, 26 Dec 2015 17:19:14 -0500 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id tBQMJ5pj026091 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sat, 26 Dec 2015 22:19:06 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0022.oracle.com (8.13.8/8.13.8) with ESMTP id tBQMJ5hE030033 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sat, 26 Dec 2015 22:19:05 GMT Original-Received: from abhmp0010.oracle.com (abhmp0010.oracle.com [141.146.116.16]) by userv0122.oracle.com (8.13.8/8.13.8) with ESMTP id tBQMJ5ca028372; Sat, 26 Dec 2015 22:19:05 GMT In-Reply-To: <<8337uphwi4.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9 (901082) [OL 12.0.6691.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] 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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:110753 Archived-At: > I have now done that. =20 > Fixed. =20 > Done. =20 > Fixed. Great. Thank you for all of those changes, sight unseen. > > And this: > > > > > Worse yet: It says "When called non-interactively", > > > suggesting that the function could be called interactively. > > > But it cannot - it is not a command. > > > The previous paragraph of the doc string describes the interactive > behavior: >=20 > When called interactively, if variable `browse-url-new-window-flag' is > non-nil, load the document in a new window, if possible, otherwise use > a random existing one. A non-nil interactive prefix argument reverses > the effect of `browse-url-new-window-flag'. >=20 > So this part was already okay (in other functions as well). Sorry; I do not understand. The doc string speaks about behavior for when it is called interactively and when it is called non-interactively. I fail to see how it is called interactively, since it is not a command - it has no `interactive' spec. Are you perhaps counting something like `M-: (browse-url-default-browser...)' as an interactive call? Normally that is not what the doc means by "interactive". Am I missing something? The doc string still seems wacko, to me. I admit that I have not studied all of the code in browse-url.el, but I shouldn't have to, just to grasp what a doc string is saying. This doc string talks about situations where the function is called interactively, which I do not see as a possibility. And it refers to an "optional second argument NEW-WINDOW", but the lambda list is (URL &rest ARGS), and the doc string in no way introduces NEW WINDOW in terms of those parameters. Sure, users can figure out that NEW-WINDOW, if present, must be the first element of list ARGS. But it would be a lot clearer if the doc string just talked about an optional second argument, and said directly what its effect is. I don't want to belabor this any more that we have already. If you really think this doc string is clear now, great. It's not so important that it be clear to me. Thanks for having taken a second look at it and having made the changes you made.