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#3941: 23.0.96; doc for distinguishing interactive calls Date: Mon, 27 Jul 2009 00:43:32 -0700 Message-ID: <399BB9E1A8B54AB3A1C2AC4BCF27C9F2@us.oracle.com> Reply-To: Drew Adams , 3941@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 1248681472 24743 80.91.229.12 (27 Jul 2009 07:57:52 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 27 Jul 2009 07:57:52 +0000 (UTC) To: Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Jul 27 09:57:45 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 1MVL5c-0006Ff-Dc for geb-bug-gnu-emacs@m.gmane.org; Mon, 27 Jul 2009 09:57:44 +0200 Original-Received: from localhost ([127.0.0.1]:43103 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MVL5b-0008P1-CT for geb-bug-gnu-emacs@m.gmane.org; Mon, 27 Jul 2009 03:57:43 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1MVL5X-0008Ow-9m for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 03:57:39 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1MVL5S-0008OH-2b for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 03:57:38 -0400 Original-Received: from [199.232.76.173] (port=60003 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1MVL5R-0008OE-Uw for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 03:57:33 -0400 Original-Received: from mx20.gnu.org ([199.232.41.8]:14109) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MVL5R-0005SI-8e for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 03:57:33 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MVL5Q-0007wm-8J for bug-gnu-emacs@gnu.org; Mon, 27 Jul 2009 03:57:32 -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 n6R7vUJV026466; Mon, 27 Jul 2009 00:57:31 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.14.3/8.14.3/Submit) id n6R7o4KB025151; Mon, 27 Jul 2009 00:50:04 -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 07:50:04 +0000 Resent-Message-ID: Resent-Sender: owner@emacsbugs.donarmstrong.com X-Emacs-PR-Message: report 3941 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by submit@emacsbugs.donarmstrong.com id=B.124868060924298 (code B ref -1); Mon, 27 Jul 2009 07:50:04 +0000 Original-Received: (at submit) by emacsbugs.donarmstrong.com; 27 Jul 2009 07:43:29 +0000 X-Spam-Bayes: score:0.5 Bayes not run. spammytokens:Tokens not available. hammytokens:Tokens not available. Original-Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.14.3/8.14.3/Debian-5) with ESMTP id n6R7hNar024291 for ; Mon, 27 Jul 2009 00:43:25 -0700 Original-Received: from mx10.gnu.org ([199.232.76.166]:59370) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1MVKri-0000Ji-TT for emacs-pretest-bug@gnu.org; Mon, 27 Jul 2009 03:43:23 -0400 Original-Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1MVKrg-0003ww-7L for emacs-pretest-bug@gnu.org; Mon, 27 Jul 2009 03:43:22 -0400 Original-Received: from mx20.gnu.org ([199.232.41.8]:13197) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1MVKrf-0003wm-N2 for emacs-pretest-bug@gnu.org; Mon, 27 Jul 2009 03:43:19 -0400 Original-Received: from rcsinet11.oracle.com ([148.87.113.123] helo=rgminet11.oracle.com) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1MVKrf-00078R-0A for emacs-pretest-bug@gnu.org; Mon, 27 Jul 2009 03:43:19 -0400 Original-Received: from acsinet15.oracle.com (acsinet15.oracle.com [141.146.126.227]) by rgminet11.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n6R7j3iU004329 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 27 Jul 2009 07:45:05 GMT Original-Received: from abhmt010.oracle.com (abhmt010.oracle.com [141.146.116.19]) by acsinet15.oracle.com (Switch-3.3.1/Switch-3.3.1) with ESMTP id n6R7hPsQ022626 for ; Mon, 27 Jul 2009 07:43:26 GMT Original-Received: from dradamslap1 (/141.144.232.119) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Mon, 27 Jul 2009 00:43:13 -0700 X-Mailer: Microsoft Office Outlook 11 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5579 Thread-Index: AcoOjfB/73kcYjWFS0iZKYT1/XXykQ== X-Source-IP: abhmt010.oracle.com [141.146.116.19] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A010203.4A6D5A92.00B5:SCFSTAT5015188,ss=1,fgs=0 X-Detected-Operating-System: by mx20.gnu.org: GNU/Linux 2.6 (newer, 1) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) X-Detected-Operating-System: by mx20.gnu.org: GNU/Linux 2.6 (newer, 2) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) Resent-Date: Mon, 27 Jul 2009 03:57:38 -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:29651 gmane.emacs.pretest.bugs:24856 Archived-At: This bug report is about node (elisp)Distinguish Interactive. Starting with Emacs 22, you introduced `called-interactively-p'. As a result, the doc explaining testing for interactive use became worse, not better. The "recommended" way is presented first. Why it is recommended is not stated, and it's not clear to me (recommended for what use cases? why?). The "recommended" way does not really test whether a function was in fact called interactively. As the doc says, it has the particular benefit (which can also be a drawback) of letting Lisp code fake an interactive call by providing the optional arg. Yes, that can often be handy; no, that does not justify calling it "the recommended" test. Note that the Emacs 20-21 doc for this does not "recommend" anything. Rather, it speaks of "the most common use of `interactive-p'" being to print a message when interactive, and presents the optional arg technique as "the other way" to do that. IOW, the sense of that previous text has been twisted into something quite different. Next is presented `called-interactively-p'. But the examples given do not show anything particular about `called-interactively-p' - that is, they don't in any way distinguish it from `interactive-p'. In fact, those same examples were used in the Emacs 20-21 doc for `interactive-p'! IIUC, the main difference between these two is that `called-interactively-p' returns non-nil for a keyboard macro run interactively. The examples do not illustrate that difference at all, but one could get the impression that they are meant to point out the particularity of `called-interactively-p'. The only thing the examples illustrate is that it is the function that calls `called-interactively-p' that is being tested for interactive use - and that is true also for `interactive-p'. Furthermore, the important rationale behind `interactive-p' returning nil for a keyboard macro, present in the Emacs 20-21 doc, was simply dropped: "As a special exception, `interactive-p' returns `nil' whenever a keyboard macro is being run. This is to suppress the informative messages and speed execution of the macro." That speaks directly to why and when to use `interactive-p'. Far from dropping such a rationale, rationales describing use cases for the other two methods are also needed. Please rewrite this page. Describe the actual behavior differences between the 3 approaches and the different use cases they are each most appropriate for. My impression is that, most of the time, code wants to distinguish the case where the _user_ actually called the command interactively. To me, that certainly does not mean the use of an optional arg that could be faked by Lisp code. The Emacs 20-21 doc made clear that the optional arg technique is merely an alternative way to handle the most common case of printing a message for an interactive call. It should hardly be called "the recommended way to test whether the function was called using `call-interactively'". And it is wrong to introduce this general topic by mentioning that common case at the outset, as if it were the motivation for interactive-use testing in general. Even if that is the most common use case, this page is about much more than that use case. There are other reasons for code to test for an interactive call, besides printing a message. And to me an interactive-call test probably means `interactive-p' more often than `called-interactively-p', since it is a call using a key binding or via `M-x' that is typically distinguished. But I recognize that this is debatable: including interactive use of the command in a keyboard macro could alternatively be considered the more common case of the two. If it were I, I'd probably start with `interactive-p', as the most restrictive (test of most truly "interactive" use). Then I'd introduce `called-interactively-p', for cases where you want to also consider calls in a keyboard macro to be interactive. Finally, I'd introduce the optional arg cliche as a way to test interactiveness that also lets you fake it from Lisp (least restrictive in interactiveness). But I would understand if some other systematic presentation were used. In any case, some thought needs to be given to the overall presentation, the various use cases, and the order of presentation. What exists now is a confusing mess. Compare the Emacs 20-21 page this evolved from, and you will notice a quantum leap in muddle. In GNU Emacs 23.0.96.1 (i386-mingw-nt5.1.2600) of 2009-07-09 on SOFT-MJASON Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4)'