Subject: RE: bug#3941: 23.0.96; doc for distinguishing interactive calls

From: "Drew Adams" <[email-masked]>
Date: Mon, 27 Jul 2009 01:17:23 -0700

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.