interactive-p and called-interactively-p

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

1. The doc for these two functions is a mess - see bug #3941.

2. Beyond the doc problem, but related to it, 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'
tells. There is nothing in the _names_ that distinguishes these two functions.
Might as well have named the new function `interactive-p-2' (no, it's not a
suggestion).

This fact is a sign that the design is wrong, for if we did come up with names
that suggest the distinction, we would soon see that using two different
functions is the wrong approach. This is really one function with two minor
behavioral variants.

It would have been far better to just 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 the 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]"

Leaving the status quo in place will bring nothing but confusion, no matter how
the doc is improved. It is better to just DTRT now.

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.