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)

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index 1d6419d78f150cbe4964ceda7a82fcafcb76fe82..0345523d344efbf6ede213b58fc7a8add87ce92c 100644 (file)
--- 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 737c11dbd8301ca6a3602a61f54c940ee3e23657..861d6724c9eefbac5b97d3eb535f5a4f5fe709f6 100644 (file)
--- 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))