fdo-mirrors/libinput
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libinput.git synced 2026-02-18 22:10:33 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc/user: some rewording and improvements

Browse source 
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Peter Hutterer 2018-07-31 16:03:49 +10:00
parent 22faa97f25
commit f955b2b73a
5 changed files with 75 additions and 51 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
doc/user/dot/libinput-record.gv Normal file
View file

@ -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
}

1
doc/user/meson.build
View file

@ -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',

45
doc/user/reporting-bugs.rst
View file

@ -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 <reporting_bugs_reproducer>` for the bug
- an :ref:`evemu recording <evemu>` 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 <https://www.freedesktop.org/wiki/Evemu/>`_ 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

22
doc/user/tools.rst
View file

@ -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: ::

38
doc/user/what-is-libinput.rst
View file

@ -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