[Emacs-diffs] emacs/doc/lispref commands.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/03/24 17:08:49

Modified files:
        doc/lispref    : commands.texi 

Log message:
        (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.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/commands.texi?cvsroot=emacs&r1=1.15&r2=1.16

Patches:
Index: commands.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/commands.texi,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -b -r1.15 -r1.16
--- commands.texi       22 Mar 2009 15:12:01 -0000      1.15
+++ commands.texi       24 Mar 2009 17:08:49 -0000      1.16
@@ -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
address@hidden property of the function symbol.  When the
address@hidden 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
address@hidden or by entering a key sequence bound to it).  The argument
address@hidden 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
address@hidden form are executed, but at this time
address@hidden 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
address@hidden property of the function's symbol.
address@hidden 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
address@hidden form in both the @code{interactive-form} symbol
+property and the function body, the former takes precedence.  The
address@hidden 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
address@hidden, byte-code function objects made from such lambda
-expressions, autoload objects that are declared as interactive
-(address@hidden fourth argument to @code{autoload}), and some of the
-primitive functions.
+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 (address@hidden fourth
+argument to @code{autoload}), and some primitive functions.
 
-A symbol satisfies @code{commandp} if its function definition
+A symbol satisfies @code{commandp} if it has a address@hidden
address@hidden 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}).