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 08:40:36 -0800 (PST) Message-ID: <41cee0e8-d5b7-4b6d-8f5b-314c01142f3a@default> References: < <87mvsywduo.fsf@gnus.org>> <<8db0a3c8-08b4-40c3-93a8-23ec9fcd8174@default>> <<83bn9dk208.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 1451148085 7414 80.91.229.3 (26 Dec 2015 16:41:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 26 Dec 2015 16:41: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 17:41: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 1aCru3-0005Up-Fc for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 17:41:11 +0100 Original-Received: from localhost ([::1]:39168 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCru2-0002iI-Qe for geb-bug-gnu-emacs@m.gmane.org; Sat, 26 Dec 2015 11:41:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46341) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCrtx-0002fj-TV for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 11:41:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aCrtu-0004fM-Kr for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 11:41:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:34236) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aCrtu-0004fI-HD for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 11:41:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84) (envelope-from ) id 1aCrtu-00079w-Bf for bug-gnu-emacs@gnu.org; Sat, 26 Dec 2015 11:41: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 16:41: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.145114804427483 (code B ref 19421); Sat, 26 Dec 2015 16:41:02 +0000 Original-Received: (at 19421) by debbugs.gnu.org; 26 Dec 2015 16:40:44 +0000 Original-Received: from localhost ([127.0.0.1]:41837 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCrtc-00079D-G3 for submit@debbugs.gnu.org; Sat, 26 Dec 2015 11:40:44 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:21081) by debbugs.gnu.org with esmtp (Exim 4.84) (envelope-from ) id 1aCrta-000790-GN for 19421@debbugs.gnu.org; Sat, 26 Dec 2015 11:40:43 -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 tBQGeavC028104 (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sat, 26 Dec 2015 16:40:36 GMT Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0022.oracle.com (8.13.8/8.13.8) with ESMTP id tBQGeah0012831 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Sat, 26 Dec 2015 16:40:36 GMT Original-Received: from abhmp0002.oracle.com (abhmp0002.oracle.com [141.146.116.8]) by aserv0121.oracle.com (8.13.8/8.13.8) with ESMTP id tBQGeaTC029721; Sat, 26 Dec 2015 16:40:36 GMT In-Reply-To: <<83bn9dk208.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:110695 Archived-At: > What would you like us to say about ARGS? Say what it is for? Name and describe its structure or its parts, if any of them (NEW-WINDOW?) are significant? I don't know the functions, so I can't really say what might be appropriate to say about ARGS, here. > If you looked at the > functions that can be invoked by browse-url, you know that they either > ignore ARGS or (in a few cases) use ARGS to pass the NEW-WINDOW flag, > in which case the corresponding function documents that. If a given function that has an ARGS &rest parameter does nothing else with ARGS except pass it on to some other function, it is enough for the doc of the first function to say that - as usual. Certainly the function's doc should say nothing about "NEW-WINDOW" unless either NEW-WINDOW is in the parameter list or the doc describes it in terms of parameters that are in the list (e.g., as one of the members of argument-list ARGS). The mention of NEW-WINDOW comes out of the blue and is incomprehensible to a user reading the doc string (this user, at least). > So this ARGS thingy is really for custom-written browser functions, in > which case whoever writes them should know what ARGS are for, and > should document that in the doc string of the function she writes. I have no complaints about imaginary doc strings of possible user-written functions. The bug report is about doc strings of predefined Emacs functions that have ARGS as &rest parameter. > > Why not fix it? Why do you not respect the GNU Emacs conventions > > and its high standards of self-documentation? What possible good > > reason do you have for not doing the right thing, here? >=20 > Do you want us to say that ARGS are ignored? Is that what would in > your opinion fix this bug? I don't know the behavior, so I won't pretend to prescribe what the doc should say. IF the ARGS are always completely ignored by a function that accepts &rest ARGS as arguments, then that is not a doc problem - the function should not accept arguments if it in fact always ignores them. But if it passes the ARGS on to some other function (for example) then that's what the doc string should say. That is not ignoring the arguments. And in that case it need say nothing more than that: "ARGS are passed to function ____" or "ARGS are passed to the function that is the value of variable ____" or similar. This is the usual treatment, no? I don't think I'm inventing anything, here. > > As for `browse-url-default-browser', its doc string does not > > even have the lame excuse you used: > > > The doc string says "Passes any ARGS to the browser function." > > It says nothing at all about ARGS. >=20 > Because it is just a dispatcher -- it invokes other functions, > which mostly ignore ARGS altogether. Then that's what its doc should say: it passes ARGS to other functions (and name or otherwise specify what those functions are or can be). And whether or not those other functions ignore ARGS is irrelevant to _this_ doc string for _this_ function. > > At least in the latest Emacs 25 snapshot I have, which dates from > > 2015-12-04: > > > > * This is the parameters lambda list: (URL &rest ARGS). > > * This is how the parameters are described in the doc string: > > "When called non-interactively, optional second argument > > NEW-WINDOW is used instead of 'browse-url-new-window-flag'." > > > > That's it! Nothing about parameter URL. >=20 > I don't think URL should need any explanations in a package that > deals with browsing URLs. So this part is a red herring, IMO. It need not say that parameter URL is a url, granted. But it might want to say something about it being a string, or about it being passed to ____, or something else - I don't know. If you think there is nothing at all to say about URL, I'm OK with that. Frankly, I'm comfortable with you, Eli, just taking a look at the bug report. I'm not very happy with it having been summarily closed without any consideration. I'm not really keen to jump back in on this and argue about it - I really don't care that much. I would hope that someone would either take a considered look at it and DTRT or that it would simply remain open until someone does that. That's the proper respect to show to bug reports and to the users who took the time to report them - even when the reports might be mistaken or foolish. Users who report bugs are trying to improve Emacs. They are not trying to make life miserable for the volunteers who maintain Emacs and who are also, like the users who report bugs, trying to improve Emacs. If you don't have the time to consider a report carefully, then please leave it open for now. Closing bug reports summarily, just to get the numbers down (?), is the kind of misguided thing seen sometimes in non-free software circles. Back to the report... You dropped this: > And yet something about an "optional second argument > NEW-WINDOW", which is not even present in the lambda list. What about that? No doc bug? 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. No acknowledgment that I might have a point and there are indeed some problems with this doc string, there at least. Instead, a sermon that if I want help then I should not say that this doc string is a "mess" and it is a "shame" to summarily close such bugs instead of at least acknowledging them or (better) making a minimal attempt to improve the doc. It's perfectly understandable that such a bug is not regarded as high-priority. But if you recognize it as a bug then why close it? And if you do _not_ recognize that a doc string that talks about NEW-WINDOW and calls the function a command, when NEW-WINDOW is undefined wrt the parameter list and the function is not interactive, then I disagree - it is a bug. However insignificant one might think such a doc bug is, at least one user (and I hardly use browse-url) thinks it is important enough to report. Whether you want to spend time looking into it or fixing it is another question - I make no argument that this bug is very important. But why close it, if it is a bug? You have not heard me complaining that this bug has not been fixed. My complaint is about it being closed summarily. That's all.