Fix handling of ctrl key in legacy mode

Also change the glfw constants used for the modifiers to match those
used in the terminal encoding. Less likely to make mistakes translating
that way.

docs/keyboard-protocol.rst

@@ -26,6 +26,12 @@ advanced usages. The protocol is based on initial work in `fixterms
 issues in that proposal, listed at the :ref:`bottom of this document
 <fixterms_bugs>`.
 
+You can see this protocol with all enhancements in action by running::
+
+    kitty +kitten key_demo
+
+inside the kitty terminal to report key events.
+
 .. versionadded:: 0.20.0
 
 Quickstart
@@ -46,7 +52,7 @@ text, or using these escape codes, for keys that do not produce text (``CSI``
 is the bytes ``0x1b 0x5b``::
 
     CSI number ; modifiers [u~]
-    CSI 1; modifiers [ABCDFHPQRSZ]
+    CSI 1; modifiers [ABCDFHPQRS]
     0x0d - for the Enter key
     0x7f or 0x08 - for Backspace
     0x09 - for Tab
@@ -58,9 +64,9 @@ modifiers pressed for the key event. The encoding is described in the
 :ref:`modifiers` section.
 
 The second form is used for a few functional keys, such as the :kbd:`Home, End,
-Tab, Arrow keys and F1-F4`, they are enumerated in the :ref:`functional` table below.
+Arrow keys and F1-F4`, they are enumerated in the :ref:`functional` table below.
 Note that if no modifiers are present the parameters are omitted entirely
-giving an escape code of the form ``CSI [ABCDFHPQRSZ]``.
+giving an escape code of the form ``CSI [ABCDFHPQRS]``.
 
 If you want support for more advanced features such as repeat and release
 events, alternate keys for shortcut matching et cetera, these can be turned on
@@ -274,7 +280,7 @@ With this flag turned on, all key events that do not generate text are
 represented in one of the following two forms::
 
     CSI number; modifier u
-    CSI 1; modifier [~ABCDFHPQRSZ]
+    CSI 1; modifier [~ABCDFHPQRS]
 
 This makes it very easy to parse key events in an application. In particular,
 :kbd:`ctrl+c` will no longer generate the ``SIGINT`` signal, but instead be
@@ -420,8 +426,8 @@ For legacy compatibility, the keys
 following algorithm:
 
 #. If the :kbd:`alt` key is pressed output the byte for ``ESC (0x1b)``
-#. If the :kbd:`ctrl` modifier is pressed mask the seventh bit ``(0b1000000)``
-   in the key's ASCII code number and output that
+#. If the :kbd:`ctrl` modifier is pressed map the key using the table
+   in :ref:`ctrl_mapping`.
 #. Otherwise, if the :kbd:`shift` modifier is pressed, output the shifted key,
    for example, ``A`` for ``a`` and ``$`` for ``4``.
 #. Otherwise, output the key unmodified
@@ -572,6 +578,45 @@ compatibility reasons.
 Note that the escape codes above of the form ``CSI 1 letter`` will omit the
 ``1`` if there are no modifiers, since ``1`` is the default value.
 
+.. _ctrl_mapping:
+
+Legacy :kbd:`ctrl` mapping of ASCII keys
+------------------------------------------
+
+When the :kbd:`ctrl` key and another key are pressed on the keyboard, terminals
+map the result *for some keys* to a *C0 control code* i.e. an value from ``0 -
+31``. This mapping was historically dependent on the layout of hardware
+terminal keyboards and is not specified anywhere, completely. The best known
+reference is `Tabe 3-5 here <https://vt100.net/docs/vt100-ug/chapter3.html>`_.
+
+The table below provides a mapping that is a commonly used superset of the table above.
+Any ASCII keys not in the table must be left untouched by :kbd:`ctrl`.
+
+.. {{{
+.. start ctrl mapping (auto generated by gen-key-constants.py do not edit)
+.. csv-table:: Emitted bytes when :kbd:`ctrl` is held down and a key is pressed
+   :header: "Key", "Byte", "Key", "Byte", "Key", "Byte"
+
+   " ", "0", "/", "31", "0", "48"
+   "1", "49", "2", "0", "3", "27"
+   "4", "28", "5", "29", "6", "30"
+   "7", "31", "8", "127", "9", "57"
+   "?", "127", "@", "0", "[", "27"
+   "\", "28", "]", "29", "^", "30"
+   "_", "31", "a", "1", "b", "2"
+   "c", "3", "d", "4", "e", "5"
+   "f", "6", "g", "7", "h", "8"
+   "i", "9", "j", "10", "k", "11"
+   "l", "12", "m", "13", "n", "14"
+   "o", "15", "p", "16", "q", "17"
+   "r", "18", "s", "19", "t", "20"
+   "u", "21", "v", "22", "w", "23"
+   "x", "24", "y", "25", "z", "26"
+   "~", "30"
+
+.. end ctrl mapping
+.. }}}
+
 .. _fixterms_bugs:
 
 Bugs in fixterms
@@ -590,7 +635,7 @@ specification.
   * No support for the :kbd:`super` modifier.
   * Makes no mention of cursor key mode and how it changes encodings
   * Incorrectly encoding shifted keys when shift modifier is used, for
-    instance, for :kbd:`ctrl+shift+I`.
+    instance, for :kbd:`ctrl+shift+i` is encoded as :kbd:`ctrl+I`.
   * No way to have non-conflicting escape codes for :kbd:`alt+letter,
     ctrl+letter, ctrl+alt+letter` key presses
   * No way to specify both shifted and unshifted keys for robust shortcut
@@ -602,3 +647,12 @@ specification.
   * No way to report key events for presses that generate text, useful for
     gaming. Think of using the :kbd:`WASD` keys to control movement.
   * Only a small subset of all possible functional keys are assigned numbers.
+  * Claims the ``CSI u`` escape code has no fixed meaning, but has been used
+    for decades as ``SCORC`` for instance by xterm and ansi.sys and
+    `DECSMBV <https://vt100.net/docs/vt510-rm/DECSMBV.html`_
+    by the VT-510 hardware terminal. This doesn't really matter since these uses
+    are for communication to the terminal not from the terminal.
+  * Handwaves that :kbd:`ctrl` *tends to* mask with ``0x1f``. In actual fact it
+    does this only for some keys. The action of :kbd:`ctrl` is not specified
+    and varies between terminals, historically because of different keyboard
+    layouts.