doc: add a subsection on how to use libinput record --autorestart

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

diff --git a/doc/tools.dox b/doc/tools.dox
index 110cf1d5ecd3a86074a5bcf7cfd6b7c1810bfd22..bd0cfe8dc1a617951eddac75ab83429030796c6a 100644 (file)
--- a/doc/tools.dox
+++ b/doc/tools.dox
@@ -202,6 +202,35 @@ have captured the bug.
 More arguments are available, see the **libinput-record(1)** and
 **libinput-replay(1)** man pages.
 
+@subsection libinput-record-autorestart libinput record's autorestart feature
+
+`libinput record` often collects thousands of events per minute. However,
+the output of `libinput record` usually needs to be visually inspected
+or replayed in realtime on a developer machine. It is thus imperative that
+the event log is kept as short as possible.
+
+For bugs that are difficult to reproduce use
+`libinput record --autorestart=2 --output-file=recording.yml`.
+All events will be recorded to a file named
+`recording.yml.<current-date-and-time>` and whenever the device does not
+send events for 2 seconds, a new file is created. This helps to keep
+individual recordings short.
+
+To use the `--autorestart` option correctly:
+- run `libinput record --autorestart=2 --output-file=<somefilename>.yml`.
+  You may provide a timeout other than 2 if needed.
+- use the device to reproduce the bug, pausing frequently for 2s and longer
+  to rotate the logs
+- when the bug triggers, **immediately stop using the device** and wait
+  several seconds for the log to rotate
+- Ctrl+C the `libinput record` process without using the device
+  again. Attach the **last recording** to the bug report.
+
+If you have to use the recorded device to stop `libinput record` (e.g. to
+switch windows), remember that this will cause a new recording to be
+created. Thus, attach the **second-to-last recording** to the bug report
+because this one contains the bug trigger.
+
 @subsection libinput-record-multiple Recording multiple devices at once
 
 In some cases, an interaction between multiple devices is the cause for a