From 463489624170201fc82ebb9e74f892400684ab35 Mon Sep 17 00:00:00 2001
From: Juri Linkov <juri@linkov.net>
Date: Thu, 2 May 2024 09:46:48 +0300
Subject: [PATCH] Support hints in the :repeat keyword of defvar-keymap for
 repeat-mode

* lisp/keymap.el (defvar-keymap): Add :hints to the :repeat keyword.
Put the property 'repeat-hint' on the command symbol.

* lisp/repeat.el (repeat-echo-message-string): Show hint strings
defined with the property 'repeat-hint' on the command symbol (bug#70576).

(cherry picked from commit 0023891e84285c2ea2a8029f479135f792c9d1e9)
---
 etc/NEWS       |  4 ++++
 lisp/keymap.el | 15 +++++++++++----
 lisp/repeat.el | 35 +++++++++++++++++++++--------------
 3 files changed, 36 insertions(+), 18 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index 53e79dfd0d9..de5a35975f4 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2779,6 +2779,10 @@ major mode.
 ** The variable 'rx-constituents' is now obsolete.
 Use 'rx-define', 'rx-let' and 'rx-let-eval' instead.
 
+---
+** 'defvar-keymap' can specify hints for 'repeat-mode'.
+Using ':repeat (:hints ((command . "hint") ...))' will show
+the hint string in the echo area together with repeatable keys.
 
 
 * Changes in Emacs 30.1 on Non-Free Operating Systems
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 @@ non-nil, all commands in the map will have the `repeat-map'
 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 @@ Specifying a list of commands is useful when those commands exist
 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 @@ property.
           (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..412afc35ba7 100644
--- a/lisp/repeat.el
+++ b/lisp/repeat.el
@@ -553,20 +553,27 @@ This function can be used to force exit of repetition while it's active."
 (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.
-- 
2.39.5