[Emacs-diffs] trunk r116588: Document `define-alternatives'.

[Xue Fuqiao]

------------------------------------------------------------
revno: 116588 [merge]
revision-id: address@hidden
parent: address@hidden
parent: address@hidden
committer: Xue Fuqiao <address@hidden>
branch nick: trunk
timestamp: Fri 2014-02-28 09:51:15 +0800
message:
  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.
modified:
  doc/lispref/ChangeLog          changelog-20091113204419-o5vbwnq5f7feedwu-6155
  doc/lispref/commands.texi      
commands.texi-20091113204419-o5vbwnq5f7feedwu-6165
  doc/lispref/elisp.texi         elisp.texi-20091113204419-o5vbwnq5f7feedwu-6176
  etc/NEWS                       news-20100311060928-aoit31wvzf25yr1z-1

=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog     2014-02-27 14:09:26 +0000
+++ b/doc/lispref/ChangeLog     2014-02-28 01:49:25 +0000
@@ -1,3 +1,9 @@
+2014-02-28  Xue Fuqiao  <address@hidden>
+
+       * elisp.texi (Top):
+       * commands.texi (Generic Commands):
+       (Defining Commands): Document `define-alternatives'.
+
 2014-02-27  Xue Fuqiao  <address@hidden>
 
        * windows.texi (Window Sizes): Document `window-size'.

=== modified file 'doc/lispref/commands.texi'
--- a/doc/lispref/commands.texi 2014-02-09 04:19:52 +0000
+++ b/doc/lispref/commands.texi 2014-02-28 01:49:25 +0000
@@ -134,6 +134,7 @@
 * 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 @@
 @end group
 @end example
 
address@hidden Generic Commands
address@hidden Select among Command Alternatives
address@hidden generic commands
address@hidden alternatives, defining
+
+The macro @code{define-alternatives} can be used to define
address@hidden commands}.  Generic commands are interactive functions
+whose implementation can be selected among several alternatives, as a
+matter of user preference.
+
address@hidden 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 address@hidden, it should be composed of
+alternating @code{defcustom} keywords and values to add to the
+declaration of @code{COMMAND-alternatives} (typically :group and
+:version).
address@hidden defmac
+
 @node Interactive Call
 @section Interactive Call
 @cindex interactive call

=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi    2014-02-21 08:04:15 +0000
+++ b/doc/lispref/elisp.texi    2014-02-28 01:49:25 +0000
@@ -746,6 +746,8 @@
 * 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
 

=== modified file 'etc/NEWS'
--- a/etc/NEWS  2014-02-28 01:05:49 +0000
+++ b/etc/NEWS  2014-02-28 01:49:25 +0000
@@ -730,7 +730,7 @@
 +++
 ** 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 @@
 +++
 ** 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.