From 7185b023c53b59735845b61bc2a1b225195e9dc3 Mon Sep 17 00:00:00 2001
From: Pierre Le Marre <dev@wismill.eu>
Date: Sun, 24 Sep 2023 09:40:08 +0200
Subject: [PATCH] Add documentation to XkbToControl
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

While some transformations are defined in the section “Interpreting the
Control Modifier” of the XKB protocol, a lot are not. Documentation is
scarce about the topic, so write down some context using the following
sources:

- https://en.wikipedia.org/wiki/Caret_notation#Use_in_software
- https://www.vt100.net/shuford/terminal/dec_keyboards_news.txt
- https://misc.openbsd.narkive.com/NvSWf6ax/which-key-shortcuts-are-safe-to-bind-and-some-q-s-about-history-and-os-diffs-re-ctrl-4-means
- https://vt100.net/docs/vt220-rm/chapter3.html#T3-5
---
 src/state.c | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/state.c b/src/state.c
index d449697..543658b 100644
--- a/src/state.c
+++ b/src/state.c
@@ -894,7 +894,33 @@ should_do_ctrl_transformation(struct xkb_state *state, xkb_keycode_t kc)
         xkb_state_mod_index_is_consumed(state, kc, ctrl) == 0;
 }
 
-/* Verbatim from libX11:src/xkb/XKBBind.c */
+/*
+ * Verbatim from `libX11:src/xkb/XKBBind.c`.
+ *
+ * The basic transformations are defined in “[Interpreting the Control Modifier]”.
+ * They correspond to the [caret notation], which maps the characters
+ * `@ABC...XYZ[\]^_` by masking them with `0x1f`. Note that there is no
+ * transformation for `?`, although `^?` is defined in the [caret notation].
+ *
+ * For convenience, the range ```abc...xyz{|}~`` and the space character ` `
+ * are processed the same way. This allow to produce control characters without
+ * requiring the use of the `Shift` modifier for letters.
+ *
+ * The transformation of the digits seems to originate from the [VT220 terminal],
+ * as a compatibility for non-US keyboards. Indeed, these keyboards may not have
+ * the punctuation characters available or in a convenient position. Some mnemonics:
+ *
+ * - ^2 maps to ^@ because @ is on the key 2 in the US layout.
+ * - ^6 maps to ^^ because ^ is on the key 6 in the US layout.
+ * - characters 3, 4, 5, 6, and 7 seems to align with the sequence `[\]^_`.
+ * - 8 closes the sequence and so maps to the last control character.
+ *
+ * The `/` transformation seems to be defined for compatibility or convenience.
+ *
+ * [Interpreting the Control Modifier]: https://www.x.org/releases/current/doc/kbproto/xkbproto.html#Interpreting_the_Control_Modifier
+ * [caret notation]: https://en.wikipedia.org/wiki/Caret_notation
+ * [VT220 terminal]: https://vt100.net/docs/vt220-rm/chapter3.html#T3-5
+ */
 static char
 XkbToControl(char ch)
 {