Add README for data columns

1 files changed, 74 insertions, 0 deletions

diff --git a/data/README b/data/README
new file mode 100644
index 0000000..43d2961
--- /dev/null
+++ b/data/README
@@ -0,0 +1,74 @@
+This directory contains the raw data for mapping between different
+keyboard codes. Naming if often based on the US keyboard layout, but
+does not indicate the symbol actually generated by the key.
+
+The columns currently in this data set are:
+
+Linux
+-----
+
+Name and value of the hardware independent keycodes used by the linux
+kernel and exposed through the input subsystem.
+
+References: linux/input.h
+
+macOS
+-----
+
+Low level key codes as exposed by Mac OS X/macOS.
+
+References: Carbon/HIToolbox/Events.h
+
+PC scan code sets
+-----------------
+
+Scan codes for the three orignal PC keyboard generations:
+
+ Set 1: XT
+ Set 2: AT
+ Set 3: PS/2
+
+The sets include codes for modern keys as well and not just the keys
+present on those original keyboards.
+
+References: linux/drivers/input/keyboard/atkbd.c
+
+USB HID
+-------
+
+Codes as specified by the HID profile in USB.
+
+References: linux/drivers/hid/usbhid/usbkbd.c
+
+Windows Virtual-key codes
+-------------------------
+
+The low level, hardware independent "VKEYs" exposed by Windows.
+
+References: mingw32/winuser.h
+
+XWin XT
+-------
+
+X11 keycodes generated by the XWin server. Based on the XT scan code
+set.
+
+References: xorg-server/hw/xwin/{winkeybd.c,winkeynames.h}
+
+Xfree86 KBD XT
+--------------
+
+X11 keycodes generated by the Xfree86 keyboard drivers. Based on the XT
+scan code set.
+
+References: xf86-input-keyboard/src/at_scancode.c
+
+X11 keysyms
+-----------
+
+Corresponding X11 keysym value(s) for a US keyboard layout.
+
+WARNING: These columns represent symbols, not physical keys, and should
+         be used with extreme care.
+
+References: http://cgit.freedesktop.org/xorg/proto/x11proto/plain/keysymdef.h