quirks: improve the README

Make the headers valid markdown and reword/reformat a few other things
to make it clearer and easier to read.

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>

diff --git a/quirks/README.md b/quirks/README.md
index 55b9056..4ff3e81 100644 (file)
--- a/quirks/README.md
+++ b/quirks/README.md
@@ -1,4 +1,5 @@
-= libinput data file format =
+libinput quirks file format
+===========================
 
 This directory contains hardware quirks used by libinput to work around bugs
 in the hardware, device behavior and to supply information not obtained
@@ -6,28 +7,36 @@ through the kernel device.
 
 **THIS IS NOT STABLE API**
 
-The data format may change at any time. If your data file is not part of the
-libinput git tree, do not expect it to work after an update. Absolutely no
-guarantees are made for backwards-compatibility.
+The data format may change at any time. If your quirks file is not part of
+the libinput git tree, do not expect it to work after an update. Absolutely
+no guarantees are made for backwards-compatibility.
 
 **THIS IS NOT A CONFIGURATION API**
 
 Use the `libinput_device_config_foo()` functions for device configuration.
-The quirks are hardware quirks only.
+Quirks here are hardware quirks only.
 
-== Data file naming ==
+Data file naming
+----------------
 
 Data files are read in versionsort order, read order determines how values
-override each other. A values read later override previously values. The
-current structure is 10-generic-foo.quirks for generic settings,
-30-vendor-foo.quirks for vendor-specific settings and 50-system-foo.quirks
-for system vendors. This is not a fixed naming scheme and may change at any
-time. It's an approximation only because some vendors are also system
-vendors, e.g. Microsoft makes devices and laptops.
+override each other. Values read later override previously read values. The
+current structure is:
+- `10-generic-foo.quirks` for generic settings,
+- `30-vendor-foo.quirks` for vendor-specific settings, and
+- `50-system-foo.quirks` for system vendors.
 
-Laptop-specific quirks should always go into the laptop vendor's file.
+This is not a fixed naming scheme and may change at any time. It's an
+approximation only because some vendors are also system vendors, e.g.
+Microsoft makes devices and laptops.
 
-== Sections, matches and values ==
+Laptop-specific quirks should always go into the laptop vendor's file even
+where they apply to a component of a different vendor. For example, a quirk
+for a Synaptics touchpad specific to a Dell laptop should go into the Dell
+quirks file.
+
+Sections, matches and values
+----------------------------
 
 A data file must contain at least one section, each section must have at
 least one `Match` tag and at least one of either `Attr` or `Model`. Section
@@ -54,24 +63,26 @@ All `Model` tags take a value of either `1` or `0`.
 
 All `Attr` tag values are specific to that attribute.
 
-== Parser errors ==
+Parser errors
+-------------
 
 The following will cause parser errors and are considered invalid data
 files:
 
 * Whitespace at the beginning of the line
-* Sections without at least one `Match*` entry
+* Sections without a `Match*` entry
 * Sections with the same `Match*` entry repeated
 * Sections without at least one of `Model*` or `Attr` entries
 * A `Model` tag with a value other than `1` or `0`
 * A string property with enclosing quotes
 
-== Debugging ==
+Debugging
+---------
 
 When modifying a data file, use the `libinput list-quirks` tool to
 verify the changes. The tool can be pointed at the data directory to
 analyse, use `--verbose` to get more info. For example:
 
 ```
-libinput list-quirks --data-dir /path/to/git/repo/data/ --verbose /dev/input/event0
+libinput list-quirks --data-dir /path/to/git/repo/quirks/ --verbose /dev/input/event0
 ```