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: RE: doc of eval-defun (C-M-x) Date: Tue, 10 Jul 2007 14:58:21 -0700 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Trace: sea.gmane.org 1184104834 18796 80.91.229.12 (10 Jul 2007 22:00:34 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 10 Jul 2007 22:00:34 +0000 (UTC) Cc: bug-gnu-emacs@gnu.org To: "Eli Zaretskii" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Wed Jul 11 00:00:33 2007 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 1I8Nkv-0000SK-Vp for geb-bug-gnu-emacs@m.gmane.org; Wed, 11 Jul 2007 00:00:26 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1I8Nkv-0005SD-4i for geb-bug-gnu-emacs@m.gmane.org; Tue, 10 Jul 2007 18:00:25 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1I8Nkm-0005Od-8C for bug-gnu-emacs@gnu.org; Tue, 10 Jul 2007 18:00:16 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1I8Nkj-0005NM-TZ for bug-gnu-emacs@gnu.org; Tue, 10 Jul 2007 18:00:15 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1I8Nkj-0005NG-GF for bug-gnu-emacs@gnu.org; Tue, 10 Jul 2007 18:00:13 -0400 Original-Received: from agminet01.oracle.com ([141.146.126.228]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1I8NkZ-0005H5-Qt; Tue, 10 Jul 2007 18:00:04 -0400 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.186.110]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l6ALxmJH032102; Tue, 10 Jul 2007 16:59:49 -0500 Original-Received: from acsmt350.oracle.com (acsmt350.oracle.com [141.146.40.150]) by rgmgw1.us.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id l6AJw4YT005226; Tue, 10 Jul 2007 15:59:48 -0600 Original-Received: from dhcp-amer-csvpn-gw2-141-144-73-85.vpn.oracle.com by acsmt351.oracle.com with ESMTP id 3026374071184104706; Tue, 10 Jul 2007 14:58:26 -0700 X-Priority: 3 (Normal) X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook IMO, Build 9.0.6604 (9.0.2911.0) In-Reply-To: Importance: Normal X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3138 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: Linux 2.4-2.6 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:16132 Archived-At: > > As to explaining why it should be indexed, that explanation is now > > irrelevant, unfortunately, since RMS has said: > > > > > We don't use the index that way. > > > > Nevertheless, FWIW, my thinking was that, since `eval-defun' is > > discussed in that node, and this use of `eval-defun' is as > > common as the `edebug' use (IMO), it would be good to help > > readers find the discussion of `eval-defun' in the context of > > `defvar' and `defcustom' (and `defface' as well). We index > > the edebug discussion of `eval-defun'; we should also index the > > use with `C-M-x', which is just as common. > > I'm not sure I understand what Richard meant by ``use the index that > way'', but let me give you my personal perspective, FWIW: we do not > index each and every instance where a certain symbol is mentioned. No, of course not. No one has suggested doing that. > We always index the instance where it is explained in the most > detailed way, and then additionally index select other places > (appropriately qualified, as in "foo (and bar)") where it is > mentioned in the context of some other feature, if those places > reveal something important that isn't covered in the locus of > the main documentation. I more or less agree with that. > So the question is: what do those two nodes say about `eval-defun' > that its main documentation in the Emacs user manual does not? I don't think that is the question. You might say that the question is: what do those two nodes say about `eval-defun' that node `Instrumenting' of the Elisp manual, which is indexed, does not? The question of whether to index occurrences in the Elisp manual is limited to the Elisp manual - unless you are going to have Elisp manual index entries that send you to the Emacs manual. Here is what those two nodes say that node Instrumenting does not: 1. The fact that this applies to more than just function definitions, and it is used for more than (other than) debugging instrumentation. Instrumenting, which is the only indexed node, is about instrumenting function definitions (for debugging), and only "when you invoke [it]... on a function definition." 2. The fact that it overrides any original definition. In this it is different from `C-x C-e', for instance, wrt `defvar', `defcustom', and `defface'. In general, the context is different, and no mention is made, in node Instrumenting, of the other use context. The use case that is described in the other nodes is, IMO, at least as frequent as the debugging use case. The purpose of node Instrumenting is to explain instrumenting a function definition for debugging. As its first line says, "In order to use Edebug to debug Lisp code, you must first 'instrument' the code." You use `eval-defun' to do that, but that is not the only, or perhaps even the main (most common) use of `eval-defun'.