Re: how-many/count-matches for non-interactive use

[Richard Stallman <rms@gnu.org>]

I'm thinking of installing this doc string for Finteractive_p.
Any comments or suggestions?

    DEFUN ("interactive-p", Finteractive_p, Sinteractive_p, 0, 0, 0,
	   doc: /* Return t if the function was run directly by user input.
    This means that the function was called with call-interactively (which
    includes being called as the binding of a key)
    and input is currently coming from the keyboard (not in keyboard macro).

    The only known proper use of `interactive-p' is in deciding whether to
    print a helpful message.  If you're thinking of using it for any other
    purpose, it is quite likely that you're making a mistake.  Think: what
    do you want to do when the command is called from a keyboard macro?

    If you want to test whether your function was called with
    `call-interactively', the way to do that is by adding an extra
    optional argument, and making the `interactive' spec specify non-nil
    unconditionally for that argument.  (`p' is a good way to do this.)  */)

I'm also thinking of this change for commands.texi.
Any comments or suggestions?

*** commands.texi	08 Sep 2004 11:40:24 -0400	1.55
--- commands.texi	24 Oct 2004 04:52:32 -0400	
***************
*** 605,629 ****
  @end deffn
  
  @defun interactive-p
! This function returns @code{t} if the containing function (the one whose
! code includes the call to @code{interactive-p}) was called
! interactively, with the function @code{call-interactively}.  (It makes
! no difference whether @code{call-interactively} was called from Lisp or
! directly from the editor command loop.)  If the containing function was
! called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
! it was not called interactively.
! @end defun
  
!   The most common use of @code{interactive-p} is for deciding whether to
! print an informative message.  As a special exception,
! @code{interactive-p} returns @code{nil} whenever a keyboard macro is
! being run.  This is to suppress the informative messages and speed
! execution of the macro.
  
!   For example:
  
  @example
  @group
  (defun foo ()
    (interactive)
    (when (interactive-p)
--- 605,626 ----
  @end deffn
  
  @defun interactive-p
! This function returns @code{t} if the containing function (the one
! whose code includes the call to @code{interactive-p}) was called in
! direct response to user input.  This means that it was called with the
! function @code{call-interactively}, and that a keyboard macro is
! not running.
  
! If the containing function was called by Lisp evaluation (or with
! @code{apply} or @code{funcall}), then it was not called interactively.
! @end defun
  
!   The most common use of @code{interactive-p} is for deciding whether
! to print an informative message.  For example:
  
  @example
  @group
+ ;; @r{Here's the usual way to use @code{interactive-p}.}
  (defun foo ()
    (interactive)
    (when (interactive-p)
***************
*** 632,637 ****
--- 629,635 ----
  @end group
  
  @group
+ ;; @r{This function is just to illustrate the behavior.}
  (defun bar ()
    (interactive)
    (setq foobar (list (foo) (interactive-p))))
***************
*** 645,651 ****
  
  @group
  ;; @r{Type @kbd{M-x bar}.}
! ;; @r{This does not print anything.}
  @end group
  
  @group
--- 643,649 ----
  
  @group
  ;; @r{Type @kbd{M-x bar}.}
! ;; @r{This does not display a message.}
  @end group
  
  @group
***************
*** 654,663 ****
  @end group
  @end example
  
!   The other way to do this sort of job is to make the command take an
! argument @code{print-message} which should be non-@code{nil} in an
! interactive call, and use the @code{interactive} spec to make sure it is
! non-@code{nil}.  Here's how:
  
  @example
  (defun foo (&optional print-message)
--- 652,662 ----
  @end group
  @end example
  
!   If you want to test @emph{only} whether the function was called
! using @code{call-interactively}, add an optional argument
! @code{print-message} which should be non-@code{nil} in an interactive
! call, and use the @code{interactive} spec to make sure it is
! non-@code{nil}.  Here's an example:
  
  @example
  (defun foo (&optional print-message)