procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve key binding documentation.

Browse source 
* 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'.
This commit is contained in:
Robert Pluim 2024-06-03 14:52:05 +02:00
parent 62d6ba2ede
commit 4dfb0829ed
2 changed files with 41 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

35
doc/emacs/custom.texi
View file

@ -1970,8 +1970,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

8
lisp/keymap.el
View file

@ -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))