changeset 102721:f4b7df42308a

(Defining Commands): Clarify introduction. (Using Interactive): Not that interactive can be put in a symbol property. (Interactive Call): Note that a symbol with a non-nil interactive-form property satisfies commandp.

--- a/doc/lispref/commands.texi	Tue Mar 24 17:07:06 2009 +0000
+++ b/doc/lispref/commands.texi	Tue Mar 24 17:08:49 2009 +0000
@@ -102,12 +102,15 @@
 @cindex functions, making them interactive
 @cindex interactive function
 
-  A Lisp function becomes a command when its body contains, at top
-level, a form that calls the special form @code{interactive}, or if
-the function's symbol has an @code{interactive-form} property.  This
-form does nothing when actually executed, but its presence serves as a
-flag to indicate that interactive calling is permitted.  Its argument
-controls the reading of arguments for an interactive call.
+  The special form @code{interactive} turns a Lisp function into a
+command.  The @code{interactive} form must be located at top-level in
+the function body (usually as the first form in the body), or in the
+@code{interactive-form} property of the function symbol.  When the
+@code{interactive} form is located in the function body, it does
+nothing when actually executed.  Its presence serves as a flag, which
+tells the Emacs command loop that the function can be called
+interactively.  The argument of the @code{interactive} form controls
+the reading of arguments for an interactive call.
 
 @menu
 * Using Interactive::     General rules for @code{interactive}.
@@ -125,28 +128,33 @@
 examine a command's @code{interactive} form.
 
 @defspec interactive arg-descriptor
-This special form declares that the function in which it appears is a
-command, and that it may therefore be called interactively (via
-@kbd{M-x} or by entering a key sequence bound to it).  The argument
-@var{arg-descriptor} declares how to compute the arguments to the
-command when the command is called interactively.
+This special form declares that a function is a command, and that it
+may therefore be called interactively (via @kbd{M-x} or by entering a
+key sequence bound to it).  The argument @var{arg-descriptor} declares
+how to compute the arguments to the command when the command is called
+interactively.
 
 A command may be called from Lisp programs like any other function, but
 then the caller supplies the arguments and @var{arg-descriptor} has no
 effect.
 
-The @code{interactive} form has its effect because the command loop
-(actually, its subroutine @code{call-interactively}) scans through the
-function definition looking for it, before calling the function.  Once
-the function is called, all its body forms including the
-@code{interactive} form are executed, but at this time
-@code{interactive} simply returns @code{nil} without even evaluating its
-argument.
-
 @cindex @code{interactive-form}, function property
-An interactive form can be added to a function post-facto via the
-@code{interactive-form} property of the function's symbol.
-@xref{Symbol Plists}.
+The @code{interactive} form must be located at top-level in the
+function body, or in the function symbol's @code{interactive-form}
+property (@pxref{Symbol Plists}).  It has its effect because the
+command loop looks for it before calling the function
+(@pxref{Interactive Call}).  Once the function is called, all its body
+forms are executed; at this time, if the @code{interactive} form
+occurs within the body, the form simply returns @code{nil} without
+even evaluating its argument.
+
+By convention, you should put the @code{interactive} form in the
+function body, as the first top-level form.  If there is an
+@code{interactive} form in both the @code{interactive-form} symbol
+property and the function body, the former takes precedence.  The
+@code{interactive-form} symbol property can be used to add an
+interactive form to an existing function, or change how its arguments
+are processed interactively, without redefining the function.
 @end defspec
 
 There are three possibilities for the argument @var{arg-descriptor}:
@@ -553,9 +561,9 @@
 @section Interactive Call
 @cindex interactive call
 
-  After the command loop has translated a key sequence into a command it
-invokes that command using the function @code{command-execute}.  If the
-command is a function, @code{command-execute} calls
+  After the command loop has translated a key sequence into a command,
+it invokes that command using the function @code{command-execute}.  If
+the command is a function, @code{command-execute} calls
 @code{call-interactively}, which reads the arguments and calls the
 command.  You can also call these functions yourself.
 
@@ -563,14 +571,15 @@
 Returns @code{t} if @var{object} is suitable for calling interactively;
 that is, if @var{object} is a command.  Otherwise, returns @code{nil}.
 
-The interactively callable objects include strings and vectors (treated
-as keyboard macros), lambda expressions that contain a top-level call to
-@code{interactive}, byte-code function objects made from such lambda
-expressions, autoload objects that are declared as interactive
-(non-@code{nil} fourth argument to @code{autoload}), and some of the
-primitive functions.
-
-A symbol satisfies @code{commandp} if its function definition
+Interactively-callable objects include strings and vectors (which are
+treated as keyboard macros), lambda expressions that contain a
+top-level @code{interactive} form (@pxref{Using Interactive}),
+byte-code function objects made from such lambda expressions, autoload
+objects that are declared as interactive (non-@code{nil} fourth
+argument to @code{autoload}), and some primitive functions.
+
+A symbol satisfies @code{commandp} if it has a non-@code{nil}
+@code{interactive-form} property, or if its function definition
 satisfies @code{commandp}.  Keys and keymaps are not commands.
 Rather, they are used to look up commands (@pxref{Keymaps}).