hwdb: Better documentation for keyboard quirks

Split up the device matching explanation, and add documentation for
the fixed layout quirk.

diff --git a/hwdb/60-keyboard.hwdb b/hwdb/60-keyboard.hwdb
index 1aa729f04797379f6c74367dff94af5a6d59f1b0..1dccbec3cc67a5acd708f07dfccb35a8d50d2473 100644 (file)
--- a/hwdb/60-keyboard.hwdb
+++ b/hwdb/60-keyboard.hwdb
@@ -1,7 +1,13 @@
 # This file is part of systemd.
 #
-# Keyboard mapping of scan codes to key codes, and
-# scan codes to add to the AT keyboard's 'force-release' list.
+# This file contains 2 types of metadata to apply to keyboards and
+# keyboard-like input devices:
+# - Key mapping
+# - Hard-coded layouts
+#
+# The matching process is the same for the different types of metadata.
+#
+# ########################### MATCHING #######################################
 #
 # The lookup keys are composed in:
 #   60-evdev.rules
@@ -40,6 +46,12 @@
 #    /sys/class/input/input?/capabilities/ev" and <vendor> is the
 #    firmware-provided string exported by the kernel DMI modalias,
 #    see /sys/class/dmi/id/modalias
+
+
+# ######################### KEY MAPPING ######################################
+#
+# Keyboard mapping of scan codes to key codes, and
+# scan codes to add to the AT keyboard's 'force-release' list.
 #
 # Scan codes are specified as:
 #   KEYBOARD_KEY_<hex scan code>=<key code identifier>
@@ -1274,9 +1286,13 @@ evdev:atkbd:dmi:bvn*:bvr*:bd*:svnDIXONSP:pnDIXON*:pvr*
  KEYBOARD_KEY_ae=!                                      # volume down
  KEYBOARD_KEY_b0=!                                      # volume up
 
-###########################################################
-# Fixed layout devices
-###########################################################
+######################### FIXED LAYOUT DEVICES #############################
+# This section lists devices for which only one keyboard layout is possible
+# or useful such as devices which "type" expecting the user's keymap to match
+# a particular one. For example, barcode readers and OTP keys.
+#
+# The layout must be an xkb compatible layout (defined with XKB_FIXED_LAYOUT),
+# with an accompanying variant (defined with XKB_FIXED_VARIANT) if necessary.
 
 # Yubico Yubico Yubikey II"
 evdev:input:b0003v1050p0010*