doc: improve the 'tools' page

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

diff --git a/doc/tools.dox b/doc/tools.dox
index b6cbdc589e7600d898ea601183eb6ec09bb38029..c38c2fc7661f58088e7598cfa5ca3a20dac5f525 100644 (file)
--- a/doc/tools.dox
+++ b/doc/tools.dox
@@ -1,16 +1,25 @@
 /**
 @page tools Helper tools
 
-libinput provides a `libinput` tool to query state and events.
-The two most common invocations are
-@ref libinput-list-devices and @ref libinput-debug-events. The @ref
-libinput-record tools are used to analyze and reproduce events sequences on
-developer machines, particularly useful when a user experiences a bug.
-
-A full explanation of the various commands available in the libinput tool is
-available in the libinput(1) man page. Generally, the tool must be run as
-root to have access to the kernel's @c /dev/input/event*
-device files.
+libinput provides a `libinput` tool to query state and events. This tool
+takes a subcommand as argument, similar to the **git** command. A full
+explanation of the various commands available in the libinput tool is
+available in the **libinput(1)** man page. 
+
+The most common tools used are:
+- `libinput list-devices`: to list locally available devices, see @ref
+  libinput-list-devices "here"
+- `libinput debug-events`: to monitor and debug events, see @ref
+  libinput-debug-events "here"
+- `libinput debug-gui`: to visualize events, see @ref libinput-debug-gui
+  "here"
+- `libinput record`: to record an event sequence for replaying, see @ref
+  libinput-record "here"
+- `libinput measure`: measure properties on a kernel device, see @ref
+  libinput-measure "here"
+
+Most the tools must be run as root to have access to the kernel's @c
+/dev/input/event* device files.
 
 @section libinput-list-devices libinput list-devices
 
@@ -19,6 +28,9 @@ recognized by libinput and can help identifying why a device behaves
 different than expected. For example, if a device does not show up in the
 output, it is not a supported input device.
 
+@note This tool does **not** show your desktop's configuration, just the
+libinput built-in defaults.
+
 @verbatim
 $ sudo libinput list-devices
 [...]
@@ -48,9 +60,6 @@ binary state all available options are listed, with the default one prefixed
 with an asterisk (*). In the example above, the default click method is
 button-areas but clickinger is available.
 
-Note that the default configuration may differ from the configuration
-applied by the desktop environment.
-
 @note This tool is intended to be human-readable and may change its output
 at any time.
 
@@ -62,8 +71,46 @@ to identify why a device behaves different than expected.
 $ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
 @endverbatim
 
-See the libinput(1) man page or the @c --help output for information about
-the available options.
+All configuration options (enable/disable tapping,
+etc.) are available as commandline arguments. To reproduce the event
+sequence as your desktop session sees it, ensure that all options are turned
+on or off as required. See the **libinput-debug-events(1)** man page or the 
+`--help` output for information about the available options. 
+
+@note When submitting a bug report, always use the `--verbose` flag to get
+additional information: `libinput debug-events --verbose <other options>`
+
+An example output from this tool may look like the snippet below. 
+
+@verbatim
+$ sudo libinput debug-events --enable-tapping --set-click-method=clickfinger
+-event2   DEVICE_ADDED     Power Button                      seat0 default group1  cap:k
+-event5   DEVICE_ADDED     Video Bus                         seat0 default group2  cap:k
+-event0   DEVICE_ADDED     Lid Switch                        seat0 default group3  cap:S
+-event1   DEVICE_ADDED     Sleep Button                      seat0 default group4  cap:k
+-event4   DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=3      seat0 default group5  cap:
+-event11  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=7      seat0 default group6  cap:
+-event12  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=8      seat0 default group7  cap:
+-event13  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=9      seat0 default group8  cap:
+-event14  DEVICE_ADDED     HDA Intel HDMI HDMI/DP,pcm=10     seat0 default group9  cap:
+-event19  DEVICE_ADDED     Integrated Camera: Integrated C   seat0 default group10 cap:k
+-event15  DEVICE_ADDED     HDA Intel PCH Dock Mic            seat0 default group11 cap:
+-event16  DEVICE_ADDED     HDA Intel PCH Mic                 seat0 default group12 cap:
+-event17  DEVICE_ADDED     HDA Intel PCH Dock Headphone      seat0 default group13 cap:
+-event18  DEVICE_ADDED     HDA Intel PCH Headphone           seat0 default group14 cap:
+-event6   DEVICE_ADDED     ELAN Touchscreen                  seat0 default group15 cap:t  size 305x172mm ntouches 10 calib
+-event3   DEVICE_ADDED     AT Translated Set 2 keyboard      seat0 default group16 cap:k
+-event20  DEVICE_ADDED     SynPS/2 Synaptics TouchPad        seat0 default group17 cap:pg  size 100x76mm tap(dl off) left scroll-nat scroll-2fg-edge click-buttonareas-clickfinger dwt-on
+-event21  DEVICE_ADDED     TPPS/2 IBM TrackPoint             seat0 default group18 cap:p left scroll-nat scroll-button
+-event7   DEVICE_ADDED     ThinkPad Extra Buttons            seat0 default group19 cap:k
+-event20  POINTER_MOTION    +3.62s       2.72/ -0.93
+ event20  POINTER_MOTION    +3.63s       1.80/ -1.42
+ event20  POINTER_MOTION    +3.65s       6.16/ -2.28
+ event20  POINTER_MOTION    +3.66s       6.42/ -1.99
+ event20  POINTER_MOTION    +3.67s       8.99/ -1.42
+ event20  POINTER_MOTION    +3.68s      11.30/  0.00
+ event20  POINTER_MOTION    +3.69s      21.32/  1.42
+@endverbatim
 
 @section libinput-debug-gui libinput debug-gui
 
@@ -72,11 +119,16 @@ touch events, pointer motion, scroll axes and gestures. Since this tool
 gathers data directly from libinput, it is thus suitable for
 pointer-acceleration testing.
 
+@note This tool does **not** use your desktop's configuration, just the
+libinput built-in defaults.
+
 @verbatim
-$ sudo libinput debug-gui
+$ sudo libinput debug-gui --enable-tapping
 @endverbatim
 
-See the libinput(1) man page or the @c --help output for information about
+As with @ref libinput-debug-events, all options must be specified on the
+commandline to emulate the correct behavior.
+See the **libinput-debug-gui(1)** man page or the `--help` output for information about
 the available options.
 
 @section libinput-record libinput record and libinput replay
@@ -123,7 +175,7 @@ Without arguments, `libinput record` displays the available devices and lets
 the user select one. Supply the number (17 in this case for
 `/dev/input/event17`) and the tool will print the device information and
 events to the file it is redirected to. More arguments are available, see
-the `libinput-record` man page.
+the **libinput-record(1)** man page.
 
 Reproduce the bug, ctrl+c and attach the output file to a bug report.
 For data protection, `libinput record` obscures key codes by default, any
@@ -147,8 +199,8 @@ sequence again, Ctrl+C stops it and removes the virtual device.
 Users are advised to always replay a recorded event sequence to ensure they
 have captured the bug.
 
-More arguments are available, see the `libinput-record` and
-`libinput-replay` man pages.
+More arguments are available, see the **libinput-record(1)** and
+**libinput-replay(1)** man pages.
 
 @subsection libinput-record-multiple Recording multiple devices at once
 
@@ -174,4 +226,12 @@ Replaying events is the same as for a single recording:
 $ sudo libinput replay touchpad-bug.log
 @endverbatim
 
+@subsection libinput-measure Measuring device properties with libinput measure
+
+The `libinput measure` tool is a multiplexer for various sub-tools that can
+measure specific properties on the device. These tools generally measure one
+thing and one thing only and their usage is highly specific to the tool.
+Please see the **libinput-measure(1)** man page for information about what
+tools are available and the man page for each respective tool.
+
 */