From 32a4aec4fa8766f0495b1aad0fa03492071b6e01 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Thu, 15 Oct 2020 17:58:43 +0200
Subject: [PATCH] man: describe wildcards and range matches in hwdb syntax

---
 man/hwdb.xml | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/man/hwdb.xml b/man/hwdb.xml
index 5267d212bad..5e906907472 100644
--- a/man/hwdb.xml
+++ b/man/hwdb.xml
@@ -47,6 +47,19 @@
       they are combined by OR. Every match line must start at the first character of the
       line.</para>
 
+      <para>Match patterns consist of literal characters, and shell-style wildcards:</para>
+      <itemizedlist>
+        <listitem><para>Asterisk <literal>*</literal> matches any number of characters
+        </para></listitem>
+        <listitem><para>Question mark <literal>?</literal> matches a single character
+        </para></listitem>
+        <listitem><para>Character list <literal>[<replaceable>chars</replaceable>]</literal> matches one of
+        the characters <replaceable>chars</replaceable> listed between <literal>[</literal> and
+        <literal>]</literal>. A range may be specified as with a dash as
+        <literal>[<replaceable>first</replaceable>-<replaceable>last</replaceable>]</literal>. The match may
+        be inverted with a caret <literal>[^…]</literal>.</para></listitem>
+      </itemizedlist>
+
       <para>The match lines are followed by one or more key-value pair lines, which are
       recognized by a leading space character. The key name and value are separated by
       <literal>=</literal>. An empty line signifies the end of a record. Lines beginning
@@ -84,6 +97,11 @@ mouse:*:name:*trackball*:*
 mouse:*:name:*TrackBall*:*
  ID_INPUT_TRACKBALL=1
 
+# The rule above could be also be written in a form that
+# matches Tb, tb, TB, tB:
+mouse:*:name:*[tT]rack[bB]all*:*
+ ID_INPUT_TRACKBALL=1
+
 # A record with a single match and five properties
 mouse:usb:v046dp4041:name:Logitech MX Master:*
  MOUSE_DPI=1000@166
@@ -103,21 +121,25 @@ evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn*:*
  KEYBOARD_KEY_a2=setup
  KEYBOARD_KEY_a3=battery
 
-evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer*:pn123*:*
+# Match vendor name "Acer" and any product name starting with "X123"
+evdev:atkbd:dmi:bvn*:bvr*:bd*:svnAcer:pnX123*:*
  KEYBOARD_KEY_a2=wlan
 
 # /etc/udev/hwdb.d/70-keyboard.hwdb
 # disable wlan key on all at keyboards
 evdev:atkbd:*
- KEYBOARD_KEY_a2=reserved</programlisting>
+ KEYBOARD_KEY_a2=reserved
+ PROPERTY_WITH_SPACES=some string</programlisting>
 
       <para>If the hwdb consists of those two files, a keyboard with the lookup string
-      <literal>evdev:atkbd:dmi:bvnAcer:bdXXXXX:bd08/05/2010:svnAcer:pn123</literal>
+      <literal>evdev:atkbd:dmi:bvnAcer:bdXXXXX:bd08/05/2010:svnAcer:pnX123</literal>
       will match all three records, and end up with the following properties:</para>
 
       <programlisting>KEYBOARD_KEY_a1=help
 KEYBOARD_KEY_a2=reserved
-KEYBOARD_KEY_a3=battery</programlisting>
+KEYBOARD_KEY_a3=battery
+PROPERTY_WITH_SPACES=some string</programlisting>
+
     </example>
   </refsect1>
 
-- 
2.47.3