bug#3941: 23.0.96; doc for distinguishing interactive calls

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

This bug report is about node (elisp)Distinguish Interactive.
Starting with Emacs 22, you introduced `called-interactively-p'.  As a
result, the doc explaining testing for interactive use became worse,
not better.
 
The "recommended" way is presented first.  Why it is recommended is
not stated, and it's not clear to me (recommended for what use cases?
why?).  The "recommended" way does not really test whether a function
was in fact called interactively.  As the doc says, it has the
particular benefit (which can also be a drawback) of letting Lisp code
fake an interactive call by providing the optional arg.  Yes, that can
often be handy; no, that does not justify calling it "the recommended"
test.
 
Note that the Emacs 20-21 doc for this does not "recommend" anything.
Rather, it speaks of "the most common use of `interactive-p'" being to
print a message when interactive, and presents the optional arg
technique as "the other way" to do that.  IOW, the sense of that
previous text has been twisted into something quite different.
 
Next is presented `called-interactively-p'.  But the examples given do
not show anything particular about `called-interactively-p' - that is,
they don't in any way distinguish it from `interactive-p'.  In fact,
those same examples were used in the Emacs 20-21 doc for
`interactive-p'!
 
IIUC, the main difference between these two is that
`called-interactively-p' returns non-nil for a keyboard macro run
interactively.  The examples do not illustrate that difference at all,
but one could get the impression that they are meant to point out the
particularity of `called-interactively-p'.  The only thing the
examples illustrate is that it is the function that calls
`called-interactively-p' that is being tested for interactive use -
and that is true also for `interactive-p'.
 
Furthermore, the important rationale behind `interactive-p' returning
nil for a keyboard macro, present in the Emacs 20-21 doc, was simply
dropped: "As a special exception, `interactive-p' returns `nil'
whenever a keyboard macro is being run.  This is to suppress the
informative messages and speed execution of the macro."  That speaks
directly to why and when to use `interactive-p'.
 
Far from dropping such a rationale, rationales describing use cases
for the other two methods are also needed.
 
Please rewrite this page.  Describe the actual behavior differences
between the 3 approaches and the different use cases they are each
most appropriate for.
 
My impression is that, most of the time, code wants to distinguish the
case where the _user_ actually called the command interactively.  To
me, that certainly does not mean the use of an optional arg that could
be faked by Lisp code.
 
The Emacs 20-21 doc made clear that the optional arg technique is
merely an alternative way to handle the most common case of printing a
message for an interactive call.  It should hardly be called "the
recommended way to test whether the function was called using
`call-interactively'".
 
And it is wrong to introduce this general topic by mentioning that
common case at the outset, as if it were the motivation for
interactive-use testing in general.  Even if that is the most common
use case, this page is about much more than that use case.  There are
other reasons for code to test for an interactive call, besides
printing a message.
 
And to me an interactive-call test probably means `interactive-p' more
often than `called-interactively-p', since it is a call using a key
binding or via `M-x' that is typically distinguished.  But I recognize
that this is debatable: including interactive use of the command in a
keyboard macro could alternatively be considered the more common case
of the two.
 
If it were I, I'd probably start with `interactive-p', as the most
restrictive (test of most truly "interactive" use).  Then I'd
introduce `called-interactively-p', for cases where you want to also
consider calls in a keyboard macro to be interactive.  Finally, I'd
introduce the optional arg cliche as a way to test interactiveness
that also lets you fake it from Lisp (least restrictive in
interactiveness).
 
But I would understand if some other systematic presentation were
used.  In any case, some thought needs to be given to the overall
presentation, the various use cases, and the order of presentation.
What exists now is a confusing mess.  Compare the Emacs 20-21 page
this evolved from, and you will notice a quantum leap in muddle.

 
In GNU Emacs 23.0.96.1 (i386-mingw-nt5.1.2600)
 of 2009-07-09 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'