RE: doc of eval-defun (C-M-x)

["Drew Adams" <drew.adams@oracle.com>]

> > 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'.