From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs,gmane.emacs.pretest.bugs Subject: bug#3936: 23.0.96; doc string of called-interactively-p Date: Mon, 27 Jul 2009 09:04:17 -0700 Message-ID: <02DB279632ED43DC9D58AC05960C61E1@us.oracle.com> References: <09B238050EFB472EBBBFDCFF9B184113@us.oracle.com><878wiaq3tl.fsf@bzg.ath.cx><87r5w2lj6v.fsf@bzg.ath.cx><5D6C9B27AFE44D5BA9E8EC53F6BA9CB9@us.oracle.com> <87prbmwklv.fsf@bzg.ath.cx> Reply-To: Drew Adams , 3936@emacsbugs.donarmstrong.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1248714376 3664 80.91.229.12 (27 Jul 2009 17:06:16 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 27 Jul 2009 17:06:16 +0000 (UTC) Cc: emacs-pretest-bug@gnu.org, 3936@emacsbugs.donarmstrong.com To: "'Bastien'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jul 27 19:06:09 2009 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1MVTeK-0003J7-EV for geb-bug-gnu-emacs@m.gmane.org; Mon, 27 Jul 2009 19:06:08 +0200 Original-Received: from localhost ([127.0.0.1]:60920 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MVTeJ-0005fR-RW for geb-bug-gnu-emacs@m.gmane.org; Mon, 27 Jul 2009 13:06:07 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MVStZ-0004Sg-7r for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 12:17:49 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MVStQ-0004PE-PT for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 12:17:47 -0400 Original-Received: from [199.232.76.173] (port=48194 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MVStQ-0004P5-FZ for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 12:17:40 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:37318) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MVStP-000515-AY for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 12:17:40 -0400 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n6RGHUib018339; Mon, 27 Jul 2009 09:17:31 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.14.3/8.14.3/Submit) id n6RGA7jI016877; Mon, 27 Jul 2009 09:10:07 -0700 X-Loop: owner@emacsbugs.donarmstrong.com Resent-From: "Drew Adams" Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Mon, 27 Jul 2009 16:10:07 +0000 Resent-Message-ID: Resent-Sender: owner@emacsbugs.donarmstrong.com X-Emacs-PR-Message: followup 3936 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by 3936-submit@emacsbugs.donarmstrong.com id=B3936.124871067215174 (code B ref 3936); Mon, 27 Jul 2009 16:10:07 +0000 Original-Received: (at 3936) by emacsbugs.donarmstrong.com; 27 Jul 2009 16:04:32 +0000 X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. Original-Received: from acsinet11.oracle.com (acsinet11.oracle.com [141.146.126.233]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n6RG4SPV015168 for <3936@emacsbugs.donarmstrong.com>; Mon, 27 Jul 2009 09:04:29 -0700 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by acsinet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n6RG4dGY029642 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 27 Jul 2009 16:04:40 GMT Original-Received: from abhmt003.oracle.com (abhmt003.oracle.com [141.146.116.12]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n6RG4U5g008792; Mon, 27 Jul 2009 16:04:30 GMT Original-Received: from dradamslap1 (/130.35.178.194) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 27 Jul 2009 09:04:17 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <87prbmwklv.fsf@bzg.ath.cx> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 Thread-Index: AcoOmzLj2zHg5SI3QqCqRuWrygc07AANqkLA X-Source-IP: abhmt003.oracle.com [141.146.116.12] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010205.4A6DD003.01C7:SCFSTAT5015188,ss=1,fgs=0 X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6 (newer, 2) Resent-Date: Mon, 27 Jul 2009 12:17:46 -0400 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:29659 gmane.emacs.pretest.bugs:24863 Archived-At: > > In particular, the doc strings of `called-interactively-p' > > and `interactive-p' should, together, make clear their > > difference. They can't both just say that they test for > > an interactive call. They need to speak about keyboard > > macro use as the difference in behavior. > > Please suggest a docstring for both these functions. > If your suggested dosctrings are clearer, we will clearly see it. > > By trying to explain in a very wordy fashion what is *not* > clear to you, you're at risk of not being clear yourself. I think I was clear enough. Fix the Elisp manual first; the doc strings will follow easily. If you don't understand what I wrote or are unwilling to work on it, perhaps someone else will. The doc is not just unclear; it is wrong/bad, as I pointed out specifically. In addition to the doc problems I listed, there is a non-doc problem: Whoever came up with the new function (in Emacs 22) `called-interactively-p' did the wrong thing, IMO. That function name tells nothing more nor less than the name `interactive-p' - there is nothing in the names that distinguishes these functions. Might as well have named the new function `interactive-p-2' (no, it's not a suggestion). It would have been far better to add an optional argument to `interactive-p' than to create a new, similarly named function. For example: (defun interactive-p (&optional k-macro-p) "Return t if function in which this appears was called interactively. If optional arg K-MACRO-P is non-nil, return t when called during execution of a keyboard macro. If it is nil, return nil in that case. ...[rest of description]" I vote for deprecating one or the other of these two functions, combining them by using an optional argument to express the alternative behaviors. That will go a long way toward clarifying the intended uses.