Document pixelwise frame resizing and fix related bug on Windows.

[bpt/emacs.git] / doc / lispref / commands.texi

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index a118e91..e4494e7 100644 (file)
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -108,19 +108,33 @@ command does.
 
   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.
+the function body, usually as the first form in the body; this applies
+to both lambda expressions (@pxref{Lambda Expressions}) and
+@code{defun} forms (@pxref{Defining Functions}).  This form does
+nothing during the actual execution of the function; its presence
+serves as a flag, telling the Emacs command loop that the function can
+be called interactively.  The argument of the @code{interactive} form
+specifies how the arguments for an interactive call should be read.
+
+@cindex @code{interactive-form} property
+  Alternatively, an @code{interactive} form may be specified in a
+function symbol's @code{interactive-form} property.  A non-@code{nil}
+value for this property takes precedence over any @code{interactive}
+form in the function body itself.  This feature is seldom used.
+
+@cindex @code{interactive-only} property
+  Sometimes, a named command is only intended to be called
+interactively, never directly from Lisp.  In that case, give it a
+non-@code{nil} @code{interactive-only} property.  In that case, the
+byte compiler will print a warning message if the command is called
+from Lisp.
 
 @menu
 * Using Interactive::     General rules for @code{interactive}.
 * Interactive Codes::     The standard letter-codes for reading arguments
                              in various ways.
 * Interactive Examples::  Examples of how to read interactive arguments.
+* Generic Commands::      Select among command alternatives.
 @end menu
 
 @node Using Interactive
@@ -562,6 +576,39 @@ Put them into three windows, selecting the last one."
 @end group
 @end example
 
+@node Generic Commands
+@subsection Select among Command Alternatives
+@cindex generic commands
+@cindex alternatives, defining
+
+The macro @code{define-alternatives} can be used to define
+@dfn{generic commands}.  Generic commands are interactive functions
+whose implementation can be selected among several alternatives, as a
+matter of user preference.
+
+@defmac define-alternatives command &rest customizations
+Define the new command `COMMAND'.
+
+The argument `COMMAND' should be a symbol.
+
+When a user runs @kbd{M-x COMMAND @key{RET}} for the first time, Emacs
+will prompt for which alternative to use and record the selected
+command as a custom variable.
+
+Running @kbd{C-u M-x COMMAND @key{RET}} prompts again for an
+alternative and overwrites the previous choice.
+
+The variable @code{COMMAND-alternatives} contains an alist
+(@pxref{Association Lists}) with alternative implementations of
+`COMMAND'.  @code{define-alternatives} does not have any effect until
+this variable is set.
+
+If @var{customizations} is non-@var{nil}, it should be composed of
+alternating @code{defcustom} keywords and values to add to the
+declaration of @code{COMMAND-alternatives} (typically :group and
+:version).
+@end defmac
+
 @node Interactive Call
 @section Interactive Call
 @cindex interactive call
@@ -1921,9 +1968,12 @@ must be the last element of the list.  For example,
 @node Accessing Mouse
 @subsection Accessing Mouse Events
 @cindex mouse events, data in
+@cindex keyboard events, data in
 
   This section describes convenient functions for accessing the data in
-a mouse button or motion event.
+a mouse button or motion event.  Keyboard event data can be accessed
+using the same functions, but data elements that aren't applicable to
+keyboard events are zero or @code{nil}.
 
   The following two functions return a mouse position list
 (@pxref{Click Events}), specifying the position of a mouse event.
@@ -3031,7 +3081,7 @@ in @ref{Errors}.)
 @end deffn
 
   You can specify a character other than @kbd{C-g} to use for quitting.
-See the function @code{set-input-mode} in @ref{Terminal Input}.
+See the function @code{set-input-mode} in @ref{Input Modes}.
 
 @node Prefix Command Arguments
 @section Prefix Command Arguments