From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 18 Nov 2023 09:52:48 +0000 (+0200)
Subject: Document changes in 'edmacro-parse-keys'
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=d9e43f2197f;p=emacs.git

Document changes in 'edmacro-parse-keys'

* lisp/edmacro.el (edmacro-parse-keys): Add a comment for forcing
output to be a vector.
(read-kbd-macro): Adjust the doc string to changes in
'edmacro-parse-keys'.  (Bug#67182)
---

diff --git a/lisp/edmacro.el b/lisp/edmacro.el
index 0b62bf262bc..535c50cee84 100644
--- a/lisp/edmacro.el
+++ b/lisp/edmacro.el
@@ -228,14 +228,14 @@ With a prefix argument, format the macro in a more concise way."
 ;;;###autoload
 (defun read-kbd-macro (start &optional end)
   "Read the region as a keyboard macro definition.
-The region is interpreted as spelled-out keystrokes, e.g., \"M-x abc RET\".
-See documentation for `edmacro-mode' for details.
+The region between START and END is interpreted as spelled-out keystrokes,
+e.g., \"M-x abc RET\".  See documentation for `edmacro-mode' for details.
 Leading/trailing \"C-x (\" and \"C-x )\" in the text are allowed and ignored.
 The resulting macro is installed as the \"current\" keyboard macro.
 
 In Lisp, may also be called with a single STRING argument in which case
 the result is returned rather than being installed as the current macro.
-The result will be a string if possible, otherwise an event vector.
+The result is a vector of input events.
 Second argument NEED-VECTOR means to return an event vector always."
   (interactive "r")
   (if (stringp start)
@@ -672,6 +672,13 @@ This function assumes that the events can be stored in a string."
 
 (defun edmacro-parse-keys (string &optional _need-vector)
   (let ((result (kbd string)))
+    ;; Always return a vector.  Stefan Monnier <monnier@iro.umontreal.ca>
+    ;; writes: "I want to eliminate the use of strings that stand for a
+    ;; sequence of events because it does nothing more than leave latent
+    ;; bugs and create confusion (between the strings used as input to
+    ;; `read-kbd-macro' and the strings that used to be output by
+    ;; `read-kbd-macro'), while increasing the complexity of the rest of
+    ;; the code which has to handle both vectors and strings."
     (if (stringp result)
         (seq-into result 'vector)
       result)))