mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-30 08:09:04 +00:00
Code Issues Releases Activity

; Reword user documentation on binding keys in Lisp

Browse Source 
* doc/emacs/custom.texi (Init Rebinding): Move the description of
'kbd' farther down.  (Bug#60859)
This commit is contained in:
Panagiotis Koutsourakis 2023-01-17 20:57:41 +02:00 committed by Eli Zaretskii
parent b3de81a6ee
commit a91b435d0d
1 changed files with 36 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
doc/emacs/custom.texi
View File

@ -1887,22 +1887,29 @@ command is less work to invoke when you really want to.
you can specify them in your initialization file by writing Lisp code.
@xref{Init File}, for a description of the initialization file.
@findex kbd
There are several ways to write a key binding using Lisp. The
simplest is to use the @code{kbd} function, which converts a textual
representation of a key sequence---similar to how we have written key
sequences in this manual---into a form that can be passed as an
argument to @code{keymap-global-set}. For example, here's how to bind
@kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}):
@findex keymap-global-set
The recommended way to write a key binding using Lisp is to use one
of the @code{keymap-global-set}, or @code{keymap-set} functions. For
example, here's how to bind @kbd{C-z} to the @code{shell} command in
the global keymap (@pxref{Interactive Shell}):
@example
(keymap-global-set "C-z" 'shell)
@end example
@cindex key sequence syntax
@noindent
The single-quote before the command name, @code{shell}, marks it as a
constant symbol rather than a variable. If you omit the quote, Emacs
would try to evaluate @code{shell} as a variable. This probably
The second argument that describes the key sequence, is a string
containing a series of characters separated by spaces with each
character corresponding to a key. Keys with modifiers can be
specified by prepending the modifier, such as @samp{C-} for Control,
or @samp{M-} for Meta. Special keys, such as @kbd{TAB} and @kbd{RET},
can be specified within angle brackets as in @kbd{@key{TAB}} and
@kbd{@key{RET}}.
The single-quote before the command name, @code{shell}, marks it as
a constant symbol rather than a variable. If you omit the quote,
Emacs would try to evaluate @code{shell} as a variable. This probably
causes an error; it certainly isn't what you want.
Here are some additional examples, including binding function keys
@ -1920,6 +1927,25 @@ and mouse events:
Language and coding systems may cause problems with key bindings for
non-@acronym{ASCII} characters. @xref{Init Non-ASCII}.
@findex global-set-key
@findex define-key
Alternatively you can use the low level functions @code{define-key}
and @code{global-set-key}. For example to bind @kbd{C-z} to the
@code{shell} command as in the above example, use:
@example
(global-set-key (kbd "C-z") 'shell)
@end example
@findex kbd
@noindent
There are various ways to specify the key sequence but the simplest is
to use the function @code{kbd} as shown in the example above.
@code{kbd} takes a single string argument specifying a key sequence in
the syntax described earlier for @code{keymap-global-set}. For more
details about binding keys using Lisp @ref{Keymaps,,, elisp, The Emacs
Lisp Reference Manual}.
@findex keymap-set
@findex keymap-unset
As described in @ref{Local Keymaps}, major modes and minor modes can