From f955b2b73a14798de3deabe2f52dbfa7769981ed Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 31 Jul 2018 16:03:49 +1000 Subject: [PATCH] doc/user: some rewording and improvements Signed-off-by: Peter Hutterer --- doc/user/dot/libinput-record.gv | 20 +++++++++++++++ doc/user/meson.build | 1 + doc/user/reporting-bugs.rst | 45 ++++++++++++++++----------------- doc/user/tools.rst | 22 +++++++++++----- doc/user/what-is-libinput.rst | 38 +++++++++++++--------------- 5 files changed, 75 insertions(+), 51 deletions(-) create mode 100644 doc/user/dot/libinput-record.gv diff --git a/doc/user/dot/libinput-record.gv b/doc/user/dot/libinput-record.gv new file mode 100644 index 00000000..a6ece212 --- /dev/null +++ b/doc/user/dot/libinput-record.gv @@ -0,0 +1,20 @@ +digraph stack +{ + compound=true; + rankdir="LR"; + node [ + shape="box"; + ] + + kernel [label="Kernel"]; + + libinput; + xserver [label="X Server"]; + record [label="libinput record"]; + + kernel -> libinput + libinput -> xserver + + kernel -> record; + record -> stdout +} diff --git a/doc/user/meson.build b/doc/user/meson.build index 24057657..c3403213 100644 --- a/doc/user/meson.build +++ b/doc/user/meson.build @@ -21,6 +21,7 @@ src_extra = [ 'dot/libinput-stack-xorg.gv', 'dot/libinput-stack-gnome.gv', 'dot/evemu.gv', + 'dot/libinput-record.gv', # svgs 'svg/button-debouncing-wave-diagram.svg', 'svg/button-scrolling.svg', diff --git a/doc/user/reporting-bugs.rst b/doc/user/reporting-bugs.rst index 6f35cace..50addd5f 100644 --- a/doc/user/reporting-bugs.rst +++ b/doc/user/reporting-bugs.rst @@ -8,11 +8,10 @@ A new bug can be filed here: https://gitlab.freedesktop.org/libinput/libinput/issues/new .. note:: libinput has lots of users but very few developers. It is in your own - interested to follow these steps precisely to ensure your bug can be + interested to follow the steps here precisely to ensure your bug can be dealt with efficiently. -When reporting bugs against libinput, please follow the instructions below -and provide the required data. You will need: +When reporting bugs against libinput, you will need: - a reliable :ref:`reproducer ` for the bug - an :ref:`evemu recording ` of the device while the bug is reproduced @@ -36,8 +35,8 @@ Stay technical, on-topic, and keep the description concise. Obtaining the libinput version ------------------------------------------------------------------------------ -If your libinput version is older than the current stable branch, you will -get asked to try the latest version. If you run a distribution-provided +If your libinput version is older than the current stable branch, please try +the latest version. If you run a distribution-provided libinput, use the package manager to get the **full** package name and version of libinput, e.g. @@ -69,8 +68,8 @@ Once you can reproduce it, use the :ref:`libinput-debug-events` helper tool. The output is textual and can help identify whether the bug is in libinput at all. Note that any configuration options you have set must be specified on the commandline, see the :ref:`libinput-debug-events` -"libinput-debug-events" man page. Use the ``--verbose`` flag to get more -information about how libinput processes events. +man page. Use the ``--verbose`` flag to get more information about how +libinput processes events. If the bug cannot be reproduced with the :ref:`libinput-debug-events` helper, even with the correct configuration options set, it is likely not a bug in @@ -105,8 +104,8 @@ Reporting touchpad bugs When you file a bug, please attach the following information: -- a virtual description of your input device, see :ref:`evemu`. This is the - most important piece of information, do not forget it! +- a virtual description of your input device, see :ref:`libinput-record`. + This is the most important piece of information, do not forget it! - the output from udevadm info, see :ref:`udev_info`. - the vendor model number of your laptop (e.g. "Lenovo Thinkpad T440s") - and the content of ``/sys/class/dmi/id/modalias``. @@ -129,8 +128,8 @@ Reporting mouse bugs When you file a bug, please attach the following information: -- a virtual description of your input device, see :ref:`evemu`. This is the - most important piece of information, do not forget it! +- a virtual description of your input device, see :ref:`libinput-record`. + This is the most important piece of information, do not forget it! - the vendor model number of the device (e.g. "Logitech M325") - the output from udevadm info, see :ref:`udev_info`. @@ -152,8 +151,8 @@ the issue is. When you file a bug, please attach the following information: -- a virtual description of your input device, see :ref:`evemu`. This is the - most important piece of information, do not forget it! +- a virtual description of your input device, see :ref:`libinput-record`. + This is the most important piece of information, do not forget it! .. _reporting_bugs_trackpoint: @@ -163,8 +162,8 @@ Reporting trackpoint bugs When you file a bug, please attach the following information: -- a virtual description of your input device, see :ref:`evemu`. This is the - most important piece of information, do not forget it! +- a virtual description of your input device, see :ref:`libinput-record`. + This is the most important piece of information, do not forget it! - the vendor model number of the device (e.g. "Logitech M325") - the output from udevadm info, see :ref:`udev_info`. - the output of ``libinput measure trackpoint-range`` @@ -181,8 +180,8 @@ All other devices When you file a bug, please attach the following information: -- a virtual description of your input device, see :ref:`evemu`. This is the - most important piece of information, do not forget it! +- a virtual description of your input device, see :ref:`libinput-record`. + This is the most important piece of information, do not forget it! - the vendor model number of the device (e.g. "Sony Plastation3 controller") .. _udev_info: @@ -221,8 +220,8 @@ node for your device. An example output is below: :: Recording devices with evemu ------------------------------------------------------------------------------ -.. note:: Where available, the :ref:`libinput-record` tools should be used instead - of evemu +.. warning:: Where available, the :ref:`libinput-record` tools should be used instead + of evemu `evemu-record `_ records the device capabilities together with the event stream from the kernel. On our @@ -275,10 +274,10 @@ device. For example, to replay the sequence recorded in the example above: :: If the bug is triggered by replaying on your device, attach the recording to the bug report. -.. note:: libinput does not affect the evemu recording. libinput and evemu talk - directly to the kernel's device nodes. An evemu recording is not - influenced by the libinput version or whether a libinput context is - currently active. +libinput does not affect the evemu recording. libinput and evemu talk +directly to the kernel's device nodes. An evemu recording is not +influenced by the libinput version or whether a libinput context is +currently active. .. graphviz:: evemu.gv diff --git a/doc/user/tools.rst b/doc/user/tools.rst index d28f7a9d..fa6917de 100644 --- a/doc/user/tools.rst +++ b/doc/user/tools.rst @@ -152,16 +152,20 @@ the available options. libinput record and libinput replay ------------------------------------------------------------------------------ +.. note:: For libinput versions 1.10 and older, use :ref:`evemu`. + The ``libinput record`` command records the **kernel** events from a specific device node. The recorded sequence can be replayed with the ``libinput replay`` command. This pair of tools is crucial to capturing bugs and reproducing them on a developer's machine. -.. note:: These tools are shipped with libinput, but the recorded events - are **kernel events** and independent of the libinput context. libinput - does not need to be running, it does not matter whether a user is - running X.Org or Wayland or even what version of libinput is currently - running. +.. graphviz:: libinput-record.gv + :align: center + +The recorded events are **kernel events** and independent of the +libinput context. libinput does not need to be running, it does +not matter whether a user is running X.Org or Wayland or even what +version of libinput is currently running. The use of the tools is straightforward, just run without arguments, piping the output into a file: :: @@ -196,12 +200,16 @@ the user select one. Supply the number (17 in this case for events to the file it is redirected to. More arguments are available, see the **libinput-record(1)** man page. +.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or + ``tmux``. + 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 alphanumeric key shows up as letter "a". -.. note:: When reproducing a bug that crashes libinput, run inside ``screen`` or - ``tmux``. +.. warning:: The longer the recording, the harder it is to identify the event + sequence triggering the bug. Please keep the event sequence as + short as possible. The recording can be replayed with the ``libinput replay`` command: :: diff --git a/doc/user/what-is-libinput.rst b/doc/user/what-is-libinput.rst index 85b4414e..20a18d28 100644 --- a/doc/user/what-is-libinput.rst +++ b/doc/user/what-is-libinput.rst @@ -14,26 +14,23 @@ what libinput is **not**. What libinput is ------------------------------------------------------------------------------ -libinput is an input stack to be used by those applications that need full -input device processing by commonly used input devices. That includes mice, -keyboards, touchpads, touchscreens and graphics tablets. libinput handles -device-specific quirks and provides an easy-to-use interface to receive +libinput is an input stack for applications that need full input device +processing by commonly used input devices. That includes mice, keyboards, +touchpads, touchscreens and graphics tablets. libinput handles +device-specific quirks and provides an easy-to-use API to receive events from devices. -libinput is designed to handle all input devices available on a system. It -is possible to limit the devices that employ libinput. For example, the use -of xf86-input-libinput depends on xorg.conf snippets for specific -devices. But libinput works best if it handles all input devices as this -allows for cross-device monitoring of events and smarter handling of -features that affect multiple devices. +libinput is designed to handle all input devices available on a system but +it is possible to limit which devices libinput has access to. +For example, the use of xf86-input-libinput depends on xorg.conf snippets +for specific devices. But libinput works best if it handles all input +devices as this allows for smarter handling of features that affect multiple +devices. -libinput restricts device-specific features to applicable devices only. -Devices with specific hardware properties may expose extra features, but -these features are not made available on other devices, even where it may be -possible to do so. One example for this are the top software buttons on the -touchpad in the Lenovo T440 and similar devices. While there may be -use-cases for providing top software buttons on other devices, libinput does -not do so. +libinput restricts device-specific features to those devices that require +those features. One example for this are the top software buttons on the +touchpad in the Lenovo T440. While there may be use-cases for providing top +software buttons on other devices, libinput does not do so. .. _what_libinput_is_not: @@ -49,10 +46,9 @@ not land in libinput master until the devices are commonly available. libinput is **not** a box of legos. It does not provide the pieces to assemble a selection of features. Many features can be disabled through -configuration options, but some features are hardcoded or hardcoded on some -devices. This usually matches the intended use of the device. There are -plenty of use-cases to provide out-of-the-ordinary features, but libinput is -not the place to support these. +configuration options, but some features are hardcoded and/or only available +on some devices. There are plenty of use-cases to provide niche features, +but libinput is not the place to support these. libinput is **not** a showcase for features. There are a lot of potential features that could be provided on input devices. But unless they have