bug#3936: 23.0.96; doc string of called-interactively-p

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