** Status This package supports the "Disambiguate escape codes" and "Report alternate keys" enhancements. I use it on a regular basis and it has seen some testing from other users.

** Installation *** Melpa You can install this package from [[https://melpa.org/#/kkp][Melpa]], by first ensuring that you have the melpa source in your package-archives.

+begin_src emacs-lisp

(require 'package) (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/") t) (package-initialize) (package-refresh-contents)

+end_src

Once that is done, this package can be installed.

+begin_src shell

package-install kkp

+end_src

*** use-package

+begin_src emacs-lisp

(use-package kkp
  :ensure t
  :config
  ;; (setq kkp-alt-modifier 'alt) ;; use this if you want to map the Alt keyboard modifier to Alt in Emacs (and not to Meta)
  (global-kkp-mode +1))

+end_src

** Usage

kkp.el works out of the box by enabling =global-kkp-mode= and is customizable via the =kkp-*= customization variables.

If you want to know if your terminal supports kkp, if its activated, and if yes, which enhancements are active, use =kkp-status=.

You can control the enabled [[https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement][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=:

+begin_src emacs-lisp

(define-key key-translation-map (kbd "M-S-.") (kbd "M-:"))

+end_src

** Background

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' ([[https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:modifyOtherKeys][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, [[https://invisible-island.net/xterm/manpage/xterm.html#VT100-Widget-Resources:formatOtherKeys][formatOtherKeys]]. Paul Leonerd Evans documented this approach in his [[https://www.leonerd.org.uk/hacks/fixterms/][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 [[https://invisible-island.net/xterm/modified-keys.html][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 [[https://sw.kovidgoyal.net/kitty/keyboard-protocol/#bugs-in-fixterms][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.