From 1180b32c3155463b32aad65eddd339a04c17b883 Mon Sep 17 00:00:00 2001 From: Eshel Yaron Date: Fri, 29 Mar 2024 13:32:41 +0100 Subject: [PATCH] ; Update 'read-multiple-choice' documentation --- lisp/emacs-lisp/rmc.el | 58 +++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/lisp/emacs-lisp/rmc.el b/lisp/emacs-lisp/rmc.el index 11ccc99ccb2..3dc8a0af014 100644 --- 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 -- 2.39.5