bug#70576: [PATCH] `repeat-echo-message-string': support repeat keymap "hints"

[Juri Linkov]

>> (defvar-keymap expreg-repeat-map
>>    :doc "Repeat map for `expreg' actions."
>>    :repeat '(:hints ((expreg-expand . "expand") (expreg-contract . 
>> "contract")))
>>    "\\" 'expreg-expand
>>    "|"  'expreg-contract)
>
> If a hint is missing for a command, it should just have its key mentioned.
> It looks like your idea would require changes to defvar-keymap.  Do you
> want to propose a patch?  We'd need some way to pass the hints in; perhaps
> the macro could set a property on the command symbol as you initially
> proposed.

Alright, let's add this to defvar-keymap.  Please try the following patch.

PS: Do you still think a new custom variable should be added to be able to
disable hint strings?

diff --git a/lisp/keymap.el b/lisp/keymap.el
index b2b475c7d71..cbd26f1060e 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -603,10 +603,11 @@ defvar-keymap
 symbol property.
 
 More control is available over which commands are repeatable; the
-value can also be a property list with properties `:enter' and
-`:exit', for example:
+value can also be a property list with properties `:enter',
+`:exit' and `:hints', for example:
 
-     :repeat (:enter (commands ...) :exit (commands ...))
+     :repeat (:enter (commands ...) :exit (commands ...)
+              :hints ((command . \"hint\") ...))
 
 `:enter' specifies the list of additional commands that only
 enter `repeat-mode'.  When the list is empty, then only the
@@ -621,6 +622,10 @@ defvar-keymap
 in this specific map, but should not have the `repeat-map' symbol
 property.
 
+`:hints' is a list of cons pairs where car is a command and
+cdr is a string that is displayed alongside of the repeatable key
+in the echo area.
+
 \(fn VARIABLE-NAME &key DOC FULL PARENT SUPPRESS NAME PREFIX KEYMAP REPEAT 
&rest [KEY DEFINITION]...)"
   (declare (indent 1))
   (let ((opts nil)
@@ -660,7 +665,9 @@ defvar-keymap
           (setq def (pop defs))
           (when (and (memq (car def) '(function quote))
                      (not (memq (cadr def) (plist-get repeat :exit))))
-            (push `(put ,def 'repeat-map ',variable-name) props)))))
+            (push `(put ,def 'repeat-map ',variable-name) props)))
+        (dolist (def (plist-get repeat :hints))
+          (push `(put ',(car def) 'repeat-hint ',(cdr def)) props))))
 
     (let ((defvar-form
            `(defvar ,variable-name
diff --git a/lisp/repeat.el b/lisp/repeat.el
index 0a59494c097..b9c96fa4e12 100644
--- a/lisp/repeat.el
+++ b/lisp/repeat.el
@@ -553,20 +553,27 @@ repeat--clear-prev
 (defun repeat-echo-message-string (keymap)
   "Return a string with the list of repeating keys in KEYMAP."
   (let (keys)
-    (map-keymap (lambda (key cmd) (and cmd (push key keys))) keymap)
-    (format-message "Repeat with %s%s"
-                    (mapconcat (lambda (key)
-                                 (substitute-command-keys
-                                  (format "\\`%s'"
-                                          (key-description (vector key)))))
-                               keys ", ")
-                    (if repeat-exit-key
-                        (substitute-command-keys
-                         (format ", or exit with \\`%s'"
-                                 (if (key-valid-p repeat-exit-key)
-                                     repeat-exit-key
-                                   (key-description repeat-exit-key))))
-                      ""))))
+    (map-keymap (lambda (key cmd) (and cmd (push (cons key cmd) keys)))
+                keymap)
+    (format-message
+     "Repeat with %s%s"
+     (mapconcat (lambda (key-cmd)
+                  (let* ((key (car key-cmd))
+                         (cmd (cdr key-cmd))
+                         (hint (when (symbolp cmd)
+                                 (get cmd 'repeat-hint))))
+                    (substitute-command-keys
+                     (format "\\`%s'%s"
+                             (key-description (vector key))
+                             (if hint (format "(%s)" hint) "")))))
+                keys ", ")
+     (if repeat-exit-key
+         (substitute-command-keys
+          (format ", or exit with \\`%s'"
+                  (if (key-valid-p repeat-exit-key)
+                      repeat-exit-key
+                    (key-description repeat-exit-key))))
+       ""))))
 
 (defun repeat-echo-message (keymap)
   "Display in the echo area the repeating keys defined by KEYMAP.