bug#59305: 29.0.50; keymap-global-set handling of string bindings different from global-set-key

[Robert Pluim <rpluim@gmail.com>]

>>>>> On Thu, 15 Dec 2022 09:42:46 +0100, Robert Pluim <rpluim@gmail.com> said:


    Robert> Then perhaps we should just change the docstrings and manual to
    Robert> explain that binding a key to a string of characters should use
    Robert> `kmacro' (since `kbd' is not the right thing for ASCII-only entry)

I was going to write 'Stefan why did you overwrite my patch', but itʼs
me who didnʼt follow up :-)

Changing `kbd' to always return a vector, attractive as it is to the
purist in me, falls foul of existing code that expects eg `(kbd
"RET")' to return a string (and thatʼs just in Emacsʼ code). I guess
we could add an 'always produce a vector' argument to `kbd', but
perhaps just recommending `kmacro' is best, since itʼs a fairly niche
usage.

This is against emacs-29

Robert
-- 

diff --git c/doc/emacs/custom.texi i/doc/emacs/custom.texi
index 4bd78f3ce83..d59440e203d 100644
--- c/doc/emacs/custom.texi
+++ i/doc/emacs/custom.texi
@@ -1933,8 +1933,38 @@ Init Rebinding
 (keymap-global-set "<mouse-2>" 'mouse-save-then-kill)
 @end example
 
-  Language and coding systems may cause problems with key bindings for
-non-@acronym{ASCII} characters.  @xref{Init Non-ASCII}.
+@cindex binding key to string
+  Key sequences can also be bound directly to Lisp strings rather than
+commands.  Such strings are written using the same syntax as key
+sequences.  For example, to bind @kbd{C-c h} to the string
+@samp{hello}:
+
+@example
+(keymap-global-set "C-c h" "h e l l o")
+@end example
+
+  Since this is somewhat cumbersome to write, the convenience function
+@code{kmacro} can be used instead:
+
+@example
+(keymap-global-set "C-c h" (kmacro "hello"))
+@end example
+
+  Non-@acronym{ASCII} characters can be specified directly in the
+string. To bind to  e.g. @samp{ol@U{00E1}}, use:
+
+@example
+(keymap-global-set "C-c h" (kmacro "ol@U{00E1}"))
+@end example
+
+  However, be aware that language and coding systems may cause
+problems with key bindings for non-@acronym{ASCII} characters.
+@xref{Init Non-ASCII}.  It may thus be better to use the following
+instead:
+
+@example
+(keymap-global-set "C-c h" (kmacro "ol\u00E1"))
+@end example
 
 @findex global-set-key
 @findex define-key
diff --git c/lisp/keymap.el i/lisp/keymap.el
index 4bdf65d39fa..592a9fd89ab 100644
--- c/lisp/keymap.el
+++ i/lisp/keymap.el
@@ -84,6 +84,9 @@ keymap-global-set
 If COMMAND is a string (which can only happen when this function is
 called from Lisp), it must satisfy `key-valid-p'.
 
+The `kmacro' convenience function converts a simple string of
+characters to an equivalent form that is acceptable for COMMAND.
+
 Note that if KEY has a local binding in the current buffer,
 that local binding will continue to shadow any global binding
 that you make with this function."
@@ -108,6 +111,9 @@ keymap-local-set
 If COMMAND is a string (which can only happen when this function is
 called from Lisp), it must satisfy `key-valid-p'.
 
+The `kmacro' convenience function converts a simple string of
+characters to an equivalent form that is acceptable for COMMAND.
+
 The binding goes in the current buffer's local keymap, which in most
 cases is shared with all other buffers in the same major mode."
   (declare (compiler-macro (lambda (form) (keymap--compile-check key) form))