This package provides support for the Kitty Keyboard Protocol (KKP).
The protocol defines an alternative way to handle keyboard input for programs running in the terminal. This allows, if the terminal (and intermediaries such as terminal multiplexers) support the protocol as well, the transmission of more detailed information about a key event from the terminal to Emacs, e.g., it transmits “<tab>” and “C-i” differently.
Currently, there exists another solution which solves the same problem, xterm’s “modifyOtherKeys”, which is already supported by Emacs (and activated by default if the terminal supports it). KKP has the advantage of supporting more keys (e.g., “<menu>” or “<Scroll_Lock>”), more key combinations (e.g., “C-M-S-l”) and more modifiers, i.e., the Hyper and Super keys. It can also dynamically detect if a terminal supports the protocol, whereas Emacs has to deduce “modifyOtherKeys” support from the TERM variable.
This package supports the “Disambiguate escape codes” and “Report alternate keys” enhancements. It has not been tested extensively.
Install by using your favorite package manager (e.g., quelpa or straight) or cloning the repository locally and putting it in your load-path:
(use-package kkp
:quelpa (kkp :repo "benjaminor/kkp" :fetcher github)
;; :straight (kkp :type git :repo "benjaminor/kkp" :host github)
;; :load-path "download-path/kkp"
:demand
:config
(kkp-enable))You can control the enabled enhancements by setting kkp-active-enhancements.
By default, it is set to ~’(disambiguate-escape-codes report-alternate-keys)~.
Note that when you activate only disambiguate-escape-codes,
the terminal reports shifted keypresses which involve another modifier by sending the modifiers with the base layout of the key.
This means “M-S-.” (Meta-Shift-.) is not translated to “M-:” (on a German keyboard) and Emacs will probably not find the proper keybinding.
“Report alternate keys” fixes this, but if you do not want to activate it, you can remap keys by using the key-translation-map:
(define-key key-translation-map (kbd "M-S-.") (kbd "M-:"))The standard xterm encoding is quite old and cannot transmit key combinations such as “C-.”.
At the request of an Emacs user, xterm introduced “modifyOtherKeys” in version 216. This feature encodes ‘ordinary (i.e., “other”) keys (such as “2”) when modified by Shift-, Control-, Alt- or Meta-modifiers by an escape sequence’ (source). By default, it uses a “CSI 27 ; modifier ; code ~” encoding. CSI (Control Sequence Introducer) is the bytes sequence “\e[“, i.e., \x1b\x5b.
By request of Paul Leonerd Evans, xterm introduced an alternative encoding for the same keys, using a CSI-u encoding (“CSI modifier ; code u”). This is turned on by an xterm setting, formatOtherKeys. Paul Leonerd Evans documented this approach in his fixterms proposals, but does not mention if it differs from the formatOtherKeys implementation in xterm.
Thomas Dickey documents the “modifyOtherKeys/formatOtherKeys” evolution in more detail here.
On the basis of the fixterms proposal, Kovid Goyal devised the Kitty Keyboard Protocol. This protocol does not deviate a lot from the fixterms proposal:
- It fixes some bugs in fixterms.
- It enables runtime opt-in and opt-out of enhancements (e.g., CSI-u encoding).
- It optionally also supports reporting event types or alternate keys.
For a complete list of enhancements, read https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement. For Emacs, other enhancements than “Disambiguate escape codes” and “Report alternate keys” do not appear to be relevant.