From c606c2523e8b6e67b38c905a61db212defeb62a1 Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
Date: Mon, 3 Jun 2024 14:52:05 +0200
Subject: [PATCH] Improve key binding documentation.

* doc/emacs/custom.texi (Init Rebinding): Explain how to bind a key to a
string and how to use non-ASCII characters.
* lisp/keymap.el (keymap-global-set, keymap-local-set): Mention
'key-description'.

(cherry picked from commit 4dfb0829ed3e9c0d26523242e8db9907191dc8db)
---
 doc/emacs/custom.texi | 35 +++++++++++++++++++++++++++++++++--
 lisp/keymap.el        |  8 ++++++++
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 1d6419d78f1..0345523d344 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1961,8 +1961,39 @@ and mouse events:
 (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{key-description} can be used instead:
+
+@example
+(keymap-global-set "C-c h" (key-description "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" (key-description "ol@U{00E1}"))
+@end example
+
+  However, be aware that language and coding systems may cause problems
+with key bindings for non-@acronym{ASCII} characters (@pxref{Init
+Non-ASCII}).  Writing the binding directly with the Unicode codepoint
+avoids these problems (@pxref{International Chars} for how to determine
+the codepoint of a character from within Emacs):
+
+@example
+(keymap-global-set "C-c h" (key-description "ol\u00E1"))
+@end example
 
 @findex global-set-key
 @findex define-key
diff --git a/lisp/keymap.el b/lisp/keymap.el
index 737c11dbd83..861d6724c9e 100644
--- a/lisp/keymap.el
+++ b/lisp/keymap.el
@@ -84,6 +84,10 @@ as its DEFINITION argument.
 If COMMAND is a string (which can only happen when this function is
 called from Lisp), it must satisfy `key-valid-p'.
 
+The `key-description' 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 +112,10 @@ as its DEFINITION argument.
 If COMMAND is a string (which can only happen when this function is
 called from Lisp), it must satisfy `key-valid-p'.
 
+The `key-description' 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))
-- 
2.39.2