From: Xue Fuqiao <xfq@gnu.org>
Date: Fri, 28 Feb 2014 01:49:25 +0000 (+0800)
Subject: Document `define-alternatives'.
X-Git-Tag: emacs-24.3.90~357^2
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=0fcfa97418aa7e7fa42887507e25b9bdf150cc66;p=emacs.git

Document `define-alternatives'.

* doc/lispref/elisp.texi (Top):
* doc/lispref/commands.texi (Generic Commands):
(Defining Commands): Document `define-alternatives'.

* etc/NEWS: Related edit.  Unrelated copyedit.
---

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index f32f88c18ae..650f97375d6 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2014-02-28  Xue Fuqiao  <xfq@gnu.org>
+
+	* elisp.texi (Top):
+	* commands.texi (Generic Commands):
+	(Defining Commands): Document `define-alternatives'.
+
 2014-02-27  Xue Fuqiao  <xfq@gnu.org>
 
 	* windows.texi (Window Sizes): Document `window-size'.
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 1df7a856a5d..e4494e7538f 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -134,6 +134,7 @@ from Lisp.
 * 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
@@ -575,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
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index b512968ff78..76b98576254 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -746,6 +746,8 @@ Defining Commands
 * 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.
+
 
 Input Events
 
diff --git a/etc/NEWS b/etc/NEWS
index b9240f2936f..d08efc818d2 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -730,7 +730,7 @@ are lined up to the first one.
 +++
 ** Octave mode
 
-*** Font locking for texinfo comments and new keywords.
+*** Font locking for Texinfo comments and new keywords.
 
 *** Completion in Octave file buffers.
 
@@ -1155,6 +1155,7 @@ treated as regexps rather than literal strings.
 +++
 ** New functions `special-form-p' and `macrop'.
 
++++
 ** New macro `define-alternatives' can be used to define generic commands.
 Generic commands are interactive functions whose implementation can be
 selected among several alternatives, as a matter of user preference.