; Update 'read-multiple-choice' documentation

diff --git a/lisp/emacs-lisp/rmc.el b/lisp/emacs-lisp/rmc.el
index 11ccc99ccb2035482d1eb3e7ede0e618a831dff5..3dc8a0af0149d0b70f15e50ec9f9b0489e64d057 100644 (file)
--- a/lisp/emacs-lisp/rmc.el
+++ b/lisp/emacs-lisp/rmc.el
@@ -154,21 +154,25 @@
 This function is used to ask the user a question with multiple
 choices.
 
-CHOICES should be a list of the form (KEY NAME [DESCRIPTION]).
-KEY is a character the user should type to select the entry.
-NAME is a short name for the entry to be displayed while prompting
-\(if there's no room, it might be shortened).
-DESCRIPTION is an optional longer description of the entry; it will
-be displayed in a help buffer if the user requests more help.  This
-help description has a fixed format in columns.  For greater
-flexibility, instead of passing a DESCRIPTION, the caller can pass
-the optional argument HELP-STRING.  This argument is a string that
-should contain a more detailed description of all of the possible
-choices.  `read-multiple-choice' will display that description in a
-help buffer if the user requests that.
-If optional argument SHOW-HELP is non-nil, show the help screen
-immediately, before any user input.  If SHOW-HELP is a string,
-use it as the name of the help buffer.
+CHOICES should be a list of the form (KEY NAME [DESCRIPTION]).  KEY is a
+character the user should type to select the entry.  NAME is a short
+name for the entry to be displayed while prompting (if there's no room,
+it might be shortened).  Alternatively, KEY can be a function that
+computes the character for the entry dynamically.  Such a key assignment
+function is called with two arguments, NAME and CHOICES, and should
+return either a character or nil to signal failure.  KEY can also be
+nil, which says to use `read-multiple-choice-assign-key-function' as the
+key assignment function for this entry.  DESCRIPTION is an optional
+longer description of the entry; it will be displayed in a help buffer
+if the user requests more help.  This help description has a fixed
+format in columns.  For greater flexibility, instead of passing a
+DESCRIPTION, the caller can pass the optional argument HELP-STRING.
+This argument is a string that should contain a more detailed
+description of all of the possible choices.  `read-multiple-choice' will
+display that description in a help buffer if the user requests that.  If
+optional argument SHOW-HELP is non-nil, show the help screen
+immediately, before any user input.  If SHOW-HELP is a string, use it as
+the name of the help buffer.
 
 This function translates user input into responses by consulting
 the bindings in `query-replace-map'; see the documentation of
@@ -289,17 +293,19 @@ Usage example:
                  (ignore-errors (scroll-other-window)))
                 ('scroll-other-window-down
                  (ignore-errors (scroll-other-window-down)))
-                (_ (setq invalid-choice
-                         (concat "Invalid choice "
-                                 (propertize (key-description (vector tchar))
-                                             'face 'read-multiple-choice-face)
-                                 ", choose one of the following (or "
-                                 (propertize "C-h" 'face 'read-multiple-choice-face)
-                                 " for help, "
-                                 (propertize "C-g" 'face 'read-multiple-choice-face)
-                                 " to quit, "
-                                 (propertize "C-r" 'face 'read-multiple-choice-face)
-                                 " to pause):\n")))))
+                (_                      ; Invalid input.
+                 (ding)
+                 (setq invalid-choice
+                       (concat "Invalid choice "
+                               (propertize (key-description (vector tchar))
+                                           'face 'read-multiple-choice-face)
+                               ", choose one of the following ("
+                               (propertize "C-h" 'face 'read-multiple-choice-face)
+                               " for help, "
+                               (propertize "C-g" 'face 'read-multiple-choice-face)
+                               " to quit, "
+                               (propertize "C-r" 'face 'read-multiple-choice-face)
+                               " to pause):\n")))))
             (message (concat invalid-choice full-prompt))
             (setq tchar
                   (condition-case nil