[Emacs-diffs] Changes to emacs/doc/lispref/commands.texi,v

[Miles Bader]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Miles Bader <miles>     07/10/15 02:07:53

Index: doc/lispref/commands.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/doc/lispref/commands.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- doc/lispref/commands.texi   9 Oct 2007 08:52:55 -0000       1.3
+++ doc/lispref/commands.texi   15 Oct 2007 02:07:52 -0000      1.4
@@ -18,6 +18,7 @@
 * Command Overview::    How the command loop reads commands.
 * Defining Commands::   Specifying how a function should read arguments.
 * Interactive Call::    Calling a command, so that it will read arguments.
+* Distinguish Interactive::     Making a command distinguish interactive calls.
 * Command Loop Info::   Variables set by the command loop for you to examine.
 * Adjusting Point::     Adjustment of point after a command.
 * Input Events::       What input looks like when you read it.
@@ -635,42 +636,74 @@
 @end example
 @end deffn
 
address@hidden 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, and that Emacs is not running in batch mode.
address@hidden Distinguish Interactive
address@hidden Distinguish Interactive Calls
+
+  Sometimes a command should display additional visual feedback (such
+as an informative message in the echo area) for interactive calls
+only.  There are three ways to do this.  The recommended way to test
+whether the function was called using @code{call-interactively} is to
+give it an optional argument @code{print-message} and use the
address@hidden spec to make it address@hidden in interactive
+calls.  Here's an example:
+
address@hidden
+(defun foo (&optional print-message)
+  (interactive "p")
+  (when print-message
+    (message "foo")))
address@hidden example
+
address@hidden
+We use @code{"p"} because the numeric prefix argument is never
address@hidden  Defined in this way, the function does display the
+message when called from a keyboard macro.
+
+  The above method with the additional argument is usually best,
+because it allows callers to say ``treat this call as interactive.''
+But you can also do the job in a simpler way by testing
address@hidden
+
address@hidden called-interactively-p
+This function returns @code{t} when the calling function was called
+using @code{call-interactively}.
 
 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 give the user additional visual feedback (such as by printing an
-informative message).  For example:
+   Here's an example of using @code{called-interactively-p}:
 
 @example
 @group
-;; @r{Here's the usual way to use @code{interactive-p}.}
 (defun foo ()
   (interactive)
-  (when (interactive-p)
-    (message "foo")))
+  (when (called-interactively-p)
+    (message "foo"))
+  'haha)
      @result{} foo
 @end group
 
 @group
-;; @r{This function is just to illustrate the behavior.}
-(defun bar ()
-  (interactive)
-  (setq foobar (list (foo) (interactive-p))))
-     @result{} bar
+;; @r{Type @kbd{M-x foo}.}
+     @print{} foo
 @end group
 
 @group
-;; @r{Type @kbd{M-x foo}.}
-     @print{} foo
+(foo)
+     @result{} haha
address@hidden group
address@hidden example
+
+  Here is another example that contrasts direct and indirect
+calls to @code{called-interactively-p}.
+
address@hidden
address@hidden
+(defun bar ()
+  (interactive)
+  (setq foobar (list (foo) (called-interactively-p))))
+     @result{} bar
 @end group
 
 @group
@@ -684,31 +717,16 @@
 @end group
 @end example
 
-  If you want to test @emph{only} whether the function was called
-using @code{call-interactively}, add an optional argument
address@hidden which should be address@hidden in an interactive
-call, and use the @code{interactive} spec to make sure it is
address@hidden  Here's an example:
-
address@hidden
-(defun foo (&optional print-message)
-  (interactive "p")
-  (when print-message
-    (message "foo")))
address@hidden example
-
address@hidden
-Defined in this way, the function does display the message when called
-from a keyboard macro.  We use @code{"p"} because the numeric prefix
-argument is never @code{nil}.
-
address@hidden called-interactively-p
-This function returns @code{t} when the calling function was called
-using @code{call-interactively}.
+  If you want to treat commands run in keyboard macros just like calls
+from Lisp programs, test @code{interactive-p} instead of
address@hidden
 
-When possible, instead of using this function, you should use the
-method in the example above; that method makes it possible for a
-caller to ``pretend'' that the function was called interactively.
address@hidden 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, and that Emacs is not running in batch mode.
 @end defun
 
 @node Command Loop Info