feat(tui): query terminal for CSI u support (#18181)

On startup query the terminal for CSI u support and enable it using
the escape sequence from kitty's progressive enhancement protocol [1].

[1]: https://sw.kovidgoyal.net/kitty/keyboard-protocol/

1 files changed, 37 insertions, 0 deletions

diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index bdf0094721..9969fc0a79 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -117,6 +117,43 @@ go to the window below: >
   tmux send-keys 'Escape' [ 2 7 u 'C-W' j
 Where `'Escape' [ 2 7 u` is an unambiguous `CSI u` sequence for the <Esc> key.
 
+						*tui-modifyOtherKeys* *tui-csiu*
+Historically, terminal emulators could not distinguish between certain control
+key modifiers and other keys. For example, <C-I> and <Tab> are represented the
+same way, as are <Esc> and <C-[>, <CR> and <C-M>, and <NL> and <C-J>. This
+meant that Nvim also could not map these keys separately.
+
+Modern terminal emulators are able to distinguish between these pairs of keys
+by encoding control modifiers differently. There are two common but distinct
+ways of doing this, known as "modifyOtherKeys" and "CSI u". Nvim supports both
+encoding methods and at startup will tell the terminal emulator that it
+understands these key encodings. If your terminal emulator supports it then
+this will allow you to map the key pairs listed above separately.
+
+At startup Nvim will query your terminal to see if it supports the CSI u
+encoding by writing the sequence >
+
+	CSI ? u CSI c
+
+If your terminal emulator responds with >
+
+	CSI ? <flags> u
+
+this means your terminal supports the CSI u encoding and Nvim will tell your
+terminal to enable it by writing the sequence >
+
+	CSI > 1 u
+
+If your terminal does not support CSI u then Nvim will instead enable the
+"modifyOtherKeys" encoding by writing the sequence >
+
+	CSI > 4 ; 2 m
+
+When Nvim exits cleanly it will send the corresponding sequence to disable the
+special key encoding. If Nvim does not exit cleanly then your terminal
+emulator could be in a bad state. If this happens, simply run "reset".
+
+
 							*tui-colors*
 Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types,
 including "linux" (whose virtual terminals have had 256-colour support since