bug#3941: 23.0.96; doc for distinguishing interactive calls

bug#3941: 23.0.96; doc for distinguishing interactive calls

[Drew Adams]

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

bug#3941: 23.0.96; doc for distinguishing interactive calls

[Drew Adams]

Sorry that I didn't include anything about the doc string of `interactive-p'
when I reported this bug. As should be clear from what I wrote, that doc string
is also horrible. Please remove the last two paragraphs entirely - the first
paragraph is OK.

"The only known proper use of `interactive-p'..." - that's garbage. You make it
sound like something unclean and bizarre, if not perverted. This is a total
twisting of what was said in Emacs 20-21 about the simple, common use case of
displaying a message only for interactive use. From "the most common use case"
we have moved to "the only known proper use". Soon we will be burning witches.
;-)

Simply state that `interactive-p' returns nil when called during interactive
execution of a keyboard macro, and that if you want a non-nil value in that use
case then use `called-interactively-p' instead. That's all. No big deal.

And fix the doc string of `called-interactively-p' similarly, to mention that
difference from `interactive-p'. And remove its similar moralizing about "the
cleanest way". And why say "This is used for implementing advice and other
function-modifying features of Emacs"? That is misleading, and it doesn't help a
bit.

Except for that difference of behavior wrt keyboard macros, IIUC, these two
functions behave the same. There is absolutely no reason for the misleading and
alarmist tone of the doc strings. Each function has a behavior and a purpose.

Please stop with the "the way to do that is" and "the only known proper use is"
and "the recommended way is". (Someone spent too much time at catechism.) Just
give users technical _information_ about (a) the behaviors and hence (b)
appropriate use cases. Forget about what's "proper" and "the way". That's not
helpful.

bug#3941: 23.0.96; doc for distinguishing interactive calls

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

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

Separating out the interactive parts into the `interactive' spec is just
good style, instead of sprinkling the code further down for
interactiveness.

I've read the node in question now, and I think it's quite clear, and
doesn't say anything I disagree with much, so I'm closing this bug
report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#3941: 23.0.96; doc for distinguishing interactive calls

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Sorry that I didn't include anything about the doc string of
> `interactive-p' when I reported this bug. As should be clear from what
> I wrote, that doc string is also horrible. Please remove the last two
> paragraphs entirely - the first paragraph is OK.

`interactive-p' is deprecated and will be going away.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/