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

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

[Drew Adams]

1. `eval-defun' is not in the Elisp manual index, except for one
   occurrence in the section on edebug.  Nodes `Defining Variables'
   and `Variable Definitions' should be indexed for `eval-defun'.

2. The doc string of `eval-defun' mentions only `defvar' and
   `defcustom'.  It should also mention the same behavior for
   `defface'.

3. The Elisp manual, node Defining Faces, which discusses `defface',
   should also mention the C-M-x (`eval-defun') behavior for
   `defface'.  The nodes discussing `defvar' and `defcustom' mention
   it, but `defface' was forgotten.


In GNU Emacs 22.1.1 (i386-mingw-nt5.1.2600)
 of 2007-06-02 on RELEASE
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Ic:/gnuwin32/include'

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

[Richard Stallman]

    1. `eval-defun' is not in the Elisp manual index, except for one
       occurrence in the section on edebug.  Nodes `Defining Variables'
       and `Variable Definitions' should be indexed for `eval-defun'.

We don't use the index that way.

    2. The doc string of `eval-defun' mentions only `defvar' and
       `defcustom'.  It should also mention the same behavior for
       `defface'.

    3. The Elisp manual, node Defining Faces, which discusses `defface',
       should also mention the C-M-x (`eval-defun') behavior for
       `defface'.  The nodes discussing `defvar' and `defcustom' mention
       it, but `defface' was forgotten.

I fixed these.  Thanks for reporting them.

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Mon, 9 Jul 2007 15:30:52 -0700
> 
>    Nodes `Defining Variables'
>    and `Variable Definitions' should be indexed for `eval-defun'.

Can you explain why?  `eval-defun' is fully described in the Emacs
manual (and indexed there), so why would we need to describe it again
in the ELisp manual?

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

[Drew Adams]

> >    Nodes `Defining Variables'
> >    and `Variable Definitions' should be indexed for `eval-defun'.
>
> Can you explain why?  `eval-defun' is fully described in the Emacs
> manual (and indexed there), so why would we need to describe it again
> in the ELisp manual?

It's already described in the Elisp manual. I'm asking that the existing
description be indexed.

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.

This is in the Elisp manual presumably because Emacs-Lisp programmers are
interested in it, and indexing it helps them find it. IMO, Emacs-Lisp
programmers are also those most likely to use `C-M-x' (`eval-defun').

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Cc: <bug-gnu-emacs@gnu.org>
> Date: Tue, 10 Jul 2007 09:19:28 -0700
> 
> 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.  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.

So the question is: what do those two nodes say about `eval-defun'
that its main documentation in the Emacs user manual does not?

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

[Drew Adams]

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

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

[Richard Stallman]

    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.

That's it.