/**
@page trackpoints Trackpoints and Pointing Sticks

This page provides an overview of trackpoint handling in libinput, also
refered to as Pointing Stick or Trackstick. The device itself is usually a
round plastic stick between the G, H and B keys with a set of buttons below
the space bar.

@image html button-scrolling.svg "A trackpoint"

libinput always treats the buttons below the space bar as the buttons that
belong to the trackpoint even on the few laptops where the buttons are not
physically wired to the trackpoint device anyway, see @ref t440_support.

Trackpoint devices have @ref button_scrolling enabled by default. This may
interfer with middle-button dragging, if middle-button dragging is required
by a user then button scrolling must be disabled.

@section trackpoint_range Motion range on trackpoints

It is difficult to associate motion on a trackpoint with a physical
reference. Unlike mice or touchpads where the motion can be
measured in mm, the trackpoint only responds to pressure. Without special
equipment it is impossible to measure identical pressure values across
multiple laptops.

The values provided by a trackpoint are motion deltas, usually corresponding
to the pressure applied to the trackstick. For example, pressure towards the
screen on a laptop provides negative y deltas. The reporting rate increases
as the pressure increases and once events are reported at the maximum rate,
the delta values increase. The figure below shows a rough illustration of
this concept. As the pressure
decreases, the delta decrease first, then the reporting rate until the
trackpoint is in a neutral state and no events are reported. Trackpoint data
is hart to generalize, see
<a href="https://who-t.blogspot.com/2018/06/observations-on-trackpoint-input-data.html">
Observations on trackpoint input data</a> for more details.

@image html trackpoint-delta-illustration.svg Illustration of the relationship between reporting rate and delta values on a trackpoint

The delta range itself can vary greatly between laptops, some devices send a
maximum delta value of 30, others can go beyond 100. However, the useful
delta range is a fraction of the maximum range. It is uncomfortable to exert
sufficient pressure to even get close to the maximum ranges.

@section trackpoint_multiplier The magic trackpoint multiplier

To accomodate for the wildly different input data on trackpoint, libinput
uses a multiplier that is applied to input deltas. Trackpoints that send
comparatively high deltas can be "slowed down", trackpoints that send low
deltas can be "sped up" to match the expected range. The actual acceleration
profile is applied to these pre-multiplied deltas.

Given a trackpoint delta (dx, dy), a multiplier M and a pointer acceleration
function f(dx, dy) → (dx', dy'), the algorithm is effectively:
@verbatim
f(M * dx, M * dy) → (dx', dy')
@endverbatim

The magic trackpoint multiplier **is not user visible configuration**. It is
part of the @ref device-quirks system and provided once per device.
User-specific preferences can be adjusted with the pointer acceleration speed
setting libinput_device_config_accel_set_speed().

@subsection trackpoint_multiplier_adjustment Adjusting the magic trackpoint multiplier

This section only applies if:
- the trackpoint default speed (speed setting 0) is unusably slow or
  unusably fast, **and**
- the lowest speed setting (-1) is still too fast **or** the highest speed
  setting is still too slow, **and**
- the @ref device-quirks for this device do not list a trackpoint multiplier
  (see @ref device-quirks-debugging)

If the only satisfactory speed settings are less than -0.75 or greater than
0.75, a multiplier *may* be required.

A specific multiplier will apply to **all users with the same laptop
model**, so proceed with caution. You must be capable/willing to adjust
device quirks, build libinput from source and restart the session frequently
to adjust the multiplier. If this does not apply, wait for someone else with
the same hardware to do this.

Finding the correct multiplier is difficult and requires some trial and
error. The default multiplier is always 1.0. A value between 0.0 and 1.0
slows the trackpoint down, a value above 1.0 speeds the trackpoint up.
Values below zero are invalid.

@note The multiplier is not a configuration to adjust to personal
preferences. The multiplier normalizes the input data into a range that can
then be configured with the speed setting.

To adjust the local multiplier, first @ref building_libinput
"build libinput from git master". It is not required to install libinput
from git. The below assumes that all @ref building_dependencies are already
installed.

@verbatim
$ cd path/to/libinput.git

# Use an approximate multiplier in the quirks file
$ cat > quirks/99-trackpont-override.quirks <<EOF
[Trackpoint Override]
MatchUdevType=pointingstick
AttrTrackpointMultiplier=1.0
EOF

# Use your trackpoint's event node. If the Attr does not show up
# then the quirk does not apply to your trackpoint.
$ ./builddir/libinput quirks list /dev/input/event18
AttrTrackpointMultiplier=1.0

# Now start a GUI program to debug the trackpoint speed.
# ESC closes the debug GUI
$ sudo ./builddir/libinput debug-gui
@endverbatim

Replace the multiplier with an approximate value and the event node with
your trackpoint's event node. Try to use trackpoint and verify the
multiplier is good enough. If not, adjust the `.quirks` file and re-run the
`libinput debug-gui`.  Note that the `libinput debug-gui` always feels
less responsive than libinput would behave in a normal install.

Once the trackpoint behaves correctly you are ready to test the system
libinput:

@verbatim
$ sudo cp quirks/99-trackpoint-override.quirks /etc/libinput/local-overrides.quirks
@endverbatim

Now verify the override is seen by the system libinput
@verbatim
$ libinput quirks list
AttrTrackpointMultiplier=1.0
@endverbatim

If the multiplier is listed, restart your Wayland session or X server. The
new multiplier is now applied to your trackpoint.

If the trackpoint behavior is acceptable, you are ready to submit this file
upstream. First, find add a more precise match for the device so it only
applies to the built-in trackpoint on your laptop model. Usually a
variation of the following is sufficient:

@verbatim
[Trackpoint Override]
MatchUdevType=pointingstick
MatchName=*TPPS/2 IBM TrackPoint*
MatchDMIModalias=dmi:*svnLENOVO:*:pvrThinkPadT440p*
AttrTrackpointMultiplier=1.0
@endverbatim

Look at your `/sys/class/dmi/id/modalias` file for the values to add. Verify
that `libinput quirks list` still shows the `AttrTrackpointMultiplier`. If
it does, then you should @ref reporting_bugs "report a bug" with the contents of
the file. Alternatively, file a merge request with the data added.


@section trackpoint_range_measure Measuring the trackpoint range

This section only applied to libinput version 1.9.x, 1.10.x, and 1.11.x and
has been removed. See @ref trackpoint_multiplier for versions 1.12.x and later.

If using libinput version 1.11.x or earlier, please see
<a href="https://wayland.freedesktop.org/libinput/doc/1.11.0/trackpoints.html#trackpoint_range_measure">
the 1.11.0 documentation</a>

*/